rowan

Rowan: Flujos de trabajo de modelado molecular y diseño de fármacos nativos de la nube

Resumen

Rowan es una plataforma de flujos de trabajo nativa de la nube para simulación molecular, química medicinal y diseño basado en estructuras. Su API de Python expone una interfaz unificada para el modelado de moléculas pequeñas, predicción de propiedades, acoplamiento, dinámica molecular y flujos de trabajo de IA estructural.

Usa Rowan cuando quieras ejecutar flujos de trabajo de química medicinal o diseño molecular de forma programática sin mantener infraestructura local de HPC, aprovisionamiento de GPU o un conjunto de herramientas de modelado separadas. Rowan maneja toda la infraestructura, gestión de resultados y escalado computacional.

Cuándo usar Rowan

Rowan es una buena opción para:

• Química cuántica, métodos semiempíricos o potenciales de redes neuronales
• Predicción de propiedades por lotes (pKa, descriptores, permeabilidad, solubilidad)
• Generación de conjuntos de conformeros y tautómeros
• Flujos de trabajo de acoplamiento (ligando único, series de análogos, refinamiento de poses)
• Co-plegado proteína-ligando y generación de MSA
• Pipelines químicos de múltiples pasos (ej., búsqueda de tautómeros → acoplamiento → análisis de poses)
• Campañas de química medicinal por lotes donde necesites infraestructura consistente y escalable

Rowan no es la opción adecuada para:

• E/S molecular simple (usa RDKit directamente)
• Química cuántica ab initio post-HF o cálculos relativistas

Inicio rápido

uv pip install rowan-python

import rowan
rowan.api_key = "tu_api_key_aqui"  # o establece la variable de entorno ROWAN_API_KEY

# Los descriptores requieren una molécula 3D, no una cadena SMILES simple.
mol = rowan.Molecule.from_smiles("CC(=O)Oc1ccccc1C(=O)O")
wf = rowan.submit_descriptors_workflow(mol, name="aspirina")
result = wf.result()

print(result.descriptors["MW"])       # 180.042 — masa exacta
print(result.descriptors["SLogP"])    # 1.31
print(result.descriptors["TopoPSA"])  # 63.6 — PSA topológico

Si eso imprime sin errores, estás configurado correctamente. Estos valores y ejemplos se verificaron con rowan-python 3.1.13.

Instalación

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

Gestión de usuarios y webhooks

Autenticación

Establece una clave API mediante variable de entorno (recomendado):

export ROWAN_API_KEY="tu_api_key_aqui"

O directamente en Python:

import rowan
rowan.api_key = "tu_api_key_aqui"

Verificar autenticación:

import rowan
user = rowan.whoami()  # Devuelve información del usuario si está autenticado
print(f"Usuario: {user.email}")
print(f"Créditos disponibles: {user.credits_available_string()}")

Formatos de entrada de moléculas

Rowan acepta moléculas en los siguientes formatos:

• SMILES (preferido): "CCO", "c1ccccc1O"
• Patrones SMARTS (para algunos flujos de trabajo): subconjunto de SMARTS para búsqueda de subestructuras
• InChI (si es compatible con tu versión de API): "InChI=1S/C2H6O/c1-2-3/h3H,2H2,1H3"

La API valida las moléculas de entrada y lanza ValueError para un SMILES no analizable o un tipo de entrada incompatible con el flujo de trabajo. Siempre usa SMILES canonicalizados para reproducibilidad.

Cadenas SMILES frente a objetos molécula

Los tipos de entrada aceptados varían según el flujo de trabajo en rowan-python 3.1.13. Solo estos flujos de trabajo comunes aceptan una cadena simple: pKa, búsqueda de conformeros, permeabilidad de membrana, ADMET, LogP, macropKa, solubilidad y MD de análisis de poses. La mayoría de los demás —incluyendo descriptores, búsqueda de tautómeros, acoplamiento, acoplamiento de análogos, BDE, RMN y Fukui— requieren rowan.Molecule.from_smiles(smiles) o un Mol/RWMol de RDKit. Un tipo incorrecto lanza ValueError antes del envío.

Consejo: Usa RDKit para validar SMILES antes del envío:

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

Patrón de uso principal

La mayoría de las tareas de Rowan siguen el mismo patrón de tres pasos:

1. Enviar un flujo de trabajo
2. Esperar la finalización (con streaming opcional)
3. Recuperar resultados tipados con propiedades de conveniencia

import rowan

# 1. Enviar — usa la función de flujo de trabajo específica (no la genérica submit_workflow)
workflow = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CC(=O)Oc1ccccc1C(=O)O"),
    name="descriptores aspirina",
)

# 2. y 3. Esperar y recuperar
result = workflow.result()  # Bloquea hasta que termine (por defecto: wait=True, poll_interval=5)
print(result.data)              # Diccionario sin procesar
print(result.descriptors["MW"]) # 180.042 masa exacta; no hay propiedad result.molecular_weight

Para flujos de trabajo de larga duración, usa streaming:

