festim-niuq 0.2.0

Non-Intrusive Uncertainty Quantification for FESTIM code

FESTIM-NIUQ

FESTIM-NIUQ is a Python package for Non-Intrusive Uncertainty Quantification of tritium transport simulations using the FESTIM finite-element framework.

The package couples EasyVVUQ (from the SEAVEA Toolkit) with FESTIM to propagate parametric uncertainties through tritium transport models and compute Sobol sensitivity indices via Polynomial Chaos Expansion (PCE) and Quasi-Monte Carlo (QMC) methods.

Features

• Non-intrusive UQ: treats the FESTIM solver as a black box — no solver modifications needed
• Sensitivity analysis: first-order and total-order Sobol indices for spatially-resolved quantities
• Multiple UQ methods: Polynomial Chaos Expansion (PCE), Quasi-Monte Carlo (QMC), and Finite Differences
• Correlated parameters: supports non-diagonal covariance matrices via Cholesky decomposition
• Bayesian inverse UQ: PCE surrogate + MCMC inversion with emcee
• Flexible configuration: all model and UQ settings controlled via YAML files
• HPC-ready: QCG-PilotJob integration and SLURM scripts included
• Automated plotting: publication-quality uncertainty and sensitivity plots

Installation

Prerequisites

• Python >= 3.9
• FESTIM (requires FEniCSx / DOLFINx)

Quick install

The easiest way to set up the environment is with conda:

# Create and activate environment with FESTIM
conda create -n festim-env
conda activate festim-env
conda install -c conda-forge festim

# Install FESTIM-NIUQ and its dependencies
pip install -r requirements.txt

Alternatively, install directly:

pip install -e .

Development install

pip install -e ".[dev]"

Usage

Basic UQ campaign

Run the default UQ campaign with built-in test configuration:

cd uq
python3 easyvvuq_festim.py

This will compute statistical moments of the tritium inventory and generate Sobol sensitivity index plots.

Custom configuration

Provide your own YAML configuration file:

python3 easyvvuq_festim.py --config config/config.uq_test_cj1959.yaml

Correlated parameters

Run UQ with correlated input parameters:

python3 easyvvuq_festim_correlated.py --config config/config.uq_test_cj1959.yaml --uq-scheme pce --p-order 3

Parameter scanning

Perform a parameter scan over a single parameter:

python3 festim_model_scan.py

Bayesian inverse UQ

Run Bayesian inversion using a PCE surrogate and MCMC:

python3 bayesian_inverse_uq.py --config config/config_bayesian_ss.yaml --p-order 3

Configuration

All settings are centralised in a YAML configuration file that controls:

• Geometry: domain size, coordinate system (Cartesian/cylindrical/spherical), mesh resolution
• Materials: transport coefficients with mean values and uncertainties
• Boundary conditions: Dirichlet, Neumann, or convective flux
• Source terms: volumetric generation rates
• Simulation: steady-state or transient, time stepping, solver tolerances
• UQ settings: parameter distributions, polynomial order, number of samples

See example configurations in uq/config/.

Testing

Run the test suite:

pytest tests/

Project Structure

festim_niuq/
├── festim_model/         # FESTIM model wrapper
│   ├── Model.py          # Main model class (FESTIM 2.0 API)
│   └── diagnostics/      # Post-processing diagnostics
├── uq/                   # UQ orchestration layer
│   ├── easyvvuq_festim.py            # Main UQ campaign script
│   ├── easyvvuq_festim_correlated.py # Correlated parameters UQ
│   ├── bayesian_inverse_uq.py        # Bayesian inverse UQ
│   ├── festim_model_run.py           # Single FESTIM run wrapper
│   ├── festim_model_scan.py          # Parameter scanning
│   ├── config/                       # Example YAML configurations
│   └── util/                         # Encoders, decoders, plotting
├── tests/                # Unit and integration tests
├── docs/                 # Documentation
└── paper/                # JOSS paper

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License — see LICENSE for details.

Citation

If you use FESTIM-NIUQ in your research, please cite it. See CITATION.cff for details.

Acknowledgements

FESTIM-NIUQ was developed at the Nuclear Futures Institute, Bangor University.