openmc.Material

class openmc.Material(material_id=None, name='', temperature=None)[source]

A material composed of a collection of nuclides/elements.

To create a material, one should create an instance of this class, add nuclides or elements with Material.add_nuclide() or Material.add_element(), respectively, and set the total material density with Material.set_density(). Alternatively, you can use Material.add_components() to pass a dictionary containing all the component information. The material can then be assigned to a cell using the Cell.fill attribute.

Parameters:

  • material_id (int, optional) – Unique identifier for the material. If not specified, an identifier will automatically be assigned.

  • name (str, optional) – Name of the material. If not specified, the name will be the empty string.

  • temperature (float, optional) – Temperature of the material in Kelvin. If not specified, the material inherits the default temperature applied to the model.

Variables:

  • id (int) – Unique identifier for the material

  • temperature (float) – Temperature of the material in Kelvin.

  • density (float) – Density of the material (units defined separately)

  • density_units (str) – Units used for density. Can be one of ‘g/cm3’, ‘g/cc’, ‘kg/m3’, ‘atom/b-cm’, ‘atom/cm3’, ‘sum’, or ‘macro’. The ‘macro’ unit only applies in the case of a multi-group calculation.

  • depletable (bool) – Indicate whether the material is depletable.

  • nuclides (list of namedtuple) – List in which each item is a namedtuple consisting of a nuclide string, the percent density, and the percent type (‘ao’ or ‘wo’). The namedtuple has field names name, percent, and percent_type.

  • isotropic (list of str) – Nuclides for which elastic scattering should be treated as though it were isotropic in the laboratory system.

  • average_molar_mass (float) – The average molar mass of nuclides in the material in units of grams per mol. For example, UO2 with 3 nuclides will have an average molar mass of 270 / 3 = 90 g / mol.

  • volume (float) – Volume of the material in cm^3. This can either be set manually or calculated in a stochastic volume calculation and added via the Material.add_volume_information() method.

  • paths (list of str) – The paths traversed through the CSG tree to reach each material instance. This property is initialized by calling the Geometry.determine_paths() method.

  • num_instances (int) – The number of instances of this material throughout the geometry. This property is initialized by calling the Geometry.determine_paths() method.

  • fissionable_mass (float) – Mass of fissionable nuclides in the material in [g]. Requires that the volume attribute is set.

  • ncrystal_cfg (str) –

    NCrystal configuration string

    Added in version 0.13.3.

add_components(components: dict, percent_type: str = 'ao')[source]

Add multiple elements or nuclides to a material

Added in version 0.13.1.

Parameters:

  • components (dict of str to float or dict) – Dictionary mapping element or nuclide names to their atom or weight percent. To specify enrichment of an element, the entry of components for that element must instead be a dictionary containing the keyword arguments as well as a value for 'percent'

  • percent_type ({'ao', 'wo'}) – ‘ao’ for atom percent and ‘wo’ for weight percent

Examples

>>> mat = openmc.Material()
>>> components  = {'Li': {'percent': 1.0,
>>>                       'enrichment': 60.0,
>>>                       'enrichment_target': 'Li7'},
>>>                'Fl': 1.0,
>>>                'Be6': 0.5}
>>> mat.add_components(components)
add_element(element: str, percent: float, percent_type: str = 'ao', enrichment: float | None = None, enrichment_target: str | None = None, enrichment_type: str | None = None, cross_sections: str | None = None)[source]

Add a natural element to the material

Parameters:

  • element (str) – Element to add, e.g., ‘Zr’ or ‘Zirconium’

  • percent (float) – Atom or weight percent

  • percent_type ({'ao', 'wo'}, optional) – ‘ao’ for atom percent and ‘wo’ for weight percent. Defaults to atom percent.

  • enrichment (float, optional) – Enrichment of an enrichment_target nuclide in percent (ao or wo). If enrichment_target is not supplied then it is enrichment for U235 in weight percent. For example, input 4.95 for 4.95 weight percent enriched U. Default is None (natural composition).

  • enrichment_target (str, optional) –

    Single nuclide name to enrich from a natural composition (e.g., ‘O16’)

    Added in version 0.12.

  • enrichment_type ({'ao', 'wo'}, optional) –

    ‘ao’ for enrichment as atom percent and ‘wo’ for weight percent. Default is: ‘ao’ for two-isotope enrichment; ‘wo’ for U enrichment

    Added in version 0.12.

  • cross_sections (str, optional) – Location of cross_sections.xml file.