for partial in workflow.stream_result(poll_interval=5):
    print(f"Completado: {partial.complete}")  # bool, no un porcentaje
    print(partial.data)

result() vs. stream_result()

Patrón	Cuándo usarlo	Duración
result()	Puedes esperar el resultado completo	<5 min típico
stream_result()	Quieres retroalimentación de progreso o necesitas resultados parciales tempranos	>5 min, o uso interactivo

Directriz: Usa result() para descriptores, pKa. Usa stream_result() para búsqueda de conformeros, acoplamiento, co-plegado.

Trabajar con resultados

La API de Rowan incluye objetos de resultado de flujo de trabajo tipados con propiedades de conveniencia.

Usar propiedades tipadas y .data

Los resultados tienen dos patrones de acceso:

1. Propiedades de conveniencia (recomendado primero): result.descriptors, result.best_pose, result.scores. Las clases de resultado difieren: la búsqueda de conformeros usa los métodos get_energies() y get_conformers().
2. Respaldo sin procesar: result.data — diccionario sin procesar de la API

Ejemplo:

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

# Propiedad de conveniencia (devuelve todos los descriptores):
print(result.descriptors["MW"])       # masa exacta/monoisotópica
print(result.descriptors["SLogP"])
print(result.descriptors["TopoPSA"])  # PSA topológico habitual

# Respaldo de datos sin procesar:
print(result.data["descriptors"])

Nota: DescriptorsResult no tiene una propiedad molecular_weight. MW es la masa exacta/monoisotópica, no el peso molecular promedio. TPSA es un descriptor 3D de superficie cargada; usa TopoPSA para el área de superficie polar topológica habitual utilizada en reglas de similitud a fármacos.

Invalidación de caché

Algunas propiedades de resultado se cargan de forma diferida (ej., geometrías de conformeros, estructuras de proteínas). Para refrescar:

result.clear_cache()
nuevas_estructuras = result.get_conformers()  # Recuperado de nuevo para ConformerSearchResult

Proyectos, carpetas y organización

Para campañas no triviales, usa proyectos y carpetas para mantener el trabajo organizado.

Proyectos

import rowan

# Crear un proyecto
project = rowan.create_project(name="Optimización líder CDK2")
rowan.set_project("Optimización líder CDK2")

# Todos los flujos de trabajo posteriores van a este proyecto
wf = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CCO"), name="compuesto de prueba"
)

# retrieve_project toma un UUID; list_workflows limita el alcance con parent_uuid.
project = rowan.retrieve_project(project.uuid)
workflows = rowan.list_workflows(parent_uuid=project.uuid, size=50)

Carpetas

# Crear una estructura jerárquica de carpetas
folder = rowan.create_folder(name="acoplamiento/lote_1/cribado")

wf = rowan.submit_docking_workflow(
    # ... parámetros de acoplamiento ...
    folder=folder,
    name="compuesto_001",
)

# Listar flujos de trabajo en una carpeta
results = rowan.list_workflows(parent_uuid=folder.uuid)

Árboles de decisión de flujos de trabajo

pKa vs. MacropKa

Usa pKa microscópico cuando:

• Necesites el pKa de un solo grupo ionizable
• Estés interesado en transiciones ácido-base y termodinámica de protonación
• La molécula tenga uno o dos sitios ionizables
• La velocidad sea crítica (más rápido, menos créditos)

Usa macropKa cuando:

• Necesites un comportamiento dependiente del pH en un rango fisiológicamente relevante (ej., 0–14)
• Quieras poblaciones agregadas de carga y estado de protonación en función del pH
• La molécula tenga múltiples grupos ionizables con protonación acoplada
• Necesites propiedades posteriores como solubilidad acuosa a diferentes pH

Ejemplo de decisión:

Fenol (pKa ~10): Usa pKa microscópico
Amina (pKa ~9–10): Usa pKa microscópico
Fármaco multiionizable (N, O, grupo ácido): Usa macropKa
Evaluación ADME en pH GI: Usa macropKa

Búsqueda de conformeros vs. búsqueda de tautómeros

Usa búsqueda de conformeros cuando:

• Se conozca una sola forma tautomérica
• Necesites un conjunto 3D diverso para acoplamiento, DM o análisis SAR
• Los enlaces rotables dominen el espacio químico

Usa búsqueda de tautómeros cuando:

• El equilibrio tautomérico sea incierto (ej., heterociclos, sistemas ceto-enol)
• Necesites modelar todos los isómeros de protonación relevantes
• Los cálculos posteriores (acoplamiento, pKa) dependan de la forma tautomérica

Flujo de trabajo combinado:

# Paso 1: Encontrar el mejor tautómero
taut_wf = rowan.submit_tautomer_search_workflow(
    initial_molecule=rowan.Molecule.from_smiles("O=c1[nH]ccnc1"),
    name="tautómeros imidazol",
)
mejor_taut = taut_wf.result().best_tautomer

