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

    New in version 0.13.3.

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

Add multiple elements or nuclides to a material

New 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: Optional[float] = None, enrichment_target: Optional[str] = None, enrichment_type: Optional[str] = None, cross_sections: Optional[str] = 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’)

    New 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

    New 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: Optional[float] = None, enrichment_target: Optional[str] = None, enrichment_type: Optional[str] = None)[source]

Add a elements from a chemical formula to the material.

New 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: Optional[dict] = 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

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.

New 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: Optional[float] = None) Union[Dict[str, float], float][source]

Returns the activity of the material or for each nuclide in the material in units of [Bq], [Bq/g] or [Bq/cm3].

New in version 0.13.1.

Parameters
  • units ({'Bq', 'Bq/g', 'Bq/cm3'}) – Specifies the type of activity to return, options include total activity [Bq], specific [Bq/g] or volumetric activity [Bq/cm3]. 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.

    New 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: Optional[float] = None) Union[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] or [W/cm3].

New in version 0.13.3.

Parameters
  • units ({'W', 'W/g', 'W/cm3'}) – Specifies the units of decay heat to return. Options include total heat [W], specific [W/g] 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.

    New 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: Optional[float] = None) Optional[Univariate][source]

Return energy distribution of decay photons from unstable nuclides.

New 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/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.

get_elements() List[str][source]

Returns all elements in the material

New in version 0.12.

Returns

elements – List of element names

Return type

list of str

get_mass(nuclide: Optional[str] = None, volume: Optional[float] = 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.

    New in version 0.13.3.

Returns

Mass of the nuclide/material in [g]

Return type

float

get_mass_density(nuclide: Optional[str] = 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: Optional[str] = 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.

New 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: Optional[float] = None) Dict[str, float][source]

Return number of atoms of each nuclide in the material

New in version 0.13.1.

Parameters

volume (float, optional) –

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

New 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: Optional[str] = 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

New in version 0.13.2.

Returns

nuclides – List of nuclide names

Return type

list of str

classmethod mix_materials(materials, fracs: Iterable[float], percent_type: str = 'ao', name: Optional[str] = None) Material[source]

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

New 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’

  • name (str) – The name for the new material, optional. Defaults to concatenated names of input materials with percentages indicated inside parentheses.

Returns

Mixture of the materials

Return type

openmc.Material

remove_element(element)[source]

Remove an element from the material

New 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: Optional[float] = 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: Optional[Iterable[str]] = 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