Notes

General enrichment procedure is allowed only for elements composed of two isotopes. If enrichment_target is given without enrichment natural composition is added to the material.

add_elements_from_formula(formula: str, percent_type: str = 'ao', enrichment: float | None = None, enrichment_target: str | None = None, enrichment_type: str | None = None)[source]

Add a elements from a chemical formula to the material.

Added in version 0.12.

Parameters:

  • formula (str) – Formula to add, e.g., ‘C2O’, ‘C6H12O6’, or (NH4)2SO4. Note this is case sensitive, elements must start with an uppercase character. Multiplier numbers must be integers.

  • percent_type ({'ao', 'wo'}, optional) – ‘ao’ for atom percent and ‘wo’ for weight percent. Defaults to atom percent.

  • enrichment (float, optional) – Enrichment of an enrichment_target nuclide in percent (ao or wo). If enrichment_target is not supplied then it is enrichment for U235 in weight percent. For example, input 4.95 for 4.95 weight percent enriched U. Default is None (natural composition).

  • enrichment_target (str, optional) – Single nuclide name to enrich from a natural composition (e.g., ‘O16’)

  • enrichment_type ({'ao', 'wo'}, optional) – ‘ao’ for enrichment as atom percent and ‘wo’ for weight percent. Default is: ‘ao’ for two-isotope enrichment; ‘wo’ for U enrichment

Notes

General enrichment procedure is allowed only for elements composed of two isotopes. If enrichment_target is given without enrichment natural composition is added to the material.

add_macroscopic(macroscopic: str)[source]

Add a macroscopic to the material. This will also set the density of the material to 1.0, unless it has been otherwise set, as a default for Macroscopic cross sections.

Parameters:

macroscopic (str) – Macroscopic to add

add_nuclide(nuclide: str, percent: float, percent_type: str = 'ao')[source]

Add a nuclide to the material

Parameters:

  • nuclide (str) – Nuclide to add, e.g., ‘Mo95’

  • percent (float) – Atom or weight percent

  • percent_type ({'ao', 'wo'}) – ‘ao’ for atom percent and ‘wo’ for weight percent

add_s_alpha_beta(name: str, fraction: float = 1.0)[source]

Add an \(S(\alpha,\beta)\) table to the material

Parameters:

  • name (str) – Name of the \(S(\alpha,\beta)\) table

  • fraction (float) – The fraction of relevant nuclei that are affected by the \(S(\alpha,\beta)\) table. For example, if the material is a block of carbon that is 60% graphite and 40% amorphous then add a graphite \(S(\alpha,\beta)\) table with fraction=0.6.

add_volume_information(volume_calc)[source]

Add volume information to a material.

Parameters:

volume_calc (openmc.VolumeCalculation) – Results from a stochastic volume calculation

clone(memo: dict | None = None) → Material[source]

Create a copy of this material with a new unique ID.

Parameters:

memo (dict or None) – A nested dictionary of previously cloned objects. This parameter is used internally and should not be specified by the user.

Returns:

clone – The clone of this material

Return type:

openmc.Material

deplete(multigroup_flux: Sequence[float], energy_group_structure: Sequence[float] | str, timesteps: Sequence[float] | Sequence[tuple[float, str]], source_rates: float | Sequence[float], timestep_units: str = 's', chain_file: cv.PathLike | 'openmc.deplete.Chain' | None = None, reactions: Sequence[str] | None = None) → list[openmc.Material][source]

Depletes that material, evolving the nuclide densities

Added in version 0.15.3.

