mcdc


Namemcdc JSON
Version 0.10.0 PyPI version JSON
download
home_pageNone
SummaryMonte Carlo / Dynamic Code, a pure python high performance Monte Carlo neutronics package
upload_time2024-06-11 19:32:05
maintainerNone
docs_urlNone
authorCaleb Shaw, Rohan Pankaj, Alexander Mote, Ethan Lame, Benjamin Whewell, Ryan G. McClarren, Todd S. Palmer, Lizhong Chen, Dmitriy Y. Anistratov, C. T. Kelley, Camille J. Palmer, Kyle E. Niemeyer
requires_python>=3.9.1
licenseBSD 3-Clause License Copyright (c) 2021, CEMeNT All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
keywords gpu hpc monte carlo nuclear mpi4py neutron transport neutronics numba
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # MC/DC: Monte Carlo Dynamic Code

![mcdc_logo v1](https://user-images.githubusercontent.com/26186244/173467190-74d9b09a-ef7d-4f0e-8bdf-4a076de7c43c.svg)

[![Build](https://github.com/CEMeNT-PSAAP/MCDC/actions/workflows/mpi_numba_reg.yml/badge.svg)](https://github.com/CEMeNT-PSAAP/MCDC/actions/workflows/mpi_numba_reg.yml)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.06415/status.svg)](https://doi.org/10.21105/joss.06415)
[![ReadTheDocs](https://readthedocs.org/projects/mcdc/badge/?version=latest&style=flat)](https://mcdc.readthedocs.org/en/latest/ )
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)



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/)).

Our documentation on installation, contribution, and a brief user guide is on [Read the Docs](https://mcdc.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 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://mcdc.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 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:** On HPC systems in particular, `mpi4py` must be built using the system's existing `mpi` installation. Installing MC/DC using the [install script](https://mcdc.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

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://mcdc.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

MC/DC has a visualizer built from the [netgen package](https://ngsolve.org/). This is not included in the base install of MC/DC due to the size of the dependencies (~300MB). To install these dependencies use
```bash
pip install mcdc['viz']
```

## Running

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

To run a hypothetical input deck (for example this [slab wall problem](https://github.com/CEMeNT-PSAAP/MCDC/tree/main/examples/fixed_source/slab_absorbium)) in pure python mode run:

```bash
python input.py
```

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). 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 Numba mode:

```bash
python input.py --mode=numba
```

### Running in parallel

MC/DC supports parallel simulation via 
[MPI4Py](https://mpi4py.readthedocs.io/en/stable/). As an example, to run on 36 
processes in Numba mode with [SLURM](https://slurm.schedmd.com/documentation.html):

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

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 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](https://mcdc.readthedocs.io/en/latest/contribution.html).

## Bugs and 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 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
```
    @article{morgan2024mcdc,
        title = {Monte {Carlo} / {Dynamic} {Code} ({MC}/{DC}): {An} accelerated {Python} package for fully transient neutron transport and rapid methods development},
        author = {Morgan, Joanna Piper and Variansyah, Ilham and Pasmann, Samuel L. and Clements, Kayla B. and Cuneo, Braxton and Mote, Alexander and Goodman, Charles and Shaw, Caleb and Northrop, Jordan and Pankaj, Rohan and Lame, Ethan and Whewell, Benjamin and McClarren, Ryan G. and Palmer, Todd S. and Chen, Lizhong and Anistratov, Dmitriy Y. and Kelley, C. T. and Palmer, Camille J. and Niemeyer, Kyle E.},
        journal = {Journal of Open Source Software},
        volume = {9},
        number = {96},
        year = {2024},
        pages = {6415},
        url = {https://joss.theoj.org/papers/10.21105/joss.06415},
        doi = {10.21105/joss.06415},
    }
```
which should render something like this

Morgan et al. (2024). Monte Carlo / Dynamic Code (MC/DC): An accelerated Python package for fully transient neutron transport and rapid methods development. Journal of Open Source Software, 9(96), 6415. https://doi.org/10.21105/joss.06415.

## License

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

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "mcdc",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9.1",
    "maintainer_email": "Ilham Variansyah <variansi@oregonstate.edu>, Kayla Clements <clemekay@oregonstate.edu>, Joanna Piper Morgan <morgajoa@oregonstate.edu>, \"Kyle E. Niemeyer\" <kyle.niemeyer@oregonstate.edu>",
    "keywords": "GPU, HPC, Monte Carlo, Nuclear, mpi4py, neutron transport, neutronics, numba",
    "author": "Caleb Shaw, Rohan Pankaj, Alexander Mote, Ethan Lame, Benjamin Whewell, Ryan G. McClarren, Todd S. Palmer, Lizhong Chen, Dmitriy Y. Anistratov, C. T. Kelley, Camille J. Palmer, Kyle E. Niemeyer",
    "author_email": "Ilham Variansyah <variansi@oregonstate.edu>, Sam Pasmann <spasmann@nd.edu>, Joanna Morgan <morgajoa@oregonstate.edu>, Kayla Clements <clemekay@oregonstate.edu>, Braxton Cuneo <bcuneo@seattleu.edu>",
    "download_url": "https://files.pythonhosted.org/packages/f3/4d/65c1ad42f820b2387955676a02c94bb923f6a3412ff98e18447f4bb23e98/mcdc-0.10.0.tar.gz",
    "platform": null,
    "description": "# MC/DC: Monte Carlo Dynamic Code\n\n![mcdc_logo v1](https://user-images.githubusercontent.com/26186244/173467190-74d9b09a-ef7d-4f0e-8bdf-4a076de7c43c.svg)\n\n[![Build](https://github.com/CEMeNT-PSAAP/MCDC/actions/workflows/mpi_numba_reg.yml/badge.svg)](https://github.com/CEMeNT-PSAAP/MCDC/actions/workflows/mpi_numba_reg.yml)\n[![DOI](https://joss.theoj.org/papers/10.21105/joss.06415/status.svg)](https://doi.org/10.21105/joss.06415)\n[![ReadTheDocs](https://readthedocs.org/projects/mcdc/badge/?version=latest&style=flat)](https://mcdc.readthedocs.org/en/latest/ )\n[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\n\n\nMC/DC is a performant, scalable, and machine-portable Python-based Monte Carlo \nneutron transport software currently developed in the Center for Exascale Monte \nCarlo Neutron Transport ([CEMeNT](https://cement-psaap.github.io/)).\n\nOur documentation on installation, contribution, and a brief user guide is on [Read the Docs](https://mcdc.readthedocs.io/en/latest/).\n\n## Installation\n\nWe 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.\nThis avoids the need for admin access when installing MC/DC's dependencies and allows greater configurability for developers.\nFor most users working on a single machine of which they are administrators, MC/DC can be installed via pip:\n```bash\npip install mcdc\n```\nFor 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://mcdc.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.\n\n### Common issues with `mpi4py`\n\nThe `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:\n* **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;\n* **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`)\n* **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://mcdc.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.\n\n### Numba Config\n\nRunning 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://mcdc.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:\n1. Download the `patch.sh` file [here]() (If you've cloned MC/DC's GitHub repository, you already have this file in your MCDC/ directory).\n2. In your active conda environment, run `bash patch_numba.sh`.\n*If you manage your environment with conda, you will not need admin privileges*.\n\n### `visualizer` Config\n\nMC/DC has a visualizer built from the [netgen package](https://ngsolve.org/). This is not included in the base install of MC/DC due to the size of the dependencies (~300MB). To install these dependencies use\n```bash\npip install mcdc['viz']\n```\n\n## Running\n\nMC/DC can be executed in different modes: via pure python or via a `jit` compiled version (Numba mode). \nBoth modes have their use cases; in general, running in Numba mode is faster but more restrictive than via pure python.\n\n### Pure Python\n\nTo run a hypothetical input deck (for example this [slab wall problem](https://github.com/CEMeNT-PSAAP/MCDC/tree/main/examples/fixed_source/slab_absorbium)) in pure python mode run:\n\n```bash\npython input.py\n```\n\nSimulation output files are saved to the directory that contains `input.py`.\n\n### Numba mode\n\nMC/DC supports transport kernel acceleration via \n[Numba](https://numba.readthedocs.io/en/stable/index.html)'s Just-in-Time \ncompilation (currently only the CPU implementation). The *overhead* time for compilation\nwhen running in Numba mode is about 15 to 80 seconds, depending on the physics and features \nsimulated. Once compiled, the simulation runs **MUCH** faster than in \nPython mode.\n\nTo run in Numba mode:\n\n```bash\npython input.py --mode=numba\n```\n\n### Running in parallel\n\nMC/DC supports parallel simulation via \n[MPI4Py](https://mpi4py.readthedocs.io/en/stable/). As an example, to run on 36 \nprocesses in Numba mode with [SLURM](https://slurm.schedmd.com/documentation.html):\n\n```bash\nsrun -n 36 python input.py --mode=numba\n```\n\nFor systems that do not use SLURM (*i.e.*, a local system) try `mpiexec` or `mpirun` in its stead.\n\n## Contributions\n\nWe welcome any contributions to this code base.\nPlease keep in mind that we do take our [code of conduct](https://github.com/CEMeNT-PSAAP/MCDC/blob/main/CODE_OF_CONDUCT.md) seriously.\nOur 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](https://mcdc.readthedocs.io/en/latest/contribution.html).\n\n## Bugs and Issues\n\nOur documentation is in the early stages of development, so thank you for bearing with us while we bring it up to snuff.\nIf 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).\n\n## Testing\n\nMC/DC uses continuous integration (CI) to run its unit and regression test suite. \nMC/DC also includes verification and performance tests, which are built and run nightly on internal systems.\nYou can find specifics on how to run these tests locally [here](https://github.com/CEMeNT-PSAAP/MCDC/tree/main/test/regression).\n\n## Cite\n\nTo provide proper attribution to MC/DC, please cite\n```\n    @article{morgan2024mcdc,\n        title = {Monte {Carlo} / {Dynamic} {Code} ({MC}/{DC}): {An} accelerated {Python} package for fully transient neutron transport and rapid methods development},\n        author = {Morgan, Joanna Piper and Variansyah, Ilham and Pasmann, Samuel L. and Clements, Kayla B. and Cuneo, Braxton and Mote, Alexander and Goodman, Charles and Shaw, Caleb and Northrop, Jordan and Pankaj, Rohan and Lame, Ethan and Whewell, Benjamin and McClarren, Ryan G. and Palmer, Todd S. and Chen, Lizhong and Anistratov, Dmitriy Y. and Kelley, C. T. and Palmer, Camille J. and Niemeyer, Kyle E.},\n        journal = {Journal of Open Source Software},\n        volume = {9},\n        number = {96},\n        year = {2024},\n        pages = {6415},\n        url = {https://joss.theoj.org/papers/10.21105/joss.06415},\n        doi = {10.21105/joss.06415},\n    }\n```\nwhich should render something like this\n\nMorgan et al. (2024). Monte Carlo / Dynamic Code (MC/DC): An accelerated Python package for fully transient neutron transport and rapid methods development. Journal of Open Source Software, 9(96), 6415. https://doi.org/10.21105/joss.06415.\n\n## License\n\nMC/DC is licensed under a BSD-3 clause license. We believe in open source software.\n",
    "bugtrack_url": null,
    "license": "BSD 3-Clause License  Copyright (c) 2021, CEMeNT All rights reserved.  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
    "summary": "Monte Carlo / Dynamic Code, a pure python high performance Monte Carlo neutronics package",
    "version": "0.10.0",
    "project_urls": {
        "Documentation": "https://mcdc.readthedocs.io/en/latest/",
        "Homepage": "https://cement-psaap.github.io/",
        "Issues": "https://github.com/CEMeNT-PSAAP/MCDC/issues",
        "Repository": "https://github.com/CEMeNT-PSAAP/MCDC"
    },
    "split_keywords": [
        "gpu",
        " hpc",
        " monte carlo",
        " nuclear",
        " mpi4py",
        " neutron transport",
        " neutronics",
        " numba"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "e26905fde70f6c648383cc1ae699bdf7b4c51735ada68fff20962b7238281927",
                "md5": "9eeb03b40e9f2bfce8a7f385917fe69a",
                "sha256": "f601c2ac717806365bf6765d70df685db8e3b53b6c318b71d1fd1534ef46869b"
            },
            "downloads": -1,
            "filename": "mcdc-0.10.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9eeb03b40e9f2bfce8a7f385917fe69a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9.1",
            "size": 86112,
            "upload_time": "2024-06-11T19:32:03",
            "upload_time_iso_8601": "2024-06-11T19:32:03.539759Z",
            "url": "https://files.pythonhosted.org/packages/e2/69/05fde70f6c648383cc1ae699bdf7b4c51735ada68fff20962b7238281927/mcdc-0.10.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f34d65c1ad42f820b2387955676a02c94bb923f6a3412ff98e18447f4bb23e98",
                "md5": "5f014d07fafecb3f1d9f053143dcd477",
                "sha256": "ba48fb6227d90299f192030a8654a0f3ba26ce4ad0d240bacbe8b8eb4df6ff15"
            },
            "downloads": -1,
            "filename": "mcdc-0.10.0.tar.gz",
            "has_sig": false,
            "md5_digest": "5f014d07fafecb3f1d9f053143dcd477",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9.1",
            "size": 15840207,
            "upload_time": "2024-06-11T19:32:05",
            "upload_time_iso_8601": "2024-06-11T19:32:05.382478Z",
            "url": "https://files.pythonhosted.org/packages/f3/4d/65c1ad42f820b2387955676a02c94bb923f6a3412ff98e18447f4bb23e98/mcdc-0.10.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-06-11 19:32:05",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "CEMeNT-PSAAP",
    "github_project": "MCDC",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "mcdc"
}
        
Elapsed time: 0.31211s