Merge pull request #24 from fusion-energy/develop

general doc updates

docs/source/example_material_from_library.rst

@@ -65,7 +65,7 @@ For several materials within the collection the temperature and the pressure
 impacts the density of the material. The neutronics_material_maker adjusts the
 density to take temperature (in C or K) and the pressure into account when
 appropriate. Densities are calculated either by a material specific formula
-(for example `FLiBe <https://github.com/fusion-energy/neutronics_material_maker/blob/openmc_version/neutronics_material_maker/data/multiplier_and_breeder_materials.json>`_)
+(for example FLiBe which has an temperature dependent equation for calculating the density https://github.com/fusion-energy/neutronics_material_maker/blob/a166ccebdb4949c987df75a404eaf8f63853e2c4/neutronics_material_maker/data/multiplier_and_breeder_materials.json#L32)
 or using `CoolProps <https://pypi.org/project/CoolProp/>`_ (for example coolants such as H2O).
 
 .. code-block:: python
@@ -76,7 +76,7 @@ or using `CoolProps <https://pypi.org/project/CoolProp/>`_ (for example coolants
 
     my_mat1.openmc_material
 
-Temperature can be provided in degrees C or Kelvin.
+Temperature must be provided in Kelvin.
 
 .. code-block:: python
 
@@ -146,13 +146,13 @@ string.
         material_id=24,
         temperature=573.15,
         pressure=15e6,
-        additional_end_lines={'mcnp': ['      mt24 lwtr.01']}
+        additional_end_lines={'mcnp': ['mt24 lwtr.01']}
     )
 
     print(my_mat2.mcnp_material)
 
 The above code will return a MCNP material card string with the additional line
-'      mt24 lwtr.01' at the end. Notice that spaces should also be set by the
+'mt24 lwtr.01' at the end. Note that spaces should also be set by the
 user.
 
 .. code-block:: bash
@@ -163,7 +163,7 @@ user.
             008016  3.32540200e-01
             008017  1.26333333e-04
             008018  6.66800000e-04
-            mt24 lwtr.01
+    mt24 lwtr.01
 
 It is also possible to specify this additional line in a JSON file and
 then read in the file and export the material. The additional end lines can

neutronics_material_maker/material.py

@@ -62,8 +62,8 @@ class Material:
             with a unique identifier.
         packing_fraction: This value is mutliplied by the density
             which allows packing_fraction to be taken into account for materials
-            involving an amount of void. Recall that packing_fraction is equal
-            to 1/void fraction
+            involving an amount of void. Recall that
+            packing_fraction = 1 - void fraction
         enrichment: This is the percentage of isotope enrichment
             required for the material. This works for materials that have
             an enrichment_target and enrichment_type also specified.
@@ -107,7 +107,7 @@ class Material:
             (str) as the key and the amount of that isotope (float) as the value
             e.g. {'Li6': 0.9, 'Li7': 0.1} alternatively zaid representation
             can also be used instead of the symbol e.g. {'3006': 0.9, '4007': 0.1}
-        percent_type: Atom "ao" or or weight fraction "wo"
+        percent_type: Atom "ao" or weight fraction "wo"
         density: value to be used as the density. Can be a number or a string.
             if a string then it will be evaluated as an equation to find the
             density and can contain temperature and pressure variables.
@@ -865,7 +865,7 @@ def from_library(name: str, **kwargs):
         return Material(name=name, **entry)
 
     def from_mixture(
-        materials,
+        materials: list,
         fracs: List[float],
         percent_type: Optional[str] = "vo",
         name: Optional[str] = None,
@@ -880,10 +880,65 @@ def from_mixture(
         volume_in_cm3: Optional[float] = None,
         additional_end_lines: Optional[Dict[str, List[str]]] = None,
     ):
-        if sum(fracs) != 1.0:
+        """Creates a material from a mixture of multiple materials.
+
+        Args:
+            materials: A list of neutronics_material_maker.Materials or openmc.Materials
+            fracs: A list of material fractions, typically sums to 1.
+            percent_type: Volume "vo" Atom "ao" or weight fraction "wo"
+            name: the name of the material
+            packing_fraction: This value is mutliplied by the density
+                which allows packing_fraction to be taken into account for materials
+                involving an amount of void. Recall that
+                packing_fraction = 1 - void fraction
+            temperature: The temperature of the material in degrees
+                Kelvin. Temperature impacts the density of some materials in the
+                collection. Materials in the collection that are impacted by
+                temperature have density equations that depend on temperature.
+                These tend to be liquids and gases used for coolants and even
+                liquids such as lithium-lead and FLiBe that are used as breeder
+                materials. Added to the OpenMC material object and the serpent
+                material card.
+            temperature_to_neutronics_code: The temperature args are often used to
+                find the material density via density equations. However it can be
+                desirable to not make use of this temperature in the neutronics
+                codes. Typically this is due to missing cross section data.
+                Defaults to True which makes use of any material temperature in the
+                neutronics material. Can be set to False which doesn't propagate
+                temperature data to the neutronics material. This only impacts
+                OpenMC and serpent materials. As shift materials require the use of
+                temperature and fispact/mcnp materials don't make use of
+                temperature on the material card.
+            pressure: The pressure of the material in Pascals. Pressure impacts the
+                density of some materials in the collection. Materials in the
+                collection that are impacted by pressure have density equations
+                that depend on pressure. These tend to be liquids and gases used
+                for coolants such as H2O and CO2.
+            zaid_suffix: The nuclear library to apply to the zaid, for
+                example ".31c", this is used in MCNP and Serpent material cards.
+            material_id: the id number or mat number used in the MCNP material card
+            decimal_places: The number of decimal places to use in MCNP and
+                Seprent material cards when they are printed out (default of 8).
+            volume_in_cm3: The volume of the material in cm3, used when
+                creating fispact material cards
+            comment: An entry used to store information on the source of the
+                material data
+            additional_end_lines: Additional lines of test that are added to the end of
+                the material card. Compatable with MCNP, Serpent, Fispact outputs
+                which are string based. Argument should be a dictionary specifying
+                the code and a list of lines to be added, be sure to include any
+                white required spaces in the string. This example will add a single
+                S(a,b) card to an MCNP card {'mcnp': ['        mt24 lwtr.01']}.
+
+        Returns: neutronics_material_maker.Material() object
+        """
+
+        if sum(fracs) * packing_fraction + (1 - packing_fraction) != 1.0:
             msg = (
-                "warning sum of MutliMaterials.fracs do not sum to 1."
-                f"{fracs} = {sum(fracs)}"
+                "Warning some material is not accounted for as the follow "
+                "equation is not equal to 1."
+                "sum(fracs)*packing_fraction + (1-packing_fraction)"
+                f"sum({fracs})*{packing_fraction} + (1-{packing_fraction})"
             )
             warnings.warn(msg, UserWarning)
 

tests/test_Material_from_mixture.py

@@ -495,7 +495,7 @@ def too_large_fracs():
             assert issubclass(w[-1].category, UserWarning)
             # the second entry is needed as OpenMC material mixer also raises
             # and error
-            assert "warning sum of MutliMaterials.fracs do not sum to 1." in str(
+            assert "Warning some material is not accounted for as the follow" in str(
                 w[-2].message
             )
 
@@ -521,25 +521,37 @@ def too_small_fracs():
             assert issubclass(w[-1].category, UserWarning)
             # the second entry is needed as OpenMC material mixer also raises
             # and error
-            assert "warning sum of MutliMaterials.fracs do not sum to 1." in str(
+            assert "Warning some material is not accounted for as the follow" in str(
                 w[-2].message
             )
 
-        def test_incorrect_packing_fraction():
-            """checks a ValueError is raised when the packing_fraction is the
-            wrong type"""
+        def not_fully_accounting_mat():
+            """checks a warning is raised when the fracs and packing fractions
+            don't account for all the material"""
 
             nmm.Material.from_mixture(
                 name="test_material",
                 materials=[
                     nmm.Material.from_library("tungsten", packing_fraction=0.6),
                     nmm.Material.from_library("eurofer", packing_fraction=0.8),
                 ],
-                fracs=[0.3, 0.7],
-                packing_fraction="1",
+                fracs=[0.3, 0.6],
+                packing_fraction=0.2,
             )
 
-        self.assertRaises(ValueError, test_incorrect_packing_fraction)
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+            # Trigger a warning.
+            not_fully_accounting_mat()
+            # Verify some things
+            assert len(w) >= 1
+            assert issubclass(w[-1].category, UserWarning)
+            # the second entry is needed as OpenMC material mixer also raises
+            # and error
+            assert "Warning some material is not accounted for as the follow" in str(
+                w[-2].message
+            )
 
         def test_too_large_packing_fraction():
             """checks a ValueError is raised when the packing_fraction is the