Merge pull request #113 from ukaea/develop

Develop

docs/environment.yml

@@ -0,0 +1,7 @@
+name: docs-environment
+
+channels:
+  - conda-forge
+
+dependencies:
+  - openmc

docs/source/conf.py

@@ -28,7 +28,6 @@
 # The full version, including alpha/beta/rc tags
 release = "1.0"
 
-
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

docs/source/example_material.rst

@@ -8,7 +8,7 @@ Here is an example that accesses a material from the internal collection called
 
 ::
 
-   import neutronics-material-maker as nmm
+   import neutronics_material_maker as nmm
 
    my_mat = nmm.Material('eurofer')
 
@@ -76,6 +76,7 @@ Lithium ceramics used in fusion breeder blankets often contain enriched lithium-
 
     my_mat2.openmc_material
 
+
 The default enrichment target for 'Li4SiO4' is Li6 but this can be changed if required.
 
 ::
@@ -94,61 +95,70 @@ Usage - make a your own materials
 Example making materials from elements
 
 ::
+
     import neutronics_material_maker as nmm
 
-    my_mat = nmm.Material(material_name="li_with_si",
-                          density= 3.0,
-                          density_unit= "g/cm3",
-                          percent_type= "ao",
-                          elements={
-                                "Li":4,
-                                "Si":2
-                            }
-    )
+    my_mat = nmm.Material(
+        material_name="li_with_si",
+        density= 3.0,
+        density_unit= "g/cm3",
+        percent_type= "ao",
+        elements={
+                "Li":4,
+                "Si":2
+                }
+        )
+
 
 Example making materials from isotopes
 
 ::
+
     import neutronics_material_maker as nmm
 
