Parameter Values#

The ParameterValues class is the main interface for managing battery simulation parameters. It provides methods for storing, updating, and processing parameters, as well as introspection features for exploring parameter sets.

Features#

The ParameterValues class now includes several helpful features:

Parameter Introspection: Use get_info() to get metadata about parameters including units and category.
Category Browsing: Use list_by_category() to find parameters by domain (e.g., “negative electrode”, “thermal”).
Parameter Comparison: Use diff() to compare two parameter sets and see what’s added, removed, or changed.

Example usage:

import pybamm

# Load a parameter set
params = pybamm.ParameterValues("Chen2020")

# Get info about a parameter
info = params.get_info("Maximum concentration in negative electrode [mol.m-3]")
print(f"Value: {info.value}, Units: {info.units}, Category: {info.category}")

# List parameters by category
neg_electrode_params = params.list_by_category("negative electrode")
print(f"Found {len(neg_electrode_params)} negative electrode parameters")

# Compare with another parameter set
marquis = pybamm.ParameterValues("Marquis2019")
diff = params.diff(marquis)
print(f"Changed parameters: {list(diff.changed.keys())[:5]}")

API Reference#

class pybamm.ParameterValues(values: dict[str, Any] | str | ParameterValues)[source]#

The parameter values for a simulation.

Note that this class does not inherit directly from the python dictionary class as this causes issues with saving and loading simulations.

Parameters:: values (dict or string or ParameterValues) – Explicit set of parameters, or reference to an inbuilt parameter set. If string and matches one of the inbuilt parameter sets, returns that parameter set.

Examples

>>> values = {"some parameter": 1, "another parameter": 2}
>>> param = pybamm.ParameterValues(values)
>>> param["some parameter"]
1
>>> param = pybamm.ParameterValues("Marquis2019")
>>> param["Reference temperature [K]"]
298.15

>>> info = param.get_info("Reference temperature [K]")
>>> info.units
'K'
>>> electrode_params = param.list_by_category("negative electrode")
>>> len(electrode_params) > 0
True

categories() → dict[str, list[str]][source]#

Return all parameters grouped by category.

Returns:: Dictionary mapping category names to lists of parameter names.
Return type:: dict[str, list[str]]

Examples

>>> param = pybamm.ParameterValues("Chen2020")
>>> cats = param.categories()
>>> "negative electrode" in cats
True

static check_parameter_values(values: dict) → dict[source]#

Check and transform parameter values.

Parameters:: values (dict) – Dictionary of parameter values to check.
Returns:: Checked and transformed parameter values.
Return type:: dict
Raises:: ValueError – If parameter names contain deprecated or invalid formats.

Examples

>>> values = {"Electrode height [m]": 0.065}
>>> checked = pybamm.ParameterValues.check_parameter_values(values)

copy() → ParameterValues[source]#

Return a copy of the parameter values.

Example

>>> params = pybamm.ParameterValues("Chen2020")
>>> params_copy = params.copy()
>>> params_copy["Current function [A]"] = 10.0  # Original unchanged

classmethod create_from_bpx(filename: str | Path, target_soc: float = 1.0) → ParameterValues[source]#

Create ParameterValues from a BPX file.

Parameters:

filename (str or Path) – The filename of the BPX file.
target_soc (float, optional) – Target state of charge. Must be between 0 and 1. Default is 1.

Returns:

A parameter values object with the parameters from the BPX file.

Return type:

ParameterValues

Examples

>>> param = pybamm.ParameterValues.create_from_bpx("battery_params.json")
>>> param = pybamm.ParameterValues.create_from_bpx("battery_params.json", target_soc=0.5)

classmethod create_from_bpx_obj(bpx_obj: dict, target_soc: float = 1.0) → ParameterValues[source]#

Create ParameterValues from a BPX dictionary object.

Parameters:

bpx_obj (dict) –
A dictionary containing the parameters in the BPX format.
target_soc (float, optional) – Target state of charge. Must be between 0 and 1. Default is 1.

Returns:

A parameter values object with the parameters in the BPX file.

Return type:

ParameterValues

Examples

