Introduction to Pipelines

Chain DirectEntry, Calculation, DataFit, and Validation elements to transform battery parameters and fit models to experimental data.

Battery parameterization is built around a simple abstraction: pipeline elements that transform input parameters into output parameters, chained together into a pipeline. This design provides flexibility to handle any parameterization workflow—from simple calculations to complex data fitting.

Pipeline Elements

The basic building block is a pipeline element. Any pipeline element accepts a set of parameter values (possibly empty) and returns another set of parameter values. The full pipeline is built by calling each element in series to yield the complete parameter set.

There are five types of pipeline element:

Type	Description
DirectEntry	The simplest type—ignores input parameters and returns pre-defined values (e.g., from literature or direct measurements)
Calculation	Computes new parameters based on provided inputs (e.g., calculating maximum particle concentration from capacity, volume fraction, and thickness)
DataFit	Estimates parameters by fitting a model to experimental data
ArrayDataFit	Fits the same model separately at each value of an independent variable (e.g., a separate fit per temperature or per pulse SOC)
Validation	Checks fitted parameters against held-out data

The pipeline element types and built-in calculations listed here are not exhaustive. See the Pipelines API how-to for the full configuration surface.

For example, a capacity pipeline chains an electrode-capacity calculation per electrode with cyclable-lithium and electrode-SOH calculations — each element consuming parameters produced by the elements before it.

Each element:

1. Takes input parameters from the parameter dictionary
2. Performs computation
3. Returns output parameters that become available to subsequent elements

To assemble and submit a pipeline programmatically, see Pipelines → Overview in the Documentation tab.

Naming conventions

Clear Naming

Use descriptive parameter names with units: "Electrode capacity [A.h]" not "cap"

Unit Consistency

Be explicit about unit conversions; use SI units internally

Built-in Calculations

Geometry & Capacity

Electrode geometry, mass, capacity, cyclable lithium, and microstructure

Thermal Properties

Heat capacity, Arrhenius temperature dependence, and thermal modeling

Piecewise Interpolants

Smooth piecewise functions for SOC and temperature-dependent parameters

Handling pipeline failures

Pipeline elements run sequentially. When an element fails, the pipeline reports an error and any downstream elements stop. The cause is recorded on the element as an error_code:

error_code	Meaning
SUBMISSION_FAILED	The element could not be submitted to a worker (for example, transient infrastructure issue). Safe to resubmit.
EXECUTION_TIMEOUT	The element exceeded its execution time limit. Adjust the configuration before retrying.
INTERNAL_ERROR	An unexpected server-side error occurred while running the element.

Resubmitting a failed pipeline

If the first failed element has error_code = SUBMISSION_FAILED, you can resubmit the pipeline. Resubmission resets that element and continues execution from where the pipeline stopped — completed elements are not re-run.

Studio

Open the pipeline detail page. When the lead failure is a submission error, a Resubmit button appears on the failed-element alert at the top of the page. Click it to retry the pipeline in place.

REST API

Resubmission goes through the generic jobs endpoint, and a pipeline is identified by its job ID (the same ID you pass to client.pipeline.get(...)):

curl -X POST \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  https://api.ionworks.com/jobs/{pipeline_id}/resubmit

The response is the updated pipeline with its elements. The endpoint returns 400 if the first failed element is not in a SUBMISSION_FAILED state, and 404 if the pipeline does not exist. See the API Reference for the full schema.

For failures with other error codes (timeouts, internal errors, or configuration issues), create a new pipeline with the corrected configuration instead of resubmitting.

Data Fitting

The pipeline abstraction also powers data fitting—estimating unknown parameters by comparing model predictions to experimental data. A DataFit element wraps a pipeline with an optimization loop:

• The optimizer proposes parameter values
• The pipeline runs the model with those values
• The objective computes how well predictions match data
• This repeats until the best-fit parameters are found

Data Fitting (theory)

Cost functions, identifiability, regularization, and other theory.

Data Fitting (how-to)

Configure and submit data fits with ionworks-schema + ionworks-api.

Pipeline errors

When a pipeline element fails, Studio shows the element in a Failed state with an error message and a machine-readable error code. Hover the status chip in any pipeline list to see the code, and expand the failed element to read the full message.

The same fields are returned by the API on failed jobs and pipeline elements:

{
  "status": "FAILED",
  "error": "'Negative electrode loading [A.h.cm-2]' not found. Best matches are [...]",
  "error_code": "CONFIGURATION_ERROR",
  "error_detail": {
    "exception_type": "ParameterNotFoundError"
  }
}

Error codes

Use the error_code field to branch on failure type without parsing error strings:

Code	When it’s raised	What to do
CONFIGURATION_ERROR	A pipeline or element is misconfigured — for example, a required parameter is missing, a value is out of range, or a field has the wrong type. Includes ParameterNotFoundError from a ParameterValues lookup, UserConfigurationError raised by pipeline/data-fit parsing, and ProtocolConfigurationError raised by the UCP protocol engine (malformed step, unknown end-condition type, missing drive cycle, unresolved goto target, initial SOC out of [0, 100], etc.).	Fix the pipeline configuration or input parameters. The error message names the offending field.
SOLVER_ERROR	The numerical solver failed to converge (e.g., voltage cut-off violated, integration failure during a simulation).	Check the operating protocol, initial conditions, and parameter values for physical consistency.
EXECUTION_TIMEOUT	The job exceeded its allowed wall-clock time.	Reduce problem size, simplify the model, or split the run.
SUBMISSION_FAILED	The job could not be submitted to the compute backend.	Retry the job. Contact support if it persists.
INTERNAL_ERROR	An unexpected error inside the platform. The raw exception message is intentionally sanitised.	Retry the job. Contact support if it persists.

Catching configuration errors in Python

Submitting a pipeline with a bad configuration doesn’t fail at submission time — the job is accepted, then the offending element fails with error_code = CONFIGURATION_ERROR once it runs (see the table above). Waiting for the pipeline with the SDK’s wait_for_completion raises that failure as an IonworksError:

from ionworks.errors import IonworksError

try:
    client.pipeline.wait_for_completion(pipeline_id)
except IonworksError as err:
    print(f"Pipeline failed: {err}")

The exception message carries the underlying failure text — for a missing parameter, the same pybamm lookup message shown above ("'Negative electrode loading [A.h.cm-2]' not found. Best matches are [...]"). It does not carry the structured error_code; for that, check the failed element’s status on the job (the JSON shown above) rather than parsing the exception message.

When a UCP protocol can’t be simulated as written — for example, a drive cycle referenced by name that wasn’t supplied, a goto target that doesn’t resolve, an end-condition string that doesn’t parse, an initial SOC outside [0, 100], or an expression that references an uninitialised variable — the failed pipeline element is tagged with the CONFIGURATION_ERROR code and its message is surfaced verbatim through the API. This distinguishes a user-correctable protocol issue (fix the protocol, drive cycles, or inputs and retry) from an unexpected internal failure, which is reported as INTERNAL_ERROR.