Mise en pratique

Tutoriels et quickstarts

Cette section décrit les parcours minimaux pour lancer SPARC, créer une configuration, exécuter une simulation, lire les résultats et vérifier leur validité scientifique.

Quickstart 0 : vérifier l'environnement

Ce premier contrôle sert à distinguer un problème d'installation d'un problème physique ou numérique.

Quickstart 1 : lancer une homojonction depuis l'interface web

Ce parcours utilise la chaîne réelle /form → /api/generate-json → /api/run-simulation/<id>/async → /api/results/<id>/status.

1. Ouvrir http://localhost:5000/form.
2. Choisir le type homojunction.
3. Sélectionner Si comme matériau actif.
4. Renseigner une région N fortement dopée et une région P plus faiblement dopée, par exemple 1e17 cm-3 et 1e15 cm-3.
5. Garder une géométrie 1D pour le premier essai : thickness_n et thickness_p, sans ly.
6. Activer l'illumination et conserver le flux AM1.5G proposé par l'interface.
7. Générer la configuration JSON, puis lancer la simulation asynchrone.
8. Suivre la progression jusqu'au statut final, puis ouvrir la page de résultats.

Tutoriel 2 : exécuter une configuration JSON en CLI

La CLI est le chemin le plus simple pour reproduire une simulation hors navigateur et archiver les entrées exactes.

venv/bin/python main.py --example homojunction

Enregistrez une configuration JSON dans configs/, puis exécutez-la :

venv/bin/python main.py configs/silicon_homo.json --output outputs

La sortie principale est un dossier de résultats dans outputs/, avec la configuration sauvegardée et un fichier *_summary.json. Ce résumé est le bon point de départ pour relire les métriques, diagnostics et flags de validité.

Tutoriel 2b : explorer et optimiser en CLI Interactive

Le CLI interactif est l'interface console complète de SPARC, conçue pour les terminaux. Elle permet de lancer des simulations, de consulter la base de matériaux, d'exécuter des optimisations bayésiennes et de visualiser des courbes J-V en caractères ASCII directement dans le terminal.

python -m cli_interactif

Fonctionnalités et navigation rapide :

• Raccourcis Clés : Appuyez sur la lettre correspondante pour ouvrir directement un écran :
  • n : Lancer l'assistant de configuration pas à pas pour configurer et démarrer une nouvelle simulation en arrière-plan.
  • h : Consulter l'historique complet des simulations enregistrées dans SQLite.
  • r : Visualiser les résultats (courbe J-V en caractères ASCII et tracés PNG).
  • m : Parcourir la bibliothèque des matériaux locaux et externes.
  • o : Configurer et exécuter des études d'optimisation bayésienne (Optuna / BoTorch).
  • t : Basculer entre le thème clair et le thème sombre de la console.
• Exécution en arrière-plan : Les simulations lancées depuis le CLI interactif s'exécutent en arrière-plan. Vous pouvez surveiller leur progression (touche p) et continuer à naviguer dans les menus sans bloquer votre terminal.

Tutoriel 3 : lancer une simulation directement par API

Pour une intégration externe, utilisez /api/simulate si vous voulez créer et exécuter en une requête synchrone. Pour des calculs longs, préférez le couple /api/generate-json puis /api/run-simulation/<id>/async.

curl -X POST http://localhost:5000/api/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "simulation_name": "api_si_homojunction",
    "simulation_type": "homojunction",
    "materials": { "active": "Si" },
    "geometry": { "thickness_n": 5e-5, "thickness_p": 2e-4, "nx": 120 },
    "doping": { "n_region": 1e17, "p_region": 1e15 },
    "voltages": { "start": 0.0, "stop": 0.75, "points": 60 },
    "illumination": { "enabled": true, "photon_flux": 2.5e17, "absorption_coefficient": 1e4 },
    "outputs": { "plots": ["iv_curve", "band_diagram"], "format": "both" }
  }'

Pour le mode asynchrone, récupérez d'abord simulation_id depuis /api/generate-json, lancez /api/run-simulation/<id>/async, puis interrogez /api/results/<id>/status jusqu'à completed ou failed.

Tutoriel 4 : interpréter correctement les résultats

SPARC expose plusieurs niveaux de diagnostic. Il faut les lire dans cet ordre pour éviter de commenter une métrique invalide.

1. Vérifier le statut d'exécution : completed, failed, running ou cancelled.
2. Lire les erreurs de validation d'entrée : matériau inconnu, géométrie impossible, dopage hors bornes, maille excessive.
3. Lire physical_validation et quality_validation pour savoir si le résultat est physiquement défendable.
4. Lire iv_metrics_valid avant d'utiliser Jsc, Voc, FF ou PCE.
5. Lire scientific_readiness pour distinguer usage exploratoire, résultat avec réserves et résultat comparable à une référence.
6. Comparer aux références de Benchmarking si le résultat doit soutenir une conclusion officielle.

Tutoriel 5 : balayage paramétrique propre

Un balayage paramétrique sert à isoler l'effet d'un seul paramètre. Commencez en 1D, avec peu de points, puis augmentez la résolution.

Si la barre de progression semble bloquée, vérifiez le statut final et les logs avant de conclure à un blocage. Les sweeps publient leur progression point par point lorsque le chemin asynchrone est utilisé.

Tutoriel 6 : optimisation avec Optuna ou BoTorch

L'optimisation automatise l'exploration d'un espace de paramètres. Elle ne remplace pas la validation physique : elle peut trouver rapidement une zone intéressante, mais les meilleurs essais doivent ensuite être rejoués et interprétés comme simulations normales.

1. Ouvrir http://localhost:5000/optimize.
2. Choisir un type de base, par exemple homojunction.
3. Définir l'objectif : efficiency, ou une combinaison si l'interface multi-objectifs est utilisée.
4. Ajouter des paramètres bornés, par exemple geometry.thickness_p ou doping.n_region.
5. Utiliser optuna pour une exploration robuste, ou botorch pour peu de paramètres avec simulations coûteuses.
6. Lancer un petit nombre d'essais, vérifier les échecs, puis augmenter n_trials.
7. Ouvrir les résultats, la heatmap, la sensibilité et le rapport PDF si nécessaire.

Tutoriel 7 : utiliser la page Validation et la campagne Benchmarking

La page /validation donne une vue utilisateur des contrôles, tandis que validation_campaign/ sert aux campagnes reproductibles.

venv/bin/python3 validation_campaign/run_validation_campaign.py

Relisez ensuite validation_campaign/runs/<timestamp>/campaign_report.md. Une décision PASS_WITH_RESERVATIONS n'est pas un échec logiciel, mais elle interdit de présenter la campagne comme validation officielle sans préciser les réserves.

Erreurs fréquentes et diagnostic rapide