HISP rework for PFC-TT

README.md

@@ -1,46 +1,81 @@
-[![CI](https://github.com/kaelyndunnell/hisp/actions/workflows/ci.yml/badge.svg)](https://github.com/kaelyndunnell/hisp/actions/workflows/ci.yml)
-[![docs](https://readthedocs.org/projects/hisp/badge/?version=latest)](https://hisp.readthedocs.io/en/latest/)
-
 # HISP
 
-Hydrogen Inventory Simulations for PFCs (HISP) is a series of code that uses FESTIM to simulate deuterium and tritium inventories in a fusion tokamak first wall and divertor PFCs. 
+Hydrogen Inventory Simulations for PFCs (HISP) is a series of code that uses FESTIM to simulate deuterium and tritium inventories in a fusion tokamak first wall and divertor PFCs.
 
-## How to Run:
+**This fork** reworks HISP to serve as the FESTIM orchestrator for [PFC-Tritium-Transport](https://github.com/iterorganization/PFC-Tritium-Transport) (PFC-TT): it receives bin objects, material properties, scenarios, and plasma data from PFC-TT and builds the corresponding FESTIM simulations. PFC-TT owns all physics definitions, inputs, and user control.
 
-Clone the repository:
+That said, once the core PFC-TT classes are importable (by having a local clone and its conda environment), HISP can also be used independently of PFC-TT's workflow. The [`example/`](example/) folder demonstrates this: bins and scenarios are defined directly in Python and passed to HISP to build and solve a simulation.
 
-```
-git clone https://github.com/kaelyndunnell/hisp
-cd hisp
+For more advanced use cases — including flexible input handling, detailed physics control, or large parameter studies — users are encouraged to work directly with https://github.com/iterorganization/PFC-Tritium-Transport, which provides a more complete and streamlined way to set up and run simulations.
+
+## What HISP Does
+
+For each bin it constructs a FESTIM simulation: it translates the bin geometry (thickness, optional Cu layer, surface area) into the model domain, assigns material parameters and trap definitions, builds time-dependent boundary conditions and implantation source expressions, and selects appropriate boundary-condition types (Robin/Neumann) before assembling and solving the transport equations with adaptive time-stepping. The per-bin outputs (retained inventory, surface fluxes, concentration profiles, and time traces) are exported to JSON for post-processing or aggregation across bins.
+
+## Dependencies
+
+HISP depends on:
+- [FESTIM](https://github.com/festim-dev/festim) — finite element solver for hydrogen transport
+- [PFC-Tritium-Transport](https://github.com/iterorganization/PFC-Tritium-Transport) — provides bin definitions, material classes, scenario handling, and plasma data
+
+Both are installed as part of the PFC-TT conda environment (see below).
+
+## How to Install
+
+Follow the full installation instructions in the [PFC-Tritium-Transport README](https://github.com/iterorganization/PFC-Tritium-Transport). In summary:
+
+### 1. Clone PFC-Tritium-Transport
+```bash
+git clone --branch main https://github.com/iterorganization/PFC-Tritium-Transport.git
 ```
 
-Run this command to create a new environment with the right dependencies (eg. dolfinx):
+### 2. Create the conda environment
+This step installs all core simulation dependencies including **FESTIM** (required by both PFC-Tritium-Transport and HISP), FEniCS-DOLFINx, PETSc, and all other required packages:
+```bash
+conda config --set channel_priority flexible
+conda env create -f PFC-TT.yml
+conda activate PFC-TT
 ```
-conda env create -f environment.yml
+
+### 3. Register the PFC-TT path
+HISP needs to know where PFC-Tritium-Transport is located on your system at runtime. Register the path once in your conda environment (replace with your actual clone location):
+```bash
+conda env config vars set PFC_TT_PATH="/path/to/your/PFC-Tritium-Transport"
+conda deactivate && conda activate PFC-TT
 ```
 
-Then, activate the environment:
+You can verify it was set correctly with:
+```bash
+conda env config vars list
 ```
-conda activate hisp-env
+
+### 4. Install HISP
+HISP is installed without dependencies since FESTIM and all other requirements are already provided by the PFC-TT conda environment:
+```bash
+pip install --no-deps git+https://github.com/AdriaLlealS/hisp.git@main
+pip install h_transport_materials
 ```
 
+## Examples
 
-Install the `hisp` package with:
+The `example/` folder contains a working example based on the HISP paper ([Dunnell et al., 2026](https://arxiv.org/abs/2604.04751)), demonstrating a full simulation of deuterium and tritium retention in iter's first wall and divertor plasma-facing components.
 
-```
-python -m pip install -e .
-```
+This example includes the results for a single bin under a specific scenario, along with a simple plotting script to visualise the outputs and the corresponding generated plot.
 
-This will also install the pip dependencies like `h-transport-materials` and `FESTIM`.
+See [`example/README.md`](example/README.md) for a full description of the example and instructions on how to run it.
 
-> **_NOTE:_**  Using `-e` with pip will install the package in editable mode, meaning the source code can be modified without having to reinstall the package.
+## Running Tests
 
-## Run the tests
+With the conda environment active and `PFC_TT_PATH` set:
+```bash
+cd /path/to/hisp
+python -m pytest tests/ -v
+```
 
-After cloning the repo and installing hisp, run:
+## Development History
 
-```
-python -m pytest test
-```
+The first prototype (2024) was a single framework that combined simulation setup and solver execution, using MHIMS as the hydrogen isotope transport solver.
+
+In early 2025, MHIMS was replaced by FESTIM for improved computational efficiency, and the codebase was split into two repositories — PFC-TT and HISP. During this stage, HISP still retained a significant role in handling physics definitions and simulation inputs alongside solver-related functionalities.
 
-> **_NOTE:_**  Make sure to install the test dependencies with `python -m pip install -e .[test]`
+A subsequent major refactor further clarified the separation of responsibilities: all physics definitions and input handling were moved into PFC-TT, where they were also extended and further developed. At the same time, HISP evolved towards a role focused on solver execution and orchestration, with improved flexibility and integration with FESTIM. These developments led to the present versions of both codes.

example/README.md

@@ -0,0 +1,66 @@
+# Example: ITER PFCs tritium retention simulation
+
+This folder recreates the bin definitions and operational scenarios shown in the
+paper below. It demonstrates how to:
+
+1. Define the plasma-facing component segments (bins) of a reactor with their
+   geometry, materials, and trap parameters.
+2. Run HISP on a single bin to solve the hydrogen isotope transport equations
+   (diffusion + trapping) via FESTIM and obtain time-resolved retention results.
+
+Reference:
+> Dunnell, K., Lleal, A., Hodille, E. A., Dufour, J., Delaporte-Mathurin, R., & Wauters, T. (2026).
+> *Hydrogen Inventory Simulations for PFCs (HISP)*.
+> arXiv:2604.04751. https://arxiv.org/abs/2604.04751
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `make_iter_bins.py` | Creates 94 Bin objects (62 poloidal segments × wetted modes) based on the configuration described in the HISP paper |
+| `scenarioA.py` | Defines a plasma operation scenario consisting of: 10 FP,DT pulses + STM (4-day wait) + bake |
+| `scenarioB.py` | Defines a plasma operation scenario consisting of: 10 FP,DT pulses + 2-day GDC + bake |
+| `scenarioC.py` | Defines a plasma operation scenario consisting of: 5 FP,DT pulses + 1 DD pulse + 5 FP,DT pulses + 1 DD pulse + 2-day GDC + bake |
+| `run_single_bin.py` | Main script — runs one bin with a chosen scenario |
+| `plot_T_inventory.py` | Plots tritium inventory from results JSON |
+| `data/` | Binned plasma flux data (ion/atom fluxes, energies, heat loads per bin) |
+
+## How to run
+
+Activate the PFC-TT conda environment (which should already have `PFC_TT_PATH` set — see the main HISP README for setup).
+
+```bash
+conda activate PFC-TT
+cd hisp/example
+python run_single_bin.py --bin-index 0 --scenario scenarioA
+```
+
+Options:
+- `--bin-index N` — which bin to simulate (0–93)
+- `--scenario {do_nothing, capability_test, just_glow}`
+
+Results are saved as JSON in `results_binN_<material>_<mode>/`.
+
+## Post-processing
+
+`plot_T_inventory.py` reads the results JSON and plots the total tritium
+inventory over time, decomposed into its mobile and trapped contributions
+(one curve per trap). This gives a clear view of how retention evolves
+through the pulse sequence and the baking.
+
+Below is the result for bin 0 — the high-wetted sub-bin of ITER's First Wall
+Panel 1 — run with Scenario A:
+
+![T inventory for bin 0](results_bin0_W_high_wetted/T_inventory.png)
+
+## Adapting this example for your own simulation
+
+The files in this folder can be used as templates for custom simulations. For any simulation you set up yourself, you need to provide two things: **bin definitions** (geometry, materials, trap parameters) and **binned plasma data files** (fluxes, heat loads, particle energies per bin).
+
+**To define your own bins and materials**, edit `make_iter_bins.py`. The file has two parts:
+
+- **Materials** — defined at the top as `Material` objects. Each material requires a name, atomic density (`Mat_density`), diffusion parameters (`D0`, `E_D`), recombination parameters (`K_R`, `E_R`), and a list of `Trap` objects with their density (atomic fraction), trapping and detrapping rate prefactors (`k_0`, `p_0`) and activation energies (`E_k`, `E_p`). Add or modify materials here to match your reactor's PFC materials.
+
+- **Bin table** (`_BIN_DATA`) — each row defines one bin with its poloidal coordinates (`z_start`, `r_start`, `z_end`, `r_end`), material name, thickness, copper backing thickness, wetted mode, surface areas, and boundary condition types. Modify the rows to match your reactor geometry, or add new rows for additional bins. Each bin must reference a material defined in the materials block above.
+
+**To provide your own plasma data**, you need to supply binned flux data files for each pulse type in your scenario — containing ion and atom fluxes, particle energies, and heat loads for each bin. The `data/` folder contains the files used in this example and serves as a reference for the expected format. These files are assigned to each pulse type inside the scenario file — look for the data file path assignments at the top of `scenarioA.py` as a template. Every bin defined in `make_iter_bins.py` must have a corresponding entry in the binned flux data files.