Metadata-Version: 2.4
Name: pvsim-pv
Version: 1.0
Summary: Semiconductor Physics Analysis and Research Code — open-source semiconductor and photovoltaic TCAD simulation platform
Author-email: PVSim Contributors <pvsim-pv@proton.me>
License: MIT License
        
        Copyright (c) 2024-2026 PVSim 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/PVSim
Project-URL: Repository, https://github.com/Quantum-ARISE-Acad/PVSim
Project-URL: Documentation, https://github.com/Quantum-ARISE-Acad/PVSim#readme
Project-URL: Changelog, https://github.com/Quantum-ARISE-Acad/PVSim/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/Quantum-ARISE-Acad/PVSim/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: seaborn>=0.11.0
Requires-Dist: uncertainties>=3.1.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: werkzeug>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: prompt_toolkit>=3.0.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: cmaes>=0.10.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
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: workers
Requires-Dist: celery>=5.3.0; extra == "workers"
Requires-Dist: redis>=4.6.0; extra == "workers"
Requires-Dist: kombu>=5.3.0; extra == "workers"
Requires-Dist: flower>=2.0.0; extra == "workers"
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"
Requires-Dist: openai>=1.0.0; extra == "llm-cloud"
Requires-Dist: mistralai>=1.0.0; extra == "llm-cloud"
Requires-Dist: google-generativeai>=0.5.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: pvsim-pv[botorch,llm-cloud,llm-local,materials,tcad,workers]; 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"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

<div align="center">

# PVSim — Semiconductor Physics Analysis and Research Code

**v1.0 · MIT · Python 3.10+ · Sesame (NIST)**

