Add the day color matrix, the energy diagnostic manual and the site figure
D-020: the delivered energy diagnostic keeps analyses 03 and 04 only, combined by the state x trend matrix of cas-d-usage-03-04.drawio into one color per day (green / orange / red, grey when unknown), coded in src/day_color.py (standard library). docs/guide/diagnostic-energetique.md explains it: part 1 for the client, part 2 for support. D-021: energy_plot.daily_figure builds the figure for the monitoring site (panel 03 above panel 04, shared time axis), written by analyse_01.py as out/<STATION>_daily.html and .json. battery_state no longer imports energy_check, so analyses 03 and 04 ship on their own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
129d4ff59b
commit
fc74fec10f
9 files changed
+467
-8
No files matched your search
@@ -3,7 +3,7 @@
|
||||
- **Statut** : prototype en place (2026-10-12). Phase C : l'état seul, sans verdict. La phase B (niveaux gradués) viendra ensuite (D-018).
|
||||
- **Script** : `python3 src/analyse_03.py [CSV ou dossiers]` (défaut : `data/`). Il lance la page commune de `analyse_01.py` : `out/<STATION>_energy.html`, où cette analyse est le troisième panneau d'analyse (D-016).
|
||||
- **Code** :
|
||||
- `src/battery_state.py` : calcul, bibliothèque standard uniquement (`run()`, `day_facts()`). Il reçoit les séries chargées par `energy_check.load_stations` ;
|
||||
- `src/battery_state.py` : calcul, bibliothèque standard uniquement (`run()`, `day_facts()`). Il reçoit les séries chargées par `energy_check.load_stations`, mais n'importe rien d'autre du projet : avec `src/battery_trend.py`, il se livre seul à la plateforme (D-021) ;
|
||||
- `src/energy_plot.py` : graphique plotly.
|
||||
|
||||
## Question posée
|
||||
|
||||
@@ -172,3 +172,37 @@ Règles du journal :
|
||||
- décaler la fin de nuit d'un jour, pour qu'elle porte sur la même journée que l'état (la fin de nuit du matin de J porte le bilan de J−1). Essayé dans la 03, puis dans la 04 seule, et écarté par l'utilisateur les deux fois. Sur VERMONT, il ramenait les barres de la 04 contraires à l'état de 16 à 4 sur 28 changements d'état, au prix d'un jour de retard ;
|
||||
- garder `t` sur le jour J en prenant la fin de nuit de J+1 : non causal.
|
||||
- **Conséquence** : l'incohérence entre l'état et la barre reste une limite connue de l'analyse 04 (limite 6 de sa fiche).
|
||||
|
||||
## D-020 — 2026-10-12 — Diagnostic énergétique livré : couleur du jour (matrice 03 × 04) et manuel
|
||||
- **Statut** : active. Remplace, pour le diagnostic livré, la « phase B » de l'analyse 03 et la combinaison prévue par D-005.
|
||||
- **Décision** :
|
||||
- le diagnostic énergétique livré ne retient que les analyses 03 (`DAILY_BATTERY_STATE`) et 04 (`DAILY_BATTERY_TREND`) ;
|
||||
- elles se combinent par une matrice état × tendance en une **couleur par jour et par station** : vert (soutenable ce jour-là), orange (incertain, à surveiller), rouge (non soutenable). La matrice est tenue par l'utilisateur dans `cas-d-usage-03-04.drawio` ;
|
||||
- un manuel l'explique, en deux couches : une lecture rapide pour le client final, une annexe technique pour l'ingénieur support (`docs/guide/diagnostic-energetique.md`).
|
||||
- **Pourquoi** : demande de l'utilisateur. Il faut apprendre au lecteur à lire les signaux envoyés ; la couleur sert d'entrée en matière, les analyses de détail.
|
||||
- **Options écartées** :
|
||||
- `NO_CHARGE` × `STABLE` en orange : une coupure d'alimentation passerait du rouge (1er jour) à l'orange (jours suivants) alors qu'elle continue, contre D-004 ;
|
||||
- un manuel pour un seul public (client ou support).
|
||||
- **Conséquence** :
|
||||
- la matrice n'est pas encore codée : le manuel décrit la cible ;
|
||||
- les analyses 01 et 02 restent dans le code et sur la page HTML, mais ne font plus partie du diagnostic livré ;
|
||||
- les cas inconnus (état ou tendance) ne sont pas encore traités dans la matrice, laissés de côté par l'utilisateur ;
|
||||
- le destinataire du diagnostic n'est plus ouvert : le client et le support, en couches.
|
||||
|
||||
## D-021 — 2026-10-12 — Graphique des analyses 03 et 04 pour le site de monitoring
|
||||
- **Statut** : active. Complète D-020.
|
||||
- **Décision** :
|
||||
- le graphique destiné au site de monitoring (Plotly) est une seule figure : le panneau de l'analyse 03 en haut, celui de l'analyse 04 dessous, sur le même axe du temps. Ce sont les panneaux de la page des analyses (D-016), sans changement ;
|
||||
- `src/energy_plot.py` en écrit une page de démo (`out/<STATION>_daily.html`) et la figure en JSON (`out/<STATION>_daily.json`), que le site passe à `Plotly.newPlot` ;
|
||||
- la matrice de D-020 est codée dans `src/day_color.py` (bibliothèque standard, embarquable), mais n'est pas tracée. Quand l'état ou la tendance est inconnu, la couleur l'est aussi (gris).
|
||||
- **Pourquoi** : demande de l'utilisateur, qui veut intégrer le diagnostic au site (page « System Summary ») et trouve les deux panneaux plus clairs qu'une couleur par jour.
|
||||
- **Options écartées** :
|
||||
- une bande d'une case par jour (couleur de la matrice, flèche de tendance) au-dessus de `BusVoltage` horaire : essayée, jugée « pas claire » par l'utilisateur ;
|
||||
- superposer les deux panneaux en double axe (03 à gauche en V, 04 à droite en ΔV), dans un 3e panneau : essayé, mauvaise lisibilité selon l'utilisateur. Le zéro de l'axe de droite tombe vers 13,6 V, les tirets de la zone morte s'y lisent comme des seuils de tension, et les grandes barres cachent la fin de nuit. Deux superpositions sur un seul axe en V n'ont pas été essayées : la tendance en marqueurs ▲ ● ▼ sur la courbe de fin de nuit, ou chaque barre tracée de la fin de nuit de J−1 à celle de J ;
|
||||
- teinter le fond de la courbe `BusVoltage`, jour par jour : la teinte se lit moins bien que des cases, et elle gêne la lecture de la courbe ;
|
||||
- pour un jour inconnu, reprendre la couleur de la colonne de l'état quand elle est unique (`FULL_CHARGE` sans veille serait vert) : l'utilisateur préfère le gris, les cas inconnus restant à traiter (D-020).
|
||||
- **Conséquence** :
|
||||
- la couleur du jour est calculée mais n'apparaît sur aucun graphique ;
|
||||
- le calcul des analyses 03 et 04 (`battery_state.py`, `battery_trend.py`) n'importe plus rien des analyses 01 et 02 : il se livre seul ;
|
||||
- le format d'intégration côté site (JSON, fragment HTML ou backend Python) reste à choisir avec l'équipe du site.
|
||||
|
||||
@@ -0,0 +1,177 @@
|
||||
# Manuel : lire le diagnostic énergétique d'une station AIMsight
|
||||
|
||||
- **Statut** : brouillon, 2026-10-12. La couleur du jour (partie 1) est calculée par `src/day_color.py`, selon la matrice de `cas-d-usage-03-04.drawio` (D-020), mais aucun graphique ne l'affiche encore (D-021).
|
||||
- **Lecteurs** : la partie 1 s'adresse au client final ; la partie 2 à l'ingénieur support AIMsight.
|
||||
|
||||
---
|
||||
|
||||
# Partie 1 : lecture rapide
|
||||
|
||||
## 1. Ce que surveille le diagnostic
|
||||
|
||||
Une station AIMsight fonctionne sur batterie. La batterie est rechargée par un panneau solaire ou par le secteur.
|
||||
|
||||
Chaque jour, pour chaque station, le diagnostic répond à une question : **l'énergie reçue ce jour-là couvre-t-elle la consommation de la station ?**
|
||||
|
||||
La réponse est une **couleur par jour**, accompagnée d'une **flèche** qui compare le jour à la veille.
|
||||
|
||||
Une station peut avoir une batterie encore bien chargée et déjà être en difficulté : si elle ne reçoit plus d'énergie, elle s'arrêtera tôt ou tard. Le diagnostic regarde donc si l'énergie arrive, pas seulement si la batterie est pleine.
|
||||
|
||||
## 2. Les trois couleurs, et ce qu'il faut faire
|
||||
|
||||
| Couleur | Ce que ça veut dire | Que faire |
|
||||
|---|---|---|
|
||||
| 🟢 **Vert** | La station a reçu assez d'énergie ce jour-là. | Rien. |
|
||||
| 🟠 **Orange** | Incertain : la batterie s'est rechargée, mais pas complètement. Le bilan de la journée ne peut pas être établi. | Rien si l'orange est isolé : un jour nuageux suffit à le produire. **Prévenir le support si l'orange dure plus de 3 jours d'affilée.** |
|
||||
| 🔴 **Rouge** | La station ne reçoit pas assez d'énergie. Des coupures, la nuit surtout, sont possibles ou déjà en cours. | **Contacter le support.** |
|
||||
| ⚪ **Gris** | Inconnu : pas assez de mesures ce jour-là pour conclure, ou premier jour suivi (pas de veille à comparer). | Regarder les jours voisins. |
|
||||
|
||||
- **Pourquoi 3 jours** : sur la station de référence (VERMONT), en période saine, la plus longue série de jours sans recharge complète est de 3 jours (du 04 au 06/05/2026). Ce seuil reste à confirmer sur d'autres stations.
|
||||
- **La couleur du jour peut encore changer** tant que la journée n'est pas terminée (minuit UTC).
|
||||
|
||||
## 3. La flèche : comparaison avec la veille
|
||||
|
||||
| Flèche | Ce que ça veut dire |
|
||||
|---|---|
|
||||
| ↗ | mieux que la veille |
|
||||
| → | comme la veille |
|
||||
| ↘ | moins bien que la veille |
|
||||
|
||||
La flèche nuance la couleur :
|
||||
- **un orange ↘** inquiète plus qu'un orange → ;
|
||||
- **un vert ↗** après un orange : la station a récupéré.
|
||||
|
||||
Une seule flèche ↘ n'est pas une alerte : un jour nuageux en donne une, suivie d'un ↗ le lendemain. **C'est la répétition qui compte.**
|
||||
|
||||
## 4. Trois exemples réels (station VERMONT, solaire, 2026)
|
||||
|
||||
### Une période saine
|
||||
|
||||
Du 05 au 14/08 : 🟢 → tous les jours. La batterie se recharge complètement chaque jour et se retrouve au même niveau chaque matin.
|
||||
|
||||
### Des oranges isolés : rien à faire
|
||||
|
||||
| Jour | 03/08 | 04/08 | … | 15/08 | 16/08 | 17/08 | 18/08 | 19/08 |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| Couleur | 🟠 ↘ | 🟢 ↗ | | 🟠 ↘ | 🟢 ↗ | 🟢 → | 🟠 ↘ | 🟢 ↗ |
|
||||
|
||||
Chaque orange est un jour nuageux, et la station revient au vert dès le lendemain.
|
||||
|
||||
### Une station qui s'épuise : prévenir le support, puis contacter le support
|
||||
|
||||
| Période | Couleurs | Ce qui se passe |
|
||||
|---|---|---|
|
||||
| 29/08 – 01/09 | 🟠 🟠 🟠 🟠 | **4 jours d'orange d'affilée** : c'est plus que tout ce qu'on voit en période saine. **Le 01/09, il faut prévenir le support**, 26 jours avant la première coupure. |
|
||||
| 02/09 – 25/09 | surtout 🟠 ; 🟢 seulement les 02–05, 07, 11, 18 et 19/09 | Les recharges complètes deviennent rares. Deux séries de 6 jours d'orange (12–17/09 et 20–25/09). |
|
||||
| 26/09 | 🔴 ↘ | La batterie est descendue sous ~30 % de charge. **Il faut contacter le support.** |
|
||||
| 27/09, 01:00 UTC | 🔴 | Première coupure de la station, la nuit. |
|
||||
| jusqu'au 09/10 | 🔴 | Coupures nocturnes répétées. |
|
||||
|
||||
Diagnostic de l'expert : interruptions nocturnes dues à un déficit d'énergie. Remède indiqué : réactiver le mode veille profonde entre les mesures, pour réduire la consommation.
|
||||
|
||||
---
|
||||
|
||||
# Partie 2 : annexe technique (support)
|
||||
|
||||
La couleur du jour combine deux analyses de la tension batterie (`BusVoltage`, moyennes horaires) :
|
||||
- l'**état** du jour (analyse 03, `DAILY_BATTERY_STATE`) ;
|
||||
- la **tendance** face à la veille (analyse 04, `DAILY_BATTERY_TREND`).
|
||||
|
||||
Le détail de chaque analyse (calcul exact, sources, résultats, options écartées) est dans sa fiche : `docs/analyses/analyse_03.md` et `docs/analyses/analyse_04.md`.
|
||||
|
||||
Une couleur reste une preuve imparfaite : elle conclut au plus `consistent with`. Elle signale une journée à regarder, elle ne remplace pas le diagnostic.
|
||||
|
||||
## 5. L'état du jour (analyse 03)
|
||||
|
||||
Chaque journée UTC (00:00 à 23:00) est lue avec deux seuils du matériel, valables dès le premier jour d'installation, sans historique (D-018) :
|
||||
- **14,0 V** : fin de charge du chargeur. Une heure à 14,0 V ou plus signale une recharge complète.
|
||||
- **12,8 V** : coude de la batterie LiFePO4 (~30 % de charge). Au-dessus, la tension de nuit reste presque plate (le « plateau ») ; en dessous, elle chute de plus en plus vite.
|
||||
|
||||
L'état se lit dans cet ordre ; la première condition vraie l'emporte :
|
||||
|
||||
| Ordre | Condition | État | Lecture |
|
||||
|---|---|---|---|
|
||||
| 1 | au moins une heure ≥ 14,0 V | ● `FULL_CHARGE` | l'apport a rempli la batterie |
|
||||
| 2 | une heure < 12,8 V | ▼ `BELOW_PLATEAU` | décharge visible : la batterie a quitté le plateau |
|
||||
| 3 | montée du jour < 0,05 V | ✕ `NO_CHARGE` | aucun apport visible de la journée |
|
||||
| 4 | sinon | ◆ `PARTIAL_CHARGE` | **incertain** : charge sans recharge complète ; sur le plateau, on ne sait pas si la batterie a gagné ou perdu |
|
||||
|
||||
- **Montée du jour** : la plus grande hausse de tension depuis un minimum antérieur du même jour.
|
||||
- **Fin de nuit** : le minimum dont part cette montée, juste avant la charge du jour. C'est le meilleur repère du niveau de la batterie.
|
||||
- **Sources des seuils** :
|
||||
- 14,0 V : sur VERMONT, le maximum du jour est soit sous 13,55 V, soit entre 14,02 et 14,33 V (170 jours sur 173) ;
|
||||
- 12,8 V : table OCV du collecteur ;
|
||||
- 0,05 V : au-dessus du bruit d'une heure sur le plateau, sous la plus faible vraie recharge observée (+0,079 V un jour nuageux).
|
||||
|
||||
## 6. La tendance (analyse 04)
|
||||
|
||||
On compare le jour J à la veille J−1 :
|
||||
1. **Si l'état a changé, l'état décide.** Rang : `FULL_CHARGE` > `PARTIAL_CHARGE` > `NO_CHARGE` > `BELOW_PLATEAU`. Un état plus haut donne `BETTER` (↗), un état plus bas donne `WORSE` (↘).
|
||||
2. **Sinon, la fin de nuit décide** : écart = fin de nuit de J − fin de nuit de J−1.
|
||||
- écart > +0,05 V : `BETTER` (↗) ;
|
||||
- écart < −0,05 V : `WORSE` (↘) ;
|
||||
- sinon : `STABLE` (→).
|
||||
|
||||
**Source de la zone morte de ±0,05 V** : sur VERMONT, entre deux jours `FULL_CHARGE` consécutifs, l'écart va de −0,026 à +0,043 V (5e et 95e centiles). Les jours de déficit de septembre baissent de −0,07 à −0,12 V.
|
||||
|
||||
**À savoir en lisant les barres** : la fin de nuit de J est celle du matin de J. Son écart résume donc la recharge de J−1, alors que l'état est celui de J. Quand l'état change, la barre peut le contredire. Exemple : le 12/04, l'état passe de `PARTIAL_CHARGE` à `FULL_CHARGE` (↗), avec une barre à −0,187 V, héritée du 11/04 nuageux.
|
||||
|
||||
## 7. La matrice : de l'état et de la tendance à la couleur
|
||||
|
||||
| Tendance \ État | ● `FULL_CHARGE` | ◆ `PARTIAL_CHARGE` | ✕ `NO_CHARGE` | ▼ `BELOW_PLATEAU` |
|
||||
|---|---|---|---|---|
|
||||
| ↗ `BETTER` | 🟢 | 🟢 | 🟠 | 🔴 |
|
||||
| → `STABLE` | 🟢 | 🟠 | 🔴 | 🔴 |
|
||||
| ↘ `WORSE` | 🟢 | 🟠 | 🔴 | 🔴 |
|
||||
|
||||
Lecture de chaque case, avec le nombre de jours observés sur VERMONT (184 jours, du 09/04 au 09/10/2026) :
|
||||
|
||||
| État | Tendance | Couleur | Situation | Lecture | VERMONT |
|
||||
|---|---|---|---|---|---|
|
||||
| `FULL_CHARGE` | ↗ | 🟢 | retour à la recharge complète, ou fin de nuit plus haute | récupération après un jour faible | 17 j |
|
||||
| `FULL_CHARGE` | → | 🟢 | recharge complète, fin de nuit à ±0,05 V | cas sain : `consistent with` un régime soutenable | 120 j |
|
||||
| `FULL_CHARGE` | ↘ | 🟢 | recharge complète, fin de nuit plus basse | rare ; à vérifier | 1 j (24/07 : artefact de trou, le 23/07 n'a que 16 h mesurées) |
|
||||
| `PARTIAL_CHARGE` | ↗ | 🟢 | reprise depuis `NO_CHARGE` ou `BELOW_PLATEAU`, ou fin de nuit plus haute | l'apport reprend | 0 j |
|
||||
| `PARTIAL_CHARGE` | → | 🟠 | charge partielle, fin de nuit à ±0,05 V | incertain ; une dérive lente (< 0,05 V/jour) reste « stable » | 10 j, dont 22–24/09 alors que la station s'épuise |
|
||||
| `PARTIAL_CHARGE` | ↘ | 🟠 | après une recharge complète, ou fin de nuit plus basse | jour nuageux ou début de déficit : à surveiller s'il se répète | 21 j |
|
||||
| `NO_CHARGE` | ↗ | 🟠 | depuis `BELOW_PLATEAU`, ou fin de nuit plus haute sans apport | peu plausible physiquement : vérifier les données (trou, redémarrage) | 0 j |
|
||||
| `NO_CHARGE` | → | 🔴 | 2e jour sans apport ou plus, batterie restée sur le plateau | `consistent with` une alimentation absente, même batterie pleine (D-004) | 0 j |
|
||||
| `NO_CHARGE` | ↘ | 🔴 | perte de l'apport, ou fin de nuit qui baisse sans apport | `consistent with` une perte d'alimentation | 0 j |
|
||||
| `BELOW_PLATEAU` | ↗ | 🔴 | fin de nuit plus haute, toujours sous le plateau | **souvent un faux « mieux »** : un jour de coupure, la fin de nuit est la tension de redémarrage | 3 j (01/10, 03/10, 08/10), tous faux |
|
||||
| `BELOW_PLATEAU` | → | 🔴 | sous le plateau, fin de nuit à ±0,05 V | `consistent with` un régime non soutenable qui dure | 7 j |
|
||||
| `BELOW_PLATEAU` | ↘ | 🔴 | entrée sous le plateau, ou fin de nuit qui baisse encore | `consistent with` un régime non soutenable ; coupures nocturnes possibles | 4 j (26/09 entrée, 27/09, 02/10, 09/10) |
|
||||
|
||||
- **Total VERMONT** : 138 jours 🟢, 31 🟠, 14 🔴 et 1 jour gris (09/04, premier jour : sans veille, pas de tendance).
|
||||
- **Jour gris** : l'état ou la tendance est inconnu (moins de 20 h mesurées sans recharge complète ni passage sous le plateau, ou pas de veille). La matrice ne traite pas encore ces cas (D-020, D-021).
|
||||
- **Pourquoi `NO_CHARGE` → est rouge et non orange** : en orange, une coupure d'alimentation passerait du rouge (1er jour, ↘) à l'orange (2e jour, →) alors qu'elle continue. Une batterie assez grande pour rester sur le plateau ne change rien : sans apport, la station tombera (D-004).
|
||||
|
||||
## 8. Lire les pages HTML
|
||||
|
||||
Commande : `python3 src/analyse_03.py`. Elle écrit deux pages dans `out/` et les ouvre dans le navigateur.
|
||||
|
||||
- `<STATION>_daily.html` : le graphique destiné au site de monitoring (D-021), soit les panneaux `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND` décrits ci-dessous, sur le même axe du temps. Sa figure Plotly est aussi écrite en JSON (`<STATION>_daily.json`), pour `Plotly.newPlot`.
|
||||
- `<STATION>_energy.html` : la page de toutes les analyses, avec ces deux panneaux, et une courbe par mesure dessous.
|
||||
|
||||
**Attention aux couleurs** : celles des panneaux ne sont pas celles de la matrice. Elles distinguent les états et les tendances ; elles ne disent pas le niveau de préoccupation. Par exemple, `BELOW_PLATEAU` y est en bleu.
|
||||
|
||||
- **Les panneaux 01 et 02** (moyennes sur 7 jours), en haut de la page, ne font pas partie de ce diagnostic : les ignorer.
|
||||
- **Panneau `DAILY_BATTERY_STATE`** (analyse 03), un point par jour, placé à midi UTC :
|
||||
- courbe foncée : le maximum du jour ; courbe claire : la fin de nuit ;
|
||||
- tirets : les seuils de 14,0 V (vert) et de 12,8 V (bleu) ;
|
||||
- marqueurs sur le maximum, selon l'état : ● vert `FULL_CHARGE`, ◆ jaune orangé `PARTIAL_CHARGE`, ▼ bleu `BELOW_PLATEAU`, ✕ violet `NO_CHARGE`.
|
||||
- **Panneau `DAILY_BATTERY_TREND`** (analyse 04), une barre par jour :
|
||||
- hauteur : l'écart de fin de nuit face à la veille, en V ;
|
||||
- couleur : bleu ↗, gris →, rouge ↘ ;
|
||||
- tirets : la zone morte de ±0,05 V ;
|
||||
- quand l'état décide, la couleur suit la tendance, même si la barre est petite ou de signe contraire (voir § 6).
|
||||
- **Survol** : chaque point et chaque barre affichent les faits calculés du jour (état, tensions, écarts, ce qui a décidé la tendance).
|
||||
- **Dessous** : une courbe par mesure. Sur `BusVoltage`, les bandes grises marquent les heures sans mesure, et les bandes colorées les zones de tension (décharge, en charge, pleine charge).
|
||||
- **Zoom** : dans le temps seulement, au rectangle ou à la molette ; double-clic pour revenir à la vue complète.
|
||||
|
||||
## 9. Limites à connaître
|
||||
|
||||
1. **Jour UTC** : la journée est coupée à minuit UTC. Pour une station éloignée en longitude, la nuit serait coupée en deux, et la fin de nuit faussée.
|
||||
2. **Seuil de 14,0 V** : il suppose le même chargeur sur toutes les stations, ce qui n'est pas confirmé. Une recharge complète de moins d'une heure peut aussi être lue `PARTIAL_CHARGE` (08/09 : maximum à 13,96 V).
|
||||
3. **Jours de coupure** : faux ↗ sous le plateau (voir § 7). La couleur reste rouge.
|
||||
4. **Dérive lente** : une baisse de moins de 0,05 V par jour est lue → (VERMONT, 22–24/09, alors que la station s'épuise). La série d'oranges, elle, la signale.
|
||||
5. **Froid** : aucune donnée d'hiver. Sous 0 °C, la charge d'une batterie LiFePO4 est en général bloquée : des jours orange ou rouges sont possibles même au soleil.
|
||||
Reference in new issue
Block a user