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 can reference the same Model configuration. This allows you to create different parameter sets for the same mathematical model without duplicating the model configuration.

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.

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.

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.

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:

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

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.

You can define derived quantities like temperature in Celsius or electrode potentials using Custom Variables.

Next Steps

Once you have a Model, you can create a Parameterized Model by combining it with specific parameters for your cell chemistry and design.