armi.materials package

The material package defines macroscopic material compositions and their properties.

Properties in scope include temperature dependent thermo/mechanical properties (like heat capacity, linear expansion coefficients, viscosity, density), and material-specific nuclear properties that can not exist at the nuclide level alone (like thermal scattering laws).

Material definitions are crucial to any nuclear analysis. This module handles the dynamic importing of all the materials defined here and in attached plugins. It is expected that most teams will have special material definitions that they will want to define.

In ARMI, materials can be defined purely in the armi.matProps YAML format. Or materials can be defined purely in Python code. To support this, the material class armi.materials.material subclasses the matProp material class.

You will find that ARMI comes provided with a set of material YAML files at armi/resources/materials. These materials are well-attributed from open-source references. They also serve as great examples of a variety of features that the armi.matProps YAML files support. ARMI also maintains a few examples of complicated material definitions in armi/materials/. You will find examples like armi.materials.water.SaturatedWater and armi.materials.uranium.Uranium.

armi.materials.setMaterialNamespaceOrder(order)[source]

Set the material namespace order at the Python interpreter, global level.

Implementation: Material collections are defined with an order of precedence in the case of duplicates. I_ARMI_MAT_ORDER
signature: setMaterialNamespaceOrder
requirements: R_ARMI_MAT_ORDER

An ARMI application will need materials. Materials can be imported from any code the application has access to, like plugin packages. This leads to the situation where one ARMI application will want to import multiple collections of materials. To handle this, ARMI keeps a list of material namespaces. This is an ordered list of importable packages that ARMI can search for a particular material by name.

This automatic exploration of an importable package saves the user the tedium have having to import or include hundreds of materials manually somehow. But it comes with a caveat; the list is ordered. If two different namespaces in the list include a material with the same name, the first one found in the list is chosen, i.e. An ARMI application will need materials. Materials can be imported from any code the application has access to, like plugin packages. This leads to the situation where one ARMI application will want to import multiple collections of materials. To handle this, ARMI keeps a list of material namespaces. This is an ordered list of importable packages that ARMI can search for a particular material by name.

This automatic exploration of an importable package saves the user the tedium have having to import or include hundreds of materials manually somehow.
armi.materials.addYamlMaterialToThisNamespace(yamlPath: str, overwriteExisting=False)[source]

Given a valid material YAML file, create a class for it and add it to this package.

Parameters:

  • yamlPath (str) – Path to a valid material YAML file, to be imported.

  • overwriteExisting (bool, optional) – If True, will overwrite existing materials in the namespace. Default False.

armi.materials.importYamlMaterialDir(dirPath=None, overwriteExisting=False, clearFirst=True)[source]

Import all Materials defined by YAML files in the defined directory into this package.

Parameters:

  • dirPath (str, optional) – Path to directory, filled with material YAML files, to be imported. If this is left as None, we will look for the “materials_data” directory in the venv.

  • overwriteExisting (bool, optional) – If True, will overwrite existing materials in the namespace. Default False.

  • clearFirst (bool, optional) – A popular safety option is to first clear out the YAML materials loaded into memory before loading new ones. This is particularly popular during unit testing.

armi.materials.importMaterialsIntoModuleNamespace(path, modName, namespace, updateSource=None)[source]

Import all Material subclasses into the top subpackage. This only works for materials defined in Python.

This allows devs to use from armi.materials import HT9. This can be used in plugins for similar purposes.

Parameters:

  • path (str or list) – Path or list of paths to package/module being imported

  • modName (str) – module name

  • namespace (dict) – The namespace

  • updateSource (str, optional) – Change DATA_SOURCE on import to a different string. Useful for saying where plugin materials are coming from.

armi.materials.iterAllMaterialClassesInNamespace(namespace)[source]

Iterate over all Material subclasses found in a namespace.

Notes

Useful for testing.

armi.materials.resolveMaterialClassByName(name: str, namespaceOrder: List[str] = None)[source]

Find the first material class that matches a name in an ordered namespace.

Names can either be fully resolved class paths (e.g. armi.materials.uZr:UZr) or simple class names (e.g. UZr). In the latter case, the CONF_MATERIAL_NAMESPACE_ORDER setting to allows users to choose which particular material of a common name (like UO2 or HT9) gets used.

Input files usually specify a material like UO2. Which particular implementation gets used (Framework’s UO2 vs. a user plugins UO2 vs. the Kentucky Transportation Cabinet’s UO2) is up to the user at runtime.

Implementation: Materials can be searched across packages in a defined namespace. I_ARMI_MAT_NAMESPACE
signature: resolveMaterialClassByName
requirements: R_ARMI_MAT_NAMESPACE

During the runtime of an ARMI application, but particularly during the construction of the reactor in memory, materials will be requested by name. At that point, this code is called to search for that material name. The search goes through the ordered list of Python namespaces provided. The first time an instance of that material is found, it is returned. In this way, the first items in the material namespace list take precedence.

When a material name is passed to this function, it may be either a simple name like the string "Water" or it may be much more specific, like armi.materials.water:Water.
Parameters:

  • name (str) – The material class name to find, e.g. "Water". Optionally, a module path and class name can be provided with a colon separator as module:className, e.g. armi.materials.water:Water for direct specification.

  • namespaceOrder (list of str, optional) – A list of namespaces in order of preference in which to search for the material. If not passed, the value in the global MATERIAL_NAMESPACE_ORDER will be used, which is often set by the CONF_MATERIAL_NAMESPACE_ORDER setting (e.g. during reactor construction). Any value passed into this argument will be ignored if the name is provided with a modulePath.

Returns:

matCls – The material, which will always be of the ARMI Material class, which subclasses the matProps class.

Return type:

armi.materials.material.Material

Raises:

KeyError – When material of name cannot be found in namespaces.

Examples

>>> resolveMaterialClassByName("UO2", ["something.else.materials", "armi.materials"])
<class 'something.else.materials.UO2'>

See also

armi.reactor.reactors.factory

Applies user settings to default namespace order.

Subpackages

Submodules