# MontePy
<img src="https://raw.githubusercontent.com/idaholab/MontePy/develop/graphics/monty.svg" width="180" alt="MontePY: a cute snek on a red over white circle"/>
[](https://github.com/idaholab/MontePy/blob/develop/LICENSE)
[](https://joss.theoj.org/papers/e5b5dc8cea19605a1507dd4d420d5199)
[](https://github.com/pyOpenSci/software-review/issues/205)
[](https://www.repostatus.org/#active)
[](https://coveralls.io/github/idaholab/MontePy?branch=develop)
[](https://github.com/idaholab/MontePy/actions/workflows/main.yml?query=branch%3Adevelop)
[](https://www.montepy.org/)
[](https://badge.fury.io/py/montepy)
[](https://anaconda.org/conda-forge/montepy)
[](https://pypi.org/project/montepy/)
[](https://doi.org/10.5281/zenodo.15185506)
MontePy is the most user-friendly Python library for reading, editing, and writing MCNP input files.
## Installing
Simply run:
```
pip install montepy
```
For more complicated setups
see the [Installing section in the user guide](https://www.montepy.org/en/stable/starting.html#installing).
## User Documentation
MontePy has a website [documenting how to work with MCNP in python with MontePy](https://www.montepy.org/).
The website contains a user's guide for getting started,
a developer's guide covering the design and approach of MontePy,
instructions for contributing,
and the Python API documentation.
## Features
* Handles almost all MCNP input syntax.
* Parses Cells, Surfaces, Materials, and Transforms very well.
* Can parse all surface types except macrobody facets ([Issue #354](https://github.com/idaholab/MontePy/issues/354)).
* Can read and write out all other MCNP inputs, even if it does not understand them .
* Attempts to write out the MCNP problem verbatim, even matching the original user formatting. (See some of the [open issues](https://github.com/idaholab/MontePy/issues).)
* Can quickly [access cells, surfaces, and materials by their numbers](https://www.montepy.org/en/stable/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/en/stable/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/en/stable/starting.html#universes).
* Currently has over 800 test cases.
Here is a quick example showing multiple tasks in MontePy:
```python
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")
```
For more examples see the [getting started guide](https://www.montepy.org/en/stable/starting.html).
### Use Cases
Here are some possible use cases for MontePy:
* Automated updating of an MCNP input file, or MCNP deck, for reactor reconfiguration, fuel shuffling, etc.
* Parameterizing an MCNP input file to check for explore the parametric space of your MCNP modeling problem
* Updating an MCNP model with the results from another code, such as depletion results from ORIGEN.
* To convert an MCNP model to another Monte Carlo code like OpenMC, SERPENT, etc.
## Limitations
Here a few of the known bugs and limitations:
* Cannot handle vertical input mode.
* Does not support editing tallies in a user-friendly way.
* Does not support editing source definition in a user-friendly way.
* Cannot parse all valid material definitions. There is a known bug ([#182](https://github.com/idaholab/MontePy/issues/182)) that MontePy can only parse materials where all
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.
## Current Development Priorities
Here are the rough development priorities for adding new features to MontePy:
1. Improve performance for the intial loading of models.
2. Implement support for tallies.
1. Implement support for source definitions.
If you have a specific feature priority that you would be willing to collaborate on you can open an issue or email us at [mgale@montepy.org](mailto:mgale@montepy.org).
## 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.
Many of the competitors do not offer the robustness that MontePy does because,
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 libraries that do utilize context-free parsing that we are aware of are:
* [MCNPy](https://github.rpi.edu/NuCoMP/mcnpy)
* [mckit](https://github.com/MC-kit/mckit)
MontePy differs from MCNPy by being:
* On PyPI and conda-forge, and able to be installed via `pip` or `conda`
* Only requiring a Python interpreter and not a Java virtual machine
* Allowing contributions from anyone with a public GitHub account
MontePy differs from mckit by being:
* Thoroughly documented
* Object-oriented
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
So MontePy doesn't do what you want?
Add an issue here with the "feature request" tag.
The system is very modular and you should be able to develop it pretty quickly.
Read the [developer's guide](https://www.montepy.org/en/stable/developing.html) for more details.
If you have any questions feel free to ask [@micahgale](mailto:mgale@montepy.org).
## Citation
You can cite MontePy as:
> Gale et al., (2025). MontePy: a Python library for reading, editing, and writing MCNP input files. Journal of Open Source Software, 10(108), 7951, [https://doi.org/10.21105/joss.07951](https://doi.org/10.21105/joss.07951)
# Finally: make objects, not regexes!
Raw data
{
"_id": null,
"home_page": null,
"name": "montepy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Micah Gale <mgale@montepy.org>",
"keywords": "MCNP, neutronics, imcnp, input file, monte carlo, radiation transport",
"author": null,
"author_email": "Micah Gale <mgale@montepy.org>, Travis Labossiere-Hickman <Travis.LabossiereHickman@inl.gov>, Brenna Carbno <brenna.carbno@inl.gov>, Benjaminas Marcinkevicius <BenjaminasDev@outlook.com>, Paul Ferney <Paul.Ferney@inl.gov>",
"download_url": "https://files.pythonhosted.org/packages/0a/09/907a99ff61d0737f410a38675aa9af13a350adda863873998822355e71e6/montepy-1.1.2.tar.gz",
"platform": null,
"description": "# MontePy\n\n<img src=\"https://raw.githubusercontent.com/idaholab/MontePy/develop/graphics/monty.svg\" width=\"180\" alt=\"MontePY: a cute snek on a red over white circle\"/>\n\n[](https://github.com/idaholab/MontePy/blob/develop/LICENSE)\n[](https://joss.theoj.org/papers/e5b5dc8cea19605a1507dd4d420d5199)\n[](https://github.com/pyOpenSci/software-review/issues/205)\n[](https://www.repostatus.org/#active)\n\n\n[](https://coveralls.io/github/idaholab/MontePy?branch=develop)\n[](https://github.com/idaholab/MontePy/actions/workflows/main.yml?query=branch%3Adevelop)\n[](https://www.montepy.org/)\n\n[](https://badge.fury.io/py/montepy)\n[](https://anaconda.org/conda-forge/montepy)\n[](https://pypi.org/project/montepy/)\n\n[](https://doi.org/10.5281/zenodo.15185506)\n\nMontePy is the most user-friendly Python library for reading, editing, and writing MCNP input files. \n\n## Installing\n\nSimply run:\n\n```\npip install montepy\n```\n\nFor more complicated setups\nsee the [Installing section in the user guide](https://www.montepy.org/en/stable/starting.html#installing).\n\n\n## User Documentation\n\nMontePy has a website [documenting how to work with MCNP in python with MontePy](https://www.montepy.org/). \nThe website contains a user's guide for getting started, \na developer's guide covering the design and approach of MontePy,\ninstructions for contributing, \nand the Python API documentation.\n\n## Features\n\t\n* Handles almost all MCNP input syntax.\n* Parses Cells, Surfaces, Materials, and Transforms very well.\t\n* Can parse all surface types except macrobody facets ([Issue #354](https://github.com/idaholab/MontePy/issues/354)).\n* Can read and write out all other MCNP inputs, even if it does not understand them\t.\n* Attempts to write out the MCNP problem verbatim, even matching the original user formatting. (See some of the [open issues](https://github.com/idaholab/MontePy/issues).)\n* Can quickly [access cells, surfaces, and materials by their numbers](https://www.montepy.org/en/stable/starting.html#collections-are-accessible-by-number). For example: `cell = problem.cells[105]`.\n* Can quickly update cell parameters, [such as importances](https://www.montepy.org/en/stable/starting.html#setting-cell-importances). For example `cell.importance.neutron = 2.0`.\n* Can easily [create universes, and fill other cells with universes](https://www.montepy.org/en/stable/starting.html#universes).\n* Currently has over 800 test cases.\n\n \nHere is a quick example showing multiple tasks in MontePy:\n\n\n```python\nimport montepy\n# read in file\nproblem = montepy.read_input(\"tests/inputs/test.imcnp\")\n \n# set photon importance for multiple cells\nimportances = {1: 0.005,\n 2: 0.1,\n 3: 1.0,\n 99: 1.235\n}\nfor cell_num, importance in importances.items():\n problem.cells[cell_num].importance.photon = importance\n\n#create a universe and fill another cell with it\nuniverse = montepy.Universe(123)\nproblem.universes.append(universe)\n# add all cells with numbers between 1 and 4\nuniverse.claim(problem.cells[1:5])\n# fill cell 99 with universe 123\nproblem.cells[99].fill.universe = universe\n\n# update all surfaces numbers by adding 1000 to them\nfor surface in problem.surfaces:\n surface.number += 1000\n# all cells using these surfaces will be automatically updated as well\n\n#write out an updated file\nproblem.write_problem(\"foo_update.imcnp\")\n```\n\nFor more examples see the [getting started guide](https://www.montepy.org/en/stable/starting.html).\n\n### Use Cases\n\nHere are some possible use cases for MontePy:\n\n* Automated updating of an MCNP input file, or MCNP deck, for reactor reconfiguration, fuel shuffling, etc.\n* Parameterizing an MCNP input file to check for explore the parametric space of your MCNP modeling problem\n* Updating an MCNP model with the results from another code, such as depletion results from ORIGEN.\n* To convert an MCNP model to another Monte Carlo code like OpenMC, SERPENT, etc. \n\n\n## Limitations\n\nHere a few of the known bugs and limitations:\n\n\t\n* Cannot handle vertical input mode.\n* Does not support editing tallies in a user-friendly way.\n* Does not support editing source definition in a user-friendly way.\n* Cannot parse all valid material definitions. There is a known bug ([#182](https://github.com/idaholab/MontePy/issues/182)) that MontePy can only parse materials where all\n keyword-value pairs show up after the nuclide definitions. For example:\n * `M1 1001.80c 1.0 plib=80p` can be parsed.\n * `M1 plib=80p 1001.80c 1.0` cannot be parsed; despite it being a valid input.\n\n## Current Development Priorities\n\nHere are the rough development priorities for adding new features to MontePy:\n\n1. Improve performance for the intial loading of models.\n2. Implement support for tallies.\n1. Implement support for source definitions.\n\nIf you have a specific feature priority that you would be willing to collaborate on you can open an issue or email us at [mgale@montepy.org](mailto:mgale@montepy.org). \n\n## Alternatives\n\nThere are some python packages that offer some of the same features as MontePy,\n but don't offer the same level of robustness, ease of installation, and user friendliness.\n\n\nMany of the competitors do not offer the robustness that MontePy does because,\n they do not utilize context-free parsing (as of 2024). \nThese packages are:\n\n* [pyMCNP](https://github.com/FSIBT/PyMCNP)\n\n* [MCNP-Input-Reader](https://github.com/ENEA-Fusion-Neutronics/MCNP-Input-Reader)\n\n* [numjuggler](https://github.com/inr-kit/numjuggler)\n\nThe only other libraries that do utilize context-free parsing that we are aware of are:\n* [MCNPy](https://github.rpi.edu/NuCoMP/mcnpy)\n* [mckit](https://github.com/MC-kit/mckit) \n\nMontePy differs from MCNPy by being:\n\n* On PyPI and conda-forge, and able to be installed via `pip` or `conda`\n* Only requiring a Python interpreter and not a Java virtual machine\n* Allowing contributions from anyone with a public GitHub account\n\nMontePy differs from mckit by being:\n* Thoroughly documented\n* Object-oriented \n\n\nFor only writing, or templating an input file there are also some great tools out there. \nThese packages don't provide the same functionality as MontePy inherently,\n but could be the right tool for the job depending on the user's needs.\n\n* [Workflow and Template Toolkit for Simulation (WATTS)](https://github.com/watts-dev/watts)\n* [Advanced Reactor Modeling Interface (ARMI)](https://github.com/terrapower/armi)\n\nAnother honorable mention that doesn't replicate the features of MontePy,\n but could be a great supplement to MontePy for defining materials, performing activations, etc.\n is [PyNE --- the Nuclear Engineering Toolkit](https://pyne.io/).\n\t\n## Bugs, Requests and Development\n\nSo MontePy doesn't do what you want? \nAdd an issue here with the \"feature request\" tag. \nThe system is very modular and you should be able to develop it pretty quickly.\nRead the [developer's guide](https://www.montepy.org/en/stable/developing.html) for more details.\nIf you have any questions feel free to ask [@micahgale](mailto:mgale@montepy.org).\n\n## Citation\n\nYou can cite MontePy as:\n\n> Gale et al., (2025). MontePy: a Python library for reading, editing, and writing MCNP input files. Journal of Open Source Software, 10(108), 7951, [https://doi.org/10.21105/joss.07951](https://doi.org/10.21105/joss.07951)\n\n \n# Finally: make objects, not regexes!\n",
"bugtrack_url": null,
"license": null,
"summary": "A library for reading, editing, and writing MCNP input files",
"version": "1.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/idaholab/MontePy/issues",
"Changelog": "https://www.montepy.org/en/stable/changelog.html",
"Documentation": "https://www.montepy.org/",
"Homepage": "https://www.montepy.org/",
"Repository": "https://github.com/idaholab/MontePy.git"
},
"split_keywords": [
"mcnp",
" neutronics",
" imcnp",
" input file",
" monte carlo",
" radiation transport"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "765cd68087be245de584d0bd4d3aeb757c34f796b9eeafb8519a4a28510dfb29",
"md5": "4bb8c2ce2ab1812346842c5eac4c6048",
"sha256": "70230affda6ecedcf51306f27855586cce99fca699344e3406ffe1c0c258c23c"
},
"downloads": -1,
"filename": "montepy-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bb8c2ce2ab1812346842c5eac4c6048",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 171273,
"upload_time": "2025-08-02T20:58:05",
"upload_time_iso_8601": "2025-08-02T20:58:05.112383Z",
"url": "https://files.pythonhosted.org/packages/76/5c/d68087be245de584d0bd4d3aeb757c34f796b9eeafb8519a4a28510dfb29/montepy-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0a09907a99ff61d0737f410a38675aa9af13a350adda863873998822355e71e6",
"md5": "52d014c219e1a1bbb8587205b5d57e22",
"sha256": "478681e6b49b7ac02e3e857f1e9ede6eab4426e0b897e0d00136b11e00c589df"
},
"downloads": -1,
"filename": "montepy-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "52d014c219e1a1bbb8587205b5d57e22",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 240492,
"upload_time": "2025-08-02T20:58:06",
"upload_time_iso_8601": "2025-08-02T20:58:06.745947Z",
"url": "https://files.pythonhosted.org/packages/0a/09/907a99ff61d0737f410a38675aa9af13a350adda863873998822355e71e6/montepy-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 20:58:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "idaholab",
"github_project": "MontePy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "montepy"
}
JSON
