pybop.pybamm#

Submodules#

Classes#

`EISSimulator`	A class to extend a PyBaMM model for EIS, automatically build/rebuild a pybamm.Simulation to obtain
`RecommendedSolver`	A shortcut for creating the PyBaMM solver recommended for optimisation.
`Simulator`	A class to automatically build/rebuild and solve a pybamm.Simulation for a given model and protocol.
`SymbolReplacer`	Helper class to replace all instances of one or more symbols in an expression tree

Functions#

`add_variable_to_model`(model, variable[, target_time])	Supplement a lithium-ion model with a design variable.
`cell_mass`(→ pybamm.Symbol)	An expression for the total cell mass in kilograms.
`cell_volume`(→ pybamm.Symbol)	An expression for the total cell volume in m3.
`set_formation_concentrations`(→ None)	Compute the concentration of lithium in the positive electrode assuming that

Package Contents#

class pybop.pybamm.EISSimulator(model: pybamm.BaseModel, f_eval: numpy.ndarray | list[float], parameter_values: pybamm.ParameterValues | None = None, initial_state: float | str | None = None, solver: pybamm.BaseSolver | None = None, geometry: pybamm.Geometry | None = None, submesh_types: dict | None = None, var_pts: dict | None = None, spatial_methods: dict | None = None, discretisation_kwargs: dict | None = None, build_every_time: bool = False)[source]#

Bases: pybop.simulators.base_simulator.BaseSimulator

A class to extend a PyBaMM model for EIS, automatically build/rebuild a pybamm.Simulation to obtain a built model which can be solved to compute the complex impedance for a given set of frequencies.

There are two contexts in which this class can be used: 1. A pybamm model can be built once and then run multiple times with different inputs. 2. A pybamm model needs to be built and then run for each set of inputs, for example in the case

where one of the inputs is a geometric parameter which requires a new mesh.

The logic for (1) and (2) occurs within the composed Simulator and happens automatically. To override this logic, the argument build_every_time can be set to True which will force (2) to occur.

Parameters:

model (pybamm.BaseModel) – The PyBaMM model to be used.
f_eval (list) – The frequencies at which to evaluate the impedance.
parameter_values (pybamm.ParameterValues, optional) – The parameter values to be used in the model.
initial_state (dict, optional) – A valid initial state, e.g. “Initial open-circuit voltage [V]” or ``”Initial SoC”`. Defaults to None, indicating that the existing initial state of charge (for an ECM) or initial concentrations (for an EChem model) will be used.
solver (pybamm.BaseSolver, optional) – The solver to simulate the composed Simulator. If None, uses pybop.pybamm.RecommendedSolver.
geometry (pybamm.Geometry, optional) – The geometry upon which to solve the model.
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).
discretisation_kwargs (dict, optional) – Any keyword arguments to pass to the Discretisation class. See pybamm.Discretisation for details.
build_every_time (bool, optional) – If True, the model will be rebuilt every evaluation. Otherwise, the need to rebuild will be determined automatically.

_catch_errors(inputs: list[Inputs]) → list[pybop.simulators.base_simulator.Solution | pybop.simulators.failed_solution.FailedSolution][source]#

_initialise_eis_matrices(inputs: pybop.parameters.parameter.Inputs) → None[source]#

Initialise the electrochemical impedance spectroscopy (EIS) simulation. This method sets up the mass matrix and solver, converts inputs to the appropriate format, extracts the necessary attributes from the model, and prepares matrices for the simulation.

Raises:: RuntimeError – If the model hasn’t been built yet.

_model_rebuild(inputs: pybop.parameters.parameter.Inputs) → None[source]#: Update the parameter values and rebuild the EIS model.

_solve(inputs: pybop.parameters.parameter.Inputs) → pybop.simulators.base_simulator.Solution[source]#

Run the EIS simulation to calculate impedance at all specified frequencies.

Parameters:

inputs (Inputs) – Input parameters.
calculate_sensitivities (bool) – Whether to calculate sensitivities (default: False). Currently not implemented for EIS.

Returns:

Complex impedance results.

Return type:

Solution

calculate_impedance(frequency)[source]#

Calculate the impedance for a given frequency.

This method computes the system matrix, solves the linear system, and calculates the impedance based on the solution.

Parameters:: frequency (float) – The frequency at which to calculate the impedance in Hz.
Returns:: The calculated impedance.
Return type:: complex

copy()[source]#: Return a copy of the simulation.

set_up_for_eis(model: pybamm.BaseModel) → pybamm.BaseModel[source]#

Set up the model for electrochemical impedance spectroscopy (EIS) simulations. This method adds the necessary algebraic equations and variables to the model. Originally developed by pybamm-eis: pybamm-team/pybamm-eis

Parameters:: model (pybamm.BaseModel) – The PyBaMM model to be used for EIS simulations.
Returns:: The modified model ready for EIS simulations.
Return type:: pybamm.BaseModel
Raises:: ValueError – If the model is missing required variables.

solve(inputs: Inputs | list[Inputs] | None = None, calculate_sensitivities: bool = False) → pybop.simulators.base_simulator.Solution | list[pybop.simulators.base_simulator.Solution][source]#

Run the EIS simulation for one or more sets of inputs and return the result(s).

Parameters:

inputs (Inputs | list[Inputs], optional) – Input parameters (default: None).
calculate_sensitivities (bool) – Whether to also return the sensitivities (default: False). Currently not implemented for EIS.

Returns:

Complex impedance results.

Return type:

Solution | list[Solution]

solve_batch(inputs: list[Inputs] = None, calculate_sensitivities: bool = False) → list[pybop.simulators.base_simulator.Solution | pybop.simulators.failed_solution.FailedSolution][source]#

Run the EIS simulation for each set of inputs and return dict-like results.

Parameters:

inputs (list[Inputs]) – A list of input parameters.
calculate_sensitivities (bool) – Whether to calculate sensitivities (default: False). Currently not implemented for EIS.

Returns:

A list of len(inputs) containing the complex impedance results.

Return type:

list[Solution]

M = None#

_f_eval#

_jac = None#

_simulator#

b = None#

property debug_mode#

property has_sensitivities#

property input_parameter_names#

property parameter_values#

property simulation#

z_scale#

class pybop.pybamm.RecommendedSolver(output_variables: list[str] | None = None)[source]#

Bases: pybamm.IDAKLUSolver

A shortcut for creating the PyBaMM solver recommended for optimisation.

class pybop.pybamm.Simulator(model: pybamm.BaseModel, parameter_values: pybamm.ParameterValues | None = None, initial_state: dict | None = None, protocol: pybamm.Experiment | pybop.processing.dataset.Dataset | numpy.ndarray | None = None, solver: pybamm.BaseSolver | None = None, output_variables: list[str] | None = None, geometry: pybamm.Geometry | None = None, submesh_types: dict | None = None, var_pts: dict | None = None, spatial_methods: dict | None = None, discretisation_kwargs: dict | None = None, build_every_time: bool = False)[source]#

Bases: pybop.simulators.base_simulator.BaseSimulator

A class to automatically build/rebuild and solve a pybamm.Simulation for a given model and protocol.

There are two contexts in which this class can be used: 1. A pybamm model can be built once and then run multiple times with different inputs. 2. A pybamm model needs to be built and then run for each set of inputs, for example in the case

where one of the inputs is a geometric parameter which requires a new mesh.

The logic for (1) and (2) happens automatically. To override this logic, the argument build_every_time can be set to True which will force (2) to occur.

Parameters:

model (pybamm.BaseModel) – The PyBaMM model to be used.
parameter_values (pybamm.ParameterValues, optional) – The parameter values to be used in the model.
initial_state (dict, optional) – A valid initial state, e.g. “Initial open-circuit voltage [V]” or ``”Initial SoC”`. Defaults to None, indicating that the existing initial state of charge (for an ECM) or initial concentrations (for an EChem model) will be used.
protocol (pybamm.Experiment | Dataset | np.ndarray | None) – The protocol as an experiment, a 1D array of values or dataset containing (time) domain data.
solver (pybamm.BaseSolver, optional) – The solver to use to solve the model. If None, uses pybop.pybamm.RecommendedSolver.
output_variables (list, optional) – A list of output variables to return.
geometry (pybamm.Geometry, optional) – The geometry upon which to solve the model.
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).
discretisation_kwargs (dict, optional) – Any keyword arguments to pass to the Discretisation class. See pybamm.Discretisation for details.
build_every_time (bool, optional) – If True, the model will be rebuilt every evaluation. Otherwise, the need to rebuild will be determined automatically.