Parameters:

  • multigroup_flux (Sequence[float]) – Energy-dependent multigroup flux values, where each sublist corresponds to a specific material. Will be normalized so that it sums to 1.

  • energy_group_structure (Sequence[float] | str) – Energy group boundaries in [eV] or the name of the group structure.

  • timesteps (iterable of float or iterable of tuple) – Array of timesteps. Note that values are not cumulative. The units are specified by the timestep_units argument when timesteps is an iterable of float. Alternatively, units can be specified for each step by passing an iterable of (value, unit) tuples.

  • source_rates (float or iterable of float, optional) – Source rate in [neutron/sec] or neutron flux in [neutron/s-cm^2] for each interval in timesteps

  • timestep_units ({'s', 'min', 'h', 'd', 'a', 'MWd/kg'}) – Units for values specified in the timesteps argument. ‘s’ means seconds, ‘min’ means minutes, ‘h’ means hours, ‘a’ means Julian years and ‘MWd/kg’ indicates that the values are given in burnup (MW-d of energy deposited per kilogram of initial heavy metal).

  • chain_file (PathLike or Chain) – Path to the depletion chain XML file or instance of openmc.deplete.Chain. Defaults to openmc.config['chain_file'].

  • reactions (list of str, optional) – Reactions to get cross sections for. If not specified, all neutron reactions listed in the depletion chain file are used.

Return type:

list of openmc.Material, one for each timestep

classmethod from_hdf5(group: Group) → Material[source]

Create material from HDF5 group

Parameters:

group (h5py.Group) – Group in HDF5 file

Returns:

Material instance

Return type:

openmc.Material

classmethod from_ncrystal(cfg, **kwargs) → Material[source]

Create material from NCrystal configuration string.

Density, temperature, and material composition, and (ultimately) thermal neutron scattering will be automatically be provided by NCrystal based on this string. The name and material_id parameters are simply passed on to the Material constructor.

Added in version 0.13.3.

Parameters:

  • cfg (str) – NCrystal configuration string

  • **kwargs – Keyword arguments passed to openmc.Material

Returns:

Material instance

Return type:

openmc.Material

classmethod from_xml_element(elem: Element) → Material[source]

Generate material from an XML element

Parameters:

elem (lxml.etree._Element) – XML element

Returns:

Material generated from XML element

Return type:

openmc.Material

get_activity(units: str = 'Bq/cm3', by_nuclide: bool = False, volume: float | None = None) → dict[str, float] | float[source]

Returns the activity of the material or of each nuclide within.

Added in version 0.13.1.

Parameters:

  • units ({'Bq', 'Bq/g', 'Bq/kg', 'Bq/cm3', 'Ci', 'Ci/m3'}) – Specifies the type of activity to return, options include total activity [Bq,Ci], specific [Bq/g, Bq/kg] or volumetric activity [Bq/cm3,Ci/m3]. Default is volumetric activity [Bq/cm3].

  • by_nuclide (bool) – Specifies if the activity should be returned for the material as a whole or per nuclide. Default is False.

  • volume (float, optional) –

    Volume of the material. If not passed, defaults to using the Material.volume attribute.

    Added in version 0.13.3.

Returns:

If by_nuclide is True then a dictionary whose keys are nuclide names and values are activity is returned. Otherwise the activity of the material is returned as a float.

Return type:

Union[dict, float]

get_decay_heat(units: str = 'W', by_nuclide: bool = False, volume: float | None = None) → dict[str, float] | float[source]

Returns the decay heat of the material or for each nuclide in the material in units of [W], [W/g], [W/kg] or [W/cm3].

Added in version 0.13.3.

Parameters:

  • units ({'W', 'W/g', 'W/kg', 'W/cm3'}) – Specifies the units of decay heat to return. Options include total heat [W], specific [W/g, W/kg] or volumetric heat [W/cm3]. Default is total heat [W].

  • by_nuclide (bool) – Specifies if the decay heat should be returned for the material as a whole or per nuclide. Default is False.

  • volume (float, optional) –

    Volume of the material. If not passed, defaults to using the Material.volume attribute.

    Added in version 0.13.3.

Returns:

If by_nuclide is True then a dictionary whose keys are nuclide names and values are decay heat is returned. Otherwise the decay heat of the material is returned as a float.