-    my_mat = nmm.Material(material_name="enriched_li",
-                          density= 3.0,
-                          density_unit= "g/cm3",
-                          percent_type= "ao",
-                          isotopes={
-                                "Li6":0.9,
-                                "Li7":0.1
-                            }
+    my_mat = nmm.Material(
+        material_name="enriched_li",
+        density= 3.0,
+        density_unit= "g/cm3",
+        percent_type= "ao",
+        isotopes={
+            "Li6":0.9,
+            "Li7":0.1
+        }
     )
 
 Example making materials from isotopes defined by zaid
 
 ::
+
     import neutronics_material_maker as nmm
 
-    my_mat = nmm.Material(material_name="enriched_li",
-                          density= 3.0,
-                          density_unit= "g/cm3",
-                          percent_type= "ao",
-                          isotopes={
-                                "3006":0.9,
-                                "3007":0.1
-                            }
+    my_mat = nmm.Material(
+        material_name="enriched_li",
+        density= 3.0,
+        density_unit= "g/cm3",
+        percent_type= "ao",
+        isotopes={
+            "3006":0.9,
+            "3007":0.1
+        }
     )
 
 It is also possible to make your own materials directly from a dictionary by making use of the python syntax **
 
 ::
+
     import neutronics_material_maker as nmm
     
-    my_dict = { "material_name": "li_with_si",
-                "elements": {
-                                "Li":4,
-                                "Si":2
-                            },
-                "density": 3.0,
-                "density_unit": "g/cm3",
-                "percent_type": "ao",
-                }
+    my_dict = {
+        "material_name": "li_with_si",
+        "elements": {
+                        "Li":4,
+                        "Si":2
+                    },
+        "density": 3.0,
+        "density_unit": "g/cm3",
+        "percent_type": "ao",
+    }
 
     my_mat = nmm.Material(**my_dict)

docs/source/example_multimaterial.rst

@@ -13,7 +13,7 @@ Making two materials and mixing them to create a MultiMaterial
    my_mat1 = nmm.Material('eurofer')
    my_mat2 = nmm.Material('tungsten')
 
-   my_mat3 = MultiMaterial(material_name='mixed_mat',
-                           materials=[my_mat1, my_mat2],
-                           fracs=[0.4, 0.6],
-                           percent_type='vo')
+   my_mat3 = nmm.MultiMaterial(material_tag='mixed_mat',
+                               materials=[my_mat1, my_mat2],
+                               fracs=[0.4, 0.6],
+                               percent_type='vo')

docs/source/index.rst

@@ -1,13 +1,22 @@
 Neutronics Material Maker
 =========================
 
-The aim of this project is to facilitate the creation of materials for use in neutronics codes such as OpenMC, Serpent, MCNP and Fispact.
+The aim of this project is to facilitate the creation of materials for use in
+neutronics codes such as OpenMC, Serpent, MCNP and Fispact.
 
-The hope is that by having this collection of materials it is easier to reuse materials across projects and use a common source with less room for user error.
+The hope is that by having this collection of materials it is easier to reuse
+materials across projects and use a common source with less room for user
+error.
 
-The package allows for materials to be made from either an internal library of materials or from your own material library.
+The package allows for materials to be made from either an internal library of
+materials or from your own material library.
 
-Material densities can be made to account for temperature, pressure and isotopic enrichment.
+Material densities can be made to account for temperature, pressure and
+isotopic enrichment.
+
+.. raw:: html
+
+      <iframe width="560" height="315" src="https://www.youtube.com/embed/V-VHLwRar9s" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
 
 .. toctree::
@@ -21,10 +30,26 @@ Material densities can be made to account for temperature, pressure and isotopic
    example_library_usage
 
 
+History
+-------
+
+The package was originally created by Jonathan Shimwell as a method of
+reducing the effort required to the same materials accross different neutronics
+codes. The current version can be considered a materials library and translator
+between material types. The original version contained methods of mixing
+materials and building materials from chemical equations. These aspects of the
+code were moved to OpenMC in code contributions (e.g
+`1 <https://github.com/openmc-dev/openmc/pull/1530>`_ and
+`2 <https://github.com/openmc-dev/openmc/pull/1534>`_ )
+which reduced the complexity and maintainance burden for the neutronics
+material maker and brought on OpenMC as a major dependancy.
+
+
 Prerequisites
 -------------
 
-To use the neutronics-material-maker tool you will need Python 3 and OpenMC installed.
+To use the neutronics-material-maker tool you will need Python 3 and OpenMC
+installed.
 
 * `Python 3 <https://www.python.org/downloads/>`_
 * `OpenMC <https://docs.openmc.org/en/stable/usersguide/install.html>`_
@@ -34,19 +59,23 @@ To use the neutronics-material-maker tool you will need Python 3 and OpenMC inst
 Installation
 ------------
 
-The recommended method is to install from [Conda Forge](https://conda-forge.org) which also installs all the dependancies including OpenMC.
+The recommended method is to install from [Conda Forge](https://conda-forge.org)
+which also installs all the dependancies including OpenMC.
+
+.. code-block:: bash
+
+   conda install neutronics_material_maker -c conda-forge
+
 
-```
-conda install neutronics_material_maker -c conda-forge
-```
+Alternativly the code can be easily installed using pip (which doesn't
+currently include OpenMC)
 
-Alternativly the code can be easily installed using pip (which doesn't currently include OpenMC)
+.. code-block:: bash
 
-```
-pip install neutronics_material_maker
-```
+   pip install neutronics_material_maker
 
-You can clone the repository, and install using the setup.py if you would like the development version.
+You can clone the repository, and install using the setup.py if you would like
+the development version.
 
 ::
 
@@ -57,7 +86,11 @@ You can clone the repository, and install using the setup.py if you would like t
 Features
 --------
 
-There are two main user classes `Material() <https://neutronics-material-maker.readthedocs.io/en/latest/material.html>`_ and `MutliMaterial() <https://neutronics-material-maker.readthedocs.io/en/latest/multimaterial.html>`_ which are both fully documented.
+There are two main user classes 
+`Material() <https://neutronics-material-maker.readthedocs.io/en/latest/material.html>`_ 
+and 
+`MutliMaterial() <https://neutronics-material-maker.readthedocs.io/en/latest/multimaterial.html>`_ 
+which are both fully documented.
 
 
 Example Scripts

environment.yml

@@ -4,6 +4,7 @@ channels:
   - conda-forge
 
 dependencies:
+  - python=3.8
   - openmc
   - pip:
     - coolprop

neutronics_material_maker/mutlimaterial.py

@@ -4,7 +4,7 @@
 
 import warnings
 from json import JSONEncoder
-from typing import List, Optional
+from typing import List, Optional, Union
 
 import neutronics_material_maker as nmm
 from neutronics_material_maker import (make_fispact_material,
@@ -80,16 +80,16 @@ class MultiMaterial:
     def __init__(
         self,
         material_tag: Optional[str] = None,
-        materials: list = [],
+        materials: List[Union[nmm.Material, openmc.Material]] = [],
         fracs: List[float] = [],
-        percent_type: str = "vo",
+        percent_type: Optional[str] = "vo",
         packing_fraction: float = 1.0,
-        zaid_suffix: str = None,
-        material_id: int = None,
-        decimal_places: int = 8,
-        volume_in_cm3: float = None,
-        temperature_in_C: float = None,
-        temperature_in_K: float = None
+        zaid_suffix: Optional[str] = None,
+        material_id: Optional[int] = None,
+        decimal_places: Optional[int] = 8,
+        volume_in_cm3: Optional[float] = None,
+        temperature_in_C: Optional[float] = None,
+        temperature_in_K: Optional[float] = None
     ):
         self.material_tag = material_tag
         self.materials = materials

neutronics_material_maker/utils.py

@@ -14,7 +14,7 @@
             .fispact_material not avaiable")
 
 
-def make_fispact_material(mat):
+def make_fispact_material(mat) -> str:
     """
     Returns a Fispact material card for the material. This contains the required
     keywords (DENSITY and FUEL) and the number of atoms of each isotope in the
@@ -43,7 +43,7 @@ def make_fispact_material(mat):
     return "\n".join(mat_card)
 
 
-def make_serpent_material(mat):
+def make_serpent_material(mat) -> str:
     """Returns the material in a string compatable with Serpent II"""
 
     if mat.material_tag is None:
@@ -78,7 +78,7 @@ def make_serpent_material(mat):
     return "\n".join(mat_card)
 
 
-def make_mcnp_material(mat):
+def make_mcnp_material(mat) -> str:
     """Returns the material in a string compatable with MCNP6"""
 
     if mat.material_id is None:
@@ -127,22 +127,22 @@ def make_mcnp_material(mat):
     return "\n".join(mat_card)
 
 
-def isotope_to_zaid(isotope):
+def isotope_to_zaid(isotope: str) -> str:
     """converts an isotope into a zaid e.g. Li6 -> 003006"""
     z, a, m = openmc.data.zam(isotope)
     zaid = str(z).zfill(3) + str(a).zfill(3)
     return zaid
 
 
-def zaid_to_isotope(zaid):
+def zaid_to_isotope(zaid: str) -> str:
     """converts an isotope into a zaid e.g. 003006 -> Li6"""
     a = str(zaid)[-3:]
     z = str(zaid)[:-3]
     symbol = openmc.data.ATOMIC_SYMBOL[int(z)]
     return symbol + str(int(a))
 
 
-def AddMaterialFromDir(directory, verbose=True):
+def AddMaterialFromDir(directory: str, verbose: bool = True):
     """Add materials to the internal library from a directory of json files"""
     for filename in Path(directory).rglob("*.json"):
         with open(filename, "r") as f:
@@ -153,7 +153,7 @@ def AddMaterialFromDir(directory, verbose=True):
             print(sorted(list(new_data.keys())), "\n")
 
 
-def AddMaterialFromFile(filename, verbose=True):
+def AddMaterialFromFile(filename, verbose=True) -> None:
     """Add materials to the internal library from a json file"""
     with open(filename, "r") as f:
         new_data = json.load(f)
@@ -163,7 +163,7 @@ def AddMaterialFromFile(filename, verbose=True):
         print(sorted(list(material_dict.keys())))
 
 
-def AvailableMaterials():
+def AvailableMaterials() -> dict:
     """Returns a dictionary of available materials"""
     return material_dict
 

readthedocs.yml

@@ -2,7 +2,13 @@
 # Read the Docs configuration file
 
 # Required
-version: 1
+version: 2
+
+build:
+  image: latest
+
+python:
+  version: 3.8
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -13,11 +19,11 @@ sphinx:
 #   - pdf
 
 # this is not needed if using conda environment
-# python:
-#   version: 3.7
-#   install:
-#     - requirements: requirements.txt
+python:
+  version: 3.8
+  install:
+    - requirements: requirements.txt
 
 # specify conda environment needed for build
 conda:
-  file: environment.yml
+  environment: docs/environment.yml