rowan

Rowan: Workflows de Modelagem Molecular e Design de Fármacos Nativos da Nuvem

Visão Geral

Rowan é uma plataforma de workflow nativa da nuvem para simulação molecular, química medicinal e design baseado em estrutura. Sua API Python expõe uma interface unificada para modelagem de pequenas moléculas, previsão de propriedades, docking, dinâmica molecular e workflows de estrutura com IA.

Use Rowan quando quiser executar workflows de química medicinal ou design molecular programaticamente sem manter infraestrutura HPC local, provisionamento de GPU ou uma coleção de ferramentas de modelagem separadas. Rowan lida com toda infraestrutura, gerenciamento de resultados e escalonamento de computação.

Quando usar Rowan

Rowan é uma boa opção para:

• Química quântica, métodos semiempíricos ou potenciais de redes neurais
• Previsão de propriedades em lote (pKa, descritores, permeabilidade, solubilidade)
• Geração de conjuntos de conformeros e tautômeros
• Workflows de docking (ligante único, série análoga, refinamento de pose)
• Co-dobramento proteína-ligante e geração de MSA
• Pipelines químicos de múltiplas etapas (ex.: busca de tautômeros → docking → análise de pose)
• Campanhas de química medicinal em lote onde você precisa de infraestrutura consistente e escalável

Rowan não é adequado para:

• E/S molecular simples (use RDKit diretamente)
• Química quântica ab initio pós-HF ou cálculos relativísticos

Início Rápido

uv pip install rowan-python

import rowan
rowan.api_key = "your_api_key_here"  # ou defina a variável de ambiente ROWAN_API_KEY

# Descritores exigem uma Molécula 3D, não uma string SMILES simples.
mol = rowan.Molecule.from_smiles("CC(=O)Oc1ccccc1C(=O)O")
wf = rowan.submit_descriptors_workflow(mol, name="aspirin")
result = wf.result()

print(result.descriptors["MW"])       # 180.042 — massa exata
print(result.descriptors["SLogP"])    # 1.31
print(result.descriptors["TopoPSA"])  # 63.6 — PSA topológica

Se isso imprimir sem erros, você está configurado corretamente. Esses valores e exemplos foram verificados em relação ao rowan-python 3.1.13.

Instalação

uv pip install rowan-python
# ou: uv pip install rowan-python

Gerenciamento de Usuário e Webhooks

Autenticação

Defina uma chave de API via variável de ambiente (recomendado):

export ROWAN_API_KEY="your_api_key_here"

Ou defina diretamente em Python:

import rowan
rowan.api_key = "your_api_key_here"

Verifique a autenticação:

import rowan
user = rowan.whoami()  # Retorna informações do usuário se autenticado
print(f"User: {user.email}")
print(f"Credits available: {user.credits_available_string()}")

Formatos de Entrada de Moléculas

Rowan aceita moléculas nos seguintes formatos:

• SMILES (preferido): "CCO", "c1ccccc1O"
• Padrões SMARTS (para alguns workflows): subconjunto de SMARTS para correspondência de subestrutura
• InChI (se suportado na sua versão da API): "InChI=1S/C2H6O/c1-2-3/h3H,2H2,1H3"

A API valida entradas de moléculas e levanta ValueError para um SMILES não analisável ou um tipo de entrada incompatível com o workflow. Sempre use SMILES canônicos para reprodutibilidade.

Strings SMILES versus objetos Molécula

Os tipos de entrada aceitos variam por workflow no rowan-python 3.1.13. Apenas esses workflows comuns aceitam uma string simples: pKa, busca de conformeros, permeabilidade de membrana, ADMET, LogP, macropKa, solubilidade e MD de análise de pose. A maioria dos outros — incluindo descritores, busca de tautômeros, docking, docking análogo, BDE, NMR e Fukui — requerem rowan.Molecule.from_smiles(smiles) ou um RDKit Mol/RWMol. Um tipo errado levanta ValueError antes da submissão.

Dica: Use RDKit para validar SMILES antes da submissão:

from rdkit import Chem
smiles = "CCO"
mol = Chem.MolFromSmiles(smiles)
if mol is None:
    raise ValueError(f"Invalid SMILES: {smiles}")

Padrão de Uso Principal

A maioria das tarefas do Rowan segue o mesmo padrão de três etapas:

1. Submeter um workflow
2. Aguardar a conclusão (com streaming opcional)
3. Recuperar resultados tipados com propriedades de conveniência

import rowan

# 1. Submeter — use a função de workflow específica (não a submit_workflow genérica)
workflow = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CC(=O)Oc1ccccc1C(=O)O"),
    name="aspirin descriptors",
)