Return type:

Union[dict, float]

get_decay_photon_energy(clip_tolerance: float = 1e-06, units: str = 'Bq', volume: float | None = None) → Univariate | None[source]

Return energy distribution of decay photons from unstable nuclides.

Added in version 0.14.0.

Parameters:

  • clip_tolerance (float) – Maximum fraction of \(\sum_i x_i p_i\) for discrete distributions that will be discarded.

  • units ({'Bq', 'Bq/g', 'Bq/kg', 'Bq/cm3'}) – Specifies the units on the integral of the distribution.

  • volume (float, optional) – Volume of the material. If not passed, defaults to using the Material.volume attribute.

Returns:

Decay photon energy distribution. The integral of this distribution is the total intensity of the photon source in the requested units.

Return type:

Univariate or None

get_element_atom_densities(element: str | None = None) → dict[str, float][source]

Returns one or all elements in the material and their atomic densities in units of atom/b-cm

Added in version 0.15.1.

Parameters:

element (str, optional) – Element for which atom density is desired. If not specified, the atom density for each element in the material is given.

Returns:

elements – Dictionary whose keys are element names and values are densities in [atom/b-cm]

Return type:

dict

get_elements() → list[str][source]

Returns all elements in the material

Added in version 0.12.

Returns:

elements – List of element names

Return type:

list of str

get_mass(nuclide: str | None = None, volume: float | None = None) → float[source]

Return mass of one or all nuclides.

Note that this method requires that the Material.volume has already been set.

Parameters:

  • nuclides (str, optional) – Nuclide for which mass is desired. If not specified, the density for the entire material is given.

  • volume (float, optional) –

    Volume of the material. If not passed, defaults to using the Material.volume attribute.

    Added in version 0.13.3.

Returns:

Mass of the nuclide/material in [g]

Return type:

float

get_mass_density(nuclide: str | None = None) → float[source]

Return mass density of one or all nuclides

Parameters:

nuclides (str, optional) – Nuclide for which density is desired. If not specified, the density for the entire material is given.

Returns:

Density of the nuclide/material in [g/cm^3]

Return type:

float

get_nuclide_atom_densities(nuclide: str | None = None) → dict[str, float][source]

Returns one or all nuclides in the material and their atomic densities in units of atom/b-cm

Changed in version 0.13.1: The values in the dictionary were changed from a tuple containing the nuclide name and the density to just the density.

Parameters:

nuclides (str, optional) –

Nuclide for which atom density is desired. If not specified, the atom density for each nuclide in the material is given.

Added in version 0.13.2.

Returns:

nuclides – Dictionary whose keys are nuclide names and values are densities in [atom/b-cm]

Return type:

dict

get_nuclide_atoms(volume: float | None = None) → dict[str, float][source]

Return number of atoms of each nuclide in the material

Added in version 0.13.1.

Parameters:

volume (float, optional) –

Volume of the material. If not passed, defaults to using the Material.volume attribute.

Added in version 0.13.3.

Returns:

Dictionary whose keys are nuclide names and values are number of atoms present in the material.

Return type:

dict

get_nuclide_densities() → dict[str, tuple][source]

Returns all nuclides in the material and their densities

Returns:

nuclides – Dictionary whose keys are nuclide names and values are 3-tuples of (nuclide, density percent, density percent type)

Return type:

dict

get_nuclides(element: str | None = None) → list[str][source]

Returns a list of all nuclides in the material, if the element argument is specified then just nuclides of that element are returned.

Parameters:

element (str) –

Specifies the element to match when searching through the nuclides

Added in version 0.13.2.

Returns:

nuclides – List of nuclide names

Return type:

list of str

mean_free_path(energy: float) → float[source]

Calculate the mean free path of neutrons in the material at a given energy.

Added in version 0.15.3.

Parameters:

energy (float) – Neutron energy in eV

Returns:

Mean free path in cm

Return type:

float

classmethod mix_materials(materials, fracs: Iterable[float], percent_type: str = 'ao', **kwargs) → Material[source]

Mix materials together based on atom, weight, or volume fractions

Added in version 0.12.

