armi.matProps package

The package armi.matProps is a material library capable of representing and computing material properties.

The matProps package allows users to define materials in a custom YAML format. The format is simple, extensible, and easy to use. Each material has a list of “properties” (like density, specific heat, vapor pressure, etc). Each of those properties be an arbitrary function of multiple independent variables, or a look up table of one or more variables. Each of these properties can define their own set of references, to allow for trustworthy modeling. A major idea in matProps is that we separate out materials as “data”, rather than representing them directly in Python as “code”.

This package does not include any material data files. The unit tests in this package have many example YAML files, and ARMI comes packaged with more real world examples at: armi/resources/materials/. The user may create their own data files to use with matProps in a directory, and pass in that path via armi.matProps.loadAll(path).

Loading Data

In your Python code, you can load a full set of matProps materials into memory with just one or two lines of code. You just have to provide a path to a directory filled with correctly-formatted YAML files:

import armi.matProps

pathToMaterialYAMLs = "path/to/materialDir/"
armi.matProps.loadSafe(pathToMaterialYAMLs)

If you do not specify a directory for the YAML files, there is a default location in your virtual environment you can store the data files (in a package named material_data):

import armi.matProps

armi.matProps.loadSafe()

Adding a Property

matProps comes with a large set of common material properties. But it is quite easy to add another material property to your simulation, if you need to.

from armi.matProps.prop import defProp

defProp("fuzz", "fuzziness", "1/m^2")
defProp("goo", "gooiness", "m^2/s")
defProp("squish", "squishiness", "1/Pa")

armi.matProps.loadSafe("path/to/hilarious/materials/")

A Note on Design

At the high-level, the matProps API exposes the functions in this file (loadAll, loadSafe, getMaterials, etc). And these functions all work off three global data collections: armi.matProps.loadedRootDirs, armi.matProps.materials, and armi.matProps.prop.properties.

It is worth noting that this design centers around global data. This could have a more object-oriented approach where the functions below and these three data sets are all stored in a class, e.g. via a MaterialLibrary class. This would be more Pythonic, and allow for multiple collections of materials, say for testing. So far, no one has ever needed multiple colletions of materials from matProps, because a single scientific model generally only needs one source of truth for what materials are.

armi.matProps.getPaths(rootDir: str) → list[source]: Get the paths of all the YAML files in a given directory.

armi.matProps.addMaterial(yamlPath: str, mat)[source]

Adds Material object instance to matProps.materials dict.

Parameters:

yamlPath (str) – Yaml file path whose information is being parsed.
mat (Material) – Material object whose data will be saved.

armi.matProps.loadAll(rootDir: str = None) → None[source]

Loads all material files from a particular directory. If a materials directory is not provided, this function will attempt to find materials in the default location in the virtual environment.

Parameters:: rootDir (str) – Directory whose YAML files will be loaded into matProps. The default is the materials_data location in the venv.

Notes

Hidden in here is a default directory which you can load your YAML files from. Inside your Python virtual environment, you can create a data directory named “materials_data”, and store all your matProps formatted YAML files. This is optional, of course, you can just explicitly pass a directory path into this method.

armi.matProps.clear() → None[source]: Clears all loaded materials in matProps.

armi.matProps.loadSafe(rootDir: str = None) → None[source]

Safely load a single directory of matProps materials.

Loading a materials directory via this function will first clear out any other materials that are loaded into matProps. If a materials directory is not provided, this function will attempt to find materials in the default location in the virtual environment. This is meant to be a helpful tool for testing.

Parameters:: rootDir (str) – Directory whose yaml files will be loaded into matProps. The default is the materials_data location in the venv.

armi.matProps package

Loading Data

Adding a Property

A Note on Design

Subpackages

Submodules