besslib 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- besslib-0.1.0/LICENSE +28 -0
- besslib-0.1.0/MANIFEST.in +2 -0
- besslib-0.1.0/PKG-INFO +210 -0
- besslib-0.1.0/README.md +180 -0
- besslib-0.1.0/pyproject.toml +52 -0
- besslib-0.1.0/setup.cfg +4 -0
- besslib-0.1.0/src/besslib/__init__.py +12 -0
- besslib-0.1.0/src/besslib/data/__init__.py +1 -0
- besslib-0.1.0/src/besslib/data/sample_05/NOTICE.md +39 -0
- besslib-0.1.0/src/besslib/data/sample_05/daily.parquet +0 -0
- besslib-0.1.0/src/besslib/data/sample_05/rests.parquet +0 -0
- besslib-0.1.0/src/besslib/data/sample_05/steps.parquet +0 -0
- besslib-0.1.0/src/besslib/frames.py +84 -0
- besslib-0.1.0/src/besslib/io/__init__.py +6 -0
- besslib-0.1.0/src/besslib/io/figgener.py +236 -0
- besslib-0.1.0/src/besslib/io/figgener_meta/README.md +12 -0
- besslib-0.1.0/src/besslib/io/figgener_meta/capacity_tests.csv +61 -0
- besslib-0.1.0/src/besslib/io/figgener_meta/systems.csv +22 -0
- besslib-0.1.0/src/besslib/soh/__init__.py +43 -0
- besslib-0.1.0/src/besslib/soh/_core.py +1081 -0
- besslib-0.1.0/src/besslib/soh/_ratio.py +277 -0
- besslib-0.1.0/src/besslib/soh/capacity.py +332 -0
- besslib-0.1.0/src/besslib/soh/capacity_test.py +205 -0
- besslib-0.1.0/src/besslib/soh/charge_loss.py +199 -0
- besslib-0.1.0/src/besslib/soh/config.py +153 -0
- besslib-0.1.0/src/besslib/soh/efficiency.py +270 -0
- besslib-0.1.0/src/besslib/soh/record.py +556 -0
- besslib-0.1.0/src/besslib/soh/reduce.py +352 -0
- besslib-0.1.0/src/besslib/soh/report.py +290 -0
- besslib-0.1.0/src/besslib/soh/resistance.py +570 -0
- besslib-0.1.0/src/besslib/soh/rests.py +488 -0
- besslib-0.1.0/src/besslib/soh/usage.py +322 -0
- besslib-0.1.0/src/besslib.egg-info/PKG-INFO +210 -0
- besslib-0.1.0/src/besslib.egg-info/SOURCES.txt +35 -0
- besslib-0.1.0/src/besslib.egg-info/dependency_links.txt +1 -0
- besslib-0.1.0/src/besslib.egg-info/requires.txt +10 -0
- besslib-0.1.0/src/besslib.egg-info/top_level.txt +1 -0
besslib-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026, besslib contributors
|
|
4
|
+
|
|
5
|
+
Redistribution and use in source and binary forms, with or without
|
|
6
|
+
modification, are permitted provided that the following conditions are met:
|
|
7
|
+
|
|
8
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
9
|
+
list of conditions and the following disclaimer.
|
|
10
|
+
|
|
11
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
12
|
+
this list of conditions and the following disclaimer in the documentation
|
|
13
|
+
and/or other materials provided with the distribution.
|
|
14
|
+
|
|
15
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
16
|
+
contributors may be used to endorse or promote products derived from
|
|
17
|
+
this software without specific prior written permission.
|
|
18
|
+
|
|
19
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
20
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
21
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
22
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
23
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
24
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
25
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
26
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
27
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
28
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
besslib-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: besslib
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: State of health from battery storage operating data, with confidence bands, in the fields of EU Regulation 2023/1542 Annex VII.
|
|
5
|
+
Author-email: Islam Ghonaiem <ghonaiem@vgtai.com>
|
|
6
|
+
License-Expression: BSD-3-Clause
|
|
7
|
+
Project-URL: Source, https://github.com/GhonAI/besslib
|
|
8
|
+
Project-URL: Documentation, https://github.com/GhonAI/besslib/tree/main/docs
|
|
9
|
+
Project-URL: Issues, https://github.com/GhonAI/besslib/issues
|
|
10
|
+
Keywords: battery,battery energy storage,BESS,state of health,capacity estimation,EU Battery Regulation,Annex VII
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Topic :: Scientific/Engineering
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: numpy>=2.0
|
|
22
|
+
Requires-Dist: pandas>=2.2.2
|
|
23
|
+
Requires-Dist: pyarrow>=16
|
|
24
|
+
Provides-Extra: plot
|
|
25
|
+
Requires-Dist: matplotlib>=3.8; extra == "plot"
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
28
|
+
Requires-Dist: matplotlib>=3.8; extra == "dev"
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
# besslib
|
|
32
|
+
|
|
33
|
+
State of health from battery storage operating data — with confidence bands, in the fields of the
|
|
34
|
+
EU Battery Regulation (2023/1542, Annex VII).
|
|
35
|
+
|
|
36
|
+
**Version 0.1.0, 20 November 2026.** It computes the Annex VII parameters; it does not certify them. It is not a
|
|
37
|
+
compliance certificate and not legal advice.
|
|
38
|
+
|
|
39
|
+

