Workflow

Base classes for Rowan workflows.

Workflow `pydantic-model`

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	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
`webhook_url`	URL that Rowan will POST to when the workflow completes.	required
`submission_group_uuid`	UUID shared by workflows submitted as one execution group.	required
`elapsed`	Elapsed time of the workflow.	required
`credits_charged`	Number of credits charged for the workflow.	required
`logfile`	Workflow logfile.	required

Show JSON schema:

{
  "$defs": {
    "Status": {
      "description": "Job execution status.",
      "enum": [
        0,
        1,
        2,
        3,
        4,
        5,
        6,
        7
      ],
      "title": "Status",
      "type": "integer"
    }
  },
  "description": "Rowan workflow base model, returned by submit workflow functions.\n\nWorkflow data is not loaded by default to avoid unnecessary downloads that could impact\nperformance. Call `fetch_latest()` to fetch and attach the workflow data.\n\n:param name: Name of the workflow.\n:param uuid: UUID of the workflow.\n:param created_at: Date and time the workflow was created.\n:param updated_at: Date and time the workflow was last updated.\n:param started_at: Date and time the workflow computation was started.\n:param completed_at: Date and time the workflow was completed.\n:param status: Status of the workflow.\n:param parent_uuid: UUID of the parent folder.\n:param notes: Workflow notes.\n:param starred: Whether the workflow is starred.\n:param public: Whether the workflow is public.\n:param workflow_type: Type of the workflow.\n:param data: Data of the workflow.\n:param email_when_complete: Whether to send an email when the workflow completes.\n:param max_credits: Maximum number of credits to use for the workflow.\n:param webhook_url: URL that Rowan will POST to when the workflow completes.\n:param submission_group_uuid: UUID shared by workflows submitted as one execution group.\n:param elapsed: Elapsed time of the workflow.\n:param credits_charged: Number of credits charged for the workflow.\n:param logfile: Workflow logfile.",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "uuid": {
      "title": "Uuid",
      "type": "string"
    },
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "updated_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Updated At"
    },
    "started_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Started At"
    },
    "completed_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Completed At"
    },
    "object_status": {
      "$ref": "#/$defs/Status"
    },
    "parent_uuid": {
      "title": "Parent Uuid",
      "type": "string"
    },
    "notes": {
      "title": "Notes",
      "type": "string"
    },
    "starred": {
      "title": "Starred",
      "type": "boolean"
    },
    "public": {
      "title": "Public",
      "type": "boolean"
    },
    "object_type": {
      "title": "Object Type",
      "type": "string"
    },
    "object_data": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Object Data"
    },
    "email_when_complete": {
      "title": "Email When Complete",
      "type": "boolean"
    },
    "max_credits": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Credits"
    },
    "elapsed": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Elapsed"
    },
    "credits_charged": {
      "title": "Credits Charged",
      "type": "number"
    },
    "object_logfile": {
      "title": "Object Logfile",
      "type": "string"
    },
    "compute_hardware": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Compute Hardware"
    },
    "submission_group_uuid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Submission Group Uuid"
    }
  },
  "required": [
    "name",
    "uuid",
    "created_at",
    "object_status",
    "parent_uuid",
    "notes",
    "starred",
    "public",
    "object_type",
    "email_when_complete",
    "credits_charged",
    "object_logfile"
  ],
  "title": "Workflow",
  "type": "object"
}

Config:

populate_by_name: True

Fields:

name (str)
uuid (str)
created_at (datetime)
updated_at (datetime | None)
started_at (datetime | None)
completed_at (datetime | None)
status (Status)
parent_uuid (str)
notes (str)
starred (bool)
public (bool)
workflow_type (str)
data (dict[str, Any] | None)
email_when_complete (bool)
max_credits (int | None)
elapsed (float | None)
credits_charged (float)
logfile (str)
compute_hardware (str | None)
submission_group_uuid (str | None)

fetch_latest

fetch_latest(in_place: bool = False) -> Self

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: str | None = None,
    parent_uuid: str | None = None,
    notes: str | None = None,
    starred: bool | None = None,
    email_when_complete: bool | None = None,
    public: bool | None = None,
    in_place: bool = False,
) -> Self

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() -> bool

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: bool = True, poll_interval: int = 5
) -> WorkflowResult

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: int = 5,
) -> Iterator[WorkflowResult]

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: int = 5) -> Self

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() -> stjames.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() -> bool

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() -> None

Stops a workflow.

Raises:

Type	Description
`HTTPError`	If the API request fails.

