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

12 KiB
Raw Blame History

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 :

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)

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)

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