[![PyPI](https://img.shields.io/pypi/v/pvsim-pv?color=0d6efd&logo=pypi&logoColor=white)](https://pypi.org/project/pvsim-pv/)
[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue?logo=python&logoColor=white)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e)](./LICENSE)
[![Docker](https://img.shields.io/badge/docker-ready-2496ED?logo=docker&logoColor=white)](./DEPLOYMENT.md)

Simulateur TCAD 1D/2D drift-diffusion pour cellules solaires, avec optimisation bayésienne automatique et assistant LLM. Fonctionne 100 % localement — aucune clé API requise en configuration minimale.

</div>

---

## Installation

### Via pip

```bash
pip install pvsim-pv

# Stack complète pour la recherche (recommandé)
pip install "pvsim-pv[tcad,botorch]"
pip install git+https://github.com/usnistgov/sesame.git
```

> **Note Sesame :** le solveur TCAD NIST n'est pas publié sur PyPI. L'installation via git est requise séparément.

**Extras disponibles :**

| Extra | Contenu |
|---|---|
| `tcad` | Numba (JIT pour Sesame) |
| `botorch` | PyTorch CPU + BoTorch (optimisation GP avancée) |
| `workers` | Celery + Redis (simulations asynchrones distribuées) |
| `llm-local` | Ollama (assistant LLM local, 0 clé API) |
| `llm-cloud` | Anthropic / OpenAI / Mistral / Gemini |
| `materials` | mp-api + pymatgen (Materials Project en ligne) |
| `all` | Tout ce qui précède |

**Commandes disponibles après installation :**

```bash
pvsim-web        # Serveur web Flask → http://localhost:5000
pvsim-tui        # CLI interactif (TUI Rich)
pvsim run config.json  # Simulation batch depuis un fichier JSON

# 🔑 Gestion des clés API et de la configuration
pvsim-config     # Assistant interactif pour générer le fichier .env
pvsim-config --set MP_API_KEY=votre_cle  # Configurer rapidement Materials Project
pvsim-config --set OPENAI_API_KEY=xxx    # Configurer l'assistant LLM
```

### Via Docker

#### Avec Docker Compose (Recommandé pour le développement)

```bash
git clone https://github.com/Quantum-ARISE-Acad/PVSim.git
cd PVSim
pvsim-config --env  # Génère un fichier .env propre
# Éditer .env — définir SESAME_WEB_SECRET
docker compose up
# → http://localhost:5000
```

La stack Docker Compose inclut : serveur web Flask, 2 workers Celery, Redis, scheduler Beat, et Flower (monitoring). Le solveur Sesame et toutes les dépendances scientifiques sont pré-installés dans l'image.

```bash
# Modes alternatifs
docker compose run --rm cli                          # CLI interactif
docker compose run --rm ai pvsim run cfg.json   # Batch
docker compose --profile llm up                      # + Ollama LLM local
docker compose up --scale worker=4                   # Scaler les workers
```

#### Avec l'image Docker Hub (Production)

Si vous ne voulez pas cloner le dépôt, vous pouvez utiliser l'image pré-construite publiée sur Docker Hub (via le pipeline automatisé) :

```bash
# Télécharger la dernière image publiée
docker pull <DOCKERHUB_USERNAME>/pvsim:latest

# Lancer le serveur web
docker run -p 5000:5000 -e SESAME_WEB_SECRET=votre_secret <DOCKERHUB_USERNAME>/pvsim:latest
```

### Depuis les sources

```bash
git clone https://github.com/Quantum-ARISE-Acad/PVSim.git
cd PVSim
python -m venv .venv && source .venv/bin/activate
pip install git+https://github.com/usnistgov/sesame.git
pip install -r requirements.txt
cp .env.example .env
pvsim-web      # ou : pvsim run configs/silicon_homo.json
```

---

## Ce que PVSim fait

PVSim est un pipeline complet : **config JSON → solveur Sesame → métriques IV → optimisation bayésienne → rapport PDF**.

Le solveur résout le système Poisson + continuité (drift-diffusion) en 1D ou 2D pour 27 types de simulation différents, sur 15 matériaux semiconducteurs validés. L'optimiseur Bayésien (Optuna / BoTorch) explore automatiquement l'espace des paramètres physiques pour maximiser l'efficacité.

---

## Types de simulation (27 routés)

| Catégorie | Types |
|---|---|
| **Jonctions simples** | `homojunction`, `homojunction_2d`, `heterojunction`, `heterojunction_2d`, `graded_heterojunction` |
| **Multicouches** | `multi_layer` (jusqu'à 7 couches) |
| **Multi-jonctions** | `tandem`, `triple_junction` |
| **Défauts** | `with_defects`, `continuous_defects`, `grain_boundaries`, `grain_boundary_2d` |
| **Études paramétriques** | `parametric_sweep`, `optimize_thickness`, `temperature_study`, `variable_illumination`, `spectrum_study` |
| **Couplages avancés** | `electro_thermal_study`, `degradation_study`, `transient_photovoltage` |
| **Caractérisations** | `quantum_efficiency`, `spectral_response`, `capacitance_voltage`, `luminescence`, `ebic_simulation`, `contact_study`, `equivalent_circuit` |

---

## Matériaux intégrés

15 matériaux avec paramètres validés (Nc, Nv, μ, τ, Cn/p Auger, B\_rad, χ, Eg) :

| Matériau | Eg (eV) | Type de gap | Référence |
|---|---|---|---|
| Si | 1.1247 | Indirect | Richter 2012, Klaassen 1992 |
| Ge | 0.664 | Indirect | NREL |
| GaAs | 1.424 | Direct | NREL |
| GaP | 2.272 | Indirect | NREL |
| InP | 1.344 | Direct | NREL |
| CdTe | 1.50 | Direct | NREL |
| CdS | 2.42 | Direct | NREL |
| CIGS | 1.30 | Direct | Ramanathan 2003 |
| CZTS | 1.50 | Direct | Kauk-Kuusik 2017 |
| MAPbI3 | 1.58 | Direct | Richter 2016 |
| CsPbI3 | 1.73 | Direct | Katan 2019 |
| FAPbI3 | 1.48 | Direct | Littérature |
| GaInP | 1.87 | Direct | Vurgaftman 2001 |
| AlGaAs | 1.80 | Direct | Vurgaftman 2001 |
| GaN | 3.43 | Direct | Monemar 1974 |

Extension en ligne via Materials Project (clé `MATERIALS_PROJECT_API_KEY`) et OPTIMADE.

---

## Format de configuration JSON

```json
{
  "simulation_name": "si_homo_baseline",
  "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+ configurations d'exemple dans `configs/`. La notation pointée `"doping.n_region"` est utilisée par l'optimiseur pour mapper les paramètres sur la config.

---

## Optimisation bayésienne

```bash
# Via l'API REST
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": "geometry.thickness_p", "type": "log_float", "low": 5e-5, "high": 2e-3}
    ]
  }'
```

**Moteurs :** Optuna TPE (défaut), Optuna GP, BoTorch qLogEI, CMA-ES, Random.

Post-optimisation : surrogate ML (Random Forest / GBM / GP), analyse de sensibilité Sobol (SALib), prédiction inverse (~1 ms vs ~5 s pour Sesame).

---

## API REST — routes principales

```
POST /api/simulate                      → Lancer une simulation
GET  /api/results/<id>                  → Résultats JSON
GET  /api/simulation/<id>/progress-stream  → SSE temps réel
POST /api/optimize/create               → Job d'optimisation
POST /api/optimize/<id>/run
GET  /api/optimize/<id>/results
POST /api/optimize/<id>/sensitivity     → Analyse Sobol
POST /api/optimize/<id>/predict         → Prédiction surrogate
GET  /api/health                        → État des services
GET  /api/docs/                         → Swagger interactif
```

---

## Architecture

```
PVSim/
├── router.py              SesameRouter — dispatch vers 27 modules (~115 kB)
├── main.py                CLI batch (entrée fichier JSON)
├── simulations/           ~55 modules (physique, matériaux, validation)
├── optimization/          Optuna + BoTorch + SALib + Surrogate
├── web/                   Flask + SQLite + ReportLab
├── cli/                   11 commandes batch
├── cli_interactif/        TUI Rich (17 écrans)
├── pvsim_agent/           Agent LLM multi-provider
├── workers/               Celery distribué
└── configs/               39+ configurations JSON d'exemple
```

---

## Variables d'environnement clés

```env
SESAME_WEB_SECRET=<clé-32-hex>          # Obligatoire en production
PVSim_WEB_PORT=5000
PVSim_DB_PATH=/app/data/pvsim.db
REDIS_URL=redis://redis:6379/0
PVSim_LLM_PROVIDER=ollama               # ollama | anthropic | openai | mistral | gemini
PVSim_LLM_MODEL=llama3.2
MATERIALS_PROJECT_API_KEY=              # Optionnel
```

Voir [`.env.example`](./.env.example) pour la liste complète.

---

## Tests

```bash
python -m pytest tests/ -v
python -m pytest tests/ -v -m unit        # Sans Sesame
pvsim run configs/silicon_homo.json --verbose
```

204+ tests. Marqueurs : `unit`, `integration`, `slow`, `benchmark`.

---

## Citer

```bibtex
@software{PVSim2026,
  title   = {PVSim — Semiconductor Physics Analysis and Research Code},
  version = {2.1.0},
  year    = {2026},
  url     = {https://github.com/Quantum-ARISE-Acad/PVSim},
  license = {MIT}
}
```

Citer également : Sesame (NIST) — https://pages.nist.gov/sesame/

---

**Liens :** [Documentation](./docs/INDEX.md) · [Guide développeur](./DEVELOPER.md) · [Déploiement](./DEPLOYMENT.md) · [Changelog](./CHANGELOG.md) · [Manuel utilisateur](./MANUEL_UTILISATEUR.md)
