Skip to main content
The ionworks-api Python package exposes client.pipeline for running and managing pipelines. For installation and authentication, see the Python API client page.

​
Submitting a pipeline

import ionworks_schema as iws
from ionworks import Ionworks

# Reads IONWORKS_API_KEY and IONWORKS_PROJECT_ID from the environment.
client = Ionworks()

pipeline = iws.Pipeline(
    {
        "known": iws.direct_entries.DirectEntry(
            parameters={"Ambient temperature [K]": 298.15},
        ),
        "Q_pos": iws.calculations.ElectrodeCapacity(electrode="positive"),
    },
    name="Capacity pipeline",
)

submission = client.pipeline.create(pipeline)
print(f"Pipeline ID: {submission.id}")
print(f"Status: {submission.status}")
client.pipeline.create() accepts either an iws.Pipeline schema instance or the dict returned by .to_config(). Schema instances are validated locally before submission, so shape errors surface immediately.

​
Overriding submission metadata

create() accepts optional project_id, name, description, and options kwargs that override any values carried on the schema: 
submission = client.pipeline.create(
    pipeline,
    project_id="your-project-id",
    name="Custom run name",
    options={"live_progress_updates": True},
)
When project_id is omitted, the client falls back to the default configured on Ionworks(...) or the IONWORKS_PROJECT_ID environment variable.

​
Waiting for completion

submission = client.pipeline.wait_for_completion(
    submission.id,
    timeout=600,        # seconds (default: 600)
    poll_interval=2,    # seconds between polls (default: 2)
    verbose=True,       # print status updates (default: True)
)
Pass raise_on_failure=False to get the failed submission response back instead of raising when the pipeline errors out.

​
Retrieving results

result = client.pipeline.result(submission.id)

# Final parameter values produced by the pipeline
print(result.result)

# Per-element output keyed by the element name used in the Pipeline
print(result.element_results["Q_pos"])
result.element_results mirrors the keys you passed to iws.Pipeline(elements=...).

​
Element metadata

Some elements (notably Validation) write extra metadata that isn’t included in element_results. Fetch it with: 
metadata = client.pipeline.get_element_metadata(submission.id, "validate")

​
Listing pipelines

# Defaults to the project on Ionworks(...) or IONWORKS_PROJECT_ID
pipelines = client.pipeline.list()

# Override the project for a single call
pipelines = client.pipeline.list(project_id="other-project-id")

# Limit the number of results
pipelines = client.pipeline.list(limit=10)

​
Getting a single submission

submission = client.pipeline.get(submission.id)
print(submission.status)  # "pending", "running", "completed", or "failed"

​
End-to-end example

import ionworks_schema as iws
from ionworks import Ionworks

client = Ionworks()

pipeline = iws.Pipeline(
    {
        "known": iws.direct_entries.DirectEntry(
            parameters={"Ambient temperature [K]": 298.15},
        ),
        "fit": iws.DataFit(
            objectives={
                "1C": iws.objectives.CurrentDriven(
                    data_input="file:examples/data/chen_synthetic_1C/time_series.csv",
                    options={"model": {"type": "SPMe"}},
                ),
            },
            parameters={
                "Negative particle diffusivity [m2.s-1]": iws.Parameter(
                    "Negative particle diffusivity [m2.s-1]",
                    initial_value=2e-14,
                    bounds=(1e-14, 1e-13),
                ),
            },
            cost=iws.costs.RMSE(),
            optimizer=iws.optimizers.DifferentialEvolution(),
        ),
    },
    name="SPMe diffusivity fit",
)

submission = client.pipeline.create(pipeline)
client.pipeline.wait_for_completion(submission.id)

result = client.pipeline.result(submission.id)
print(result.element_results["fit"])
For more end-to-end examples (entry-only, calculation-only, datafit, validation), see packages/ionworks-api/examples/pipeline/ in the SDK repo.