MontePy

MontePy: a Python library for reading, editing, and writing MCNP input files. - Published in JOSS (2025)

https://github.com/idaholab/montepy

Science Score: 100.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 8 DOI reference(s) in README and JOSS metadata
✓
Academic publication links
Links to: joss.theoj.org, zenodo.org
✓
Committers with academic emails
5 of 8 committers (62.5%) from academic institutions
✓
Institutional organization owner
Organization idaholab has institutional domain (inl.gov)
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

api mcnp mcnp6 monte-carlo neutronics radiation-transport

Keywords from Contributors

mesh

Scientific Fields

Engineering Computer Science - 32% confidence

Last synced: 6 months ago · JSON representation ·

Repository

MontePy is the most user friendly Python library (API) to read, edit, and write MCNP input files.

Basic Info

Host: GitHub
Owner: idaholab
License: mit
Language: Python
Default Branch: develop
Homepage: https://www.montepy.org/
Size: 8.64 MB

Statistics

Stars: 48
Watchers: 5
Forks: 15
Open Issues: 117
Releases: 37

Topics

api mcnp mcnp6 monte-carlo neutronics radiation-transport

Created about 2 years ago · Last pushed 6 months ago

Metadata Files

Readme Changelog Contributing License Code of conduct Citation Authors

MontePy

MontePY: a cute snek on a red over white circle

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.

User Documentation

