claude-scientific-skills/scientific-skills/rowan/references/api_reference.md

Rowan API Reference

Table of Contents

1. Workflow Class
2. Workflow Submission Functions
3. Workflow Retrieval Functions
4. Batch Operations
5. Utility Functions

---

Workflow Class

The Workflow class represents a submitted computational job.

Attributes

Attribute	Type	Description
uuid	str	Unique identifier
name	str	User-assigned name
status	str	Current status: "pending", "running", "completed", "failed"
created_at	datetime	Submission timestamp
completed_at	datetime	Completion timestamp (None if not finished)
credits_charged	float	Credits consumed
data	dict	Workflow results (lazy-loaded)
workflow_type	str	Type of calculation
folder_uuid	str	Parent folder UUID

Note: Workflow data is not loaded by default to avoid unnecessary downloads. Call fetch_latest() to load results.

Methods

Status Management

# Get current status
status = workflow.get_status()

# Check if finished
if workflow.is_finished():
    print("Done!")

# Block until completion
workflow.wait_for_result(timeout=3600)  # Optional timeout in seconds

# Refresh from API
workflow.fetch_latest(in_place=True)

Data Operations

# Update metadata
workflow.update(
    name="New name",
    notes="Additional notes",
    starred=True
)

# Delete workflow
workflow.delete()

# Delete only results data (keep metadata)
workflow.delete_data()

# Download trajectory files (for MD workflows)
workflow.download_dcd_files(output_dir="trajectories/")

# Download SDF file
workflow.download_sdf_file(output_path="molecule.sdf")

Execution Control

# Stop a running workflow
workflow.stop()

---

Workflow Submission Functions

Generic Submission

rowan.submit_workflow(
    name: str,                      # Workflow name
    initial_molecule: Molecule,     # stjames.Molecule object
    workflow_type: str,             # e.g., "pka", "optimization", "conformer_search"
    workflow_data: dict = {},       # Workflow-specific parameters
    folder_uuid: str = None,        # Optional folder
    max_credits: float = None       # Credit limit
) -> Workflow

Specialized Submission Functions

All functions return a Workflow object.

Property Prediction

# pKa calculation
rowan.submit_pka_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Redox potential
rowan.submit_redox_potential_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Solubility prediction
rowan.submit_solubility_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Fukui indices (reactivity)
rowan.submit_fukui_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Bond dissociation energy
rowan.submit_bde_workflow(
    initial_molecule: Molecule,
    bond_indices: tuple,  # (atom1_idx, atom2_idx)
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

Molecular Modeling

# Geometry optimization
rowan.submit_basic_calculation_workflow(
    initial_molecule: Molecule,
    workflow_type: str = "optimization",  # or "single_point", "frequency"
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Conformer search
rowan.submit_conformer_search_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Tautomer search
rowan.submit_tautomer_search_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Dihedral scan
rowan.submit_dihedral_scan_workflow(
    initial_molecule: Molecule,
    dihedral_indices: tuple,  # (a1, a2, a3, a4)
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Transition state search
rowan.submit_ts_search_workflow(
    initial_molecule: Molecule,  # Starting guess
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

Protein-Ligand Workflows

# Docking
rowan.submit_docking_workflow(
    protein: str,                   # Protein UUID
    pocket: dict,                   # {"center": [x,y,z], "size": [dx,dy,dz]}
    initial_molecule: Molecule,
    executable: str = "vina",       # "vina" or "qvina2"
    scoring_function: str = "vinardo",
    exhaustiveness: int = 8,
    do_csearch: bool = True,
    do_optimization: bool = True,
    do_pose_refinement: bool = True,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Batch docking
rowan.submit_batch_docking_workflow(
    protein: str,
    pocket: dict,
    smiles_list: list,              # List of SMILES strings
    executable: str = "qvina2",
    scoring_function: str = "vina",
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Protein cofolding
rowan.submit_protein_cofolding_workflow(
    initial_protein_sequences: list,  # List of amino acid sequences
    initial_smiles_list: list = None, # Optional ligand SMILES
    ligand_binding_affinity_index: int = None,
    use_msa_server: bool = False,
    use_potentials: bool = True,
    compute_strain: bool = False,
    do_pose_refinement: bool = False,
    model: str = "boltz_2",         # "boltz_1x", "boltz_2", "chai_1r"
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

Spectroscopy & Analysis

# NMR prediction
rowan.submit_nmr_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Ion mobility (collision cross-section)
rowan.submit_ion_mobility_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

# Molecular descriptors
rowan.submit_descriptors_workflow(
    initial_molecule: Molecule,
    name: str = None,
    folder_uuid: str = None,
    max_credits: float = None
)

---

Workflow Retrieval Functions

# Retrieve single workflow by UUID
workflow = rowan.retrieve_workflow(uuid: str) -> Workflow

# Retrieve multiple workflows
workflows = rowan.retrieve_workflows(uuids: list) -> list[Workflow]

# List workflows with filtering
workflows = rowan.list_workflows(
    name: str = None,           # Filter by name (partial match)
    status: str = None,         # "pending", "running", "completed", "failed"
    workflow_type: str = None,  # e.g., "pka", "docking"
    starred: bool = None,       # Filter by starred status
    folder_uuid: str = None,    # Filter by folder
    page: int = 1,              # Pagination
    size: int = 20              # Results per page
) -> list[Workflow]

---

Batch Operations

# Submit multiple workflows at once
workflows = rowan.batch_submit_workflow(
    molecules: list,            # List of stjames.Molecule objects
    workflow_type: str,         # Workflow type for all
    workflow_data: dict = {},
    folder_uuid: str = None,
    max_credits: float = None
) -> list[Workflow]

# Poll status of multiple workflows
statuses = rowan.batch_poll_status(
    uuids: list                 # List of workflow UUIDs
) -> dict                       # {uuid: status}

---

Utility Functions

# Get current user info
user = rowan.whoami() -> User
# user.username, user.email, user.credits, user.weekly_credits

# Convert SMILES to stjames.Molecule
mol = rowan.smiles_to_stjames(smiles: str) -> Molecule

# Get API key from environment
api_key = rowan.get_api_key() -> str

# Low-level API client
client = rowan.api_client() -> httpx.Client

# Molecule name lookup
smiles = rowan.molecule_lookup(name: str) -> str
# e.g., rowan.molecule_lookup("aspirin") -> "CC(=O)Oc1ccccc1C(=O)O"

---

User Class

Returned by rowan.whoami().

Attributes

Attribute	Type	Description
username	str	Username
email	str	Email address
firstname	str	First name
lastname	str	Last name
credits	float	Available credits
weekly_credits	float	Weekly credit allocation
organization	dict	Organization details
individual_subscription	dict	Subscription information

---

Error Handling

import rowan

try:
    workflow = rowan.submit_pka_workflow(mol, name="test")
except rowan.RowanAPIError as e:
    print(f"API error: {e}")
except rowan.AuthenticationError as e:
    print(f"Authentication failed: {e}")
except rowan.RateLimitError as e:
    print(f"Rate limited, retry after: {e.retry_after}")

---

Common Patterns

Waiting for Multiple Workflows

import rowan
import time

workflows = [rowan.submit_pka_workflow(mol) for mol in molecules]

# Poll until all complete
while True:
    statuses = rowan.batch_poll_status([wf.uuid for wf in workflows])
    if all(s in ["completed", "failed"] for s in statuses.values()):
        break
    time.sleep(10)

# Fetch results
for wf in workflows:
    wf.fetch_latest(in_place=True)
    if wf.status == "completed":
        print(wf.data)

Organizing Workflows in Folders

import rowan

# Create project structure
project = rowan.create_project("Drug Discovery")
lead_folder = rowan.create_folder("Lead Compounds", project_uuid=project.uuid)
backup_folder = rowan.create_folder("Backup Series", project_uuid=project.uuid)

# Submit to specific folder
workflow = rowan.submit_pka_workflow(
    mol,
    name="Lead 1 pKa",
    folder_uuid=lead_folder.uuid
)