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:
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`.
|
||||
Reference in new issue
Block a user