From dd7354d408e9cd8e56441d061022af257e7aaffd Mon Sep 17 00:00:00 2001 From: "Micah D. Gale" Date: Wed, 16 Oct 2024 07:30:05 -0500 Subject: [PATCH 01/10] Added workflow status badge. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 97836508..7bfafb5d 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ [![Coverage Status](https://coveralls.io/repos/github/idaholab/MontePy/badge.svg?branch=develop)](https://coveralls.io/github/idaholab/MontePy?branch=develop) [![PyPI version](https://badge.fury.io/py/montepy.svg)](https://badge.fury.io/py/montepy) [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![Docs Deployment](https://github.com/idaholab/MontePy/actions/workflows/deploy.yml/badge.svg)](https://www.montepy.org/) MontePy is the most user friendly Python library for reading, editing, and writing MCNP input files. From c0e0403f289ff758c228c48936af30f737f34c82 Mon Sep 17 00:00:00 2001 From: Micah Gale Date: Wed, 16 Oct 2024 07:32:06 -0500 Subject: [PATCH 02/10] Update README.md Fixed workflow badge --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7bfafb5d..6a455495 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![Coverage Status](https://coveralls.io/repos/github/idaholab/MontePy/badge.svg?branch=develop)](https://coveralls.io/github/idaholab/MontePy?branch=develop) [![PyPI version](https://badge.fury.io/py/montepy.svg)](https://badge.fury.io/py/montepy) [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -[![Docs Deployment](https://github.com/idaholab/MontePy/actions/workflows/deploy.yml/badge.svg)](https://www.montepy.org/) +[![Docs Deployment](https://github.com/idaholab/MontePy/actions/workflows/deploy.yml/badge.svg?branch=main)](https://www.montepy.org/) MontePy is the most user friendly Python library for reading, editing, and writing MCNP input files. From 4089b1ad15b13d8648d89c25b2d2d28d0e345846 Mon Sep 17 00:00:00 2001 From: Micah Gale Date: Wed, 16 Oct 2024 07:40:44 -0500 Subject: [PATCH 03/10] Added python versions badge, and reorganized them --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6a455495..86fde99f 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,13 @@ [![license](https://img.shields.io/github/license/idaholab/MontePy.svg)](https://github.com/idaholab/MontePy/blob/develop/LICENSE) [![JOSS article status](https://joss.theoj.org/papers/e5b5dc8cea19605a1507dd4d420d5199/status.svg)](https://joss.theoj.org/papers/e5b5dc8cea19605a1507dd4d420d5199) [![Coverage Status](https://coveralls.io/repos/github/idaholab/MontePy/badge.svg?branch=develop)](https://coveralls.io/github/idaholab/MontePy?branch=develop) -[![PyPI version](https://badge.fury.io/py/montepy.svg)](https://badge.fury.io/py/montepy) [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) + + +[![PyPI version](https://badge.fury.io/py/montepy.svg)](https://badge.fury.io/py/montepy) [![Docs Deployment](https://github.com/idaholab/MontePy/actions/workflows/deploy.yml/badge.svg?branch=main)](https://www.montepy.org/) +[![PyPI pyversions](https://img.shields.io/pypi/pyversions/montepy.svg)](https://pypi.python.org/pypi/montepy/) + MontePy is the most user friendly Python library for reading, editing, and writing MCNP input files. From 093d5b501a71f7c36d3f3f0bd8db0a3491a5ed08 Mon Sep 17 00:00:00 2001 From: Micah Gale Date: Wed, 16 Oct 2024 08:00:51 -0500 Subject: [PATCH 04/10] Update README.md Added recommended citation for now. --- README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 86fde99f..42c71149 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![PyPI version](https://badge.fury.io/py/montepy.svg)](https://badge.fury.io/py/montepy) [![Docs Deployment](https://github.com/idaholab/MontePy/actions/workflows/deploy.yml/badge.svg?branch=main)](https://www.montepy.org/) -[![PyPI pyversions](https://img.shields.io/pypi/pyversions/montepy.svg)](https://pypi.python.org/pypi/montepy/) +[![PyPI pyversions](https://img.shields.io/pypi/pyversions/montepy.svg)](https://pypi.org/project/montepy/) MontePy is the most user friendly Python library for reading, editing, and writing MCNP input files. @@ -103,5 +103,15 @@ The system is very modular and you should be able to develop it pretty quickly. Read the [developer's guide](https://www.montepy.org/developing.html) for more details. If you have any questions feel free to ask [@micahgale](mailto:mgale@montepy.org). +## Citation + +For citing MontePy in a publication a [Journal of Open Source Software](https://joss.readthedocs.io/en/latest/) article is under review. +In the meantime there is a DOI for the software from [OSTI](https://osti.gov): [DOI:10.11578/dc.20240115.1](https://doi.org/10.11578/dc.20240115.1). + +You can cite MontePy as: + +> M. Gale, T. Labossiere-Hickman, B. Carbno, A. Bascom, and MontePy contributors, "MontePy", 2024, [doi: 10.11578/dc.20240115.1](https://doi.org/10.11578/dc.20240115.1). + + # Finally: make objects, not regexes! From a5e89ef0f8a42c29037b0dad3bcedb7032f1bb11 Mon Sep 17 00:00:00 2001 From: "Micah D. Gale" Date: Wed, 16 Oct 2024 08:45:03 -0500 Subject: [PATCH 05/10] Documented competitors. --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/README.md b/README.md index 42c71149..91d4b9fc 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,44 @@ Here a few of the known bugs and limitations: keyword-value pairs show up after the nuclide definitions. For example: * `M1 1001.80c 1.0 plib=80p` can be parsed. * `M1 plib=80p 1001.80c 1.0` cannot be parsed; despite it being a valid input. + +## Alternatives + +There are some python packages that offer some of the same features as MontePy, + but don't offer the same level of robustness, ease of installation, and user friendliness. + +For reading, editing, and writing input files there are: + +* [MCNP™y](https://github.rpi.edu/NuCoMP/mcnpy). MontePy differs by being: + * On PyPI, and can be installed via pip. + * Only requires a python interpreter, and not a Java virtual machine. + * Allowing contributions from anyone with a public GitHub account + +* [pyMCNP](https://github.com/FSIBT/PyMCNP). MontePy differs by: + * being on PyPI. + * Using a context-free parser that can understand cell geometry, and preserve user formatting. + * Supporting more edge cases of MCNP syntax (usually covered by foot notes in the manual). + +* [MCNP-Input-Reader](https://github.com/ENEA-Fusion-Neutronics/MCNP-Input-Reader). MontePy differs by: + * Being well documented + * Using a context-free parser. + * Being actively maintained. + +* [numjuggler](https://github.com/inr-kit/numjuggler). MontePy differs by: + * Using a context-free-parser. + * Focusing an object oriented user interface rather than trying to be a one-off command line utility. + * Being actively maintained. + +For only writing, or templating an input file there are also some great tools out there. +These packages don't provide the same functionality as MontePy inherently, + but could be the right tool for the job depending on the user's needs. + +* [Workflow and Template Toolkit for Simulation (WATTS)](https://github.com/watts-dev/watts) +* [Advanced Reactor Modeling Interface (ARMI)](https://github.com/terrapower/armi) + +Another honorable mention that doesn't replicate the features of MontePy, + but could be a great supplement to MontePy for defining materials, performing activations, etc. + is [PyNE --- the Nuclear Engineering Toolkit](https://pyne.io/). ## Bugs, Requests and Development From 02265e4513c45cb2d3988b75d3677d8ca204f97c Mon Sep 17 00:00:00 2001 From: "Micah D. Gale" Date: Thu, 17 Oct 2024 16:50:04 -0500 Subject: [PATCH 06/10] Updated example to work and be recognizable by doctest. --- README.md | 54 +++++++++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 91d4b9fc..a6f47f07 100644 --- a/README.md +++ b/README.md @@ -51,34 +51,34 @@ and the Python API documentation. Here is a quick example showing multiple tasks in MontePy: ```python -import montepy -# read in file -problem = montepy.read_input("foo.imcnp") +>>> import montepy +>>> # read in file +>>> problem = montepy.read_input("tests/inputs/test.imcnp") -# set photon importance for multiple cells -importances = {1: 0.005, - 2: 0.1, - 3: 1.0, - 99: 1.235 -} -for cell_num, importance in importances.items(): - problem.cells[cell_num].importance.photon = importance - -#create a universe and fill another cell with it -universe = montepy.Universe(123) -problem.univeres.append(universe) -# add all cells with numbers between 1 and 4 -universe.claim(problem.cells[1:5]) -# fill cell 99 with universe 123 -problem.cells[99].fill.universe = universe - -# update all surfaces numbers by adding 1000 to them -for surface in problem.surfaces: - surface.number += 1000 -# all cells using these surfaces will be automatically updated as well - -#write out an updated file -problem.write_problem("foo_update.imcnp") +>>> # set photon importance for multiple cells +>>> importances = {1: 0.005, +... 2: 0.1, +... 3: 1.0, +... 99: 1.235 +... } +>>> for cell_num, importance in importances.items(): +... problem.cells[cell_num].importance.photon = importance + +>>> #create a universe and fill another cell with it +>>> universe = montepy.Universe(123) +>>> problem.universes.append(universe) +>>> # add all cells with numbers between 1 and 4 +>>> universe.claim(problem.cells[1:5]) +>>> # fill cell 99 with universe 123 +>>> problem.cells[99].fill.universe = universe + +>>> # update all surfaces numbers by adding 1000 to them +>>> for surface in problem.surfaces: +... surface.number += 1000 +>>> # all cells using these surfaces will be automatically updated as well + +>>> #write out an updated file +>>> problem.write_problem("foo_update.imcnp") ``` From 468d4b8e39cfbf3dccae82195554b1dcf94b585b Mon Sep 17 00:00:00 2001 From: "Micah D. Gale" Date: Wed, 30 Oct 2024 14:04:53 -0500 Subject: [PATCH 07/10] Updated urls in contributing guide. --- CONTRIBUTING.md | 11 +++++------ README.md | 4 +--- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ed311628..499663d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,8 +12,8 @@ of Conduct](CODE_OF_CONDUCT.md). Please report any unacceptable behavior to mgal ## Resources - [GitHub Repository](https://github.com/idaholab/montepy) -- [Documentation](https://idaholab.github.io/MontePy/) -- [Developer's Guide](https://idaholab.github.io/MontePy/developing.html) +- [Documentation](https://www.montepy.org/) +- [Developer's Guide](https://www.montepy.org/developing.html) ## How to Report Bugs @@ -29,12 +29,11 @@ Please review the package philosophy to see if the feature would be a good fit. ## How to Submit Changes -All changes to OpenMC happen through pull requests. For a full overview of the -process, see the developer's guide section on [Contributing to -OpenMC](https://docs.openmc.org/en/latest/devguide/contributing.html). +All changes to MontePy happen through pull requests. For a full overview of the +process, see the developer's guide section on [MontePy's documentation](https://www.montepy.org/developing.html) ## Code Style Before you run off to make changes to the code, please review the [design -philosophy](https://idaholab.github.io/MontePy/developing.html#design-philosophy), +philosophy](https://www.montepy.org/developing.html#design-philosophy), and make sure to also use [black](https://black.readthedocs.io/en/stable/index.html). diff --git a/README.md b/README.md index a6f47f07..b4f6f3ca 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ and the Python API documentation. * Can quickly [access cells, surfaces, and materials by their numbers](https://www.montepy.org/starting.html#collections-are-accessible-by-number). For example: `cell = problem.cells[105]`. * Can quickly update cell parameters, [such as importances](https://www.montepy.org/starting.html#setting-cell-importances). For example `cell.importance.neutron = 2.0`. * Can easily [create universes, and fill other cells with universes](https://www.montepy.org/starting.html#universes). -* Currently has over 430 test cases. +* Currently has over 550 test cases. Here is a quick example showing multiple tasks in MontePy: @@ -80,8 +80,6 @@ Here is a quick example showing multiple tasks in MontePy: >>> #write out an updated file >>> problem.write_problem("foo_update.imcnp") -``` - ## Limitations Here a few of the known bugs and limitations: From e102ada8b9277f2d5185ca772a3813682c0faf83 Mon Sep 17 00:00:00 2001 From: "Micah D. Gale" Date: Wed, 30 Oct 2024 14:09:49 -0500 Subject: [PATCH 08/10] Simplified competition explenation. --- README.md | 37 ++++++++++++++++--------------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index b4f6f3ca..9496ee2b 100644 --- a/README.md +++ b/README.md @@ -98,27 +98,22 @@ Here a few of the known bugs and limitations: There are some python packages that offer some of the same features as MontePy, but don't offer the same level of robustness, ease of installation, and user friendliness. -For reading, editing, and writing input files there are: - -* [MCNP™y](https://github.rpi.edu/NuCoMP/mcnpy). MontePy differs by being: - * On PyPI, and can be installed via pip. - * Only requires a python interpreter, and not a Java virtual machine. - * Allowing contributions from anyone with a public GitHub account - -* [pyMCNP](https://github.com/FSIBT/PyMCNP). MontePy differs by: - * being on PyPI. - * Using a context-free parser that can understand cell geometry, and preserve user formatting. - * Supporting more edge cases of MCNP syntax (usually covered by foot notes in the manual). - -* [MCNP-Input-Reader](https://github.com/ENEA-Fusion-Neutronics/MCNP-Input-Reader). MontePy differs by: - * Being well documented - * Using a context-free parser. - * Being actively maintained. - -* [numjuggler](https://github.com/inr-kit/numjuggler). MontePy differs by: - * Using a context-free-parser. - * Focusing an object oriented user interface rather than trying to be a one-off command line utility. - * Being actively maintained. +Many of the competitors do not offer the robustness that MontePy does becuase, + they do not utilize context-free parsing (as of 2024). +These packages are: + +* [pyMCNP](https://github.com/FSIBT/PyMCNP) + +* [MCNP-Input-Reader](https://github.com/ENEA-Fusion-Neutronics/MCNP-Input-Reader) + +* [numjuggler](https://github.com/inr-kit/numjuggler) + +The only other library that does utilize context-free parsing that we are aware is +[MCNP™y](https://github.rpi.edu/NuCoMP/mcnpy). MontePy differs by being: +* On PyPI, and can be installed via pip. +* Only requires a python interpreter, and not a Java virtual machine. +* Allowing contributions from anyone with a public GitHub account + For only writing, or templating an input file there are also some great tools out there. These packages don't provide the same functionality as MontePy inherently, From b7d2145e55238891aff1564dc4703ebc73e6133e Mon Sep 17 00:00:00 2001 From: "Micah D. Gale" Date: Wed, 30 Oct 2024 14:10:44 -0500 Subject: [PATCH 09/10] fixed missing markdown. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 9496ee2b..5ee1a5e6 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,7 @@ Here is a quick example showing multiple tasks in MontePy: >>> #write out an updated file >>> problem.write_problem("foo_update.imcnp") +``` ## Limitations From ab309f034ef865e494a255f9af2e7e0d380d04c8 Mon Sep 17 00:00:00 2001 From: "Micah D. Gale" Date: Thu, 31 Oct 2024 07:45:57 -0500 Subject: [PATCH 10/10] Found workaround to doing interactive python mode. --- README.md | 54 +++++++++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 5ee1a5e6..95bd9412 100644 --- a/README.md +++ b/README.md @@ -51,34 +51,34 @@ and the Python API documentation. Here is a quick example showing multiple tasks in MontePy: ```python ->>> import montepy ->>> # read in file ->>> problem = montepy.read_input("tests/inputs/test.imcnp") +import montepy +# read in file +problem = montepy.read_input("tests/inputs/test.imcnp") ->>> # set photon importance for multiple cells ->>> importances = {1: 0.005, -... 2: 0.1, -... 3: 1.0, -... 99: 1.235 -... } ->>> for cell_num, importance in importances.items(): -... problem.cells[cell_num].importance.photon = importance - ->>> #create a universe and fill another cell with it ->>> universe = montepy.Universe(123) ->>> problem.universes.append(universe) ->>> # add all cells with numbers between 1 and 4 ->>> universe.claim(problem.cells[1:5]) ->>> # fill cell 99 with universe 123 ->>> problem.cells[99].fill.universe = universe - ->>> # update all surfaces numbers by adding 1000 to them ->>> for surface in problem.surfaces: -... surface.number += 1000 ->>> # all cells using these surfaces will be automatically updated as well - ->>> #write out an updated file ->>> problem.write_problem("foo_update.imcnp") +# set photon importance for multiple cells +importances = {1: 0.005, + 2: 0.1, + 3: 1.0, + 99: 1.235 +} +for cell_num, importance in importances.items(): + problem.cells[cell_num].importance.photon = importance + +#create a universe and fill another cell with it +universe = montepy.Universe(123) +problem.universes.append(universe) +# add all cells with numbers between 1 and 4 +universe.claim(problem.cells[1:5]) +# fill cell 99 with universe 123 +problem.cells[99].fill.universe = universe + +# update all surfaces numbers by adding 1000 to them +for surface in problem.surfaces: + surface.number += 1000 +# all cells using these surfaces will be automatically updated as well + +#write out an updated file +problem.write_problem("foo_update.imcnp") ``` ## Limitations