Models

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

Schemas for models.

class ionworks_schema.models.ECM(options=None)

Bases: BaseSchema

A class for the Equivalent Circuit Model.

Extends: ionworks_schema.base.BaseSchema

options: dict[str, 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 initialise 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)

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

optionsdict, optional

Model options. "working electrode" may be "both" (default) or "positive" and selects the cell configuration as described above. Any remaining options are forwarded to the underlying battery-model options for parameter bookkeeping; the governing equations of this model are fixed (diffusion-only), so options that select submodels have no effect on the physics.

Extends: ionworks_schema.base.BaseSchema

options: dict[str, 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 initialise 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)

Bases: BaseSchema

A class for the Lumped Single Particle Model with Resistance.

Extends: ionworks_schema.base.BaseSchema

options: dict[str, 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 initialise 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)

Bases: BaseSchema

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

Extends: ionworks_schema.base.BaseSchema

options: dict[str, 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 initialise 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)

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.

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

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 initialise 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)

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".

optionsdict, optional

Model settings:

• capacity function: capacity function used by the model.

  Default None.

• species format: how each MSMR species is parameterised —

  "Qj" (capacity) or "Xj" (mole fraction). Default "Qj".

• direction: "delithiation", "lithiation", or None

  (no direction assumed). Default None.

• particle phases: number of phases in the electrode —

  "1" for a single-phase electrode (default) or "2" for a composite with primary and secondary phases.

Extends: ionworks_schema.base.BaseSchema

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

options: dict[str, 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 initialise 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)

Bases: BaseSchema

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

Extends: ionworks_schema.base.BaseSchema

options: dict[str, 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 initialise 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.