Merge pull request #202 from CEMeNT-PSAAP/dev

Version release 0.10.0

.github/workflows/draft-pdf.yml

@@ -1,4 +1,5 @@
-on: [push]
+name: Build JOSS paper, only on dispatch
+on: [workflow_dispatch]
 
 jobs:
   paper:

.github/workflows/manual_publish.yml

@@ -8,7 +8,10 @@
 
 # assumming this is being done in a repo with trusted publishing permissions in pypi
 
-name: Manually upload Python Package (if auto upload fails)
+# There is an automated runner which should upload a new PyPi package but it often fails due to API BS.
+# This is here so one doesn't have to republish everything
+
+name: manually publish pypi package (for touble shooting)
 
 on: workflow_dispatch
 

.github/workflows/verification_man_mpi_numba.yml

@@ -0,0 +1,35 @@
+name: Verification Tests (manual execution only)
+
+on: workflow_dispatch
+
+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: Verification Tests - Numba and MPI
+      run: |
+          cd test/verification/analytic
+          python run.py --mode=numba --mpiexec=2

.gitignore

@@ -13,6 +13,9 @@ __pycache__
 *.nbc
 *.nbi
 
+# GPU cache
+__ptxcache__
+
 # Editor
 .spyproject
 *.swp
@@ -51,3 +54,4 @@ pytestdebug.log
 docs/build
 docs/source/pythonapi/generated/
 
+*.csv

README.md

@@ -3,6 +3,7 @@
 ![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)
 
@@ -108,18 +109,21 @@ You can find specifics on how to run these tests locally [here](https://github.c
 
 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},
-}
+    @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
 
-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)
+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
 

docs/source/contribution.rst

@@ -10,6 +10,15 @@ Whether you are here to make a single PR and never return, or want to become a m
 We have regular developers meetings for any and all who are interested to discuss contributions to this code base.
 
 This describes the processes of contributing to MC/DC for both internal (CEMeNT) and external developers.
+We make contributions to the ``dev`` branch of MC/DC.
+To get started making alterations in a cloned repo
+
+#. fork ``CEMeNT-PSAAP/MCDC`` to your github account
+#. ``git clone git@github.com:<YOUR_GITHUB>/MCDC.git``
+#. ``git switch dev``
+#. run install script which will install MC/DC as an editable package from this directory
+
+Push some particles around!!!!
 
 Please note our `code of conduct <https://github.com/CEMeNT-PSAAP/MCDC/blob/main/CODE_OF_CONDUCT.md>`_ which we take seriously
 
@@ -88,6 +97,17 @@ Alteratively a developer could delete the ``__pycache__`` directory or other cac
 At some point MC/DC will enable `Numba's Ahead of Time compilation abilities <https://numba.readthedocs.io/en/stable/user/pycc.html>`_. But the core development team is holding off until scheduled `upgrades to AOT functionality in Numba are implemented <https://numba.readthedocs.io/en/stable/reference/deprecation.html#deprecation-numba-pycc>`_.
 However if absolutely required by users numba does allow for some `cache sharing <https://numba.readthedocs.io/en/stable/developer/caching.html>`_.
 
+------------------
+Adding a New Input
+------------------
+
+To add a new keyword argument such that a user can interface with it in an input deck 
+there are a few different places a dev will need to make alterations
+
+#. ``card.py`` (where the input cards are actually defined)
+#. ``type.py`` (where the type information of the inputs are strictly added)
+#. ``input_.py`` (where user inputs are merged with the specifications in ``card.py`` and ``type.py``)
+
 -------
 Testing
 -------
@@ -103,7 +123,7 @@ Our github based CI runs for,
 * linux-64 (x86)
 * osx-64 (x86, intel based macs)
 
-while we do not have continuos integration we have validated MC/DC on other systems.
+while we do not have continuous integration we have validated MC/DC on other systems.
 
 To run the regression tests locally, navigate to ``\MCDC\tests\regression`` and run,
 
@@ -141,7 +161,7 @@ Adding Documentation
 
 
 It's not everything it needs to be but we are trying!
-If your contribution changes the behavior of the input deck, instillation process, or testing infrastructure your contribution must include alteration to this documentaiton.
+If your contribution changes the behavior of the input deck, instillation process, or testing infrastructure your contribution must include alteration to this documentation.
 That can be done by editing the RST files in ``/MCDC/docs/source/<FILENAME>.rst``.
 
 To add a new page to the documentation,
@@ -164,6 +184,8 @@ Pull Requests
 
 MC/DC works off of a fork workflow in which contributors fork our repo, make alterations, and submit a pull requests.
 You should only submit a pull request once your code passes all tests, is properly linted, you have edited documentation (if necessary), and added any new tests (if needed).
