Merge pull request CEMeNT-PSAAP#149 from jpmorgan98/main

Documentation and Packaging update (Pre mc/dc 0.0.9)

.github/workflows/draft-pdf.yml

@@ -0,0 +1,23 @@
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: docs/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v1
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: docs/paper.pdf

.github/workflows/mpi_numba_reg.yml

@@ -1,4 +1,4 @@
-name: Regression Test - Numba and MPI
+name: Regression Test - Numba and MPI (2 threads)
 
 on: [push, pull_request]
 
@@ -23,7 +23,7 @@ jobs:
     - name: Install dependencies
       run: |
         #sudo apt-get install libopenmpi-dev
-        pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
+        #pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
         pip list 
         pip install -e .
     - name: Patch Numba
@@ -32,5 +32,4 @@ jobs:
     - name: Regression Test - Numba and MPI
       run: |
           cd test/regression
-          python run.py --mode=numba --mpiexec=4
           python run.py --mode=numba --mpiexec=2

.github/workflows/mpi_numba_regII.yml

@@ -0,0 +1,35 @@
+name: Regression Test - Numba and MPI (4 threads)
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+        fail-fast: false
+        matrix:
+            os: ["ubuntu-latest"] #, "macos-latest"
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up python 3.11
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.11"
+    - name: debug
+      run: |
+        pwd
+        ls
+    - uses: mpi4py/setup-mpi@v1
+    - name: Install dependencies
+      run: |
+        #sudo apt-get install libopenmpi-dev
+        #pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
+        pip list 
+        pip install -e .
+    - name: Patch Numba
+      run : |
+        bash .github/workflows/patch.sh
+    - name: Regression Test - Numba and MPI
+      run: |
+          cd test/regression
+          python run.py --mode=numba --mpiexec=2

.github/workflows/mpi_reg.yml

@@ -23,7 +23,7 @@ jobs:
     - name: Install dependencies
       run: |
         #sudo apt-get install libopenmpi-dev
-        pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
+        #pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
         pip list 
         pip install -e .
     - name: Patch Numba

.github/workflows/numba_reg.yml

@@ -23,7 +23,7 @@ jobs:
     - name: Install dependencies
       run: |
         #sudo apt-get install libopenmpi-dev
-        pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
+        #pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
         pip list 
         pip install -e .
     - name: Patch Numba

.github/workflows/python-publish.yml

@@ -0,0 +1,45 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+    release:
+      types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.11'
+    - uses: mpi4py/setup-mpi@v1
+    - name: Install dependencies
+      run: |
+        python --version
+        python -m pip install --upgrade pip
+        pip install .
+        pip install build
+    - name: Patch Numba
+      run : |
+        bash .github/workflows/patch.sh
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/python_reg.yml

@@ -23,7 +23,7 @@ jobs:
     - name: Install dependencies
       run: |
         #sudo apt-get install libopenmpi-dev
-        pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
+        #pip install numpy numba h5py matplotlib scipy pytest colorama mpi4py ngsolve distinctipy
         pip list 
         pip install -e .
     - name: Patch Numba

README.md

@@ -2,110 +2,74 @@
 
 ![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)
+[![ReadTheDocs](https://readthedocs.org/projects/cement-psaapgithubio/badge/?version=latest&style=flat)](https://cement-psaapgithubio.readthedocs.org/en/latest/ )
 [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
-[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-contributor%20covenant-green.svg)](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+
 
 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/)).
 
-*Please Note that this project is in the early stages of devlopment.* We welcome any and all collaborators, feel free to reach out via comments or submit a PR! Enjoy!
+Our documentation on installation, contribution, and a brief user guide is on [Read the Docs](https://cement-psaapgithubio.readthedocs.io/en/latest/).
 
 ## Installation
 
-In the root directory:
-
+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 -e .
+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.
 
-## Usage
-
-As an example, let us consider a simple time-dependent transport problem based 
-on the [AZURV1 benchmark](https://inis.iaea.org/search/search.aspx?orig_q=RN:41070601):
-
-```python
-import numpy as np
-
-import mcdc
-
-# =============================================================================
-# Set model
-# =============================================================================
-
-# Set materials
-m = mcdc.material(capture = np.array([1.0/3.0]),
-                  scatter = np.array([[1.0/3.0]]),
-                  fission = np.array([1.0/3.0]),
-                  nu_p    = np.array([2.3]),
-                  speed   = np.array([1.0]))
+### Common issues with `mpi4py`
 
-# Set surfaces
-s1 = mcdc.surface('plane-x', x=-1E10, bc="reflective")
-s2 = mcdc.surface('plane-x', x=1E10,  bc="reflective")
+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://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.
 
-# Set cells
-mcdc.cell([+s1, -s2], m)
+### Numba Config
 
-# =============================================================================
-# Set source
-# =============================================================================
+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*.
 
-mcdc.source(point=[0.0,0.0,0.0], isotropic=True)
+### `visualizer` Config
 
-# =============================================================================
-# Set tally, setting, and run mcdc
-# =============================================================================
+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']
+```
 
-# Tally
-mcdc.tally(scores=['flux'],
-           x=np.linspace(-20.5, 20.5, 202),
-           t=np.linspace(0.0, 20.0, 21))
+## Running
 
-# Setting
-mcdc.setting(N_particle=1E3)
+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.
 
-# Run
-mcdc.run()
-```
+### Pure Python
 
-If we save the input script above as `input.py`, we can run it as follows:
+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
 ```
 
-A more advanced input example that includes setting up multigroup (in energy and 
-delayed precursor) materials, lattice geometry, and continuous movements of 
-control rods is provided in `MCDC/example/c5g7/3d/TDX`.
-
-### Output
-
-MC/DC simulation results are stored in 
-[HDF5 format](https://www.hdfgroup.org/solutions/hdf5/), which can be processed 
-using [H5Py](https://www.h5py.org/) (default file name: `output.h5`) as follows:
-
-```python
-import h5py
-
-with h5py.File('output.h5', 'r') as f:
-    x      = f['tally/grid/x'][:]
-    t      = f['tally/grid/t'][:]
-    phi    = f['tally/flux/mean'][:]
-    phi_sd = f['tally/flux/sdev'][:]
-```
+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
@@ -120,3 +84,43 @@ processes in Numba mode with [SLURM](https://slurm.schedmd.com/documentation.htm
 ```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]().
+
+## 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
+```
+@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](https://doi.org/10.48550/arXiv.2305.07636)
+
+## License
+
+MC/DC is licensed under a BSD-3 clause license. We believe in open source software.

docs/README.md

@@ -0,0 +1,10 @@
+# MC/DC Documentation!
+
+To build these docs locally run the following:
+```bash 
+conda install sphinx==7.2.6
+pip install furo sphinx_toolbox
+make html
+```
+
+Then launch ``build/html/index.html`` with your browser of choice