Merge pull request #647 from idaholab/646-address-review-coments-from-munkm

Address review comments from PyOpenSci

Author: MicahGale

README.md

@@ -4,13 +4,15 @@
 
 [![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)
 [![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)
 
 
+[![Coverage Status](https://coveralls.io/repos/github/idaholab/MontePy/badge.svg?branch=develop)](https://coveralls.io/github/idaholab/MontePy?branch=develop)
+[![Testing status](https://github.com/idaholab/MontePy/actions/workflows/main.yml/badge.svg?branch=develop)](https://github.com/idaholab/MontePy/actions/workflows/main.yml?query=branch%3Adevelop)
+[![Docs Deployment](https://github.com/idaholab/MontePy/actions/workflows/deploy.yml/badge.svg?branch=main)](https://www.montepy.org/)
+
 [![PyPI version](https://badge.fury.io/py/montepy.svg)](https://badge.fury.io/py/montepy)
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/montepy.svg)](https://anaconda.org/conda-forge/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.org/project/montepy/)
 
 
@@ -83,6 +85,8 @@ for surface in problem.surfaces:
 problem.write_problem("foo_update.imcnp")
 ```
 
+For more examples see the [getting started guide](https://www.montepy.org/en/stable/starting.html).
+
 ## Limitations
 
 Here a few of the known bugs and limitations:
@@ -96,13 +100,23 @@ Here a few of the known bugs and limitations:
    * `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:
+
+#. Redesign the `Material` interface to be more user friendly.
+#. 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](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 becuase,
+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:
 
@@ -112,12 +126,19 @@ These packages are:
 
 * [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:
+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 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
 
+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,

doc/source/starting.rst

@@ -46,6 +46,31 @@ System Wide (for the current user)
 #. Install it from `PyPI <https://pypi.org/project/montepy>`_ by running ``pip install montepy``. 
    You may need to run ``pip install --user montepy`` if you are not allowed to install the package.
 
+Installing Optional Dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MontePy offers multiple optional dependencies which some users may desire,
+though this is mostly intended for developers.
+Pip can install these through the following command:
+
+``pip install montepy[<extras>]``
+
+Where ``<extras>`` is one of the following options:
+
+#. ``demos``: installs the dependencies for running the demo problems in `jupyter <https://jupyter.org/>`_.
+
+#. ``doc``: installs the dependencies for building the website using `sphinx <https://www.sphinx-doc.org/en/master/>`_.
+
+#. ``build``: installs the dependencies for building the source distribution packages.
+
+#. ``format``: install the dependencies for formatting the code with `black <https://black.readthedocs.io/en/stable/index.html>`_. 
+
+#. ``test``: installs the dependencies for testing the software.
+
+#. ``demo-test``: installs the dependencies for testing the demos.
+
+#. ``develop``: installs everything a developer may need, specifically: ``montepy[test,doc,format,demo-test]``.
+
 Install specific version for a project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The best way maybe to setup a project-specific `conda <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_, 
@@ -401,18 +426,6 @@ So there is a convenient way to update a surface, but how do you easily get the
 For instance what if you want to shift a cell up in Z by 10 cm? 
 It would be horrible to have to get each surface by their number, and hoping you don't change the numbers along the way.
 
-One way you might think of is: oh let's just filter the surfaces by their type?:
-
-.. testcode::
-
-    for surface in cell.surfaces:
-        if surface.surface_type == montepy.surfaces.surface_type.SurfaceType.PZ:
-            surface.location += 10
-
-Wow that's rather verbose. 
-This was the only way to do this with the API for awhile.
-But MontePy 0.0.5 fixed this with: you guessed it: generators.
-
 The :class:`~montepy.surface_collection.Surfaces` collection has a generator for every type of surface in MCNP.
 These are very easy to find: they are just the lower case version of the 
 MCNP surface mnemonic. 
@@ -423,6 +436,53 @@ This previous code is much simpler now:
     for surface in cell.surfaces.pz:
         surface.location += 10
 
+Setting Boundary Conditions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As discussed in :manual63:`5.3.1` surfaces can have three boundary conditions:
+
+* Reflective boundary
+* White boundary
+* periodic boundary
+
+.. note::
+
+   Vacuum boundary conditions are the fourth type.
+   They are defined by cells with 0 importance though.
+
+The reflective and white boundary conditions are easiest to set as they are Boolean conditions.
+These are controlled by :func:`~montepy.surfaces.surface.Surface.is_reflecting` and 
+:func:`~montepy.surfaces.surface.Surface.is_white_boundary` respectively.
+For Example:
+
+.. testcode::
+
+   from montepy.surfaces.surface_type import SurfaceType
+
+   bottom = montepy.surfaces.axis_plane.AxisPlane()
+   bottom.surface_type = SurfaceType.PZ
+   bottom.is_reflecting = True
+
+   cyl = montepy.surfaces.cylinder_on_axis.CylinderOnAxis()
+   cyl.surface_type = SurfaceType.CZ
+   cyl.is_white_boundary = True
+
+
+Setting a periodic boundary is slightly more difficult. 
+In this case the boundary condition must be set to the other periodic surface with :func:`~montepy.surfaces.surface.Surface.periodic_surface`.
+So to continue with the previous example:
+
+.. testcode::
+
+   bottom.location = 0.0
+   bottom.is_reflecting = False
+
+   top = montepy.surfaces.axis_plane.AxisPlane()
+   top.surface_type = SurfaceType.PZ
+   top.location = 1.26
+
+   bottom.periodic_surface = top
+
 Cells 
 -----
 
@@ -592,19 +652,33 @@ Order of precedence and grouping is automatically handled by Python so you can e
 
 .. testcode::
 
+   import montepy.surfaces as surfs
+   from montepy.surfaces.surface_type import SurfaceType
+
    # build blank surfaces 
    bottom_plane = montepy.surfaces.axis_plane.AxisPlane()
+   bottom_plane.surface_type = SurfaceType.PZ
    bottom_plane.location = 0.0
+
    top_plane = montepy.surfaces.axis_plane.AxisPlane()
+   top_plane.surface_type = SurfaceType.PZ
    top_plane.location = 10.0
+
    fuel_cylinder = montepy.surfaces.cylinder_on_axis.CylinderOnAxis()
+   fuel_cylinder.surface_type = SurfaceType.CZ
    fuel_cylinder.radius = 1.26 / 2
+
    clad_cylinder = montepy.surfaces.cylinder_on_axis.CylinderOnAxis()
    clad_cylinder.radius = (1.26 / 2) + 1e-3 # fuel, gap, cladding
+   clad_cylinder.surface_type = SurfaceType.CZ
+
    clad_od = montepy.surfaces.cylinder_on_axis.CylinderOnAxis()
    clad_od.radius = clad_cylinder.radius + 0.1 # add thickness
+   clad_od.surface_type = SurfaceType.CZ
    other_fuel = montepy.surfaces.cylinder_on_axis.CylinderOnAxis()
    other_fuel.radius = 3.0
+   other_fuel.surface_type = SurfaceType.CZ
+
    bottom_plane.number = 1
    top_plane.number = 2
    fuel_cylinder.number = 3
@@ -850,13 +924,13 @@ If you want to try to troubleshoot errors in python you can do this with the fol
    This following guide may return an incomplete problem object that may break in very wierd ways.
    Never use this for actual file editing; only use it for troubleshooting.
 
-1. Setup a new Problem object:
+#. Setup a new Problem object:
 
    .. testcode::
 
        problem = montepy.MCNP_Problem("foo.imcnp") 
 
-1. Next load the input file with the ``check_input`` set to ``True``.
+#. Next load the input file with the ``check_input`` set to ``True``.
 
    .. testcode::
 

pyproject.toml

@@ -64,7 +64,7 @@ build = [
 	"setuptools-scm>=8",
 ]
 develop = [
-	"montepy[test,doc,format]",
+	"montepy[test,doc,format,demo-test]",
 ]
 demos = ["jupyter"]
 demo-test = ["montepy[demos]", "papermill"]