Added version change and added and clarified docs.

montepy/cell.py

@@ -1,4 +1,4 @@
-# Copyright 2024, Battelle Energy Alliance, LLC All Rights Reserved.
+# 2024, Battelle Energy Alliance, LLC All Rights Reserved.
 from __future__ import annotations
 
 import copy
@@ -571,8 +571,14 @@ def update_pointers(self, cells, materials, surfaces):
     def remove_duplicate_surfaces(self, deleting_dict):
         """Updates old surface numbers to prepare for deleting surfaces.
 
-        :param deleting_dict: a dict of the surfaces to delete.
-        :type deleting_dict: dict
+        .. versionchanged:: 1.0.0
+
+            The form of the deleting_dict was changed as :class:`~montepy.surfaces.Surface` is no longer hashable.
+
+        :param deleting_dict: a dict of the surfaces to delete, mapping the old surface to the new surface to replace it.
+            The keys are the number of the old surface. The values are a tuple
+            of the old surface, and then the new surface.
+        :type deleting_dict: dict[int, tuple[Surface, Surface]]
         """
         new_deleting_dict = {}
 

montepy/data_inputs/material.py

@@ -273,6 +273,10 @@ class Material(data_input.DataInputAbstract, Numbered_MCNP_Object):
             * :manual63:`5.6.1`
             * :manual62:`106`
 
+    .. versionchanged:: 1.0.0
+
+        This was the primary change for this release. For more details on what changed see :ref:`migrate 0 1`.
+
     :param input: the input that contains the data for this material
     :type input: Input
     """
@@ -382,6 +386,10 @@ def is_atom_fraction(self) -> bool:
         """
         If true this constituent is in atom fraction, not weight fraction.
 
+        .. versionchanged:: 1.0.0
+
+            This property is now settable.
+
         :rtype: bool
         """
         pass
@@ -428,6 +436,9 @@ def default_libraries(self):
 
             None
             00c
+
+        .. versionadded:: 1.0.0
+
         """
         pass
 
