Run Examples in CI.

.github/workflows/main.yml

@@ -97,7 +97,7 @@ jobs:
 
 
 
-  doc-test:
+  doc-build:
     runs-on: ubuntu-latest
 
     steps:
@@ -126,6 +126,30 @@ jobs:
              make linkcheck
       - name: test sitemap
         run: python .github/scripts/check_sitemap.py 
+
+  doc-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: set up python 3.12
+        uses: actions/setup-python@v5
+        with: 
+          python-version: 3.12
+      - run: pip install . montepy[doc,build,demo-test,test]
+      - run: python -m phmutest README.md --replmode --log
+        name: Test readme code
+      - run: | 
+          cd doc
+          make doctest
+        name: Test all example code in documentation.
+      - run: |
+          cd demo
+          for file in *.ipynb; do papermill $file foo.ipynb; done
+        name: Test all demo notebooks 
 
   format-test:
     runs-on: ubuntu-latest

README.md

@@ -50,7 +50,8 @@ and the Python API documentation.
 
 Here is a quick example showing multiple tasks in MontePy:
 
-```python
+
+``` python
 import montepy
 # read in file
 problem = montepy.read_input("tests/inputs/test.imcnp")
@@ -99,6 +100,7 @@ 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.
 
+
 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:

demo/Pin_cell.ipynb

@@ -8,6 +8,7 @@
    "outputs": [],
    "source": [
     "import montepy\n",
+    "import os\n",
     "montepy.__version__"
    ]
   },
@@ -49,8 +50,7 @@
     "There's some issues\n",
     "==================\n",
     "\n",
