> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Create reusable PyBaMM model configurations (SPM, SPMe, DFN) with options and version pinning for battery simulations

A **Model** in Ionworks is a mathematical model configuration that defines the
structure and equations used to simulate battery behavior. Models specify:

* **PyBaMM Model Type**: The underlying mathematical model (e.g., `SPM`, `SPMe`, `DFN`)
* **Model Options**: Configuration options that modify the model's behavior
* **PyBaMM Version**: Automatically set to the current PyBaMM version when the model is created (not user-specifiable)
* **Cell Compatibility**: Whether the model works with full cells, half cells, or both

Models are reusable—multiple [Parameterized Models](/build/parameterized-models)
can reference the same Model configuration. This allows you to create different
parameter sets for the same mathematical model without duplicating the model
configuration.

<Note>
  **Models are Immutable**

  Once a model is created and used in a parameterized model or simulation, its
  configuration (PyBaMM model type, options, version) cannot be changed. This
  ensures reproducibility—parameterized models and simulations are permanently
  linked to the exact model version that was used.

  To modify a model's configuration, you must create a new model. Only the name
  and description can be updated after creation.
</Note>

### Creating a Model

Models can be created in two ways:

1. **Use System Models**: Ionworks provides pre-created system models for common PyBaMM model types (SPM, SPMe, DFN) in both full-cell and half-cell configurations. These are available to all users and are the recommended starting point for most use cases.

2. **Create Custom Models**: You can create custom models with specific configurations and options. This is useful when you need to customize model options.

<Info>
  **System Models**: Ionworks automatically includes system models when you list
  models in your organization. These include: - **Full Cell**: SPM, SPMe, DFN,
  LumpedSPMR, LumpedSPMeR, ECM, plus **SPM Composite**, **SPMe Composite**, and
  **DFN Composite** for blended (two-phase) negative electrodes - **Half Cell**:
  SPM, SPMe, DFN, ECM. You can use these system models directly without creating
  your own.
</Info>

### Available Model Types

Ionworks supports several electrochemical models, each offering different levels
of detail and computational complexity:

#### PyBaMM Standard Models

**SPM (Single Particle Model)**
: The simplest model that represents each electrode as a single, average-sized
spherical particle. It focuses on solid-phase diffusion within particles and
assumes uniform electrolyte concentration and potential, neglecting electrolyte
dynamics. This model is computationally efficient and suitable for
applications where electrolyte variations are minimal.

**SPMe (Single Particle Model with Electrolyte)**
: Builds upon the SPM by incorporating electrolyte dynamics, accounting for
variations in electrolyte concentration and potential across the cell. This
enhancement provides more accurate representation of battery behavior,
especially under conditions where electrolyte effects are significant. The SPMe
balances computational efficiency with improved accuracy.

**DFN (Doyle-Fuller-Newman Model)**
: The most comprehensive model that considers multiple spherical particles
within each electrode, solid-phase diffusion, electrolyte dynamics, and
Butler-Volmer kinetics. This detailed approach captures intricate interactions
within the battery but requires more computational resources. Best for
applications requiring high accuracy and detailed understanding of internal
processes.

**SPM Composite, SPMe Composite, DFN Composite (Full Cell)**
: Variants of SPM, SPMe, and DFN configured for **composite (blended) negative
electrodes** with two particle phases — for example, graphite + silicon
anodes. Each model is created with the PyBaMM options:

```json theme={null}
{
  "particle phases": ["2", "1"],
  "open-circuit potential": [["single", "current sigmoid"], "single"],
  "particle mechanics": "swelling only"
}
```

Use these system models when your cell has a blended anode that requires a
current-sigmoid OCP for the secondary phase and swelling mechanics. They share
the same custom variables (`Temperature [degC]`, `Anode potential [V]`,
`Cathode potential [V]`) as the standard full-cell models, so existing
parameterized models, optimizations, and validations work without changes.

#### Ionworks Models

**LumpedSPMR (Lumped Single Particle Model with Resistance)**
: An enhanced single particle model that includes resistance effects and
supports thermal modeling. This model represents both electrodes, each as a
single spherical particle, and includes lumped resistance terms. It supports
thermal options ("isothermal" or "lumped") and surface temperature options
("ambient" or "lumped"). Available for full cell configurations only.

