Simulation

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

A Simulation class for easy building and running of PyBaMM simulations.

Parameters:

• model (pybamm.BaseModel) – The model to be simulated

• experiment (pybamm.Experiment or string or list (optional)) – The experimental conditions under which to solve the model. If a string is passed, the experiment is constructed as pybamm.Experiment([experiment]). If a list is passed, the experiment is constructed as pybamm.Experiment(experiment).

• geometry (pybamm.Geometry (optional)) – The geometry upon which to solve the model

• parameter_values (pybamm.ParameterValues (optional)) – Parameters and their corresponding numerical values.

• submesh_types (dict (optional)) – A dictionary of the types of submesh to use on each subdomain

• var_pts (dict (optional)) – A dictionary of the number of points used by each spatial variable

• spatial_methods (dict (optional)) – A dictionary of the types of spatial method to use on each domain (e.g. pybamm.FiniteVolume)

• solver (pybamm.BaseSolver (optional)) – The solver to use to solve the model.

• output_variables (list (optional)) – A list of variables to plot automatically

• C_rate (float (optional)) – The C-rate at which you would like to run a constant current (dis)charge.

• discretisation_kwargs (dict (optional)) – Any keyword arguments to pass to the Discretisation class. See pybamm.Discretisation for details.

build(initial_soc=None, inputs=None)

A method to build the model into a system of matrices and vectors suitable for performing numerical computations. If the model has already been built or solved then this function will have no effect. This method will automatically set the parameters if they have not already been set.

Parameters:

• initial_soc (float, optional) – Initial State of Charge (SOC) for the simulation. Must be between 0 and 1. If given, overwrites the initial concentrations provided in the parameter set.

• inputs (dict, optional) – A dictionary of input parameters to pass to the model when solving.

build_for_experiment(initial_soc=None, inputs=None, solve_kwargs=None)

Similar to Simulation.build(), but for the case of simulating an experiment, where there may be several models and solvers to build.

create_gif(number_of_images=80, duration=0.1, output_filename='plot.gif')

Generates x plots over a time span of t_eval and compiles them to create a GIF. For more information see pybamm.QuickPlot.create_gif()

Parameters:

• number_of_images (int (optional)) – Number of images/plots to be compiled for a GIF.

• duration (float (optional)) – Duration of visibility of a single image/plot in the created GIF.

• output_filename (str (optional)) – Name of the generated GIF file.

plot(output_variables=None, **kwargs)

A method to quickly plot the outputs of the simulation. Creates a pybamm.QuickPlot object (with keyword arguments ‘kwargs’) and then calls pybamm.QuickPlot.dynamic_plot().

Parameters:

• output_variables (list, optional) – A list of the variables to plot.

• **kwargs – Additional keyword arguments passed to pybamm.QuickPlot.dynamic_plot(). For a list of all possible keyword arguments see pybamm.QuickPlot.

plot_voltage_components(ax=None, show_legend=True, split_by_electrode=False, show_plot=True, **kwargs_fill)

Generate a plot showing the component overpotentials that make up the voltage

Parameters:

• ax (matplotlib Axis, optional) – The axis on which to put the plot. If None, a new figure and axis is created.

• show_legend (bool, optional) – Whether to display the legend. Default is True.

• split_by_electrode (bool, optional) – Whether to show the overpotentials for the negative and positive electrodes separately. Default is False.

• show_plot (bool, optional) – Whether to show the plots. Default is True. Set to False if you want to only display the plot after plt.show() has been called.

• kwargs_fill – Keyword arguments, passed to ax.fill_between.

save(filename)

Save simulation using pickle module.

Parameters:

filename (str) – The file extension can be arbitrary, but it is common to use “.pkl” or “.pickle”

save_model(filename: str | None = None, mesh: bool = False, variables: bool = False)

Write out a discretised model to a JSON file

Parameters:

• mesh (bool) – The mesh used to discretise the model. If false, plotting tools will not be available when the model is read back in and solved.

• variables (bool) – The discretised variables. Not required to solve a model, but if false tools will not be available. Will automatically save meshes as well, required for plotting tools.

• filename (str, optional) – The desired name of the JSON file. If no name is provided, one will be created based on the model name, and the current datetime.

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

A method to solve the model. This method will automatically build and set the model parameters if not already done so.

Parameters:

• t_eval (numeric type, optional) –

  The times at which to stop the integration due to a discontinuity in time. Can be provided as an array of times at which to return the solution, or as a list [t0, tf] where t0 is the initial time and tf is the final time. If the solver does not support intra-solve interpolation, providing t_eval as a list returns the solution at 100 points within the interval [t0, tf]. Otherwise, the solution is returned at the times specified in t_interp or as a result of the adaptive time-stepping solution. See the t_interp argument for more details.

  If not using an experiment or running a drive cycle simulation (current provided as data) t_eval must be provided.

  If running an experiment the values in t_eval are ignored, and the solution times are specified by the experiment.

  If None and the parameter “Current function [A]” is read from data (i.e. drive cycle simulation) the model will be solved at the times provided in the data.

• solver (pybamm.BaseSolver, optional) – The solver to use to solve the model. If None, Simulation.solver is used

• save_at_cycles (int or list of ints, optional) – Which cycles to save the full sub-solutions for. If None, all cycles are saved. If int, every multiple of save_at_cycles is saved. If list, every cycle in the list is saved. The first cycle (cycle 1) is always saved.

• calc_esoh (bool, optional) – Whether to include eSOH variables in the summary variables. If False then only summary variables that do not require the eSOH calculation are calculated. Default is True.

• starting_solution (pybamm.Solution) – The solution to start stepping from. If None (default), then self._solution is used. Must be None if not using an experiment.

• initial_soc (float, optional) – Initial State of Charge (SOC) for the simulation. Must be between 0 and 1. If given, overwrites the initial concentrations provided in the parameter set.

• callbacks (list of callbacks, optional) – A list of callbacks to be called at each time step. Each callback must implement all the methods defined in pybamm.callbacks.BaseCallback.

• showprogress (bool, optional) – Whether to show a progress bar for cycling. If true, shows a progress bar for cycles. Has no effect when not used with an experiment. Default is False.

• t_interp (None, list or ndarray, optional) – The times (in seconds) at which to interpolate the solution. Defaults to None. Only valid for solvers that support intra-solve interpolation (IDAKLUSolver).

• **kwargs – Additional key-word arguments passed to solver.solve. See pybamm.BaseSolver.solve().

step(dt, solver=None, t_eval=None, save=True, starting_solution=None, inputs=None, **kwargs)

A method to step the model forward one timestep. This method will automatically build and set the model parameters if not already done so.

Parameters:

• dt (numeric type) – The timestep over which to step the solution

• solver (pybamm.BaseSolver) – The solver to use to solve the model.

• t_eval (list or numpy.ndarray, optional) – An array of times at which to return the solution during the step (Note: t_eval is the time measured from the start of the step, so should start at 0 and end at dt). By default, the solution is returned at t0 and t0 + dt.

• save (bool) – Turn on to store the solution of all previous timesteps

• starting_solution (pybamm.Solution) – The solution to start stepping from. If None (default), then self._solution is used

• **kwargs – Additional key-word arguments passed to solver.solve. See pybamm.BaseSolver.step().