>>> bpx_dict = {"Header": {...}, "Cell": {...}, "Parameterisation": {...}}
>>> param = pybamm.ParameterValues.create_from_bpx_obj(bpx_dict)
>>> param = pybamm.ParameterValues.create_from_bpx_obj(bpx_dict, target_soc=0.8)

diff(other: ParameterValues, *, rtol: float = 0.0) → ParameterDiff[source]#

Compare this ParameterValues with another and return differences.

Parameters:

other (ParameterValues) – The other parameter values to compare against.
rtol (float, optional) – Relative tolerance for numerical comparisons. Differences smaller than rtol * max(|a|, |b|) are ignored. Default is 0.0 (exact comparison). Set to e.g. 1e-6 to ignore tiny floating-point differences.

Returns:

Object containing added, removed, and changed parameters.

Return type:

ParameterDiff

Examples

>>> chen = pybamm.ParameterValues("Chen2020")
>>> marquis = pybamm.ParameterValues("Marquis2019")
>>> diff = chen.diff(marquis)
>>> isinstance(diff.changed, dict)
True

With tolerance:

>>> params1 = pybamm.ParameterValues({"x": 1.0})
>>> params2 = pybamm.ParameterValues({"x": 1.0 + 1e-10})
>>> params1.diff(params2, rtol=1e-9).changed  # Empty
{}

evaluate(symbol: Symbol, inputs: dict | None = None) → Any[source]#

Process and evaluate a symbol.

Parameters:

symbol (pybamm.Symbol) – Symbol or Expression tree to evaluate.
inputs (dict, optional) – Input parameter values for evaluation.

Returns:

The evaluated symbol.

Return type:

number or array

Example

>>> params = pybamm.ParameterValues("Chen2020")
>>> param = pybamm.Parameter("Current function [A]")
>>> result = params.evaluate(param)  # Returns evaluated value

static from_config(filename_or_dict: str | Path | dict) → ParameterValues#

Load a ParameterValues object from a JSON file or a dictionary.

Parameters:: filename_or_dict (str, Path, or dict) – The filename to load the JSON file from, or a dictionary.
Returns:: The ParameterValues object.
Return type:: ParameterValues

Examples

>>> param = pybamm.ParameterValues.from_json("parameters.json")
>>> param_dict = {"Temperature [K]": 298.15}
>>> param = pybamm.ParameterValues.from_json(param_dict)

static from_json(filename_or_dict: str | Path | dict) → ParameterValues[source]#

Load a ParameterValues object from a JSON file or a dictionary.

Parameters:: filename_or_dict (str, Path, or dict) – The filename to load the JSON file from, or a dictionary.
Returns:: The ParameterValues object.
Return type:: ParameterValues

Examples

>>> param = pybamm.ParameterValues.from_json("parameters.json")
>>> param_dict = {"Temperature [K]": 298.15}
>>> param = pybamm.ParameterValues.from_json(param_dict)

get(key: str, default: Any = None) → Any[source]#

Return item corresponding to key if it exists, otherwise return default.

Parameters:

key (str) – The parameter name to retrieve.
default (Any, optional) – The default value to return if key is not found. Default is None.

Returns:

The parameter value if found, otherwise the default value.

Return type:

Any

Examples

>>> param = pybamm.ParameterValues("Chen2020")
>>> param.get("Current function [A]")
5.0
>>> param.get("NonExistent Parameter", 42)
42

get_info(key: str) → ParameterInfo[source]#

Get metadata about a parameter.

Parameters:: key (str) – The parameter name.
Returns:: Metadata including value, units, category, and type information.
Return type:: ParameterInfo

Examples

>>> param = pybamm.ParameterValues("Chen2020")
>>> info = param.get_info("Maximum concentration in negative electrode [mol.m-3]")
>>> info.units
'mol.m-3'
>>> info.category
'negative electrode'

items()[source]#

Return parameter items.

Returns:: The parameter items as (key, value) pairs.
Return type:: dict_items

Examples

>>> param = pybamm.ParameterValues({"Temperature [K]": 298.15})
>>> items = list(param.items())
>>> ("Temperature [K]", 298.15) in items
True

keys()[source]#

Return parameter keys.

Returns:: The parameter keys.
Return type:: dict_keys

