Pipeline#

Client for managing pipelines with data fitting, calculations, and validation.

For usage examples and guides, see Simulate API on docs.ionworks.com.

Pipeline client for running parameterization workflows.

This module provides the PipelineClient for creating and managing pipelines that combine data fitting, calculations, and validation steps for battery model parameterization.

Pipeline shape validation is delegated to ionworks_schema — both this client’s PipelineClient.create() method and the backend route parse against the same schema, so a payload that builds with iws.Pipeline(...) validates identically end-to-end.

class ionworks.pipeline.PipelineSubmissionMetadata(*, project_id=None, options=None)[source]#

Bases: BaseModel

SDK-only metadata attached to a pipeline submission.

These fields are not part of ionworks_schema.Pipeline because they describe how the submission is routed (which project, which runtime options) rather than what the pipeline does.

Parameters:

project_id (str | None)
options (dict[str, Any] | None)

project_id: str | None#

options: dict[str, Any] | None#

resolve_project_id()[source]#

Resolve project_id from env vars if not provided.

Prefers IONWORKS_PROJECT_ID; falls back to the deprecated PROJECT_ID (with a DeprecationWarning) via resolve_env_project_id().

Return type:: PipelineSubmissionMetadata

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.pipeline.DataFitResponse(*, parameter_values)[source]#

Bases: BaseModel

Response from a data fitting step containing fitted parameters.

Parameters:: parameter_values (dict[str, Any])

parameter_values: dict[str, Any]#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.pipeline.CalculationResponse(*, parameter_values)[source]#

Bases: BaseModel

Response from a calculation step containing calculated parameters.

Parameters:: parameter_values (dict[str, Any])

parameter_values: dict[str, Any]#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.pipeline.ValidationResponse(*, validation_results, summary_stats)[source]#

Bases: BaseModel

Response from a validation step containing validation results.

Parameters:

validation_results (dict[str, Any])
summary_stats (dict[str, list[Any]])

validation_results: dict[str, Any]#

summary_stats: dict[str, list[Any]]#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.pipeline.EntryResponse(*, parameter_values)[source]#

Bases: BaseModel

Response from an entry point containing parameter values.

Parameters:: parameter_values (dict[str, Any])

parameter_values: dict[str, Any]#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.pipeline.PipelineSubmissionResponse(*, id, name, description=None, status, error=None)[source]#

Bases: BaseModel

Response from submitting a pipeline to the API.

Parameters:

id (str)
name (str)
description (str | None)
status (str)
error (str | None)

id: str#

name: str#

description: str | None#

status: str#

error: str | None#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.pipeline.PipelineResponse(*, result, element_results)[source]#

Bases: BaseModel

Complete response from retrieving pipeline results.

Parameters:

result (dict[str, Any])
element_results (dict[str, Any])

result: dict[str, Any]#

element_results: dict[str, Any]#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.pipeline.PipelineClient(client)[source]#

Bases: object

Client for creating and managing pipeline workflows.

Parameters:: client (Any)

__init__(client)[source]#

Initialize the pipeline client.

Parameters:: client (Any) – The HTTP client to use for API requests.
Return type:: None

create(config, *, project_id=None, name=None, description=None, options=None)[source]#

Run a complete pipeline with the given configuration.

Parameters:

config (ionworks_schema.Pipeline or dict[str, Any]) – Pipeline configuration. Either an iws.Pipeline schema instance (constructed via iws.Pipeline(elements=...)) or a dict with elements, name, description and SDK-only fields such as project_id/options. Dicts are validated against iws.Pipeline before submission so shape errors surface locally.
project_id (str, optional) – Project to submit to. Falls back to a project_id field on config (dict form), then to the PROJECT_ID env var.
name (str, optional) – Submission name override. Falls back to the schema’s name field.
description (str, optional) – Submission description override. Falls back to the schema’s description field.
options (dict[str, Any], optional) – Submission options (e.g. {"live_progress_updates": True}). Falls back to config["options"] (dict form).

