pybop.pybamm#

Submodules#

Classes#

`EISSimulator`	A class to extend a PyBaMM model for EIS, automatically build/rebuild a pybamm.Simulation to obtain
`Simulator`	A class to automatically build/rebuild and solve a pybamm.Simulation for a given model and protocol.

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.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._utils.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

batch_solve(inputs: list[Inputs] = None, calculate_sensitivities: bool = False) → list[pybop.simulators.base_simulator.Solution | pybop._utils.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]

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]

M = None#

_f_eval#

_jac = None#

_simulation#

b = None#

debug_mode = False#

property has_sensitivities#

property input_parameter_names#

property parameter_values#

property simulation#

z_scale#

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

_catch_errors(inputs: list[Inputs])[source]#

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

_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._utils.FailedSolution][source]#: Convert failed solutions to FailedSolution objects.

_pybamm_solve(inputs: Inputs | list[Inputs] | None) → pybamm.Solution | list[pybamm.Solution][source]#: A function that runs the simulation using the built model.

_set_protocol(protocol: pybamm.Experiment | pybop._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_experiment_with_rebuild(inputs: list[Inputs]) → list[pybamm.Solution][source]#: Simulate an experiment, rebuilding the simulation for each set of inputs.

_simulate_experiment_without_rebuild(inputs: list[Inputs]) → list[pybamm.Solution][source]#: Simulate an experiment without rebuilding the PyBaMM model.

_solve_in_time_with_rebuild(inputs: list[Inputs]) → list[pybamm.Solution][source]#: Solve in time, rebuilding the model for each set of inputs.

_solve_in_time_without_rebuild(inputs: list[Inputs]) → list[pybamm.Solution][source]#: Solve in time without rebuilding the PyBaMM model.

batch_solve(inputs: list[Inputs], calculate_sensitivities: bool = False) → list[pybamm.Solution | pybop._utils.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]

build_model() → None[source]#: Build the model using the given parameter values.

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.

rebuild_model(inputs: pybop.parameters.parameter.Inputs) → None[source]#: Update the parameter values and rebuild the model, if required.

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]

_built_model = None#

_calculate_sensitivities = False#

_discretisation_kwargs#

_experiment = None#

_geometry#

_initial_state = None#

_input_parameter_names#

_model#

_output_variables = None#

_parameter_values#

_requires_model_rebuild = False#

_sim_experiment = None#

_solve = None#

_solver = None#

_spatial_methods#

_submesh_types#

_t_eval = None#

_t_interp = None#

_var_pts#

property built_model#

debug_mode = False#

exception = ['These parameter values are infeasible.']#

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#

warning_patterns = ['Ah is greater than', 'Non-physical point encountered']#

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.