Marked material_components for deprecation.

doc/source/changelog.rst

@@ -10,7 +10,11 @@ MontePy Changelog
 
 **Performance Improvement**
 
-* Fixed method of linking ``Material`` to ``ThermalScattering`` objects, avoiding a very expensive O(N:sup:`2`) (:issue:`510`).
+* Fixed method of linking ``Material`` to ``ThermalScattering`` objects, avoiding a very expensive O(N :sup:`2`) (:issue:`510`).
+
+**Deprecations**
+
+* Marked ``Material.material_components`` as deprecated, and created migration plan describing what to expect moving forward (:issue:`506`).
 
 0.4.0
 --------------

doc/source/migrations/migrate0_1.rst

@@ -0,0 +1,54 @@
+.. _migrate 0 1:
+
+Migration plan for MontePy 1.0.0
+================================
+
+.. meta::
+ :description: Migration plan for moving from MontePy 0.x to MontePy 1.0.0
+
+Necessity
+---------
+
+The MCNP 6.2 and 6.3 manuals are ambiguously worded around whether nuclides can be repeated in a material definition.
+Due to this the authors of MontePy in MontePy 0.x.x assumed that repeated nuclides were not allowed.
+Due to this assumption material composition data were stored in python dictionary,
+where the keys were the nuclide and their library.
+Due to this if duplicate nuclides are present only the last instance of that nuclide will have its information preserved in the model.
+This is clearly not a desired outcome.
+
+However, it has been confirmed that duplicate nuclides are allowed in MCNP,
+and can be advantageous. 
+See :issue:`504` for more details.
+Due to this it was decided that the best way forward was to abandon the old design,
+and to create a brand new data structure.
+This means that backwards compatibility *will* be broken, 
+and so this fix is leading to a major version release.
+
+
+Deprecations
+------------
+The following properties and objects are currently deprecated, 
+and will be removed in MontePy 1.0.0.
+
+* :func:`montepy.data_inputs.material.Material.material_components`. 
+ This is the dictionary that caused this design problem. 
+
+* :class:`montepy.data_inputs.material_components.MaterialComponents`
+ This is the class that stores information in the above dictionary. 
+ It is largely excess object wrapping, that makes the material interface 
+ overly complex.
+
+* :class:`montepy.data_inputs.Isotope` will be renamed to ``Nuclide``. 
+ This is to better align with MCNP documentation,
+ and better reflect that the nuclear data for a nuclide can represent 
+ 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.

doc/source/users.rst

@@ -9,5 +9,6 @@ User Guide
  utilities
  tricks
  faq
+ migrations/migrate0_1
  changelog
  publications

montepy/data_inputs/isotope.py

@@ -3,13 +3,21 @@
 from montepy.errors import *
 from montepy.input_parser.syntax_node import PaddingNode, ValueNode
 
+import warnings
+
 
 class Isotope:
  """
  A class to represent an MCNP isotope
 
+ .. deprecated:: 0.4.1
+ This will class is deprecated, and will be renamed: ``Nuclde``.
+ For more details see the :ref:`migrate 0 1`.
+
  :param ZAID: the MCNP isotope identifier
  :type ZAID: str
+ :param suppress_warning: Whether to suppress the ``FutureWarning``.
+ :type suppress_warning: bool
  """
 
  # Cl-52 Br-101 Xe-150 Os-203 Cm-251 Og-296
@@ -22,7 +30,14 @@ class Isotope:
  Points on bounding curve for determining if "valid" isotope
  """
 
- def __init__(self, ZAID="", node=None):
+ def __init__(self, ZAID="", node=None, suppress_warning=False):
+ if not suppress_warning:
+ warnings.warn(
+ "montepy.data_inputs.isotope.Isotope is deprecated and will be renamed: Nuclide.\n"
+ "See <https://www.montepy.org/migrations/migrate0_1.html> for more information ",
+ FutureWarning,
+ )
+
  if node is not None and isinstance(node, ValueNode):
  if node.type == float:
  node = ValueNode(node.token, str, node.padding)

montepy/data_inputs/material.py

@@ -12,6 +12,8 @@
 import itertools
 import re
 
+import warnings
+
 
 def _number_validator(self, number):
  if number <= 0:
@@ -51,7 +53,7 @@ def __init__(self, input=None):
  f"Material definitions for material: {self.number} is not valid.",
  )
  for isotope_node, fraction in iterator:
- isotope = Isotope(node=isotope_node)
+ isotope = Isotope(node=isotope_node, suppress_warning=True)
  fraction.is_negatable_float = True
  if not set_atom_frac:
  set_atom_frac = True
@@ -68,8 +70,9 @@ def __init__(self, input=None):
  input,
  f"Material definitions for material: {self.number} cannot use atom and mass fraction at the same time",
  )
+
  self._material_components[isotope] = MaterialComponent(
- isotope, fraction
+ isotope, fraction, suppress_warning=True
  )
 
  @make_prop_val_node("_old_number")
@@ -102,13 +105,23 @@ def is_atom_fraction(self):
  @property
  def material_components(self):
  """