# 2. & 3. Aguardar e recuperar
result = workflow.result()  # Bloqueia até terminar (padrão: wait=True, poll_interval=5)
print(result.data)              # Dicionário bruto
print(result.descriptors["MW"]) # 180.042 massa exata; sem propriedade result.molecular_weight

Para workflows de longa duração, use streaming:

for partial in workflow.stream_result(poll_interval=5):
    print(f"Complete: {partial.complete}")  # bool, não uma porcentagem
    print(partial.data)

result() vs. stream_result()

Padrão	Quando Usar	Duração
result()	Você pode esperar pelo resultado completo	<5 min típico
stream_result()	Você quer feedback de progresso ou precisa de resultados parciais antecipados	>5 min, ou uso interativo

Diretriz: Use result() para descritores, pKa. Use stream_result() para busca de conformeros, docking, co-dobramento.

Trabalhando com Resultados

A API do Rowan inclui objetos de resultado de workflow tipados com propriedades de conveniência.

Usando propriedades tipadas e .data

Os resultados têm dois padrões de acesso:

1. Propriedades de conveniência (recomendado primeiro): result.descriptors, result.best_pose, result.scores. As classes de resultado diferem: busca de conformeros usa métodos get_energies() e get_conformers().
2. Fallback bruto: result.data — dicionário bruto da API

Exemplo:

result = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CCO"),
    name="ethanol",
).result()

# Propriedade de conveniência (retorna todos os descritores):
print(result.descriptors["MW"])       # massa exata/monoisotópica
print(result.descriptors["SLogP"])
print(result.descriptors["TopoPSA"])  # PSA topológica usual

# Fallback de dados brutos:
print(result.data["descriptors"])

Nota: DescriptorsResult não tem uma propriedade molecular_weight. MW é massa exata/monoisotópica, não peso molecular médio. TPSA é um descritor de superfície carregada 3D; use TopoPSA para a área de superfície polar topológica usual usada em regras de semelhança a fármacos.

Invalidação de cache

Algumas propriedades de resultado são carregadas preguiçosamente (ex.: geometrias de conformeros, estruturas de proteínas). Para atualizar:

result.clear_cache()
new_structures = result.get_conformers()  # Recuperado novamente para ConformerSearchResult

Projetos, Pastas e Organização

Para campanhas não triviais, use projetos e pastas para manter o trabalho organizado.

Projetos

import rowan

# Criar um projeto
project = rowan.create_project(name="CDK2 lead optimization")
rowan.set_project("CDK2 lead optimization")

# Todos os workflows subsequentes vão para este projeto
wf = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CCO"), name="test compound"
)

# retrieve_project recebe um UUID; list_workflows escopa com parent_uuid.
project = rowan.retrieve_project(project.uuid)
workflows = rowan.list_workflows(parent_uuid=project.uuid, size=50)

Pastas

# Criar uma estrutura de pastas hierárquica
folder = rowan.create_folder(name="docking/batch_1/screening")

wf = rowan.submit_docking_workflow(
    # ... parâmetros de docking ...
    folder=folder,
    name="compound_001",
)

# Listar workflows em uma pasta
results = rowan.list_workflows(parent_uuid=folder.uuid)

Árvores de Decisão de Workflow

pKa vs. MacropKa

Use pKa microscópico quando:

• Você precisa do pKa de um único grupo ionizável
• Você está interessado em transições ácido-base e termodinâmica de protonação
• A molécula tem um ou dois sítios ionizáveis
• A velocidade é crítica (mais rápido, menos créditos)

Use macropKa quando:

• Você precisa de comportamento dependente de pH em uma faixa fisiologicamente relevante (ex.: 0–14)
• Você deseja populações agregadas de carga e estado de protonação em diferentes pH
• A molécula tem múltiplos grupos ionizáveis com protonação acoplada
• Você precisa de propriedades downstream como solubilidade aquosa em diferentes pH

Exemplo de decisão:

Fenol (pKa ~10): Use pKa microscópico
Amina (pKa ~9–10): Use pKa microscópico
Fármaco multi-ionizável (N, O, grupo ácido): Use macropKa
Avaliação ADME em pH GI: Use macropKa

Busca de conformeros vs. busca de tautômeros

Use busca de conformeros quando:

• Uma única forma tautômera é conhecida
• Você precisa de um conjunto 3D diverso para docking, MD ou análise SAR
• Ligações rotacionáveis dominam o espaço químico

Use busca de tautômeros quando:

• O equilíbrio tautômero é incerto (ex.: heterociclos, sistemas ceto-enol)
• Você precisa modelar todos os isômeros de protonação relevantes
• Cálculos downstream (docking, pKa) dependem da forma tautômera

Workflow combinado:

# Passo 1: Encontrar o melhor tautômero
taut_wf = rowan.submit_tautomer_search_workflow(
    initial_molecule=rowan.Molecule.from_smiles("O=c1[nH]ccnc1"),
    name="imidazole tautomers",
)
best_taut = taut_wf.result().best_tautomer