**LumpedSPMeR (Lumped Single Particle Model with Electrolyte and Resistance)**
: Builds upon LumpedSPMR by incorporating electrolyte dynamics. This model
adds electrolyte concentration overpotential using a tanks-in-series approach
for volume-averaged electrolyte equations, accounting for concentration
variations across negative electrode, separator, and positive electrode
regions. It provides improved accuracy for conditions where electrolyte
effects are significant while maintaining computational efficiency. Supports
the same thermal and surface temperature options as LumpedSPMR. Available for
full cell configurations only.

**ECM (Equivalent Circuit Model)**
: A circuit-based model that represents the battery as an equivalent electrical
circuit with an open-circuit voltage (OCV) source and resistance-capacitance
(RC) pairs. This model is computationally very efficient and useful for
control applications and real-time simulations. Supports configurable RC pairs
and thermal modeling options ("isothermal", "lumped", or "two-state").
Available for both full cell and half cell configurations.

The ECM also supports an optional **throughput-based degradation model**: set
`"capacity"` and/or `"resistance scale"` to `"function"` (both default to
`"constant"`) and supply a function of `(Q_throughput, time)` — the running
capacity throughput `∫|I| dt` in A·h and elapsed simulation time in seconds —
for `Capacity [A.h]` and/or `Resistance scale`, a multiplier applied to `R0`
and every `R_rc`. `ionworkspipeline` ships `iwp.models.linear_capacity_loss`
and `iwp.models.linear_resistance_increase` for a simple "X% loss per
equivalent cycle" model, paired with the `"... per equivalent cycle [%]"`
parameters; these are unbounded; for a bounded or calendar-aging model, write
a custom function instead. A degradation-enabled solution exposes
`Capacity throughput [A.h]` (when either option is `"function"`),
`Capacity [A.h]` (when `"capacity"` is `"function"`), and `Resistance scale`
(when `"resistance scale"` is `"function"`) as extra output variables —
reading one while its option is left at `"constant"` raises a
missing-variable error rather than returning a default value. See the
[degradation primer](/guide/batteries-101/degradation) for the physics
behind capacity fade and resistance growth.

The ECM also exposes reconstructed electrode potentials as outputs
(`Anode potential [V]` and `Cathode potential [V]`), which is useful for
reproducing working-electrode and counter-electrode control modes — for
example, the BioLogic EWE (working-electrode voltage) and ECE
(counter-electrode voltage) limits. The total cell overpotential is split
between the two electrodes using the **Anode overpotential fraction**
parameter (`0` to `1`). Use `0` when the anode is a non-polarisable
reference (e.g. a Li metal counter electrode in a half cell), or `1` when
the cathode is the non-polarisable reference. Intermediate values are a
rough approximation only.

To use this output, your parameter set must also define
`Anode open-circuit potential [V]` and `Cathode open-circuit potential [V]`
as functions of state of charge. Built-in chemistry parameter sets (e.g.
`NMC/Graphite`, `LFP/Graphite`, `LFP/Li metal`) populate these
automatically; ECM fits from the [ECM Parameterization](/build/ecm-parameterization)
tool default to anode = 0 and cathode = OCV so that
`Cathode potential − Anode potential = Voltage` by construction.

### Model Options and Capabilities

Models can be configured with various options to customize their behavior:

* **Thermal modeling**: Some models support "isothermal" (constant
  temperature), "lumped" (single temperature state), or "two-state" thermal
  options
* **Surface temperature**: LumpedSPMR and LumpedSPMeR support "ambient" or
  "lumped" surface temperature modeling
* **RC pairs**: ECM supports configurable resistance-capacitance (RC) pairs to
  capture dynamic polarization behavior
* **Parameter dependencies**: ECM allows parameters to depend on variables like
  SOC, current, or temperature
* **Working electrode**: PyBaMM standard models (SPM, SPMe, DFN) for half-cell
  configurations use the "positive" working electrode option

### Editing Models

**Models** can have their name and description updated, but the model
configuration (PyBaMM model type, options, version) cannot be changed after
creation. This immutability ensures reproducibility—any parameterized model or
simulation using a model will always reference the exact same model
configuration.

To modify a model's configuration, you must create a new model.

<Note>
  You can define derived quantities like temperature in Celsius or electrode potentials using [Custom Variables](/build/custom-variables).
</Note>

### Next Steps

Once you have a Model, you can create a [Parameterized
Model](/build/parameterized-models) by combining it with specific parameters for
your cell chemistry and design.