Metadata-Version: 2.4
Name: sparc-pv
Version: 2.0.3
Summary: Semiconductor Physics Analysis and Research Code — open-source semiconductor and photovoltaic TCAD simulation code
Author-email: SPARC Contributors <sparc-pv@proton.me>
License: MIT License
        
        Copyright (c) 2024-2026 SPARC Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        ---
        
        Third-party dependencies and their licenses:
        
        - Sesame (NIST)     — BSD-3-Clause
        - NumPy             — BSD-3-Clause
        - SciPy             — BSD-3-Clause
        - Optuna            — MIT
        - scikit-learn      — BSD-3-Clause
        - BoTorch            — MIT
        - PyTorch           — BSD-3-Clause
        - SALib             — MIT
        - Flask             — BSD-3-Clause
        - Celery            — BSD-3-Clause
        - pymatgen          — MIT
        - Matplotlib        — PSF/BSD
        - ReportLab         — BSD
        
Project-URL: Homepage, https://github.com/Quantum-ARISE-Acad/SPARC
Project-URL: Repository, https://github.com/Quantum-ARISE-Acad/SPARC
Project-URL: Documentation, https://github.com/Quantum-ARISE-Acad/SPARC/tree/main/docs
Project-URL: Changelog, https://github.com/Quantum-ARISE-Acad/SPARC/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/Quantum-ARISE-Acad/SPARC/issues
Keywords: photovoltaics,solar cells,TCAD,drift-diffusion,simulation,optimisation,Sesame,semiconductor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: flask>=2.0.0
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: flasgger>=0.9.5
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: sqlalchemy>=1.4.0
Requires-Dist: rich>=13.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: requests>=2.26.0
Requires-Dist: tqdm>=4.62.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: reportlab>=4.0.0
Requires-Dist: fpdf2>=2.4.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: joblib>=1.2.0
Requires-Dist: SALib>=1.4.0
Requires-Dist: optuna>=3.0.0
Requires-Dist: celery>=5.3.0
Requires-Dist: redis>=4.6.0
Requires-Dist: uncertainties>=3.1.0
Requires-Dist: seaborn>=0.11.0
Provides-Extra: tcad
Requires-Dist: numba>=0.54.0; extra == "tcad"
Provides-Extra: botorch
Requires-Dist: torch>=2.0.0; extra == "botorch"
Requires-Dist: botorch>=0.9.0; extra == "botorch"
Provides-Extra: llm-local
Requires-Dist: ollama>=0.2.0; extra == "llm-local"
Provides-Extra: llm-cloud
Requires-Dist: anthropic>=0.40.0; extra == "llm-cloud"
Provides-Extra: materials
Requires-Dist: pymatgen>=2022.3.7; extra == "materials"
Requires-Dist: mp-api>=0.37.0; extra == "materials"
Requires-Dist: boto3>=1.26.0; extra == "materials"
Provides-Extra: all
Requires-Dist: sparc-pv[botorch,llm-local,materials,tcad]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.3.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: flake8-bugbear>=24.0.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Dynamic: license-file

# SPARC — Semiconductor Physics Analysis and Research Code v2.1.0

> **Plateforme open source d'optimisation automatique de cellules solaires par intelligence artificielle.**
> 100 % locale · 100 % gratuite · 0 clé API · Prête à l'emploi via Docker.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](#licence)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](#déploiement-docker)

> **Documentation technique (HTML & PDF) → [docs/INDEX.md](./docs/INDEX.md)**
> **Manuel utilisateur complet → [MANUEL_UTILISATEUR.md](./MANUEL_UTILISATEUR.md)**
> **Guide de déploiement → [DEPLOYMENT.md](./DEPLOYMENT.md)**
> **Guide développeur → [devreadme.md](./devreadme.md)**

---

## Table des matières

