Introduction to Pipelines

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

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

Pipeline Elements

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

There are three types of pipeline elements:

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

The pipeline element types and built-in calculations listed here are not exhaustive. See the API reference for full details.

import ionworkspipeline as iwp

pipeline = iwp.Pipeline([
    iwp.calculations.Capacity("Positive"),
    iwp.calculations.Capacity("Negative"),
    iwp.calculations.CyclableLithium(),
    iwp.calculations.ElectrodeSOH(),
])

result = pipeline.run(parameter_values)

Each element:

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

Custom Calculations

You can create custom calculations for specialized workflows:

class MyCustomCalculation(iwp.Calculation):
    def __init__(self, some_option):
        self.some_option = some_option

    def run(self, inputs):
        value = inputs["Some input parameter [units]"]
        result = value * self.some_option
        return {"Some output parameter [units]": result}

Custom calculations integrate seamlessly with pipelines and built-in calculations.

Clear Naming

Use descriptive 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

Data Fitting

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

datafit = iwp.DataFit(
    objectives=objectives,      # Compare model to data
    parameters=parameters,      # Which parameters to fit
    optimizer=optimizer,        # How to search
)

result = datafit.run(fixed_parameters)

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

Introduction to Data Fitting

Learn how to set up objectives, parameters, and optimizers for parameter estimation

Python Examples

Common workflows and code examples in the Python documentation