__getstate__()[source]#

__setstate__(state)[source]#

_catch_errors(inputs: list[Inputs], options: dict)[source]#

_determine_rebuild_requirement(build_every_time: bool | None) → bool[source]#: Determine if model needs rebuilding on each evaluation.

_process_solutions(solutions: list[pybamm.Solution]) → list[pybamm.Solution | pybop.simulators.failed_solution.FailedSolution][source]#: Convert failed solutions to FailedSolution objects.

_set_protocol(protocol: pybamm.Experiment | pybop.processing.dataset.Dataset | numpy.ndarray | None)[source]#

Set up the protocol for the simulation.

Parameters:: protocol (pybamm.Experiment | pybop.Dataset | np.ndarray | None) – The protocol as an experiment, a 1D array of values or dataset containing (time) domain data.

t_eval#

The time points to stop the solver at. These points should be used to inform the solver of discontinuities in the solution.

Type:: np.ndarray, optional

t_interp#

The time points at which to interpolate the solution. If None, no interpolation will be done.

Type:: np.ndarray, optional

experiment#

The experimental conditions under which to solve the model.

Type:: pybamm.Experiment | string | list, optional

_set_up_solution_method(output_variables: list[str] | None = None) → None[source]#: Configure the mode of operation.

_simulate_with_rebuild(inputs: list[Inputs], options: dict) → list[pybamm.Solution][source]#: Simulate, rebuilding the simulation for each set of inputs.

_simulate_without_rebuild(inputs: list[Inputs], options: dict) → list[pybamm.Solution][source]#: Simulate without rebuilding the PyBaMM model.

convert_to_pybamm_initial_state(initial_state: dict | None) → None[source]#

Convert an initial state of charge into a float and an initial open-circuit voltage into a string ending in “V”.

Parameters:: initial_state (dict) – A valid initial state, e.g. the initial state of charge or open-circuit voltage.
Returns:: If float, this value is used as the initial state of charge (as a decimal between 0 and 1). If str ending in “V”, this value is used as the initial open-circuit voltage.
Return type:: float or str
Raises:: ValueError – If the input is not a dictionary with a single, valid key.

copy()[source]#: Return a copy of the simulation.

create_simulation() → pybamm.Simulation[source]#: Create a simulation with current configuration and optional experiment.

set_output_variables(value: list[str] | None)[source]#

Run the simulation using the built model and solver for one or more sets of inputs and return the solution object(s).

Parameters:

inputs (Inputs | list[Inputs], optional) – Input parameters (default: None).
calculate_sensitivities (bool) – Whether to also return the sensitivities (default: False).

Returns:

The solution object(s).

Return type:

pybamm.Solution | pybop.FailedSolution | list[pybamm.Solution | pybop.FailedSolution]

solve_batch(inputs: list[Inputs], calculate_sensitivities: bool = False) → list[pybamm.Solution | pybop.simulators.failed_solution.FailedSolution][source]#

Run the simulation using the built model and solver for each set of inputs and return dict-like simulation results.

