Bicyclus

Bicyclus is a Bayesian Inference module for Cyclus. Specifically, it is an interface written in Python3 that connects Cyclus, a nuclear fuel simulator, with PyMC (formerly PyMC3), a Python package for Bayesian statistics using Markov chain Monte Carlo algorithms.

Bicyclus, Bicyclus, Bicyclus
I want to use my Bicyclus
I want to use Cyclus
I want to infer with Cyclus
I want to infer what I like.

Freddie Mercury (somewhen, somewhere, probably)

Features

• Run inference processes on nuclear fuel cycles simulated with Cyclus.
• Store quantities of interest and simulation output that are not part of the inference process, in separate files. These can be used for later analysis.
• Use PyMC distributions as priors (WIP, currently restricted to a subset of distributions).
• Features utility functions for post-processing and plotting posterior distributions.

How-to

Requirements

The following table lists the software requirements. All dependencies listed below will be installed automatically through pip3 except for Cyclus, which the user must install themself.

Name	Tested with version	Notes
Python	3.10.6
PyMC	4.2.0	must be used with PyMC v4.x or larger
Aesara	2.8.2	only for PyMC v4.x
PyTensor		only for PyMC v5.x or larger
Arviz	0.12.1
NumPy	1.23.3
Scipy	1.9.1
Pandas	1.5.0	only for plotting
matplotlib	3.6.0	only for plotting
seaborn	0.12.0	only for plotting
Cyclus	1.5.5-59-gb1a858e3	Must be installed by the user

Installation

Install Bicyclus and all dependencies.

$ git clone https://github.com/Nuclear-Verification-and-Disarmament/bicyclus.git
$ cd bicyclus
$ pip3 install ".[plotting]"

If you do not want to install dependencies needed for plotting, run the following commands:

$ git clone https://github.com/Nuclear-Verification-and-Disarmament/bicyclus.git
$ cd bicyclus
$ pip3 install .

You can still run the inference process, but features from bicyclus/visualize may not be available.

Tutorial

Inference mode

A minimum working example (MWE) can be found in the examples directory. At the moment, Bicyclus can be used through a driver script that has to be written on a case-by-case basis. However, the MWE provided should be a good starting point for any new driver script.

Forward mode

Bicyclus can be used to perform large-scale forward simulations with Cyclus, which can be useful, e.g., to perform sensity analyses. This so-called forward mode uses Quasi Monte Carlo sampling (specifically, Sobol sequences) to efficiently sample the input parameter space. Furthermore, the driver script and file structure used in the inference mode can largely be reused here.

An MWE might be provided at a later stage.

Pitfalls

• Depending on the runtime of one Cyclus run, subprocess's timeout value has to be adapted. It is defined in bicyclus/blackbox/blackbox.py (CyclusCliModel.simulate) and is currently set to 300 seconds (as of September 2022).

Legacy code

Originally, this work was developed as part of a Bachelor's thesis by Lewin Bormann. If you are interested in the git blame and log beyond this repository's initial commit, please visit the original repository. That repository also contains two applications of complex nuclear fuel cycles and reconstruction scenarios.

Contributing: Usage of pre-commit hooks

We follow the Black code style. Run the following command from the root directory to enable use of the pre-commit hook. This will automatically run black when comitting and thus will ensure proper formatting of the committed code.

$ git config --local core.hooksPath .githooks/