Python API

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.

Serializing a pipeline to JSON

Use .to_config() when you want to inspect, cache, or transport the pipeline payload as JSON — for example to review it before submission, commit it to version control, or hand it off to another process.

import json

config = pipeline.to_config()

# Inspect or save
with open("pipeline_config.json", "w") as f:
    json.dump(config, f, indent=2)

# Submit later, or from another process
submission = client.pipeline.create(config)

.to_config() is the only supported serializer. It emits the discriminators pipeline elements and objectives need (top-level elements are keyed on element_type, and nested schemas carry their own type), and applies the schema’s field-name mappings (for example, data_input → data).Do not use Pydantic’s model_dump() to build API payloads. model_dump() drops these discriminators and skips field-name mappings, so it produces a dict the API may reject.

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")

Data-fit parameter trace

Data-fit elements log the optimizer’s per-iteration progress to the element’s job metadata. Pull it down with client.job.get_parameter_trace using the element’s job ID — see Inspecting the parameter trace for the full schema. The element’s job_id lives in the pipeline’s elements list rather than in element_results, so fetch the list and pick out the data-fit element by name:

elements = client.get(f"/pipelines/{submission.id}/elements")
fit_job_id = next(e["job_id"] for e in elements if e["name"] == "fit")

trace = client.job.get_parameter_trace(fit_job_id)

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"

SimplePipeline

A SimplePipeline is a lightweight alternative to Pipeline for workflows with at most one expensive element — a single DataFit or Validation. It runs fire-and-forget and returns a flat result containing parameter_values, cost, and (for validation) summary_stats. Submit and poll it through client.simple_pipeline.

Building the config

SimplePipeline inherits everything from Pipeline and adds client-side validation that rejects configs with more than one expensive element:

import ionworks_schema as iws

objective = iws.objectives.CurrentDriven(data_input="path/to/discharge.csv")

pipeline = iws.SimplePipeline(
    elements={
        "initial_params": iws.direct_entries.DirectEntry(
            parameters={"Negative particle diffusivity [m2.s-1]": 2e-14},
        ),
        "fit": iws.DataFit(
            objectives={"cycle": objective},
            parameters={
                "Negative particle diffusivity [m2.s-1]": iws.Parameter(
                    "Negative particle diffusivity [m2.s-1]",
                    bounds=(1e-14, 1e-13),
                    initial_value=2e-14,
                )
            },
            cost=iws.costs.RMSE(),
            optimizer=iws.parameter_estimators.ScipyDifferentialEvolution(
                maxiter=10
            ),
        ),
    },
    name="My Fit",
)

config = pipeline.to_config()

If you pass more than one DataFit or Validation element, SimplePipeline raises a ValueError immediately — no need to wait for a server-side rejection.

Submitting and polling

from ionworks import Ionworks

client = Ionworks()

# Submit the config
sp = client.simple_pipeline.create(config, name=pipeline.name)
# sp.status == "pending"

# Wait for completion (polls automatically)
result = client.simple_pipeline.wait_for_completion(sp.id, timeout=600)

# Read results
print(result.result["parameter_values"])
# {"Negative particle diffusivity [m2.s-1]": 5.3e-14}
print(result.result["cost"])

Validation pipelines

SimplePipeline also supports a single Validation element. The result includes summary_stats alongside parameter_values.

objective = iws.objectives.CurrentDriven(data_input="path/to/cycle.csv")

validation_pipeline = iws.SimplePipeline(
    elements={
        "validate": iws.Validation(
            objectives={"cycle": objective},
        ),
    },
    name="Validate fitted model",
)

sp = client.simple_pipeline.create(
    validation_pipeline.to_config(), name=validation_pipeline.name
)
result = client.simple_pipeline.wait_for_completion(sp.id, timeout=600)
print(result.result["summary_stats"])

End-to-end example

import pybamm
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": pybamm.lithium_ion.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.

Get Started

Core Concepts

Data

Build

Pipelines

Simulate

Optimize

Submitting a pipeline

Serializing a pipeline to JSON

Overriding submission metadata

Waiting for completion

Retrieving results

Element metadata

Data-fit parameter trace

Listing pipelines

Getting a single submission

SimplePipeline

Building the config

Submitting and polling

Validation pipelines

End-to-end example

​Submitting a pipeline

​Serializing a pipeline to JSON

​Overriding submission metadata

​Waiting for completion

​Retrieving results

​Element metadata

​Data-fit parameter trace

​Listing pipelines

​Getting a single submission

​SimplePipeline

​Building the config

​Submitting and polling

​Validation pipelines

​End-to-end example

Submitting a pipeline

Serializing a pipeline to JSON

Overriding submission metadata

Waiting for completion

Retrieving results

Element metadata

Data-fit parameter trace

Listing pipelines

Getting a single submission

SimplePipeline

Building the config

Submitting and polling

Validation pipelines

End-to-end example