Parameters:

inputs (list[Inputs]) – A list of input parameters.
calculate_sensitivities (bool) – Whether to also return the sensitivities (default: False).

Returns:

A list of len(inputs) containing the solution objects.

Return type:

list[pybamm.Solution | pybop.FailedSolution]

_discretisation_kwargs#

_experiment = None#

_geometry#

_initial_state = None#

_input_parameter_names#

_model#

_output_variables = None#

_parameter_values#

_requires_model_rebuild = False#

_simulation = None#

_solve = None#

_solver = None#

_spatial_methods#

_submesh_types#

_t_eval = None#

_t_interp = None#

_var_pts#

property built_model#

debug_mode = False#

property experiment#

property has_sensitivities#

property initial_state#

property input_parameter_names#

property model#

property output_variables#

property parameter_values#

property requires_model_rebuild#

property solver#

verbose = False#

class pybop.pybamm.SymbolReplacer(symbol_replacement_map: dict[pybamm.Symbol, pybamm.Symbol], processed_symbols: dict[pybamm.Symbol, pybamm.Symbol] | None = None, process_initial_conditions: bool = True)[source]#

Helper class to replace all instances of one or more symbols in an expression tree with another symbol, as defined by the dictionary symbol_replacement_map Originally developed by pybamm: pybamm-team/pybamm

Parameters:

symbol_replacement_map (dict {pybamm.Symbol -> pybamm.Symbol}) – Map of which symbols should be replaced by which.
processed_symbols (dict {pybamm.Symbol -> pybamm.Symbol}, optional) – cached replaced symbols
process_initial_conditions (bool, optional) – Whether to process initial conditions, default is True

_process_events(events: list) → list[source]#

_process_symbol(symbol: pybamm.Symbol) → pybamm.Symbol[source]#

process_boundary_conditions(model)[source]#: Process boundary conditions for a PybaMM model class Boundary conditions are dictionaries {“left”: left bc, “right”: right bc} in general, but may be imposed on the tabs (or not on the tab) for a small number of variables, e.g. {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc “no tab”: no tab bc}.

process_model(unprocessed_model, inplace=True)[source]#

Replace all instances of a symbol in a PyBaMM model class.

Parameters:

unprocessed_model (pybamm.BaseModel) – Model class to assign parameter values to
inplace (bool, optional) – If True, replace the parameters in the model in place. Otherwise, return a new model with parameter values set (default: True).

process_symbol(symbol)[source]#

This function recurses down the tree, replacing any symbols in self._symbol_replacement_map.keys() with their corresponding value

Parameters:: symbol (pybamm.Symbol) – The symbol to replace
Returns:: Symbol with all replacements performed
Return type:: pybamm.Symbol

_process_initial_conditions = True#

_processed_symbols#

_symbol_replacement_map#

pybop.pybamm.add_variable_to_model(model, variable: str, target_time: float | None = None)[source]#: Supplement a lithium-ion model with a design variable.

pybop.pybamm.cell_mass() → pybamm.Symbol[source]#

An expression for the total cell mass in kilograms.

This method defines the total mass as the sum of the components masses, including the electrodes, separator, and current collectors, based on their densities, porosities, and thicknesses.

pybop.pybamm.cell_volume() → pybamm.Symbol[source]#

An expression for the total cell volume in m3.

This method defines the total cell volume as the product of the electrode cross-sectional area and the total thickness of the cell including electrodes, eparator, and current collectors.

pybop.pybamm.set_formation_concentrations(parameter_values: pybamm.ParameterValues) → None[source]#

Compute the concentration of lithium in the positive electrode assuming that all lithium in the active material originated from the positive electrode.

Only perform the calculation if an initial concentration exists for both electrodes, i.e. it is not a half cell.

Parameters:: parameter_values (pybamm.ParameterValues) – A PyBaMM parameter set containing standard lithium ion parameters.