Package: mcdc
MC/DC: Monte Carlo Dynamic CodeMC/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 usingRead the DocsInstallationWe recommend usingcondaor 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:pipinstallmcdcCommon issues withmpi4pyThepip mpi4pydistribution 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 recommendopenmpiisinstalled via homebrew(note that more reliable mpi4py distribution can also befound on homebrew), alternatively you can usecondaif you don't have admin privileges;Linux users:we recommendopenmpiis 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 youdo not use the pip distributionand instead install MC/DC and its dependencies viainstall scriptswe've included that will buildmpi4pyfrom 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 theNumba patch, and can configure thecontinuous energy data libraryif you have access.Numba ConfigurationMC/DC requires Numba to be patched to be able to run performantly innumba mode. There is a very simple patch file that will make it automatically. To patch numbaDownload thepatch.shfilehere(If you cloned the git packa)Make sure you have bash installed if nessacary (macOS)In your active conda environment runbash patch_numba.shIf you manage your environment with conda you will not need admin privilegesvisualizerConfigMC/DC has a visualizer built from thenetgen package. This is not included in the base install of MC/DC due to the size of the dependencies (~300MB). To install these dependencies usepipinstallmcdc['viz']RunningMC/DC has many different modes you can run in.
A generous flexible pure python environment or ajitcompiled fast, but restrictive, mode.
Depending on your use case you will most likely favor one over the other.Pure PythonTo run a hypothetical input deck (for example thisslab wall problem) in pure python mode run:pythoninput.pySimulation outputs will be placed in the same directory theinput.pyfile is located in.Numba modeMC/DC supports transport kernel acceleration viaNumba's Just-in-Time
compilation (currently only the CPU implementation). Running in Numba mode takes
anoverheadof about 15 to 80 seconds depending on the physics/features
simulated; however, once compiled, the simulation runsMUCHfaster than the
Python mode.To run in the Numba mode:pythoninput.py--mode=numbaRunning in parallelMC/DC supports parallel simulation viaMPI4Py. As an example, to run on 36
processes in Numba mode withSLURM:srun-n36pythoninput.py--mode=numbaFor system that do no use SLURM (i.e. a local system) trympiexecormpirunin its stead.ContributionsWe welcome any contributions to this code base. Please keep in mind ourcode of conductthat 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 ourContribution guideBugs and IssuesOur 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 toopen an issue*We are not your HPC's admins. We can only do so muchTestingMC/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 locallygo here.CiteTo 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 thisVariansyah, 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.” InInternational Conference on Mathematics and Computational Methods Applied to Nuclear Science and Engineering, Niagara Falls, Ontario, Canada. DOI.10.48550/arXiv.2305.07636LicenseMC/DC is licensed under a BSD-3 clause license. We believe in open source software