MC/DC: Monte Carlo Dynamic Code

MC/DC is a performant, scalable, and machine-portable Python-based Monte Carlo neutron transport software currently developed in the Center for Exascale Monte Carlo Neutron Transport (CEMeNT).

We have documentation on, installation, contribution and a brief user guide using Read the Docs

Installation

We recommend using conda or some other environment manager to manage the MC/DC installation. This avoids the need for sudo access for MC/DC's dependencies and allows greater configurability for developers. For most users working on a single machine that they are administrators of MC/DC can be installed with:

pip install mcdc

Common issues with mpi4py

The pip mpi4py distribution commonly has errors when building due to incompatible local MPI dependencies it builds off of. While pip does have some reamdie for this we recommend the following:

• Mac users: we recommend openmpi is installed via homebrew (note that more reliable mpi4py distribution can also be found on homebrew), alternatively you can use conda if you don't have admin privileges;
• Linux users: we recommend openmpi is installed via a root package manager if possible (e.g. sudo apt install openmpi) or a conda distribution (e.g. conda install openmpi)
• HPC users and developers on any system: we recommend you do not use the pip distribution and instead install MC/DC and its dependencies via install scripts we've included that will build mpi4py from source and use conda to manage your environment. This is the most reliable way MC/DC can be installed and configured. It also takes care of the Numba patch, and can configure the continuous energy data library if you have access.

Numba Configuration

MC/DC requires Numba to be patched to be able to run performantly in numba mode. There is a very simple patch file that will make it automatically. To patch numba

1. Download the patch.sh file here (If you cloned the git packa)
2. Make sure you have bash installed if nessacary (macOS)
3. In your active conda environment run bash patch_numba.sh If you manage your environment with conda you will not need admin privileges

visualizer Config

MC/DC has a visualizer built from the netgen package. This is not included in the base install of MC/DC due to the size of the dependencies (~300MB). To install these dependencies use

pip install mcdc['viz']

Running

MC/DC has many different modes you can run in. A generous flexible pure python environment or a jit compiled fast, but restrictive, mode. Depending on your use case you will most likely favor one over the other.

Pure Python

To run a hypothetical input deck (for example this slab wall problem) in pure python mode run:

python input.py

Simulation outputs will be placed in the same directory the input.py file is located in.

Numba mode

MC/DC supports transport kernel acceleration via Numba's Just-in-Time compilation (currently only the CPU implementation). Running in Numba mode takes an overhead of about 15 to 80 seconds depending on the physics/features simulated; however, once compiled, the simulation runs MUCH faster than the Python mode.

To run in the Numba mode:

python input.py --mode=numba

Running in parallel

MC/DC supports parallel simulation via MPI4Py. As an example, to run on 36 processes in Numba mode with SLURM:

srun -n 36 python input.py --mode=numba

For system that do no use SLURM (i.e. a local system) try mpiexec or mpirun in its stead.

Contributions

We welcome any contributions to this code base. Please keep in mind our code of conduct that we do take seriously. We work off a forking development structure where you fork this repo, make contributions then open a pull request. That code will then be reviewed by the primary developers. For more information on how to do this see our Contribution guide

Bugs and Issues

Our documentation is in the early stages of development so bare with us while we bring that upto snuff. If you do feel that you have found a novel bug or we should be aware of feel free to open an issue *We are not your HPC's admins. We can only do so much

Testing

MC/DC uses CI to run it's unit and regression test suite. MC/DC also includes a verification and performance test that get ran on nightly builds on internal systems. For specifics on how to run these tests locally go here.

Cite

To provide proper attribution to MC/DC please cite,

@inproceedings{var_mc23_mcdc,
    Booktitle = {International Conference on Mathematics and Computational Methods Applied to Nuclear Science and Engineering},
    title = {Development of {MC/DC}: a performant, scalable, and portable Python-based {M}onte {C}arlo neutron transport code},
    year = {2023},
    author = {Ilham Variansyah and Joanna Piper Morgan and Kyle E. Niemeyer and Ryan G. McClarren},
    address = {Niagara Falls, Ontario, Canada},
    doi={10.48550/arXiv.2305.07636},
}

which should render something like this

Variansyah, Ilham, J. P. Morgan, K. E. Niemeyer, and R. G. McClarren. 2023. “Development of MC/DC: a performant, scalable, and portable Python-based Monte Carlo neutron transport code.” In International Conference on Mathematics and Computational Methods Applied to Nuclear Science and Engineering, Niagara Falls, Ontario, Canada. DOI. 10.48550/arXiv.2305.07636

License

MC/DC is licensed under a BSD-3 clause license. We believe in open source software