Models¶

The models module provides PyBaMM model classes and utilities for adding design variables and computing metrics.

Model Classes¶

class ionworkspipeline.data_fits.models.MSMRHalfCellModel(electrode, options=None)¶

A class for the MSMR half-cell model of the open-circuit potential (OCP).

Parameters¶

electrodestr

The electrode to use for the model.

optionsdict, optional

A dictionary of options to pass to the model. The options include:

capacity function
The capacity function to use for the model. Default is None.
species format
The species format to use for the model. Can be “Qj” for capacity or “Xj” for mole fraction. Default is “Qj”.
direction
The direction to use for the model. Can be None, “delithiation” or “lithiation”. Default is None.
particle phases
How many particle phases are present in the electrode. Can be “1” (default) or “2” for composite electrodes with Primary and Secondary phases.

Extends: ionworkspipeline.controllers.ConfigMixin

build(parameter_values, data, voltage_limits=None)¶

Build the model.

Parameters¶

parameter_valuespybamm.ParameterValues: The parameter values to use for the model.
datadict: The data to use for the model.
voltage_limitstuple, optional: The voltage range over which to evaluate the variables returned by the solve_full method. Default is None, in which case the full range of the data is used.

default_capacity_function(electrode, parameter_values, species_format='Qj', direction=None, differential=False)¶

Get the default capacity function for the model. Returns ionworkspipeline.data_fits.objectives.get_q_half_cell_msmr.

Parameters¶

electrodestr: The electrode to use for the model.
parameter_valuespybamm.ParameterValues: The parameter values to use for the model.
species_formatstr, optional: The species format to use for the model. Default is “Qj”.
directionstr, optional: The direction to use for the model. Default is None.
differentialbool, optional: Whether to return the differential capacity function. Default is False.

solve(inputs, calculate_dQdU=False, calculate_dUdQ=False)¶

Solve the model at the given inputs.

Parameters¶

inputsdict: The inputs to use to evaluate the OCP.
calculate_dQdUbool, optional: Whether to calculate the differential capacity [Ah/V]. Default is False.
calculate_dUdQbool, optional: Whether to calculate the differential voltage [V/Ah]. Default is False.

Returns¶

dict: The outputs of the model. Should include “Capacity [A.h]”, “Differential capacity [Ah/V]”, “Differential voltage [V/Ah]”.

solve_full(inputs)¶

Solve the model over the voltage range specified by the voltage_limits option in the build method.

Parameters¶

inputsdict: The inputs to use to evaluate the OCP.

Returns¶

dict: The outputs of the model (“Full voltage [V]”, “Full capacity [A.h]”, “Full differential capacity [Ah/V]”, “Full differential voltage [V/Ah]”).

class ionworkspipeline.data_fits.models.MSMRFullCellModel(negative_electrode_model, positive_electrode_model, options=None)¶

A class for the MSMR full-cell model of the open-circuit potential (OCP).

Parameters¶

negative_electrode_modelMSMRHalfCellModel: The model for the negative electrode.
positive_electrode_modelMSMRHalfCellModel: The model for the positive electrode.

Extends: ionworkspipeline.controllers.ConfigMixin

build(parameter_values, data, negative_voltage_limits, positive_voltage_limits)¶

Build the model.

Parameters¶

parameter_valuespybamm.ParameterValues: The parameter values to use for the model.
datadict: The data to use for the model.
negative_voltage_limitstuple: The voltage range over which to evaluate the negative electrode model.
positive_voltage_limitstuple: The voltage range over which to evaluate the positive electrode model.

solve(inputs)¶

Solve the model at the given inputs.

Parameters¶

inputsdict: The inputs to use to evaluate the OCP.

Returns¶

dict: The outputs of the model. Should include “Capacity [A.h]” and “Differential voltage [V/Ah]”.

class ionworkspipeline.data_fits.models.LumpedSPMR(options=None, name='Lumped Single Particle Model with Resistance')¶

Lumped Single Particle Model with Resistance

