011 Workflow 2078e809

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

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

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
)