Models

Schemas for battery models supported by the pipeline. Mirrors ionworkspipeline.models.

Schemas for models.

class ionworks_schema.models.ECM(options=None, simulation_settings=None)

Bases: BaseSchema

A class for the Equivalent Circuit Model.

Parameters

optionsECMOptions or dict, optional

See ECMOptions for the available keys.

simulation_settingsSimulationSettings or dict, optional

Persistent simulation settings (mesh + solver) re-applied at simulation time. When None the model defaults are used.

Extends: ionworks_schema.base.BaseSchema

options: ECMOptions | None

simulation_settings: Annotated[SimulationSettings | dict[str, Any], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.

class ionworks_schema.models.GITTModel(options=None, simulation_settings=None)

Bases: BaseSchema

Diffusion-only model for fitting solid diffusivities to GITT or pulse data.

The model solves x-averaged spherical particle diffusion in each modelled electrode, with the surface flux set by the applied current, and computes the cell voltage from the electrode open-circuit potentials evaluated at the particle surface stoichiometries, minus an ohmic drop through a single lumped "Ohmic resistance [Ohm]" parameter. There are no reaction kinetics (Butler-Volmer), no electrolyte dynamics, and no thermal effects; all parameters are constant except the open-circuit potentials.

The "working electrode" option selects the cell configuration:

• "both" (default): full cell. Both electrodes are modelled and the voltage is the difference of their open-circuit potentials minus the ohmic drop. A positive (discharge) current delithiates the negative electrode and lithiates the positive electrode.

• "positive": half-cell against a lithium-metal counter electrode, following the pybamm half-cell convention. Only the working electrode is modelled (the counter electrode contributes no overpotential) and the voltage is its open-circuit potential minus the ohmic drop. A positive (discharge) current lithiates the working electrode. As in pybamm, anode-material half cells are also expressed with "positive" — rename the anode’s parameters to the positive convention first.

This is a fitting model intended for extracting solid-phase diffusivities (and the lumped ohmic resistance) from GITT or pulse-relaxation measurements — it is not a general-purpose simulation model. Each modelled electrode is parameterised with the standard full-cell parameter names (thickness, active material volume fraction, particle radius, diffusivity, OCP, maximum and initial concentrations) plus the current function, electrode cross-sectional area, initial temperature, and "Ohmic resistance [Ohm]".

Parameters

optionsGITTModelOptions or dict, optional

See GITTModelOptions for the available keys.

simulation_settingsSimulationSettings or dict, optional

Persistent simulation settings (mesh + solver) re-applied at simulation time. When None the model defaults are used.

Extends: ionworks_schema.base.BaseSchema

options: GITTModelOptions | None

simulation_settings: Annotated[SimulationSettings | dict[str, Any], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.

class ionworks_schema.models.LumpedSPMR(options=None, simulation_settings=None)

Bases: BaseSchema

A class for the Lumped Single Particle Model with Resistance.

Extends: ionworks_schema.base.BaseSchema

options: LumpedSPMROptions | None

simulation_settings: Annotated[SimulationSettings | dict[str, Any], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.

class ionworks_schema.models.LumpedSPMeR(options=None, simulation_settings=None)

Bases: BaseSchema

A class for the Lumped Single Particle Model with electrolyte and Resistance.

Extends: ionworks_schema.base.BaseSchema

options: LumpedSPMROptions | None

simulation_settings: Annotated[SimulationSettings | dict[str, Any], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.

class ionworks_schema.models.MSMRFullCellModel(negative_electrode_model, positive_electrode_model, options=None, simulation_settings=None)

Bases: BaseSchema

Full-cell MSMR model of the open-circuit potential — pairs a negative and positive half-cell MSMR model into one full-cell OCV.

Use this with MSMRFullCell to fit an MSMR description of a full cell from full-cell OCV data.

Parameters

negative_electrode_modelMSMRHalfCellModel

MSMR model for the negative electrode.

positive_electrode_modelMSMRHalfCellModel

MSMR model for the positive electrode.

optionsdict, optional

Extra options forwarded to the underlying model.

simulation_settingsSimulationSettings or dict, optional

Persistent simulation settings (mesh + solver) re-applied at simulation time. When None the model defaults are used.

Extends: ionworks_schema.base.BaseSchema

negative_electrode_model: Annotated[dict[str, Any] | BaseSchema, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]

positive_electrode_model: Annotated[dict[str, Any] | BaseSchema, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]

options: dict[str, Any] | None

simulation_settings: Annotated[SimulationSettings | dict[str, Any], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.

class ionworks_schema.models.MSMRHalfCellModel(electrode, options=None, simulation_settings=None)

Bases: BaseSchema

Half-cell MSMR (Multi-Species Multi-Reaction) model for one electrode’s open-circuit potential.

Parameters

electrodestr

Electrode the model describes — "positive" or "negative".

optionsMSMRHalfCellModelOptions or dict, optional

See MSMRHalfCellModelOptions for the available keys.

simulation_settingsSimulationSettings or dict, optional

Persistent simulation settings (mesh + solver) re-applied at simulation time. When None the model defaults are used.

For a composite electrode (particle phases = "2") the lower excess may be given either as a per-phase split (Primary/Secondary: {Electrode} electrode lower excess capacity [A.h], summed) when it is known from another source, or as a single electrode-level {Electrode} electrode lower excess capacity [A.h] when it is not.

Extends: ionworks_schema.base.BaseSchema

electrode: Literal['positive', 'negative']

options: MSMRHalfCellModelOptions | None

simulation_settings: Annotated[SimulationSettings | dict[str, Any], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.

class ionworks_schema.models.SimulationSettings(var_pts=None, submesh_types=None, spatial_methods=None, geometry=None, solver=None)

Bases: BaseSchema

Persistent simulation settings attached to a model or parameterized model.

A flat bag of pybamm Simulation keyword arguments that should be applied whenever this (parameterized) model is simulated. The fields mirror the pybamm kwargs exactly, so the serialized form is folded straight into simulation_kwargs at solve time with no reshaping.

The required settings are parameter-dependent: a fitted solid diffusivity with a steep near-surface gradient needs a refined, surface-clustered particle mesh (and sometimes a specific solver) that the model defaults do not provide. All fields are optional; a higher-precedence source merges over a lower one per key, so a parameterized model can refine just r_n / r_p (or swap the solver) without restating everything.

Parameters

var_ptsdict of str to int, optional

Number of mesh points per spatial variable, e.g. {"r_n": 16, "r_p": 16}. Stored as a plain JSON dict of ints.

submesh_typesdict, optional

Mapping of domain name (e.g. "negative particle") to a serialized submesh — a pybamm.MeshGenerator.to_config() payload ({"$type": "type", "class": ..., "submesh_params": {...}}). A live {domain: pybamm.MeshGenerator} mapping is accepted at construction and serialized to this form by to_config().

spatial_methodsdict, optional

Mapping of domain name to a serialized pybamm.SpatialMethod.

geometrydict, optional

Serialized geometry override. Rarely needed; when absent the geometry is derived from the model.

solverdict, optional

Serialized solver configuration (pybamm.BaseSolver.to_config() form — the solver class name under "type" plus its tolerances/options). A live pybamm.BaseSolver is accepted and serialized by to_config().

Notes

to_config() emits the flat canonical form — plain var_pts ints and submesh_types as a flat per-domain map — with no "type" discriminator, so the block is a plain nested dict ready to use as simulation_kwargs.

Extends: ionworks_schema.base.BaseSchema

var_pts: dict[str, int] | None

submesh_types: dict[str, Any] | None

spatial_methods: dict[str, Any] | None

geometry: dict[str, Any] | None

solver: Any | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.

class ionworks_schema.models.SingleElectrodeLumpedSPMR(options=None, simulation_settings=None)

Bases: BaseSchema

A class for the single-electrode Lumped SPM with Resistance.

Extends: ionworks_schema.base.BaseSchema

options: SingleElectrodeLumpedSPMROptions | None

simulation_settings: Annotated[SimulationSettings | dict[str, Any], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.