Parameters¶

optionsdict

Dictionary of options to override default options. Options are:

thermal: str, thermal model to use. Can be “isothermal” or “lumped”.
surface_temperature: str, surface temperature model to use. Can be “ambient” or “lumped”.
working_electrode: str, working electrode to use. Can be “both”, “negative” or “positive”.

namestr, optional

The name of the model. Default is “Lumped Single Particle Model with Resistance”.

Extends: pybamm.models.base_model.BaseModel

property default_geometry¶: Returns a dictionary of the default geometry for the model, which is empty by default.

property default_spatial_methods¶: Returns a dictionary of the default spatial methods for the model, which is empty by default.

property default_submesh_types¶: Returns a dictionary of the default submesh types for the model, which is empty by default.

property default_var_pts¶: Returns a dictionary of the default variable points for the model, which is empty by default.

static get_initial_state(initial_value, parameter_values, tol=1e-06)¶

Get the initial state of the model.

Parameters¶

initial_valuefloat: The initial value of the state.
parameter_valuesdict: The parameter values.
tolfloat, optional: The tolerance for the initial state.

Returns¶

tuple: The initial state of the model (x, y).

static get_stoichiometry_limits(parameter_values)¶

Get the stoichiometry limits from the electrode SOH solver.

Parameters¶

parameter_valuespybamm.ParameterValues: The parameter values. Must include “Negative electrode capacity [A.h]”, “Positive electrode capacity [A.h]”, and “Cyclable lithium capacity [A.h]”.

Returns¶

tuple: (x_0, x_100, y_100, y_0) stoichiometry limits.

static plot_voltage_components(solution, ax=None, show_plot=True, split_by_electrode=False, **kwargs_fill)¶

Plot voltage components from a solution.

Parameters¶

solutionpybamm.Solution: Solution to plot
axmatplotlib.axes.Axes, optional: Axes to plot on
show_plotbool, optional: Whether to show the plot
split_by_electrodebool, optional: Whether to show the overpotentials for the negative and positive electrodes separately. Default is False.
**kwargs_filldict, optional: Keyword arguments for fill_between

static set_initial_state(initial_value, parameter_values, tol=1e-06, inplace=True, inputs=None)¶

Set the initial state of the model.

Parameters¶

initial_valuefloat: The initial value of the state.
parameter_valuesdict: The parameter values.
tolfloat, optional: The tolerance for the initial state.
inplacebool, optional: Whether to set the initial state in place or return a new parameter values object.
inputsdict, optional: Optional inputs dictionary (unused, for API compatibility).

class ionworkspipeline.data_fits.models.LumpedSPMeR(options=None, name='Lumped Single Particle Model with Electrolyte and Resistance')¶

Lumped Single Particle Model with Resistance and Electrolyte concentration overpotential

Parameters¶

optionsdict

Dictionary of options to override default options. Options are:

thermal: str, thermal model to use. Can be “isothermal” or “lumped”.
surface_temperature: str, surface temperature model to use. Can be “ambient” or “lumped”.
working_electrode: str, working electrode to use. Can be “both”, “negative” or “positive”.

namestr, optional

The name of the model. Default is “Lumped Single Particle Model with Electrolyte and Resistance”.

Extends: ionworkspipeline.data_fits.models.lumped_spmr.LumpedSPMR

class ionworkspipeline.data_fits.models.SingleElectrodeLumpedSPMR(options=None)¶

Lumped single-electrode (half-cell) Single Particle Model with Resistance

Parameters¶

optionsdict

Dictionary of options to override default options. Options are:

thermal: “isothermal” or “lumped”
surface temperature: “ambient” or “lumped”
rc pairs: str, number of RC pairs to include in the model. Must be a non-negative integer as a string (e.g., “0”, “1”, “2”, “5”, etc.). Default is “0”.
parameter_dependencies: dict, optional. Specifies which variables each parameter depends on. Keys must be in [“tau”, “R_rc”, “C_rc”]. Values are tuples containing any combination of (“soc”, “temperature”). Empty tuple means the parameter is constant (pybamm.Parameter). Default is all dependencies for backward compatibility.

