# Materials – pyne.material¶

This module contains the Material class, which is used to represent nuclear materials throughout PyNE.

All functionality may be found in the material package:

from pyne import material


Materials are the primary container for radionuclides. They map nuclides to mass weights, though they contain methods for converting to/from atom fractions as well. In many ways they take inspiration from numpy arrays and python dictionaries. Materials have two main attributes which define them.

1. comp: a normalized composition mapping from nuclides (zzaaam-ints) to mass-weights (floats).
2. mass: the mass of the material.

## Material Class¶

class pyne.material.Material

Material composed of nuclides.

Parameters: comp : dict or str This is the input nuclide component dictionary. This dictionary need not be normalized; Material initialization will automatically renormalize the stream. Thus the comp simply is a dictionary of relative mass. The keys of comp must be integers representing nuclides in id-form. The values are floats for each nuclide’s mass fraction. If a string is provided instead of a dictionary, then Material will read in the comp vector from a file at the string’s location. This either plaintext or hdf5 files. If no comp is provided, an empty Material object is constructed. mass : float, optional This is the mass of the new stream. If the mass provided is negative (default -1.0) then the mass of the new stream is calculated from the sum of compdict’s components before normalization. If the mass here is positive or zero, then this mass overrides the calculated one. density : float, optional This is the density of the material. atoms_per_molecule : float, optional Number of atoms to per molecule of material. Needed to obtain proper scaling of molecular mass. For example, this value for water is 3.0. metadata : JSON-convertable Python object, optional Initial attributes to build the material with. At the top-level this is usually a dictionary with string keys. This container is used to store arbitrary metadata about the material. free_mat : bool, optional Flag for whether this wrapper ‘owns’ this underlying C++ pyne::Material object, and thus determines whether or not to deallocate it on wrapper destruction.
activity()

This provides the activity of the comp of the material.

Returns: nucvec : dict For a Material mat
alara(self)

This method returns an ALARA material in string form, with relevant attributes as ALARA valid comments.

Returns: s : str The MCNP material card.
clear() → None. Remove all items from D.
collapse_elements(self, nucset)

Collapses the elements in the material, excluding the nucids in the set nucset. This function returns a copy of the material.

Parameters: nucset : set, optional A set of integers representing nucids which should not be collapsed. newmat : Material A copied and collapsed material.
cram()

Transmutes the material via the CRAM method.

Parameters: A : 1D array-like The transmutation matrix [unitless] order : int, optional The CRAM approximation order (default 14). A new material which has been transmuted.
decay(double t)

Decays a material for a time t, in seconds. Returns a new material.

decay_heat()

This provides the decay heat using the comp of the the Material. It assumes that the composition of material is given in units of [grams] and returns decay heat in units of [MW].

Returns: nucvec : dict For a Material mat
del_mat(nuc_sequence)

Removes a subset of the material and returns a new material comprised of only the non-specified nuclides.

Parameters: nuc_sequence : sequence Nuclides to be taken out of the current material. submaterial : Material A new material object that only has the members not given in nuc_sequence. The mass of the submaterial is calculated based on the mass fraction composition and mass of the original material.

Notes

The input here is seen as a suggestion and so no error is raised if a nuclide is asked for via nuc_sequence that is not present in the original material.

del_range(lower=0, upper=INT_MAX)

Remove a range [lower, upper) of nuclides from this material and returns a submaterial.

Parameters: lower : nuclide-name, optional Lower bound on nuclide range. upper : nuclide-name, optional Upper bound on nuclide range. submaterial : Material A new mass stream object that does not contain nuclides on the given range.
dose_per_g()

This provides the dose per gram using the comp of the the Material.

Parameters: dose_type : string One of: ext_air, ext_soil, ingest, inhale source : int optional; default is EPA 0 for EPA, 1 for DOE, 2 for GENII nucvec : dict For a Material mat: ext_air_dose returns mrem/h per g per m^3 ext_soil_dose returns mrem/h per g per m^2 ingest_dose returns mrem per g inhale_dose returns mrem per g
dump_json()

