Installation#

Use an environment manager such as venv or conda when installing MC/DC as a user or developer. An isolated environment avoids administrator access and keeps dependencies clean.

In general, Creating a venv environment and Installing with pip are the easiest options. Creating a conda environment and Installing MC/DC via conda requires more steps but can be more robust on specialized systems. A conda environment is necessary to install MC/DC on LLNL’s Lassen machine.

Creating a venv environment#

Python virtual environments are the recommended way to run MC/DC on personal machines and HPC systems. MC/DC supports Python 3.11 and newer, and the selected Python installation must provide venv. On HPC systems, administrators often provide Python and its package sources through a module system, so load a supported module such as python/3.13 before creating the environment.

Create a Python virtual environment with:

python -m venv <name_of_venv>

Activate the environment after creating it:

source <name_of_venv>/bin/activate

Activate the environment in each new terminal session before using MC/DC. Once the environment is active, continue to Installing with pip.

Installing with pip#

Install MC/DC with pip inside an active venv or conda environment to avoid administrator access and keep dependencies isolated.

Install the latest stable release from PyPI when you do not need to modify MC/DC:

pip install mcdc

Installing from Source#

Install MC/DC from source when you need a specific branch or plan to contribute changes: Use Python 3.14 for a contributor environment that will run Black locally; runtime-only source installations may use any supported Python version.

  1. Clone the MC/DC repository: git clone https://github.com/mcdc-project/mcdc.git

  2. Enter the repository: cd mcdc

  3. Install MC/DC and its development tools: python -m pip install -e ".[dev]"

The -e flag installs MC/DC as an editable package, so source changes and branch switches take effect without reinstalling the package.

Installing MC/DC via conda#

Conda provides robust environment management on systems with non-standard hardware or constrained software stacks. It is particularly useful on HPC systems such as Lassen, where mpi4py must match the system MPI implementation.

Install conda with Miniconda or Anaconda. The following commands install Miniconda on selected HPC architectures.

Dane (LLNL, x86_64),

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

Lassen (LLNL, IBM Power9),

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-ppc64le.sh
bash Miniconda3-latest-Linux-ppc64le.sh

The following example creates and activates a Python 3.13 conda environment named mcdc-env:

conda create -n mcdc-env python=3.13
conda activate mcdc-env

Clone MC/DC and enter the repository:

git clone https://github.com/mcdc-project/mcdc.git
cd mcdc

On an HPC system, load the appropriate MPI module and build mpi4py against that implementation before installing MC/DC:

module load <mpi_module>
CC=mpicc python -m pip install --no-cache-dir --no-binary=mpi4py mpi4py
python -m pip install -e ".[dev]"

On a local machine where pip can provide a compatible mpi4py installation, install MC/DC directly:

python -m pip install -e ".[dev]"

Run python -m pytest from the repository root to verify the installation.

Installing via Containers#

For container-based installation and execution, see MC/DC Container Guide.

Generating a Neutron Data Library from ACE Files#

MC/DC ships with a neutron conversion tool in tools/data_library_generator/neutron/ that reads standard ACE-format nuclear data files and writes them into MC/DC’s per-nuclide HDF5 format. This is the primary path for creating continuous-energy neutron libraries.

Prerequisites:

pip install ACEtk h5py numpy tqdm

You also need a set of ACE files from a source such as NJOY or an ENDF/B distribution.

Environment variables:

Variable

Description

MCDC_ACELIB

Path to the directory containing your ACE files.

MCDC_LIB

Path to the output directory where MC/DC HDF5 files will be written.

Running the generator:

export MCDC_ACELIB=/path/to/ace/files
export MCDC_LIB=/path/to/mcdc/library

cd tools/data_library_generator/neutron
python generate.py

By default, the tool converts only nuclides without a corresponding HDF5 file in $MCDC_LIB. Use --rewrite to regenerate all files or --verbose for detailed per-nuclide output:

python generate.py --rewrite --verbose

The generator processes each ACE file as follows:

  1. Reads the ACE header to determine nuclide identity (Z, A, isomeric state) and temperature.

  2. Extracts the principal cross-section block and writes HDF5 datasets grouped by reaction type.

  3. Extracts angular and energy distributions for each reaction channel.

  4. Extracts prompt and delayed \(\nu(E)\) data, precursor fractions, decay constants, and energy spectra for fissionable nuclides.

The resulting HDF5 file (e.g., U235-293.6K.h5) is ready for use with mcdc.Material().

GPU Operability (MC/DC+Harmonize)#

MC/DC supports most of its Numba enabled features for GPU compilation and execution. When targeting GPUs, MC/DC uses the Harmonize library as its GPU runtime, a.k.a. the thing that actually executes MC/DC functions. Harmonize provides an event scheduler similar to those implemented in OpenMC and Shift, along with a novel asynchronous scheduler. For more information on Harmonize and how we compile MC/DC with it, see this TOMACs article describing the async scheduler or our publications in American Nuclear Society: Math and Comp Meeting in 2025.

If you encounter configuration problems, please file a GitHub issue, especially when using supported supercomputers such as LLNL’s Tioga, El Capitan, or Lassen.

Nvidia GPUs

To compile and execute MC/DC on Nvidia GPUs, first satisfy the Harmonize prerequisites (CUDA 11.8 and Numba 0.61 or newer).

  1. Clone the harmonize repo: git clone https://github.com/CEMeNT-PSAAP/harmonize.git

  2. Install into the proper Python env: pip install -e .

Operability should now be enabled.

AMD GPUs

The prerequisites for AMD operability require a Numba patch that enables the AMD target triple in LLVM IR. It is recommended that this is done within a Python venv virtual environment.

To compile and execute MC/DC on AMD GPUs, first satisfy the Harmonize prerequisites (ROCm 6.0.0 and Numba 0.61 or newer).

  1. Patch Numba to enable HIP (instructions here)

  2. Clone harmonize and switch to the AMD branch with git switch amd_event_interop_revamp

  3. Install Harmonize with pip install -e . or using Harmonize’s install script

Operability should now be enabled.