Add design spec for MA7D_DROP energy analysis

First analysis of the station energy-health use case: 7-day moving
average of BusVoltage compared to its own 30-day maximum, evaluated
causally at each hourly point, with a plotly visualisation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-09 18:31:38 +02:00
1 parent 57ea286014
commit e07656902a
1 file changed
+174
@@ -0,0 +1,174 @@
# Analyse énergétique v1 : tendance de tension en moyenne glissante (`MA7D_DROP`)
- Date : 2026-10-09
- Statut : design validé en brainstorming, spec à relire
- Périmètre : première analyse du cas d'usage « santé énergétique des stations » (voir `CLAUDE.md`)
## 1. Objectif
Écrire un script Python qui détermine **analytiquement**, point par point, si une station est dans un régime énergétique anormal, c'est-à-dire un régime qui menace son fonctionnement. Le script produit aussi un graphique qui montre les séries temporelles et une courbe du niveau d'anomalie.
Ce n'est **qu'une analyse parmi d'autres**. Elle doit avoir raison dans la majorité des situations, pas dans 100 % des cas. La force du diagnostic viendra de la combinaison de plusieurs analyses indépendantes. Cette combinaison est hors périmètre de la v1.
## 2. Décisions issues du brainstorming
| Sujet | Décision |
|---|---|
| Définition de l'anomalie | Un régime qui n'est pas soutenable : sur un cycle, l'apport ne couvre pas la consommation. Un niveau de charge bas n'est pas en soi l'anomalie. Une station débranchée avec une batterie pleine est déjà en anomalie. |
| Périmètre | Coupures avérées et déficit en cours. La prévision d'autonomie est reportée. |
| Analyse v1 | Une seule : la moyenne glissante de `BusVoltage` comparée à son propre passé récent. Cette idée vient de l'utilisateur. |
| Mode de calcul | Causal : le verdict au point t n'utilise que les données ≤ t. Le rejeu d'un historique équivaut au temps réel embarqué. |
| Niveau d'anomalie | Un indicateur continu en unité physique (V). Pas de score de 0 à 1, car les pseudo-probabilités sont interdites. |
| Embarqué | L'analyse n'utilise que la bibliothèque standard. Le graphique utilise plotly, sur le poste de dev seulement, dans `.venv/`. |
| Données de test | Données réelles uniquement (`data/`, `vermont/`). Aucune donnée simulée. |
## 3. Faits établis sur les données (exploration du 2026-10-09)
- **Unités.** Elles viennent du collecteur embarqué `src/__main__ (3).py` (bibliothèque INA219, shunt de 0,1 Ω) : `BusVoltage` en V, `BusCurrent` en mA, `Power` en mW, `ShuntVoltage` en mV. Les valeurs exportées sont des moyennes horaires.
- **`Power`, `BusCurrent` et `ShuntVoltage` sont une seule mesure.** P/(V·I) ≈ 0,99 et Shunt/0,1 Ω ≈ I. Elles mesurent la **consommation** de la station. L'apport (panneau ou secteur) **n'est pas mesuré**.
- **VERMONT consomme ~5,0 W constants d'avril à octobre.** Son déficit vient d'un apport en baisse, pas d'une consommation en hausse.
- **La fenêtre doit couvrir un nombre entier de jours** pour annuler le cycle jour/nuit. Avec une fenêtre de 72 h, la météo domine : deux jours nuageux font baisser JUNGFRAU (sain) d'environ −100 mV/j, autant qu'un vrai déficit. Avec 168 h, la météo est lissée.
- **Un seuil de tension absolu ne marche pas d'une station à l'autre.** Le niveau moyen est d'environ 14,25 V sur secteur et 13,4 V en solaire. Même en bonne santé, les nuits de JUNGFRAU descendent à 12,9 V et celles de VERMONT restent à 13,15 V.
## 4. Analyse `MA7D_DROP`
### 4.1 Définition
Les données sont sur une grille horaire. Pour chaque horodatage t de la série `BusVoltage` :
1. `ma(t)` = moyenne des valeurs non vides parmi les 168 créneaux horaires t−167 h … t. Si moins de 80 % des créneaux ont une valeur, `ma(t)` n'est pas défini.
2. `ref(t)` = maximum de `ma` sur les 720 créneaux t−720 h … t−1 h. Il n'est défini que si au moins 24 de ces `ma` sont définis.
3. `value(t)` = `ma(t)` − `ref(t)`, en V.
4. `anomaly(t)` vaut `True` si `value(t)` < −0,2 V et `False` sinon. Il vaut `None` (UNKNOWN) si `ma(t)` ou `ref(t)` n'est pas défini.
Un créneau absent du fichier compte comme une valeur vide. Tous les horodatages sont en UTC, avec fuseau horaire explicite (`datetime` aware).
### 4.2 Constantes et sources
Les constantes sont en tête de module, chacune avec sa source en commentaire. Ce sont des réglages de calibration.
| Constante | Valeur | Source |
|---|---|---|
| `WINDOW_H` | 168 | Multiple de 24 h, pour annuler le cycle jour/nuit. Avec 72 h, la météo n'est pas lissée (exploration du 2026-10-09, §3). |
| `REF_H` | 720 | 30 jours. Assez long pour contenir le dernier régime sain avant un déficit. C'est un choix de conception. |
| `MIN_COVERAGE` | 0,8 | Testé à 50 % : en début d'historique, la fenêtre réellement remplie devient trop courte et JUNGFRAU (sain) tombe à −0,19 V. À 80 %, il reste à −0,13 V. |
| `MIN_REF_POINTS` | 24 | Au moins un jour de référence. C'est un choix de conception. |
| `THRESHOLD_V` | −0,2 | Calé sur les cas de régression (§4.3). Pire cas sain : −0,16 V. Premiers franchissements en déficit avant les coupures. |
### 4.3 Résultats sur les cas annotés (prototype d'exploration)
| Station | Diagnostic expert | Pire écart en bonne santé | Premier point < −0,2 V | Première coupure énergétique |
|---|---|---|---|---|
| FLORIDA | secteur, sain | −0,04 V | aucun | aucune |
| JUNGFRAU | solaire, sain | −0,13 V | aucun | aucune |
| VERMONT | solaire, interruptions nocturnes | −0,16 V (05-11, 3 jours nuageux) | 2026-09-24 07:00 | 2026-09-27 01:00 (~2,8 j après) |
| WILDSTRUBEL | solaire, décharge profonde | — | 2026-09-06 14:00 | 2026-09-09 22:00 (~3,3 j après) |
| MISSISSIPPI | secteur, coupures | — | 2025-12-09 12:00 | 2025-12-25 14:00 |
### 4.4 Limites connues
Elles sont acceptées pour la v1 ; d'autres analyses viendront les couvrir.
1. **Marge mince** : le pire cas sain est à −0,16 V pour un seuil à −0,2 V. Le seuil n'est calé que sur 5 stations.
2. **Retard sur une perte secteur** : elle n'est détectée que 25 à 31 h après le début (MISSISSIPPI). Une station débranchée avec une petite batterie (7 Ah, environ 15 h d'autonomie à 5 W) coupe avant l'alerte.
3. **Biais pendant les coupures** : les valeurs qui manquent sont les plus basses de la nuit, donc `ma` est biaisé vers le haut. Quand la couverture tombe sous 80 %, le point passe en UNKNOWN.
4. **Coût de calcul** : le calcul naïf coûte O(n × (168 + 720)), soit quelques secondes pour un an de données horaires. En temps réel, il n'y a qu'un point par heure.
## 5. Contrat d'analyse
Toute analyse, actuelle ou future, respecte ce contrat pour pouvoir être combinée plus tard :
```python
run(series: dict[str, dict[datetime, float | None]]) -> Result
# series : {nom_métrique: {t: valeur ou None}}, une seule station
Result = {
"analysis": "MA7D_DROP",
"rule": {"threshold_v": -0.2, "window_h": 168, ...}, # constantes + leurs sources
"points": [Point, ...], # un point par horodatage de la série
}
Point = {
"t": datetime,
"value": float | None, # indicateur continu, unité physique
"anomaly": bool | None, # None = UNKNOWN
"facts": {...}, # faits qui justifient le verdict
}
```
Pour `MA7D_DROP`, `facts` contient `ma_v`, `ref_v`, `ref_t` (l'horodatage du maximum de référence) et `coverage`.
**Niveau de confiance** : une analyse seule conclut au plus à `consistent with` un déficit énergétique. Le niveau `strongly supported` demandera l'accord de plusieurs analyses indépendantes.
## 6. Entrées
- **Fichiers** : CSV nommés `<STATION>_<Metric>_<YYYY_MM_DD_HH_MM> to <YYYY_MM_DD_HH_MM>.csv`, avec les colonnes `,time_utc,metric`. Une valeur `metric` vide signifie qu'il n'y a pas de mesure.
- **Analyse du nom de fichier** : `^(?P<station>[^_]+)_(?P<metric>.+?)_\d{4}_\d{2}_\d{2}_\d{2}_\d{2} to .+\.csv$`. Le nom de métrique peut contenir des `_`, par exemple `sensor_thermal_deg_c`.
- **Arguments** : des fichiers et/ou des dossiers. Pour un dossier, tous les `*.csv` qu'il contient sont pris. Les séries sont regroupées par station.
- **Doublon** : si deux fichiers donnent la même métrique pour la même station, c'est une erreur explicite.
- **Station sans `BusVoltage`** : elle est ignorée, avec un message.
## 7. Sorties
### 7.1 `src/energy_check.py` (bibliothèque standard uniquement)
```bash
python3 src/energy_check.py vermont/ data/ [--out out/]
```
- **Fichier JSON** : un par station, `out/<STATION>_energy.json`. Il contient le `Result` (§5) et les `periods`.
- **Période d'anomalie** : séquence maximale de points dont `anomaly` vaut `True` ou `None`, qui commence et finit par `True`.
- Champs : `start`, `end`, `worst_value`, `worst_t`.
- `end` vaut `null` si tous les points qui suivent le dernier `True` de la période sont `None` (anomalie en cours ou non résolue en fin d'export).
- **Résumé texte** : un par station sur la sortie standard, généré à partir des faits. Exemple de **format** (les valeurs X sont remplies à partir de `facts`) :
> VERMONT : anomalie énergétique (`consistent with`) du 2026-09-24 07:00 à la fin de l'export. Moyenne sur 7 jours : X V, soit X V sous son maximum du <ref_t> (X V). Règle MA7D_DROP (seuil −0,2 V, source : cas de régression).
Une station sans anomalie produit une ligne « aucune anomalie (`not observed`) sur la période analysée », avec le pire écart et sa date.
- **Dossier de sortie** : `out/`, ignoré par git.
### 7.2 `src/energy_plot.py` (plotly, `.venv`)
```bash
.venv/bin/python src/energy_plot.py vermont/ [--out out/]
```
Le script importe `energy_check`, lance l'analyse et écrit `out/<STATION>_energy.html`. La page contient des sous-graphes empilés avec un axe de temps commun :
1. **Tension** : `BusVoltage` brute (trait fin), `ma`, `ref` et `ref − 0,2 V`. Les créneaux sans `BusVoltage` apparaissent en bandes grises.
2. **Écart** : `value` en V, avec une ligne horizontale à −0,2 V et un fond rouge sur les périodes d'anomalie. Le survol affiche `facts`.
3. **Métriques supplémentaires** : un sous-graphe par métrique présente pour la station (`Power`, températures…), dans l'ordre alphabétique.
## 8. Fichiers
| Fichier | Rôle |
|---|---|
| `src/energy_check.py` | chargement des CSV, analyse `MA7D_DROP`, JSON et résumé (bibliothèque standard) |
| `src/energy_plot.py` | graphique HTML (plotly) |
| `tests/test_energy_check.py` | tests de régression (`unittest`) |
| `.gitignore` | ajout de `out/` |
`src/__main__ (3).py` est une copie de référence du collecteur embarqué. Il n'est pas modifié.
## 9. Tests
Un seul fichier, `tests/test_energy_check.py`, en `unittest`, lancé avec `python3 -m unittest discover tests`. Il porte uniquement sur les données réelles :
| Cas | Assertion |
|---|---|
| FLORIDA | aucun point avec `anomaly is True` |
| JUNGFRAU | aucun point avec `anomaly is True` |
| VERMONT | 1re anomalie dans [2026-09-20 00:00, 2026-09-27 01:00) |
| WILDSTRUBEL | 1re anomalie < 2026-09-09 22:00 |
| MISSISSIPPI | 1re anomalie < 2025-12-25 14:00 |
| Causalité (VERMONT) | l'analyse sur la série tronquée à 2026-09-24 07:00 donne, pour ce point, le même `value` et le même `anomaly` que l'analyse complète |
| Nom de fichier | `VERMONT_sensor_thermal_deg_c_2026_02_22_15_00 to 2026_10_09_15_00.csv` donne la station `VERMONT` et la métrique `sensor_thermal_deg_c` |
## 10. Hors périmètre (analyses suivantes, même contrat)
- **Classement des trous** : coupure d'alimentation, cause externe, début d'historique, retard de synchronisation. Il s'appuie sur la tension avant et après le trou, comparée au coude LiFePO4 à 12,8 V.
- **Signature « station éteinte »** : chute de `sensor_thermal` pendant un trou, comparée aux mêmes heures les jours précédents.
- **Simultanéité entre stations** : un trou à la même heure sur plusieurs stations indique une cause commune hors station.
- **Taux de jours à charge complète** (tension ≥ 14,0 V) sur 7 jours glissants : alerte plus précoce en solaire (~10 j pour VERMONT).
- **Indicateur rapide de perte secteur** : sortie de la tension de maintien, pour couvrir la limite 2.
- **Autonomie sans apport** : énergie restante ÷ `Power`. Elle demande la capacité de la batterie (7 ou 21 Ah).
- **Combinaison des analyses** et passage au niveau `strongly supported`.