To get started, install rowan-python from the Python Package Index:
pip install rowan-python
Usage of the Python API requires generation of an API key at labs.rowansci.com. This guide walks through the process of generating a new API key.
Use your API key by assigning it to rowan.api_key:
import rowan
rowan.api_key = "my_secret_api_key"
Equivalently, you can set the environment variable ROWAN_API_KEY:
export ROWAN_API_KEY=my_secret_api_key
Your API keys allow authentication to your account, so keep them secure! Don't store API keys in places where others could access them, like GitHub or shared scripts.
In Rowan, data is stored in the open-source stjames format.
compute APIWorkflows can be submitted using rowan.compute(). This function submits a workflow, automatically monitors its status, and returns the result when complete.
res = rowan.compute(
name="benzene redox",
molecule="c1ccccc1",
workflow_type="redox_potential",
)
print(res["object_data"]["oxidation_potential"]) # 2.7466429
str | cctk.Molecule | stjames.Molecule)The initial molecule for the workflow. Molecules can be specified as a SMILES string, a cctk.Molecule, or a stjames.Molecule.
str)The workflow to run on the molecule.
The name of the workflow.
The folder to submit the calculation to. If left blank, calculations will be submitted into the user's root folder.
bool)Whether or not the function should wait until complete to return. Defaults to True.
int)The interval at which to check calculation status, in seconds. Defaults to 5.
dict)Additional arguments will be passed as workflow-specific parameters.
This object represents a folder in Rowan, which can hold other folders or workflows.
{
"name": "example folder",
"parent_uuid": "64b01a92-e52d-45ac-9768-3cc9430eaa6e",
"notes": "This is a folder",
"starred": false,
"public": false,
"created_at": "2024-09-10T13:58:39.500Z",
"updated_at": "2024-09-10T13:58:39.500Z",
"is_root": false,
"uuid": "6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
}
str)The name of the folder.
str)The UUID of this folder's parent (the folder which contains this folder).
str)Any notes associated with this folder.
bool)Whether or not this folder is starred.
bool)Whether or not this folder is publicly viewable. This will propagate to all contained workflows and folders.
datetime.datetime)The date and time at which this folder was created.
datetime.datetime)The date and time at which this folder was most recently updated.
bool)Whether or not this folder is the user's root folder.
str)The UUID of this folder.
This function creates a new folder and returns the folder object.
rowan.Folder.create(
name="new folder",
parent_uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The name of the folder.
str)The UUID of this folder's parent (the folder which contains this folder).
str)Any notes associated with this folder.
bool)Whether or not this folder is starred.
bool)Whether or not this folder is publicly viewable. This will propagate to all contained workflows and folders.
The folder object.
This function retrieves a folder.
folder = rowan.Folder.retrieve(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The UUID of this folder.
The folder object.
This function updates a folder and returns the new object.
rowan.Folder.update(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
name="renaming this folder",
public=True,
)
str)The UUID of this folder.
str)The name of the folder.
str)The UUID of this folder's parent (the folder which contains this folder).
str)Any notes associated with this folder.
bool)Whether or not this folder is starred.
bool)Whether or not this folder is publicly viewable. This will propagate to all contained workflows and folders.
The new folder object.
This function deletes a folder. This action cannot be undone!
rowan.Folder.delete(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The UUID of this folder.
Nothing.
This function returns all folders that meet specified criteria.
folder_res = rowan.Folder.list(
name_contains="redox",
)
str)Return folders whose name contains a specified string.
str)The UUID of the folders' parent (the folder which contains these folders).
bool)Whether or not the folders are starred.
bool)Whether or not the folders are public.
int)Which page of results to return.
int)How many results to return per page.
list[dict])A list of the folders that match the specified criteria.
int)The total number of pages.
This object represents a workflow in Rowan.
{
"name": "water pka",
"parent_uuid": "824f1db1-e7ff-4d3f-a102-62c365d0fb80",
"notes": "",
"starred": false,
"public": false,
"object_type": "pka",
"object_data": {
"pka_range": [-5, 25],
"deprotonate_elements": ["8"],
"deprotonate_atoms": [],
"protonate_elements": ["8"],
"protonate_atoms": [],
"mode": "careful",
"initial_molecule": {
"charge": 0,
"multiplicity": 1,
"atoms": [
{
"atomic_number": 8,
"position": [-0.011994152329862118, 0.3976341784000397, 0]
},
{
"atomic_number": 1,
"position": [-0.7571237087249756, -0.2218356728553772, 0]
},
{
"atomic_number": 1,
"position": [0.7691178917884827, -0.17579850554466248, 0]
}
],
}
},
"email_when_complete": false,
"created_at": "2024-09-11T14:34:49.085669Z",
"updated_at": null,
"started_at": null,
"completed_at": null,
"uuid": "b834ab26-8533-489c-97a5-bd915f00a6c2",
"elapsed": 0,
"credits_charged": 0,
"object_status": 0,
"object_logfile": "",
"is_free": true
}
str)The name of the workflow.
str)The UUID of this workflow's parent (the folder which contains this workflow).
str)Any notes associated with this workflow.
bool)Whether or not this workflow is starred.
bool)Whether or not this workflow is publicly viewable.
datetime.datetime)The date and time at which this workflow was created.
datetime.datetime)The date and time at which this workflow was most recently updated.
datetime.datetime | None)The date and time at which this workflow started running.
datetime.datetime | None)The date and time at which this workflow finished.
bool)Whether or not this workflow was free.
str)The UUID of this workflow.
dict)The data associated with this workflow. See stjames for detailed per-workflow descriptions.
int)The status of this workflow, as an integer. Status codes are defined in stjames.
str)The logfile associated with this workflow.
float)The amount of time this workflow took to run, in seconds.
int)The number of credits charged to the user for running this workflow.
This function creates a new workflow.
rowan.Workflow.submit(
name="new pka prediction",
workflow_type="pka",
initial_molecule=stjames_molecule_dict,
workflow_data={
"pka_range": [-5, 25],
},
)
str)The name of the workflow.
str)The UUID of the folder where this workflow should go.
str)What sort of workflow to run.
dict)The molecule to run the workflow on, formatted as a stjames.Molecule.
dict)Any additional data to submit to the workflow. See stjames for detailed per-workflow descriptions.
The workflow object.
This function retrieves a workflow.
workflow = rowan.Workflow.retrieve(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The UUID of the workflow.
The workflow object.
This function updates a workflow and returns the new object.
rowan.Workflow.update(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
name="renaming this workflow",
public=True,
)
str)The UUID of this workflow.
str)The name of the workflow.
str)The UUID of this workflow's parent (the folder which contains this workflow).
str)Any notes associated with this workflow.
bool)Whether or not this workflow is starred.
bool)Whether or not this workflow is publicly viewable.
bool)Whether or not to send an email update when the workflow is complete.
The new workflow object.
This function stops a workflow that hasn't yet finished.
workflow = rowan.Workflow.stop(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The UUID of the workflow.
Nothing.
This function returns the status of a given workflow.
status = rowan.Workflow.status(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The UUID of the workflow.
The status, as type int.
This function returns True if a workflow is finished and False otherwise.
finished_yet = rowan.Workflow.is_finished(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The UUID of the workflow.
If the workflow, as type bool.
This function deletes a workflow. This action cannot be undone!
rowan.Workflow.delete(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The UUID of this workflow.
Nothing.
This function returns all workflow that meet specified criteria.
workflow_res = rowan.Workflow.list(
name_contains="Ph",
object_status=3,
object_type="redox_potential",
)
str)Return workflows whose name contains a specified string.
str)The UUID of the workflows' parent (the folder which contains these workflows).
bool)Whether or not the workflows are starred.
bool)Whether or not the workflows are public.
int)The status of the workflows.
str)The type of these workflows.
int)Which page of results to return.
int)How many results to return per page.
list[dict])A list of the workflows that match the specified criteria.
int)The total number of pages.
This object represents a single calculation in Rowan. Calculations are created by workflows, and workflow results often contain the UUIDs of their constituent calculations.
{
"settings": {
"method": "aimnet2_wb97md3",
"basis_set": null,
"tasks": [
"optimize",
"frequencies"
],
},
"molecules": [...],
"status": 2,
"name": "neutral (conformer 1)",
"elapsed": 0.09688869799998656,
}
The full calculation object is detailed in stjames.
dict)The settings for the calculation (see stjames).
list[dict])The molecules in the calculation. Single-point calculations will have only a single molecule, while optimizations will have a list of molecules. Molecules are stored in the stjames.Molecule format.
int)The status of this calculation, as an integer. Status codes are defined in stjames.
float)How long this calculation took to run, in seconds.
str)The name of this calculation.
This function retrieves a calculation.
folder = rowan.Calculation.retrieve(
uuid="6dac05de-ce7f-4f6d-b7d2-743981aa1fde",
)
str)The UUID of this calculation.
The calculation object.