Initial commit for rowan
This commit is contained in:
dfty
413
references/api_reference.md
Normal file
413
references/api_reference.md
Normal file
@@ -0,0 +1,413 @@
|
||||
# Rowan API Reference
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Workflow Class](#workflow-class)
|
||||
2. [Workflow Submission Functions](#workflow-submission-functions)
|
||||
3. [Workflow Retrieval Functions](#workflow-retrieval-functions)
|
||||
4. [Batch Operations](#batch-operations)
|
||||
5. [Utility Functions](#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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# Stop a running workflow
|
||||
workflow.stop()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Submission Functions
|
||||
|
||||
### Generic Submission
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
)
|
||||
```
|
||||
Reference in New Issue
Block a user