delete

delete() -> None

Deletes the workflow.

Raises:

Type	Description
`HTTPError`	If the API request fails.

delete_data

delete_data() -> None

Deletes the workflow data from the API.

Raises:

Type	Description
`HTTPError`	If the API request fails.

dispatch_info

dispatch_info() -> DispatchInfo

Fetch estimated dispatch information for this workflow.

Returns:

Type	Description
`DispatchInfo`	estimated time, hardware, and queue info.

Raises:

Type	Description
`HTTPError`	if the API request fails.

submit_draft

submit_draft() -> Self

Submit a draft workflow for execution.

Returns:

Type	Description
`Self`	updated workflow instance.

Raises:

Type	Description
`WorkflowError`	if workflow is not in DRAFT status.
`HTTPError`	if the API request fails.

download_msa_files

download_msa_files(
    msa_format: MSAFormat, path: Path | str | None = None
) -> None

Download MSA files for an MSA workflow.

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

download_dcd_files

download_dcd_files(
    replicates: list[int],
    name: str | None = None,
    path: Path | str | None = None,
) -> 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: dict[str, Any],
    workflow_type: str,
    workflow_uuid: str,
    complete: bool = 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: dict[str, Any]

Raw workflow data dict for fallback access.

clear_cache

clear_cache() -> None

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.

DispatchInfo `dataclass`

DispatchInfo(
    to_be_dispatched: bool | None,
    compute_hardware: str | None,
    estimated_runtime_minutes: float | None,
)

Estimated dispatch information for a workflow.

Parameters:

Name	Type	Description	Default
`to_be_dispatched`	`bool \| None`	whether workflow will be queued (vs starting immediately).	required
`compute_hardware`	`str \| None`	hardware type (CPU, H200, A100, etc.).	required
`estimated_runtime_minutes`	`float \| None`	estimated runtime in minutes, or None if unknown.	required

Message `dataclass`

Message(title: str, body: str, type: str)

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_NAME,
    workflow_data: dict[str, Any] | None = None,
    initial_molecule: StructureInput
    | dict[str, Any]
    | None = None,
    initial_smiles: SMILES | None = None,
    name: str | None = None,
    folder_uuid: str | Folder | None = None,
    max_credits: int | None = None,
    webhook_url: str | None = None,
    is_draft: bool = False,
) -> Workflow

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`	`StructureInput \| dict[str, Any] \| None`	Molecule object to use as the initial molecule.	`None`
`initial_smiles`	`SMILES \| 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`
`webhook_url`	`str \| None`	URL that Rowan will POST to when the workflow completes.	`None`
`is_draft`	`bool`	If True, submit the workflow as a draft without starting execution.	`False`

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: str) -> Workflow

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: list[str]) -> list[Workflow]

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: str | None = None,
    name_contains: str | None = None,
    public: bool | None = None,
    starred: bool | None = None,
    status: int | None = None,
    workflow_type: WORKFLOW_NAME | None = None,
    page: int = 0,
    size: int = 10,
) -> list[Workflow]

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_NAME,
    workflow_data: dict[str, Any] | None = None,
    initial_molecules: list[StructureInput | dict[str, Any]]
    | None = None,
    initial_smileses: list[SMILES] | None = None,
    names: list[str] | None = None,
    folder_uuid: str | Folder | None = None,
    max_credits: int | None = None,
    webhook_url: str | None = None,
) -> list[Workflow]

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[StructureInput \| dict[str, Any]] \| None`	Molecule objects to use as initial molecules.	`None`
`initial_smileses`	`list[SMILES] \| 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`
`webhook_url`	`str \| None`	URL to call when each workflow completes.	`None`

Returns:

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

batch_poll_status

batch_poll_status(uuids: list[str]) -> dict[str, int]

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
`dict[str, int]`	Counts keyed by lower-case status name, plus the total workflow count.

Raises:

Type	Description
`HTTPError`	If the API request fails.

Workflow

Workflow pydantic-model

fetch_latest

update

done

result

stream_result

wait_for_result

get_status

is_finished

stop

delete

delete_data

dispatch_info

submit_draft

download_msa_files

download_dcd_files

WorkflowResult dataclass

data property

clear_cache

WorkflowError

DispatchInfo dataclass

Message dataclass

submit_workflow

retrieve_workflow

retrieve_workflows

list_workflows

batch_submit_workflow

batch_poll_status

Workflow `pydantic-model`

WorkflowResult `dataclass`

data `property`

DispatchInfo `dataclass`

Message `dataclass`