Core API

Workflow Utilities

Base classes for Rowan workflows.

Solvent module-attribute

Solvent = Solvent

Mode module-attribute

Mode = Mode

Workflow

Bases: BaseModel

Rowan workflow base model, returned by submit workflow functions.

Workflow data is not loaded by default to avoid unnecessary downloads that could impact performance. Call fetch_latest() to fetch and attach the workflow data.

Parameters:

Name	Type	Description	Default
name		Name of the workflow.	required
uuid		UUID of the workflow.	required
created_at		Date and time the workflow was created.	required
updated_at		Date and time the workflow was last updated.	required
started_at		Date and time the workflow computation was started.	required
completed_at		Date and time the workflow was completed.	required
status		Status of the workflow.	required
parent_uuid		UUID of the parent folder.	required
notes		Workflow notes.	required
starred		Whether the workflow is starred.	required
public		Whether the workflow is public.	required
workflow_type		Type of the workflow.	required
data		Data of the workflow.	required
email_when_complete		Whether to send an email when the workflow completes.	required
max_credits		Maximum number of credits to use for the workflow.	required
elapsed		Elapsed time of the workflow.	required
credits_charged		Number of credits charged for the workflow.	required
logfile		Workflow logfile.	required

fetch_latest

fetch_latest(in_place=False)

Loads workflow data from the database and updates the current instance.

Parameters:

Name	Type	Description	Default
in_place	bool	Whether to update the current instance in-place.	False

Returns:

Type	Description
Self	Updated instance (self).

Raises:

Type	Description
HTTPError	If the API request fails.

update

update(
    name=None,
    parent_uuid=None,
    notes=None,
    starred=None,
    email_when_complete=None,
    public=None,
    in_place=False,
)

Updates a workflow in the API with new data.

Parameters:

Name	Type	Description	Default
name	str | None	New name for the workflow.	None
parent_uuid	str | None	UUID of the parent folder.	None
notes	str | None	Description of the workflow.	None
starred	bool | None	Whether the workflow is starred.	None
email_when_complete	bool | None	Whether to send an email when complete.	None
public	bool | None	Whether the workflow is public.	None
in_place	bool	Whether to update the current instance in-place.	False

Raises:

Type	Description
HTTPError	If the API request fails.

done

done()

Check if the workflow has finished (success, failure, or stopped).

Non-blocking check following the concurrent.futures.Future pattern.

Returns:

Type	Description
bool	True if workflow is no longer running.

result

result(wait=True, poll_interval=5)

Return the typed result, optionally waiting for completion.

Follows the concurrent.futures.Future.result() pattern.

Parameters:

Name	Type	Description	Default
wait	bool	If True (default), block until the workflow completes. If False, return immediately with whatever data is available.	True
poll_interval	int	Seconds between status checks while waiting.	5

Returns:

Type	Description
WorkflowResult	WorkflowResult subclass with typed access to results.

Raises:

Type	Description
WorkflowError	If the workflow failed or was stopped.

stream_result

stream_result(poll_interval=5)

Poll the workflow and yield results until complete.

Yields partial results at each poll interval while running, then yields the final complete result once the workflow finishes.

:yields: WorkflowResult at each poll interval, with final complete result last.

Parameters:

Name	Type	Description	Default
poll_interval	int	Seconds between status checks.	5

Raises:

Type	Description
WorkflowError	If the workflow fails or is stopped.

wait_for_result

wait_for_result(poll_interval=5)

Wait for the workflow to finish.

.. deprecated:: Use :meth:result instead, which waits and returns the typed result.

Returns:

Type	Description
Self	Current instance (self).

get_status

get_status()

Gets the status of the workflow.

Returns:

Type	Description
Status	Status of the workflow, as an instance of stjames.Status.

is_finished

is_finished()

Check if the workflow is finished.

.. deprecated:: Use :meth:done instead.

Returns:

Type	Description
bool	True if the workflow status is COMPLETED_OK, FAILED, or STOPPED.

stop

stop()

Stops a workflow.

Raises:

Type	Description
HTTPError	If the API request fails.

delete

delete()

Deletes the workflow.

Raises:

Type	Description
HTTPError	If the API request fails.

delete_data

delete_data()

Deletes the workflow data from the API.

Raises:

Type	Description
HTTPError	If the API request fails.

download_msa_files

download_msa_files(msa_format, path=None)

Download MSA files for an MSA workflow.

.. deprecated:: Use workflow.result().download_files() instead.

download_dcd_files

download_dcd_files(replicates, name=None, path=None)

Downloads DCD trajectory files for specified replicates.

.. deprecated:: Use workflow.result().download_trajectories() instead.

Parameters:

Name	Type	Description	Default
replicates	list[int]	List of replicate indices to download	required
name	str | None	Optional custom name for the tar.gz file	None
path	Path | str | None	Directory to save the file to	None

WorkflowResult dataclass

WorkflowResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Base class for workflow results.

Wraps the raw workflow data dict and parses it into a stjames object for typed access to nested data.

Parameters:

Name	Type	Description	Default
workflow_data	dict[str, Any]	Raw data dict from the workflow	required
workflow_type	str	Workflow type string	required
workflow_uuid	str	UUID of the parent workflow (for API calls)	required

data property

data

Raw workflow data dict for fallback access.

clear_cache

clear_cache()

Clear all cached data to force re-fetching on next access.

Use this if you need to refresh lazily-loaded data (e.g., structures, calculations) from the API.

WorkflowError

Bases: Exception

Raised when a workflow fails or is stopped.

Message dataclass

Message(title, body, type)

A workflow message (error, warning, or info).

Parameters:

Name	Type	Description	Default
title	str	Short message title.	required
body	str	Full message content.	required
type	str	Message type: 'error', 'warning', or 'info'.	required

submit_workflow

submit_workflow(
    workflow_type,
    workflow_data=None,
    initial_molecule=None,
    initial_smiles=None,
    name=None,
    folder_uuid=None,
    max_credits=None,
)

Submits a workflow to the API.

Parameters:

Name	Type	Description	Default
workflow_type	WORKFLOW_NAME	Type of workflow to submit.	required
workflow_data	dict[str, Any] | None	Dictionary containing the data required to run the workflow.	None
initial_molecule	MoleculeInput | None	Molecule object to use as the initial molecule.	None
initial_smiles	str | None	SMILES string to use as the initial molecule.	None
name	str | None	Name for the workflow.	None
folder_uuid	str | Folder | None	UUID of the folder to store the workflow in, or a Folder object.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If neither initial_smiles nor a valid initial_molecule is provided.
HTTPError	If the API request fails.

retrieve_workflow

retrieve_workflow(uuid)

Retrieve a workflow from the API by UUID.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the workflow to retrieve.	required

Returns:

Type	Description
Workflow	Workflow object with the fetched data.

Raises:

Type	Description
requests.HTTPError	If the API request fails.

retrieve_workflows

retrieve_workflows(uuids)

Retrieve a list of workflows from the API.

Parameters:

Name	Type	Description	Default
uuids	list[str]	UUIDs of the workflows to retrieve.	required

Returns:

Type	Description
list[Workflow]	List of Workflow objects representing the retrieved workflows.

Raises:

Type	Description
HTTPError	If the API request fails.

list_workflows

list_workflows(
    parent_uuid=None,
    name_contains=None,
    public=None,
    starred=None,
    status=None,
    workflow_type=None,
    page=0,
    size=10,
)

List workflows subject to the specified criteria.

Parameters:

Name	Type	Description	Default
parent_uuid	str | None	UUID of the parent folder.	None
name_contains	str | None	Substring to search for in workflow names.	None
public	bool | None	Filter workflows by their public status.	None
starred	bool | None	Filter workflows by their starred status.	None
status	int | None	Filter workflows by their status.	None
workflow_type	WORKFLOW_NAME | None	Filter workflows by their type.	None
page	int	Page number to retrieve.	0
size	int	Number of items per page.	10

Returns:

Type	Description
list[Workflow]	List of Workflow objects that match the search criteria.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

batch_submit_workflow

batch_submit_workflow(
    workflow_type,
    workflow_data=None,
    initial_molecules=None,
    initial_smileses=None,
    names=None,
    folder_uuid=None,
    max_credits=None,
)

Submits a batch of workflows to the API.

Each workflow will be submitted with the same workflow type, workflow data, and folder UUID, but with different initial molecules and/or SMILES strings.

Parameters:

Name	Type	Description	Default
workflow_type	WORKFLOW_NAME	Type of workflow to submit.	required
workflow_data	dict[str, Any] | None	Dictionary containing the data required to run the workflow.	None
initial_molecules	list[MoleculeInput] | None	Molecule objects to use as initial molecules.	None
initial_smileses	list[str] | None	SMILES strings to use as initial molecules.	None
names	list[str] | None	Names for the submitted workflows.	None
folder_uuid	str | Folder | None	UUID of the folder to store the workflows in.	None
max_credits	int | None	Maximum number of credits to use per workflow.	None

Returns:

Type	Description
list[Workflow]	List of Workflow objects representing the submitted workflows.

batch_poll_status

batch_poll_status(uuids)

Poll the status of a list of workflows.

Parameters:

Name	Type	Description	Default
uuids	list[str]	UUIDs of the workflows to poll.	required

Returns:

Type	Description
list[dict[str, Any]]	Status information for each workflow.

Raises:

Type	Description
HTTPError	If the API request fails.

ADMET

ADMET workflow - Absorption, Distribution, Metabolism, Excretion, and Toxicity.

ADMETResult dataclass

ADMETResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from an ADMET workflow.

properties property

properties

ADMET properties (molecular weight, logP, TPSA, etc.).

submit_admet_workflow

