From e680f2f73a105b289768af33623906f5d09771d8 Mon Sep 17 00:00:00 2001 From: Kayla Clements <43577305+clemekay@users.noreply.github.com> Date: Fri, 26 Jan 2024 12:26:07 -0800 Subject: [PATCH] Update README.md --- README.md | 55 +++++++++++++++++++++++++++---------------------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 8a832f73..df74dd10 100644 --- a/README.md +++ b/README.md @@ -12,31 +12,31 @@ 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](https://cement-psaap.github.io/)). -We have documentation on, installation, contribution and a brief user guide using [Read the Docs](https://cement-psaapgithubio.readthedocs.io/en/latest/) +Our documentation on installation, contribution, and a brief user guide is on [Read the Docs](https://cement-psaapgithubio.readthedocs.io/en/latest/). ## Installation We recommend using [`conda`](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) 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: +This avoids the need for admin access when installing MC/DC's dependencies and allows greater configurability for developers. +For most users working on a single machine of which they are administrators, MC/DC can be installed via pip: ```bash pip install mcdc ``` +For developers or users on HPC machines, we recommend that you *not* use the pip distribution and instead install MC/DC and its dependencies via the included [install script](https://cement-psaapgithubio.readthedocs.io/en/latest/install.html), which builds `mpi4py` from source and uses conda to manage your environment. *This is the most reliable way to install and configure MC/DC*. It also takes care of the [Numba patch]() and can configure the [continuous energy data library](), if you have access. ### 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: +The `pip mpi4py` distribution commonly has errors when building due to incompatible local MPI dependencies it builds off of. While pip does have some remedy for this, we recommend the following: * **Mac users:** we recommend `openmpi` is [installed via homebrew](https://formulae.brew.sh/formula/open-mpi) (note that more reliable mpi4py distribution can also be [found on homebrew](https://formulae.brew.sh/formula/mpi4py)), 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](https://cement-psaapgithubio.readthedocs.io/en/latest/install.html) 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. +* **HPC users and developers on any system:** On HPC systems in particular, `mpi4py` must be built using the system's existing `mpi` installation. Installing MC/DC using the [install script](https://cement-psaapgithubio.readthedocs.io/en/latest/install.html) we've included will handle that for you by installing dependencies using conda rather than pip. It also takes care of the [Numba patch]() and can configure the [continuous energy data library](), if you have access. ### Numba Config -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* +Running MC/DC performantly in [Numba mode](#numba-mode) requires a patch to a single Numba file. If you installed MC/DC with the [install script](https://cement-psaapgithubio.readthedocs.io/en/latest/install.html), this patch has already been taken care of. If you installed via pip, we have a patch script will make the necessary changes for you: +1. Download the `patch.sh` file [here]() (If you've cloned MC/DC's GitHub repository, you already have this file in your MCDC/ directory). +2. 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 @@ -47,9 +47,8 @@ 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. +MC/DC can be executed in different modes: via pure python or via a `jit` compiled version (Numba mode). +Both modes have their use cases; in general, running in Numba mode is faster but more restrictive than via pure python. ### Pure Python @@ -59,18 +58,18 @@ To run a hypothetical input deck (for example this [slab wall problem](https://g python input.py ``` -Simulation outputs will be placed in the same directory the `input.py` file is located in. +Simulation output files are saved to the directory that contains `input.py`. ### Numba mode MC/DC supports transport kernel acceleration via [Numba](https://numba.readthedocs.io/en/stable/index.html)'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 +compilation (currently only the CPU implementation). The *overhead* time for compilation +when running in Numba mode is about 15 to 80 seconds, depending on the physics and features +simulated. Once compiled, the simulation runs **MUCH** faster than in Python mode. -To run in the Numba mode: +To run in Numba mode: ```bash python input.py --mode=numba @@ -86,28 +85,28 @@ processes in Numba mode with [SLURM](https://slurm.schedmd.com/documentation.htm 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. +For systems that do not 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](https://github.com/CEMeNT-PSAAP/MCDC/blob/main/CODE_OF_CONDUCT.md) 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]() +Please keep in mind that we do take our [code of conduct](https://github.com/CEMeNT-PSAAP/MCDC/blob/main/CODE_OF_CONDUCT.md) seriously. +Our development structure is fork-based: a developer makes a personal fork of this repo, commits contributions to their personal fork, then opens a pull request when they're ready to merge their changes into the main code base. Their contributions 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](https://github.com/CEMeNT-PSAAP/MCDC/issues). +Our documentation is in the early stages of development, so thank you for bearing with us while we bring it up to snuff. +If you find a novel bug or anything else you feel we should be aware of, feel free to [open an issue](https://github.com/CEMeNT-PSAAP/MCDC/issues). ## 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. -See specifics on how to run these tests locally [here](https://github.com/CEMeNT-PSAAP/MCDC/tree/main/test/regression). +MC/DC uses continuous integration (CI) to run its unit and regression test suite. +MC/DC also includes verification and performance tests, which are built and run nightly on internal systems. +You can find specifics on how to run these tests locally [here](https://github.com/CEMeNT-PSAAP/MCDC/tree/main/test/regression). ## Cite -To provide proper attribution to MC/DC please 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}, @@ -124,4 +123,4 @@ Variansyah, Ilham, J. P. Morgan, K. E. Niemeyer, and R. G. McClarren. 2023. “D ## License -MC/DC is licensed under a BSD-3 clause license. We believe in open source software \ No newline at end of file +MC/DC is licensed under a BSD-3 clause license. We believe in open source software.