Calculations

All calculations are subclasses of the base calculation class

class ionworkspipeline.calculations.Calculation(source)

Base class for calculations that derive new parameters from existing ones.

Calculations transform input parameters through algebraic or numerical methods to produce output parameters. Common uses include computing geometric properties, stoichiometry windows, and material concentrations.

Consider creating a custom calculation when:

  • You have a proprietary relationship between parameters

  • The built-in calculations don’t cover your specific use case

  • You want to encapsulate complex logic for reuse

  • You need to integrate with external data sources or models

All calculations follow the same pattern:

  1. Take input parameters

  2. Perform computation

  3. Return output parameters

Custom calculations work seamlessly with pipelines and all returned parameters become available to subsequent calculations in the pipeline.

Parameters

sourcestr

Reference or description of the calculation method (e.g., paper citation, algorithm description).

Notes

Best practices for custom calculations:

  • Clear naming: Use descriptive names with units, e.g., "Electrode capacity [A.h]" not "cap"

  • Document inputs/outputs: Clearly document what parameters your calculation requires and produces

  • Unit consistency: Be explicit about unit conversions; use SI units internally

  • Validate inputs: Check for missing or invalid inputs early and provide clear error messages

Accessing input parameters:

Calculations receive a parameter dictionary. Access values using standard Python dictionary syntax:

def run(self, inputs):
    # Direct access
    thickness = inputs["Positive electrode thickness [m]"]

    # With default value
    temperature = inputs.get("Temperature [K]", 298.15)

    # Check if parameter exists
    if "Optional parameter" in inputs:
        optional = inputs["Optional parameter"]

Examples

Create a custom calculation for electrode capacity from loading:

>>> from ionworkspipeline.calculations import Calculation
>>> class CustomCalculation(Calculation):
...     def __init__(self):
...         super().__init__(source="Custom method")
...     def run(self, parameter_values):
...         result = parameter_values["Input [m]"] * 2
...         return iwp.ParameterValues({"Output [m]": result})
>>> calc = CustomCalculation()
>>> calc.source
'Custom method'

Extends: ionworkspipeline.controllers.ConfigMixin

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

to_config() → dict

Convert the Calculation back to parser configuration format.

Returns

dict

Configuration dictionary that can be passed to parse_calculation

The following calculations are available: