Diagnostic opérationnel

Dépannage & FAQ

Cette page aide à isoler les pannes réelles : installation, interface web, statut asynchrone, base SQLite, matériaux, solveur Sesame, validité scientifique et optimisation.

Méthode. Ne partez pas du message affiché dans le navigateur uniquement. Relevez toujours le type de simulation, l'identifiant simulation_id, le statut final, le traceback terminal et les champs de validation scientifique.

Diagnostic rapide en 5 minutes

Question	Commande ou route	Ce que cela distingue
L'application parse-t-elle ?	`venv/bin/python -m py_compile web/app.py router.py`	Erreur Python avant même Flask.
Le serveur répond-il ?	`GET /api/health`	Serveur absent vs backend vivant.
La configuration est-elle créée ?	`POST /api/generate-json`	Erreur formulaire/validation vs erreur solveur.
Le run est-il lancé ?	`POST /api/run-simulation/<id>/async`	Erreur d'exécution vs config non persistée.
Quel est le statut réel ?	`GET /api/results/<id>/status`	`running`, `completed`, `failed`, `invalid` ou `partial`.

Arbre de triage

Si /api/health ne répond pas, traitez d'abord le démarrage Flask ou l'environnement Python.
Si /api/generate-json échoue, le problème est dans les entrées, les matériaux, la géométrie ou la base SQLite.
Si /api/generate-json réussit mais le run échoue, regardez router.py, Sesame, le maillage et les limites physiques.
Si le run termine mais la page affiche invalid ou partial, le problème est scientifique, pas seulement informatique.
Si l'interface semble bloquée, séparez le polling normal, le timeout navigateur, le statut SQLite et le vrai traceback solveur.

Démarrage Flask et imports

Symptôme	Cause probable	Action
`python -m web.app` s'arrête immédiatement	Erreur de syntaxe ou import cassé dans un module partagé.	Lancer `venv/bin/python -m py_compile web/app.py router.py simulations/utils.py`, puis corriger la première erreur remontée.
Le navigateur ne charge rien	Serveur non lancé, mauvais port, ou processus arrêté.	Vérifier le terminal Flask et ouvrir `http://localhost:5000/api/health`.
La page charge mais les API renvoient HTML 500	Exception côté serveur masquée par l'interface.	Lire le traceback terminal et reproduire avec la route API concernée.

Interface web, polling et longues simulations

Important. Des lignes répétées GET /api/results/<id>/status 200 sont normales : c'est le polling de progression. Le signal utile est le statut final, le message d'erreur ou un traceback après ces lignes.

Symptôme	Interprétation	Contrôle concret
La barre reste longtemps au même pourcentage	Calcul encore vivant, progression trop grossière, ou vrai blocage solveur.	Comparer `/api/results/<id>/status`, terminal Flask, statut SQLite et logs Redis si utilisé.
Le run semble s'arrêter après environ 30 minutes	Timeout navigateur ou interruption backend selon les logs.	Vérifier si le backend continue à écrire des statuts après l'arrêt côté navigateur.
Historique et page résultats ne disent pas la même chose	Statut terminal non persisté ou statut d'affichage dérivé de la validité scientifique.	Lire `status`, `display_status` et `error` dans `/api/results/<id>/status`.
Erreur réseau après clic sur Simuler	Souvent un 400/500 backend présenté comme erreur navigateur.	Regarder la réponse JSON, le terminal Flask et la route exacte appelée.

Base SQLite et persistance

Message	Cause probable	Correction
`attempt to write a readonly database`	Variable `SPARC_DB_PATH` ou `SESAME_WEB_DB` pointant vers une ancienne base non inscriptible.	Pointer la base vers `data/sparc.db` ou une base située dans le checkout courant, puis redémarrer Flask.
Simulation créée mais absente de l'historique	Écriture SQLite échouée ou deux chemins DB différents entre web et worker.	Comparer la valeur DB utilisée par web et worker, puis relancer une création via `/api/generate-json`.
Statut `running` persistant après échec terminal	État final non persisté dans SQLite.	Lire `error` dans la base et vérifier le chemin worker/thread local.

Matériaux et fournisseurs externes