Dumps the material to a JSON object.

Returns: val : jsoncpp.Value An object-type JSON value.
expand_elements(self)

Expands the elements (‘U’, ‘C’, etc) in the material by replacing them with their natural isotopic distributions with the exception of the ids in nucset. This function returns a copy.

Parameters: nucset : set, optional A set of integers representing nucids which should not be expanded. newmat : Material A copied and expanded material.
fluka()

Return a fluka material record if there is only one component, otherwise return the compound material record and the fluka compound record Parameters ———-

The sequential material id starting from 26 unless predefined
fluka_compound_str()

Return the FLUKA MATERIAL record for the compound, and the FLUKA COMPOUND record for the components Parameters ———-

The sequential compound id starting from 26 unless predefined
fluka_format_field()

Return a string for a single field in the FLUKA MATERIAL record Parameters ———-

The field value
fluka_material_component()

Return the FLUKA MATERIAL record with the given id, nucid and name. Parameters ———-

The sequential material id, the (single) nucid, and the fluka name
fluka_material_line()

Return the FLUKA MATERIAL record with the given znum, atomic mass, id, and fluka name Parameters ———-

The znum, atomic mass, material id, and the fluka name
fluka_material_str()

Return the FLUKA MATERIAL record with the given id. A single-component material is expected Parameters ———-

The sequential material id starting from 26 unless predefined
from_atom_frac(atom_fracs)

Loads the material composition based on a mapping of atom fractions.

Parameters: atom_fracs : dict Dictionary that maps nuclides or materials to atom fractions for the material. The keys may be intergers, strings, or materials. The values must be castable to floats.

Examples

To get a material from water, based on atom fractions:

h2o = {10010: 2.0, 'O16': 1.0}
mat = Material()
mat.from_atom_frac(h2o)


Or for Uranium-Oxide, based on an initial fuel vector:

# Define initial heavy metal
ihm = Material()
ihm.from_atom_frac({'U235': 0.05, 'U238': 0.95})

# Define Uranium-Oxide
uox = {ihm: 1.0, 80160: 2.0}
mat = Material()
mat.from_atom_frac(uox)


Note that the initial heavy metal was used as a key in a dictionary. This is possible because Materials are hashable.

from_hdf5(char * filename, char * datapath, int row=-1, int protocol=1)

Initialize a Material object from an HDF5 file.

Parameters: filename : str Path to HDF5 file that contains the data to read in. datapath : str Path to HDF5 table or group that represents the data. In the example below, datapath = “/material”. row : int, optional The index of the arrays from which to read the data. This ranges from 0 to N-1. Defaults to the last element of the array. Negative indexing is allowed (row[-N] = row[0]). protocol : int, optional Specifies the protocol to use to read in the data. Different protocols are used to represent different internal structures in the HDF5 file.

Notes

There are currently two protocols which are implemented for how to store materials inside of an HDF5 file. Protocol 0 is the older, deprecated method using a group of arrays. Protocol 1 is the newer, prefered method which uses a table of materials plus a side array of nuclides.

The Protocol 0 HDF5 representation of a Material is a group that holds several extendable array datasets. One array is entitled “Mass” while the other datasets are nuclide names in name form (“U235”, “NP237”, etc). For example:

file.h5 (file)
|-- material (group)
|-- Mass (array)
|-- H1 (array)
|-- O16 (array)
|-- U235 (array)
|-- PU239 (array)
|-- ...


The arrays are all of length N, where each row typically represents a different fuel cycle pass. The sum of all of the nuclide arrays should sum to one, like Material.comp. This method is deprecated.

Protocol 1 is the newer, more efficient protocol for storing many materials. It consists of a table which stores the material information and an array that stores the nuclides (id) which index the comp array:

