Python API

The ionworks-api Python package lets you run simulations and submit parameterization pipelines programmatically. For installation and authentication, see the Python API client page. To save, validate, parse, or convert the protocols you run here, see the Protocol API page.

Running simulations

Use client.simulation to run simulations. A simulation requires a parameterized model and a protocol in UCP format.

Single simulation

response = client.simulation.protocol({
    "parameterized_model": "your-parameterized-model-id",
    "protocol_experiment": {
        "protocol": """
global:
  initial_soc: 1
  temperature: 25
steps:
  - Discharge:
      mode: C-rate
      value: 1
      ends:
        - "Voltage < 2.5"
""",
        "name": "1C Discharge",
    },
})

print(f"Simulation ID: {response.simulation_id}")
print(f"Job ID: {response.job_id}")

You can also pass experiment parameters and design parameters:

response = client.simulation.protocol({
    "parameterized_model": "your-parameterized-model-id",
    "protocol_experiment": {
        "protocol": """
global:
  initial_soc: input["Initial SOC"]
steps:
  - Discharge:
      mode: C-rate
      value: input["C-rate"]
      ends:
        - "Voltage < 2.5"
""",
        "name": "Parameterized Discharge",
    },
    "experiment_parameters": {
        "Initial SOC": 1.0,
        "C-rate": 0.5,
    },
    "design_parameters": {
        "Positive electrode thickness [m]": 75e-6,
    },
})

design_parameters is a single-simulation convenience field on protocol(). Pass a flat dict[str, float] of parameter overrides — the client translates them internally to a one-row discrete DOE before submission. Use it when you want to vary one or more design parameters for a single run without writing out the full DOE schema.

In protocol(), design_parameters and design_parameters_doe are mutually exclusive, and any DOE you supply must resolve to exactly one simulation. Passing both, or a DOE that would expand to multiple simulations, raises ValueError — use protocol_batch for multi-simulation sweeps instead.

To run a protocol you have already saved, pass protocol_id in place of protocol_experiment — exactly one of the two. project_id is then optional and defaults to the saved protocol’s own project:

response = client.simulation.protocol({
    "parameterized_model": "your-parameterized-model-id",
    "protocol_id": "your-protocol-id",
})

Config keys are checked before anything is sent. A misspelt or misplaced key raises a ValueError naming it and listing the valid top-level keys, rather than being ignored.

Waiting for results

Use wait_for_completion to poll until the simulation finishes. The method detects failed and canceled jobs immediately rather than waiting for the timeout.

result = client.simulation.wait_for_completion(
    response.simulation_id,
    timeout=120,        # seconds (default: 60)
    poll_interval=2,    # seconds between polls (default: 2)
    verbose=True,       # print status updates (default: True)
)

Set raise_on_failure=False to get the result dict instead of raising an exception when a simulation fails:

result = client.simulation.wait_for_completion(
    response.simulation_id,
    raise_on_failure=False,
)

Batch simulations with design of experiments

Run multiple simulations across a parameter sweep using protocol_batch:

responses = client.simulation.protocol_batch({
    "parameterized_model": "your-parameterized-model-id",
    "protocol_experiment": {
        "protocol": "...",
        "name": "C-rate Sweep",
    },
    "design_parameters_doe": {
        "sampling": "grid",
        "rows": [
            {
                "type": "discrete",
                "name": "Positive electrode thickness [m]",
                "values": [50e-6, 75e-6, 100e-6],
            },
        ],
    },
})

# Wait for all simulations
results = client.simulation.wait_for_completion(
    [r.simulation_id for r in responses],
    timeout=300,
)

Supported DOE row types:

Type	Fields	Description
`discrete`	`values`	Specific values to test
`range`	`min`, `max`, `count`	Evenly spaced values between min and max
`normal`	`mean`, `std`, `count`	Values sampled around the mean

Sampling strategies: grid (all combinations), random, latin_hypercube.

Explicit list of runs

When the runs are not a sampled design, list them with conditions instead of design_parameters_doe. Each condition is one simulation with its own experiment_parameters and design_parameters; nothing is crossed. A top-level experiment_parameters is a shared default that each condition can override. conditions and design_parameters_doe cannot be combined.

responses = client.simulation.protocol_batch({
    "parameterized_model": "your-parameterized-model-id",
    "protocol_id": "your-protocol-id",
    "experiment_parameters": {"Initial SOC [%]": 100},
    "conditions": [
        {"experiment_parameters": {"Temperature [°C]": 10}},
        {
            "experiment_parameters": {"Temperature [°C]": 40},
            "design_parameters": {"Negative electrode porosity": 0.35},
        },
    ],
})

Checking many simulations at once

get_statuses returns the status of many simulations in one request, which is cheaper than calling get() per id. Unknown ids are omitted from the result.

statuses = client.simulation.get_statuses([r.simulation_id for r in responses])
for s in statuses:
    print(s["simulation_id"], s["status"])

Retrieving simulation data

# List all simulations
simulations = client.simulation.list()

