An implementation of the Battery Parameter eXchange (BPX) format in Pydantic. BPX, an outcome of the Faraday Institution Multi-scale Modelling project, is an open standard for physics-based Li-ion battery models that has been developed to reduce costs and time-to-market through a common definition of physics-based battery models that can be used widely across industry. To find out more, visit the BPX website.
This repository features a Pydantic-based parser for JSON files in the BPX format, which validates your file against the schema.
To support the new open standard, About:Energy have supplied two parameters sets for an NMC and LFP cell. The BPX files and associated examples and information can be found on the A:E BPX Parameterisation repository.
To see how to use BPX with PyBaMM, check out the BPX example repository.
The BPX package can be installed using pip
pip install bpxBPX is available on GNU/Linux, MacOS and Windows. We strongly recommend to install PyBaMM within a python virtual environment, in order not to alter any distribution python files.
To create a BPX object from a JSON file, you can use the parse_bpx_file function
import bpx
filename = 'path/to/my/file.json'
my_params = bpx.parse_bpx_file(filename)my_params will now be of type BPX, which acts like a python dataclass with the same attributes as the BPX format. To obatin example files, see the examples folder, the A:E BPX Parameterisation repository, or the BPX example repository.
Attributes of the class can be printed out using the standard Python dot notation, for example, you can print out the initial temperature of the cell using
print('Initial temperature of cell:', my_params.parameterisation.cell.initial_temperature)Alternatively, you can export the BPX object as a dictionary and use the string names (aliases) of the parameters from the standard
my_params_dict = my_params.dict(by_alias=True)
print('Initial temperature of cell:', my_params_dict["Parameterisation"]["Cell"]["Initial temperature [K]"])The entire BPX object can be pretty printed using the devtools package
from devtools import pprint
pprint(my_params)You can convert any Function objects in BPX to regular callable Python functions, for example:
positive_electrode_diffusivity = my_params.parameterisation.positive_electrode.diffusivity.to_python_function()
diff_at_one = positive_electrode_diffusivity(1.0)
print('positive electrode diffusivity at x = 1.0:', diff_at_one)If you want to output the complete JSON schema in order to build a custom tool yourself, you can do so:
print(bpx.BPX.schema_json(indent=2))According to the pydantic docs, the generated schemas are compliant with the specifications: JSON Schema Core, JSON Schema Validation and OpenAPI.
API documentation for the bpx package can be built locally using Sphinx. To build the documentation first clone the repository, install the bpx package, and then run the following command:
sphinx-build docs docs/_build/html This will generate a number of html files in the docs/_build/html directory. To view the documentation, open the file docs/_build/html/index.html in a web browser, e.g. by running
open docs/_build/html/index.htmlIf you have any questions please get in touch via email bpx@faraday.ac.uk.