file.h5 (file)
|-- material (table)
|-- mass (double col)
|-- density (double col)
|-- atoms_per_molecule (double col)
|-- comp (double array col, len of nuc_zz)
|-- nuc_zz (int array)
|-- material_attr (variable length char array)


The material table has a string attribute called ‘nucpath’ which holds the path to the nuclide array inside this HDF5 file. The same nucpath may be used for multiple material tables. The length of the nucpath must match the length of the comp arrays.

Examples

This method loads data into a pre-existing Material. Initialization is therefore a two-step process:

mat = Material()
mat.from_hdf5("afile.h5", "/foo/bar/mat", -3)

from_json(char * filename)

Initialize a Material object from a JSON file.

Parameters: filename : str Path to text file that contains the data to read in.
from_text(char * filename)

Initialize a Material object from a simple text file.

Parameters: filename : str Path to text file that contains the data to read in.

Notes

The text representation of Materials are nuclide identifiers in the first column and mass or weight values in the second column. For example, for natural uranium:

922340  0.000055
U235    0.00720
92238   0.992745


Data in this file must be whitespace separated. Any valid nuclide naming scheme may be used for the nuclide identifiers. Moreover, material metadata may be optionally supplied:

Name    NatU
Mass    42.0
APerM   1
922340  0.000055
U235    0.00720
92238   0.992745


Examples

This method loads data into a pre-existing Material. Initialization is therefore a two-step process:

mat = Material()
mat.from_text("natu.txt")


This method is most often called implicitly by the Material constructor.

gammas()

Returns a vector of gamma rays and intensities in decays/s/atom material

Returns: gammas : a vector of pairs of gamma-rays and intensities. The intensities are in decays/s/atom material
get(k[, d]) → D[k] if k in D, else d. d defaults to None.
items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D
keys() → list of D's keys
load_json(json)

Loads a JSON instance into this Material.

Parameters: json : jsoncpp.Value An object-type JSON value.
mass_density(self, num_dens=-1.0, atoms_per_molecule=-1.0)

Computes, sets, and returns the mass density when num_dens is greater than or equal zero. If num_dens is negative, this simply returns the current value of the density attribute.

Parameters: num_dens : float, optional The number density from which to compute the mass density in units of [1/cc]. atoms_per_molecule : float, optional Number of atoms to per molecule of material. For example, this value for water is 3.0. density : float The density attr [g/cc].
mcnp(frac_type)

Return an mcnp card Parameters ———-

int 0 means use “mass” as the frac_type
molecular_mass(atoms_per_molecule=-1.0)

This method returns the molecular mass of the comp of this material.

Parameters: atoms_per_molecule : double, optional Number of atoms to per molecule of material. Needed to obtain proper scaling. For example, this value for water is 3.0. mol_mass : float Molecular mass in [amu].
mult_by_mass()

This multiplies comp by mass and returns the resultant nuctopic vector.

Returns: nucvec : dict For a Material mat, $\mbox{nucvec[nuc]} = \mbox{mat.comp[nuc]} \times \mbox{mat.mass}$
norm_comp()

Normalizes the composition, preserving the mass of the nuclide vector as mass.

normalize()

This convenience method normalizes the mass stream by setting its mass = 1.0.

not_fluka_builtin()

Return whether a string is in the fluka built-in list Parameters ———-

A string representing a FLUKA material name
number_density(self, mass_dens=-1.0, atoms_per_molecule=-1.0)

Computes and returns the number density from the mass_dens argument if this is greater than or equal zero. If mass_dens is negative, then the number density is computed using the current value of the density attribute.

Parameters: mass_dens : float, optional The mass density from which to compute the number density in units of [g/cc]. atoms_per_molecule : float, optional Number of atoms to per molecule of material. For example, this value for water is 3.0. num_dens : float The number density [1/cc] of the material.
openmc(frac_type)

Return an openmc xml element for the material