Parameters:

  • materials (Iterable of openmc.Material) – Materials to combine

  • fracs (Iterable of float) – Fractions of each material to be combined

  • percent_type ({'ao', 'wo', 'vo'}) – Type of percentage, must be one of ‘ao’, ‘wo’, or ‘vo’, to signify atom percent (molar percent), weight percent, or volume percent, optional. Defaults to ‘ao’

  • **kwargs – Keyword arguments passed to openmc.Material

Returns:

Mixture of the materials

Return type:

openmc.Material

remove_element(element)[source]

Remove an element from the material

Added in version 0.13.1.

Parameters:

element (str) – Element to remove

remove_macroscopic(macroscopic: str)[source]

Remove a macroscopic from the material

Parameters:

macroscopic (str) – Macroscopic to remove

remove_nuclide(nuclide: str)[source]

Remove a nuclide from the material

Parameters:

nuclide (str) – Nuclide to remove

set_density(units: str, density: float | None = None)[source]

Set the density of the material

Parameters:

  • units ({'g/cm3', 'g/cc', 'kg/m3', 'atom/b-cm', 'atom/cm3', 'sum', 'macro'}) – Physical units of density.

  • density (float, optional) – Value of the density. Must be specified unless units is given as ‘sum’.

to_xml_element(nuclides_to_ignore: Iterable[str] | None = None) → Element[source]

Return XML representation of the material

Parameters:

nuclides_to_ignore (list of str) – Nuclides to ignore when exporting to XML.

Returns:

element – XML element containing material data

Return type:

lxml.etree._Element

waste_classification(metal: bool = False) → str[source]

Classify the material for near-surface waste disposal.

This method determines a waste classification for the material based on the NRC regulations (10 CFR 61.55). Note that the NRC regulations do not consider many long-lived radionuclides relevant to fusion systems; for fusion applications, it is recommended to calculate a waste disposal rating based on limits by Fetter et al. using the waste_disposal_rating() method.

Parameters:

metal (bool, optional) – Whether or not the material is in metal form.

Returns:

The waste disposal classification, which can be “Class A”, “Class B”, “Class C”, or “GTCC” (greater than class C).

Return type:

str

waste_disposal_rating(limits: str | dict[str, float] = 'Fetter', metal: bool = False, by_nuclide: bool = False) → float | dict[str, float][source]

Return the waste disposal rating for the material.

This method returns a waste disposal rating for the material based on a set of specific activity limits. The waste disposal rating is a single number that represents the sum of the ratios of the specific activity for each radionuclide in the material against a nuclide-specific limit. A value less than 1.0 indicates that the material “meets” the limits whereas a value greater than 1.0 exceeds the limits.

Note that the limits for NRC do not consider many long-lived radionuclides relevant to fusion systems. A paper by Fetter et al. applies the NRC methodology to calculate specific activity limits for an expanded set of radionuclides.

Parameters:

  • limits (str or dict, optional) –

    The name of a predefined set of specific activity limits or a dictionary that contains specific activity limits for radionuclides, where keys are nuclide names and values are activities in units of [Ci/m3]. The predefined options are:

    • ’Fetter’: Uses limits from Fetter et al. (1990)

    • ’NRC_long’: Uses the 10 CFR 61.55 limits for long-lived radionuclides

    • ’NRC_short_A’: Uses the 10 CFR 61.55 class A limits for short-lived radionuclides

    • ’NRC_short_B’: Uses the 10 CFR 61.55 class B limits for short-lived radionuclides

    • ’NRC_short_C’: Uses the 10 CFR 61.55 class C limits for short-lived radionuclides

  • metal (bool, optional) – Whether or not the material is in metal form (only applicable for NRC based limits)

  • by_nuclide (bool, optional) – Whether to return the waste disposal rating for each nuclide in the material. If True, a dictionary is returned where the keys are the nuclide names and the values are the waste disposal ratings for each nuclide. If False, a single float value is returned that represents the overall waste disposal rating for the material.

Returns:

The waste disposal rating for the material or its constituent nuclides.

Return type:

float or dict

See also

Material.waste_classification