+Open a PR to the ``dev`` branch in Github.
+MC/DC's main branch is only updated for version releases at which time a PR from dev to main is opened, tagged, archived, and published automatically.
 
 Within your pull request documentation please list:
 

docs/source/index.rst

@@ -83,7 +83,9 @@ A full exhaustive list of publications can be found on the `CEMeNT site <https:/
     install
     user
     contribution
+    theory/index
     pythonapi/index
+    pubs
 
 .. sidebar-links::
     :caption: Links
@@ -112,15 +114,32 @@ To build the docs
 To Cite MC/DC
 =============
 
-If you use or devlope in MC/DC and would like to publish your results
+If you use MC/DC and would like to provide proper attribution
 please cite our article in the Journal of Open Source software
 
-.. code-block:: 
-
+.. code-block:: bibtex
+        
     @article{morgan2024mcdc,
-        booktitle = {}
-        title = {},
-        author = {},
-        date = {},
-        doi = {},
+        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},
     }
+
+If you are developing or working with specific numerical methods please take greater care
+to cite the specific publications where that work is presented.
+An exhaustive list can be found on our :ref:`pubs` page.
+Also check out and even longer list of associated publications on our
+`center's publications page <https://cement-psaap.github.io/publications/>`_

docs/source/pubs.rst