photons()

Returns a vector of photons and intensities in decays/s/atom material. This vector is the combination of X-rays and gamma-rays produced in the decay of the material.

Parameters: norm : boolean Whether or not to normalize the returned data if True then intensities photons : a vector of pairs of photon energies and intensities. The intensities are in decays/s/atom material
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

set_mat(nuc_sequence, value)

Sets a subset of the material to a new value and returns a new material.

Parameters: nuc_sequence : sequence Nuctopes –OR– elements to be taken from current stream. Members of this list must be integers. For example, [922350, 942390] would take U-235 and Pu-239. value : float Mass value to set all nuclides in sequence to on the material. submaterial : Material A new material object whose members in nuc_sequence have the cooresponding mass value. The mass of the submaterial is calculated based on the mass fraction composition and mass of the original material.
set_range(lower=0, upper=INT_MAX, value=0.0)

Sets a sub-material from this mat based on a range [lower, upper) to a new mass weight value.

Parameters: lower : nuclide-name, optional Lower bound on nuclide range. upper : nuclide-name, optional Upper bound on nuclide range. value : float Mass value to set all nuclides on the range to on the material. submaterial : Material A new mass stream object that only has nuclides on the given range.
setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
sub_act()

Convenience method that gets the Actinide portion of a mass stream.

Returns: submaterial : Material A new mass stream object that only has Actinide members.
sub_elem(element)

Grabs a subset of the material and returns a new material comprised of only the nuclides of the specified element.

Returns: submaterial : Material A new mass stream object that only has members of the given element.
sub_fp()

Convenience method that gets the Fission Product portion of a mass stream.

Returns: submaterial : Material A new mass stream object that only has Fission Product members.
sub_lan()

Convenience method that gets the Lanthanide portion of a mass stream.

Returns: submaterial : Material A new mass stream object that only has Lanthanide members.
sub_ma()

Convenience method that gets the Minor Actinide portion of a mass stream.

Returns: submaterial : Material A new mass stream object that only has Minor Actinide members.
sub_mat(nuc_sequence)

Grabs a subset of the material and returns a new material comprised of only the specified nuclides.

Parameters: nuc_sequence : sequence Nuctopes –OR– elements to be taken from current stream. Members of this list must be integers. For example, [922350, 942390] would take U-235 and Pu-239. submaterial : Material A new mass stream object that only has the members given in nuc_sequence. The mass of the submaterial is calculated based on the mass fraction composition and mass of the original mass stream.

Notes

The input here is seen as a suggestion and so no error is raised if a nuclide is asked for via nuc_sequence that is not present in the original material.

sub_pu()

Convenience method that gets the Plutonium portion of a mass stream.

Returns: submaterial : Material A new mass stream object that only has Plutonium members.
sub_range(lower=0, upper=INT_MAX)

Grabs a sub-material from this mat based on a range [lower, upper) of values.

Parameters: lower : nuclide-name, optional Lower bound on nuclide range. upper : nuclide-name, optional Upper bound on nuclide range. submaterial : Material A new mass stream object that only has nuclides on the given range.
sub_tru()

Convenience method that gets the Transuranic portion of a mass stream.

Returns: submaterial : Material A new mass stream object that only has Transuranic members.
sub_u()

Convenience method that gets the Uranium portion of a mass stream.

Returns: submaterial : Material A new mass stream object that only has Uranium members.
to_atom_dens()

Converts the material to a map of nuclides to atom densities.

Returns: atom_dens : mapping Dictionary-like object that maps nuclides to atom densites in the material.
to_atom_frac()

Converts the material to a map of nuclides to atom fractions.

Returns: atom_fracs : mapping Dictionary-like object that maps nuclides to atom fractions in the material.
update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values
write_alara(self, filename)

The method appends an ALARA material d\$efinition, with attributes to the file with the supplied filename.

