diff --git a/docs/superpowers/specs/2026-10-09-energy-ma7d-design.md b/docs/superpowers/specs/2026-10-09-energy-ma7d-design.md new file mode 100644 index 0000000..f766c5b --- /dev/null +++ b/docs/superpowers/specs/2026-10-09-energy-ma7d-design.md @@ -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 `__ to .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[^_]+)_(?P.+?)_\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/_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 (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/_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`.