|
|
40
|
+
|
|
41
|
+
*System 05 (LMO/NMC, 15 Ah nominal): the capacity from operating data, at the end of each month, with its 90 % band, against the 4 field capacity tests (dots). 2 of the 4 tests have an estimate at their date, and the band holds the test value in 2 of them. The first estimate is at the end of September 2017: the first year gives none (grey). Hollow dots: tests without an estimate. 17 month ends without data are left blank.*
|
|
42
|
+
|
|
43
|
+
Checked on open field data: 21 home storage systems, 1,269 months, 60 field capacity tests.
|
|
44
|
+
On the 14 systems the method was not tuned on:
|
|
45
|
+
|
|
46
|
+
- LMO/NMC and NMC, 28 tests: median error 2.62 points of nominal capacity (target ≤ 3): **passed**.
|
|
47
|
+
- LFP, 10 tests: 5 have no estimate (target ≤ 5 points): **failed**.
|
|
48
|
+
- The 90 % band held the measured value in 43 % of 28 tests (target 80 %): **failed**. [Why →](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/limits.md)
|
|
49
|
+
|
|
50
|
+
Every number on this page is written by `validation/make_readme.py` from a results file in `validation/results/`.
|
|
51
|
+
|
|
52
|
+
## Install and run
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
pip install besslib
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
import besslib
|
|
60
|
+
reduced, spec = besslib.io.read_sample() # system 05, Aug 2016 – Sep 2022, CC BY 4.0
|
|
61
|
+
record = besslib.soh.annex_vii(None, spec, reduced=reduced)
|
|
62
|
+
print(record.to_frame())
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Output (the frame, as a table; resistance in ohm, efficiency and power capability as shares):
|
|
66
|
+
|
|
67
|
+
| code | field | value | low | high | unit | events | status |
|
|
68
|
+
|---|---|---|---|---|---|---|---|
|
|
69
|
+
| A1 | the remaining capacity | 11.52 | 11.41 | 11.64 | Ah | 210.4 | estimated |
|
|
70
|
+
| A2 | where possible, the remaining power capability | 0.7262 | 0.6553 | 0.797 | share of the first day | 283 | estimated |
|
|
71
|
+
| A3 | where possible, the remaining round trip efficiency | 0.9605 | 0.9602 | 0.9608 | share | 97.41 | estimated |
|
|
72
|
+
| A4 | the evolution of self-discharging rates | | | | mA | 210.4 | not possible from this data: the band of the offset current could not be computed |
|
|
73
|
+
| A5 | where possible, the ohmic resistance | 0.1406 | 0.1341 | 0.1471 | ohm | 55.67 | estimated |
|
|
74
|
+
| B1 | the date of manufacture of the battery and, where appropriate, the date of putting into service | | | | date | 0 | not possible from this data: not in the dataset |
|
|
75
|
+
| B2 | the energy throughput | 5646 | 5616 | 5676 | kWh | 1607 | estimated |
|
|
76
|
+
| B3 | the capacity throughput | 37250 | 37070 | 37420 | Ah | 1607 | estimated |
|
|
77
|
+
| B4 | the tracking of harmful events, such as the number of deep discharge events, time spent in extreme temperatures, time spent charging in extreme temperatures | 566 | 566 | 566 | events | 566 | estimated |
|
|
78
|
+
| B5 | the number of full equivalent charge-discharge cycles | 1242 | 1236 | 1247 | cycles | 1607 | estimated |
|
|
79
|
+
|
|
80
|
+
The sample is system 05, LMO/NMC, 15 Ah nominal, from August 2016 to September 2022: three reduced tables (one row per day, per current step and per rest candidate, not the raw samples), 6.8 MB in the package; the raw archive is 856 MB. The sample's data is CC BY 4.0, not BSD-3-Clause; its credit is in
|
|
81
|
+
[`NOTICE.md`](https://github.com/GhonAI/besslib/blob/v0.1.0/src/besslib/data/sample_05/NOTICE.md) and in each file's metadata.
|
|
82
|
+
|
|
83
|
+
The quickstart runs without the capacity-test mask, as a user would. The published record of the same system leaves
|
|
84
|
+
the test windows out ([Annex VII page](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/03_annex_vii.md)); a test checks that the sample with that mask
|
|
85
|
+
gives the published record exactly.
|
|
86
|
+
|
|
87
|
+
**Your own data:** a pandas DataFrame in the frame format of
|
|
88
|
+
[`besslib/frames.py`](https://github.com/GhonAI/besslib/blob/v0.1.0/src/besslib/frames.py) (columns, units, sign convention) and a `besslib.PackSpec`;
|
|
89
|
+
then `besslib.soh.annex_vii(frame, spec)`. **The full field data** of one system, from the Zenodo archive:
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
git clone https://github.com/GhonAI/besslib && cd besslib
|
|
93
|
+
pip install -e .[dev]
|
|
94
|
+
# downloads Data_ID_05.zip (856 MB), reduces it, deletes it, and writes
|
|
95
|
+
# validation/results/phase3/system_05_record.json and system_05_yearly.csv
|
|
96
|
+
python validation/run_annex_vii.py --held-out 5
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## What it computes
|
|
100
|
+
|
|
101
|
+
Each field carries a value, a band, the number of events it rests on, the method with its source, and a status.
|
|
102
|
+
Where the data cannot give a value, the status says `not possible from this data` with the reason. Nothing is
|
|
103
|
+
filled in silently.
|
|
104
|
+
|
|
105
|
+
| Code | Annex VII (quoted) | What besslib reports | Method and source |
|
|
106
|
+
|---|---|---|---|
|
|
107
|
+
| A1 | "the remaining capacity" | remaining capacity between the system's own end of charge and end of discharge | capacity between full and empty rests by coulomb counting, fitted with the offset current (Figgener et al., Nature Energy 9, 1438 (2024), doi:10.1038/s41560-024-01620-9) |
|
|
108
|
+
| A2 | "where possible, the remaining power capability" | power capability share, derived from the 1-second resistance, not measured | ratio of the resistance on the first day to the resistance at the date, from dV/dI of current steps between consecutive samples (Barai et al., Sci. Rep. 8, 21 (2018), doi:10.1038/s41598-017-18424-5; Schweiger et al., Sensors 10, 5604 (2010), doi:10.3390/s100605604); no power test |
|
|
109
|
+
| A3 | "where possible, the remaining round trip efficiency" | round-trip efficiency (DC, at the battery terminals) over full-to-full loops | energy out / energy in over closed loops between full rests (Regulation (EU) 2023/1542, Annex IV (6)); band: the ratio over these loops had each closed exactly, from the error of the state of charge at their end rests, estimated as the mean lag-2 product of the loop scores minus the mean lag-1 product |
|
|
110
|
+
| A4 | "the evolution of self-discharging rates" | apparent charge loss (an upper bound for self-discharge) | minus the offset current of the capacity fit (Figgener et al., Nature Energy 9, 1438 (2024), doi:10.1038/s41560-024-01620-9); band with the current sensor's gain error |
|
|
111
|
+
| A5 | "where possible, the ohmic resistance" | 1-second resistance, pack temperature band at 25 degrees C | dV/dI of current steps between consecutive samples (Barai et al., Sci. Rep. 8, 21 (2018), doi:10.1038/s41598-017-18424-5; Schweiger et al., Sensors 10, 5604 (2010), doi:10.3390/s100605604) |
|
|
112
|
+
| B1 | "the date of manufacture of the battery and, where appropriate, the date of putting into service" | date of manufacture; date of putting into service | the pack's documents (PackSpec), passed through |
|
|
113
|
+
| B2 | "the energy throughput" | energy throughput (in + out) since the first day of data | trapezoid sums of charging and discharging power over the measured time; band: sensor accuracy (Figgener et al. 2024, Supplementary Table 2) as a rectangular half-width (JCGM 100:2008, 4.3.7) |
|
|
114
|
+
| B3 | "the capacity throughput" | capacity throughput (in + out) since the first day of data | trapezoid sums of charging and discharging current over the measured time; band: sensor accuracy (Figgener et al. 2024, Supplementary Table 2) as a rectangular half-width (JCGM 100:2008, 4.3.7) |
|
|
115
|
+
| B4 | "the tracking of harmful events, such as the number of deep discharge events, time spent in extreme temperatures, time spent charging in extreme temperatures" | discharges to the system's own end-of-discharge level (observed; not a limit count) | measured hours per pack-temperature band and mode; discharges that reached the system's own end-of-discharge level (empty rests); voltage extremes; counts against limits when limits are given |
|
|
116
|
+
| B5 | "the number of full equivalent charge-discharge cycles" | full equivalent cycles since the first day of data | capacity throughput / (2 x reference capacity); band: sensor accuracy (Figgener et al. 2024, Supplementary Table 2) as a rectangular half-width (JCGM 100:2008, 4.3.7) |
|
|
117
|
+
|
|
118
|
+
## How it was checked
|
|
119
|
+
|
|
120
|
+
Thresholds were tuned on 7 development systems and frozen; the results below come from the
|
|
121
|
+
14 held-out systems, run once, and from synthetic packs with a known truth. A failed check is published as
|
|
122
|
+
failed, with its reason.
|
|
123
|
+
|
|
124
|
+
Configuration hashes: capacity `109e9eb1efa5`, record `c2f7f545cebb`. Every result file carries them.
|
|
125
|
+
|
|
126
|
+
**Capacity** ([page](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/02_capacity_validation.md); the reference tests: [page](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/01_reference.md))
|
|
127
|
+
|
|
128
|
+
| Check | Scope | Value | Pass if | Result |
|
|
129
|
+
|---|---|---|---|---|
|
|
130
|
+
| V2 | held-out LMO/NMC and NMC | median \|error\| 2.62 points (22/28 estimated) | <= 3 points | passed |
|
|
131
|
+
| V2 info | same, without 03/3 and 08/1 | median \|error\| 2.62 points (26 tests) | information | – |
|
|
132
|
+
| V3 | held-out LFP | median \|error\| inf points; median error +4.80 (5/10 estimated) | <= 5 points, bias shown | failed |
|
|
133
|
+
| V4 | held-out LMO/NMC and NMC | band held the test in 43% of 28 | >= 80 % | failed |
|
|
134
|
+
| V4 info | held-out LFP | band held the test in 10% of 10 | information | – |
|
|
135
|
+
| V4 info | same as V4, without 03/3 and 08/1 | band held the test in 42% of 26 | information | – |
|
|
136
|
+
| V5 | held-out LMO/NMC (4 systems) | mean fade -3.14 points/year; paper -3.1 | within +-0.5 | passed |
|
|
137
|
+
| V5 info | all LMO/NMC (6 systems) | mean fade -2.69 points/year | information | – |
|
|
138
|
+
| V5 | held-out NMC (5 systems) | mean fade -4.58 points/year; paper -1.9 | within +-0.5 | failed |
|
|
139
|
+
| V5 info | all NMC (7 systems) | mean fade -3.67 points/year | information | – |
|
|
140
|
+
| V5 | held-out LFP (5 systems) | mean fade -1.39 points/year; paper -2.0 | within +-0.5 | failed |
|
|
141
|
+
| V5 info | all LFP (8 systems) | mean fade -0.80 points/year | information | – |
|
|
142
|
+
| V6 | 200 synthetic packs | band held the true usable fade (-1.88) in 89.5% | 85-95 % | passed |
|
|
143
|
+
| V7 | core against batch path, 90 daily estimates (months of tests 01/1, 07/1, 17/2) | max relative difference 2.0e-15 | <= 1e-6 | passed |
|
|
144
|
+
| V8 | 21 systems | one command per system: python validation/run_capacity.py <id> | all 21 rebuilt with one hash | passed |
|
|
145
|
+
|
|
146
|
+
**The other Annex VII fields** ([page](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/03_annex_vii.md))
|
|
147
|
+
|
|
148
|
+
| Check | Scope | Value | Pass if | Result |
|
|
149
|
+
|---|---|---|---|---|
|
|
150
|
+
| W1 info | development records | 7 of 7 records; 0 fields break the rule | information | – |
|
|
151
|
+
| W1 | held-out records | 14 of 14 records; 0 fields break the rule | 0 | passed |
|
|
152
|
+
| W2 | 200 synthetic packs: resistance at the weighted mean age of the days in memory | fails under each truth. same-days truth 200 of 200: too wide, because that truth shares every day with the estimate, so the day-to-day scatter the statistical half-width stands for (median 0.62% of the value) is not in the difference; the largest difference is 0.77%, and the systematic half-width alone (median 0.53%) holds 187 of 200. At the date 0 of 200: the estimate lags the growing resistance (the value at the date is a median 2.3% above it). At 25 degrees C 90 of 200: the days in the band read a median +0.9% against 25 degrees C, and the estimator has no temperature model | 85-95 % | failed |
|
|
153
|
+
| W2 | 200 synthetic packs: resistance growth per year, whole record, against the simulator's known growth (median 4.93 % per year at the fit's origin; this truth was chosen after the first results) | band held the truth in 184 of 200 (92.0%); same-days truth (information): 199 of 200 (99.5%) | 85-95 % | passed |
|
|
154
|
+
| W5 | 200 synthetic packs: round-trip efficiency, full-to-full loops | band held the truth in 176 of 200 (88.0%) | 85-95 % | passed |
|
|
155
|
+
| W7 | 200 synthetic packs: apparent charge loss (hidden drain) | band held the truth in 87 of 200 (43.5%) | 85-95 % | failed |
|
|
156
|
+
| W8 | 200 synthetic packs: Ah, kWh, cycles; planted events (pack B: current gain error only) | largest relative error 0.498%; events exact on 200 of 200; 200 of 200 packs within the rule | <= 0.6 % and exact, every pack | passed |
|
|
157
|
+
| W8 info | 200 synthetic packs: the same on pack B with current and voltage noise | largest relative error 0.498%; events exact on 189 of 200; 189 of 200 packs within the rule | information | – |
|
|
158
|
+
| W3 info | development capacity tests | median \|difference\| 21.9 % over 12 of 22 tests with a reference; median difference by chemistry {'LFP': 64.1, 'LMO/NMC': -8.2, 'NMC': -11.5} | information | – |
|
|
159
|
+
| W3 | held-out capacity tests | 18 of 38 tests have a reference: not possible | >= 30 references, then <= 20 % | not possible |
|
|
160
|
+
| W4 info | development: neighbouring 5-degree bands: the colder reads higher | 59 of 68 (87%) | information | – |
|
|
161
|
+
| W6 info | development: full-to-full against empty-to-empty loop ratios within 1 point (no band needed) | 24 of 36 (67%) | information | – |
|
|
162
|
+
| W4 | held-out: neighbouring 5-degree bands: the colder reads higher | 112 of 120 (93%) | >= 80% | passed |
|
|
163
|
+
| W6 | held-out: full-to-full against empty-to-empty loop ratios within 1 point (no band needed) | 47 of 64 (73%) | >= 80% | failed |
|
|
164
|
+
| W9 | core against batch, resistance: 240 daily estimates (months of tests 01/1 (2017-06), 07/1 (2017-06), 17/2 (2020-06)) | max relative difference 3.6e-14 (64-bit); 2.6e-06 (32-bit, information) | <= 1e-6 | passed |
|
|
165
|
+
| W9 | core against batch, efficiency: 10 daily estimates (months of tests 01/1 (2017-06), 07/1 (2017-06), 17/2 (2020-06)) | max relative difference 0.0e+00 (64-bit); 1.3e-06 (32-bit, information) | <= 1e-6 | passed |
|
|
166
|
+
| W9 | daily counters against rest counters: 138814 rests, systems [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21] | max relative difference 8.7e-13 (throughput, system 13) | <= 1e-6 | passed |
|
|
167
|
+
| W10 | capacity settings and committed phase 2 files | hash 109e9eb1efa5; 0 of 60 committed files differ | 0 differences | passed |
|
|
168
|
+
| W10 | phase 2 rebuilt for 21 systems | 0 of 60 files differ | 0 differences | passed |
|
|
169
|
+
| W10 | records rebuilt twice for 21 systems | 0 differences over 42 files | 0 differences | passed |
|
|
170
|
+
|
|
171
|
+
## Limits
|
|
172
|
+
|
|
173
|
+
1. **Apparent charge loss (A4) is biased.** The band held the true drain in 87 of 200 packs (44 %).
|
|
174
|
+
2. **Capacity at or below zero still says estimated.** Records with a capacity at or below zero and the status `estimated`: system 09: -35.25 Ah.
|
|
175
|
+
3. **The capacity band leaves out the lag.** On 200 synthetic packs the monthly 90 % band held the true usable capacity at the date in 1386 of 4782 month ends (29 %), and at the weighted mean age of the pairs in memory in 4227 (88 %).
|
|
176
|
+
4. **Power capability estimated while resistance is not possible.** Power capability `estimated` while the resistance is `not possible`: system 08 reads 90 %; system 18 reads 102 %; system 19 reads 102 %; system 20 reads 144 %.
|
|
177
|
+
5. Already published on the pages: the method needs regular full cycles, the first year of a record gives no capacity estimate, apparent charge loss is an upper bound for self-discharge, efficiency is DC at the battery terminals, and resistance is a short-pulse value, not the impedance-spectroscopy one.
|
|
178
|
+
|
|
179
|
+
All limits, with their numbers and pages: [`docs/limits.md`](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/limits.md).
|
|
180
|
+
|
|
181
|
+
## Rebuild every number
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
git clone https://github.com/GhonAI/besslib && cd besslib
|
|
185
|
+
pip install -e .[dev]
|
|
186
|
+
python validation/build_reference.py # the field capacity tests, from the Zenodo archives
|
|
187
|
+
python validation/run_capacity.py <id> # capacity, one system
|
|
188
|
+
python validation/run_annex_vii.py <id> # the Annex VII record, one system
|
|
189
|
+
python validation/make_readme.py # this page
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The scripts download the archives one at a time and delete them after reducing.
|
|
193
|
+
|
|
194
|
+
## Cite
|
|
195
|
+
|
|
196
|
+
Use GitHub's "Cite this repository" ([`CITATION.cff`](https://github.com/GhonAI/besslib/blob/v0.1.0/CITATION.cff)), and cite the data.
|
|
197
|
+
|
|
198
|
+
## Data and credit
|
|
199
|
+
|
|
200
|
+
Data: Figgener, J. et al., Data for: Multi-year field measurements of home storage systems and their use in capacity estimation, Zenodo (2024), https://doi.org/10.5281/zenodo.12091223, licence CC BY 4.0.
|
|
201
|
+
|
|
202
|
+
Paper: Figgener, J. et al., Multi-year field measurements of home storage systems and their use in capacity estimation, Nature Energy 9, 1438-1447 (2024), https://doi.org/10.1038/s41560-024-01620-9, licence CC BY-NC-ND 4.0: cited, nothing copied.
|
|
203
|
+
|
|
204
|
+
## Contact
|
|
205
|
+
|
|
206
|
+
Islam Ghonaiem, ghonaiem@vgtai.com. Issues: [GitHub](https://github.com/GhonAI/besslib/issues).
|
|
207
|
+
|
|
208
|
+
## Licence
|
|
209
|
+
|
|
210
|
+
Code: BSD-3-Clause, see [`LICENSE`](https://github.com/GhonAI/besslib/blob/v0.1.0/LICENSE). The shipped sample: CC BY 4.0 (see above).
|
besslib-0.1.0/README.md
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# besslib
|
|
2
|
+
|
|
3
|
+
State of health from battery storage operating data — with confidence bands, in the fields of the
|
|
4
|
+
EU Battery Regulation (2023/1542, Annex VII).
|
|
5
|
+
|
|
6
|
+
**Version 0.1.0, 20 November 2026.** It computes the Annex VII parameters; it does not certify them. It is not a
|
|
7
|
+
compliance certificate and not legal advice.
|
|
8
|
+
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+
*System 05 (LMO/NMC, 15 Ah nominal): the capacity from operating data, at the end of each month, with its 90 % band, against the 4 field capacity tests (dots). 2 of the 4 tests have an estimate at their date, and the band holds the test value in 2 of them. The first estimate is at the end of September 2017: the first year gives none (grey). Hollow dots: tests without an estimate. 17 month ends without data are left blank.*
|
|
12
|
+
|
|
13
|
+
Checked on open field data: 21 home storage systems, 1,269 months, 60 field capacity tests.
|
|
14
|
+
On the 14 systems the method was not tuned on:
|
|
15
|
+
|
|
16
|
+
- LMO/NMC and NMC, 28 tests: median error 2.62 points of nominal capacity (target ≤ 3): **passed**.
|
|
17
|
+
- LFP, 10 tests: 5 have no estimate (target ≤ 5 points): **failed**.
|
|
18
|
+
- The 90 % band held the measured value in 43 % of 28 tests (target 80 %): **failed**. [Why →](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/limits.md)
|
|
19
|
+
|
|
20
|
+
Every number on this page is written by `validation/make_readme.py` from a results file in `validation/results/`.
|
|
21
|
+
|
|
22
|
+
## Install and run
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
pip install besslib
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
import besslib
|
|
30
|
+
reduced, spec = besslib.io.read_sample() # system 05, Aug 2016 – Sep 2022, CC BY 4.0
|
|
31
|
+
record = besslib.soh.annex_vii(None, spec, reduced=reduced)
|
|
32
|
+
print(record.to_frame())
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Output (the frame, as a table; resistance in ohm, efficiency and power capability as shares):
|
|
36
|
+
|
|
37
|
+
| code | field | value | low | high | unit | events | status |
|
|
38
|
+
|---|---|---|---|---|---|---|---|
|
|
39
|
+
| A1 | the remaining capacity | 11.52 | 11.41 | 11.64 | Ah | 210.4 | estimated |
|
|
40
|
+
| A2 | where possible, the remaining power capability | 0.7262 | 0.6553 | 0.797 | share of the first day | 283 | estimated |
|
|
41
|
+
| A3 | where possible, the remaining round trip efficiency | 0.9605 | 0.9602 | 0.9608 | share | 97.41 | estimated |
|
|
42
|
+
| A4 | the evolution of self-discharging rates | | | | mA | 210.4 | not possible from this data: the band of the offset current could not be computed |
|
|
43
|
+
| A5 | where possible, the ohmic resistance | 0.1406 | 0.1341 | 0.1471 | ohm | 55.67 | estimated |
|
|
44
|
+
| B1 | the date of manufacture of the battery and, where appropriate, the date of putting into service | | | | date | 0 | not possible from this data: not in the dataset |
|
|
45
|
+
| B2 | the energy throughput | 5646 | 5616 | 5676 | kWh | 1607 | estimated |
|
|
46
|
+
| B3 | the capacity throughput | 37250 | 37070 | 37420 | Ah | 1607 | estimated |
|
|
47
|
+
| B4 | the tracking of harmful events, such as the number of deep discharge events, time spent in extreme temperatures, time spent charging in extreme temperatures | 566 | 566 | 566 | events | 566 | estimated |
|
|
48
|
+
| B5 | the number of full equivalent charge-discharge cycles | 1242 | 1236 | 1247 | cycles | 1607 | estimated |
|
|
49
|
+
|
|
50
|
+
The sample is system 05, LMO/NMC, 15 Ah nominal, from August 2016 to September 2022: three reduced tables (one row per day, per current step and per rest candidate, not the raw samples), 6.8 MB in the package; the raw archive is 856 MB. The sample's data is CC BY 4.0, not BSD-3-Clause; its credit is in
|
|
51
|
+
[`NOTICE.md`](https://github.com/GhonAI/besslib/blob/v0.1.0/src/besslib/data/sample_05/NOTICE.md) and in each file's metadata.
|
|
52
|
+
|
|
53
|
+
The quickstart runs without the capacity-test mask, as a user would. The published record of the same system leaves
|
|
54
|
+
the test windows out ([Annex VII page](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/03_annex_vii.md)); a test checks that the sample with that mask
|
|
55
|
+
gives the published record exactly.
|
|
56
|
+
|
|
57
|
+
**Your own data:** a pandas DataFrame in the frame format of
|
|
58
|
+
[`besslib/frames.py`](https://github.com/GhonAI/besslib/blob/v0.1.0/src/besslib/frames.py) (columns, units, sign convention) and a `besslib.PackSpec`;
|
|
59
|
+
then `besslib.soh.annex_vii(frame, spec)`. **The full field data** of one system, from the Zenodo archive:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
git clone https://github.com/GhonAI/besslib && cd besslib
|
|
63
|
+
pip install -e .[dev]
|
|
64
|
+
# downloads Data_ID_05.zip (856 MB), reduces it, deletes it, and writes
|
|
65
|
+
# validation/results/phase3/system_05_record.json and system_05_yearly.csv
|
|
66
|
+
python validation/run_annex_vii.py --held-out 5
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## What it computes
|
|
70
|
+
|
|
71
|
+
Each field carries a value, a band, the number of events it rests on, the method with its source, and a status.
|
|
72
|
+
Where the data cannot give a value, the status says `not possible from this data` with the reason. Nothing is
|
|
73
|
+
filled in silently.
|
|
74
|
+
|
|
75
|
+
| Code | Annex VII (quoted) | What besslib reports | Method and source |
|
|
76
|
+
|---|---|---|---|
|
|
77
|
+
| A1 | "the remaining capacity" | remaining capacity between the system's own end of charge and end of discharge | capacity between full and empty rests by coulomb counting, fitted with the offset current (Figgener et al., Nature Energy 9, 1438 (2024), doi:10.1038/s41560-024-01620-9) |
|
|
78
|
+
| A2 | "where possible, the remaining power capability" | power capability share, derived from the 1-second resistance, not measured | ratio of the resistance on the first day to the resistance at the date, from dV/dI of current steps between consecutive samples (Barai et al., Sci. Rep. 8, 21 (2018), doi:10.1038/s41598-017-18424-5; Schweiger et al., Sensors 10, 5604 (2010), doi:10.3390/s100605604); no power test |
|
|
79
|
+
| A3 | "where possible, the remaining round trip efficiency" | round-trip efficiency (DC, at the battery terminals) over full-to-full loops | energy out / energy in over closed loops between full rests (Regulation (EU) 2023/1542, Annex IV (6)); band: the ratio over these loops had each closed exactly, from the error of the state of charge at their end rests, estimated as the mean lag-2 product of the loop scores minus the mean lag-1 product |
|
|
80
|
+
| A4 | "the evolution of self-discharging rates" | apparent charge loss (an upper bound for self-discharge) | minus the offset current of the capacity fit (Figgener et al., Nature Energy 9, 1438 (2024), doi:10.1038/s41560-024-01620-9); band with the current sensor's gain error |
|
|
81
|
+
| A5 | "where possible, the ohmic resistance" | 1-second resistance, pack temperature band at 25 degrees C | dV/dI of current steps between consecutive samples (Barai et al., Sci. Rep. 8, 21 (2018), doi:10.1038/s41598-017-18424-5; Schweiger et al., Sensors 10, 5604 (2010), doi:10.3390/s100605604) |
|
|
82
|
+
| B1 | "the date of manufacture of the battery and, where appropriate, the date of putting into service" | date of manufacture; date of putting into service | the pack's documents (PackSpec), passed through |
|
|
83
|
+
| B2 | "the energy throughput" | energy throughput (in + out) since the first day of data | trapezoid sums of charging and discharging power over the measured time; band: sensor accuracy (Figgener et al. 2024, Supplementary Table 2) as a rectangular half-width (JCGM 100:2008, 4.3.7) |
|
|
84
|
+
| B3 | "the capacity throughput" | capacity throughput (in + out) since the first day of data | trapezoid sums of charging and discharging current over the measured time; band: sensor accuracy (Figgener et al. 2024, Supplementary Table 2) as a rectangular half-width (JCGM 100:2008, 4.3.7) |
|
|
85
|
+
| B4 | "the tracking of harmful events, such as the number of deep discharge events, time spent in extreme temperatures, time spent charging in extreme temperatures" | discharges to the system's own end-of-discharge level (observed; not a limit count) | measured hours per pack-temperature band and mode; discharges that reached the system's own end-of-discharge level (empty rests); voltage extremes; counts against limits when limits are given |
|
|
86
|
+
| B5 | "the number of full equivalent charge-discharge cycles" | full equivalent cycles since the first day of data | capacity throughput / (2 x reference capacity); band: sensor accuracy (Figgener et al. 2024, Supplementary Table 2) as a rectangular half-width (JCGM 100:2008, 4.3.7) |
|
|
87
|
+
|
|
88
|
+
## How it was checked
|
|
89
|
+
|
|
90
|
+
Thresholds were tuned on 7 development systems and frozen; the results below come from the
|
|
91
|
+
14 held-out systems, run once, and from synthetic packs with a known truth. A failed check is published as
|
|
92
|
+
failed, with its reason.
|
|
93
|
+
|
|
94
|
+
Configuration hashes: capacity `109e9eb1efa5`, record `c2f7f545cebb`. Every result file carries them.
|
|
95
|
+
|
|
96
|
+
**Capacity** ([page](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/02_capacity_validation.md); the reference tests: [page](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/01_reference.md))
|
|
97
|
+
|
|
98
|
+
| Check | Scope | Value | Pass if | Result |
|
|
99
|
+
|---|---|---|---|---|
|
|
100
|
+
| V2 | held-out LMO/NMC and NMC | median \|error\| 2.62 points (22/28 estimated) | <= 3 points | passed |
|
|
101
|
+
| V2 info | same, without 03/3 and 08/1 | median \|error\| 2.62 points (26 tests) | information | – |
|
|
102
|
+
| V3 | held-out LFP | median \|error\| inf points; median error +4.80 (5/10 estimated) | <= 5 points, bias shown | failed |
|
|
103
|
+
| V4 | held-out LMO/NMC and NMC | band held the test in 43% of 28 | >= 80 % | failed |
|
|
104
|
+
| V4 info | held-out LFP | band held the test in 10% of 10 | information | – |
|
|
105
|
+
| V4 info | same as V4, without 03/3 and 08/1 | band held the test in 42% of 26 | information | – |
|
|
106
|
+
| V5 | held-out LMO/NMC (4 systems) | mean fade -3.14 points/year; paper -3.1 | within +-0.5 | passed |
|
|
107
|
+
| V5 info | all LMO/NMC (6 systems) | mean fade -2.69 points/year | information | – |
|
|
108
|
+
| V5 | held-out NMC (5 systems) | mean fade -4.58 points/year; paper -1.9 | within +-0.5 | failed |
|
|
109
|
+
| V5 info | all NMC (7 systems) | mean fade -3.67 points/year | information | – |
|
|
110
|
+
| V5 | held-out LFP (5 systems) | mean fade -1.39 points/year; paper -2.0 | within +-0.5 | failed |
|
|
111
|
+
| V5 info | all LFP (8 systems) | mean fade -0.80 points/year | information | – |
|
|
112
|
+
| V6 | 200 synthetic packs | band held the true usable fade (-1.88) in 89.5% | 85-95 % | passed |
|
|
113
|
+
| V7 | core against batch path, 90 daily estimates (months of tests 01/1, 07/1, 17/2) | max relative difference 2.0e-15 | <= 1e-6 | passed |
|
|
114
|
+
| V8 | 21 systems | one command per system: python validation/run_capacity.py <id> | all 21 rebuilt with one hash | passed |
|
|
115
|
+
|
|
116
|
+
**The other Annex VII fields** ([page](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/03_annex_vii.md))
|
|
117
|
+
|
|
118
|
+
| Check | Scope | Value | Pass if | Result |
|
|
119
|
+
|---|---|---|---|---|
|
|
120
|
+
| W1 info | development records | 7 of 7 records; 0 fields break the rule | information | – |
|
|
121
|
+
| W1 | held-out records | 14 of 14 records; 0 fields break the rule | 0 | passed |
|
|
122
|
+
| W2 | 200 synthetic packs: resistance at the weighted mean age of the days in memory | fails under each truth. same-days truth 200 of 200: too wide, because that truth shares every day with the estimate, so the day-to-day scatter the statistical half-width stands for (median 0.62% of the value) is not in the difference; the largest difference is 0.77%, and the systematic half-width alone (median 0.53%) holds 187 of 200. At the date 0 of 200: the estimate lags the growing resistance (the value at the date is a median 2.3% above it). At 25 degrees C 90 of 200: the days in the band read a median +0.9% against 25 degrees C, and the estimator has no temperature model | 85-95 % | failed |
|
|
123
|
+
| W2 | 200 synthetic packs: resistance growth per year, whole record, against the simulator's known growth (median 4.93 % per year at the fit's origin; this truth was chosen after the first results) | band held the truth in 184 of 200 (92.0%); same-days truth (information): 199 of 200 (99.5%) | 85-95 % | passed |
|
|
124
|
+
| W5 | 200 synthetic packs: round-trip efficiency, full-to-full loops | band held the truth in 176 of 200 (88.0%) | 85-95 % | passed |
|
|
125
|
+
| W7 | 200 synthetic packs: apparent charge loss (hidden drain) | band held the truth in 87 of 200 (43.5%) | 85-95 % | failed |
|
|
126
|
+
| W8 | 200 synthetic packs: Ah, kWh, cycles; planted events (pack B: current gain error only) | largest relative error 0.498%; events exact on 200 of 200; 200 of 200 packs within the rule | <= 0.6 % and exact, every pack | passed |
|
|
127
|
+
| W8 info | 200 synthetic packs: the same on pack B with current and voltage noise | largest relative error 0.498%; events exact on 189 of 200; 189 of 200 packs within the rule | information | – |
|
|
128
|
+
| W3 info | development capacity tests | median \|difference\| 21.9 % over 12 of 22 tests with a reference; median difference by chemistry {'LFP': 64.1, 'LMO/NMC': -8.2, 'NMC': -11.5} | information | – |
|
|
129
|
+
| W3 | held-out capacity tests | 18 of 38 tests have a reference: not possible | >= 30 references, then <= 20 % | not possible |
|
|
130
|
+
| W4 info | development: neighbouring 5-degree bands: the colder reads higher | 59 of 68 (87%) | information | – |
|
|
131
|
+
| W6 info | development: full-to-full against empty-to-empty loop ratios within 1 point (no band needed) | 24 of 36 (67%) | information | – |
|
|
132
|
+
| W4 | held-out: neighbouring 5-degree bands: the colder reads higher | 112 of 120 (93%) | >= 80% | passed |
|
|
133
|
+
| W6 | held-out: full-to-full against empty-to-empty loop ratios within 1 point (no band needed) | 47 of 64 (73%) | >= 80% | failed |
|
|
134
|
+
| W9 | core against batch, resistance: 240 daily estimates (months of tests 01/1 (2017-06), 07/1 (2017-06), 17/2 (2020-06)) | max relative difference 3.6e-14 (64-bit); 2.6e-06 (32-bit, information) | <= 1e-6 | passed |
|
|
135
|
+
| W9 | core against batch, efficiency: 10 daily estimates (months of tests 01/1 (2017-06), 07/1 (2017-06), 17/2 (2020-06)) | max relative difference 0.0e+00 (64-bit); 1.3e-06 (32-bit, information) | <= 1e-6 | passed |
|
|
136
|
+
| W9 | daily counters against rest counters: 138814 rests, systems [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21] | max relative difference 8.7e-13 (throughput, system 13) | <= 1e-6 | passed |
|
|
137
|
+
| W10 | capacity settings and committed phase 2 files | hash 109e9eb1efa5; 0 of 60 committed files differ | 0 differences | passed |
|
|
138
|
+
| W10 | phase 2 rebuilt for 21 systems | 0 of 60 files differ | 0 differences | passed |
|
|
139
|
+
| W10 | records rebuilt twice for 21 systems | 0 differences over 42 files | 0 differences | passed |
|
|
140
|
+
|
|
141
|
+
## Limits
|
|
142
|
+
|
|
143
|
+
1. **Apparent charge loss (A4) is biased.** The band held the true drain in 87 of 200 packs (44 %).
|
|
144
|
+
2. **Capacity at or below zero still says estimated.** Records with a capacity at or below zero and the status `estimated`: system 09: -35.25 Ah.
|
|
145
|
+
3. **The capacity band leaves out the lag.** On 200 synthetic packs the monthly 90 % band held the true usable capacity at the date in 1386 of 4782 month ends (29 %), and at the weighted mean age of the pairs in memory in 4227 (88 %).
|
|
146
|
+
4. **Power capability estimated while resistance is not possible.** Power capability `estimated` while the resistance is `not possible`: system 08 reads 90 %; system 18 reads 102 %; system 19 reads 102 %; system 20 reads 144 %.
|
|
147
|
+
5. Already published on the pages: the method needs regular full cycles, the first year of a record gives no capacity estimate, apparent charge loss is an upper bound for self-discharge, efficiency is DC at the battery terminals, and resistance is a short-pulse value, not the impedance-spectroscopy one.
|
|
148
|
+
|
|
149
|
+
All limits, with their numbers and pages: [`docs/limits.md`](https://github.com/GhonAI/besslib/blob/v0.1.0/docs/limits.md).
|
|
150
|
+
|
|
151
|
+
## Rebuild every number
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
git clone https://github.com/GhonAI/besslib && cd besslib
|
|
155
|
+
pip install -e .[dev]
|
|
156
|
+
python validation/build_reference.py # the field capacity tests, from the Zenodo archives
|
|
157
|
+
python validation/run_capacity.py <id> # capacity, one system
|
|
158
|
+
python validation/run_annex_vii.py <id> # the Annex VII record, one system
|
|
159
|
+
python validation/make_readme.py # this page
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The scripts download the archives one at a time and delete them after reducing.
|
|
163
|
+
|
|
164
|
+
## Cite
|
|
165
|
+
|
|
166
|
+
Use GitHub's "Cite this repository" ([`CITATION.cff`](https://github.com/GhonAI/besslib/blob/v0.1.0/CITATION.cff)), and cite the data.
|
|
167
|
+
|
|
168
|
+
## Data and credit
|
|
169
|
+
|
|
170
|
+
Data: Figgener, J. et al., Data for: Multi-year field measurements of home storage systems and their use in capacity estimation, Zenodo (2024), https://doi.org/10.5281/zenodo.12091223, licence CC BY 4.0.
|
|
171
|
+
|
|
172
|
+
Paper: Figgener, J. et al., Multi-year field measurements of home storage systems and their use in capacity estimation, Nature Energy 9, 1438-1447 (2024), https://doi.org/10.1038/s41560-024-01620-9, licence CC BY-NC-ND 4.0: cited, nothing copied.
|
|
173
|
+
|
|
174
|
+
## Contact
|
|
175
|
+
|
|
176
|
+
Islam Ghonaiem, ghonaiem@vgtai.com. Issues: [GitHub](https://github.com/GhonAI/besslib/issues).
|
|
177
|
+
|
|
178
|
+
## Licence
|
|
179
|
+
|
|
180
|
+
Code: BSD-3-Clause, see [`LICENSE`](https://github.com/GhonAI/besslib/blob/v0.1.0/LICENSE). The shipped sample: CC BY 4.0 (see above).
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "besslib"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "State of health from battery storage operating data, with confidence bands, in the fields of EU Regulation 2023/1542 Annex VII."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "BSD-3-Clause"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Islam Ghonaiem", email = "ghonaiem@vgtai.com" }]
|
|
14
|
+
keywords = [
|
|
15
|
+
"battery",
|
|
16
|
+
"battery energy storage",
|
|
17
|
+
"BESS",
|
|
18
|
+
"state of health",
|
|
19
|
+
"capacity estimation",
|
|
20
|
+
"EU Battery Regulation",
|
|
21
|
+
"Annex VII",
|
|
22
|
+
]
|
|
23
|
+
classifiers = [
|
|
24
|
+
"Development Status :: 3 - Alpha",
|
|
25
|
+
"Intended Audience :: Science/Research",
|
|
26
|
+
"Topic :: Scientific/Engineering",
|
|
27
|
+
"Programming Language :: Python :: 3",
|
|
28
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
29
|
+
"Programming Language :: Python :: 3.11",
|
|
30
|
+
"Programming Language :: Python :: 3.12",
|
|
31
|
+
]
|
|
32
|
+
dependencies = ["numpy>=2.0", "pandas>=2.2.2", "pyarrow>=16"]
|
|
33
|
+
|
|
34
|
+
[project.optional-dependencies]
|
|
35
|
+
plot = ["matplotlib>=3.8"]
|
|
36
|
+
dev = ["pytest>=8", "matplotlib>=3.8"]
|
|
37
|
+
|
|
38
|
+
[project.urls]
|
|
39
|
+
Source = "https://github.com/GhonAI/besslib"
|
|
40
|
+
Documentation = "https://github.com/GhonAI/besslib/tree/main/docs"
|
|
41
|
+
Issues = "https://github.com/GhonAI/besslib/issues"
|
|
42
|
+
|
|
43
|
+
[tool.setuptools.packages.find]
|
|
44
|
+
where = ["src"]
|
|
45
|
+
|
|
46
|
+
[tool.setuptools.package-data]
|
|
47
|
+
"besslib.io" = ["figgener_meta/*.csv", "figgener_meta/*.md"]
|
|
48
|
+
"besslib.data" = ["sample_05/*.parquet", "sample_05/NOTICE.md"]
|
|
49
|
+
|
|
50
|
+
[tool.pytest.ini_options]
|
|
51
|
+
testpaths = ["tests"]
|
|
52
|
+
addopts = "-q"
|
besslib-0.1.0/setup.cfg
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
"""besslib: state of health from battery storage operating data."""
|
|
2
|
+
|
|
3
|
+
from importlib import metadata as _metadata
|
|
4
|
+
|
|
5
|
+
from besslib import frames, io, soh
|
|
6
|
+
from besslib.frames import PackSpec
|
|
7
|
+
|
|
8
|
+
try:
|
|
9
|
+
__version__ = _metadata.version("besslib")
|
|
10
|
+
except _metadata.PackageNotFoundError: # running from a source tree that was never installed
|
|
11
|
+
__version__ = "unknown"
|
|
12
|
+
__all__ = ["PackSpec", "frames", "io", "soh", "__version__"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Data shipped with besslib: the sample of the quickstart (``besslib.io.read_sample``)."""
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Sample data: system 05 of the Figgener home-storage dataset
|
|
2
|
+
|
|
3
|
+
## What the files are
|
|
4
|
+
|
|
5
|
+
`daily.parquet`, `steps.parquet` and `rests.parquet` are the reduced tables of system 05: one row per day, per current step and per rest candidate. besslib reads them with `besslib.io.read_sample()`.
|
|
6
|
+
|
|
7
|
+
Modified: reduced by besslib 0.1.0 with validation/reduce_phase3.py: daily sums, current steps and rest candidates; not the original samples.
|
|
8
|
+
|
|
9
|
+
Made with the settings of configuration hashes 109e9eb1efa5 (capacity) and c2f7f545cebb (record).
|
|
10
|
+
|
|
11
|
+
## Credit
|
|
12
|
+
|
|
13
|
+
Creators, as in the Zenodo record:
|
|
14
|
+
|
|
15
|
+
- Figgener, Jan
|
|
16
|
+
- Haberschusz, David
|
|
17
|
+
- Wessels, Oliver
|
|
18
|
+
- Kairies, Kai-Philipp
|
|
19
|
+
- Bors, Jakob
|
|
20
|
+
- van Ouwerkerk, Jonas
|
|
21
|
+
- Sauer, Dirk Uwe
|
|
22
|
+
|
|
23
|
+
Title: Data for: Multi-year field measurements of home storage systems and their use in capacity estimation.
|
|
24
|
+
|
|
25
|
+
Source: Zenodo, https://doi.org/10.5281/zenodo.12091223, file Data_ID_05.zip.
|
|
26
|
+
|
|
27
|
+
Licence: CC BY 4.0, https://creativecommons.org/licenses/by/4.0/.
|
|
28
|
+
|
|
29
|
+
This sample is licensed under CC BY 4.0, not under the BSD-3-Clause licence of the besslib code.
|
|
30
|
+
|
|
31
|
+
## Disclaimer
|
|
32
|
+
|
|
33
|
+
The licensed material is provided as-is and as-available, without representations or warranties of any kind, as stated in Section 5 of the CC BY 4.0 licence (disclaimer of warranties and limitation of liability).
|
|
34
|
+
|
|
35
|
+
## The paper
|
|
36
|
+
|
|
37
|
+
The dataset belongs to an article in Nature Energy. Cite it when you use the data:
|
|
38
|
+
|
|
39
|
+
Figgener, J. et al., Multi-year field measurements of home storage systems and their use in capacity estimation, Nature Energy 9, 1438-1447 (2024), https://doi.org/10.1038/s41560-024-01620-9, licence CC BY-NC-ND 4.0: cited, nothing copied.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
"""The one data contract of besslib: column names, units and the sign convention.
|
|
2
|
+
|
|
3
|
+
Every function in ``besslib.soh`` reads a *frame*: a pandas DataFrame with a sorted,
|
|
4
|
+
timezone-naive ``DatetimeIndex`` and the columns below. ``besslib.sim`` (A2) writes
|
|
5
|
+
the same format.
|
|
6
|
+
|
|
7
|
+
Sign convention
|
|
8
|
+
---------------
|
|
9
|
+
Positive ``current_a`` and positive ``power_w`` mean **charging**: energy flows into
|
|
10
|
+
the battery and its state of charge rises. Discharging is negative.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from dataclasses import dataclass, field
|
|
16
|
+
from datetime import date
|
|
17
|
+
|
|
18
|
+
import pandas as pd
|
|
19
|
+
|
|
20
|
+
#: Required columns and their units.
|
|
21
|
+
REQUIRED = {
|
|
22
|
+
"voltage_v": "V, at the battery terminals",
|
|
23
|
+
"current_a": "A, positive = charging",
|
|
24
|
+
"power_w": "W, positive = charging",
|
|
25
|
+
"temp_pack_c": "degrees C, battery pack",
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
#: Optional columns and their units.
|
|
29
|
+
OPTIONAL = {
|
|
30
|
+
"temp_ambient_c": "degrees C, room or ambient",
|
|
31
|
+
"interpolated": "bool, True where the value was filled in, not measured",
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class FrameError(ValueError):
|
|
36
|
+
"""The DataFrame does not follow the besslib frame format."""
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def check_frame(frame: pd.DataFrame) -> pd.DataFrame:
|
|
40
|
+
"""Return ``frame`` unchanged if it follows the format; raise ``FrameError`` if not."""
|
|
41
|
+
if not isinstance(frame.index, pd.DatetimeIndex):
|
|
42
|
+
raise FrameError("the index must be a DatetimeIndex")
|
|
43
|
+
if frame.index.tz is not None:
|
|
44
|
+
raise FrameError("the index must be timezone-naive")
|
|
45
|
+
missing = [name for name in REQUIRED if name not in frame.columns]
|
|
46
|
+
if missing:
|
|
47
|
+
raise FrameError(f"missing columns: {', '.join(missing)}")
|
|
48
|
+
if not frame.index.is_monotonic_increasing:
|
|
49
|
+
raise FrameError("the index must be sorted by time")
|
|
50
|
+
if frame.index.has_duplicates:
|
|
51
|
+
raise FrameError("the index has duplicate timestamps")
|
|
52
|
+
return frame
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass(frozen=True)
|
|
56
|
+
class PackSpec:
|
|
57
|
+
"""What is known about a battery pack from its documents, not from its data.
|
|
58
|
+
|
|
59
|
+
``reference_capacity_ah`` is the value every state-of-health share is divided by.
|
|
60
|
+
besslib prints it with every share, because the same pack can read 100 % or 65 %
|
|
61
|
+
depending on the reference chosen.
|
|
62
|
+
"""
|
|
63
|
+
|
|
64
|
+
nominal_capacity_ah: float
|
|
65
|
+
nominal_energy_kwh: float
|
|
66
|
+
cells_in_series: int
|
|
67
|
+
cells_in_parallel: int = 1
|
|
68
|
+
chemistry: str = ""
|
|
69
|
+
nominal_voltage_v: float | None = None
|
|
70
|
+
voltage_max_v: float | None = None
|
|
71
|
+
voltage_min_v: float | None = None
|
|
72
|
+
reference_capacity_ah: float | None = None
|
|
73
|
+
date_of_manufacture: date | None = None
|
|
74
|
+
date_put_into_service: date | None = None
|
|
75
|
+
name: str = ""
|
|
76
|
+
extra: dict = field(default_factory=dict, compare=False)
|
|
77
|
+
|
|
78
|
+
def __post_init__(self) -> None:
|
|
79
|
+
if self.nominal_capacity_ah <= 0 or self.nominal_energy_kwh <= 0:
|
|
80
|
+
raise ValueError("nominal capacity and energy must be positive")
|
|
81
|
+
if self.cells_in_series < 1 or self.cells_in_parallel < 1:
|
|
82
|
+
raise ValueError("cell counts must be at least 1")
|
|
83
|
+
if self.reference_capacity_ah is None:
|
|
84
|
+
object.__setattr__(self, "reference_capacity_ah", self.nominal_capacity_ah)
|