@@ -0,0 +1,149 @@
+.. _pubs:
+
+=============
+Publications
+=============
+
+This page contains various formal publications describing the features and algorithms of MC/DC.
+If you are writing a research paper please provide proper attribution to those whose work you are using in MC/DC.
+Generally, the citation on the home page is a good place to start.
+
+General MC/DC Papers
+---------------------
+
+I. Variansyah, J. P. Morgan, J. Northrop K. E. Niemeyer, and 
+R. G. McClarren. “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 (2023). Preprint DOI 10.48550/arXiv.2305.13555.
+
+I. Variansyah and R. G. McClarren. “High-fidelity treatment for object
+movement in time-dependent Monte Carlo transport simulations.”
+In International Conference on Mathematics and Computational
+Methods Applied to Nuclear Science and Engineering. Niagara Falls,
+Ontario, Canada (2023). Preprint DOI 10.48550/arXiv.2305.07641.
+
+
+Population Control Publications
+--------------------------------
+
+I. Variansyah and R. G. McClarren. “An effective initial particle 
+sampling technique for Monte Carlo reactor transient simulations.” 
+In International Conference on Mathematics and Computational Methods 
+Applied to Nuclear Science and Engineering. Niagara Falls, Ontario, 
+Canada (2023). Preprint DOI 10.48550/arXiv.2305.07646.
+
+I. Variansyah and R. G. McClarren. “An effective initial particle sampling
+technique for Monte Carlo reactor transient simulations.” In International
+Conference on Physics of Reactors. Pittsburgh, Pennsylvania, USA (2022).
+
+I. Variansyah and R. G. McClarren. “Performance of Population Control
+Techniques in Monte Carlo Reactor Criticality Simulation.” In International
+Conference on Physics of Reactors. Pittsburgh, Pennsylvania, USA (2022).
+
+Software Engineering in MC/DC Publications
+-------------------------------------------
+
+J. P. Morgan, I. Variansyah, S. Pasmann, K. B. Clements, B. Cuneo, A. Mote, 
+C. Goodman, C. Shaw, J. Northrop, R. Pankaj, E. Lame, B. Whewell, 
+R. McClarren, T. S. Palmer, L. Chen, D. Anistratov, C. T. Kelley, 
+C. Palmer, and K. E. Niemeyer. Monte Carlo / Dynamic Code (MC/DC): 
+An accelerated Python package for fully transient neutron transport 
+and rapid methods development. Accepted Journal of Open Source Software. 
+9(96), 6415. DOI 10.21105/joss.06415.
+
+B. Cuneo and Mike Bailey. 2023. Divergence Reduction in Monte Carlo 
+Neutron Transport with On-GPU Asynchronous Scheduling. ACM Trans. 
+Model. Comput. Simul. (October 2023). DOI 10.1145/3626957.
+
+J. P. Morgan, T. S. Palmer, and K. E. Niemeyer. “Automatic Hardware Code Generation
+for Neutron Transport Applications.” In Transactions of the American Nuclear Society,
+volume 126, p. 318–320. American Nuclear Society, Anaheim, CA (2022)
+Preprint DOI: 10.5281/zenodo.6646813 DOI: 10.13182/T126-38137.
+
+UQ Publications
+---------------
+
+K. B. Clements, G. Geraci, A. J. Olson, and T. S. Palmer. 
+A variance deconvolution estimator for efficient uncertainty 
+quantification in Monte Carlo radiation transport applications. 
+Accepted Journal of Quantitative Spectroscopy and Radiative Transfer. 
+(2024). DOI 10.1016/j.jqsrt.2024.108958.
+
+K. B. Clements, G. Geraci, A. J. Olson, and T. S. Palmer. 
+“Global Sensitivity Analysis in Monte Carlo Radiation Transport.” 
+In International Conference on Mathematics and Computational Methods
+Applied to Nuclear Science and Engineering. Niagara Falls, Ontario, Canada (2023)
+
+K. B. Clements, G. Geraci, and A. J. Olson, A Variance Deconvolution Approach
+to Sampling Uncertainty Quantification for Monte Carlo Radiation Transport
+Solvers, in Computer Science Research Institute Summer Proceedings 2021,
+J.D. Smith and E. Galvan, eds., Technical Report SAND2022-0653R,
+Sandia National Laboratories, 2021, pp. 293–307. DOI: 10.2172/1855061.
+
+Hybrid Monte Carlo Publications
+-------------------------------
+
+B. Whewell, R. G. McClarren, C. D. Hauck & M. Shin “Multigroup Neutron Transport 
+Using a Collision-Based Hybrid Method”, Nuclear Science and Engineering, 
+197:7, 1386-1405, (2023) DOI: 10.1080/00295639.2022.2154119.
+
+E. Smith, I. Variansyah, and R. G. McClarren. 
+“Variable Dynamic Mode Decomposition for Estimating Time Eigenvalues
+in Nuclear Systems.” Nuclear Science and Engineering (2022). 
+DOI 10.1080/00295639.2022.2142025, Preprint.
+
+V. Novellino and D. Anistratov, Analysis of Hybrid MC/Deterministic Methods
+for Transport Problems Based on Low-Order Equations Discretized by
+Finite Volume Scheme. Transaction of American Nuclear Society, 
+v. 130, 2024 Preprint DOI: 10.48550/arXiv:2403.05673
+
+E. Smith, I. Variansyah, and R. G. McClarren. “Compressed Dynamic Mode Decomposition
+for Time-Eigenvalue Calculations.” In International Conference on Mathematics
+and Computational Methods Applied to Nuclear Science and Engineering.
+Niagara Falls, Ontario, Canada (2023). Preprint DOI 10.48550/arXiv.2208.10942.
+
+iQMC Publications
+-----------------
+
+S. Pasmann, I. Variansyah, C. T. Kelley, and R. G. McClarren. (2024). 
+Mitigating Spatial Error in the iterative-Quasi-Monte Carlo (iQMC) Method 
+for Neutron Transport Simulations with Linear Discontinuous Source Tilting 
+and Effective Scattering and Fission Rate Tallies. Accepted Nuclear Science 
+and Engineering. Preprint DOI 10.48550/arXiv.2401.04029
+
+S. Pasmann, I. Variansyah, C. T. Kelley, and R. G. McClarren. 
+“A Quasi-Monte Carlo Method with Krylov Linear Solvers for Multigroup 
+Neutron Transport Simulations.” Nuclear Science and Engineering (
+Jan 2023). DOI 10.1080/00295639.2022.2143704.
+
+S. Pasmann, I. Variansyah, C. T. Kelley, and R. G. McClarren.
+“iQMC: Iterative Quasi-Monte Carlo with Krylov Linear Solvers
+for k-Eigenvalue Neutron Transport Simulations.” In International
+Conference on Mathematics and Computational Methods Applied to
+Nuclear Science and Engineering. Niagara Falls, Ontario, Canada
+(2023). Preprint DOI: 0.48550/arXiv.2306.11600.
+
+S. Pasmann, I. Variansyah, and R. G. McClarren.
+“Convergent Transport Source Iteration Calculations
+with Quasi-Monte Carlo.” In Transactions of the American Nuclear Society,
+volume 124, pp. 192–195. American Nuclear Society (2021).
+
+Validation and Verification Publications
+----------------------------------------
+
+C. J. Palmer, J. Northrop, T. S. Palmer, A. J. Reynolds.
+Validation of Time-dependent Shift using the Pulsed Sphere
+Benchmarks. Frontiers in Nuclear Engineering,
+Sec. Fission and Reactor Design. Vol 2. (2023). DOI: 10.3389/fnuen.2023.1294583.
+
+J. Northrop, C. Palmer, and A. J. Reynolds. “Inter-code Comparison of Time Independent
+Pulsed Sphere Benchmark Results.” In Transactions of the American Nuclear Society,
+volume 126. p. 334-337 American Nuclear Society, Anaheim, CA (2022).
+Preprint DOI: 10.5281/zenodo.7250603 DOI 10.13182/T126-38312.
+
+A. J. Reynolds, & T. S. Palmer. Verification and Scaling of Time-Dependent
+Shift Using the AZURV1 Benchmark. In Transactions of the
+American Nuclear Society, volume 126. p. 310-313. Anaheim,
+California, United States (2020) Preprint DOI 10.5281/zenodo.7222601 DOI 10.13182/T126-38060.