rowan

# Rowan: Cloud-Based Quantum Chemistry Platform ## Overview Rowan is a cloud-based computational chemistry platform that provides programmatic access to quantum chemistry workflows through a Python API. It enables automation of complex molecular simulations without requiring local computational resources or expertise in multiple quantum chemistry packages. **Key Capabilities:** - Molecular property prediction (pKa, redox potential, solubility, ADMET-Tox) - Geometry optimization and conformer searching - Protein-ligand docking with AutoDock Vina - AI-powered protein cofolding with Chai-1 and Boltz models - Access to DFT, semiempirical, and neural network potential methods - Cloud compute with automatic resource allocation **Why Rowan:** - No local compute cluster required - Unified API for dozens of computational methods - Results viewable in web interface at labs.rowansci.com - Automatic resource scaling ## Installation and Authentication ### Installation ```bash uv pip install rowan-python ``` ### Authentication Generate an API key at [labs.rowansci.com/account/api-keys](https://labs.rowansci.com/account/api-keys). **Option 1: Direct assignment** ```python import rowan rowan.api_key = "your_api_key_here" ``` **Option 2: Environment variable (recommended)** ```bash export ROWAN_API_KEY="your_api_key_here" ``` The API key is automatically read from `ROWAN_API_KEY` on module import. ### Verify Setup ```python import rowan # Check authentication user = rowan.whoami() print(f"Logged in as: {user.username}") print(f"Credits available: {user.credits}") ``` ## Core Workflows ### 1. pKa Prediction Calculate the acid dissociation constant for molecules: ```python import rowan import stjames # Create molecule from SMILES mol = stjames.Molecule.from_smiles("c1ccccc1O") # Phenol # Submit pKa workflow workflow = rowan.submit_pka_workflow( initial_molecule=mol, name="phenol pKa calculation" ) # Wait for completion workflow.wait_for_result() workflow.fetch_latest(in_place=True) # Access results print(f"Strongest acid pKa: {workflow.data['strongest_acid']}") # ~10.17 ``` ### 2. Conformer Search Generate and optimize molecular conformers: ```python import rowan import stjames mol = stjames.Molecule.from_smiles("CCCC") # Butane workflow = rowan.submit_conformer_search_workflow( initial_molecule=mol, name="butane conformer search" ) workflow.wait_for_result() workflow.fetch_latest(in_place=True) # Access conformer ensemble conformers = workflow.data['conformers'] for i, conf in enumerate(conformers): print(f"Conformer {i}: Energy = {conf['energy']:.4f} Hartree") ``` ### 3. Geometry Optimization Optimize molecular geometry to minimum energy structure: ```python import rowan import stjames mol = stjames.Molecule.from_smiles("CC(=O)O") # Acetic acid workflow = rowan.submit_basic_calculation_workflow( initial_molecule=mol, name="acetic acid optimization", workflow_type="optimization" ) workflow.wait_for_result() workflow.fetch_latest(in_place=True) # Get optimized structure optimized_mol = workflow.data['final_molecule'] print(f"Final energy: {optimized_mol.energy} Hartree") ``` ### 4. Protein-Ligand Docking Dock small molecules to protein targets: ```python import rowan # First, upload or create protein protein = rowan.create_protein_from_pdb_id( name="EGFR kinase", code="1M17" ) # Define binding pocket (from crystal structure or manual) pocket = { "center": [10.0, 20.0, 30.0], "size": [20.0, 20.0, 20.0] } # Submit docking workflow = rowan.submit_docking_workflow( protein=protein.uuid, pocket=pocket, initial_molecule=stjames.Molecule.from_smiles("Cc1ccc(NC(=O)c2ccc(CN3CCN(C)CC3)cc2)cc1"), name="EGFR docking" ) workflow.wait_for_result() workflow.fetch_latest(in_place=True) # Access docking results docking_score = workflow.data['docking_score'] print(f"Docking score: {docking_score}") ``` ### 5. Protein Cofolding (AI Structure Prediction) Predict protein-ligand complex structures using AI models: ```python import rowan # Protein sequence protein_seq = "MENFQKVEKIGEGTYGVVYKARNKLTGEVVALKKIRLDTETEGVPSTAIREISLLKELNHPNIVKLLDVIHTENKLYLVFEFLHQDLKKFMDASALTGIPLPLIKSYLFQLLQGLAFCHSHRVLHRDLKPQNLLINTEGAIKLADFGLARAFGVPVRTYTHEVVTLWYRAPEILLGCKYYSTAVDIWSLGCIFAEMVTRRALFPGDSEIDQLFRIFRTLGTPDEVVWPGVTSMPDYKPSFPKWARQDFSKVVPPLDEDGRSLLSQMLHYDPNKRISAKAALAHPFFQDVTKPVPHLRL" # Ligand SMILES ligand = "CCC(C)CN=C1NCC2(CCCOC2)CN1" # Submit cofolding with Chai-1 workflow = rowan.submit_protein_cofolding_workflow( initial_protein_sequences=[protein_seq], initial_smiles_list=[ligand], name="kinase-ligand cofolding", model="chai_1r" # or "boltz_1x", "boltz_2" ) workflow.wait_for_result() workflow.fetch_latest(in_place=True) # Access structure predictions print(f"Predicted TM Score: {workflow.data['ptm_score']}") print(f"Interface pTM: {workflow.data['interface_ptm']}") ``` ## RDKit-Native API For users working with RDKit molecules, Rowan provides a simplified interface: ```python import rowan from rdkit import Chem # Create RDKit molecule mol = Chem.MolFromSmiles("c1ccccc1O") # Compute pKa directly pka_result = rowan.run_pka(mol) print(f"pKa: {pka_result.strongest_acid}") # Batch processing mols = [Chem.MolFromSmiles(smi) for smi in ["CCO", "CC(=O)O", "c1ccccc1O"]] results = rowan.batch_pka(mols) for mol, result in zip(mols, results): print(f"{Chem.MolToSmiles(mol)}: pKa = {result.strongest_acid}") ``` **Available RDKit-native functions:** - `run_pka`, `batch_pka` - pKa calculations - `run_tautomers`, `batch_tautomers` - Tautomer enumeration - `run_conformers`, `batch_conformers` - Conformer generation - `run_energy`, `batch_energy` - Single-point energies - `run_optimization`, `batch_optimization` - Geometry optimization See `references/rdkit_native.md` for complete documentation. ## Workflow Management ### List and Query Workflows ```python # List recent workflows workflows = rowan.list_workflows(size=10) for wf in workflows: print(f"{wf.name}: {wf.status}") # Filter by status pending = rowan.list_workflows(status="running") # Retrieve specific workflow workflow = rowan.retrieve_workflow("workflow-uuid") ``` ### Batch Operations ```python # Submit multiple workflows workflows = rowan.batch_submit_workflow( molecules=[mol1, mol2, mol3], workflow_type="pka", workflow_data={} ) # Poll status of multiple workflows statuses = rowan.batch_poll_status([wf.uuid for wf in workflows]) ``` ### Folder Organization ```python # Create folder for project folder = rowan.create_folder(name="Drug Discovery Project") # Submit workflow to folder workflow = rowan.submit_pka_workflow( initial_molecule=mol, name="compound pKa", folder_uuid=folder.uuid ) # List workflows in folder folder_workflows = rowan.list_workflows(folder_uuid=folder.uuid) ``` ## Computational Methods Rowan supports multiple levels of theory: **Neural Network Potentials:** - AIMNet2 (ωB97M-D3) - Fast and accurate - Egret - Rowan's proprietary model **Semiempirical:** - GFN1-xTB, GFN2-xTB - Fast for large molecules **DFT:** - B3LYP, PBE, ωB97X variants - Multiple basis sets available Methods are automatically selected based on workflow type, or can be specified explicitly in workflow parameters. ## Reference Documentation For detailed API documentation, consult these reference files: - **`references/api_reference.md`**: Complete API documentation - Workflow class, submission functions, retrieval methods - **`references/workflow_types.md`**: All 30+ workflow types with parameters - pKa, docking, cofolding, etc. - **`references/rdkit_native.md`**: RDKit-native API functions for seamless cheminformatics integration - **`references/molecule_handling.md`**: stjames.Molecule class - creating molecules from SMILES, XYZ, RDKit - **`references/proteins_and_organization.md`**: Protein upload, folder management, project organization - **`references/results_interpretation.md`**: Understanding workflow outputs, confidence scores, validation ## Common Patterns ### Pattern 1: Property Prediction Pipeline ```python import rowan import stjames smiles_list = ["CCO", "c1ccccc1O", "CC(=O)O"] # Submit all pKa calculations workflows = [] for smi in smiles_list: mol = stjames.Molecule.from_smiles(smi) wf = rowan.submit_pka_workflow( initial_molecule=mol, name=f"pKa: {smi}" ) workflows.append(wf) # Wait for all to complete for wf in workflows: wf.wait_for_result() wf.fetch_latest(in_place=True) print(f"{wf.name}: pKa = {wf.data['strongest_acid']}") ``` ### Pattern 2: Virtual Screening ```python import rowan # Upload protein once protein = rowan.upload_protein("target.pdb", name="Drug Target") protein.sanitize() # Clean structure # Define pocket pocket = {"center": [x, y, z], "size": [20, 20, 20]} # Screen compound library for smiles in compound_library: mol = stjames.Molecule.from_smiles(smiles) workflow = rowan.submit_docking_workflow( protein=protein.uuid, pocket=pocket, initial_molecule=mol, name=f"Dock: {smiles[:20]}" ) ``` ### Pattern 3: Conformer-Based Analysis ```python import rowan import stjames mol = stjames.Molecule.from_smiles("complex_molecule_smiles") # Generate conformers conf_wf = rowan.submit_conformer_search_workflow( initial_molecule=mol, name="conformer search" ) conf_wf.wait_for_result() conf_wf.fetch_latest(in_place=True) # Analyze lowest energy conformers conformers = sorted(conf_wf.data['conformers'], key=lambda x: x['energy']) print(f"Found {len(conformers)} unique conformers") print(f"Energy range: {conformers[0]['energy']:.4f} to {conformers[-1]['energy']:.4f} Hartree") ``` ## Best Practices 1. **Set API key via environment variable** for security and convenience 2. **Use folders** to organize related workflows 3. **Check workflow status** before accessing data 4. **Use batch functions** for multiple similar calculations 5. **Handle errors gracefully** - workflows can fail due to invalid molecules 6. **Monitor credits** - use `rowan.whoami().credits` to check balance ## Error Handling ```python import rowan try: workflow = rowan.submit_pka_workflow( initial_molecule=mol, name="calculation" ) workflow.wait_for_result(timeout=3600) # 1 hour timeout if workflow.status == "completed": workflow.fetch_latest(in_place=True) print(workflow.data) elif workflow.status == "failed": print(f"Workflow failed: {workflow.error_message}") except rowan.RowanAPIError as e: print(f"API error: {e}") except TimeoutError: print("Workflow timed out") ``` ## Additional Resources - **Web Interface**: https://labs.rowansci.com - **Documentation**: https://docs.rowansci.com - **Python API Docs**: https://docs.rowansci.com/api/python/v2/ - **Tutorials**: https://docs.rowansci.com/tutorials