Example:
```
# No dependencies - all parameters are constants
{"parameter_dependencies": {
    "tau": (),
    "R_rc": (),
    "C_rc": ()
}}

# Partial dependencies - tau depends only on SOC
{"parameter_dependencies": {
    "tau": ("soc",),
    "R_rc": ("temperature",),
    "C_rc": ("soc", "temperature")
}}
```

Notes¶

The model uses array parameters for RC pairs. Parameters should be specified as:

R_rc [Ohm]: list of resistance values for each RC pair

C_rc [F]: list of capacitance values for each RC pair

For example, with 2 RC pairs:

parameter_values = pybamm.ParameterValues({
    "R_rc [Ohm]": [0.01, 0.005],
    "C_rc [F]": [100, 200],
    ...
})

PyBaMM automatically converts array parameters to indexed format:

{"R_rc [Ohm]": [0.01, 0.005]} becomes {"R_rc (0) [Ohm]": 0.01, "R_rc (1) [Ohm]": 0.005}

Extends: pybamm.models.base_model.BaseModel

static custom_set_initial_state(initial_value, parameter_values, inplace=False, **kwargs)¶

Custom set_initial_state for SingleElectrodeLumpedSPMR.

Converts a voltage string (e.g. “4.2 V”) or SOC float into the "Initial SOC" parameter that the lumped SPMR model expects.

Parameters¶

initial_valuestr or float: Either a voltage string like "4.2 V" or a numeric SOC (0–1).
parameter_valuespybamm.ParameterValues: The parameter values to update.
inplacebool, optional: If False (default), return a copy with the updated SOC.
**kwargs: Additional arguments (e.g. direction, inputs) forwarded by Simulation.set_initial_state; accepted but not used.

property default_geometry¶: Returns a dictionary of the default geometry for the model, which is empty by default.

property default_spatial_methods¶: Returns a dictionary of the default spatial methods for the model, which is empty by default.

property default_submesh_types¶: Returns a dictionary of the default submesh types for the model, which is empty by default.

property default_var_pts¶: Returns a dictionary of the default variable points for the model, which is empty by default.

static get_initial_soc_from_voltage(V_init, parameter_values, solver=None)¶

Calculate initial SOC from target OCP voltage using an algebraic PyBaMM model.

This method numerically inverts the open-circuit voltage (OCP) function to find the SOC that corresponds to a given voltage. It only considers the OCP (with entropic-change temperature correction), not overpotential or ohmic resistance terms.

Parameters¶

V_initfloat: Target open-circuit voltage [V]
parameter_valuesdict or pybamm.ParameterValues: Dictionary of parameter values needed to evaluate the OCP function. Must include: - “Open-circuit voltage [V]”: OCP function - “Open-circuit voltage entropic change [V.K-1]”: entropic coefficient - “Initial temperature [K]”: temperature for OCP evaluation - “Reference temperature [K]”: reference temperature - “Lower voltage cut-off [V]”: minimum voltage (for initial guess) - “Upper voltage cut-off [V]”: maximum voltage (for initial guess)
solverpybamm.Solver, optional: Solver to use for the algebraic equation. Default is AlgebraicSolver()

Returns¶

float: Initial SOC value that produces the target OCP voltage

Examples¶

>>> param_values = {
...     "Open-circuit voltage [V]": ocp_pos,
...     "Open-circuit voltage entropic change [V.K-1]": 0,
...     "Initial temperature [K]": 298.15,
...     "Reference temperature [K]": 298.15,
...     "Lower voltage cut-off [V]": 3.0,
...     "Upper voltage cut-off [V]": 4.2,
... }
>>> soc = SingleElectrodeLumpedSPMR.get_initial_soc_from_voltage(
...     3.8, param_values
... )
>>> 0 < soc < 1
True

