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/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