Introduction#

QUEENS (Quantification of Uncertain Effects in Engineering Systems) is a Python framework for solver-independent multi-query analyses of large-scale computational models.

Capabilities#

QUEENS offers a large collection of cutting-edge algorithms for deterministic and probabilistic analyses such as:

parameter studies and identification
sensitivity analysis
surrogate modeling
uncertainty quantification
Bayesian inverse analysis

QUEENS provides a modular architecture for:

parallel queries of large-scale computational models
robust data, resource, and error management
easy switching between analysis types
smooth scaling from laptop to HPC cluster

Installation#

Prerequisites: A Unix system with Python 3.12 or newer. For development, use Pixi.

Clone the QUEENS repository and install it from the source checkout with:

pip install .

We recommend using some form of environment management instead of installing into your system Python. For more details, see the QUEENS documentation.

Optional runtime extras can be installed with:

pip install ".[tutorials]"
pip install ".[fourc]"
pip install ".[all]"

Recommended installation#

We recommend a modern project-based workflow based on Pixi especially for development. After cloning the repository, installing with Pixi is as easy as:

pixi install
pixi run install-editable

The default Pixi environment contains the core QUEENS dependencies. Use all for runtime extras without development tools. For named Pixi environments, run pixi run -e <environment> install-editable once for each environment you want to use.

Development installation#

For development, we recommend using Pixi together with the dev environment. dev contains the full contributor setup, including development tools, tutorials, and the 4C interface dependencies. Clone the repository and install with:

pixi install --environment dev
pixi run -e dev install-editable

Useful development commands then look like:

pixi run -e dev pytest
pixi run -e dev pre-commit run --all-files

User-managed environments#

QUEENS should be installed into an isolated Python environment rather than into your system Python. The examples below use different environment managers, but the idea is always the same:

Create an environment with Python 3.12 or newer.
Activate that environment.
Check that python points to the environment and has the expected version.
Install QUEENS from the repository root with python -m pip install ..

`venv`#

Use venv if you already have Python 3.12 installed on your system:

git clone https://github.com/queens-py/queens.git
cd queens
python3.12 -m venv .venv
source .venv/bin/activate
python --version
python -m pip install --upgrade pip
python -m pip install .

After activation, python --version should report Python 3.12 or newer. If python3.12 is not available, install Python 3.12 first with your system package manager or another Python installer.

`uv venv`#

If you use uv, let uv install and select Python 3.12:

git clone https://github.com/queens-py/queens.git
cd queens
uv python install 3.12
uv venv --python 3.12
source .venv/bin/activate
python --version
python -m pip install .

Conda#

Conda-style environment managers can create an environment with the required Python version directly:

git clone https://github.com/queens-py/queens.git
cd queens
conda create -n queens python=3.12
conda activate queens
python --version
python -m pip install .

The same pattern also applies to compatible tools such as Mamba or Micromamba.

For development, prefer the locked Pixi environments shown above because they keep dependency resolution and editable installs aligned with CI.

Testing installation#

To test for a successful installation, run the test suite:

pixi run -e dev pytest

Consult the documentation of QUEENS tests for more details on testing.

Citing QUEENS#

You used QUEENS for a publication? Don’t forget to cite

@misc{queens,
      title={QUEENS: An Open-Source Python Framework for Solver-Independent Analyses of Large-Scale Computational Models},
      author={Jonas Biehler and Jonas Nitzler and Sebastian Brandstaeter and Maximilian Dinkel and Volker Gravemeier and Lea J. Haeusel and Gil Robalo Rei and Harald Willmann and Barbara Wirthl and Wolfgang A. Wall},
      year={2025},
      eprint={2508.16316},
      archivePrefix={arXiv},
      primaryClass={cs.CE},
      url={https://arxiv.org/abs/2508.16316},
      note = {Jonas Biehler, Jonas Nitzler, and Sebastian Brandstaeter contributed equally.}
}

and the respective methods papers.

License#

Licensed under GNU LGPL-3.0 (or later). See LICENSE.