1. [Vue d'ensemble](#vue-densemble)
2. [Démarrage rapide](#démarrage-rapide)
3. [Architecture](#architecture)
4. [Mode Web (Flask)](#mode-web)
5. [Mode CLI interactif](#mode-cli-interactif)
6. [Mode IA — Optimiseur Bayésien](#mode-ia--optimiseur-bayésien)
7. [Types de simulation](#types-de-simulation)
8. [Format des configurations JSON](#format-des-configurations-json)
9. [Base de matériaux](#base-de-matériaux)
10. [Déploiement Docker](#déploiement-docker)
11. [Variables d'environnement](#variables-denvironnement)
12. [API REST](#api-rest)
13. [Tests](#tests)
14. [Résultats et sorties](#résultats-et-sorties)
15. [Licence](#licence)

---

## Vue d'ensemble

SPARC est un pipeline **simulation + optimisation IA** pour cellules solaires :

| Composant | Technologie | Rôle |
|---|---|---|
| **Simulation TCAD** | Sesame 2.x (NIST) | Physique ab initio 1D/2D |
| **Optimisation principale** | Optuna (TPE / GP / CMA-ES) | Bayesian optimization |
| **Optimisation avancée** | BoTorch + PyTorch CPU | Gaussian Process qEI |
| **Analyse de sensibilité** | SALib (Sobol) | Importance des paramètres |
| **Surrogate Model** | scikit-learn (RF/GBM/GP) | Prédiction sans simulation |
| **Interface Web** | Flask + Plotly + Bootstrap | Graphiques interactifs |
| **CLI interactif** | Rich + Questionary | Terminal riche |
| **File de tâches** | Celery + Redis | Calcul distribué |
| **Base de données** | SQLite | Persistance locale |
| **Rapports** | ReportLab + Matplotlib | PDF publication-ready |
| **Agent LLM** | Ollama / Anthropic | Assistant IA conversationnel |

**Ce que ça change :**

> Avant : *"J'ai testé 20 configurations en 3 semaines"*
>
> Après : *"J'ai testé 1 000 configurations en 2 heures, l'IA a trouvé η = 23.7 % et m'a dit exactement quel paramètre est critique"*

---

## Démarrage rapide

```bash
# 1. Cloner le dépôt
git clone https://github.com/Quantum-ARISE-Acad/SPARC.git
cd sparc

# 2. Copier et configurer les variables d'environnement
cp .env.example .env
# Éditez .env et définissez SESAME_WEB_SECRET=une-clé-secrète

# 3. Lancer tous les services (web + workers + Redis)
docker compose up

# 4. Ouvrir l'interface web
#    http://localhost:5000

# 5. CLI interactif (terminal Rich)
docker compose run --rm cli

# 6. Exécution batch (Mode IA — ligne de commande JSON)
docker compose run --rm ai python main.py configs/silicon_homo.json
```

> **Note :** La première construction Docker télécharge PyTorch CPU (~300 MB) et Sesame depuis GitHub.
> Prévoyez 5 à 10 minutes lors du premier `docker compose build`.

### Installation sans Docker (environnement local Python)

Utile pour le développement, les machines sans Docker, ou pour itérer
rapidement sans reconstruire d'image.

**Pré-requis :** Python 3.10+ (3.11 recommandé), `pip`, `git`, un compilateur
C pour quelques dépendances scientifiques (déjà présent sur macOS/Linux ;
`Build Tools for Visual Studio` sur Windows).

```bash
# 1. Cloner le dépôt
git clone https://github.com/Quantum-ARISE-Acad/SPARC.git
cd sparc

# 2. Créer un environnement virtuel (fortement recommandé)
python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# 3. Installer Sesame (dépendance non publiée sur PyPI)
pip install git+https://github.com/usnistgov/sesame.git

# 4. Installer toutes les dépendances SPARC
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

# 5. (Optionnel) Materials Project — clé API gratuite
#    https://next-gen.materialsproject.org/api
cp .env.example .env
# Éditez .env :
#   MATERIALS_PROJECT_API_KEY=votre_cle
#   SESAME_WEB_SECRET=une-cle-secrete

# 6a. Lancer l'interface web (Flask)
python -m web.app
# → http://localhost:5000

# 6b. Lancer le CLI interactif (Rich + questionary)
python -m cli_interactif

# 6c. Exécuter une simulation en batch
python main.py configs/silicon_homo.json
```

**Optimisation & LLM (optionnels) :**

```bash
# Bayesian Optimization avancée (BoTorch + PyTorch CPU)
pip install botorch torch

# Assistant IA local (Ollama — https://ollama.com)
ollama serve &
ollama pull llama3.2
# Dans .env : OLLAMA_HOST=http://localhost:11434
```

**Worker asynchrone (optionnel) pour les simulations longues :**

```bash
# Redis local (macOS : brew install redis · Linux : apt install redis-server)
redis-server &
# Dans un autre terminal
celery -A web.tasks worker --loglevel=info
# (Beat scheduler optionnel)
celery -A web.tasks beat --loglevel=info
```

**Dépannage local courant :**

| Symptôme | Cause probable | Correctif |
|----------|----------------|-----------|
| `ModuleNotFoundError: sesame` | pip install a ignoré le git URL | `pip install git+https://github.com/usnistgov/sesame.git` |
| `mp-api` s'installe mais crashe sur Windows | `h5py` incompatible | `pip install --upgrade h5py numpy` puis relancer |
| `pylatexenc` bloque l'installation | setuptools trop récent | `pip install "setuptools<72"` avant `-r requirements.txt` |
| Port 5000 occupé (macOS AirPlay) | Flask entre en conflit | `FLASK_RUN_PORT=5050 python -m web.app` |
| Base SQLite `simulations.db` vide | permission sur `web/` | `chmod u+w web/` ou lancez depuis un dossier utilisateur |
| PDF ne se génère pas | reportlab/matplotlib absents | `pip install reportlab matplotlib` |

> **Astuce :** pour un environnement 100 % reproductible, gelez vos
> dépendances après installation avec `pip freeze > requirements.lock.txt`.

---

## Architecture

```
sparc/
├── main.py                     # CLI JSON (entrée fichier config)
├── router.py                   # SesameRouter — dispatch type → module
├── output_manager.py           # Sauvegarde résultats (JSON + PNG)
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
│
├── simulations/                # Cœur scientifique (Sesame TCAD)
│   ├── homojunction.py         # p-n Si, GaAs, etc.
│   ├── heterojunction.py       # CdS/CdTe, a-Si/c-Si, etc.
│   ├── multijunction.py        # Tandem / triple jonction
│   ├── quantum_efficiency.py   # EQE spectralement résolu
│   ├── capacitance.py          # C-V, Mott-Schottky
│   ├── luminescence.py         # PL / EL
│   ├── temperature.py          # Étude Varshni T-dépendante
│   ├── parametric.py           # Sweeps paramétriques
│   ├── grain_boundary_2d.py    # Joint de grain 2D
│   ├── materials_database.py   # 10+ matériaux intégrés
│   └── visualization.py        # Graphiques publication
│
├── optimization/               # Moteur IA
│   ├── optuna_engine.py        # Bayesian opt. Optuna TPE/GP/CMA-ES
│   ├── botorch_engine.py       # GP avancé BoTorch qEI
│   ├── sensitivity.py          # Sobol + heatmap corrélations
│   └── surrogate.py            # Surrogate RF/GBM/GP
│
├── web/                        # Interface Flask
│   ├── app.py                  # Routes (simulation + optimisation)
│   ├── database.py             # SQLite (simulations + optimisations)
│   ├── reports.py              # Génération PDF
│   └── templates/
│       ├── optimize.html       # Page optimiseur IA
│       ├── optimize_results.html
│       └── ...
│
├── cli_interactif/             # CLI Rich + Questionary
│   ├── main.py                 # Menu principal (o = optimiseur)
│   └── screens/
│       ├── optimizer.py        # Écran optimiseur IA
│       └── ...
│
├── workers/                    # Celery distribué
│   ├── celery_app.py           # Configuration queues
│   └── simulation_worker.py   # Tasks simulation + optimisation
│
└── configs/                    # 39 configurations JSON d'exemple
```

---

## Mode Web

L'interface web Flask tourne sur le port **5000**.

### Lancement

```bash
docker compose up
# Ouvrir http://localhost:5000
```

### Pages disponibles

| URL | Description |
|---|---|
| `/` | Accueil |
| `/form` | Nouvelle simulation |
| `/configure/<type>` | Configuration avancée avec prévisualisation |
| `/optimize` | **Optimiseur IA** (Bayésien) |
| `/optimize/results/<id>` | Résultats — convergence, heatmap, Top 10, surrogate |
| `/api/docs/` | **Documentation Swagger / OpenAPI** (Flasgger) |
| `/history` | Historique des simulations |
| `/compare` | Comparaison côte à côte |
| `/materials` | Base de matériaux |
| `/statistics` | Métriques globales — distribution des efficacités |
| `/validation` | Conformité IEEE/ASTM de la dernière simulation |
| `/chat` | **Assistant IA** — interface LLM conversationnelle |

---

## Mode CLI interactif

```bash
# Depuis Docker
docker exec -it sparc-web-1 python -m cli_interactif

# En local
python -m cli_interactif
```

### Raccourcis du menu

| Touche | Écran |
|---|---|
| `d` | Tableau de bord |
| `n` | Nouvelle simulation |
| `o` | **Optimiseur IA** |
| `a` | **Assistant LLM** (chat en langage naturel) |
| `h` | Historique |
| `r` | Visualiser résultats |
| `c` | Comparaison |
| `m` | Base matériaux |
| `s` | Statistiques |
| `b` | Constructeur config. JSON |
| `e` | Exporter (CSV / PDF) |
| `f` | Favoris |
| `g` | Recherche globale |
| `t` | Basculer thème |
| `q` | Quitter |

### CLI JSON (batch / scripts)

```bash
# Simulation depuis fichier config
python main.py configs/silicon_homo.json

# Options
python main.py configs/tandem_demo.json --output ./resultats --verbose

# Lister les types
python main.py --list-types

# Afficher un exemple
python main.py --example heterojunction
```

### CLI batch — `python -m cli` (11 commandes)

Depuis la v2.1.0, les 11 commandes du CLI batch sont toutes fonctionnelles :

| Commande | Description | Note v2.1.0 |
|---|---|---|
| `run` | Lancer une simulation | — |
| `list` | Lister les simulations | — |
| `show` | Afficher les détails | — |
| `compare` | Comparer deux simulations | Affiche désormais `Jmax` et `Vmax` correctement |
| `export` | Exporter les résultats | — |
| `materials` | Base de matériaux | — |
| `config` | Gérer la configuration | — |
| `validate` | Valider une config JSON | — |
| `delete` | Supprimer une simulation | — |
| `browse` | Parcourir l'historique | Pleinement fonctionnel (bugfix) ; accepte `--output`/`-o` |
| `types` | Lister les types de simulation | — |

---

## Mode IA — Optimiseur Bayésien

### Principe

L'optimiseur explore intelligemment l'espace des paramètres physiques :

```
Trials 1–20   →  Exploration initiale aléatoire
Trials 21+    →  Exploitation Bayésienne
                 (propose les zones les plus prometteuses)
```

### Moteurs disponibles

| Moteur | Algorithme | Usage recommandé |
|---|---|---|
| **Optuna TPE** | Tree-structured Parzen Estimator | Défaut · tout usage |
| **Optuna GP** | Gaussian Process Sampler | < 10 paramètres |
| **BoTorch GP** | qLogExpectedImprovement | Maximum précision |
| **CMA-ES** | Evolution Strategy | Espaces larges continus |
| **Random** | Échantillonnage uniforme | Baseline |

### Via l'interface Web

1. Aller sur `http://localhost:5000/optimize`
2. Choisir le type de simulation et le moteur
3. Définir les paramètres avec leurs bornes
4. Cliquer **Lancer l'optimisation**
5. Suivre la progression en temps réel
6. Analyser : convergence, importance, heatmap, Top 10

### Via le CLI interactif

```bash
python -m cli_interactif
# Touche 'o' → Nouvelle optimisation → Suivre l'assistant
```

### Via l'API REST

```bash
# Créer le job
curl -X POST http://localhost:5000/api/optimize/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "opt_si",
    "sim_type": "homojunction",
    "engine": "optuna",
    "sampler": "tpe",
    "n_trials": 200,
    "objectives": ["efficiency"],
    "param_ranges": [
      {"name": "doping.n_region", "type": "log_float", "low": 1e15, "high": 1e18},
      {"name": "doping.p_region", "type": "log_float", "low": 1e14, "high": 1e17},
      {"name": "geometry.thickness_n", "type": "log_float", "low": 1e-5, "high": 5e-4},
      {"name": "geometry.thickness_p", "type": "log_float", "low": 5e-5, "high": 2e-3}
    ]
  }'
# → {"success": true, "opt_id": "abc123de"}

# Lancer
curl -X POST http://localhost:5000/api/optimize/abc123de/run

# Suivre (Server-Sent Events)
curl http://localhost:5000/api/optimize/abc123de/progress

# Résultats
curl http://localhost:5000/api/optimize/abc123de/results

# Rapport PDF
curl http://localhost:5000/api/optimize/abc123de/pdf -o rapport.pdf
```

### Format `param_ranges`

```json
{
  "name":  "doping.n_region",
  "type":  "log_float",
  "low":   1e15,
  "high":  1e18,
  "label": "Dopage N (cm-3)"
}
```

| `type` | Espace d'exploration |
|---|---|
| `float` | Continu linéaire |
| `log_float` | Continu log-scale (dopage, τ, μ) |
| `int` | Entier linéaire |
| `log_int` | Entier log-scale |
| `categorical` | Valeurs discrètes (`"choices": [...]`) |

La notation pointée mappe sur la structure de la config Sesame :
`doping.n_region` → `config["doping"]["n_region"]`

### Analyse de sensibilité Sobol

```bash
curl -X POST http://localhost:5000/api/optimize/abc123de/sensitivity \
  -H "Content-Type: application/json" \
  -d '{"n_samples": 64}'
```

Retourne les indices S1 (premier ordre) et ST (total-effect) pour chaque paramètre.

### Surrogate — prédiction instantanée

Après l'optimisation, un Random Forest est entraîné sur les trials.
Prédiction en ~1 ms au lieu de ~5 s (Sesame) :

```bash
curl -X POST http://localhost:5000/api/optimize/abc123de/predict \
  -H "Content-Type: application/json" \
  -d '{
    "doping.n_region": 2.5e16,
    "doping.p_region": 1e15,
    "geometry.thickness_n": 1e-4,
    "geometry.thickness_p": 3e-4
  }'
# → {"predicted_value": 18.7, "uncertainty": 0.4, "confidence_95": [17.9, 19.5]}
```

### Surrogate — analyse avancée (CLI)

Le menu **Analyse du surrogate** dans le CLI (`o → Analyse du surrogate`) offre :

| Option | Description |
|---|---|
| Scan 1D | Variation d'un paramètre · courbe ASCII en temps réel |
| Inverse prediction | Trouve les paramètres atteignant une cible η donnée |
| Sauvegarder | Exporte le modèle entraîné (`.pkl`, fallback `~/.sparc/surrogates/`) |
| Charger | Recharge un surrogate précédemment entraîné |

---

## Progression en temps réel (SSE)

Les résultats de simulation en cours sont streamés via **Server-Sent Events** :

```bash
# Suivre la progression d'une simulation
curl -N http://localhost:5000/api/simulation/<sim_id>/progress-stream
```

La page `/results/<sim_id>` se connecte automatiquement au stream SSE
et affiche une barre de progression mise à jour sans rechargement.

---

## Comparaison visuelle

La page `/compare` offre 6 onglets :

| Onglet | Description |
|---|---|
| J-V | Courbes courant-tension superposées |
| P-V | Courbes puissance avec marqueur Pmax |
| EQE | Réponse spectrale comparée |
| Radar | Graphe araignée normalisé (η, Jsc, Voc, FF) |
| Tableau | Valeurs numériques, meilleure cellule surlignée, Δ |
| Diff config | Différences de configuration côte à côte |

---

## Export des données spatiales 2D

Pour les simulations `grain_boundary_2d`, le CLI propose (menu Export) :

- **CSV** : colonnes `i, j, x_cm, y_cm, n, p, v, efn, efp, R_srh`
- **NPZ** : format NumPy compressé (`.npz`) pour traitement Python direct

---

## Tâches planifiées (Celery Beat)

| Tâche | Fréquence | Description |
|---|---|---|
| `cleanup-redis-results-hourly` | 1 h | Supprime les résultats Redis > 24 h |
| `archive-old-simulations-daily` | 24 h | Archive SQLite → gzip JSONL (rétention configurable) |
| `compute-global-stats` | 6 h | Recalcule les métriques globales (Redis) |

Configurer la rétention via `SPARC_RETENTION_DAYS` (défaut : 90 jours).

---

## Types de simulation

| Type | Description |
|---|---|
| `homojunction` | p-n homojonction 1D (Si, GaAs, etc.) |
| `heterojunction` | Hétérojonction 1D (CdS/CdTe, a-Si/c-Si, etc.) |
| `graded_heterojunction` | Hétérojonction à gradient de gap |
| `with_defects` | Avec défauts SRH (énergie, capture, densité) |
| `tandem` | Tandem 2 jonctions (top + bottom cell) |
| `parametric_sweep` | Balayage d'un paramètre sur une plage |
| `optimize_thickness` | Optimise le rapport d'épaisseur n/p |
| `temperature_study` | Étude T-dépendante (modèle Varshni) |
| `variable_illumination` | Intensité lumineuse variable |
| `spectrum_study` | Différents spectres (AM0, AM1.5G, custom) |
| `quantum_efficiency` | EQE point par point |
| `spectral_response` | SR = EQE × flux AM1.5G |
| `capacitance_voltage` | C-V différentielle + Mott-Schottky |
| `luminescence` | PL (photoexcitation) / EL (polarisation) |
| `contact_study` | Schottky vs ohmique (φ_B variable) |
| `equivalent_circuit` | Extraction Rs, Rsh depuis IV |
| `ebic` | EBIC (Electron Beam Induced Current) |
| `ebic_simulation` | EBIC avancé (profil de faisceau + diffusion) |
| `grain_boundaries` | Joint de grain 1.5D |
| `grain_boundary_2d` | Joint de grain 2D Sesame (cartes n, p, V, R_SRH) |
| `lifetime_analysis` | Durée de vie effective vs injection |

---

## Format des configurations JSON

```json
{
  "simulation_name": "mon_si_homo",
  "simulation_type": "homojunction",
  "materials": {
    "active": "Si"
  },
  "geometry": {
    "thickness_n": 5e-5,
    "thickness_p": 2e-4,
    "nx": 100
  },
  "doping": {
    "n_region": 1e17,
    "p_region": 1e15
  },
  "voltages": {
    "start": 0.0,
    "stop": 0.7,
    "points": 50
  },
  "illumination": {
    "enabled": true,
    "photon_flux": 2.5e17,
    "absorption_coefficient": 1e4
  }
}
```

39 exemples préconfigurés sont disponibles dans `configs/`.

---

## Base de matériaux

### Matériaux intégrés

| Matériau | Eg (eV) | Catégorie |
|---|---|---|
| Si | 1.12 | Semiconducteur élémentaire |
| Ge | 0.66 | Semiconducteur élémentaire |
| GaAs | 1.42 | III-V |
| CdTe | 1.50 | II-VI |
| CdS | 2.42 | II-VI |
| CIGS | 1.15–1.65 | Ternaire |
| CZTS | 1.50 | Quaternaire |
| MAPbI3 | 1.55 | Pérovskite |
| InP | 1.35 | III-V |
| GaInP | 1.90 | III-V ternaire |

### Matériau personnalisé (JSON)

```json
{
  "Eg": 1.34,
  "Nc": 4.7e17,
  "Nv": 9.0e18,
  "mu_e": 100.0,
  "mu_h": 25.0,
  "eps": 13.6,
  "tau_e": 1e-8,
  "tau_h": 1e-8,
  "chi": 4.07
}
```

---

## Déploiement Docker

```bash
docker compose up
```

| Service | Port | Rôle |
|---|---|---|
| `web` | 5000 | Flask + API + Optimisation + Chat IA |
| `worker` (×2) | — | Workers Celery |
| `beat` | — | Scheduler (nettoyage horaire) |
| `redis` | 6379 | Broker Celery + cache |
| `flower` | 5555 | Monitoring workers |
| `ollama` ¹ | 11434 | LLM local (profil `llm`) |
| `cli` ¹ | — | CLI interactif (profil `cli`) |
| `ai` ¹ | — | Batch / scripts JSON (profil `ai`) |

¹ services à démarrage manuel uniquement

```bash
# Mode Web (défaut)
docker compose up

# Mode CLI interactif
docker compose run --rm cli

# Mode IA — exécution d'une config JSON
docker compose run --rm ai python main.py configs/silicon_homo.json

# Démarrer avec assistant LLM Ollama
docker compose --profile llm up
docker compose exec ollama ollama pull llama3.2

# Scaler les workers
docker compose up --scale worker=4

# Health check
curl http://localhost:5000/api/health

# Reconstruire sans cache
docker compose build --no-cache
```

> **Données persistantes :** la base SQLite (`sparc.db`) et les résultats (`outputs/`)
> sont stockés dans des **volumes Docker nommés** (`sparc_data`, `sparc_outputs`).
> Ils survivent aux redémarrages. `docker compose down -v` les efface.

### Installation sans Docker

```bash
pip install -r requirements.txt
pip install torch --extra-index-url https://download.pytorch.org/whl/cpu
pip install botorch
pip install git+https://github.com/usnistgov/sesame.git@e2769a9d15c64415a87a5cfb566cbf2f3dac309f

python main.py configs/silicon_homo.json
```

---

## Variables d'environnement

```env
# Obligatoire en production
SESAME_WEB_SECRET=changez-cette-cle

# Serveur
SESAME_WEB_HOST=0.0.0.0
SESAME_WEB_PORT=5000
SESAME_WEB_DEBUG=0

# Base de données
SPARC_DB_PATH=/app/data/sparc.db

# Redis / Celery
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

# Flower
SPARC_FLOWER_PORT=5555

# Agent LLM — provider : ollama (local) | anthropic (cloud)
SPARC_LLM_PROVIDER=ollama
SPARC_LLM_MODEL=llama3.2
OLLAMA_BASE_URL=http://ollama:11434

# Clé Anthropic (si SPARC_LLM_PROVIDER=anthropic)
ANTHROPIC_API_KEY=

# Optionnel : Materials Project API
# Accepte aussi : MP_API_KEY ou MAPI_KEY
MATERIALS_PROJECT_API_KEY=

# Rétention des archives (jours)
SPARC_RETENTION_DAYS=90
```

---

## API REST

### Simulations

| Méthode | URL | Description |
|---|---|---|
| `POST` | `/api/simulate` | Créer et lancer |
| `GET` | `/api/results/<id>/status` | Statut + progression |
| `GET` | `/api/results/<id>` | Résultats JSON |
| `GET` | `/api/results/<id>/plot/<nom>` | Graphique PNG |
| `GET` | `/api/results/<id>/csv` | Export CSV |
| `GET` | `/api/results/<id>/pdf` | Rapport PDF |
| `GET` | `/api/results/<id>/progress` | Flux SSE |

### Optimisation IA

| Méthode | URL | Description |
|---|---|---|
| `POST` | `/api/optimize/create` | Créer un job |
| `POST` | `/api/optimize/<id>/run` | Lancer |
| `GET` | `/api/optimize/<id>/progress` | Flux SSE |
| `GET` | `/api/optimize/<id>/status` | Statut |
| `GET` | `/api/optimize/<id>/results` | Résultats complets |
| `GET` | `/api/optimize/<id>/heatmap` | Matrice de corrélation |
| `POST` | `/api/optimize/<id>/sensitivity` | Analyse Sobol |
| `POST` | `/api/optimize/<id>/predict` | Prédiction surrogate |
| `GET` | `/api/optimize/<id>/pdf` | Rapport PDF |
| `DELETE` | `/api/optimize/<id>/delete` | Supprimer |
| `GET` | `/api/optimize/history` | Liste des optimisations |

### Matériaux

| Méthode | URL | Description |
|---|---|---|
| `GET` | `/api/materials` | Liste |
| `GET` | `/api/materials/<formule>` | Propriétés |
| `POST` | `/api/materials/search` | Recherche par Eg |

---

## Tests

```bash
# Tests d'intégration (204+ tests)
python -m pytest tests/ -v

# Test rapide d'une simulation
python main.py configs/silicon_homo.json --verbose

# Valider les helpers d'optimisation (sans Sesame)
python -c "
from optimization.optuna_engine import _apply_params_to_config
cfg = {'doping': {'n_region': 1e16}}
result = _apply_params_to_config(cfg, {'doping.n_region': 5e16})
assert result['doping']['n_region'] == 5e16
print('OK — param injection')
"

# Valider le surrogate
python -c "
from optimization.surrogate import SurrogateModel
trials = [{'params': {'x': i*0.1, 'y': i*0.2}, 'objectives': {'efficiency': i*0.5}} for i in range(20)]
sm = SurrogateModel('rf')
s = sm.train(trials, ['x', 'y'])
p = sm.predict({'x': 1.0, 'y': 2.0})
print(f'OK — R2={s[\"r2_score\"]:.3f}, pred={p[\"predicted_value\"]:.2f}')
"
```

---

## Résultats et sorties

```
outputs/
├── mon_si_homo_20240410/
│   ├── mon_si_homo_results.json
│   └── viz/
│       ├── iv_curve.png
│       ├── band_diagram.png
│       ├── eqe.png
│       ├── recombination.png
│       └── ...
├── pdf/                            ← Rapports PDF (CLI interactif)
│   └── rapport_ma_simulation.pdf
├── optimisation_opt_si.pdf         ← Rapport d'optimisation
├── optimisation_opt_si.csv         ← Trials d'optimisation
└── surrogate_rf.pkl                ← Surrogate model sauvegardé
```

> **Note :** Les rapports PDF générés depuis le CLI interactif sont
> automatiquement enregistrés dans `outputs/pdf/` pour une retrouvabilité
> facile. Si le dossier n'est pas inscriptible, le fallback est
> `~/.sparc/reports/`.

### Paramètres extraits (IEEE 488-2022)

| Paramètre | Symbole | Unité |
|---|---|---|
| Efficacité | η (PCE) | % |
| Courant de court-circuit | Jsc | mA/cm² |
| Tension circuit ouvert | Voc | V |
| Facteur de remplissage | FF | — |
| Courant de saturation | J0 | mA/cm² |
| Facteur d'idéalité | n | — |
| Résistance série | Rs | Ω·cm² |
| Résistance shunt | Rsh | Ω·cm² |

---

## Licence

MIT. Dépendances principales : Sesame (NIST), Optuna (MIT), BoTorch (MIT),
PyTorch (BSD), scikit-learn (BSD), SALib (MIT), Flask (BSD), ReportLab (BSD).
