-
Notifications
You must be signed in to change notification settings - Fork 12
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merge develop into main for v0.4.0 release #49
Changes from 68 commits
b0433de
3f83150
a88ac51
7411768
e836bbe
233f4db
6ca9e7b
1339711
3a848d7
d03c39a
8dc406b
4a36ec6
bed16f8
5eeb7e9
4a3704b
804d758
8ad4272
274dc79
f933a15
acb236f
eb9579d
c2afaf8
3b3e389
e286492
f88c6f4
bca53ce
58930b3
2a6a0a6
679e153
b46ddc4
14f2c11
b9200d1
7a54d44
19d3dcf
755ccfd
d18380d
3524977
1fa5ba0
e4b061c
98b9c1e
fc38062
f116efd
dd506d8
b797fea
28eb745
4cba3f6
694e727
cd00a67
ea7c2c1
e4168ef
79ecbc2
ee7f21c
2fbff65
8b359b3
337624b
1d51b3d
cd577b9
df537c7
fee5318
bc8382e
b677fe2
9099c56
19b78b8
9bdb956
c36a05b
39ad3d6
599d80a
9d57532
c184b7b
64c6470
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# .readthedocs.yaml | ||
# Read the Docs configuration file | ||
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details | ||
|
||
# Required | ||
version: 2 | ||
|
||
# Set the version of Python and other tools you might need | ||
build: | ||
os: ubuntu-22.04 | ||
tools: | ||
python: "3.11" | ||
|
||
# Build documentation in the docs/ directory with Sphinx | ||
sphinx: | ||
builder: html | ||
configuration: docs/conf.py | ||
fail_on_warning: false | ||
|
||
# Optionally declare the Python requirements required to build your docs | ||
python: | ||
install: | ||
- method: pip | ||
path: . | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,15 +1,26 @@ | ||
# [v0.3.1](https://github.com/pybamm-team/BPX/releases/tag/v0.3.1) | ||
- Temporarily pin Pydantic version ([#35](https://github.com/pybamm-team/BPX/pull/35)) | ||
# [v0.4.0](https://github.com/FaradayInstitution/BPX/releases/tag/v0.4.0) | ||
|
||
- Added five parametrisation examples (two DFN parametrisation examples from About:Energy open-source release, blended electrode definition, user-defined 0th-order hysteresis, and SPM parametrisation). ([#45](https://github.com/FaradayInstitution/BPX/pull/45)) | ||
- Allow user-defined parameters to be added using the field ["Parameterisation"]["User-defined"] ([#44](https://github.com/pybamm-team/BPX/pull/44)) | ||
- Added basic API documentation ([#43](https://github.com/FaradayInstitution/BPX/pull/43)) | ||
- Added validation based on models: SPM, SPMe, DFN ([#34](https://github.com/pybamm-team/BPX/pull/34)). A warning will be produced if the user-defined model type does not match the parameter set (e.g., if the model is `SPM`, but the full DFN model parameters are provided). | ||
- Added support for well-mixed, blended electrodes that contain more than one active material ([#33](https://github.com/pybamm-team/BPX/pull/33)) | ||
- Added validation of the STO limits subbed into the OCPs vs the upper/lower cut-off voltage limits for non-blended electrodes with the OCPs defined as functions ([#32](https://github.com/FaradayInstitution/BPX/pull/32)). The user can provide a tolerance by updating the settings variable `BPX.settings.tolerances["Voltage [V]"]` or by passing extra option `v_tol` to `parse_bpx_file()`, `parse_bpx_obj()` or `parse_bpx_str()` functions. Default value of the tolerance is 1 mV. The tolerance cannot be negative. | ||
- Added the target SOC check in `get_electrode_concentrations()` function. Raise a warning if the SOC is outside of [0,1] interval. | ||
|
||
# [v0.3.1](https://github.com/FaradayInstitution/BPX/releases/tag/v0.3.1) | ||
|
||
- Temporarily pin Pydantic version ([#35](https://github.com/FaradayInstitution/BPX/pull/35)) | ||
|
||
# [v0.3.0](https://github.com/pybamm-team/BPX/releases/tag/v0.3.0) | ||
|
||
- Added a missing factor of 2 in the definition of the interfacial current, see the Butler-Volmer equation (2a) in the associated BPX standard document. The interfacial current is now given by $j=2j_0\sinh(F\eta/2/R/T)$ instead of $j=j_0\sinh(F\eta/2/R/T)$. | ||
|
||
# [v0.2.0](https://github.com/pybamm-team/BPX/releases/tag/v0.2.0) | ||
# [v0.2.0](https://github.com/FaradayInstitution/BPX/releases/tag/v0.2.0) | ||
|
||
- Parsing a BPX json file with additional (unexpected) fields now raises a `ValidationError` ([#16](https://github.com/pybamm-team/BPX/pull/16)) | ||
- Fixed a bug in the experiment schema ([#13](https://github.com/pybamm-team/BPX/pull/13)) | ||
- Parsing a BPX json file with additional (unexpected) fields now raises a `ValidationError` ([#16](https://github.com/FaradayInstitution/BPX/pull/16)) | ||
- Fixed a bug in the experiment schema ([#13](https://github.com/FaradayInstitution/BPX/pull/13)) | ||
|
||
# [v0.1.0](https://github.com/pybamm-team/BPX/releases/tag/v0.1.0) | ||
# [v0.1.0](https://github.com/FaradayInstitution/BPX/releases/tag/v0.1.0) | ||
|
||
Initial release of the Battery Parameter eXchange (BPX) format. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,6 @@ | ||
# BPX | ||
![tests](https://github.com/pybamm-team/BPX/actions/workflows/test.yml/badge.svg) | ||
[![codecov](https://codecov.io/gh/pybamm-team/BPX/branch/main/graph/badge.svg?token=Krv0JW3gYZ)](https://codecov.io/gh/pybamm-team/BPX) | ||
# 🔋 BPX | ||
![tests](https://github.com/FaradayInstitution/BPX/actions/workflows/test.yml/badge.svg) | ||
[![codecov](https://codecov.io/gh/FaradayInstitution/BPX/branch/main/graph/badge.svg?token=Krv0JW3gYZ)](https://codecov.io/gh/FaradayInstitution/BPX) | ||
|
||
An implementation of the Battery Parameter eXchange (BPX) format in Pydantic. BPX, an outcome of the Faraday Institution [Multi-scale Modelling project](https://www.faraday.ac.uk/research/lithium-ion/battery-system-modelling/), 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](https://bpxstandard.com/). | ||
|
||
|
@@ -9,38 +9,26 @@ This repository features a Pydantic-based parser for JSON files in the BPX forma | |
To support the new open standard, [About:Energy](https://www.aboutenergy.io/) 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](https://github.com/About-Energy-OpenSource/About-Energy-BPX-Parameterisation/). | ||
|
||
To see how to use BPX with [PyBaMM](https://www.pybamm.org/), check out the [BPX example repository](https://github.com/pybamm-team/bpx-example). | ||
## Prerequisites | ||
|
||
- Python 3+ | ||
|
||
## Installation | ||
|
||
Create a new virtual environment, or activate an existing one (this example uses the python `venv` module, but you could use Anaconda and a `conda` environment) | ||
|
||
```bash | ||
python3 -m venv env | ||
source env/bin/activate | ||
``` | ||
|
||
Install the `BPX` module using pip | ||
|
||
## 🚀 Installation | ||
The BPX package can be installed using pip | ||
```bash | ||
pip install bpx | ||
``` | ||
|
||
## Usage | ||
|
||
Create a python script similar to that below | ||
BPX is available on GNU/Linux, MacOS and Windows. We strongly recommend to install PyBaMM within a python [virtual environment](https://docs.python.org/3/tutorial/venv.html), in order not to alter any distribution python files. | ||
|
||
## 💻 Usage | ||
To create a BPX object from a JSON file, you can use the `parse_bpx_file` function | ||
```python | ||
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](https://github.com/About-Energy-OpenSource/About-Energy-BPX-Parameterisation/), or the [BPX example repository](https://github.com/pybamm-team/bpx-example). | ||
|
||
`my_params` will now be of type `BPX`, which acts like a python dataclass with the same attributes as the BPX format. For example, you can print out the initial temperature of the cell using | ||
|
||
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 | ||
```python | ||
print('Initial temperature of cell:', my_params.parameterisation.cell.initial_temperature) | ||
``` | ||
|
@@ -51,25 +39,35 @@ my_params_dict = my_params.dict(by_alias=True) | |
print('Initial temperature of cell:', my_params_dict["Parameterisation"]["Cell"]["Initial temperature [K]"]) | ||
``` | ||
|
||
If you want to pretty print the entire object, you can use the `devtools` package to do this (remember to `pip install devtools`) | ||
|
||
The entire BPX object can be pretty printed using the `devtools` package | ||
```python | ||
from devtools import pprint | ||
pprint(my_params) | ||
``` | ||
|
||
You can convert any `Function` objects in `BPX` to regular callable Python functions, for example: | ||
|
||
```python | ||
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: | ||
|
||
```python | ||
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. | ||
|
||
## 📖 Documentation | ||
API documentation for the `bpx` package can be built locally using [Sphinx](https://www.sphinx-doc.org/en/master/). To build the documentation first [clone the repository](https://github.com/git-guides/git-clone), then run the following command: | ||
```bash | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This didn't work straight away for me ('No module named bpx' error). I just git-cloned the repo (dev branch) and tried the command below. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. you have to install bpx first, will update the instructions There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yeah, I realised that I had installed the previous version of BPX, that's why it probably complained. |
||
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 | ||
```bash | ||
open docs/_build/html/index.html | ||
``` | ||
|
||
## 📫 Get in touch | ||
If you have any questions please get in touch via email <bpx@faraday.ac.uk>. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,13 @@ | ||
"""BPX schema and parsers""" | ||
# flake8: noqa F401 | ||
|
||
__version__ = "0.3.1" | ||
__version__ = "0.4.0" | ||
|
||
|
||
from .interpolated_table import InterpolatedTable | ||
from .expression_parser import ExpressionParser | ||
from .function import Function | ||
from .validators import check_sto_limits | ||
from .schema import BPX | ||
from .parsers import parse_bpx_str, parse_bpx_obj, parse_bpx_file | ||
from .utilities import get_electrode_stoichiometries, get_electrode_concentrations |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,49 +1,74 @@ | ||
from bpx import BPX | ||
|
||
|
||
def parse_bpx_file(filename: str) -> BPX: | ||
def parse_bpx_file(filename: str, v_tol: float = 0.001) -> BPX: | ||
""" | ||
A convenience function to parse a bpx file into a BPX model. | ||
|
||
Parameters | ||
---------- | ||
|
||
filename: str | ||
a filepath to a bpx file | ||
v_tol: float | ||
absolute tolerance in [V] to validate the voltage limits, 1 mV by default | ||
|
||
Returns | ||
------- | ||
BPX: | ||
BPX: :class:`bpx.BPX` | ||
a parsed BPX model | ||
""" | ||
if v_tol < 0: | ||
raise ValueError("v_tol should not be negative") | ||
|
||
BPX.settings.tolerances["Voltage [V]"] = v_tol | ||
|
||
return BPX.parse_file(filename) | ||
|
||
|
||
def parse_bpx_obj(bpx: dict) -> BPX: | ||
def parse_bpx_obj(bpx: dict, v_tol: float = 0.001) -> BPX: | ||
""" | ||
A convenience function to parse a bpx dict into a BPX model. | ||
|
||
Parameters | ||
---------- | ||
|
||
bpx: dict | ||
a dict object in bpx format | ||
v_tol: float | ||
absolute tolerance in [V] to validate the voltage limits, 1 mV by default | ||
|
||
Returns | ||
------- | ||
BPX: | ||
BPX: :class:`bpx.BPX` | ||
a parsed BPX model | ||
""" | ||
if v_tol < 0: | ||
raise ValueError("v_tol should not be negative") | ||
|
||
BPX.settings.tolerances["Voltage [V]"] = v_tol | ||
|
||
return BPX.parse_obj(bpx) | ||
|
||
|
||
def parse_bpx_str(bpx: str) -> BPX: | ||
def parse_bpx_str(bpx: str, v_tol: float = 0.001) -> BPX: | ||
""" | ||
A convenience function to parse a json formatted string in bpx format into a BPX | ||
model. | ||
|
||
Parameters | ||
---------- | ||
|
||
bpx: str | ||
a json formatted string in bpx format | ||
v_tol: float | ||
absolute tolerance in [V] to validate the voltage limits, 1 mV by default | ||
|
||
Returns | ||
------- | ||
BPX: | ||
a parsed BPX model | ||
""" | ||
if v_tol < 0: | ||
raise ValueError("v_tol should not be negative") | ||
|
||
BPX.settings.tolerances["Voltage [V]"] = v_tol | ||
|
||
return BPX.parse_raw(bpx) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There are still a few links to the old (pybamm-team) repo here and below.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thanks, will update