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