-    "* Density was defined wrong\n",
-    "* Wrong cross section data were used."
+    "* Density was defined wrong"
    ]
   },
   {
@@ -76,31 +76,6 @@
     "    print(cell)"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "6b2ba1cc-65be-43ad-8999-5bc3f5b04968",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "material = problem.materials[1]\n",
-    "for material in problem.materials:\n",
-    "    for componenet in material.material_components:\n",
-    "        componenet.library = \"00c\""
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "f1c794a6-3926-4bbb-b82d-a2dab8d8f741",
-   "metadata": {
-    "scrolled": true
-   },
-   "outputs": [],
-   "source": [
-    "problem.materials"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "54111f69-8bcc-4c6b-9c34-81e4d615240e",
@@ -120,6 +95,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "#make folder\n",
+    "os.mkdir(\"parametric\")\n",
+    "\n",
     "fuel_wall = problem.surfaces[1]\n",
     "gap_wall = problem.surfaces[2]\n",
     "clad_wall = problem.surfaces[3]\n",
@@ -138,6 +116,14 @@
     "            plane.location = (pitch / 2) * (-1 if plane.location < 0 else 1)\n",
     "        problem.write_to_file(f\"parametric/pin_cell_{pin_radius}r_{pitch}p.imcnp\")"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9f75012f-d2bc-40c6-9167-08205c4a2395",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -156,7 +142,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

doc/foo.imcnp

@@ -0,0 +1 @@
+source/foo.imcnp

doc/source/conf.py

@@ -36,8 +36,10 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
+    "sphinx.ext.doctest",
     "sphinx_sitemap",
     "sphinx_favicon",
+    "sphinx_copybutton"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -52,7 +54,7 @@
 
 html_baseurl = "https://www.montepy.org/"
 sitemap_url_scheme = "{link}"
-html_extra_path = ["robots.txt"]
+html_extra_path = ["robots.txt", "foo.imcnp"]
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.

doc/source/developing.rst

@@ -6,10 +6,20 @@ The syntax layers handle the boring syntax things: like multi-line cards, and co
 The semantic layer takes this information and makes sense of it, like what the material number in a cell card is.
 
 .. note::
+
    Punchcards are dead.
    For this reason MontePy refrains from using antiquated terminology like "cards" and "decks".
    Instead MontePy refers to "inputs", and "files" or "problems". 
 
+.. note:: 
+   Demo code is based on `tests/inputs/test.imcnp`. 
+   You can load this with:
+
+    .. testcode::
+
+        import montepy
+        problem = montepy.read_input("tests/inputs/test.imcnp")
+
 Contributing
 ------------
 
@@ -97,7 +107,7 @@ Version information is stored in git tags,
 and retrieved using `setuptools scm <https://setuptools-scm.readthedocs.io/en/latest/>`_.
 The version tag shall match the regular expression:
 
-``v\d.\d+.\d+``.
+``v\d\.\d+\.\d+``.
 
 These tags will be applied by a maintainer during the release process,
 and cannot be applied by normal users.
@@ -309,6 +319,7 @@ and :func:`~montepy.input_parser.syntax_node.ValueNode.is_negatable_identifier`
 This will make it so that ``value`` always returns a positive value, and so :func:`~montepy.input_parser.syntax_node.ValueNode.is_negative` returns a boolean value.
 
 .. note::
+
    Setting :func:`~montepy.input_parser.syntax_node.ValueNode.is_negatable_identifier` to ``True`` 
    will convert the ValueNode to an integer ValueNode (via :func:`~montepy.input_parser.syntax_node.ValueNode._convert_to_int`).
 
@@ -336,14 +347,20 @@ This should include most if not all internal state information.
 
 See this example for :class:`~montepy.cell.Cell`
 
->>> str(cell)
-CELL: 2, mat: 2, DENS: 8.0 g/cm3
->>> repr(cell)
-CELL: 2
-MATERIAL: 2, ['iron']
-density: 8.0 atom/b-cm
-SURFACE: 1005, RCC
-
+.. doctest::
+   :skipif: True # skip because multi-line doc tests are kaputt
+
+    >>> cell = problem.cells[2]
+    >>> print(str(cell))
+    CELL: 2, mat: 2, DENS: 8.0 atom/b-cm
+    >>> print(repr(cell))
+    CELL: 2
+    MATERIAL: 2, ['iron']
+    density: 8.0 atom/b-cm
+    SURFACE: 1005, RCC
+    SURFACE: 1015, CZ
+    SURFACE: 1020, PZ
+    SURFACE: 1025, PZ
 
 Writing to File (Format for MCNP Input)
 """""""""""""""""""""""""""""""""""""""
@@ -426,7 +443,6 @@ For example the ``Surface`` number setter looks like:
         assert number > 0
         if self._problem:
             self._problem.surfaces.check_number(number)
-        self._mutated = True
         self._surface_number = number
 
 
@@ -524,7 +540,6 @@ For example the ``Surface`` number setter looks like::
         assert number > 0
         if self._problem:
             self._problem.surfaces.check_number(number)
-        self._mutated = True
         self._surface_number = number
 
 Data Cards that Modify Cells :class:`~montepy.data_inputs.cell_modifier.CellModifierInput`
@@ -727,14 +742,16 @@ For a ``Surface`` it is owned by the ``Surfaces`` collection owned by the ``MCNP
 A cell then borrows this object by referencing it in its own ``Surfaces`` collections. 
 For example:
 
->>> # owns
->>> x = Cell()
->>> hex(id(x))
-'0x7f4c6c89dc30'
->>> # borrows
->>> new_list = [x]
->>> hex(id(new_list[0]))
-'0x7f4c6c89dc30'
+.. doctest::
+
+    >>> import montepy
+    >>> # owns
+    >>> x = montepy.Cell()
+    >>> old_id = hex(id(x))
+    >>> # borrows
+    >>> new_list = [x]
+    >>> old_id == hex(id(new_list[0]))
+    True
 
 The general principle is that only one-directional pointers should be used,
 and bidirectional pointers should never be used.

doc/source/foo.imcnp

@@ -0,0 +1,14 @@
+Example Problem
+1 0  -1 2 -3
+2 0  -4 5 -6
+
+1 CZ 0.5
+2 PZ 0
+3 PZ 1.5
+4 CZ 0.500001
+5 PZ 1.5001
+6 PZ 2.0
+
+kcode 1.0 100 25 100
+TR1 0 0 1.0
+TR2 0 0 1.00001

doc/source/migrations/migrate0_1.rst

@@ -44,11 +44,69 @@ and will be removed in MontePy 1.0.0.
   isotopic, isomeric, or atomic data.
 
 
-New Interface
--------------
-Currently the replacement interface has not been fully designed yet.
-If you have input you can `join the discussion <https://github.com/idaholab/MontePy/discussions/475>`_.
-There will also be some alpha-testing announced in that discussion.
-
-Once MontePy 1.0.0 is released this will be updated with information about the new interface,
-and how to migrate to it.
+New Interface & Migration
+-------------------------
+
+.. note::
+
+        This design is not finalized and is subject to change.
+        This is the currently planned design for ``1.0.0a1``.
+        If you have input you can `join the discussion <https://github.com/idaholab/MontePy/discussions/475>`_.
+        This is also where alpha-testing will be announced.
+
+``material_components`` removal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Material composition data has moved from ``Material.material_components`` to the ``Material`` itself.
+``Material`` is now a list-like iterable.
+It is a list of tuples which are ``(nuclide, fraction)`` pairs.
+
+.. testcode::
+   :skipif: True # avoid running on < 1.0.0
+
+   >>> import montepy 
+   >>> problem = montepy.read_input("tests/inputs/test.imcnp")
+   >>> mat = problem.materials[1]
+   >>> mat[0]
+   (Nuclide('92235.80c'), 5)
+   >>> mat[1]
+   (Nuclide('92238.80c'), 95)
+
+Searching Components
+^^^^^^^^^^^^^^^^^^^^
+
+Finding a specific ``Nuclide`` in a ``Material`` is now much easier.
+First there will be a ``Material.find`` method that takes either a ``Nuclide`` string,
+or various over search criteria (e.g., ``element``),
+and creates a generator of all matching component tuples.
+
+If you want to check if a ``Material`` contains a specific ``Nuclide``
+you can simply test ``nuclide in material``.
+The ``Material.contains`` function will provide more options,
+such as setting a minimum threshold, and testing for multiple nuclides at once.
+
+Adding Nuclides
+^^^^^^^^^^^^^^^
+Adding a new nuclide will be easiest with the ``add_nuclide`` function.
+
+Editing Nuclide Compositon
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Editing a material composition will be very similar to editing a ``list``.
+Existing components can be set to a nuclide component nuclide.
+Also existing components can be deleted with ``del``. 
+
+
+``Isotope`` Deprecation and Removal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The decision was made to remove the name ``Isotope``.
+This is because not all material components are an isotope,
+they may be an isomer, or event an element.
+Rather the MCNP generalized terminology of ``Nuclide`` was adopted.
+The idea of a specific nuclide, e.g., ``H-1`` was separated from an
+MCNP material component e.g., ``1001.80c``. 
+The actual ``Nuclide`` information was moved to a new class: ``Nucleus``,
+that is immutable. 
+The ``Nuclide`` wraps this and adds a ``Library`` object to specify the nuclear data that is used.
+It makes sense to be able to change a library.
+It does not make sense to change the intrinsic properties of a nuclide (i.e., ``Z``, ``A``, etc.).