Symptôme	Cause probable	Action
`Matériau inconnu`	Nom absent de la base locale ou alias non reconnu.	Vérifier `/api/materials/list`, puis utiliser le symbole attendu, par exemple `Si`.
Materials Project ne renvoie rien	Clé absente, réseau indisponible ou fournisseur dégradé.	Contrôler `MATERIALS_PROJECT_API_KEY` et l'état fournisseur affiché dans la page Matériaux.
OPTIMADE est `unreachable`	Réseau bloqué, endpoint externe indisponible ou timeout.	Ne pas conclure que la recherche locale est cassée ; utiliser les résultats locaux et noter l'état dégradé.
Des doublons apparaissent dans les résultats matériaux	Comportement volontaire : sources différentes, même formule.	Comparer la source, les propriétés et les métadonnées plutôt que dédupliquer automatiquement.

Convergence Sesame et erreurs numériques

Symptôme	Cause fréquente	Correction recommandée
`Maximum iterations reached`	Dopage trop abrupt, tension trop agressive, maillage insuffisant ou contact difficile.	Réduire le pas de tension, commencer en 1D, augmenter `geometry.nx` progressivement et simplifier les contacts.
Courant non physique ou Jsc énorme	Unités, flux photonique, épaisseur, génération ou géométrie 2D incohérents.	Vérifier cm vs m, `photon_flux`, `absorption_coefficient`, `lx`/`ly` et les warnings de validation.
Calcul 2D trop lent	Domaine ou maillage trop grand.	Valider le cas en 1D, puis fixer un `ny` modéré et augmenter le maillage par étapes.
Hétérojonction très instable	Offsets de bandes élevés, interface non passivée ou limite tunnel non modélisée.	Lire les limitations de Hétérojonction et réduire l'agressivité du cas test.

Résultat terminé mais scientifiquement invalide

Un statut technique completed signifie que l'exécution a produit un objet résultat. La page peut cependant afficher invalid ou partial si les diagnostics scientifiques bloquent l'interprétation.

Champ	Ce qu'il faut vérifier
`iv_metrics_valid`	Si `false`, ne pas publier `Jsc`, `Voc`, `FF` ou `PCE` comme métriques PV valides.
`equilibrium_only`	Le résultat peut décrire un état d'équilibre, mais pas une performance photovoltaïque complète.
`physics_validity.pv_metrics_applicable`	Indique si les métriques PV ont un sens pour ce type de résultat.
`scientific_readiness`	Classe le niveau d'usage : exploratoire, avec réserves, candidat qualifié ou invalide.
`diagnostic_report`	Donne les raisons concrètes : fallback, courbe IV inutilisable, violation de bornes, manque de référence.

Sweeps, optimisation et tâches longues

Cas	Diagnostic	Action
`parametric_sweep` très long	Nombre de points, base 2D involontaire ou solveur lent.	Commencer avec 3 points, garder `parametric.dimension = "1d"`, puis augmenter progressivement.
Sweep bloqué vers 85%	Peut être un souci de publication de progression ou un dernier point très lent.	Lire le statut final et les logs avant de relancer. Un polling 200 seul n'est pas une preuve d'échec.
Optimisation indique `stalled`	Aucun changement de progression depuis le délai de surveillance.	Consulter `/api/optimize/<opt_id>/status`, réduire `n_trials` et rejouer le meilleur cas en simulation simple.
Aucun trial réussi	Bornes de paramètres non physiques ou configuration de base invalide.	Exécuter d'abord la configuration de base hors optimisation.

LLM, chat et coûts

Symptôme	Cause probable	Correction
`sparc_agent module not installed`	Agent optionnel absent ou import impossible.	Installer l'extra agent ou utiliser SPARC sans assistant LLM.
Clé API refusée	Provider, modèle ou clé incorrects.	Utiliser `/api/llm/test-key` depuis la configuration LLM.
Stream timeout	Réponse modèle trop longue ou provider lent.	Réduire le contexte, augmenter prudemment le timeout ou changer de modèle.

Campagne de validation

Si la question est “est-ce scientifiquement valide ?”, ne vous arrêtez pas au statut web. Lancez ou relisez la campagne de validation.

Validation reproductible

venv/bin/python3 validation_campaign/run_validation_campaign.py

Décision	Lecture
`PASS`	Les critères déclarés passent pour la campagne courante.
`PASS_WITH_RESERVATIONS`	Résultat exploitable avec réserves ; ne pas présenter comme validation officielle sans référence externe.
`FAIL`	Corriger le modèle, les bornes, les références ou l'exécution avant usage.

Informations à fournir pour un diagnostic

simulation_id ou opt_id.
Type de simulation et configuration JSON minimale.
Réponse de /api/results/<id>/status ou /api/optimize/<id>/status.
Traceback terminal complet, pas seulement le message navigateur.
Champs iv_metrics_valid, scientific_readiness, physical_validation et diagnostic_report si disponibles.