Parameters: filename : str The file to append the material definition to.
write_hdf5(filename, datapath="/material", nucpath="/nucid", row=-0.0, chunksize=100)

Writes the material to an HDF5 file, using Protocol 1 (see the from_hdf5() method).

Parameters: filename : str Path to HDF5 file to write the data out to. If the file does not exist, it will be created. datapath : str, optional Path to HDF5 table that represents the data. If the table does not exist, it will be created. nucpath : str, optional Path to id array of nuclides to write out. If this array does not exist, it is created with the nuclides present in this material. Nuclides present in this material but not in nucpath will not be written out. row : float, optional The row index of the HDF5 table to write this material to. This ranges from 0 to N. Negative indexing is allowed (row[-N] = row[0]). Defaults to the appending this material to the table (row[N] = row[-0.0]). This value must be a float since in integer repesentation 0 is -0, but in float representation 0.0 is not -0.0. chunksize : int, optional In Protocol 1, materials are stored in an HDF5 table which is an extensible data type. The chunksize determines the number of rows per chunk. For better performance, this number should be as close as possible to the final table size. This parameter is only relevant if a new table is being created.

Examples

The following writes out ten low-enriched uranium materials to a new table:

leu = Material({'U235': 0.04, 'U238': 0.96}, 4.2, "LEU", 1.0)
leu.write_hdf5('proto1.h5', chunksize=10)

for i in range(2, 11):
leu = Material({'U235': 0.04, 'U238': 0.96}, i*4.2, "LEU",
1.0*i)
leu.write_hdf5('proto1.h5')

write_json(filename)

Writes the material to a JSON file.

Parameters: filename : str Path to text file to write the data to. If the file already exists, it will be overwritten.

Examples

The following writes out a low-enriched uranium material to a new file:

leu = Material({'U235': 0.04, 'U238': 0.96}, 42.0, "LEU", 1.0)
leu.write_json('leu.json')

write_mcnp(self, filename, frac_type='mass')

The method appends an MCNP mass fraction definition, with attributes to the file with the supplied filename.

Parameters: filename : str The file to append the material definition to. frac_type : str, optional Either ‘mass’ or ‘atom’. Speficies whether mass or atom fractions are used to describe material composition.
write_openmc(self, filename, frac_type='mass')

The method appends an OpenMC mass fraction definition, with attributes to the file with the supplied filename.

Parameters: filename : str The file to append the material definition to. frac_type : str, optional Either ‘mass’ or ‘atom’. Speficies whether mass or atom fractions are used to describe material composition.
write_text(filename)

Writes the material to a plain text file.

Parameters: filename : str Path to text file to write the data to. If the file already exists, it will be overwritten.

Examples

The following writes out a low-enriched uranium material to a new file:

leu = Material({'U235': 0.04, 'U238': 0.96}, 42.0, "LEU", 1.0)
leu.write_text('leu.txt')

xrays()

Returns a vector of X rays and intensities in decays/s/atom material. Includes only X rays from internal conversion and electron capture

Returns: x-rays : a vector of pairs of X-rays and intensities. The intensities are in decays/s/atom material

## Material Generation Functions¶

The following top-level module functions are used to generate materials from various sources.

pyne.material.from_atom_frac(atom_fracs, double mass=-1.0, double atoms_per_molecule=-1.0)

Create a Material from a mapping of atom fractions.

Parameters: atom_fracs : dict Dictionary that maps nuclides or materials to atom fractions for the material. The keys may be intergers, strings, or materials. The values must be castable to floats. mass : float, optional This is the mass of the new stream. If the mass provided is negative (default -1.0) then the mass of the new stream is calculated from the sum of compdict’s components before normalization. If the mass here is positive or zero, then this mass overrides the calculated one. density : float, optional This is the density of the material. atoms_per_molecule : float, optional Number of atoms per molecule of material. Needed to obtain proper scaling of molecular mass. For example, this value for water is 3.0. metadata : JSON-convertable Python object, optional Initial attributes to build the material with. At the top-level this is usually a dictionary with string keys. This container is used to store arbitrary metadata about the material. mat : Material A material generated from atom fractions.