static plot_voltage_components(solution, ax=None, show_plot=True, split_rc_pairs=False, **kwargs_fill)¶

Plot voltage components from a solution.

Parameters¶

solutionpybamm.Solution: Solution to plot
axmatplotlib.axes.Axes, optional: Axes to plot on
show_plotbool, optional: Whether to show the plot
split_rc_pairsbool, optional: Whether to show the RC pairs separately. Default is False.
**kwargs_filldict, optional: Keyword arguments for fill_between

class ionworkspipeline.data_fits.models.ECM(options=None)¶

Equivalent Circuit Model

Parameters¶

optionsdict

Dictionary of options to override default options. Options are:

thermal: str, thermal model to use. Can be “isothermal”, “lumped”, or “two-state”. Default is “isothermal”.

rc pairs: str, number of RC pairs to include in the model. Must be a non-negative integer as a string (e.g., “0”, “1”, “2”, “5”, etc.). Default is “0”.
parameter_dependencies: dict, optional. Specifies which variables each parameter depends on. Keys must be in [“OCV”, “R0”, “R_rc”, “C_rc”]. Values are tuples containing any combination of (“soc”, “current”, “temperature”). Empty tuple means the parameter is constant (pybamm.Parameter). Default is all dependencies for backward compatibility.

Example:
# No dependencies - all parameters are constants
{"parameter_dependencies": {
    "OCV": (),
    "R0": (),
    "R_rc": (),
    "C_rc": ()
}}

# Partial dependencies - OCV depends only on SOC
{"parameter_dependencies": {
    "OCV": ("soc",),
    "R0": ("soc", "temperature"),
    "R_rc": ("soc", "temperature"),
    "C_rc": ("soc", "temperature")
}}

Notes¶

The ECM model uses array parameters for RC pairs. Parameters should be specified as:

R_rc [Ohm]: list of resistance values for each RC pair

C_rc [F]: list of capacitance values for each RC pair

For example, with 3 RC pairs:

parameter_values = pybamm.ParameterValues({
    "R_rc [Ohm]": [0.02, 0.002, 0.001],
    "C_rc [F]": [1, 10, 100],
    ...
})

PyBaMM automatically converts array parameters to indexed format:

{"R_rc [Ohm]": [0.02, 0.002]} becomes {"R_rc (0) [Ohm]": 0.02, "R_rc (1) [Ohm]": 0.002}

Extends: pybamm.models.base_model.BaseModel

static custom_set_initial_state(initial_value, parameter_values, inplace=False, **kwargs)¶

Custom set_initial_state for ECM.

Converts a voltage string (e.g. “4.2 V”) or SOC float into the "Initial SOC" parameter that the ECM model expects.

Parameters¶

initial_valuestr or float: Either a voltage string like "4.2 V" or a numeric SOC (0–1).
parameter_valuespybamm.ParameterValues: The parameter values to update.
inplacebool, optional: If False (default), return a copy with the updated SOC.
**kwargs: Additional arguments (e.g. direction, inputs) forwarded by Simulation.set_initial_state; accepted but not used.

static get_initial_soc_from_voltage(V_init, parameter_values, solver=None)¶

Calculate initial SOC from target OCV voltage using an algebraic model.

Parameters¶

V_initfloat: Target open-circuit voltage [V]
parameter_valuesdict or pybamm.ParameterValues: Must include "Open-circuit voltage [V]" and voltage cut-offs.
solverpybamm.Solver, optional: Defaults to pybamm.AlgebraicSolver().

Returns¶

float: Initial SOC that produces the target OCV.

Models¶

Model Classes¶

Parameters¶

Parameters¶

Parameters¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Parameters¶

Parameters¶

Returns¶

Parameters¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Parameters¶

Parameters¶

Parameters¶

Notes¶

Parameters¶

Parameters¶

Returns¶

Examples¶

Parameters¶

Parameters¶

Notes¶

Parameters¶

Parameters¶

Returns¶

Submodules¶

This Page