submit_admet_workflow(
    initial_smiles,
    name="ADMET Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits an ADMET workflow to predict drug-likeness properties.

Parameters:

Name	Type	Description	Default
initial_smiles	str | MoleculeInput	Molecule to calculate ADMET properties for. Accepts a SMILES string or any molecule type (RowanMolecule, stjames.Molecule, RDKit Mol, or dict). The molecule must have a SMILES string associated with it, as ADMET models are 2D/SMILES-based and do not use 3D coordinates.	required
name	str	Name of the workflow.	'ADMET Workflow'
folder_uuid	str | None	UUID of the folder to store the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If the molecule has no SMILES associated with it.
requests.HTTPError	if the request to the API fails.

Analogue Docking

Analogue docking workflow - dock analogues using a template ligand.

AnalogueDockingResult dataclass

AnalogueDockingResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from an analogue-docking workflow.

analogue_scores property

analogue_scores

Docking scores for each analogue SMILES.

best_poses property

best_poses

Best docked pose per analogue, keyed by SMILES.

Fetches the final geometry from each analogue's top-scoring pose. Analogues with no successful poses are excluded.

Returns:

Type	Description
dict[str, Molecule]	Dictionary mapping SMILES to docked Molecule with 3D coordinates.

get_pose

get_pose(smiles, index=0)

Fetch a docked ligand pose as a calculation with 3D coordinates.

Parameters:

Name	Type	Description	Default
smiles	str	SMILES string of the analogue.	required
index	int	Index of the pose (0-based, ordered by score). Default 0 (best).	0

Returns:

Type	Description
Calculation	Calculation containing the docked ligand molecule with 3D coordinates.

Raises:

Type	Description
KeyError	If the SMILES is not found.
IndexError	If index is out of range.
ValueError	If the pose has no UUID.

get_poses

get_poses(smiles)

Fetch all docked ligand poses as calculations with 3D coordinates.

Parameters:

Name	Type	Description	Default
smiles	str	SMILES string of the analogue.	required

Returns:

Type	Description
list[Calculation]	List of Calculations for each pose (ordered by score).

Raises:

Type	Description
KeyError	If the SMILES is not found.

get_complex

get_complex(smiles, index=0)

Fetch a protein-ligand complex structure for a specific analogue.

Parameters:

Name	Type	Description	Default
smiles	str	SMILES string of the analogue.	required
index	int	Index of the pose (0-based, ordered by score). Default 0 (best).	0

Returns:

Type	Description
Protein	Protein object with the full protein-ligand complex.

Raises:

Type	Description
KeyError	If the SMILES is not found.
IndexError	If index is out of range.
ValueError	If the complex has no structure UUID.

get_complexes

get_complexes(smiles)

Fetch all protein-ligand complex structures for a specific analogue.

Parameters:

Name	Type	Description	Default
smiles	str	SMILES string of the analogue.	required

Returns:

Type	Description
list[Protein]	List of Protein objects for each complex (ordered by score).

Raises:

Type	Description
KeyError	If the SMILES is not found.

submit_analogue_docking_workflow

submit_analogue_docking_workflow(
    analogues,
    initial_molecule,
    protein,
    executable="vina",
    scoring_function="vinardo",
    exhaustiveness=8,
    name="Analogue Docking Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits an analogue-docking workflow to the API.

Parameters:

Name	Type	Description	Default
analogues	list[str]	SMILES strings to dock.	required
initial_molecule	MoleculeInput	Template to which to align molecules to.	required
protein	str | Protein	Protein to dock. Can be input as a uuid or a Protein object.	required
executable	str	Which docking implementation to use.	'vina'
scoring_function	str	Which docking scoring function to use.	'vinardo'
exhaustiveness	float	Which exhaustiveness to employ.	8
name	str	Name of the workflow.	'Analogue Docking Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted analogue-docking workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Basic Calculation

Basic calculation workflow - perform quantum chemical calculations.

BasicCalculationResult dataclass

BasicCalculationResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a basic-calculation workflow.

calculation_uuid property

calculation_uuid

The UUID of the calculation.

calculation property

calculation

Lazily fetched Calculation object with full molecule data.

molecule property

molecule

The final molecule geometry with all computed properties.

molecules property

molecules

All molecules from the calculation (e.g., optimization trajectory).

energy property

energy

Energy of the final molecule (Hartree).

charges property

charges

Partial charges on each atom.

spin_densities property

spin_densities

Spin densities on each atom (for open-shell systems).

dipole property

dipole

Dipole moment vector (Debye).

frequencies property

frequencies

Vibrational frequencies in cm^-1 (if frequency calculation was performed).

optimization_energies

optimization_energies(relative=False)

Energies for each optimization step.

Parameters:

Name	Type	Description	Default
relative	bool	If True, return relative energies in kcal/mol (relative to the lowest energy step). If False (default), return absolute energies in Hartree.	False

Returns:

Type	Description
list[float]	List of energies for each optimization step.

submit_basic_calculation_workflow

submit_basic_calculation_workflow(
    initial_molecule,
    method="omol25_conserving_s",
    basis_set=None,
    tasks=None,
    mode="auto",
    engine=None,
    name="Basic Calculation Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submit a basic-calculation workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to perform the calculation on.	required
method	Method | str	Method to use for the calculation.	'omol25_conserving_s'
basis_set	BasisSet | str | None	Basis set to use (if any).	None
tasks	list[str] | None	Tasks to perform for the calculation.	None
mode	str	Mode to run the calculation in.	'auto'
engine	str | None	Engine to use for the calculation.	None
name	str	Name of the workflow.	'Basic Calculation Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Batch Docking

Batch docking workflow - high-throughput molecular docking.

BatchDockingResult dataclass

BatchDockingResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a batch-docking workflow.

scores property

scores

Docking scores indexed by SMILES.

submit_batch_docking_workflow

submit_batch_docking_workflow(
    smiles_list,
    protein,
    pocket,
    executable="qvina2",
    scoring_function="vina",
    exhaustiveness=8,
    name="Batch Docking Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a batch-docking workflow to the API.

Parameters:

Name	Type	Description	Default
smiles_list	list[str]	SMILES strings to dock.	required
protein	str | Protein	Protein to dock (UUID or Protein object).	required
pocket	list[list[float]]	Binding pocket coordinates [[x,y,z], [x,y,z]].	required
executable	str	Which docking implementation to use.	'qvina2'
scoring_function	str	Which docking scoring function to use.	'vina'
exhaustiveness	float	Docking exhaustiveness parameter.	8
name	str	Name of the workflow.	'Batch Docking Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Bond Dissociation Energy

BDE workflow - Bond Dissociation Energy calculations.

BDEEntry dataclass

BDEEntry(fragment_idxs, energy=None)

A bond dissociation energy result.

BDEResult dataclass

BDEResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a Bond-Dissociation Energy (BDE) workflow.

energy property

energy

Energy of the molecule (Hartree).

bdes property

bdes

Bond dissociation energies.

submit_bde_workflow

submit_bde_workflow(
    initial_molecule,
    mode="rapid",
    atoms=None,
    all_CH=False,
    all_CX=False,
    name="BDE Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a Bond-Dissociation Energy (BDE) workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to calculate BDEs for.	required
mode	str	Mode to run the calculation in.	'rapid'
atoms	list[int] | None	Atom indices (1-indexed) to dissociate.	None
all_CH	bool	Whether to dissociate all C-H bonds.	False
all_CX	bool	Whether to dissociate all C-X bonds (X = halogen).	False
name	str	Name of the workflow.	'BDE Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

find_ch_bonds

find_ch_bonds(molecule, distance_max=1.2)

Find all C-H bonds in a molecule.

Parameters:

Name	Type	Description	Default
molecule	MoleculeInput	Molecule to search (Molecule, stjames.Molecule, or dict).	required
distance_max	float	Maximum C-H distance to consider a bond (A).	1.2

Returns:

Type	Description
list[tuple[int, int]]	List of (carbon_index, hydrogen_index) tuples (1-based indices). Example:: mol = Molecule.from_smiles("CCO") # ethanol bonds = find_ch_bonds(mol) # [(1, 4), (1, 5), (1, 6), (2, 7), (2, 8)]

find_cx_bonds

find_cx_bonds(molecule)

Find all C-X bonds in a molecule (X = F, Cl, Br, I, At, Ts).

Parameters:

Name	Type	Description	Default
molecule	MoleculeInput	Molecule to search (Molecule, stjames.Molecule, or dict).	required

Returns:

Type	Description
list[tuple[int, int]]	List of (carbon_index, halogen_index) tuples (1-based indices). Example:: mol = Molecule.from_smiles("CCCl") # chloroethane bonds = find_cx_bonds(mol) # [(2, 3)]

find_bonds

find_bonds(molecule, element_a, element_b, distance_max)

Find all bonds between two element types in a molecule.

Parameters:

Name	Type	Description	Default
molecule	MoleculeInput	Molecule to search (Molecule, stjames.Molecule, or dict).	required
element_a	int	Atomic number of first element.	required
element_b	int	Atomic number of second element.	required
distance_max	float	Maximum distance to consider a bond (A).	required

Returns:

Type	Description
list[tuple[int, int]]	List of (atom_a_index, atom_b_index) tuples (1-based indices). Example:: mol = Molecule.from_smiles("O") # water bonds = find_bonds(mol, 8, 1, 1.1) # O-H bonds # [(1, 2), (1, 3)]

Conformer Search

Conformer-search workflow - find low-energy molecular conformations.

ConformerSearchResult dataclass

ConformerSearchResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a conformer-search workflow.

num_conformers property

num_conformers

Number of conformers found.

conformer_uuids property

conformer_uuids

List of conformer UUIDs (nested for multistage optimization).

radii_of_gyration property

radii_of_gyration

Radius of gyration for each conformer (A).

sasa property

sasa

Solvent accessible surface area for each conformer (A^2).

polar_sasa property

polar_sasa

Polar solvent accessible surface area for each conformer (A^2).

get_energies

get_energies(relative=False)

Get conformer energies.

Parameters:

Name	Type	Description	Default
relative	bool	If True, return relative energies in kcal/mol (relative to the lowest energy conformer). If False (default), return absolute energies in Hartree.	False

Returns:

Type	Description
list[float]	List of conformer energies ordered by energy (lowest first).

get_conformers

get_conformers(n=None)

Fetch conformer molecules.

Parameters:

Name	Type	Description	Default
n	int | None	Number of conformers to fetch (default: all). Conformers are ordered by energy, so n=5 returns the 5 lowest-energy conformers.	None

Returns:

Type	Description
list[Molecule]	List of Molecule objects. .. note:: Makes one API call per conformer.

get_conformer

get_conformer(index, stage=-1)

Fetch a conformer's calculation data by index.

.. note:: Makes one API call per conformer on first access. Results are cached. Call clear_cache() to refresh.

Parameters:

Name	Type	Description	Default
index	int	Conformer index (0-based).	required
stage	int	Optimization stage (-1 for final stage).	-1

Returns:

Type	Description
Calculation	Calculation object with molecule and energy data.

Raises:

Type	Description
IndexError	If the index is out of range.
ValueError	If the conformer UUID is None.

submit_conformer_search_workflow

submit_conformer_search_workflow(
    initial_molecule,
    conf_gen_settings=None,
    final_method="aimnet2_wb97md3",
    solvent=None,
    transition_state=False,
    name="Conformer Search Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a conformer-search workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to perform the conformer search on.	required
conf_gen_settings	ConformerGenSettings | None	Conformer generation method and settings. Defaults to ETKDGSettings(). Available options (importable directly from rowan): ETKDGSettings -- RDKit ETKDG, fast, good for most small molecules LyrebirdSettings -- Rowan ML model iMTDGCSettings -- CREST iMTD-GC metadynamics, more thorough MonteCarloMultipleMinimumSettings -- MCMM conformer search	None
final_method	Method | str	Method to use for the final optimization.	'aimnet2_wb97md3'
solvent	SolventInput	Solvent to use for the final optimization.	None
transition_state	bool	Whether to optimize the transition state.	False
name	str	Name of the workflow.	'Conformer Search Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Descriptors

Descriptors workflow - calculate molecular descriptors.

DescriptorsResult dataclass

DescriptorsResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a descriptors workflow.

descriptors property

descriptors

Computed molecular descriptors.

submit_descriptors_workflow

submit_descriptors_workflow(
    initial_molecule,
    name="Descriptors Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a descriptors workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to calculate the descriptors of.	required
name	str	Name of the workflow.	'Descriptors Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Docking

Docking workflow - molecular docking to protein targets.

DockingScore dataclass

DockingScore(
    score, pose=None, complex_pdb=None, posebusters_valid=False, strain=None, rmsd=None
)

A docking pose with its score.

DockingResult dataclass

DockingResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a docking workflow.

scores property

scores

List of docking scores with poses.

conformers property

conformers

UUIDs of optimized conformers.

best_pose property

best_pose

Best docked pose as a Molecule with 3D coordinates.

get_pose

get_pose(index=0)

Fetch a docked ligand pose as a calculation with 3D coordinates.

Parameters:

Name	Type	Description	Default
index	int	Index of the pose (0-based, ordered by score). Default 0 (best).	0

Returns:

Type	Description
Calculation	Calculation containing the docked ligand molecule with 3D coordinates.

Raises:

Type	Description
IndexError	If index is out of range.
ValueError	If the pose has no UUID.

get_poses

get_poses()

Fetch all docked ligand poses as calculations with 3D coordinates.

Returns:

Type	Description
list[Calculation]	List of Calculations for each pose (ordered by score).

get_complex

get_complex(index=0)

Fetch a protein-ligand complex structure.

Parameters:

Name	Type	Description	Default
index	int	Index of the pose (0-based, ordered by score). Default 0 (best).	0

Returns:

Type	Description
Protein	Protein object with the full protein-ligand complex.

Raises:

Type	Description
IndexError	If index is out of range.
ValueError	If the complex has no structure UUID.

get_complexes

get_complexes()

Fetch all protein-ligand complex structures.

Returns:

Type	Description
list[Protein]	List of Protein objects for each complex (ordered by score).

submit_docking_workflow

submit_docking_workflow(
    protein,
    pocket,
    initial_molecule,
    executable="vina",
    scoring_function="vinardo",
    exhaustiveness=8,
    do_csearch=False,
    do_optimization=False,
    do_pose_refinement=True,
    name="Docking Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a docking workflow to the API.

Parameters:

Name	Type	Description	Default
protein	str | Protein	Protein to dock. Can be input as a uuid or a Protein object.	required
pocket	list[list[float]]	Binding pocket coordinates [[x,y,z], [x,y,z]].	required
initial_molecule	MoleculeInput	Initial molecule to be docked.	required
executable	str	Which docking implementation to use.	'vina'
scoring_function	str	Which docking scoring function to use.	'vinardo'
exhaustiveness	float	Which exhaustiveness to employ.	8
do_csearch	bool	Whether to perform a conformational search on the ligand.	False
do_optimization	bool	Whether to perform an optimization on the ligand.	False
do_pose_refinement	bool	Whether or not to optimize output poses.	True
name	str	Name of the workflow.	'Docking Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted docking workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Double-Ended TS Search

Double-ended TS search workflow - find transition states between reactant and product.

ReactionPathPoint dataclass

ReactionPathPoint(distance, calculation_uuid, calculation=None)

Point along the reaction path.

Parameters:

Name	Type	Description	Default
distance	float	Distance along the reaction path.	required
calculation_uuid	str | None	UUID of the calculation at this point.	required
calculation	Calculation | None	Populated by get_path_calculations(), None otherwise.	None

DoubleEndedTSSearchResult dataclass

DoubleEndedTSSearchResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a double-ended transition state search workflow.

ts_guess_calculation_uuid property

ts_guess_calculation_uuid

UUID of the transition state guess calculation.

ts_guess_calculation property

ts_guess_calculation

The transition state guess Calculation with full molecule data (lazily fetched).

ts_molecule property

ts_molecule

The transition state molecule.

ts_energy property

ts_energy

Energy of the transition state (Hartree).

forward_path property

forward_path

Reaction path points from reactant to TS.

backward_path property

backward_path

Reaction path points from product to TS.

get_path_calculations

get_path_calculations()

Fetch all path point calculations, sorted by distance.

Combines forward (reactant → TS) and backward (product → TS) points, sorted by distance, each with its Calculation populated. Results are cached after the first call.

.. note:: Makes one API call per path point on first access.

Returns:

Type	Description
list[ReactionPathPoint]	List of ReactionPathPoints with calculations populated, sorted by distance.

get_path_energies

get_path_energies(relative=False)

Get energies along the reaction path, sorted by distance.

Parameters:

Name	Type	Description	Default
relative	bool	If True, return relative energies in kcal/mol (relative to the lowest energy point). If False (default), return absolute energies in Hartree.	False

Returns:

Type	Description
list[float]	List of energies along the reaction path.

submit_double_ended_ts_search_workflow

submit_double_ended_ts_search_workflow(
    reactant,
    product,
    calculation_settings=None,
    search_settings=None,
    optimize_inputs=False,
    optimize_ts=True,
    name="Double-Ended TS Search Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a double-ended transition state search workflow to the API.

Parameters:

Name	Type	Description	Default
reactant	dict[str, Any] | Molecule	reactant Molecule.	required
product	dict[str, Any] | Molecule	product Molecule.	required
calculation_settings	Settings | dict[str, Any] | None	Settings to use for calculations.	None
search_settings	FSMSettings | dict[str, Any] | None	settings to use for the transition state search.	None
optimize_inputs	bool	Whether to optimize the reactant and product before the search.	False
optimize_ts	bool	Whether to optimize the found transition state.	True
name	str	name of the workflow.	'Double-Ended TS Search Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Electronic Properties

Electronic properties workflow - calculate electronic properties.

MolecularOrbital dataclass

MolecularOrbital(points, occupation, energy)

Molecular orbital with cube data.

Parameters:

Name	Type	Description	Default
points	tuple[tuple[float, float, float, float], ...]	Cube data as (x, y, z, value) points (Bohr).	required
occupation	int	Occupation number (0, 1, or 2).	required
energy	float	Orbital energy (Hartree).	required

ElectronicPropertiesResult dataclass

ElectronicPropertiesResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from an electronic-properties workflow.

dipole property

dipole

Dipole moment vector (Debye).

quadrupole property

quadrupole

Quadrupole moment tensor (Debye*A).

mulliken_charges property

mulliken_charges

Mulliken partial charges on each atom.

lowdin_charges property

lowdin_charges

Lowdin partial charges on each atom.

wiberg_bond_orders property

wiberg_bond_orders

Wiberg bond orders as (atom1, atom2, order) tuples.

mayer_bond_orders property

mayer_bond_orders

Mayer bond orders as (atom1, atom2, order) tuples.

density_cube property

density_cube

Electron density cube as list of (x, y, z, value) points.

electrostatic_potential_cube property

electrostatic_potential_cube

Electrostatic potential cube as list of (x, y, z, value) points.

molecular_orbitals property

molecular_orbitals

Molecular orbitals indexed by orbital number.

homo property

homo

Highest occupied molecular orbital (HOMO). Energy in Hartree.

lumo property

lumo

Lowest unoccupied molecular orbital (LUMO). Energy in Hartree.

homo_lumo_gap property

homo_lumo_gap

HOMO-LUMO gap (Hartree).

submit_electronic_properties_workflow

submit_electronic_properties_workflow(
    initial_molecule,
    method="b97_3c",
    basis_set=None,
    compute_density_cube=True,
    compute_electrostatic_potential_cube=True,
    compute_num_occupied_orbitals=1,
    compute_num_virtual_orbitals=1,
    name="Electronic Properties Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits an electronic-properties workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to calculate electronic properties for.	required
method	Method | str	Method to use for the calculation.	'b97_3c'
basis_set	str | None	Basis set to use (if any).	None
compute_density_cube	bool	Whether to compute the density cube.	True
compute_electrostatic_potential_cube	bool	Whether to compute the electrostatic potential cube.	True
compute_num_occupied_orbitals	int	Number of occupied orbitals to save.	1
compute_num_virtual_orbitals	int	Number of virtual orbitals to save.	1
name	str	Name of the workflow.	'Electronic Properties Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Fukui

Fukui workflow - calculate Fukui indices for reactivity prediction.

FukuiResult dataclass

FukuiResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a Fukui index workflow.

global_electrophilicity_index property

global_electrophilicity_index

Global electrophilicity index.

fukui_positive property

fukui_positive

Fukui f+ indices (electrophilic attack susceptibility).

fukui_negative property

fukui_negative

Fukui f- indices (nucleophilic attack susceptibility).

fukui_zero property

fukui_zero

Fukui f0 indices (radical attack susceptibility).

submit_fukui_workflow

submit_fukui_workflow(
    initial_molecule,
    optimization_method="gfn2_xtb",
    fukui_method="gfn1_xtb",
    solvent_settings=None,
    name="Fukui Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a Fukui workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to calculate the Fukui indices of.	required
optimization_method	str	Method to use for the optimization.	'gfn2_xtb'
fukui_method	str	Method to use for the Fukui calculation.	'gfn1_xtb'
solvent_settings	dict[str, str] | None	Optional implicit solvent for the Fukui calculation. A dict with two keys: "solvent": solvent name string (e.g. "water", "dichloromethane", "dmso"). See rowan.Solvent for all valid values. "model": solvation model. Use "alpb" or "gbsa" for xTB methods (the defaults gfn1_xtb / gfn2_xtb); use "cpcm" or "smd" for DFT methods. Example: solvent_settings={"solvent": "water", "model": "alpb"}	None
name	str	Name of the workflow.	'Fukui Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If the solvent model is incompatible with the chosen method.
requests.HTTPError	if the request to the API fails.

Hydrogen Bond Donor/Acceptor Strength

Hydrogen-bond donor/acceptor-strength workflow.

HydrogenBondAcceptorSite dataclass

HydrogenBondAcceptorSite(atom_idx, pkbhx, position, name=None)

Hydrogen-bond-acceptor site.

HydrogenBondDonorSite dataclass

HydrogenBondDonorSite(atom_idx, pk_alpha, position)

Hydrogen-bond-donor site.

HydrogenBondDonorAcceptorStrengthResult dataclass

HydrogenBondDonorAcceptorStrengthResult(
    workflow_data, workflow_type, workflow_uuid, eager=True
)

Bases: WorkflowResult

Result from a hydrogen-bond donor/acceptor-strength workflow.

acceptor_sites property

acceptor_sites

Hydrogen bond acceptor sites with pKBHX values.

donor_sites property

donor_sites

Hydrogen bond donor sites with pK_alpha values.

molecular_pkbhx property

molecular_pkbhx

Overall molecular HBA strength as log10(sum of 10^pkbhx) for sites with pkbhx > -1.

molecular_pk_alpha property

molecular_pk_alpha

Overall molecular HBD strength as log10(sum of 10^pk_alpha) (pk_alpha > -1).

submit_hydrogen_bond_donor_acceptor_strength_workflow

submit_hydrogen_bond_donor_acceptor_strength_workflow(
    initial_molecule,
    do_csearch=True,
    do_optimization=True,
    name="Hydrogen-Bond Acceptor/Donor Strength",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a hydrogen-bond donor/acceptor-strength workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to calculate HBA/HBD strength for.	required
do_csearch	bool	Whether to perform a conformational search.	True
do_optimization	bool	Whether to perform an optimization.	True
name	str	Name of the workflow.	'Hydrogen-Bond Acceptor/Donor Strength'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Interaction Energy Decomposition

Interaction energy decomposition workflow - SAPT0 decomposition between molecular fragments.

InteractionEnergyDecompositionResult dataclass

InteractionEnergyDecompositionResult(
    workflow_data, workflow_type, workflow_uuid, eager=True
)

Bases: WorkflowResult

Result from an interaction energy decomposition workflow.

fragment1_indices property

fragment1_indices

Atom indices (1-indexed) defining fragment 1.

total_interaction_energy property

total_interaction_energy

Total interaction energy (kcal/mol).

electrostatic_interaction_energy property

electrostatic_interaction_energy

Electrostatic interaction energy (kcal/mol).

exchange_interaction_energy property

exchange_interaction_energy

Exchange interaction energy (kcal/mol).

dispersion_interaction_energy property

dispersion_interaction_energy

Dispersion interaction energy (kcal/mol).

induction_interaction_energy property

induction_interaction_energy

Induction interaction energy (kcal/mol).

_validate_fragment_separation

_validate_fragment_separation(molecule, fragment1_indices)

Validate that no atom in fragment 1 is covalently bonded to an atom outside fragment 1.

Raises:

Type	Description
ValueError	If a cross-fragment covalent bond is detected.

submit_interaction_energy_decomposition_workflow

submit_interaction_energy_decomposition_workflow(
    initial_molecule,
    fragment1_indices,
    method="sapt0",
    basis_set="jun-cc-pVDZ",
    name="Interaction Energy Decomposition",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits an interaction energy decomposition (SAPT0) workflow to the API.

Decomposes the interaction energy between two molecular fragments into electrostatic, exchange, dispersion, and induction components.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Dimer molecule to decompose.	required
fragment1_indices	list[int]	Atom indices (1-indexed) defining fragment 1. Fragment 2 is all remaining atoms.	required
method	Literal['sapt0']	Energy decomposition method. Currently only "sapt0" is supported.	'sapt0'
basis_set	str	Basis set for the calculation. Defaults to "jun-cc-pVDZ".	'jun-cc-pVDZ'
name	str	Name of the workflow.	'Interaction Energy Decomposition'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If both folder and folder_uuid are provided, or if fragment 1 contains atoms covalently bonded to atoms outside fragment 1.
requests.HTTPError	if the request to the API fails.

Ion Mobility

Ion-mobility workflow - predict collision cross sections.

IonMobilityResult dataclass

IonMobilityResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from an ion-mobility workflow.

average_ccs property

average_ccs

Average collision cross section (Angstrom^2).

average_ccs_stdev property

average_ccs_stdev

Uncertainty in average CCS.

conformer_ccs property

conformer_ccs

Collision cross section per conformer (Angstrom^2).

boltzmann_weights property

boltzmann_weights

Boltzmann weights for conformers.

submit_ion_mobility_workflow

submit_ion_mobility_workflow(
    initial_molecule,
    temperature=300,
    protonate=False,
    do_csearch=True,
    do_optimization=True,
    name="Ion-Mobility Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits an ion-mobility workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule used in the scan.	required
temperature	float	Temperature at which to predict CCS values (K).	300
protonate	bool	Whether or not to automatically detect protonation site. If True, every basic site will be protonated and values returned for the most stable.	False
do_csearch	bool	Whether to perform a conformational search on the molecule.	True
do_optimization	bool	Whether to perform an optimization on the molecule.	True
name	str	Name of the workflow.	'Ion-Mobility Workflow'
folder_uuid	str | None	UUID of the folder to store the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

IRC

IRC workflow - Intrinsic Reaction Coordinate calculations.

IRCResult dataclass

IRCResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from an Intrinsic Reaction Coordinate (IRC) workflow.

ts_uuid property

ts_uuid

UUID of the transition state calculation.

forward_uuids property

forward_uuids

UUIDs of the forward IRC path calculations.

backward_uuids property

backward_uuids

UUIDs of the backward IRC path calculations.

ts_calculation property

ts_calculation

The transition state Calculation (lazily fetched).

ts_molecule property

ts_molecule

The optimized transition state molecule.

ts_energy property

ts_energy

Energy of the transition state (Hartree).

forward_molecules property

forward_molecules

Molecules along the forward IRC path (lazily fetched).

backward_molecules property

backward_molecules

Molecules along the backward IRC path (lazily fetched).

get_forward_calculations

get_forward_calculations()

Fetch all forward IRC path calculations.

Returns:

Type	Description
list[Calculation]	List of Calculation objects along the forward path. .. note:: Makes one API call per step. Results are cached.

get_backward_calculations

get_backward_calculations()

Fetch all backward IRC path calculations.

Returns:

Type	Description
list[Calculation]	List of Calculation objects along the backward path. .. note:: Makes one API call per step. Results are cached.

get_forward_energies

get_forward_energies(relative=False)

Get energies along the forward IRC path.

Parameters:

Name	Type	Description	Default
relative	bool	If True, return relative energies in kcal/mol (relative to the lowest energy point). If False (default), return absolute energies in Hartree.	False

Returns:

Type	Description
list[float]	List of energies along the forward path.

get_backward_energies

get_backward_energies(relative=False)

Get energies along the backward IRC path.

Parameters:

Name	Type	Description	Default
relative	bool	If True, return relative energies in kcal/mol (relative to the lowest energy point). If False (default), return absolute energies in Hartree.	False

Returns:

Type	Description
list[float]	List of energies along the backward path.

submit_irc_workflow

submit_irc_workflow(
    initial_molecule,
    method="uma_m_omol",
    solvent=None,
    preopt=True,
    step_size=0.05,
    max_irc_steps=30,
    name="IRC Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits an Intrinsic Reaction Coordinate (IRC) workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Transition state molecule to start IRC from.	required
method	Method | str	Computational method to use for the IRC calculation.	'uma_m_omol'
solvent	SolventInput	Solvent to use for the calculation.	None
preopt	bool	Whether to perform a pre-optimization of the TS.	True
step_size	float	Step size to use for the IRC calculation.	0.05
max_irc_steps	int	Maximum number of IRC steps to perform.	30
name	str	Name of the workflow.	'IRC Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted IRC workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

MacropKa

MacropKa workflow - predict macroscopic pKa values.

MacropKaMicrostate dataclass

MacropKaMicrostate(smiles, energy, charge)

A microstate from a macropKa calculation.

MacropKaValue dataclass

MacropKaValue(initial_charge, final_charge, pka)

A macroscopic pKa value.

MacropKaResult dataclass

MacropKaResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a macropKa workflow.

isoelectric_point property

isoelectric_point

Isoelectric point (pH units).

solvation_energy property

solvation_energy

Solvation energy (kcal/mol).

kpuu_probability property

kpuu_probability

Probability that Kpuu >= 0.3.

microstates property

microstates

All microstates.

pka_values property

pka_values

Macroscopic pKa values.

microstate_weights_by_ph property

microstate_weights_by_ph

Microstate weights by pH as (pH, weights) pairs.

Each weights list corresponds to the microstates in the same order as the microstates property.

logd_by_ph property

logd_by_ph

Distribution constant by pH as (pH, logD) pairs.

aqueous_solubility_by_ph property

aqueous_solubility_by_ph

Aqueous solubility by pH as (pH, log(S)/L) pairs.

submit_macropka_workflow

submit_macropka_workflow(
    initial_smiles,
    min_pH=0,
    max_pH=14,
    min_charge=-2,
    max_charge=2,
    compute_solvation_energy=False,
    compute_aqueous_solubility=True,
    name="Macropka Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a macropKa workflow to the API.

Parameters:

Name	Type	Description	Default
initial_smiles	str | MoleculeInput	Molecule to calculate macroscopic pKa values for. Accepts a SMILES string or any molecule type (RowanMolecule, stjames.Molecule, RDKit Mol, or dict). The molecule must have a SMILES string associated with it, as macropKa models are 2D/SMILES-based and do not use 3D coordinates.	required
min_pH	int	Minimum pH to use in the macropka workflow.	0
max_pH	int	Maximum pH to use in the macropka workflow.	14
min_charge	int	Minimum charge to use in the macropka workflow.	-2
max_charge	int	Maximum charge to use in the macropka workflow.	2
compute_solvation_energy	bool	Whether to compute the solvation energy.	False
compute_aqueous_solubility	bool	Whether to compute aqueous solubility for each pH.	True
name	str	Name of the workflow.	'Macropka Workflow'
folder_uuid	str | None	UUID of the folder to store the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If the molecule has no SMILES associated with it.
requests.HTTPError	if the request to the API fails.

Membrane Permeability

Membrane permeability workflow - predict membrane permeability.

MembranePermeabilityResult dataclass

MembranePermeabilityResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a membrane-permeability workflow.

caco2_p_app property

caco2_p_app

Caco-2 apparent permeability (cm/s).

caco2_log_p property

caco2_log_p

Caco-2 log permeability.

blm_log_p property

blm_log_p

Black lipid membrane log permeability.

pampa_log_p property

pampa_log_p

PAMPA log permeability.

plasma_log_p property

plasma_log_p

Plasma membrane log permeability.

bbb_log_p property

bbb_log_p

Blood-brain barrier log permeability.

energy_profile property

energy_profile

Energy profile across the membrane as (position (A), energy (kcal/mol)) pairs.

submit_membrane_permeability_workflow

submit_membrane_permeability_workflow(
    initial_molecule,
    method="gnn-mtl",
    name="Membrane Permeability Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a membrane-permeability workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput | str	Molecule used in the workflow.	required
method	Literal['gnn-mtl', 'pypermm']	Method used to compute membrane permeability.	'gnn-mtl'
name	str	Name of the workflow.	'Membrane Permeability Workflow'
folder_uuid	str | None	UUID of the folder to store the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

MSA

MSA workflow - Multiple Sequence Alignment for proteins.

MSAResult dataclass

MSAResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a Multiple Sequence Alignment (MSA) workflow.

_output_formats property

_output_formats

Output formats requested for the MSA.

download_files

download_files(format=None, path=None)

Download MSA files for this workflow.

Parameters:

Name	Type	Description	Default
format	MSAOutputFormat | MSAFormat | None	Output format to download. If None, downloads all requested formats.	None
path	Path | str | None	Directory to save files to. Defaults to current directory.	None

Returns:

Type	Description
list[Path]	List of paths to downloaded tar.gz files.

Raises:

Type	Description
ValueError	If the requested format wasn't in the original output_formats.
HTTPError	If the API request fails.

submit_msa_workflow

submit_msa_workflow(
    initial_protein_sequences,
    output_formats=None,
    name="MSA Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a Multiple Sequence Alignment (MSA) workflow to the API.

Parameters:

Name	Type	Description	Default
initial_protein_sequences	list[str | ProteinSequence]	List of protein sequences to align (amino acid strings).	required
output_formats	set[MSAOutputFormat | MSAFormat] | None	Output formats for the MSA files ("colabfold", "chai", "boltz"). Defaults to {"colabfold"}.	None
name	str	Name to assign to the workflow.	'MSA Workflow'
folder_uuid	str | None	UUID of the folder where the workflow will be stored.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted MSA workflow.

Raises:

Type	Description
HTTPError	If the API request fails.

Multistage Optimization

Multistage optimization workflow - optimize molecules with staged methods.

MultiStageOptResult dataclass

MultiStageOptResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a multistage-optimization workflow.

calculation_uuids property

calculation_uuids

UUIDs of all calculations in the optimization stages.

calculations property

calculations

All optimization stage calculations (lazily fetched).

Typically includes xTB pre-optimization, DFT optimization, and final single-point. Access final_calculation for just the last stage.

final_calculation property

final_calculation

The final Calculation object with full molecule data (lazily fetched).

molecule property

molecule

The final optimized molecule geometry.

energy property

energy

Energy of the final optimized molecule (Hartree).

charges property

charges

Partial charges on each atom.

dipole property

dipole

Dipole moment vector (Debye).

get_stage_energies

get_stage_energies()

Fetch energies for all completed stages.

Useful for polling partial results — call this on each poll to see which stages have completed and their energies.

Returns:

Type	Description
list[tuple[str, float | None]]	List of (calculation_uuid, energy_in_hartree) for each completed stage. .. note:: Makes one API call per completed stage. Results are not cached since this is intended for use during polling with result(wait=False).

submit_multistage_optimization_workflow

submit_multistage_optimization_workflow(
    initial_molecule,
    mode=Mode.RAPID,
    solvent=None,
    xtb_preopt=True,
    transition_state=False,
    frequencies=False,
    name="Multistage Optimization Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a multistage-optimization workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to optimize.	required
mode	Mode	Mode to run the calculation in.	RAPID
solvent	SolventInput	Solvent for the final single-point calculation.	None
xtb_preopt	bool	Whether to pre-optimize with xTB.	True
transition_state	bool	Whether this is a transition state optimization.	False
frequencies	bool	Whether to calculate frequencies.	False
name	str	Name of the workflow.	'Multistage Optimization Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

NMR

NMR workflow - predict Nuclear Magnetic Resonance spectra.

NMRPeak dataclass

NMRPeak(nucleus, shift, atom_indices)

An NMR peak.

NMRResult dataclass

NMRResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a Nuclear Magnetic Resonance (NMR) workflow.

chemical_shifts property

chemical_shifts

Per-atom NMR chemical shifts (Boltzmann-weighted ensemble average).

Index corresponds to atom index in the molecule. Returns None for atoms without NMR-active nuclei (e.g., oxygen).

per_conformer_chemical_shifts property

per_conformer_chemical_shifts

Chemical shifts for each conformer before Boltzmann averaging.

Outer list is per-conformer, inner list is per-atom.

boltzmann_weights property

boltzmann_weights

Boltzmann weights for each conformer (sum to 1.0).

conformer_uuids property

conformer_uuids

UUIDs of the conformer calculations.

predicted_peaks property

predicted_peaks

Predicted NMR peaks grouped by nucleus atomic number.

Keys are atomic numbers (1 for 1H, 6 for 13C). Peaks with equivalent atoms are merged and shifts are averaged.

symmetry_equivalent_nuclei property

symmetry_equivalent_nuclei

Groups of symmetry-equivalent atom indices (0-indexed).

Atoms in the same group have equivalent chemical environments and are averaged together in predicted_peaks.

submit_nmr_workflow

submit_nmr_workflow(
    initial_molecule,
    solvent="chloroform",
    do_csearch=True,
    do_optimization=True,
    name="NMR Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a Nuclear Magnetic Resonance (NMR) prediction workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to predict NMR spectra for.	required
solvent	SolventInput	Solvent for NMR calculation (default: chloroform).	'chloroform'
do_csearch	bool	Whether to perform a conformational search.	True
do_optimization	bool	Whether to optimize conformer geometries.	True
name	str	Name of the workflow.	'NMR Workflow'
folder_uuid	str | None	UUID of the folder to store the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

pKa

pKa workflow - predict acid/base dissociation constants.

pKaMicrostate dataclass

pKaMicrostate(atom_index, pka, smiles=None, delta_g=None, uncertainty=None)

Microstate from a pKa calculation.

Available fields depend on the pKa method used: aimnet2_wagen2024 provides delta_g; chemprop_nevolianis2025 provides smiles and uncertainty.

Parameters:

Name	Type	Description	Default
atom_index	int	Index of the protonation site atom.	required
pka	float	Predicted pKa value.	required
smiles	str | None	SMILES of the microstate (chemprop_nevolianis2025 only).	None
delta_g	float | None	Free energy of (de)protonation in kcal/mol (aimnet2_wagen2024 only).	None
uncertainty	float | None	Prediction uncertainty (chemprop_nevolianis2025 only).	None

pKaResult dataclass

pKaResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a pKa workflow.

strongest_acid property

strongest_acid

Strongest acidic site pKa value.

strongest_base property

strongest_base

Strongest basic site pKa value.

conjugate_acids property

conjugate_acids

List of conjugate acid microstates with pKa values.

conjugate_bases property

conjugate_bases

List of conjugate base microstates with pKa values.

structures property

structures

Optimized structure calculations (lazily fetched).

Only available for aimnet2_wagen2024 method (3D structure-based).

.. note:: Makes one API call per structure on first access. Results are cached. Call clear_cache() to refresh.

Raises:

Type	Description
ValueError	If method is chemprop_nevolianis2025 (no structures).

_make_microstate

_make_microstate(m)

Convert a stjames microstate to pKaMicrostate.

_get_structure_uuids

_get_structure_uuids()

Extract structure UUIDs from workflow data.

submit_pka_workflow

submit_pka_workflow(
    initial_molecule,
    pka_range=(2, 12),
    method="aimnet2_wagen2024",
    solvent="water",
    deprotonate_elements=None,
    protonate_elements=None,
    mode=Mode.CAREFUL,
    name="pKa Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a pKa workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput | str	Molecule to calculate pKa for. Accepts Molecule, stjames.Molecule, RDKit Mol, dict, or SMILES string.	required
pka_range	tuple[int, int]	Range of pKa values to calculate.	(2, 12)
method	Literal['aimnet2_wagen2024', 'chemprop_nevolianis2025']	Algorithm used to compute pKa values.	'aimnet2_wagen2024'
solvent	SolventInput	Solvent in which pKa values will be computed.	'water'
deprotonate_elements	list[int] | None	Elements to deprotonate (atomic numbers).	None
protonate_elements	list[int] | None	Elements to protonate (atomic numbers).	None
mode	Mode	Mode to run the calculation in.	CAREFUL
name	str	Name of the workflow.	'pKa Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If method and input type don't match.
requests.HTTPError	if the request to the API fails.

Pose Analysis MD

Pose-analysis MD workflow - molecular dynamics simulations for ligand-protein complexes.

TrajectoryResult dataclass

TrajectoryResult(uuid, ligand_rmsd, contacts)

Results from a single MD trajectory replicate.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the trajectory calculation.	required
ligand_rmsd	list[float]	Ligand RMSD values over time (Angstrom).	required
contacts	list[BindingPoseContact]	Ligand-protein contacts with occupancy over the trajectory.	required

PoseAnalysisMDResult dataclass

PoseAnalysisMDResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a Pose-Analysis Molecular Dynamics (MD) workflow.

trajectories property

trajectories

Results from each trajectory replicate.

Each trajectory contains RMSD values, contact analysis, and cluster assignments.

average_rmsds property

average_rmsds

Average ligand RMSD per trajectory (Angstrom).

minimized_protein_uuid property

minimized_protein_uuid

UUID of the energy-minimized protein structure.

messages property

messages

Any messages or warnings from the workflow.

get_minimized_protein

get_minimized_protein()

Fetch the energy-minimized protein structure.

.. note:: Makes one API call on first access. Results are cached. Call clear_cache() to refresh.

Returns:

Type	Description
Protein | None	Protein object or None if not available.

get_atom_distances

get_atom_distances(atom_pairs, replicate=0)

Fetch interatomic distances over the trajectory for specified atom pairs.

Atom indices can be found in the contacts field of each trajectory, which provides ligand_atom_index and protein_atom_index for each contact.

Parameters:

Name	Type	Description	Default
atom_pairs	list[tuple[int, int]]	List of (atom_i, atom_j) index pairs (0-indexed).	required
replicate	int	Trajectory replicate index (default 0).	0

Returns:

Type	Description
list[list[float]]	List of distance arrays, one per pair, over all frames (Angstrom).

Raises:

Type	Description
HTTPError	If the API request fails.

download_trajectories

download_trajectories(replicates, name=None, path=None)

Download DCD trajectory files for specified replicates.

Parameters:

Name	Type	Description	Default
replicates	list[int]	List of replicate indices to download.	required
name	str | None	Custom name for the tar.gz file (without extension).	None
path	Path | str | None	Directory to save the file to. Defaults to current directory.	None

Returns:

Type	Description
Path	Path to the downloaded tar.gz file.

Raises:

Type	Description
HTTPError	If the API request fails.

submit_pose_analysis_md_workflow

submit_pose_analysis_md_workflow(
    protein,
    initial_smiles,
    num_trajectories=4,
    equilibration_time_ns=1,
    simulation_time_ns=10,
    temperature=300,
    pressure_atm=1.0,
    langevin_timescale_ps=1.0,
    timestep_fs=2,
    constrain_hydrogens=True,
    nonbonded_cutoff=8.0,
    ionic_strength_M=0.1,
    water_buffer=6.0,
    ligand_residue_name="LIG",
    protein_restraint_cutoff=7.0,
    protein_restraint_constant=100,
    save_solvent=False,
    validate_forcefield=True,
    name="Pose-Analysis MD Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a Pose-Analysis Molecular Dynamics (MD) workflow to the API.

Parameters:

Name	Type	Description	Default
protein	str | Protein	Holo protein on which MD will be run. Can be input as a UUID or a Protein object.	required
initial_smiles	str	SMILES for the ligand.	required
num_trajectories	int	Number of trajectories to run.	4
equilibration_time_ns	float	Equilibration time per trajectory, in ns.	1
simulation_time_ns	float	Simulation time per trajectory, in ns.	10
temperature	float	Temperature, in K.	300
pressure_atm	float	Pressure, in atm.	1.0
langevin_timescale_ps	float	Timescale for the Langevin integrator, in ps⁻¹.	1.0
timestep_fs	float	Timestep, in femtoseconds.	2
ligand_residue_name	str	Name of the residue corresponding to the ligand.	'LIG'
constrain_hydrogens	bool	Whether to use SHAKE to freeze bonds to hydrogen.	True
nonbonded_cutoff	float	Nonbonded cutoff for particle-mesh Ewald, in Å.	8.0
ionic_strength_M	float	Ionic strength of the solution, in M (molar).	0.1
water_buffer	float	Amount of water to add around the protein, in Å.	6.0
protein_restraint_cutoff	float	Cutoff past which alpha-carbons will be constrained, in Å.	7.0
protein_restraint_constant	float	Force constant for backbone restraints, in kcal/mol/Ų.	100
save_solvent	bool	Whether to save solvent molecules.	False
validate_forcefield	bool	if True (default), validate the protein forcefield compatibility before submitting. Raises an error early if the protein cannot be parameterized or has clashing residues.	True
name	str	Name of the workflow.	'Pose-Analysis MD Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Protein Binder Design

Protein binder design workflow - generate protein binders.

BinderScores dataclass

BinderScores(
    iptm=None,
    design_ptm=None,
    quality_score=None,
    bb_rmsd=None,
    loop=None,
    helix=None,
    sheet=None,
    liability_score=None,
    liability_num_violations=None,
    liability_high_severity_violations=None,
    min_interaction_pae=None,
    delta_sasa_refolded=None,
    plip_hbonds_refolded=None,
    plip_saltbridge_refolded=None,
    num_tokens=None,
    design_hydrophobicity=None,
    num_filters_passed=None,
)

Scores for a generated protein binder design.

Parameters:

Name	Type	Description	Default
iptm	float | None	Interface predicted TM-score (0-1, higher is better).	None
design_ptm	float | None	Predicted TM-score for the designed binder (0-1).	None
quality_score	float | None	Overall quality score (0-1, higher is better).	None
bb_rmsd	float | None	Backbone RMSD compared to initial structure (Angstrom).	None
loop	float | None	Fraction of residues in loop conformation.	None
helix	float | None	Fraction of residues in helix conformation.	None
sheet	float | None	Fraction of residues in sheet conformation.	None
liability_score	float | None	Liability score (lower is better).	None
liability_num_violations	int | None	Number of liability violations.	None
liability_high_severity_violations	int | None	Number of high-severity liability violations.	None
min_interaction_pae	float | None	Minimum predicted aligned error at the interface.	None
delta_sasa_refolded	float | None	Change in solvent-accessible surface area upon binding (A^2).	None
plip_hbonds_refolded	int | None	Number of hydrogen bonds at the interface.	None
plip_saltbridge_refolded	int | None	Number of salt bridges at the interface.	None
num_tokens	int | None	Number of tokens in the design.	None
design_hydrophobicity	float | None	Hydrophobicity of the designed binder.	None
num_filters_passed	int | None	Number of quality filters passed.	None

ProteinBinder dataclass

ProteinBinder(bound_structure_uuid=None, sequence=None, scores=None)

Generated protein binder design.

Parameters:

Name	Type	Description	Default
bound_structure_uuid	str | None	UUID of the bound structure (binder + target complex).	None
sequence	str | None	Amino acid sequence of the designed binder.	None
scores	BinderScores | None	Detailed scores for the binder design.	None

iptm property

iptm

Interface predicted TM-score (0-1, higher is better).

quality_score property

quality_score

Overall quality score (0-1, higher is better).

ProteinBinderDesignResult dataclass

ProteinBinderDesignResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a protein-binder-design workflow.

generated_binders property

generated_binders

Generated protein binder designs, sorted by quality score.

messages property

messages

Any messages or warnings from the workflow.

submit_protein_binder_design_workflow

submit_protein_binder_design_workflow(
    binder_design_input,
    protocol=BinderProtocol.PROTEIN_ANYTHING,
    num_designs=10,
    budget=2,
    name="Protein Binder Design Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a protein-binder-design workflow to the API.

Parameters:

Name	Type	Description	Default
binder_design_input	dict[str, Any]	Input specification for the binder design (BoltzGenInput format).	required
protocol	BinderProtocol | str	Design protocol to use. Options: - PROTEIN_ANYTHING: Design a protein binder - PEPTIDE_ANYTHING: Design a peptide binder - PROTEIN_SMALL_MOLECULE: Design a protein that binds a small molecule - NANOBODY_ANYTHING: Design a nanobody binder	PROTEIN_ANYTHING
num_designs	int	Number of designs to generate.	10
budget	int	Number of designs to return in the final diversity-optimized set.	2
name	str	Name of the workflow.	'Protein Binder Design Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If protocol is not a valid BinderProtocol.
requests.HTTPError	if the request to the API fails.

Protein Cofolding

Protein cofolding workflow - predict protein-protein and protein-ligand complexes.

CofoldingScores dataclass

CofoldingScores(ptm=None, iptm=None, avg_lddt=None, confidence_score=None)

Confidence scores for a cofolding prediction.

Parameters:

Name	Type	Description	Default
ptm	float | None	Predicted TM-score (0-1, higher is better).	None
iptm	float | None	Interface predicted TM-score (0-1, higher is better).	None
avg_lddt	float | None	Average per-residue LDDT confidence (0-1).	None
confidence_score	float | None	Overall confidence score (0-1).	None

AffinityScore dataclass

AffinityScore(
    pred_value=None,
    pred_value1=None,
    pred_value2=None,
    probability_binary=None,
    probability_binary1=None,
    probability_binary2=None,
)

Predicted binding affinity scores.

Parameters:

Name	Type	Description	Default
pred_value	float | None	Predicted binding affinity (ensemble average).	None
pred_value1	float | None	Predicted binding affinity (model 1).	None
pred_value2	float | None	Predicted binding affinity (model 2).	None
probability_binary	float | None	Probability of binding (ensemble average, 0-1).	None
probability_binary1	float | None	Probability of binding (model 1, 0-1).	None
probability_binary2	float | None	Probability of binding (model 2, 0-1).	None

CofoldingResult dataclass

CofoldingResult(
    scores=None,
    affinity_score=None,
    strain=None,
    posebusters_valid=None,
    lddt=None,
    pose_uuid=None,
    predicted_structure_uuid=None,
    predicted_refined_structure_uuid=None,
)

Single cofolding prediction result.

Parameters:

Name	Type	Description	Default
scores	CofoldingScores | None	Confidence scores for the prediction.	None
affinity_score	AffinityScore | None	Predicted binding affinity (if computed).	None
strain	float | None	Ligand strain energy (if computed).	None
posebusters_valid	bool | None	Whether the pose passes PoseBusters validation.	None
lddt	list[float] | None	Per-residue LDDT confidence scores.	None
pose_uuid	str | None	UUID of the pose.	None
predicted_structure_uuid	str | None	UUID of the predicted structure.	None
predicted_refined_structure_uuid	str | None	UUID of the refined structure (if refinement was run).	None

ProteinCofoldingResult dataclass

ProteinCofoldingResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a protein-cofolding workflow.

scores property

scores

Confidence scores for the primary prediction.

affinity_score property

affinity_score

Predicted binding affinity for the primary prediction.

strain property

strain

Ligand strain energy for the primary prediction.

posebusters_valid property

posebusters_valid

Whether the primary pose passes PoseBusters validation.

lddt property

lddt

Per-residue LDDT confidence scores for the primary prediction.

predicted_structure_uuid property

predicted_structure_uuid

UUID of the predicted structure.

predicted_refined_structure_uuid property

predicted_refined_structure_uuid

UUID of the refined structure (if pose refinement was enabled).

predictions property

predictions

All cofolding predictions.

cofolding_results property

cofolding_results

Alias for predictions (matches API response field name).

messages property

messages

Any messages or warnings from the workflow (e.g., stereochemistry issues).

get_predicted_structure

get_predicted_structure()

Fetch the predicted structure as a Protein object.

.. note:: Makes one API call on first access. Results are cached. Call clear_cache() to refresh.

get_refined_structure

get_refined_structure()

Fetch the refined structure as a Protein object (if available).

.. note:: Makes one API call on first access. Results are cached. Call clear_cache() to refresh.

_make_cofolding_scores staticmethod

_make_cofolding_scores(s)

Convert cofolding scores data to CofoldingScores dataclass.

_make_affinity_score staticmethod

_make_affinity_score(a)

Convert affinity score data to AffinityScore dataclass.

submit_protein_cofolding_workflow

submit_protein_cofolding_workflow(
    initial_protein_sequences=None,
    initial_dna_sequences=None,
    initial_rna_sequences=None,
    initial_smiles_list=None,
    ligand_binding_affinity_index=None,
    use_msa_server=True,
    use_potentials=False,
    compute_strain=False,
    do_pose_refinement=False,
    name="Protein-Ligand Co-Folding",
    model=CofoldingModel.BOLTZ_2,
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a protein-cofolding workflow to the API.

Predicts the 3D structure of protein-protein, protein-ligand, protein-DNA, protein-RNA, or other biomolecular complexes.

Parameters:

Name	Type	Description	Default
initial_protein_sequences	list[str] | None	Protein sequences to be cofolded.	None
initial_dna_sequences	list[str] | None	DNA sequences to be cofolded.	None
initial_rna_sequences	list[str] | None	RNA sequences to be cofolded.	None
initial_smiles_list	list[str] | None	List of SMILES strings for the ligands to be cofolded with.	None
ligand_binding_affinity_index	int | None	Index of the ligand for which to compute the binding affinity.	None
use_msa_server	bool	Whether to use the MSA server for the computation.	True
use_potentials	bool	Whether to use potentials for the computation.	False
compute_strain	bool	Whether to compute the strain of the pose (if pose_refinement is enabled).	False
do_pose_refinement	bool	Whether to optimize non-rotatable bonds in output poses.	False
name	str	Name of the workflow.	'Protein-Ligand Co-Folding'
model	CofoldingModel | str	Model to use for the computation.	BOLTZ_2
folder_uuid	str | None	UUID of the folder to store the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If no protein, DNA, or RNA sequences are provided.
requests.HTTPError	if the request to the API fails.

Protein MD

Protein MD workflow - molecular dynamics simulations for proteins.

ProteinMDResult dataclass

ProteinMDResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a Protein Molecular Dynamics (MD) workflow.

trajectory_uuids property

trajectory_uuids

UUIDs of all trajectory calculations.

minimized_protein_uuid property

minimized_protein_uuid

UUID of the energy-minimized protein structure.

bonds property

bonds

Bond connectivity as pairs of atom indices.

messages property

messages

Any messages or warnings from the workflow.

get_minimized_protein

get_minimized_protein()

Fetch the energy-minimized protein structure.

.. note:: Makes one API call on first access. Results are cached. Call clear_cache() to refresh.

Returns:

Type	Description
Protein | None	Protein object or None if not available.

download_trajectories

download_trajectories(replicates, name=None, path=None)

Download DCD trajectory files for specified replicates.

Parameters:

Name	Type	Description	Default
replicates	list[int]	List of replicate indices to download.	required
name	str | None	Custom name for the tar.gz file (without extension).	None
path	Path | str | None	Directory to save the file to. Defaults to current directory.	None

Returns:

Type	Description
Path	Path to the downloaded tar.gz file.

Raises:

Type	Description
HTTPError	If the API request fails.

submit_protein_md_workflow

submit_protein_md_workflow(
    protein,
    num_trajectories=4,
    equilibration_time_ns=1,
    simulation_time_ns=10,
    temperature=300,
    pressure_atm=1.0,
    langevin_timescale_ps=1.0,
    timestep_fs=2,
    constrain_hydrogens=True,
    nonbonded_cutoff=8.0,
    ionic_strength_M=0.1,
    water_buffer=6.0,
    save_solvent=False,
    validate_forcefield=True,
    name="Protein MD Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a Protein Molecular Dynamics (MD) workflow to the API.

Parameters:

Name	Type	Description	Default
protein	str | Protein	holo protein on which MD will be run. Can be input as a UUID or a Protein object.	required
num_trajectories	int	Number of trajectories to run.	4
equilibration_time_ns	float	how long to equilibrate trajectories for, in ns	1
simulation_time_ns	float	how long to run trajectories for, in ns	10
temperature	float	temperature, in K	300
pressure_atm	float	pressure, in atm	1.0
langevin_timescale_ps	float	timescale for the Langevin integrator, in ps^-1	1.0
timestep_fs	float	timestep, in femtoseconds	2
constrain_hydrogens	bool	whether or not to use SHAKE to freeze bonds to hydrogen	True
nonbonded_cutoff	float	nonbonded cutoff for particle-mesh Ewald, in A	8.0
ionic_strength_M	float	ionic strength of the solution, in M (molar)	0.1
water_buffer	float	amount of water to add around the protein, in A	6.0
save_solvent	bool	whether solvent should be saved	False
validate_forcefield	bool	if True (default), validate the protein forcefield compatibility before submitting. Raises an error early if the protein cannot be parameterized or has clashing residues.	True
name	str	Name of the workflow.	'Protein MD Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

RBFE Graph

RBFE graph workflow - build perturbation graphs for relative binding free energy calculations.

RelativeBindingFreeEnergyGraphEdge dataclass

RelativeBindingFreeEnergyGraphEdge(
    ligand_a,
    ligand_b,
    core=None,
    score=None,
    ddg=None,
    ddg_err=None,
    complex_dg=None,
    complex_dg_err=None,
    solvent_dg=None,
    solvent_dg_err=None,
    vacuum_dg=None,
    vacuum_dg_err=None,
    failed=False,
    complex_lambda_values=None,
    complex_overlap_matrix=None,
)

An edge in an RBFE perturbation graph.

RelativeBindingFreeEnergyGraphResult dataclass

RelativeBindingFreeEnergyGraphResult(
    workflow_data, workflow_type, workflow_uuid, eager=True
)

Bases: WorkflowResult

Result from an RBFE graph construction workflow.

ligands property

ligands

Ligand molecules keyed by identifier.

graph property

graph

The constructed RBFE perturbation graph as a dict, or None if not yet computed.

Pass directly to submit_rbfe_perturbation_workflow(graph=...).

edges property

edges

Graph edges. Empty list if graph is not yet built.

submit_relative_binding_free_energy_graph_workflow

submit_relative_binding_free_energy_graph_workflow(
    ligands,
    mode="greedy",
    hub_compound_id=None,
    greedy_scoring="best",
    greedy_k_min_cut=3,
    refine_cutoff=None,
    name="RBFE Graph",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits an RBFE graph construction workflow to the API.

Builds a perturbation graph connecting ligands for relative binding free energy (RBFE) calculations.

Parameters:

Name	Type	Description	Default
ligands	dict[str, MoleculeInput]	Dictionary mapping ligand identifiers to molecules.	required
mode	Literal['greedy', 'star_map']	Graph construction strategy: "greedy" or "star_map".	'greedy'
hub_compound_id	str | None	Ligand identifier for the hub when mode="star_map".	None
greedy_scoring	Literal['best', 'jaccard', 'dummy_atoms']	Edge scoring heuristic for greedy mode: "best", "jaccard", or "dummy_atoms".	'best'
greedy_k_min_cut	int	Target edge-connectivity for greedy augmentation. Must be > 0.	3
refine_cutoff	float | None	Optional MCS similarity cutoff for graph refinement.	None
name	str	Name of the workflow.	'RBFE Graph'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If both folder and folder_uuid are provided.
requests.HTTPError	if the request to the API fails.

Relative Binding Free Energy Perturbation

RBFE perturbation workflow - run relative binding free energy FEP simulations.

RelativeBindingFreeEnergyResult dataclass

RelativeBindingFreeEnergyResult(dg, dg_err)

Aggregate RBFE outcome for a single ligand.

Parameters:

Name	Type	Description	Default
dg	float	Predicted binding free energy difference (kcal/mol).	required
dg_err	float	Uncertainty estimate on dg.	required

RelativeBindingFreeEnergyDiagnostics dataclass

RelativeBindingFreeEnergyDiagnostics(
    cycle_closure_rms, windows_completed, windows_failed
)

Quality-control metrics from an RBFE simulation.

Parameters:

Name	Type	Description	Default
cycle_closure_rms	float | None	RMS error across completed thermodynamic cycles.	required
windows_completed	int | None	Count of successfully converged lambda windows.	required
windows_failed	int | None	Count of failed lambda windows.	required

RelativeBindingFreeEnergyPerturbationResult dataclass

RelativeBindingFreeEnergyPerturbationResult(
    workflow_data, workflow_type, workflow_uuid, eager=True
)

Bases: WorkflowResult

Result from a relative binding free energy perturbation workflow.

ligands property

ligands

Ligand molecules keyed by identifier.

edges property

edges

Graph edges with per-edge FEP results.

ligand_dg_results property

ligand_dg_results

Per-ligand binding free energy results, or None if not yet computed.

diagnostics property

diagnostics

Aggregate QC metrics from the FEP simulation.

download_edge_trajectories

download_edge_trajectories(edge_index, lambda_vals=None, path=None, name=None)

Download DCD trajectory files for a specific perturbation edge.

Parameters:

Name	Type	Description	Default
edge_index	int	Index of the edge (0-based, matching edges order).	required
lambda_vals	list[float] | None	Lambda values to download. Defaults to all windows.	None
path	Path | str | None	Directory to save the file to. Defaults to current directory.	None
name	str | None	Custom name for the tar.gz file (without extension).	None

Returns:

Type	Description
Path	Path to the downloaded tar.gz file.

Raises:

Type	Description
IndexError	If edge_index is out of range.
HTTPError	If the API request fails.

download_all_trajectories

download_all_trajectories(path=None)

Download DCD trajectory files for all perturbation edges.

Parameters:

Name	Type	Description	Default
path	Path | str | None	Directory to save the files to. Defaults to current directory.	None

Returns:

Type	Description
list[Path]	List of paths to the downloaded tar.gz files, one per edge.

Raises:

Type	Description
HTTPError	If any API request fails.

submit_relative_binding_free_energy_perturbation_workflow

submit_relative_binding_free_energy_perturbation_workflow(
    graph_result,
    protein,
    tmd_settings="recommended",
    forcefield="off_sage_2_0_0",
    charge_method=None,
    n_eq_steps=None,
    n_frames=None,
    steps_per_frame=400,
    n_windows=None,
    min_overlap=None,
    target_overlap=None,
    water_sampling_padding=0.4,
    rest_max_temperature_scale=1.0,
    rest_temperature_scale_interpolation="exponential",
    local_md_steps=None,
    local_md_k=10000.0,
    local_md_radius=1.2,
    local_md_free_reference=False,
    legs=None,
    save_trajectories=False,
    trajectory_save_interval=1000,
    validate_forcefield=True,
    name="RBFE Perturbation",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a relative binding free energy perturbation (RBFE) workflow to the API.

Runs FEP simulations along edges of the perturbation graph to predict relative binding free energies between ligands.

Preset settings (any individual param overrides the tmd_settings): - "fast": fewer windows/steps for quick screening (NAGL charges). - "recommended" (default): balanced speed and accuracy (NAGL charges). - "rigorous": same as recommended but disables local MD for higher accuracy.

Parameters:

Name	Type	Description	Default
graph_result	RelativeBindingFreeEnergyGraphResult	Completed RelativeBindingFreeEnergyGraphResult.	required
protein	str | Protein	Protein target, as a UUID string or Protein object.	required
tmd_settings	Literal['fast', 'recommended', 'rigorous']	Starting settings profile. Individual params override this.	'recommended'
forcefield	Literal['off_sage_2_0_0', 'off_sage_2_2_1']	Force field for the simulation (e.g. "off_sage_2_0_0").	'off_sage_2_0_0'
charge_method	Literal['amber_am1bcc', 'nagl'] | None	Method for computing partial charges.	None
n_eq_steps	int | None	Equilibration steps per lambda window.	None
n_frames	int | None	Production frames saved per lambda window.	None
steps_per_frame	int	MD integration steps per saved frame.	400
n_windows	int | None	Maximum number of lambda windows considered for bisection.	None
min_overlap	float | None	Minimum acceptable overlap during schedule bisection.	None
target_overlap	float | None	Desired overlap after HREX optimization.	None
water_sampling_padding	float	Extra nanometers added to the solvent sampling radius.	0.4
rest_max_temperature_scale	float	Maximum effective temperature scaling for REST.	1.0
rest_temperature_scale_interpolation	Literal['exponential', 'linear']	Functional form used for REST scaling.	'exponential'
local_md_steps	int | None	Number of local MD steps per frame (0 disables local MD).	None
local_md_k	float	Spring constant used during local MD.	10000.0
local_md_radius	float	Sphere radius in nanometers for the local MD region.	1.2
local_md_free_reference	bool	Whether to free the reference frame during local MD.	False
legs	list[Literal['vacuum', 'solvent', 'complex']] | None	Which thermodynamic cycle legs to run.	None
save_trajectories	bool	Whether to save DCD trajectories.	False
trajectory_save_interval	int	Save every Nth frame when saving trajectories.	1000
validate_forcefield	bool	If True (default), validate protein forcefield compatibility before submitting.	True
name	str	Name of the workflow.	'RBFE Perturbation'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If graph_result has no graph or both folder and folder_uuid are provided.
requests.HTTPError	if the request to the API fails.

Redox Potential

Redox potential workflow - calculate oxidation/reduction potentials.

RedoxPotentialResult dataclass

RedoxPotentialResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a redox-potential workflow.

oxidation_potential property

oxidation_potential

Oxidation potential in V (vs SHE).

reduction_potential property

reduction_potential

Reduction potential in V (vs SHE).

neutral_molecule_uuid property

neutral_molecule_uuid

UUID of the optimized neutral molecule calculation.

cation_molecule_uuid property

cation_molecule_uuid

UUID of the optimized cation (oxidized) molecule calculation.

anion_molecule_uuid property

anion_molecule_uuid

UUID of the optimized anion (reduced) molecule calculation.

messages property

messages

Any messages or warnings from the workflow.

get_neutral_molecule

get_neutral_molecule()

Fetch the optimized neutral molecule calculation.

get_cation_molecule

get_cation_molecule()

Fetch the optimized cation (oxidized) molecule calculation.

get_anion_molecule

get_anion_molecule()

Fetch the optimized anion (reduced) molecule calculation.

submit_redox_potential_workflow

submit_redox_potential_workflow(
    initial_molecule,
    reduction=False,
    oxidation=True,
    mode=Mode.RAPID,
    name="Redox Potential Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a redox-potential workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to calculate the redox potential of.	required
reduction	bool	Whether to calculate the reduction potential.	False
oxidation	bool	Whether to calculate the oxidation potential.	True
mode	Mode	Mode to run the calculation in.	RAPID
name	str	Name of the workflow.	'Redox Potential Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Scan

Scan workflow - perform potential energy surface scans.

ScanResult dataclass

ScanResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a scan workflow.

scan_point_uuids property

scan_point_uuids

UUIDs of scan point calculations.

scan_points property

scan_points

All scan point calculations.

.. note:: Makes one API call per scan point on first access. Results are cached. Call clear_cache() to refresh.

messages property

messages

Any messages or warnings from the workflow.

get_energies

get_energies(relative=False)

Get scan coordinate values paired with energies.

Parameters:

Name	Type	Description	Default
relative	bool	If True, return relative energies in kcal/mol (relative to the lowest energy point). If False (default), return absolute energies in Hartree.	False

Returns:

Type	Description
list[tuple[float, float | None]]	List of (coordinate, energy) tuples. Coordinate is the scanned value (e.g., bond distance in Angstrom, angle in degrees).

submit_scan_workflow

submit_scan_workflow(
    initial_molecule,
    scan_settings=None,
    calculation_engine=None,
    calculation_method="uma_m_omol",
    wavefront_propagation=True,
    name="Scan Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a scan workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to scan.	required
scan_settings	ScanSettings | dict[str, Any] | None	Scan settings.	None
calculation_engine	str | None	Engine to use for the calculation.	None
calculation_method	Method | str	Method to use for the calculation.	'uma_m_omol'
wavefront_propagation	bool	Whether to use wavefront propagation in the scan.	True
name	str	Name of the workflow.	'Scan Workflow'
folder_uuid	str | None	UUID of the folder to store the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

Solubility

Solubility workflow - predict molecular solubility in various solvents.

SolubilityValue dataclass

SolubilityValue(temperature, solubility, uncertainty=None)

Solubility measurement at a specific temperature.

Parameters:

Name	Type	Description	Default
temperature	float	Temperature in Kelvin.	required
solubility	float	Solubility in log(mol/L).	required
uncertainty	float | None	Uncertainty in the solubility prediction.	None

SolubilityEntry dataclass

SolubilityEntry(solvent, values)

Solubility results for a single solvent.

Parameters:

Name	Type	Description	Default
solvent	str	Solvent SMILES.	required
values	tuple[SolubilityValue, ...]	Solubility values at each temperature.	required

SolubilityResult dataclass

SolubilityResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from an aqueous-solubility workflow.

solubilities property

solubilities

Solubility results per solvent, with each value paired to its temperature.

_resolve_solvent

_resolve_solvent(solvent)

Convert a solvent name or SMILES to SMILES.

Parameters:

Name	Type	Description	Default
solvent	str	Solvent name (e.g., "ethanol") or SMILES (e.g., "CCO").	required

Returns:

Type	Description
str	SMILES string.

Raises:

Type	Description
ValueError	If solvent is not a recognized name or valid SMILES.

submit_solubility_workflow

submit_solubility_workflow(
    initial_smiles,
    method="fastsolv",
    solvents=None,
    temperatures=None,
    name="Solubility Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a solubility workflow to the API.

Parameters:

Name	Type	Description	Default
initial_smiles	str | MoleculeInput	Molecule to calculate solubility for. Accepts a SMILES string or any molecule type (RowanMolecule, stjames.Molecule, RDKit Mol, or dict). The molecule must have a SMILES string associated with it, as solubility models are 2D/SMILES-based and do not use 3D coordinates.	required
method	Literal['fastsolv', 'kingfisher', 'esol']	Solubility prediction method: - "fastsolv": ML-based solid solubility. Supports arbitrary solvents and temperatures. - "kingfisher": ML-based aqueous solubility. Water only, 298.15K only. - "esol": ESOL regression for aqueous solubility. Water only, 298.15K only.	'fastsolv'
solvents	list[str] | None	List of solvent names or SMILES. Common names like "ethanol", "water", "thf" are recognized (see COMMON_SOLVENTS). For fastsolv, any solvent SMILES is accepted. For kingfisher/esol, must be ["water"] or ["O"].	None
temperatures	list[float] | None	List of temperatures in Kelvin. For fastsolv, any temperatures. For kingfisher/esol, must be [298.15] (room temperature).	None
name	str	Name of the workflow.	'Solubility Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If the molecule has no SMILES, or solvents/temperatures are incompatible with the method.
requests.HTTPError	If the request to the API fails.

Solvent-Dependent Conformers

Solvent-dependent conformers workflow - conformer search with multi-solvent scoring.

SolventDependentConformerProperties dataclass

SolventDependentConformerProperties(
    solvent_accessible_surface_area,
    polar_solvent_accessible_surface_area,
    radius_of_gyration,
)

Conformer ensemble properties for a single solvent.

Parameters:

Name	Type	Description	Default
solvent_accessible_surface_area	float	Average SASA (A^2).	required
polar_solvent_accessible_surface_area	float	Average polar SASA for non-C/H atoms (A^2).	required
radius_of_gyration	float	Radius of gyration (A).	required

SolventDependentConformer dataclass

SolventDependentConformer(
    calculation_uuid,
    free_energy_by_solvent,
    relative_free_energy_by_solvent,
    population_by_solvent,
)

A single conformer scored across multiple solvents.

Parameters:

Name	Type	Description	Default
calculation_uuid	str	UUID of the underlying calculation.	required
free_energy_by_solvent	dict[Solvent, float]	Absolute free energy per solvent (Hartree).	required
relative_free_energy_by_solvent	dict[Solvent, float]	Free energy relative to lowest conformer per solvent (kcal/mol).	required
population_by_solvent	dict[Solvent, float]	Boltzmann population per solvent (0-1).	required

SolventDependentConformersResult dataclass

SolventDependentConformersResult(
    workflow_data, workflow_type, workflow_uuid, eager=True
)

Bases: WorkflowResult

Result from a solvent-dependent conformers workflow.

num_conformers property

num_conformers

Number of conformers found.

solvents property

solvents

Solvents used for scoring.

conformers property

conformers

Conformers with per-solvent energies and populations.

per_solvent_properties property

per_solvent_properties

Aggregate ensemble properties per solvent (SASA, polar SASA, radius of gyration).

relative_free_energy_by_solvent property

relative_free_energy_by_solvent

Relative transfer free energy by solvent (kcal/mol).

submit_solvent_dependent_conformers_workflow

submit_solvent_dependent_conformers_workflow(
    initial_molecule,
    solvents=None,
    conf_gen_settings=None,
    energy_window=30,
    name="Solvent-Dependent Conformers",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a solvent-dependent conformers workflow to the API.

Generates conformers and scores them across multiple solvents using CPCM-X, enabling prediction of solvent-dependent conformer populations and transfer free energies. The input molecule must have 3D coordinates.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule with 3D coordinates to perform the conformer search on.	required
solvents	list[Solvent] | None	Solvents to score conformers in (rowan.Solvent enum). Defaults to hexane, octanol, chloroform, DMSO, and water.	None
conf_gen_settings	ConformerGenSettingsUnion | None	Conformer generation settings. Defaults to rowan.iMTDSettings with GFN-FF and 30 kcal/mol energy window. Other options: rowan.ETKDGSettings, rowan.iMTDGCSettings, rowan.LyrebirdSettings.	None
energy_window	float	Energy window for conformer generation (kcal/mol). Only used when conf_gen_settings is None.	30
name	str	Name of the workflow.	'Solvent-Dependent Conformers'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If both folder and folder_uuid are provided.
requests.HTTPError	If the request to the API fails.

Spin States

Spin-states workflow - calculate energies of different spin multiplicities.

SpinState dataclass

SpinState(multiplicity, energy, calculation_uuids)

Spin state result.

Parameters:

Name	Type	Description	Default
multiplicity	int	Spin multiplicity (1=singlet, 2=doublet, 3=triplet, etc.).	required
energy	float	Energy in Hartree.	required
calculation_uuids	tuple[str | None, ...]	UUIDs for each optimization stage (for multistage optimization).	required

SpinStatesResult dataclass

SpinStatesResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a spin-states workflow.

spin_states property

spin_states

List of spin states with energies, in submission order.

messages property

messages

Any messages or warnings from the workflow.

get_calculation

get_calculation(multiplicity, stage=-1)

Fetch the calculation for a specific spin state.

.. note:: Makes one API call per spin state on first access. Results are cached. Call clear_cache() to refresh.

Parameters:

Name	Type	Description	Default
multiplicity	int	Spin multiplicity to fetch.	required
stage	int	Optimization stage (-1 for final stage).	-1

Returns:

Type	Description
Calculation	Calculation object with molecule and energy data.

Raises:

Type	Description
ValueError	If the multiplicity is not found or has no calculation.

get_energies

get_energies(relative=False)

Get energies for each spin state.

Parameters:

Name	Type	Description	Default
relative	bool	If True, return relative energies in kcal/mol (relative to the ground state / lowest energy spin state). If False (default), return absolute energies in Hartree.	False

Returns:

Type	Description
list[float]	List of energies for each spin state.

_validate_multiplicity

_validate_multiplicity(mol_dict, multiplicity)

Validate that a spin multiplicity is compatible with the molecule.

Uses stjames.Molecule.check_electron_sanity() for validation.

Parameters:

Name	Type	Description	Default
mol_dict	dict[str, Any]	Molecule dict with atomic_numbers and charge.	required
multiplicity	int	Spin multiplicity to validate.	required

Raises:

Type	Description
ValueError	If multiplicity is invalid for this molecule.

submit_spin_states_workflow

submit_spin_states_workflow(
    initial_molecule,
    states,
    mode=Mode.RAPID,
    solvent=None,
    xtb_preopt=True,
    frequencies=False,
    name="Spin States Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a spin-states workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to calculate spin states for.	required
states	list[int]	List of multiplicities to calculate (e.g., [1, 3, 5] for singlet, triplet, quintet).	required
mode	Mode	Mode to run the calculation in.	RAPID
solvent	SolventInput	Solvent to use for the calculation.	None
xtb_preopt	bool	Whether to pre-optimize with xTB.	True
frequencies	bool	Whether to calculate frequencies.	False
name	str	Name of the workflow.	'Spin States Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
ValueError	If any multiplicity is incompatible with the molecule.
requests.HTTPError	If the request to the API fails.

Strain

Strain workflow - calculate molecular strain energy.

StrainResult dataclass

StrainResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a strain workflow.

strain property

strain

Computed strain energy (kcal/mol).

conformer_uuids property

conformer_uuids

UUIDs of conformer calculations.

constrained_optimization_uuid property

constrained_optimization_uuid

UUID of the constrained optimization calculation.

messages property

messages

Any messages or warnings from the workflow.

constrained_optimization property

constrained_optimization

The constrained optimization calculation.

conformers property

conformers

All conformer calculations.

.. note:: Makes one API call per conformer on first access. Results are cached. Call clear_cache() to refresh.

conformer_energies property

conformer_energies

Energies for all conformers (Hartree).

conformer_molecules property

conformer_molecules

Molecule objects for all conformers.

get_boltzmann_weights

get_boltzmann_weights(temperature=300.0)

Compute Boltzmann weights for conformers.

Parameters:

Name	Type	Description	Default
temperature	float	Temperature in Kelvin (default: 300K).	300.0

Returns:

Type	Description
list[float]	List of weights (sum to 1.0), excluding failed conformers.

submit_strain_workflow

submit_strain_workflow(
    initial_molecule,
    harmonic_constraint_spring_constant=5.0,
    constrain_hydrogens=False,
    conf_gen_settings=None,
    name="Strain Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a strain workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to calculate strain for.	required
harmonic_constraint_spring_constant	float	Spring constant for harmonic constraints (kcal/mol/A). Default 5.0.	5.0
constrain_hydrogens	bool	Whether to constrain hydrogen positions. Default False.	False
conf_gen_settings	ConformerGenSettingsUnion | None	Conformer generation settings. Defaults to ETKDG with max 50 conformers.	None
name	str	Name of the workflow.	'Strain Workflow'
folder_uuid	str | None	UUID of the folder to store the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	If the request to the API fails.

Tautomer Search

Tautomer-search workflow - find tautomeric forms of molecules.

Tautomer dataclass

Tautomer(energy, weight, predicted_relative_energy, structure_uuids)

Tautomer result.

Parameters:

Name	Type	Description	Default
energy	float	Energy in Hartree.	required
weight	float	Boltzmann weight (sum to 1.0 across all tautomers).	required
predicted_relative_energy	float	Relative energy in kcal/mol (relative to lowest energy).	required
structure_uuids	tuple[str, ...]	UUIDs of the structure calculations.	required

TautomerResult dataclass

TautomerResult(workflow_data, workflow_type, workflow_uuid, eager=True)

Bases: WorkflowResult

Result from a tautomer-search workflow.

tautomers property

tautomers

List of tautomers with energies and weights.

messages property

messages

Any messages or warnings from the workflow.

best_tautomer property

best_tautomer

Molecule of the highest Boltzmann-weight tautomer.

molecules property

molecules

Molecules for all tautomers.

.. note:: Makes one API call per tautomer on first access. Results are cached. Call clear_cache() to refresh.

submit_tautomer_search_workflow

submit_tautomer_search_workflow(
    initial_molecule,
    mode=Mode.CAREFUL,
    name="Tautomer Search Workflow",
    folder_uuid=None,
    folder=None,
    max_credits=None,
)

Submits a tautomer-search workflow to the API.

Parameters:

Name	Type	Description	Default
initial_molecule	MoleculeInput	Molecule to find tautomers for.	required
mode	Mode	Mode to run the calculation in (reckless, rapid, careful).	CAREFUL
name	str	Name of the workflow.	'Tautomer Search Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None

Returns:

Type	Description
Workflow	Workflow object representing the submitted workflow.

Raises:

Type	Description
requests.HTTPError	If the request to the API fails.

Folder Class and Functions

Folder

Bases: BaseModel

A class representing a folder in the Rowan API.

Attributes:

Name	Type	Description
uuid	str	The UUID of the folder.
name	str | None	The name of the folder.
parent_uuid	str | None	The UUID of the parent folder.
notes	str	Folder notes.
starred	bool	Whether the folder is starred.
public	bool	Whether the folder is public.
created_at	datetime | None	The date and time the folder was created.

fetch_latest

fetch_latest(in_place=False)

Fetch the latest folder data from the API.

This method refreshes the folder object with the latest data from the API.

Parameters:

Name	Type	Description	Default
in_place	bool	Whether to update the current instance in-place.	False

Returns:

Type	Description
Self	Updated instance (self).

Raises:

Type	Description
HTTPError	If the API request fails.

update

update(name=None, parent_uuid=None, notes=None, starred=None, public=None)

Update a folder.

Parameters:

Name	Type	Description	Default
name	str | None	New name of the folder.	None
parent_uuid	str | None	UUID of the new parent folder.	None
notes	str | None	Description of the folder.	None
starred	bool | None	Whether the folder is starred.	None
public	bool | None	Whether the folder is public.	None

Returns:

Type	Description
Self	Updated folder object.

delete

delete()

Delete the folder and all its contents.

This is a destructive action, it will delete all the folders and workflows that are inside this folder.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

print_folder_tree

print_folder_tree(max_depth=10, show_uuids=False)

Retrieves a folder tree from the API.

Parameters:

Name	Type	Description	Default
max_depth	int	Maximum depth of the folder tree.	10
show_uuids	bool	Whether to show the UUIDs of the folders.	False

Raises:

Type	Description
HTTPError	If the API request fails.

retrieve_folder

retrieve_folder(uuid)

Retrieves a folder from the API by UUID. Folder UUID can be found in the folder's URL.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the folder to retrieve.	required

Returns:

Type	Description
Folder	Folder object representing the retrieved folder.

Raises:

Type	Description
HTTPError	If the API request fails.

list_folders

list_folders(
    parent_uuid=None, name_contains=None, public=None, starred=None, page=0, size=10
)

Retrieve a list of folders based on the specified criteria.

Parameters:

Name	Type	Description	Default
parent_uuid	str | None	UUID of the parent folder to filter by.	None
name_contains	str | None	Substring to search for in folder names.	None
public	bool | None	Filter folders by their public status.	None
starred	bool | None	Filter folders by their starred status.	None
page	int	Pagination parameter to specify the page number.	0
size	int	Pagination parameter to specify the number of items per page.	10

Returns:

Type	Description
list[Folder]	List of Folder objects that match the search criteria.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

create_folder

create_folder(name, parent_uuid=None, notes='', starred=False, public=False)

Create a new folder.

Parameters:

Name	Type	Description	Default
name	str	Name of the folder.	required
parent_uuid	str | None	UUID of the parent folder.	None
notes	str	Description of the folder.	''
starred	bool	Whether the folder is starred.	False
public	bool	Whether the folder is public.	False

Returns:

Type	Description
Folder	Newly created folder.

get_folder

get_folder(path, create=True)

Get a folder by name or nested path within the default project.

This is the easiest way to get a folder to use as a location for calculations. By default, any missing folders along the path are created automatically.

Example::

folder = rowan.get_folder("CDK2/docking/batch_1")
workflow = rowan.submit_docking_workflow(..., folder_uuid=folder.uuid)

Parameters:

Name	Type	Description	Default
path	str	Folder name or /-separated path, e.g. "project/subdir/run1".	required
create	bool	If True (default), create missing folders. If False, raise ValueError if any segment is not found.	True

Returns:

Type	Description
Folder	The deepest :class:Folder in the path.

Raises:

Type	Description
ValueError	If the path is empty, or create=False and a folder is not found.

print_folder_tree

print_folder_tree(uuid, max_depth=10, show_uuids=False)

Retrieves a folder tree from the API.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the root of the folder tree.	required
max_depth	int	Maximum depth of the folder tree.	10
show_uuids	bool	Whether to show the UUIDs of the folders.	False

Raises:

Type	Description
HTTPError	If the API request fails.

User Class and Functions

Organization

Bases: BaseModel

A Rowan organization

Attributes:

Name	Type	Description
name	str	The name of the organization.
weekly_credits	float | None	The weekly credits of the organization.
credits	float | None	The credits of the organization.

OrganizationRole

Bases: BaseModel

A Rowan organization role

Attributes:

Name	Type	Description
name	str	The name of the organization role.

SubscriptionPlan

Bases: BaseModel

A Rowan subscription plan

Attributes:

Name	Type	Description
name	str	The name of the subscription plan.

IndividualSubscription

Bases: BaseModel

A Rowan individual subscription

Attributes:

Name	Type	Description
subscription_plan	SubscriptionPlan	The subscription plan of the individual subscription.

User

Bases: BaseModel

A Rowan user

Attributes:

Name	Type	Description
uuid	str	The UUID of the user.
username	str	The username of the user.
email	str	The email of the user.
firstname	str | None	The first name of the user.
lastname	str | None	The last name of the user.
weekly_credits	float | None	The weekly credits of the user.
credits	float | None	The credits of the user.
billing_name	str | None	The billing name of the user.
billing_address	str | None	The billing address of the user.
credit_balance_warning	float | None	The credit balance warning of the user.
organization	Organization | None	The organization of the user.
organization_role	OrganizationRole | None	The organization role of the user.
individual_subscription	IndividualSubscription | None	The individual subscription of the user.

credits_available_string

credits_available_string()

Returns a string showing available credits, including organization credits if applicable

Returns:

Type	Description
str	String showing available credits

whoami

whoami()

Returns the current user

Protein Class and Functions

Protein

Bases: BaseModel

A Rowan protein.

Data is not loaded by default to avoid unnecessary downloads that could impact performance. Call load_data() to fetch and attach the protein data to this Protein object.

Attributes:

Name	Type	Description
uuid	str	The UUID of the protein
created_at	datetime | None	The creation date of the protein
used_in_workflow	bool | None	Whether the protein is used in a workflow
ancestor_uuid	str | None	The UUID of the ancestor protein
sanitized	int | None	Whether the protein is sanitized
name	str | None	The name of the protein
data	dict | None	The data of the protein
public	bool | None	Whether the protein is public

refresh

refresh(in_place=True)

Loads protein data

Returns:

Type	Description
Self	protein with loaded data

update

update(name=None, data=None, public=None, pocket=None)

Updates protein data

Parameters:

Name	Type	Description	Default
name	str | None	New name of the protein	None
data	dict | None	New data of the protein	None
public	bool | None	Whether the protein is public	None
pocket	list[list[float]] | None	New pocket of the protein	None

Returns:

Type	Description
Self	Updated protein object

delete

delete()

Deletes a protein

Raises:

Type	Description
requests.HTTPError	if the request to the API fails

sanitize

sanitize(poll_interval=10.0, timeout=300.0)

Sanitizes a protein and waits for the process to complete.

Protein sanitization runs asynchronously on the server. This method submits the request then polls until sanitization succeeds, fails, or times out.

Parameters:

Name	Type	Description	Default
poll_interval	float	Seconds between status checks (default 10).	10.0
timeout	float	Maximum seconds to wait before raising (default 300).	300.0

Raises:

Type	Description
RuntimeError	if sanitization fails, is stopped, or times out.
requests.HTTPError	if any API request fails.

prepare

prepare(
    find_missing_residues=True,
    add_missing_atoms=True,
    remove_heterogens=True,
    keep_waters=False,
    remove_hydrogens=False,
    remove_invalid_hydrogens=False,
    add_hydrogens=True,
    add_hydrogen_ph=7.0,
    optimize_hydrogens=True,
    poll_interval=10.0,
    timeout=300.0,
)

Prepare a protein for simulation and waits for the process to complete.

Runs PDBFixer to fix nonstandard residues, add missing atoms/hydrogens, and optionally optimizes hydrogen positions with OpenMM. This is the recommended method for preparing proteins before MD or RBFE workflows.

Parameters:

Name	Type	Description	Default
find_missing_residues	bool	Identify and model missing residues.	True
add_missing_atoms	bool	Add missing heavy atoms to residues.	True
remove_heterogens	bool	Remove ligands, salts, and other heterogens.	True
keep_waters	bool	Preserve water molecules when removing heterogens.	False
remove_hydrogens	bool	Remove all existing hydrogens before adding new ones.	False
remove_invalid_hydrogens	bool	Remove hydrogens not matching the forcefield template.	False
add_hydrogens	bool	Add missing hydrogen atoms.	True
add_hydrogen_ph	float	pH used to determine protonation states when adding hydrogens.	7.0
optimize_hydrogens	bool	Optimize hydrogen positions with OpenMM energy minimization.	True
poll_interval	float	Seconds between status checks (default 10).	10.0
timeout	float	Maximum seconds to wait before raising (default 300).	300.0

Raises:

Type	Description
RuntimeError	If preparation fails, is stopped, or times out.
requests.HTTPError	If any API request fails.

validate_protein_forcefield

validate_protein_forcefield()

Validate that this protein can be parameterized with the MD forcefield.

Calls the server-side validation which checks that all residues are recognized by OpenMM and that there are no clashing atoms. Call this before submitting any MD workflow to catch preparation issues early.

If validation fails, try re-preparing with remove_invalid_hydrogens=True: protein.prepare(remove_invalid_hydrogens=True)

Raises:

Type	Description
requests.HTTPError	if validation fails or the API request fails.

download_pdb_file

download_pdb_file(path=None, name=None)

Downloads the PDB file for a protein

Parameters:

Name	Type	Description	Default
path	Path | str | None	Directory to save the file to (defaults to current directory)	None
name	str | None	Optional custom name for the file (defaults to protein name)	None

Raises:

Type	Description
requests.HTTPError	if the request to the API fails

retrieve_protein

retrieve_protein(uuid)

Retrieves a protein from the API using its UUID.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the protein to retrieve.	required

Returns:

Type	Description
Protein	Protein object representing the retrieved protein.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

list_proteins

list_proteins(ancestor_uuid=None, name_contains=None, page=0, size=20)

List proteins

Parameters:

Name	Type	Description	Default
ancestor_uuid	str | None	UUID of the ancestor protein to filter by	None
name_contains	str | None	Substring to search for in protein names	None
page	int	Page number to retrieve	0
size	int	Number of items per page	20

Returns:

Type	Description
list[Protein]	List of Protein objects that match the search criteria

Raises:

Type	Description
requests.HTTPError	if the request to the API fails

upload_protein

upload_protein(name, file_path, project_uuid=None)

Uploads a protein from a PDB file to the API.

Parameters:

Name	Type	Description	Default
name	str	Name of the protein to create	required
file_path	Path	Path to the PDB file to upload	required

Returns:

Type	Description
Protein	Protein object representing the uploaded protein

Raises:

Type	Description
requests.HTTPError	if the request to the API fails

create_protein_from_pdb_id

create_protein_from_pdb_id(name, code, project_uuid=None)

Creates a protein from a PDB ID.

Parameters:

Name	Type	Description	Default
name	str	Name of the protein to create	required
code	str	PDB ID of the protein to create	required
project_uuid	str | Project | None	UUID of the project to create the protein in	None

Returns:

Type	Description
Protein	Protein object representing the created protein

Raises:

Type	Description
requests.HTTPError	if the request to the API fails

Project Class and Functions

Project

Bases: BaseModel

A class representing a project in the Rowan API.

Attributes:

Name	Type	Description
uuid	str	The UUID of the project.
name	str | None	The name of the project.
created_at	datetime | None	The date and time the project was created.

update

update(name=None)

Update a project.

Parameters:

Name	Type	Description	Default
name	str | None	New name of the project.	None

Returns:

Type	Description
Self	Updated project object.

delete

delete()

Delete the project.

This is a destructive action, it will delete all the folders and workflows that are inside this project.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

retrieve_project

retrieve_project(uuid)

Retrieves a project from the API by UUID. Project UUID can be found in the project's URL.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the project to retrieve.	required

Returns:

Type	Description
Project	Project object representing the retrieved project.

Raises:

Type	Description
HTTPError	If the API request fails.

list_projects

list_projects(name_contains=None, page=0, size=10)

Retrieve a list of projects based on the specified criteria.

Parameters:

Name	Type	Description	Default
name_contains	str | None	Substring to search for in project names.	None
page	int	Pagination parameter to specify the page number.	0
size	int	Pagination parameter to specify the number of items per page.	10

Returns:

Type	Description
list[Project]	List of Folder objects that match the search criteria.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.

create_project

create_project(name)

Create a new project.

Parameters:

Name	Type	Description	Default
name	str	Name of the project.	required

Returns:

Type	Description
Project	Newly created project.

set_project

set_project(name)

Set the active project by name for all subsequent API calls.

This is equivalent to setting rowan.project_uuid directly, but lets you use a human-readable name instead of a UUID.

Example::

rowan.set_project("CDK2 campaign")
folder = rowan.get_folder("docking/batch_1")

Parameters:

Name	Type	Description	Default
name	str	Exact name of the project to activate.	required

Returns:

Type	Description
Project	The matched Project.

Raises:

Type	Description
ValueError	If no project with that name is found.

default_project

default_project()

Retrieves the default project from the API.

Returns:

Type	Description
Project	Project object representing the default project.

Raises:

Type	Description
HTTPError	If the API request fails.

Utilities

get_api_key

get_api_key()

Get the API key from the environment variable ROWAN_API_KEY or the module-level attribute rowan.api_key.

If neither of these are set, raise a ValueError with a helpful message.

Returns:

Type	Description
str	API key.

get_project_uuid

get_project_uuid()

Get the active project UUID from the module-level attribute rowan.project_uuid.

Returns:

Type	Description
str | None	Project UUID string, or None if not set.

smiles_to_stjames

smiles_to_stjames(smiles)

Convert a SMILES string to a stjames.Molecule object.

Parameters:

Name	Type	Description	Default
smiles	str	String representing the SMILES notation of the molecule.	required

Returns:

Type	Description
Molecule	stjames.Molecule object created from the given SMILES string.