Examples

>>> param = pybamm.ParameterValues("Chen2020")
>>> keys = list(param.keys())
>>> "Current function [A]" in keys
True

list_by_category(category: ParameterCategory | str) → list[str][source]#

Return all parameter names in a given category.

Parameters:: category (ParameterCategory or str) – The category to filter by. Can be a ParameterCategory enum value or a string like “negative electrode”.
Returns:: List of parameter names in the category.
Return type:: list[str]

Examples

>>> param = pybamm.ParameterValues("Chen2020")
>>> electrode_params = param.list_by_category("negative electrode")
>>> len(electrode_params) > 0
True

pop(*args, **kwargs) → Any[source]#

Remove and return a parameter value.

Example

>>> params = pybamm.ParameterValues("Chen2020")
>>> val = params.pop("Current function [A]")

print_evaluated_parameters(evaluated_parameters: dict, output_file: str) → None[source]#

Print a dictionary of evaluated parameters to an output file.

Parameters:

evaluated_parameters (dict) – The evaluated parameters.
output_file (str) – The file to print parameters to.

Examples

>>> param = pybamm.ParameterValues("Chen2020")
>>> evaluated_params = {"Temperature [K]": 298.15, "Voltage [V]": 3.7}
>>> param.print_evaluated_parameters(evaluated_params, "params.txt")

print_parameters(parameters, output_file: str | None = None) → dict[source]#

Return dictionary of evaluated parameters.

Optionally print these evaluated parameters to an output file.

Parameters:

parameters (class or dict containing pybamm.Parameter objects) – Class or dictionary containing all the parameters to be evaluated.
output_file (str, optional) – The file to print parameters to. If None, the parameters are not printed, and this function simply acts as a test that all the parameters can be evaluated.

Returns:

The evaluated parameters.

Return type:

dict

Examples

>>> param = pybamm.ParameterValues("Chen2020")
>>> params_dict = {"param1": pybamm.Parameter("Current function [A]")}
>>> evaluated = param.print_parameters(params_dict)
>>> isinstance(evaluated, dict)
True
>>> param.print_parameters(params_dict, "output.txt")
defaultdict(<class 'list'>, {'param1': np.float64(5.0)})

process_boundary_conditions(model: BaseModel) → dict[source]#

Process boundary conditions for a model.

Boundary conditions are dictionaries {“left”: left bc, “right”: right bc} in general, but may be imposed on the tabs for some variables.

Parameters:: model (pybamm.BaseModel) – Model whose boundary conditions to process.
Returns:: Processed boundary conditions.
Return type:: dict

Examples

>>> model = pybamm.lithium_ion.SPM()
>>> param = pybamm.ParameterValues("Chen2020")
>>> bcs = param.process_boundary_conditions(model)

process_geometry(geometry: dict) → None[source]#

Assign parameter values to a geometry (inplace).

Parameters:: geometry (dict) – Geometry specs to assign parameter values to.

Examples

>>> geometry = pybamm.battery_geometry()
>>> param = pybamm.ParameterValues("Chen2020")
>>> param.process_geometry(geometry)

process_model(unprocessed_model: BaseModel, inplace: bool = True, delayed_variable_processing: bool | None = None) → BaseModel[source]#

Assign parameter values to a model.

Parameters:

unprocessed_model (pybamm.BaseModel) – Model to assign parameter values for.
inplace (bool, optional) – If True (default), replace parameters in place. If False, return a new model with parameter values set.
delayed_variable_processing (bool, optional) – If True, make variable processing a post-processing step. Default is False.

Returns:

The parameterized model.

Return type:

pybamm.BaseModel

Raises:

pybamm.ModelError – If an empty model is passed.

Example

>>> model = pybamm.lithium_ion.SPM()
>>> params = pybamm.ParameterValues("Chen2020")
>>> processed_model = params.process_model(model)

process_symbol(symbol: Symbol) → Symbol[source]#

Walk through the symbol and replace any Parameter with a Value.

If a symbol has already been processed, the cached value is returned.

Parameters:: symbol (pybamm.Symbol) – Symbol or Expression tree to set parameters for.
Returns:: Symbol with Parameter instances replaced by values.
Return type:: pybamm.Symbol