- The internal dictionary containing all the components of this material.
+  The internal dictionary containing all the components of this material.
 
- The keys are :class:`~montepy.data_inputs.isotope.Isotope` instances, and the values are
- :class:`~montepy.data_inputs.material_component.MaterialComponent` instances.
+ .. deprecated:: 0.4.1
+ MaterialComponent has been deprecated as part of a redesign for the material
+ interface due to a critical bug in how MontePy handles duplicate nuclides.
+ See :ref:`migrate 0 1`.
 
- :rtype: dict
+ The keys are :class:`~montepy.data_inputs.isotope.Isotope` instances, and the values are
+ :class:`~montepy.data_inputs.material_component.MaterialComponent` instances.
+
+ :rtype: dict
  """
+ warnings.warn(
+ f"""material_components is deprecated, and will be removed in MontePy 1.0.0.
+See <https://www.montepy.org/migrations/migrate0_1.html> for more information """,
+ DeprecationWarning,
+ )
  return self._material_components
 
  @make_prop_pointer("_thermal_scattering", thermal_scattering.ThermalScatteringLaw)
@@ -149,7 +162,7 @@ def format_for_mcnp_input(self, mcnp_version):
 
  def _update_values(self):
  new_list = syntax_node.IsotopesNode("new isotope list")
- for isotope, component in self.material_components.items():
+ for isotope, component in self._material_components.items():
  isotope._tree.value = isotope.mcnp_str()
  new_list.append(("_", isotope._tree, component._tree))
  self._tree.nodes["data"] = new_list
@@ -198,8 +211,8 @@ def __repr__(self):
  else:
  ret += "mass\n"
 
- for component in self.material_components:
- ret += repr(self.material_components[component]) + "\n"
+ for component in self._material_components:
+ ret += repr(self._material_components[component]) + "\n"
  if self.thermal_scattering:
  ret += f"Thermal Scattering: {self.thermal_scattering}"
 
@@ -212,7 +225,7 @@ def __str__(self):
  def _get_material_elements(self):
  sortable_components = [
  (iso, component.fraction)
- for iso, component in self.material_components.items()
+ for iso, component in self._material_components.items()
  ]
  sorted_comps = sorted(sortable_components)
  elements_set = set()
@@ -224,7 +237,7 @@ def _get_material_elements(self):
  return elements
 
  def validate(self):
- if len(self.material_components) == 0:
+ if len(self._material_components) == 0:
  raise IllegalState(
  f"Material: {self.number} does not have any components defined."
  )
@@ -237,10 +250,10 @@ def __hash__(self):
 
  """
  temp_hash = ""
- sorted_isotopes = sorted(list(self.material_components.keys()))
+ sorted_isotopes = sorted(list(self._material_components.keys()))
  for isotope in sorted_isotopes:
  temp_hash = hash(
- (temp_hash, str(isotope), self.material_components[isotope].fraction)
+ (temp_hash, str(isotope), self._material_components[isotope].fraction)
  )
 
  return hash((temp_hash, self.number))

montepy/data_inputs/material_component.py

@@ -3,6 +3,8 @@
 from montepy.input_parser.syntax_node import PaddingNode, ValueNode
 from montepy.utilities import make_prop_val_node
 
+import warnings
+
 
 def _enforce_positive(self, val):
  if val <= 0:
@@ -15,13 +17,26 @@ class MaterialComponent:
 
  For example: this may be H-1 in water: like 1001.80c — 0.6667
 
+ .. deprecated:: 0.4.1
+ MaterialComponent has been deprecated as part of a redesign for the material
+ interface due to a critical bug in how MontePy handles duplicate nuclides.
+ See :ref:`migrate 0 1`.
+
  :param isotope: the Isotope object representing this isotope
  :type isotope: Isotope
  :param fraction: the fraction of this component in the material
  :type fraction: ValueNode
+ :param suppress_warning: Whether to suppress the ``DeprecationWarning``.
+ :type suppress_warning: bool
  """
 
- def __init__(self, isotope, fraction):
+ def __init__(self, isotope, fraction, suppress_warning=False):
+ if not suppress_warning:
+ warnings.warn(
+ f"""MaterialComponent is deprecated, and will be removed in MontePy 1.0.0.
+See <https://www.montepy.org/migrations/migrate0_1.html> for more information """,
+ DeprecationWarning,
+ )
  if not isinstance(isotope, Isotope):
  raise TypeError(f"Isotope must be an Isotope. {isotope} given")
  if isinstance(fraction, (float, int)):