Material.from_atom_frac
Underlying method class method.

Examples

To get a material from water, based on atom fractions:

h2o = {10010: 2.0, 'O16': 1.0}
mat = from_atom_frac(h2o)


Or for Uranium-Oxide, based on an initial fuel vector:

# Define initial heavy metal
ihm = from_atom_frac({'U235': 0.05, 'U238': 0.95})

# Define Uranium-Oxide
uox = {ihm: 1.0, 80160: 2.0}
mat = from_atom_frac(uox)


Note that the initial heavy metal was used as a key in a dictionary. This is possible because Materials are hashable.

pyne.material.from_hdf5(char * filename, char * datapath, int row=-1, int protocol=1)

Create a Material object from an HDF5 file.

Parameters: filename : str Path to HDF5 file that contains the data to read in. datapath : str Path to HDF5 table or group that represents the data. row : int, optional The index of the arrays from which to read the data. This ranges from 0 to N-1. Defaults to the last element of the array. Negative indexing is allowed (row[-N] = row[0]). protocol : int, optional Specifies the protocol to use to read in the data. Different protocols are used to represent different internal structures in the HDF5 file. mat : Material A material found in the HDF5 file.

Material.from_hdf5
Underlying method class method.

Examples

This method loads data into a new material:

mat = from_hdf5("afile.h5", "/foo/bar/mat", -3)


pyne.material.from_text(char * filename, double mass=-1.0, double atoms_per_molecule=-1.0)

Create a Material object from a simple text file.

Parameters: filename : str Path to text file that contains the data to read in. mass : float, optional This is the mass of the new stream. If the mass provided is negative (default -1.0) then the mass of the new stream is calculated from the sum of compdict’s components before normalization. If the mass here is positive or zero, then this mass overrides the calculated one. atoms_per_molecule : float, optional Number of atoms to per molecule of material. Needed to obtain proper scaling of molecular mass. For example, this value for water is 3.0. metadata : JSON-convertable Python object, optional Initial attributes to build the material with. At the top-level this is usually a dictionary with string keys. This container is used to store arbitrary metadata about the material. mat : Material A material found in the HDF5 file.

Material.from_text
Underlying method class method.

Examples

This method loads data into a new Material:

mat = from_text("natu.txt")


## Material Library¶

class pyne.material.MaterialLibrary(lib=None, datapath="/materials", nucpath="/nucid")

The material library is a collection of unique keys mapped to Material objects. This is useful for organization and declaring prefernces between several sources (multiple libraries).

Parameters: lib : dict-like, str, or None, optional The data to intialize the material library with. If this is a string, it is interpreted as a path to a file. datapath : str, optional The path in the heirarchy to the data table in an HDF5 file. nucpath : str, optional The path in the heirarchy to the nuclide array in an HDF5 file.
clear() → None. Remove all items from D.
from_hdf5()

Loads data from an HDF5 file into this material library.

Parameters: file : str A path to an HDF5 file. datapath : str, optional The path in the heirarchy to the data table in an HDF5 file. nucpath : str, optional The path in the heirarchy to the nuclide array in an HDF5 file.
from_json()

Loads data from a JSON file into this material library.

Parameters: file : str A path to a JSON file.
get(k[, d]) → D[k] if k in D, else d. d defaults to None.
items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D
keys() → list of D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values
write_hdf5()

Writes this material library to an HDF5 file.

Parameters: filename : str A path to an HDF5 file. datapath : str, optional The path in the heirarchy to the data table in an HDF5 file. nucpath : str, optional The path in the heirarchy to the nuclide array in an HDF5 file.
write_json()

Writes this material library to a JSON file.

Parameters: file : str A path to a JSON file.