besslib 0.1.0__py3-none-any.whl
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/__init__.py +12 -0
- besslib/data/__init__.py +1 -0
- besslib/data/sample_05/NOTICE.md +39 -0
- besslib/data/sample_05/daily.parquet +0 -0
- besslib/data/sample_05/rests.parquet +0 -0
- besslib/data/sample_05/steps.parquet +0 -0
- besslib/frames.py +84 -0
- besslib/io/__init__.py +6 -0
- besslib/io/figgener.py +236 -0
- besslib/io/figgener_meta/README.md +12 -0
- besslib/io/figgener_meta/capacity_tests.csv +61 -0
- besslib/io/figgener_meta/systems.csv +22 -0
- besslib/soh/__init__.py +43 -0
- besslib/soh/_core.py +1081 -0
- besslib/soh/_ratio.py +277 -0
- besslib/soh/capacity.py +332 -0
- besslib/soh/capacity_test.py +205 -0
- besslib/soh/charge_loss.py +199 -0
- besslib/soh/config.py +153 -0
- besslib/soh/efficiency.py +270 -0
- besslib/soh/record.py +556 -0
- besslib/soh/reduce.py +352 -0
- besslib/soh/report.py +290 -0
- besslib/soh/resistance.py +570 -0
- besslib/soh/rests.py +488 -0
- besslib/soh/usage.py +322 -0
- besslib-0.1.0.dist-info/METADATA +210 -0
- besslib-0.1.0.dist-info/RECORD +31 -0
- besslib-0.1.0.dist-info/WHEEL +5 -0
- besslib-0.1.0.dist-info/licenses/LICENSE +28 -0
- besslib-0.1.0.dist-info/top_level.txt +1 -0
besslib/soh/reduce.py
ADDED
|
@@ -0,0 +1,352 @@
|
|
|
1
|
+
"""Reduce a long record to three small tables: one row per day, per current step and per rest.
|
|
2
|
+
|
|
3
|
+
The record is read once, piece by piece (for example month by month), and never held
|
|
4
|
+
whole. The three tables hold everything the usage counts, the resistance and the
|
|
5
|
+
round-trip efficiency need, so those can be computed again and again without reading the
|
|
6
|
+
raw data:
|
|
7
|
+
|
|
8
|
+
``daily``
|
|
9
|
+
One row per calendar day, none left out: seconds measured and interpolated, charge
|
|
10
|
+
and energy in and out, the lowest and highest voltage, and the measured seconds
|
|
11
|
+
spent charging, discharging and idle in each 1-degree pack-temperature bin.
|
|
12
|
+
``steps``
|
|
13
|
+
One row per current step at the loosest setting of the tuning grid: the two
|
|
14
|
+
currents and voltages around the step, the temperature and the seconds for which
|
|
15
|
+
the current stayed steady before the step. A step qualifies for a setting
|
|
16
|
+
``(min_step_c_rate, steady_s)`` when its size and its steady time reach it.
|
|
17
|
+
``rests``
|
|
18
|
+
The rest candidates of ``rests.detect_rests_in_parts``, with the running energy
|
|
19
|
+
counters, and five sums of the daily path (``*_today``) over the steps of the rest's
|
|
20
|
+
own day up to its start. The sum of the daily rows of the days before a rest plus
|
|
21
|
+
these ``*_today`` values reproduces the running counters of the rest detector by a
|
|
22
|
+
second, independent path; the two agree to rounding.
|
|
23
|
+
|
|
24
|
+
Definitions. A *step* is the interval between two consecutive samples. A step belongs to
|
|
25
|
+
the calendar day of its end sample. ``sample_s`` is the median sampling interval. A step
|
|
26
|
+
is *valid* when the current is finite at both ends. Charge and energy use the trapezoid
|
|
27
|
+
rule over the steps that are valid (energy: have a finite power at both ends) and not
|
|
28
|
+
longer than the break gap of the configuration; a step with a longer gap is not bridged.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
from dataclasses import dataclass
|
|
34
|
+
from pathlib import Path
|
|
35
|
+
|
|
36
|
+
import numpy as np
|
|
37
|
+
import pandas as pd
|
|
38
|
+
|
|
39
|
+
from besslib.frames import PackSpec, check_frame
|
|
40
|
+
from besslib.soh.config import CapacityConfig
|
|
41
|
+
from besslib.soh.rests import REST_COLUMNS, _arrays, _power, detect_rests_in_parts
|
|
42
|
+
|
|
43
|
+
#: Lower edge of the first temperature bin (degrees C) and the number of 1-degree bins.
|
|
44
|
+
TEMP_BIN_LOW_C = -20
|
|
45
|
+
TEMP_BINS = 90
|
|
46
|
+
#: The three operating modes of a step, as the daily table names them.
|
|
47
|
+
MODES = ("charge", "discharge", "idle")
|
|
48
|
+
#: The loosest step setting of the tuning grid: every step table row passes it.
|
|
49
|
+
LOOSEST_MIN_STEP_C_RATE = 0.05
|
|
50
|
+
LOOSEST_STEADY_S = 2.0
|
|
51
|
+
#: Longest steady look-back (s) and the tolerance of "steady" (share of the step size).
|
|
52
|
+
STEADY_CAP_S = 10.0
|
|
53
|
+
STEADY_TOLERANCE = 0.2
|
|
54
|
+
|
|
55
|
+
_TAIL = 24 # samples kept from the previous piece (a step and its steady look-back reach back at most this far)
|
|
56
|
+
_NBIN = TEMP_BINS + 1 # the last bin is "no temperature reading"
|
|
57
|
+
_SUM_COLUMNS = ["measured_s", "interpolated_s", "ah_in", "ah_out", "wh_in", "wh_out"]
|
|
58
|
+
_TODAY_COLUMNS = ["ah_in_today", "ah_out_today", "wh_in_today", "wh_out_today", "measured_s_today"]
|
|
59
|
+
_TODAY_FROM = [2, 3, 4, 5, 0] # their columns in _SUM_COLUMNS
|
|
60
|
+
STEP_COLUMNS = [
|
|
61
|
+
"time", "current_before_a", "current_after_a", "voltage_before_v", "voltage_after_v", "temp_pack_c", "steady_s",
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def _bin_names() -> list[str]:
|
|
66
|
+
names = []
|
|
67
|
+
for mode in MODES:
|
|
68
|
+
names += [f"s_{mode}_{k:02d}" for k in range(TEMP_BINS)] + [f"s_{mode}_nan"]
|
|
69
|
+
return names
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
_BIN_COLUMNS = _bin_names()
|
|
73
|
+
DAILY_COLUMNS = (
|
|
74
|
+
["day", "t_first", "t_last", "sample_s", *_SUM_COLUMNS, "voltage_min_v", "voltage_max_v"] + _BIN_COLUMNS
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@dataclass
|
|
79
|
+
class Reduced:
|
|
80
|
+
"""The three tables of a reduced record and its usual sampling interval (s)."""
|
|
81
|
+
|
|
82
|
+
daily: pd.DataFrame
|
|
83
|
+
steps: pd.DataFrame
|
|
84
|
+
rests: pd.DataFrame
|
|
85
|
+
sample_s: float
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _time(seconds) -> pd.DatetimeIndex:
|
|
89
|
+
return pd.to_datetime(np.asarray(seconds, dtype=np.int64), unit="s")
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
class _Tap:
|
|
93
|
+
"""Sums one piece of the record into daily rows, step rows and per-rest day sums.
|
|
94
|
+
|
|
95
|
+
A piece is read together with the last samples of the pieces before it, so the step
|
|
96
|
+
that ends at its first sample and the steady look-back of its first steps see their
|
|
97
|
+
neighbours. The day sums are made from per-step arrays, not from the running
|
|
98
|
+
counters of the rest detector.
|
|
99
|
+
"""
|
|
100
|
+
|
|
101
|
+
def __init__(self, spec: PackSpec, config: CapacityConfig) -> None:
|
|
102
|
+
self.config = config
|
|
103
|
+
self.idle_a = config.current_c_rate * spec.nominal_capacity_ah
|
|
104
|
+
self.step_a = LOOSEST_MIN_STEP_C_RATE * spec.nominal_capacity_ah
|
|
105
|
+
self.tail = None
|
|
106
|
+
self.sample_s: list[float] = []
|
|
107
|
+
self.carry_day = None
|
|
108
|
+
self.carry = np.zeros(len(_TODAY_COLUMNS))
|
|
109
|
+
# per piece: day numbers, sums, bin seconds, vmin, vmax, first and last sample time
|
|
110
|
+
self.days, self.sums, self.bins, self.vmin, self.vmax, self.tfirst, self.tlast = [], [], [], [], [], [], []
|
|
111
|
+
self.steps: list[pd.DataFrame] = []
|
|
112
|
+
self.today: list[np.ndarray] = []
|
|
113
|
+
|
|
114
|
+
def __call__(self, prev, cur: pd.DataFrame, tables) -> None:
|
|
115
|
+
check_frame(cur)
|
|
116
|
+
cfg = self.config
|
|
117
|
+
t_c, i_c, v_c, temp_c, interp_c = _arrays(cur)
|
|
118
|
+
p_c = _power(cur)
|
|
119
|
+
n = len(t_c)
|
|
120
|
+
# sample interval of this piece: the median step, as the rest detector's counters
|
|
121
|
+
dt_c = np.diff(t_c).astype(float)
|
|
122
|
+
if len(dt_c):
|
|
123
|
+
s = float(np.median(dt_c))
|
|
124
|
+
else:
|
|
125
|
+
s = self.sample_s[-1] if self.sample_s else 1.0
|
|
126
|
+
self.sample_s.append(s)
|
|
127
|
+
|
|
128
|
+
if self.tail is None:
|
|
129
|
+
m = 0
|
|
130
|
+
t, i, v, temp, interp, p = t_c, i_c, v_c, temp_c, interp_c, p_c
|
|
131
|
+
else:
|
|
132
|
+
m = len(self.tail[0])
|
|
133
|
+
t, i, v, temp, interp, p = (np.concatenate([a, b]) for a, b in zip(self.tail, (t_c, i_c, v_c, temp_c, interp_c, p_c)))
|
|
134
|
+
self.tail = tuple(a[-_TAIL:] for a in (t, i, v, temp, interp, p))
|
|
135
|
+
|
|
136
|
+
# --- per-step arrays, one value per sample of this piece (0 where the sample has no step) ---
|
|
137
|
+
lo = 1 if m == 0 else 0 # the first sample of the record has no step
|
|
138
|
+
J = np.arange(m + lo, m + n) # end samples of the steps in this piece
|
|
139
|
+
dt = (t[J] - t[J - 1]).astype(float)
|
|
140
|
+
fi = np.isfinite(i)
|
|
141
|
+
valid = fi[J] & fi[J - 1]
|
|
142
|
+
bridged = valid & (dt <= cfg.break_gap_s)
|
|
143
|
+
ii = np.where(fi, i, 0.0)
|
|
144
|
+
pf = np.isfinite(p)
|
|
145
|
+
pbridged = pf[J] & pf[J - 1] & (dt <= cfg.break_gap_s)
|
|
146
|
+
pp = np.where(pf, p, 0.0)
|
|
147
|
+
|
|
148
|
+
def trapezoid(x, ok):
|
|
149
|
+
return np.where(ok, 0.5 * (x[J] + x[J - 1]) * dt, 0.0)
|
|
150
|
+
|
|
151
|
+
rows = np.zeros((len(_SUM_COLUMNS), n))
|
|
152
|
+
sl = slice(lo, n)
|
|
153
|
+
measured = np.where(valid, np.where(dt <= 1.5 * s, dt, s), 0.0)
|
|
154
|
+
rows[0, sl] = measured
|
|
155
|
+
rows[1, sl] = np.where(interp[J], np.minimum(dt, cfg.break_gap_s), 0.0)
|
|
156
|
+
rows[2, sl] = trapezoid(np.maximum(ii, 0.0), bridged) / 3600.0
|
|
157
|
+
rows[3, sl] = trapezoid(np.maximum(-ii, 0.0), bridged) / 3600.0
|
|
158
|
+
rows[4, sl] = trapezoid(np.maximum(pp, 0.0), pbridged) / 3600.0
|
|
159
|
+
rows[5, sl] = trapezoid(np.maximum(-pp, 0.0), pbridged) / 3600.0
|
|
160
|
+
|
|
161
|
+
# mode and temperature bin of the end sample
|
|
162
|
+
mode = np.where(i_c >= self.idle_a, 0, np.where(i_c <= -self.idle_a, 1, 2))
|
|
163
|
+
okt = np.isfinite(temp_c)
|
|
164
|
+
with np.errstate(invalid="ignore"):
|
|
165
|
+
k = np.clip(np.floor(np.where(okt, temp_c, 0.0)) - TEMP_BIN_LOW_C, 0, TEMP_BINS - 1)
|
|
166
|
+
col = mode * _NBIN + np.where(okt, k, TEMP_BINS).astype(np.int64)
|
|
167
|
+
|
|
168
|
+
# --- daily sums: the samples of each calendar day are contiguous ---
|
|
169
|
+
day = t_c // 86400
|
|
170
|
+
starts = np.concatenate([[0], np.flatnonzero(np.diff(day)) + 1])
|
|
171
|
+
seg = np.zeros(n, dtype=np.int64)
|
|
172
|
+
seg[starts[1:]] = 1
|
|
173
|
+
seg = np.cumsum(seg)
|
|
174
|
+
nseg = len(starts)
|
|
175
|
+
sums = np.add.reduceat(rows, starts, axis=1).T
|
|
176
|
+
bins = np.bincount(seg * (3 * _NBIN) + col, weights=rows[0], minlength=nseg * 3 * _NBIN).reshape(nseg, 3 * _NBIN)
|
|
177
|
+
self.days.append(day[starts])
|
|
178
|
+
self.sums.append(sums)
|
|
179
|
+
self.bins.append(bins)
|
|
180
|
+
self.vmin.append(np.fmin.reduceat(v_c, starts))
|
|
181
|
+
self.vmax.append(np.fmax.reduceat(v_c, starts))
|
|
182
|
+
self.tfirst.append(t_c[starts])
|
|
183
|
+
self.tlast.append(t_c[np.concatenate([starts[1:] - 1, [n - 1]])])
|
|
184
|
+
|
|
185
|
+
# --- the sums of the rest's own day up to its start ---
|
|
186
|
+
rests = tables[0]
|
|
187
|
+
if len(rests):
|
|
188
|
+
r = np.searchsorted(t_c, rests["start"].astype("datetime64[s]").astype(np.int64))
|
|
189
|
+
if not np.array_equal(t_c[r], rests["start"].astype("datetime64[s]").astype(np.int64)):
|
|
190
|
+
raise ValueError("a rest starts at a time that is not a sample of its piece")
|
|
191
|
+
cs = np.cumsum(rows[_TODAY_FROM], axis=1)
|
|
192
|
+
before = np.where(starts[seg[r]] > 0, cs[:, np.maximum(starts[seg[r]] - 1, 0)], 0.0)
|
|
193
|
+
today = (cs[:, r] - before).T
|
|
194
|
+
if self.carry_day is not None:
|
|
195
|
+
first = seg[r] == 0
|
|
196
|
+
if day[0] == self.carry_day:
|
|
197
|
+
today[first] += self.carry
|
|
198
|
+
self.today.append(today)
|
|
199
|
+
else:
|
|
200
|
+
self.today.append(np.zeros((0, len(_TODAY_COLUMNS))))
|
|
201
|
+
last = sums[-1, _TODAY_FROM].copy()
|
|
202
|
+
if self.carry_day is not None and day[-1] == self.carry_day:
|
|
203
|
+
last += self.carry
|
|
204
|
+
self.carry, self.carry_day = last, int(day[-1])
|
|
205
|
+
|
|
206
|
+
# --- the step rows ---
|
|
207
|
+
fv = np.isfinite(v)
|
|
208
|
+
di = np.abs(i[J] - i[J - 1])
|
|
209
|
+
ok = valid & fv[J] & fv[J - 1] & ~interp[J] & ~interp[J - 1] & (dt <= 1.5 * s)
|
|
210
|
+
with np.errstate(invalid="ignore"):
|
|
211
|
+
ok &= di >= self.step_a
|
|
212
|
+
c = J[ok]
|
|
213
|
+
if len(c):
|
|
214
|
+
dic = di[ok]
|
|
215
|
+
ref = i[c - 1]
|
|
216
|
+
reach = max(1, int(round(STEADY_CAP_S / s)))
|
|
217
|
+
alive = np.ones(len(c), dtype=bool)
|
|
218
|
+
n_ok = np.zeros(len(c))
|
|
219
|
+
for back in range(1, reach + 1):
|
|
220
|
+
kk = c - 1 - back
|
|
221
|
+
inside = kk >= 0
|
|
222
|
+
kc = np.maximum(kk, 0)
|
|
223
|
+
with np.errstate(invalid="ignore"):
|
|
224
|
+
good = (
|
|
225
|
+
inside & fi[kc] & ~interp[kc] & ((t[kc + 1] - t[kc]) <= 1.5 * s)
|
|
226
|
+
& (np.abs(i[kc] - ref) <= STEADY_TOLERANCE * dic)
|
|
227
|
+
)
|
|
228
|
+
alive &= good
|
|
229
|
+
n_ok += alive
|
|
230
|
+
steady = n_ok * s
|
|
231
|
+
keep = steady >= LOOSEST_STEADY_S
|
|
232
|
+
c, steady = c[keep], steady[keep]
|
|
233
|
+
self.steps.append(
|
|
234
|
+
pd.DataFrame(
|
|
235
|
+
{
|
|
236
|
+
"time": _time(t[c]),
|
|
237
|
+
"current_before_a": i[c - 1],
|
|
238
|
+
"current_after_a": i[c],
|
|
239
|
+
"voltage_before_v": v[c - 1],
|
|
240
|
+
"voltage_after_v": v[c],
|
|
241
|
+
"temp_pack_c": temp[c],
|
|
242
|
+
"steady_s": steady,
|
|
243
|
+
}
|
|
244
|
+
)
|
|
245
|
+
)
|
|
246
|
+
|
|
247
|
+
# --- the finished tables ---
|
|
248
|
+
def daily(self, sample_s: float) -> pd.DataFrame:
|
|
249
|
+
if not self.days:
|
|
250
|
+
return pd.DataFrame(columns=DAILY_COLUMNS)
|
|
251
|
+
day = np.concatenate(self.days)
|
|
252
|
+
full = np.arange(day.min(), day.max() + 1)
|
|
253
|
+
pos = np.searchsorted(full, day)
|
|
254
|
+
out_sums = np.zeros((len(full), len(_SUM_COLUMNS)))
|
|
255
|
+
out_bins = np.zeros((len(full), 3 * _NBIN))
|
|
256
|
+
np.add.at(out_sums, pos, np.concatenate(self.sums))
|
|
257
|
+
np.add.at(out_bins, pos, np.concatenate(self.bins))
|
|
258
|
+
vmin = np.full(len(full), np.nan)
|
|
259
|
+
vmax = np.full(len(full), np.nan)
|
|
260
|
+
np.fmin.at(vmin, pos, np.concatenate(self.vmin))
|
|
261
|
+
np.fmax.at(vmax, pos, np.concatenate(self.vmax))
|
|
262
|
+
big = np.iinfo(np.int64).max
|
|
263
|
+
tfirst = np.full(len(full), big, dtype=np.int64)
|
|
264
|
+
tlast = np.full(len(full), -big, dtype=np.int64)
|
|
265
|
+
np.minimum.at(tfirst, pos, np.concatenate(self.tfirst))
|
|
266
|
+
np.maximum.at(tlast, pos, np.concatenate(self.tlast))
|
|
267
|
+
none = tfirst == big
|
|
268
|
+
data = {
|
|
269
|
+
"day": pd.to_datetime(full * 86400, unit="s"),
|
|
270
|
+
"t_first": pd.to_datetime(np.where(none, 0, tfirst), unit="s").where(~none),
|
|
271
|
+
"t_last": pd.to_datetime(np.where(none, 0, tlast), unit="s").where(~none),
|
|
272
|
+
"sample_s": np.full(len(full), sample_s),
|
|
273
|
+
}
|
|
274
|
+
for k, name in enumerate(_SUM_COLUMNS):
|
|
275
|
+
data[name] = out_sums[:, k]
|
|
276
|
+
data["voltage_min_v"] = vmin
|
|
277
|
+
data["voltage_max_v"] = vmax
|
|
278
|
+
for k, name in enumerate(_BIN_COLUMNS):
|
|
279
|
+
data[name] = out_bins[:, k]
|
|
280
|
+
return pd.DataFrame(data)[DAILY_COLUMNS]
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
def reduce_parts(parts, spec: PackSpec, config: CapacityConfig | None = None, log=None) -> Reduced:
|
|
284
|
+
"""Reduce a record that comes in consecutive pieces (for example months) to its three tables.
|
|
285
|
+
|
|
286
|
+
``parts`` is any iterable of frames in time order; it is read once, and at most three
|
|
287
|
+
pieces are in memory at a time. The rest candidates are those of
|
|
288
|
+
``rests.detect_rests_in_parts`` for ``config`` (default ``CapacityConfig()``), with the
|
|
289
|
+
energy counters and the day sums added. ``log`` is called with the number of pieces
|
|
290
|
+
finished.
|
|
291
|
+
"""
|
|
292
|
+
config = config or CapacityConfig()
|
|
293
|
+
tap = _Tap(spec, config)
|
|
294
|
+
table = detect_rests_in_parts(parts, spec, config, log=log, each=tap)
|
|
295
|
+
sample_s = float(np.median(tap.sample_s)) if tap.sample_s else float("nan")
|
|
296
|
+
daily = tap.daily(sample_s)
|
|
297
|
+
steps = (
|
|
298
|
+
pd.concat(tap.steps, ignore_index=True) if tap.steps else pd.DataFrame({c: [] for c in STEP_COLUMNS})
|
|
299
|
+
)[STEP_COLUMNS]
|
|
300
|
+
table = table.reset_index(drop=True)
|
|
301
|
+
today = np.concatenate(tap.today) if tap.today else np.zeros((0, len(_TODAY_COLUMNS)))
|
|
302
|
+
for k, name in enumerate(_TODAY_COLUMNS):
|
|
303
|
+
table[name] = today[:, k]
|
|
304
|
+
# a step table keeps its dtypes even when empty
|
|
305
|
+
steps["time"] = pd.to_datetime(steps["time"])
|
|
306
|
+
for name in STEP_COLUMNS[1:]:
|
|
307
|
+
steps[name] = steps[name].astype("float64")
|
|
308
|
+
return Reduced(daily=daily, steps=steps, rests=table[REST_COLUMNS + _TODAY_COLUMNS], sample_s=sample_s)
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
def reduce_frame(frame: pd.DataFrame, spec: PackSpec, config: CapacityConfig | None = None) -> Reduced:
|
|
312
|
+
"""Reduce one frame held in memory; the same as ``reduce_parts([frame], ...)``."""
|
|
313
|
+
return reduce_parts([frame], spec, config)
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
def _paths(folder, name) -> dict[str, Path]:
|
|
317
|
+
return {k: Path(folder) / f"{name}_{k}.parquet" for k in ("daily", "steps", "rests")}
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
def write_reduced(reduced: Reduced, folder, name: str) -> None:
|
|
321
|
+
"""Write ``<folder>/<name>_daily.parquet``, ``_steps.parquet`` and ``_rests.parquet``."""
|
|
322
|
+
Path(folder).mkdir(parents=True, exist_ok=True)
|
|
323
|
+
paths = _paths(folder, name)
|
|
324
|
+
reduced.daily.to_parquet(paths["daily"], index=False, compression="zstd")
|
|
325
|
+
reduced.steps.to_parquet(paths["steps"], index=False, compression="zstd")
|
|
326
|
+
reduced.rests.to_parquet(paths["rests"], index=False, compression="zstd")
|
|
327
|
+
|
|
328
|
+
|
|
329
|
+
def read_reduced(folder, name: str) -> Reduced:
|
|
330
|
+
"""Read the three tables written by ``write_reduced``."""
|
|
331
|
+
paths = _paths(folder, name)
|
|
332
|
+
daily = pd.read_parquet(paths["daily"])
|
|
333
|
+
sample_s = float(daily["sample_s"].iloc[0]) if len(daily) else float("nan")
|
|
334
|
+
return Reduced(
|
|
335
|
+
daily=daily, steps=pd.read_parquet(paths["steps"]), rests=pd.read_parquet(paths["rests"]), sample_s=sample_s
|
|
336
|
+
)
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
def temp_hours(daily: pd.DataFrame) -> pd.DataFrame:
|
|
340
|
+
"""Hours spent in each mode and 1-degree temperature bin, over all the days of ``daily``.
|
|
341
|
+
|
|
342
|
+
Long form with the columns ``mode``, ``temp_c`` (lower edge of the bin in degrees C;
|
|
343
|
+
NaN for the rows of no temperature reading) and ``hours``. Every mode has
|
|
344
|
+
``TEMP_BINS + 1`` rows.
|
|
345
|
+
"""
|
|
346
|
+
rows = []
|
|
347
|
+
edges = list(range(TEMP_BIN_LOW_C, TEMP_BIN_LOW_C + TEMP_BINS)) + [np.nan]
|
|
348
|
+
for mode in MODES:
|
|
349
|
+
names = [f"s_{mode}_{k:02d}" for k in range(TEMP_BINS)] + [f"s_{mode}_nan"]
|
|
350
|
+
seconds = daily[names].sum(axis=0).to_numpy(dtype=float)
|
|
351
|
+
rows.append(pd.DataFrame({"mode": mode, "temp_c": np.array(edges, dtype=float), "hours": seconds / 3600.0}))
|
|
352
|
+
return pd.concat(rows, ignore_index=True)
|
besslib/soh/report.py
ADDED
|
@@ -0,0 +1,290 @@
|
|
|
1
|
+
"""One self-contained HTML page for an Annex VII record.
|
|
2
|
+
|
|
3
|
+
``report`` writes the record's ten fields as a table, the method and limits of each,
|
|
4
|
+
the data credit and both configuration hashes into one HTML file: inline style, no
|
|
5
|
+
scripts, no external files. Given a ``history`` (records at earlier dates), it adds one
|
|
6
|
+
small figure per field with numbers, embedded as PNG; the figures need matplotlib.
|
|
7
|
+
|
|
8
|
+
The same record gives the same bytes: the page holds no time of writing, and the PNG
|
|
9
|
+
files carry no software stamp.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import base64
|
|
15
|
+
import io
|
|
16
|
+
import math
|
|
17
|
+
from html import escape
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
import pandas as pd
|
|
21
|
+
|
|
22
|
+
from besslib.soh.record import AnnexVII
|
|
23
|
+
|
|
24
|
+
NOT_A_CERTIFICATE = (
|
|
25
|
+
"It computes the Annex VII parameters; it does not certify them. It is not a compliance certificate and not "
|
|
26
|
+
"legal advice."
|
|
27
|
+
)
|
|
28
|
+
NO_MATPLOTLIB = "figures need matplotlib (pip install besslib[plot])"
|
|
29
|
+
NO_HISTORY = "A history (records at earlier dates, history=) adds one figure per field."
|
|
30
|
+
|
|
31
|
+
_COLUMNS = ("Code", "Annex VII field", "besslib label", "Value", "Low", "High", "Unit", "Events", "Status")
|
|
32
|
+
_PNG_METADATA = {"Software": None} # no version stamp: the same figure gives the same bytes
|
|
33
|
+
_LINE = "#2a78d6"
|
|
34
|
+
_INK = "#0b0b0b"
|
|
35
|
+
_INK2 = "#52514e"
|
|
36
|
+
_GRID = "#e4e3df"
|
|
37
|
+
_SURFACE = "#fcfcfb"
|
|
38
|
+
|
|
39
|
+
_STYLE = """
|
|
40
|
+
:root { color-scheme: light; --bg: #fcfcfb; --surface: #f3f2ee; --ink: #0b0b0b; --ink2: #52514e;
|
|
41
|
+
--rule: #d9d8d2; --accent: #2a78d6; --estimated: #1d6b3a; --absent: #8a4b00; }
|
|
42
|
+
@media (prefers-color-scheme: dark) {
|
|
43
|
+
:root:not([data-theme="light"]) { color-scheme: dark; --bg: #1a1a19; --surface: #242422; --ink: #f0efec;
|
|
44
|
+
--ink2: #c3c2b7; --rule: #3a3a37; --accent: #3987e5; --estimated: #7fd19c; --absent: #f0b46a; }
|
|
45
|
+
}
|
|
46
|
+
:root[data-theme="dark"] { color-scheme: dark; --bg: #1a1a19; --surface: #242422; --ink: #f0efec;
|
|
47
|
+
--ink2: #c3c2b7; --rule: #3a3a37; --accent: #3987e5; --estimated: #7fd19c; --absent: #f0b46a; }
|
|
48
|
+
* { box-sizing: border-box; }
|
|
49
|
+
body { margin: 0; background: var(--bg); color: var(--ink);
|
|
50
|
+
font: 15px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
|
|
51
|
+
main { max-width: 72rem; margin: 0 auto; padding: 24px 16px 48px; }
|
|
52
|
+
h1 { font-size: 1.5rem; line-height: 1.25; margin: 0 0 4px; }
|
|
53
|
+
h2 { font-size: 1.15rem; margin: 32px 0 8px; border-bottom: 1px solid var(--rule); padding-bottom: 4px; }
|
|
54
|
+
h3 { font-size: 1rem; margin: 20px 0 4px; }
|
|
55
|
+
p { margin: 4px 0; }
|
|
56
|
+
.sub { color: var(--ink2); margin: 0 0 16px; }
|
|
57
|
+
.notice { background: var(--surface); border-left: 3px solid var(--accent); padding: 8px 12px; margin: 16px 0; }
|
|
58
|
+
dl.facts { display: grid; grid-template-columns: max-content 1fr; gap: 2px 16px; margin: 8px 0; }
|
|
59
|
+
dl.facts dt { color: var(--ink2); }
|
|
60
|
+
dl.facts dd { margin: 0; overflow-wrap: anywhere; }
|
|
61
|
+
.scroll { overflow-x: auto; -webkit-overflow-scrolling: touch; }
|
|
62
|
+
table { border-collapse: collapse; width: 100%; font-size: 0.9rem; }
|
|
63
|
+
caption { text-align: left; color: var(--ink2); padding: 0 0 6px; }
|
|
64
|
+
th, td { text-align: left; vertical-align: top; padding: 6px 8px; border-bottom: 1px solid var(--rule); }
|
|
65
|
+
th { font-weight: 600; background: var(--surface); }
|
|
66
|
+
td.num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; }
|
|
67
|
+
td.estimated { color: var(--estimated); }
|
|
68
|
+
td.absent { color: var(--absent); }
|
|
69
|
+
code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.9em; }
|
|
70
|
+
.field { margin: 0 0 12px; }
|
|
71
|
+
.label { color: var(--ink2); }
|
|
72
|
+
figure { margin: 12px 0; }
|
|
73
|
+
figure img { display: block; max-width: 100%; height: auto; border-radius: 6px; background: #fcfcfb; }
|
|
74
|
+
figcaption { color: var(--ink2); font-size: 0.85rem; margin-top: 4px; }
|
|
75
|
+
footer { margin-top: 40px; color: var(--ink2); font-size: 0.85rem; border-top: 1px solid var(--rule);
|
|
76
|
+
padding-top: 12px; overflow-wrap: anywhere; }
|
|
77
|
+
"""
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _num(value) -> str:
|
|
81
|
+
"""A number to 4 significant digits, without an exponent from 1e-4 to 1e9; blank for NaN or None."""
|
|
82
|
+
if value is None:
|
|
83
|
+
return ""
|
|
84
|
+
v = float(value)
|
|
85
|
+
if not math.isfinite(v):
|
|
86
|
+
return ""
|
|
87
|
+
if v == 0 or not 1e-4 <= abs(v) < 1e9:
|
|
88
|
+
return f"{v:.4g}"
|
|
89
|
+
decimals = 3 - math.floor(math.log10(abs(v)))
|
|
90
|
+
text = f"{round(v, decimals):.{max(decimals, 0)}f}"
|
|
91
|
+
return text.rstrip("0").rstrip(".") if "." in text else text
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _date(stamp) -> str:
|
|
95
|
+
return str(pd.Timestamp(stamp))
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _status_class(status: str) -> str:
|
|
99
|
+
return "estimated" if status == "estimated" else "absent" if status.startswith("not possible") else ""
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def _table(record: AnnexVII) -> str:
|
|
103
|
+
head = "".join(f'<th scope="col">{escape(c)}</th>' for c in _COLUMNS)
|
|
104
|
+
rows = []
|
|
105
|
+
for f in record.fields:
|
|
106
|
+
cls = f' class="{_status_class(f.status)}"' if _status_class(f.status) else ""
|
|
107
|
+
rows.append(
|
|
108
|
+
"<tr>"
|
|
109
|
+
f'<th scope="row"><code>{escape(f.code)}</code></th>'
|
|
110
|
+
f"<td>{escape(f.field)}</td>"
|
|
111
|
+
f"<td>{escape(f.label)}</td>"
|
|
112
|
+
f'<td class="num">{_num(f.value)}</td>'
|
|
113
|
+
f'<td class="num">{_num(f.low)}</td>'
|
|
114
|
+
f'<td class="num">{_num(f.high)}</td>'
|
|
115
|
+
f"<td>{escape(f.unit)}</td>"
|
|
116
|
+
f'<td class="num">{_num(f.events)}</td>'
|
|
117
|
+
f"<td{cls}>{escape(f.status)}</td>"
|
|
118
|
+
"</tr>"
|
|
119
|
+
)
|
|
120
|
+
caption = f"The ten parameters of Annex VII. Bands at the level {_num(record.level)}"
|
|
121
|
+
a1_level = next((f.details.get("band_level") for f in record.fields if f.code == "A1"), None)
|
|
122
|
+
caption += f"; A1 at {_num(a1_level)}." if a1_level is not None else "."
|
|
123
|
+
return (
|
|
124
|
+
f'<div class="scroll"><table><caption>{escape(caption)}</caption>'
|
|
125
|
+
f"<thead><tr>{head}</tr></thead><tbody>{''.join(rows)}</tbody></table></div>"
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _texts(details: dict) -> list[tuple[str, str]]:
|
|
130
|
+
"""The texts of a field's details that say what it is and where it stops."""
|
|
131
|
+
out = []
|
|
132
|
+
for key, name in (("what_it_is", "What it is"), ("what_it_holds", "What it holds"), ("limits", "Limits")):
|
|
133
|
+
text = details.get(key)
|
|
134
|
+
if isinstance(text, str) and text:
|
|
135
|
+
out.append((name, text))
|
|
136
|
+
for key in ("date_of_manufacture", "date_put_into_service"):
|
|
137
|
+
if key in details:
|
|
138
|
+
value = details[key]
|
|
139
|
+
shown = "" if value is None else str(value)
|
|
140
|
+
status = details.get(f"{key}_status", "")
|
|
141
|
+
text = "; ".join(t for t in (shown, status) if t)
|
|
142
|
+
out.append((key.replace("_", " ").capitalize(), text))
|
|
143
|
+
return out
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def _methods(record: AnnexVII) -> str:
|
|
147
|
+
parts = []
|
|
148
|
+
for f in record.fields:
|
|
149
|
+
rows = [("Annex VII field", f.field), ("Method and source", f.method), *_texts(f.details), ("Status", f.status)]
|
|
150
|
+
facts = "".join(f"<dt>{escape(k)}</dt><dd>{escape(v)}</dd>" for k, v in rows)
|
|
151
|
+
parts.append(
|
|
152
|
+
f'<section class="field"><h3><code>{escape(f.code)}</code> '
|
|
153
|
+
f'<span class="label">{escape(f.label)}</span></h3><dl class="facts">{facts}</dl></section>'
|
|
154
|
+
)
|
|
155
|
+
return "".join(parts)
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def _series(records: list[AnnexVII], code: str) -> pd.DataFrame:
|
|
159
|
+
rows = []
|
|
160
|
+
for r in records:
|
|
161
|
+
f = r.field(code)
|
|
162
|
+
rows.append({"date": pd.Timestamp(r.date), "value": f.value, "low": f.low, "high": f.high, "unit": f.unit})
|
|
163
|
+
return pd.DataFrame(rows)
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def _figure(series: pd.DataFrame, code: str, unit: str) -> str:
|
|
167
|
+
"""One field over the dates as base64 PNG: the value as a line, the band as a shaded area."""
|
|
168
|
+
from matplotlib.backends.backend_agg import FigureCanvasAgg
|
|
169
|
+
from matplotlib.figure import Figure
|
|
170
|
+
|
|
171
|
+
fig = Figure(figsize=(6.4, 2.6), dpi=110, facecolor=_SURFACE)
|
|
172
|
+
FigureCanvasAgg(fig)
|
|
173
|
+
ax = fig.add_subplot()
|
|
174
|
+
ax.set_facecolor(_SURFACE)
|
|
175
|
+
x = series["date"].dt.to_pydatetime()
|
|
176
|
+
band = series["low"].notna() & series["high"].notna()
|
|
177
|
+
if band.any():
|
|
178
|
+
ax.fill_between(x, series["low"], series["high"], where=band.to_numpy(), color=_LINE, alpha=0.18,
|
|
179
|
+
linewidth=0)
|
|
180
|
+
# a whisker per date, so that a date between dates without numbers still shows its band
|
|
181
|
+
ax.vlines([d for d, ok in zip(x, band) if ok], series["low"][band], series["high"][band], color=_LINE,
|
|
182
|
+
alpha=0.5, linewidth=1.5)
|
|
183
|
+
ax.plot(x, series["value"], color=_LINE, linewidth=2, marker="o", markersize=5)
|
|
184
|
+
ax.set_title(code, loc="left", fontsize=9, color=_INK)
|
|
185
|
+
ax.set_ylabel(unit, fontsize=8, color=_INK2)
|
|
186
|
+
ax.tick_params(labelsize=8, colors=_INK2)
|
|
187
|
+
ax.grid(axis="y", color=_GRID, linewidth=0.8)
|
|
188
|
+
for side in ("top", "right"):
|
|
189
|
+
ax.spines[side].set_visible(False)
|
|
190
|
+
for side in ("left", "bottom"):
|
|
191
|
+
ax.spines[side].set_color(_GRID)
|
|
192
|
+
fig.autofmt_xdate()
|
|
193
|
+
fig.tight_layout()
|
|
194
|
+
buf = io.BytesIO()
|
|
195
|
+
fig.savefig(buf, format="png", metadata=_PNG_METADATA, facecolor=_SURFACE)
|
|
196
|
+
return base64.b64encode(buf.getvalue()).decode("ascii")
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def _history_table(series: pd.DataFrame) -> str:
|
|
200
|
+
rows = "".join(
|
|
201
|
+
f"<tr><td>{escape(_date(d))}</td><td class=\"num\">{_num(v)}</td><td class=\"num\">{_num(lo)}</td>"
|
|
202
|
+
f"<td class=\"num\">{_num(hi)}</td></tr>"
|
|
203
|
+
for d, v, lo, hi in zip(series["date"], series["value"], series["low"], series["high"])
|
|
204
|
+
)
|
|
205
|
+
return (
|
|
206
|
+
'<div class="scroll"><table><thead><tr><th scope="col">Date</th><th scope="col">Value</th>'
|
|
207
|
+
f'<th scope="col">Low</th><th scope="col">High</th></tr></thead><tbody>{rows}</tbody></table></div>'
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def _history(record: AnnexVII, history) -> str:
|
|
212
|
+
if history is None:
|
|
213
|
+
return f"<p>{escape(NO_HISTORY)}</p>"
|
|
214
|
+
by_date = {pd.Timestamp(r.date): r for r in history}
|
|
215
|
+
by_date.setdefault(pd.Timestamp(record.date), record)
|
|
216
|
+
records = [by_date[d] for d in sorted(by_date)]
|
|
217
|
+
try:
|
|
218
|
+
import matplotlib # noqa: F401
|
|
219
|
+
except ImportError:
|
|
220
|
+
plot = False
|
|
221
|
+
else:
|
|
222
|
+
plot = True
|
|
223
|
+
first, last = _date(records[0].date), _date(records[-1].date)
|
|
224
|
+
parts = [f"<p>{escape(f'{len(records)} dates, {first} to {last}.')}</p>"]
|
|
225
|
+
if not plot:
|
|
226
|
+
parts.append(f"<p>{escape(NO_MATPLOTLIB)}</p>")
|
|
227
|
+
for f in record.fields:
|
|
228
|
+
series = _series(records, f.code)
|
|
229
|
+
if not series["value"].map(lambda v: v is not None and math.isfinite(float(v))).any():
|
|
230
|
+
continue
|
|
231
|
+
parts.append(f"<h3><code>{escape(f.code)}</code> <span class=\"label\">{escape(f.label)}</span></h3>")
|
|
232
|
+
if plot:
|
|
233
|
+
png = _figure(series, f.code, f.unit)
|
|
234
|
+
alt = f"{f.code} {f.label} over {len(records)} dates, in {f.unit}, with its band"
|
|
235
|
+
parts.append(
|
|
236
|
+
f"<figure><img src=\"data:image/png;base64,{png}\" alt=\"{escape(alt)}\" width=\"704\" "
|
|
237
|
+
f"height=\"286\"><figcaption>{escape(f'Value and band, in {f.unit}')}</figcaption></figure>"
|
|
238
|
+
)
|
|
239
|
+
parts.append(_history_table(series))
|
|
240
|
+
return "".join(parts)
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def report(record: AnnexVII, path, history=None) -> Path:
|
|
244
|
+
"""Write the record as one self-contained HTML page at ``path``; return the path.
|
|
245
|
+
|
|
246
|
+
Parameters
|
|
247
|
+
----------
|
|
248
|
+
record
|
|
249
|
+
An ``AnnexVII`` record (``besslib.soh.annex_vii``).
|
|
250
|
+
path
|
|
251
|
+
The HTML file to write.
|
|
252
|
+
history
|
|
253
|
+
Optional records of the same battery at earlier dates (for example year ends).
|
|
254
|
+
With matplotlib installed, one figure per field that has numbers over those
|
|
255
|
+
dates is embedded as PNG; without it, the page says so.
|
|
256
|
+
"""
|
|
257
|
+
path = Path(path)
|
|
258
|
+
name = record.pack.get("name") or "battery"
|
|
259
|
+
when = _date(record.date)
|
|
260
|
+
title = f"Annex VII record: {name}, {when}"
|
|
261
|
+
facts = [
|
|
262
|
+
("Pack", name),
|
|
263
|
+
("Chemistry", str(record.pack.get("chemistry") or "")),
|
|
264
|
+
("Record date", when),
|
|
265
|
+
("Reference capacity", f"{_num(record.reference_capacity_ah)} Ah"),
|
|
266
|
+
("Configuration hash, capacity", record.capacity_config_hash),
|
|
267
|
+
("Configuration hash, record", record.record_config_hash),
|
|
268
|
+
("Annex VII wording", record.annex_vii_version),
|
|
269
|
+
]
|
|
270
|
+
facts_html = "".join(f"<dt>{escape(k)}</dt><dd>{escape(v)}</dd>" for k, v in facts if v)
|
|
271
|
+
credit = (
|
|
272
|
+
f"<footer><p><strong>Data credit.</strong> {escape(record.data_credit)}</p></footer>"
|
|
273
|
+
if record.data_credit else ""
|
|
274
|
+
)
|
|
275
|
+
page = (
|
|
276
|
+
"<!doctype html>\n"
|
|
277
|
+
'<html lang="en">\n<head>\n<meta charset="utf-8">\n'
|
|
278
|
+
'<meta name="viewport" content="width=device-width, initial-scale=1">\n'
|
|
279
|
+
f"<title>{escape(title)}</title>\n<style>{_STYLE}</style>\n</head>\n<body>\n<main>\n"
|
|
280
|
+
f"<h1>Annex VII record: {escape(name)}</h1>\n"
|
|
281
|
+
f'<p class="sub">At {escape(when)}. Made with besslib.</p>\n'
|
|
282
|
+
f'<p class="notice">{escape(NOT_A_CERTIFICATE)}</p>\n'
|
|
283
|
+
f'<dl class="facts">{facts_html}</dl>\n'
|
|
284
|
+
f"<h2>The ten parameters</h2>\n{_table(record)}\n"
|
|
285
|
+
f"<h2>Over time</h2>\n{_history(record, history)}\n"
|
|
286
|
+
f"<h2>Methods and limits</h2>\n{_methods(record)}\n"
|
|
287
|
+
f"{credit}\n</main>\n</body>\n</html>\n"
|
|
288
|
+
)
|
|
289
|
+
path.write_text(page, encoding="utf-8")
|
|
290
|
+
return path
|