@@ -451,6 +462,8 @@ def get_nuclide_library(
             The final backup is that MCNP will use the first matching library in ``XSDIR``.
             Currently MontePy doesn't support reading an ``XSDIR`` file and so it will return none in this case.
 
+        .. versionadded:: 1.0.0
+
         :param nuclide: the nuclide to check.
         :type nuclide: Union[Nuclide, str]
         :param library_type: the LibraryType to check against.
@@ -610,6 +623,8 @@ def append(self, nuclide_frac_pair: tuple[Nuclide, float]):
         """
         Appends the tuple to this material.
 
+        .. versionadded:: 1.0.0
+
         :param nuclide_frac_pair: a tuple of the nuclide and the fraction to add.
         :type nuclide_frac_pair: tuple[Nuclide, float]
         """
@@ -630,6 +645,8 @@ def change_libraries(self, new_library: Union[str, Library]):
         """
         Change the library for all nuclides in the material.
 
+        .. versionadded:: 1.0.0
+
         :param new_library: the new library to set all Nuclides to use.
         :type new_library: Union[str, Library]
         """
@@ -646,6 +663,8 @@ def add_nuclide(self, nuclide: Union[Nuclide, str, int], fraction: float):
         """
         Add a new component to this material of the given nuclide, and fraction.
 
+        .. versionadded:: 1.0.0
+
         :param nuclide: The nuclide to add, which can be a string Identifier, or ZAID.
         :type nuclide: Nuclide, str, int
         :param fraction: the fraction of this component being added.
@@ -665,7 +684,7 @@ def add_nuclide(self, nuclide: Union[Nuclide, str, int], fraction: float):
 
     def contains(
         self,
-        nuclide: Nuclide,
+        nuclide: Union[Nuclide, Nucleus, Element, str, int],
         *args: Union[Nuclide, Nucleus, Element, str, int],
         threshold: float = 0.0,
     ) -> bool:
@@ -704,6 +723,7 @@ def contains(
 
             If a nuclide is in a material multiple times, and cumulatively exceeds the threshold,
             but for each instance it appears it is below the threshold this method will return False.
+        .. versionadded:: 1.0.0
 
         :param nuclide: the first nuclide to check for.
         :type nuclide: Union[Nuclide, Nucleus, Element, str, int]
@@ -779,6 +799,8 @@ def contains(
     def normalize(self):
         """
         Normalizes the components fractions so that they sum to 1.0.
+
+        .. versionadded:: 1.0.0
         """
         total_frac = sum(self.values)
         for _, val_node in self._components:
@@ -837,8 +859,9 @@ def values(self):
             0.6666666666666666
             0.026666666666666665
 
-        :rtype: Generator[float]
+        .. versionadded:: 1.0.0
 
+        :rtype: Generator[float]
         """
 
         def setter(old_val, new_val):
@@ -901,8 +924,9 @@ def nuclides(self):
 
                  Nuclide('O-16.00c')
 
-        :rtype: Generator[Nuclide]
+        .. versionadded:: 1.0.0
 
+        :rtype: Generator[Nuclide]
         """
 
         def setter(old_val, new_val):
@@ -1009,6 +1033,7 @@ def find(
             Get all ENDF/B-VIII.0
             [(2, (Nuclide('Pu-239.00c'), 0.1)), (3, (Nuclide('O-16.00c'), 0.1))]
 
+        .. versionadded:: 1.0.0
 
         :param name: The name to pass to Nuclide to search by a specific Nuclide. If an element name is passed this
             will only match elemental nuclides.
@@ -1105,6 +1130,8 @@ def find_vals(
 
             0.2
 
+        .. versionadded:: 1.0.0
+
         :param name: The name to pass to Nuclide to search by a specific Nuclide. If an element name is passed this
             will only match elemental nuclides.
         :type name: str
@@ -1124,8 +1151,6 @@ def find_vals(
         for _, (_, fraction) in self.find(name, element, A, meta_state, library):
             yield fraction
 
-    # TODO create indexible/settable values
-
     def __bool__(self):
         return bool(self._components)
 

montepy/input_parser/syntax_node.py

@@ -1749,12 +1749,15 @@ def __eq__(self, other):
 
 class MaterialsNode(SyntaxNodeBase):
     """
-    A node for representing isotopes and their concentration.
+    A node for representing isotopes and their concentration,
+    and the material parameters.
 
-    This stores a list of tuples of ZAIDs and concentrations.
+    This stores a list of tuples of ZAIDs and concentrations,
+    or a tuple of a parameter.
 
-    .. versionadded:: 0.2.0
-        This was added with the major parser rework.
+    .. versionadded:: 1.0.0
+
+        This was added as a more general version of ``IsotopesNodes``.
 
     :param name: a name for labeling this node.
     :type name: str
@@ -1767,6 +1770,10 @@ def append_nuclide(self, isotope_fraction):
         """
         Append the isotope fraction to this node.
 
+        .. versionadded:: 1.0.0
+
+            Added to replace ``append``
+
         :param isotope_fraction: the isotope_fraction to add. This must be a tuple from
             A Yacc production. This will consist of: the string identifying the Yacc production,
             a ValueNode that is the ZAID, and a ValueNode of the concentration.
@@ -1779,7 +1786,16 @@ def append(self):  # pragma: no cover
         raise DeprecationWarning("Deprecated. Use append_param or append_nuclide")
 
     def append_param(self, param):
-        """ """
+        """
+        Append the parameter to this node.
+
+        .. versionadded:: 1.0.0
+
+            Added to replace ``append``
+
+        :param param: the parameter to add to this node.
+        :type param: ParametersNode
+        """
         self._nodes.append((param,))
 
     def format(self):

montepy/materials.py

@@ -1,4 +1,8 @@
 # Copyright 2024, Battelle Energy Alliance, LLC All Rights Reserved.
+
+from __future__ import annotations
+from typing import Generator, Union
+
 import montepy
 from montepy.numbered_object_collection import NumberedDataObjectCollection
 
@@ -20,8 +24,62 @@ class Materials(NumberedDataObjectCollection):
     def __init__(self, objects=None, problem=None):
         super().__init__(Material, objects, problem)
 
-    def get_containing(self, nuclide, *args, threshold=0.0):
-        """ """
+    def get_containing(
+        self,
+        nuclide: Union[
+            montepy.data_inputs.nuclide.Nuclide,
+            montepy.data_inputs.nuclide.Nucleus,
+            montepy.Element,
+            str,
+            int,
+        ],
+        *args: Union[
+            montepy.data_inputs.nuclide.Nuclide,
+            montepy.data_inputs.nuclide.Nucleus,
+            montepy.Element,
+            str,
+            int,
+        ],
+        threshold: float = 0.0,
+    ) -> Generator[Material]:
+        """
+        Get all materials that contain these nuclides.
+
+        This uses :func:`~montepy.data_inputs.material.Material.contains` under the hood.
+        See that documentation for more guidance.
+
+        Examples
+        ^^^^^^^^
+
+        One example would to be find all water bearing materials:
+
+        .. testcode::
+
+            import montepy
+            problem = montepy.read_input("foo.imcnp")
+            for mat in problem.materials.get_containing("H-1", "O-16", threshold = 0.3):
+                print(mat)
+
+        .. testoutput::
+
+            MATERIAL: 1, ['hydrogen', 'oxygen']
+
+        .. versionadded:: 1.0.0
+
+        :param nuclide: the first nuclide to check for.
+        :type nuclide: Union[Nuclide, Nucleus, Element, str, int]
+        :param args: a plurality of other nuclides to check for.
+        :type args: Union[Nuclide, Nucleus, Element, str, int]
+        :param threshold: the minimum concentration of a nuclide to be considered. The material components are not
+            first normalized.
+        :type threshold: float
+
+        :return: A generator of all matching materials
+        :rtype: Generator[Material]
+
+        :raises TypeError: if any argument is of the wrong type.
+        :raises ValueError: if the fraction is not positive or zero, or if nuclide cannot be interpreted as a Nuclide.
+        """
         nuclides = []
         for nuclide in [nuclide] + list(args):
             if not isinstance(
@@ -59,12 +117,31 @@ def sort_by_type(nuclide):
                 yield material
 
     @property
-    def default_libraries(self):
+    def default_libraries(self) -> dict[montepy.LibraryType, montepy.Library]:
         """
         The default libraries for this problem defined by ``M0``.
 
+
+        Examples
+        ^^^^^^^^
+
+        To set the default libraries for a problem you need to set this dictionary
+        to a Library or string.
+
+        .. testcode:: python
+
+            import montepy
+            problem = montepy.read_input("foo.imcnp")
+
+            # set neutron default to ENDF/B-VIII.0
+            problem.materials.default_libraries["nlib"] = "00c"
+            # set photo-atomic
+            problem.materials.default_libraries[montepy.LibraryType.PHOTO_ATOMIC] = montepy.Library("80p")
+
+        .. versionadded:: 1.0.0
+
         :returns: the default libraries in use
-        :rtype: dict
+        :rtype: dict[LibraryType, Library]
         """
         try:
             return self[0].default_libraries

montepy/particle.py

@@ -64,6 +64,9 @@ def __hash__(self):
 @unique
 class LibraryType(str, Enum):
     """
+    Enum to represent the possible types that a nuclear data library can be.
+
+    .. versionadded:: 1.0.0
 
     Taken from section of 5.6.1 of LA-UR-22-30006
     """