Validation scientifique

Benchmarking & validation

Cette page décrit comment SPARC est comparé à des invariants analytiques, des enveloppes publiées et des références externes SCAPS-1D, PC1D ou expérimentales. Le but est de rendre les résultats auditables, pas de promettre une certification automatique.

Point important. Un benchmark réussi signifie que le code respecte les critères de la campagne courante. Pour un usage officiel, il faut encore des références externes appariées au dispositif étudié : export SCAPS-1D, PC1D ou mesure expérimentale comparable.

Objectif du benchmarking

Le benchmarking répond à trois questions différentes, qui ne doivent pas être mélangées :

Niveau	Question	Ce que cela prouve	Ce que cela ne prouve pas
Invariants analytiques	Les formules et constantes de référence sont-elles cohérentes ?	Limite Shockley-Queisser, Green FF, bornes NREL, cohérence thermodynamique.	La convergence du solveur Sesame sur une géométrie donnée.
Cas TCAD internes	Le backend Sesame termine-t-il des cas physiques contrôlés ?	Le flux routeur → solveur → résultats → validation fonctionne sans fallback interdit.	La correspondance avec un outil externe indépendant.
Références externes	SPARC reproduit-il une IV ou un jeu de métriques externe ?	Comparaison quantitative avec SCAPS-1D, PC1D ou données expérimentales importées.	La validité universelle sur d'autres matériaux ou géométries.

Campagne officielle du dépôt

Le dossier validation_campaign/ contient la campagne de validation reproductible. Elle est pilotée par validation_campaign/manifest.json et exécutée par validation_campaign/run_validation_campaign.py.

Lancer la campagne

venv/bin/python3 validation_campaign/run_validation_campaign.py

Les sorties sont créées dans validation_campaign/runs/<timestamp>/ :

campaign_report.json : rapport complet exploitable par script.
campaign_report.md : synthèse lisible avec décisions, métriques, réserves et échecs.
simulations/ : dossiers de résultats des cas TCAD exécutés pendant la campagne.

Politique d'acceptation

La campagne actuelle applique les règles suivantes :

Règle	Effet
`tests_must_pass`	Les suites pytest de benchmark doivent passer.
`simulations_must_complete`	Les cas TCAD déclarés doivent produire des résultats.
`no_analytical_fallback`	Un fallback analytique bloque la qualification officielle du cas.
`no_physical_validation_errors`	Les erreurs de validation physique sont bloquantes.
`warnings_allowed_with_reservations`	Les avertissements peuvent mener à `PASS_WITH_RESERVATIONS`.
`external_references_required_for_official`	L'usage officiel exige des références externes appariées.

Suites de tests analytiques

La suite analytical_benchmarks regroupe les tests de cohérence scientifique qui ne dépendent pas nécessairement d'une simulation complète :

tests/test_benchmark_validation.py : bornes Shockley-Queisser, enveloppes NREL et invariants de performance.
tests/test_nrel_reference_validation.py : cohérence avec des familles de records et limites publiées.
tests/test_scaps_pc1d_benchmark.py : invariants analytiques inspirés des comparaisons SCAPS/PC1D.
tests/test_physics_models.py : modèles de mobilité, Varshni, recombinaisons et grandeurs physiques de base.
tests/test_input_validation.py : garde-fous d'entrée avant exécution.

Interprétation. Ces tests verrouillent les calculs et les bornes physiques. Ils ne remplacent pas une simulation TCAD complète ni une comparaison expérimentale.

Cas TCAD actuellement déclarés

Cas	Configuration	Critères principaux	Références
`si_homojunction_1sun_tcad`	`validation_campaign/configs/si_homojunction_1sun.json`	Jsc 5-50 mA/cm², Voc 0.35-0.80 V, FF 0.30-0.90, PCE 1-30%.	SCAPS, PC1D et mesure expérimentale possibles; enveloppes SQ et NREL déclarées.
`ml_si_si_1sun_tcad`	`validation_campaign/configs/ml_si_si_1sun.json`	Jsc 1-50 mA/cm², Voc 0.20-0.90 V, FF 0.20-0.95, PCE 0.1-30%.	Enveloppe Shockley-Queisser Si/Si; smoke test multicouche Sesame.

Comparaison SCAPS-1D, PC1D ou expérimentale

Les références externes sont attendues sous forme de fichiers CSV dans validation_campaign/external_references/. Le modèle de fichier se trouve dans validation_campaign/external_references/templates/iv_reference_template.csv.

Type	Dossier	Usage
SCAPS-1D	`external_references/scaps/`	Comparer une courbe IV issue d'un outil TCAD indépendant.
PC1D	`external_references/pc1d/`	Comparer des cas silicium ou invariants thermodynamiques.
Expérimental	`external_references/experimental/`	Comparer à une mesure réelle après harmonisation unités/surface/spectre.

Les critères externes déclarés pour les IV incluent actuellement :

Jsc : écart relatif typique ≤ 5%.
Voc : écart absolu typique ≤ 20 mV.
FF : écart absolu typique ≤ 0.03.
PCE : écart absolu typique ≤ 1 point de pourcentage.
IV NRMSE : erreur normalisée typique ≤ 5%.

Décisions produites

Décision	Signification	Action recommandée
`PASS`	Tests et cas déclarés passent sans réserve bloquante.	Archiver le rapport et poursuivre avec références externes si usage officiel.
`PASS_WITH_RESERVATIONS`	Aucun échec bloquant, mais au moins une réserve scientifique subsiste.	Documenter la réserve et éviter les claims de certification.
`FAIL`	Au moins une suite ou simulation viole un critère.	Corriger le modèle, la configuration ou les bornes avant toute publication.

Relation avec `scientific_readiness`

Le benchmarking de campagne et scientific_readiness n'ont pas exactement le même rôle :

scientific_readiness qualifie un résultat individuel au moment de l'exécution : métriques PV applicables, erreurs bloquantes, référence externe présente ou non.
La campagne de benchmarking qualifie un état du dépôt sur un ensemble de tests et de cas reproductibles.
Une simulation individuelle peut être affichée dans l'interface tout en étant research_only ou invalid.
Une campagne peut passer avec réserves si les sorties sont cohérentes mais manquent de référence externe officielle.

Ajouter un nouveau cas de benchmark

Créer une configuration JSON minimale dans validation_campaign/configs/.
Ajouter le cas dans validation_campaign/manifest.json avec des bornes numériques explicites.
Déclarer les références externes attendues si le cas doit soutenir un usage officiel.
Exécuter venv/bin/python3 validation_campaign/run_validation_campaign.py.
Archiver campaign_report.json, campaign_report.md et les résultats de simulation.

Règle de publication. Ne présentez jamais une performance comme validée officiellement si le rapport indique une référence externe manquante, un fallback analytique, une métrique PV invalide ou une décision PASS_WITH_RESERVATIONS/FAIL.