# Paso 2: Generar conformeros a partir del mejor tautómero
conf_wf = rowan.submit_conformer_search_workflow(
    initial_molecule=mejor_taut,
    name="conformeros imidazol",
)

Acoplamiento vs. acoplamiento de análogos vs. co-plegado

Flujo de trabajo	Cuándo usarlo	Entrada	Salida
Acoplamiento	Ligando único, bolsillo conocido	Proteína + SMILES + coordenadas de bolsillo	Pose, puntuación, dG
Acoplamiento de análogos	5–100+ compuestos relacionados	Proteína + lista de SMILES + ligando de referencia	Todas las poses, alineadas con referencia
Co-plegado proteína-ligando	Secuencia + ligando, sin estructura cristalina	Secuencia de proteína + SMILES	Complejo unido predicho por ML

Utilidades de proteínas

Subir proteínas

# Desde archivo PDB local
protein = rowan.upload_protein(
    name="dominio quinasa EGFR",
    file_path="egfr_kinase.pdb",
)

# Desde base de datos PDB
protein_from_pdb = rowan.create_protein_from_pdb_id(
    name="CDK2 (1M17)",
    code="1M17",
)

# Recuperar proteína subida previamente
protein = rowan.retrieve_protein("uuid-proteína")

# Listar todas las proteínas
mis_proteinas = rowan.list_proteins()

Guía de preparación de proteínas

• Formato de archivo: PDB, mmCIF (Rowan lo detecta automáticamente)
• Moléculas de agua: Rowan normalmente mantiene el agua relevante; elimina el agua a granel previamente si lo deseas
• Heteroátomos: Cofactores, iones y ligandos unidos generalmente se conservan; elimina heteroátomos no deseados antes de subir
• Proteínas multicadena: Totalmente compatibles
• Resolución: Funciona con estructuras de RMN, modelos de homología y crio-EM; la calidad importa para predicciones posteriores
• Validación: Rowan valida la sintaxis PDB; los archivos severamente malformados pueden ser rechazados

Catálogo de flujos de trabajo

Nueve categorías comunes de flujos de trabajo — descriptores, pKa microscópico, MacropKa, búsqueda de conformeros, búsqueda de tautómeros, acoplamiento, acoplamiento de análogos, generación de MSA y co-plegado proteína-ligando — cada una con código de envío y formas de resultado, más la lista completa de cada tipo de flujo de trabajo compatible (modelado central, diseño basado en estructura, química computacional avanzada, química de reacciones, propiedades avanzadas, energía libre de unión, y biología de secuencias y estructural) están en references/workflow_catalog.md.

Envío por lotes, webhooks y trabajo asíncrono

El patrón de enviar/poll/recuperar por lotes, el patrón de disparar y verificar sin bloqueo, configuración de webhooks, creación y rotación de secretos, verificación de carga útil y firma (con un manejador de FastAPI), y mejores prácticas de webhooks están en references/batch_and_webhooks.md.

Acceso, precios y créditos

Los límites del nivel gratuito, el consumo de créditos por flujo de trabajo y las estimaciones de costo típicas están en references/access_and_pricing.md.

Ejemplo práctico y solución de problemas

Una campaña completa de optimización líder — configuración de proyecto, tautómeros, pKa en una serie de análogos, recopilación de resultados y un seguimiento de acoplamiento — está en references/end_to_end_example.md.

Errores comunes con sus soluciones y consejos de depuración están en references/troubleshooting.md.

Patrones de uso recomendados

• Prefiere flujos de trabajo nativos de Rowan sobre el ensamblaje de bajo nivel cuando existan
• Usa proyectos y carpetas para cualquier campaña no trivial (>5 flujos de trabajo)
• Usa result() para bloquear hasta completar (por defecto: wait=True, poll_interval=5)
• Usa primero las propiedades de resultado tipadas, recurre a .data para campos no mapeados
• Usa envío por lotes para bibliotecas de compuestos o series de análogos
• Encadena flujos de trabajo para campañas químicas de múltiples pasos:
  • pKa → macropKa → permeabilidad (evaluación ADME)
  • búsqueda de tautómeros → acoplamiento → MD de análisis de poses (refinamiento de poses)
  • generación de MSA → co-plegado proteína-ligando (predicción de estructura con IA)
• Usa webhooks para campañas de larga duración (>50 flujos de trabajo) o pipelines asíncronos
• Usa streaming para retroalimentación interactiva en búsquedas grandes de conformeros/acoplamiento

Resumen

Usa Rowan cuando tu flujo de trabajo requiera ejecución en la nube para tareas de diseño molecular, especialmente cuando quieras una API unificada y un manejo consistente de resultados en modelado de moléculas pequeñas, proteínas, acoplamiento, predicción ADME y generación de estructuras con ML.

Rowan es una plataforma de flujos de trabajo de diseño molecular, no solo un motor de química remoto. Maneja el escalado de infraestructura, la persistencia de resultados y la orquestación de pipelines de múltiples pasos para que puedas centrarte en la ciencia.