Returns:

The pipeline submission response.

Return type:

PipelineSubmissionResponse

Raises:

ValueError – If the configuration is invalid.

update(pipeline_id, name=None, description=None)[source]#

Partially update a pipeline’s name and/or description.

This is a metadata-only update: it cannot modify the pipeline’s config or affect a running job.

Parameters:

pipeline_id (str) – The pipeline ID to update.
name (str | None, optional) – New name. Omit (or pass None) to leave unchanged.
description (str | None, optional) – New description. Omit (or pass None) to leave unchanged.

Returns:

The updated record.

Return type:

PipelineSubmissionResponse

Raises:

ValueError – If neither name nor description is provided.

list(project_id=None, limit=None)[source]#

List all pipelines.

Parameters:

project_id (str | None) – The project id to filter pipelines. If not provided, uses the project_id set on the Ionworks client or the IONWORKS_PROJECT_ID environment variable.
limit (int | None) – Maximum number of pipelines to return. If not provided, returns all pipelines (up to the API’s default limit).

Returns:

List of pipeline submission responses.

Return type:

list[PipelineSubmissionResponse]

Raises:

ValueError – If response data is not a list or project_id is missing.

get(job_id)[source]#

Get the pipeline response for the given job id.

Parameters:: job_id (str) – The job id.
Returns:: The pipeline submission response.
Return type:: PipelineSubmissionResponse

result(job_id)[source]#

Get the result for the given job id.

Parameters:: job_id (str) – The job id.
Returns:: The pipeline results.
Return type:: PipelineResponse

cancel(pipeline_id)[source]#

Cancel a running pipeline and all its non-terminal elements.

Parameters:: pipeline_id (str) – The pipeline ID to cancel.
Returns:: The updated record (status will be canceled if cancellation took effect; otherwise the current state is returned).
Return type:: PipelineSubmissionResponse

delete(pipeline_id)[source]#

Delete a pipeline, its elements, associated jobs, and storage files.

Parameters:: pipeline_id (str) – The pipeline ID to delete.
Return type:: None

get_element_metadata(pipeline_id, element_name, elements=None)[source]#

Fetch the metadata blob for a named element of a pipeline.

Locates the element by name in the pipeline’s elements list, then delegates to client.job.get_metadata for the underlying job. Use this when you need fields that are stripped from element.result and persisted to storage instead — for example, validation_results and validation_plot_config written by a validation element.

Parameters:

pipeline_id (str) – The pipeline whose element metadata to fetch.
element_name (str) – The name of the element within the pipeline — the key used in the elements dict at submission time. Element names are user-chosen and unique per pipeline (a pipeline may run multiple validation elements under names like "validate_pristine" and "validate_aged").
elements (list[dict], optional) – Pre-fetched elements list from GET /pipelines/{id}/elements. Pass this when pulling metadata for several elements of the same pipeline to avoid re-fetching the list on every call. When omitted, the list is fetched fresh.

Returns:

The parsed metadata payload for the element’s job.

Return type:

dict[str, Any]

Raises:

ValueError – If the pipeline has no element with the given name, or that element has no associated job (e.g. it never ran).

wait_for_completion(pipeline_id, timeout=600, poll_interval=2, verbose=True, raise_on_failure=True)[source]#

Wait for a pipeline to complete by polling until done or timeout.

Parameters:

pipeline_id (str) – The pipeline ID to wait for.
timeout (int, optional) – Maximum time to wait in seconds (default: 600).
poll_interval (int, optional) – Time between polls in seconds (default: 2).
verbose (bool, optional) – Whether to print status updates (default: True).
raise_on_failure (bool, optional) – Whether to raise IonworksError when pipeline fails (default: True).

Returns:

The completed (or failed, if raise_on_failure=False) pipeline response.

Return type:

PipelineSubmissionResponse

Raises:

TimeoutError – If timeout is reached before the pipeline completes.
IonworksError – If the pipeline fails and raise_on_failure is True.