# Get a specific simulation
simulation = client.simulation.get(simulation_id)

# Get result data (time series, steps, metrics)
result = client.simulation.get_result(simulation_id)

get_result returns a typed SimulationResult dataclass with three fields:

Field	Type	Description
`result.time_series`	`DataFrame`	One row per time point; columns are signal names (e.g. `"Time [s]"`, `"Voltage [V]"`, `"Current [A]"`).
`result.steps`	`DataFrame`	One row per protocol step (e.g. `"Step count"`, `"Step type"`, `"Duration [s]"`).
`result.metrics`	`dict[str, Any]`	Scalar metrics computed over the run (e.g. cycle-level summaries).

time_series and steps are returned as polars DataFrames by default. Call set_dataframe_backend("pandas") once at session start to receive pandas DataFrames instead.

from ionworks import Ionworks

client = Ionworks()
simulation_id = "your-simulation-id"  # e.g. response.simulation_id from a submitted run
result = client.simulation.get_result(simulation_id)

# Plot voltage vs time. With the default polars backend, convert to pandas first;
# with the pandas backend (set_dataframe_backend("pandas")), use result.time_series directly.
ts = result.time_series.to_pandas()  # drop .to_pandas() on the pandas backend
ts.plot(x="Time [s]", y="Voltage [V]")

# Inspect protocol steps
print(result.steps)

# Read scalar metrics
print(result.metrics)

Discharge capacity [A.h] and Charge capacity [A.h] in time_series reset to 0 at each step boundary. Use "Step count" to join time_series to steps, or accumulate per-step end values if you need a continuous cumulative capacity trace.

Deleting a simulation

client.simulation.delete("your-simulation-id")

Running pipelines

Pipelines have moved to their own page. See the Pipelines API how-to for submitting pipelines and simple pipelines, polling them, reading results, and managing submissions.

Managing studies

Use client.study to create, list, update, and delete studies. Studies are scoped to a project. All client.study.* methods accept project_id as an optional keyword argument. When omitted, they use the default project configured on the client (or resolved from IONWORKS_PROJECT_ID). Pass project_id= explicitly to override on a per-call basis.

Listing studies

# Uses the default project from the client
studies = client.study.list()
for study in studies:
    print(f"{study.name} (ID: {study.id})")

# Filter by name
studies = client.study.list(name="Discharge")

# Paginate results
studies = client.study.list(limit=10, offset=0)

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

Supported filters: name, name_exact, order_by, order.

Getting a study

study = client.study.get("your-study-id")

Creating a study

study = client.study.create({
    "name": "1C Discharge Sweep",
    "description": "Comparing discharge curves across temperatures",
})

Updating a study

study = client.study.update("your-study-id", {
    "name": "1C Discharge Sweep v2",
})

Assigning simulations and measurements

# Assign a simulation to a study
client.study.assign_simulation("your-study-id", "simulation-id")

# Remove a simulation from a study
client.study.remove_simulation("your-study-id", "simulation-id")

# Assign a measurement to a study
client.study.assign_measurement("your-study-id", "measurement-id")

# List measurements in a study
measurements = client.study.list_measurements("your-study-id")

# Remove a measurement from a study
client.study.remove_measurement("your-study-id", "measurement-id")

Deleting a study

client.study.delete("your-study-id")

You can find the ID for any resource from the Ionworks Studio web app. The ID is displayed in the URL when you navigate to a resource’s detail page.

Next steps

Simulations

Learn about running simulations in Ionworks Studio.

Protocol API

Save, validate, parse, and convert protocols with client.protocol.

Protocol reference

Full reference for the Universal Cycler Protocol format.

Uploading data

Upload and manage cell data via the Python API.

Build API

List and retrieve models and parameterized models.

Get Started

Quickstarts

Core Concepts

Operate

Data

Build

Simulate

Optimize

Running simulations

Single simulation

Waiting for results

Batch simulations with design of experiments

Explicit list of runs

Checking many simulations at once

Retrieving simulation data

Deleting a simulation

Running pipelines

Managing studies

Listing studies

Getting a study

Creating a study

Updating a study

Assigning simulations and measurements

Deleting a study

Next steps

Simulations

Protocol API

Protocol reference

Uploading data

Build API

​Running simulations

​Single simulation

​Waiting for results

​Batch simulations with design of experiments

​Explicit list of runs

​Checking many simulations at once

​Retrieving simulation data

​Deleting a simulation

​Running pipelines

​Managing studies

​Listing studies

​Getting a study

​Creating a study

​Updating a study

​Assigning simulations and measurements

​Deleting a study

​Next steps

Simulations

Protocol API

Protocol reference

Uploading data

Build API

Running simulations

Single simulation

Waiting for results

Batch simulations with design of experiments

Explicit list of runs

Checking many simulations at once

Retrieving simulation data

Deleting a simulation

Running pipelines

Managing studies

Listing studies

Getting a study

Creating a study

Updating a study

Assigning simulations and measurements

Deleting a study

Next steps