MontePy has a website documenting how to work with MCNP in python with MontePy. 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).
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.)
Can quickly access cells, surfaces, and materials by their numbers. For example: cell = problem.cells[105].
Can quickly update cell parameters, such as importances. For example cell.importance.neutron = 2.0.
Can easily create universes, and fill other cells with 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 cellnum, importance in importances.items(): problem.cells[cellnum].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.writeproblem("fooupdate.imcnp") ```

For more examples see the getting started guide.

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) 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:

Improve performance for the intial loading of models.
Implement support for tallies.
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.

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:

The only other libraries that do utilize context-free parsing that we are aware of are: * MCNPy * 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.

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.

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 for more details. If you have any questions feel free to ask @micahgale.

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

Finally: make objects, not regexes!

Owner

Name: Idaho National Laboratory
Login: idaholab
Kind: organization
Email: cody.permann@inl.gov
Location: Idaho, US

Website: https://inl.gov
Repositories: 90
Profile: https://github.com/idaholab

Open Source Software From Idaho National Laboratory

JOSS Publication

MontePy: a Python library for reading, editing, and writing MCNP input files.

Published

April 09, 2025

DOI

10.21105/joss.07951

Volume 10, Issue 108, Page 7951

Authors

Micah D. Gale

Idaho National Laboratory, USA

Travis J. Labossiere-Hickman

Idaho National Laboratory, USA

Brenna A. Carbno
Idaho National Laboratory, USA

Andrew J. Bascom

Idaho National Laboratory, USA

Editor

Kelly Rowland

Citation (CITATION.cff)

cff-version: "1.2.0"
authors:
- family-names: Gale
  given-names: Micah D.
  orcid: "https://orcid.org/0000-0001-6451-4818"
- family-names: Labossiere-Hickman
  given-names: Travis J.
  orcid: "https://orcid.org/0000-0003-0742-3404"
- family-names: Carbno
  given-names: Brenna A.
- family-names: Bascom
  given-names: Andrew J.
  orcid: "https://orcid.org/0009-0005-6691-5128"
contact:
- family-names: Gale
  given-names: Micah D.
  orcid: "https://orcid.org/0000-0001-6451-4818"
doi: 10.5281/zenodo.15185507
message: If you use this software, please cite our article in the
  Journal of Open Source Software.
preferred-citation:
  authors:
  - family-names: Gale
    given-names: Micah D.
    orcid: "https://orcid.org/0000-0001-6451-4818"
  - family-names: Labossiere-Hickman
    given-names: Travis J.
    orcid: "https://orcid.org/0000-0003-0742-3404"
  - family-names: Carbno
    given-names: Brenna A.
  - family-names: Bascom
    given-names: Andrew J.
    orcid: "https://orcid.org/0009-0005-6691-5128"
  date-published: 2025-04-09
  doi: 10.21105/joss.07951
  issn: 2475-9066
  issue: 108
  journal: Journal of Open Source Software
  publisher:
    name: Open Journals
  start: 7951
  title: "MontePy: a Python library for reading, editing, and writing
    MCNP input files."
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.07951"
  volume: 10
title: "MontePy: a Python library for reading, editing, and writing MCNP
  input files."

GitHub Events

Total

Create event: 95
Release event: 13
Issues event: 194
Watch event: 14
Delete event: 77
Member event: 2
Issue comment event: 308
Push event: 691
Pull request review comment event: 323
Pull request event: 190
Pull request review event: 322
Fork event: 7

Last Year

Create event: 95
Release event: 13
Issues event: 196
Watch event: 14
Delete event: 77
Member event: 2
Issue comment event: 309
Push event: 691
Pull request review comment event: 323
Pull request event: 190
Pull request review event: 322
Fork event: 7

Committers

Last synced: 7 months ago

All Time

Total Commits: 4,040
Total Committers: 8
Avg Commits per committer: 505.0
Development Distribution Score (DDS): 0.062

Past Year

Commits: 1,370
Committers: 6
Avg Commits per committer: 228.333
Development Distribution Score (DDS): 0.132

Top Committers

Name	Email	Commits
Micah D. Gale	m**e@i**v	3,789
Travis J. Labossiere-Hickman	T**n@I**v	169
kordusas	b**s@g**m	57
Ferney, Paul Alexandre	p**y@i**v	11
Brenna A. Carbno	b**o@i**v	5
dependabot[bot]	4****]	3
Wendy Skinner	A**N@I**v	3
Brijeshthummar02	b**2@g**m	3

Committer Domains (Top 20 + Academic)

inl.gov: 5

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 362
Total pull requests: 360
Average time to close issues: 5 months
Average time to close pull requests: 10 days
Total issue authors: 10
Total pull request authors: 7
Average comments per issue: 2.75
Average comments per pull request: 1.57
Merged pull requests: 299
Bot issues: 0
Bot pull requests: 7

Past Year

Issues: 130
Pull requests: 224
Average time to close issues: 14 days
Average time to close pull requests: 9 days
Issue authors: 8
Pull request authors: 7
Average comments per issue: 0.57
Average comments per pull request: 1.29
Merged pull requests: 182
Bot issues: 0
Bot pull requests: 7

View more stats

Top Authors

Issue Authors

MicahGale (287)
tjlaboss (52)
SterlingButters (9)
dodu94 (6)
jpmorgan98 (2)
marco-de-pietri (2)
pferney05 (1)
AlphonseM91 (1)
yaohualiu (1)
kordusas (1)

Pull Request Authors

MicahGale (310)
tjlaboss (34)
dependabot[bot] (7)
kordusas (4)
pferney05 (2)
Brijeshthummar02 (2)
Vikranth3140 (1)

Top Labels

Issue Labels

feature request (142) bugs (106) documentation (54) code improvement (46) good first issue (42) CI/CD (33) gitlab merge request (31) alpha testing (27) parsers are hard (26) low priority (20) critical (16) mccafe ☕ (12) performance 🐌 (7) duplicate (5) lanl did something (3) enhancement (3) PyOpenSci / JOSS (3) question (2) github_actions (1) dependencies (1) nqa-1 sqa (1)

Pull Request Labels

bugs (131) documentation (121) CI/CD (84) code improvement (70) feature request (42) parsers are hard (34) alpha testing (32) critical (31) PyOpenSci / JOSS (16) performance 🐌 (12) dependencies (9) github_actions (9) low priority (8) enhancement (5)

Packages

Total packages: 1
Total downloads:
- pypi 457 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 28
Total maintainers: 1

pypi.org: montepy

A library for reading, editing, and writing MCNP input files

Homepage: https://www.montepy.org/
Documentation: https://www.montepy.org/
License: mit
Latest release: 1.1.2
published 7 months ago

Versions: 28
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 457 Last month

Rankings

Dependent packages count: 10.0%

Average: 38.2%

Dependent repos count: 66.3%

Maintainers (1)

mgale

Last synced: 6 months ago

Dependencies

.github/workflows/deploy.yml actions

actions/checkout v4 composite
actions/configure-pages v4 composite
actions/deploy-pages v4 composite
actions/download-artifact v4 composite
actions/setup-python v4 composite
actions/upload-pages-artifact v3 composite
pypa/gh-action-pypi-publish release/v1 composite

.github/workflows/main.yml actions

actions/checkout v4 composite
actions/setup-python v4 composite
actions/upload-artifact v3 composite

pyproject.toml pypi

numpy *
sly ==0.5

requirements/common.txt pypi

numpy >=1.18
sly >=0.5.0

requirements/dev.txt pypi

black ==23.3.0 development
build * development
coverage >=6.3.2 development
pytest * development
sphinx * development
sphinx_rtd_theme * development
sphinxcontrib-apidoc * development

MontePy

Science Score: 100.0%

Keywords

Keywords from Contributors

Scientific Fields

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

MontePy

Installing

User Documentation

Features

read in file

set photon importance for multiple cells

create a universe and fill another cell with it

add all cells with numbers between 1 and 4

fill cell 99 with universe 123

update all surfaces numbers by adding 1000 to them

all cells using these surfaces will be automatically updated as well

write out an updated file

Use Cases

Limitations

Current Development Priorities

Alternatives

Bugs, Requests and Development

Citation

Finally: make objects, not regexes!

Owner

JOSS Publication

MontePy: a Python library for reading, editing, and writing MCNP input files.

Authors

Editor

Tags

Citation (CITATION.cff)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: montepy

Rankings

Maintainers (1)

Dependencies