Files
Support-Agent/docs/superpowers/specs/2026-10-09-energy-ma7d-design.md
T
maximeandClaude Opus 5.5 e07656902a 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>
2026-10-09 18:31:38 +02:00

175 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.