Simulation

The Simulation class is the primary entry point for running PyBaMM simulations. It wraps a model together with parameter values, a solver, and optional experimental conditions, and exposes a simple .solve() → .plot() workflow.

Class signature

pybamm.Simulation(
    model,
    experiment=None,
    geometry=None,
    parameter_values=None,
    submesh_types=None,
    var_pts=None,
    spatial_methods=None,
    solver=None,
    output_variables=None,
    C_rate=None,
    discretisation_kwargs=None,
    cache_esoh=True,
)

Constructor parameters

model

pybamm.BaseModel

required

The model to be simulated. For example pybamm.lithium_ion.DFN() or pybamm.lithium_ion.SPM().

experiment

pybamm.Experiment | str | list

Experimental conditions under which to solve the model. Accepts a pybamm.Experiment instance, a single step string, or a list of step strings. If omitted, the simulation runs a simple constant-current (dis)charge controlled by parameter_values.

geometry

pybamm.Geometry

The geometry on which to solve the model. Defaults to model.default_geometry.

parameter_values

pybamm.ParameterValues

Parameter set to use. Defaults to model.default_parameter_values.

submesh_types

dict

Mapping of subdomain names to submesh classes. Defaults to model.default_submesh_types.

var_pts

dict

Number of mesh points for each spatial variable. Defaults to model.default_var_pts.

spatial_methods

dict

Mapping of domain names to spatial method instances (e.g. pybamm.FiniteVolume). Defaults to model.default_spatial_methods.

solver

pybamm.BaseSolver

The solver to use. Defaults to model.default_solver.

output_variables

list[str]

Variable names to plot automatically when plot() is called without arguments.

C_rate

float

C-rate for a constant-current (dis)charge. Only used when experiment is None. Sets Current function [A] in parameter_values to C_rate * Nominal cell capacity [A.h].

discretisation_kwargs

dict

Extra keyword arguments forwarded to pybamm.Discretisation. See pybamm.Discretisation for details.

cache_esoh

bool

default:"True"

Whether to cache the electrode state-of-health (eSOH) solver between calls to solve(). Disabling this forces eSOH to be recomputed on every call, which is useful when parameters are modified in-place between solves.

Methods

`solve()`

Build the model (if not already built) and run the solver. Returns a pybamm.Solution object.

sim.solve(
    t_eval=None,
    solver=None,
    save_at_cycles=None,
    calc_esoh=None,
    starting_solution=None,
    initial_soc=None,
    direction=None,
    callbacks=None,
    showprogress=False,
    inputs=None,
    t_interp=None,
    **kwargs,
)

t_eval

array-like | list

Times at which to return the solution. Required when not using an experiment or drive cycle. Can be [t0, tf] (returns 100 points) or a full array. Ignored when using an experiment.

solver

pybamm.BaseSolver

Override the solver for this call only.

save_at_cycles

int | list[int]

Which experiment cycles to store full sub-solutions for. Only valid when using an experiment. None saves all cycles.

calc_esoh

bool

Whether to compute eSOH (electrode state-of-health) summary variables. Overrides the model default.

starting_solution

pybamm.Solution

Resume stepping from a previous solution. Only valid when using an experiment.

initial_soc

float

Initial State of Charge between 0 and 1. Overwrites initial concentrations from the parameter set.

callbacks

list

Callback objects called at each time step. Each must implement all methods from pybamm.callbacks.BaseCallback.

showprogress

bool

default:"false"

Show a progress bar over cycles. Has no effect without an experiment.

t_interp

array-like

Times (in seconds) at which to interpolate the solution. Only valid for solvers that support intra-solve interpolation (IDAKLUSolver).

`build()`

Discretise the model into matrices and vectors. Called automatically by solve(). Use this to pre-build the model and inspect the discretised form.

sim.build(initial_soc=None, direction=None, inputs=None)

initial_soc

float

Initial SOC between 0 and 1. Sets electrode stoichiometries via the eSOH solver.

`plot()`

Create an interactive pybamm.QuickPlot and call dynamic_plot().

sim.plot(output_variables=None, **kwargs)

output_variables

list[str]

Variable names to include. Defaults to sim.output_variables if set.

plot() raises ValueError if the model has not been solved yet.

`save()` and `pybamm.load_sim()`

Persist and reload a simulation using Python’s pickle module.

sim.save("my_simulation.pkl")

sim2 = pybamm.load_sim("my_simulation.pkl")

filename

str

required

File path. Common extensions are .pkl or .pickle. Models using convert_to_format = 'python' cannot be saved.

`save_model()`

Write the built, discretised model to a JSON file for later use without rebuilding.

sim.save_model(filename=None, mesh=False, variables=False)

filename

str

Output JSON file path. Auto-generated from the model name and current datetime if not provided.

mesh

bool

default:"false"

Include the mesh in the saved file (required for plotting after reloading).

variables

bool

default:"false"

Include discretised variables in the saved file. Also saves the mesh.

save_model() requires the model to be built first. Call sim.build() before saving. Experiments are not yet supported.

`set_initial_state()`

Set the initial state of charge or lithiation direction before building.

sim.set_initial_state(initial_soc, direction=None, inputs=None)

initial_soc

float

required

Target SOC between 0 and 1.

direction

str

"discharge" or "charge" — the lithiation direction used by the eSOH solver.

Properties

solution

pybamm.Solution | None

The most recent solution returned by solve(). None before the first solve.

model

pybamm.BaseModel

The model (with parameters set if build() has been called).

parameter_values

pybamm.ParameterValues

The parameter values currently in use.

solver

pybamm.BaseSolver

The solver instance.

built_model

pybamm.BaseModel | None

The fully discretised model. None until build() or solve() is called.

mesh

pybamm.Mesh | None

The mesh used for discretisation.

Examples

import pybamm

model = pybamm.lithium_ion.SPM()
sim = pybamm.Simulation(model)

# Solve for 1 hour (3600 s)
sim.solve([0, 3600])

sim.plot()

Core

Models

Parameters

Solvers

Spatial Methods & Mesh

Plotting

Utilities

Class signature

Constructor parameters

Methods

`solve()`

`build()`

`plot()`

`save()` and `pybamm.load_sim()`

`save_model()`

`set_initial_state()`

Properties

Examples

Build docs developers (and LLMs) love

Core

Models

Parameters

Solvers

Spatial Methods & Mesh

Plotting

Utilities

​Class signature

​Constructor parameters

​Methods

​solve()

​build()

​plot()

​save() and pybamm.load_sim()

​save_model()

​set_initial_state()

​Properties

​Examples

Build docs developers (and LLMs) love

Class signature

Constructor parameters

Methods

`solve()`

`build()`

`plot()`

`save()` and `pybamm.load_sim()`

`save_model()`

`set_initial_state()`

Properties

Examples