# Passo 2: Gerar conformeros a partir do melhor tautômero
conf_wf = rowan.submit_conformer_search_workflow(
    initial_molecule=best_taut,
    name="imidazole conformers",
)

Docking vs. docking análogo vs. co-dobramento

Workflow	Quando Usar	Entrada	Saída
Docking	Ligante único, bolsa conhecida	Proteína + SMILES + coordenadas da bolsa	Pose, pontuação, dG
Docking análogo	5–100+ compostos relacionados	Proteína + lista de SMILES + ligante de referência	Todas as poses, alinhadas à referência
Co-dobramento proteína-ligante	Sequência + ligante, sem estrutura cristalina	Sequência da proteína + SMILES	Complexo ligado previsto por ML

Utilitários de Proteínas

Upload de proteínas

# A partir de arquivo PDB local
protein = rowan.upload_protein(
    name="egfr_kinase_domain",
    file_path="egfr_kinase.pdb",
)

# A partir do banco de dados PDB
protein_from_pdb = rowan.create_protein_from_pdb_id(
    name="CDK2 (1M17)",
    code="1M17",
)

# Recuperar proteína enviada anteriormente
protein = rowan.retrieve_protein("protein-uuid")

# Listar todas as proteínas
my_proteins = rowan.list_proteins()

Orientação para preparação de proteínas

• Formato de arquivo: PDB, mmCIF (Rowan detecta automaticamente)
• Moléculas de água: Rowan geralmente mantém água relevante; remova água em massa antes se desejado
• Heteroátomos: Cofatores, íons e ligantes ligados são geralmente preservados; remova heteroátomos indesejados antes do upload
• Proteínas de múltiplas cadeias: Totalmente suportado
• Resolução: Funciona com estruturas NMR, modelos de homologia e cryo-EM; a qualidade é importante para previsões downstream
• Validação: Rowan valida sintaxe PDB; arquivos severamente malformados podem ser rejeitados

Catálogo de Workflows

Nove categorias comuns de workflow — descritores, pKa microscópico, MacropKa, busca de conformeros, busca de tautômeros, docking, docking análogo, geração de MSA e co-dobramento proteína-ligante — cada uma com código de submissão e formatos de resultado, mais a lista completa de cada tipo de workflow suportado (modelagem principal, design baseado em estrutura, química computacional avançada, química de reação, propriedades avançadas, energia livre de ligação e biologia sequencial e estrutural) estão em references/workflow_catalog.md.

Submissão em Lote, Webhooks e Trabalho Assíncrono

Submissão/poll/recuperação em lote, o padrão de disparar e verificar não bloqueante, configuração de webhook, criação e rotação de segredos, verificação de payload e assinatura (com um manipulador FastAPI) e melhores práticas de webhook estão em references/batch_and_webhooks.md.

Acesso, Preços e Créditos

Limites do nível gratuito, consumo de crédito por workflow e estimativas de custo típicas estão em references/access_and_pricing.md.

Exemplo Prático e Solução de Problemas

Uma campanha completa de otimização de lead — configuração de projeto, tautômeros, pKa em uma série análoga, coleta de resultados e acompanhamento de docking — está em references/end_to_end_example.md.

Erros comuns com suas correções e dicas de depuração estão em references/troubleshooting.md.

Padrões de Uso Recomendados

• Prefira workflows nativos do Rowan em vez de montagem de baixo nível quando existirem
• Use projetos e pastas para qualquer campanha não trivial (>5 workflows)
• Use result() para bloquear até a conclusão (padrão: wait=True, poll_interval=5)
• Use propriedades de resultado tipadas primeiro, recorra a .data para campos não mapeados
• Use submissão em lote para bibliotecas de compostos ou séries análogas
• Encadeie workflows para campanhas químicas de múltiplas etapas:
  • pKa → macropKa → permeabilidade (avaliação ADME)
  • busca de tautômeros → docking → MD de análise de pose (refinamento de pose)
  • geração de MSA → co-dobramento proteína-ligante (previsão de estrutura com IA)
• Use webhooks para campanhas de longa duração (>50 workflows) ou pipelines assíncronos
• Use streaming para feedback interativo em grandes buscas de conformeros/docking

Resumo

Use Rowan quando seu workflow exigir execução em nuvem para tarefas de design molecular, especialmente quando você quiser uma API unificada e tratamento consistente de resultados em modelagem de pequenas moléculas, proteínas, docking, previsão ADME e geração de estrutura com ML.

Rowan é uma plataforma de workflow de design molecular, não apenas um motor de química remoto. Ela lida com escalonamento de infraestrutura, persistência de resultados e orquestração de pipelines de múltiplas etapas para que você possa se concentrar na ciência.