Example

>>> params = pybamm.ParameterValues("Chen2020")
>>> param = pybamm.Parameter("Current function [A]")
>>> processed = params.process_symbol(param)
>>> result = processed.evaluate()  # Returns evaluated value

search(key: str, print_values: bool = True) → None[source]#

Search dictionary for keys containing ‘key’.

Example

>>> params = pybamm.ParameterValues("Chen2020")
>>> params.search("electrolyte", print_values=False)
Results for 'electrolyte': ...

set_initial_ocps(initial_value, direction=None, param=None, known_value='cyclable lithium capacity', inplace=True, options=None, inputs=None)[source]#: Deprecated: Use set_initial_state instead.

set_initial_state(initial_value, direction=None, param=None, inplace: bool = True, options=None, inputs=None)[source]#

Set the initial state of the battery.

Delegates to chemistry-specific implementation.

Parameters:

initial_value (float) – The initial state value (e.g., SOC or voltage).
direction (str, optional) – Direction for setting state. Default is None.
param (pybamm.ParameterValues, optional) – Parameter values to use. Default is None (uses self).
inplace (bool, optional) – If True, modify parameters in place. Default is True.
options (dict, optional) – Model options. Default is None.
inputs (dict, optional) – Input parameters. Default is None.

Returns:

Updated parameter values if inplace=False, otherwise None.

Return type:

ParameterValues or None

Examples

>>> param = pybamm.ParameterValues("Chen2020")
>>> result = param.set_initial_state(0.5)  # Sets initial SOC to 50%
>>> isinstance(result, pybamm.ParameterValues)
True

set_initial_stoichiometries(initial_value, direction=None, param=None, known_value='cyclable lithium capacity', inplace=True, options=None, inputs=None, tol=1e-06)[source]#: Deprecated: Use set_initial_state instead.

set_initial_stoichiometry_half_cell(initial_value, direction=None, param=None, known_value='cyclable lithium capacity', inplace=True, options=None, inputs=None)[source]#: Deprecated: Use set_initial_state instead.

to_config(filename: str | None = None) → dict#

Convert the parameter values to a JSON-serializable dictionary.

Optionally saves to a file.

Parameters:: filename (str, optional) – The filename to save the JSON file to. If not provided, the dictionary is not saved.
Returns:: The JSON-serializable dictionary.
Return type:: dict

Examples

>>> param = pybamm.ParameterValues({"Temperature [K]": 298.15})
>>> param_dict = param.to_json()  # Get dictionary
>>> isinstance(param_dict, dict)
True
>>> param.to_json("parameters.json")
{'Temperature [K]': 298.15}

to_json(filename: str | None = None) → dict[source]#

Convert the parameter values to a JSON-serializable dictionary.

Optionally saves to a file.

Parameters:: filename (str, optional) – The filename to save the JSON file to. If not provided, the dictionary is not saved.
Returns:: The JSON-serializable dictionary.
Return type:: dict

Examples

>>> param = pybamm.ParameterValues({"Temperature [K]": 298.15})
>>> param_dict = param.to_json()  # Get dictionary
>>> isinstance(param_dict, dict)
True
>>> param.to_json("parameters.json")
{'Temperature [K]': 298.15}

update(values: Mapping[str, Any], *, check_conflict: bool = False, check_already_exists: bool = False, path: str = '') → None[source]#

Update parameter values.

Parameters:

values (dict) – Dictionary of parameter values to update.
check_conflict (bool, optional) – Deprecated.
check_already_exists (bool, optional) – Deprecated.
path (str, optional) – Path from which to load functions (legacy parameter).

Example

>>> params = pybamm.ParameterValues("Chen2020")
>>> params.update({"Current function [A]": 2.0})  # Update existing
>>> params.update({'a': 1.0})  # Create new

Notes

The check_already_exists parameter is deprecated.

values()[source]#

Return parameter values.

Returns:: The parameter values.
Return type:: dict_values

Examples

>>> param = pybamm.ParameterValues({"Temperature [K]": 298.15})
>>> vals = list(param.values())
>>> 298.15 in vals
True