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 mixtures of radionuclides. They map nuclides to mass fractions, 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-fractions (floats).

2. mass: the mass of the material.

The Material Libraries – pyne.material_library class is available to efficiently manipulate collections of materials. The material class is presented below. For more information please refer to Materials.

HDF5 File Structure

When using the write_hdf5 method to write a material in a group named my_mat (the user shall provide the name for this group in argument datapath), the default structure for the HDF5 file is: .. verbatim:

/material/
/--------/my_mat/
         /------/composition
         /------/nuclidelist
         /------/composition_metadata

Where, /material and /material/my_mat are HDF5 groups, and composition, nuclidelist and composition_metadata are HDF5 datasets.

The Material Libraries – pyne.material_library class is available to efficiently manipulate collections of materials.

Previous HDF5 File Structure

In files created with previous versions, it’s possible that the datapath or /material already exist as a dataset in the file. In such cases, the old writing method will be used. Older data structure are deprecated but still available to written when providing a

nucpath to the

write_hdf5() method, or when writing a material in a file with the old data structure. Old data structure looks like: .. verbatim:

/my_mat/
/------/nucpath
/my_mat_metadata
/nuclidelist

my_mat (the datapath – default material) is a HDF5 dataset containing the material composition, nucpath is a attribute containing the path to the nuclide list. The attribute is attached to the datapath. my_mat_metadata is a dataset containing the metadata of the material. nuclidelist is a dataset containing the list of nuclides composition the material.

from_hdf5() will detect the structure (old or new) of the file (when using protocol1).

The material class is presented below.

For more information please refer to :ref:`usersguide_material`.

Material Class

class pyne.material.Material(comp, mass=- 1.0, atoms_per_mol=- 1.0, attrs=None)

Material composed of nuclides.

Parameters

compdict 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.

massfloat, 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.

densityfloat, optional

This is the density of the material.

atoms_per_moleculefloat, 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.

metadataJSON-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_matbool, 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. It assumes

that the mass of the material is given in units of [grams] and returns activities in units of [Bq].

Returns

nucvecdict

For a Material mat

alara(self)

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

Returns

sstr

The MCNP material card.

clear(self)

collapse_elements()

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

Parameters

nucsetset, optional

A set of integers representing nucids which should not be collapsed.

Returns

newmatMaterial

A copied and collapsed material.

cram()

Transmutes the material via the CRAM method.

Parameters

A1D array-like

The transmutation matrix [unitless]

orderint, optional

The CRAM approximation order (default 14).

Returns

A new material which has been transmuted.

decay()

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

nucvecdict

For a Material mat

del_mat()

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

Parameters

nuc_sequencesequence

Nuclides to be taken out of the current material.

Returns

submaterialMaterial

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()

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

Parameters

lowernuclide-name, optional

Lower bound on nuclide range.

uppernuclide-name, optional

Upper bound on nuclide range.

Returns

submaterialMaterial

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_typestring

One of: ext_air, ext_soil, ingest, inhale

sourceint

optional; default is EPA 0 for EPA, 1 for DOE, 2 for GENII

Returns

nucvecdict

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

valjsoncpp.Value

An object-type JSON value.

expand_elements()

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

nucsetset, optional

A set of integers representing nucids which should not be expanded.

Returns

newmatMaterial

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

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_activity()

Loads the material composition based on a mapping of radionuclide activities. It assumes that activities are supplied in units of [Bq] and sets the material mass to units of [grams].

Parameters

activitiesdict

Dictionary that maps radionuclides to activities for the material. The keys may be intergers or strings. The values must be castable to floats.

Examples

To get a material of natural uranium, based on activities:

natu = {'U234': 12223.2, 'U235': 568.648, 'U238': 12347.1}
mat = Material()
mat.from_activity(natu)

from_atom_frac()

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

Parameters

atom_fracsdict

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()

Initialize a Material object from an HDF5 file.

Parameters

filenamestr

Path to HDF5 file that contains the data to read in.

datapathstr

Path to HDF5 table or group that represents the data. In the example below, datapath = “/mat_name”.

rowint, 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]).

protocolint, 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()

Initialize a Material object from a JSON file.

Parameters

filenamestr

Path to text file that contains the data to read in.

from_text()

Initialize a Material object from a simple text file.

Parameters

filenamestr

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

gammasa vector of pairs of gamma-rays and intensities. The

intensities are in decays/s/atom material

get(self, key, default=None)

get_uwuw_name()

Return a uwuw material name

items(self)

keys(self)

load_json()

Loads a JSON instance into this Material.

Parameters

jsonjsoncpp.Value

An object-type JSON value.

mass_density()

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_densfloat, optional

The number density from which to compute the mass density in units of [1/cc].

atoms_per_moleculefloat, optional

Number of atoms to per molecule of material. For example, this value for water is 3.0.

Returns

densityfloat

The density attr [g/cc].

mcnp(frac_type='mass', mult_den=True) Return an mcnp card Parameters ---------- frac_type : str, optional Either 'mass' or 'atom'. Speficies whether mass or atom fractions are used to describe material composition. (default 'mass') mult_den : bool, optional Flag for whether material cards are written in mass density if True, or mass fraction if False. (default True)

Return an mcnp card Parameters ———- frac_type : str, optional

Either ‘mass’ or ‘atom’. Speficies whether mass or atom fractions are used to describe material composition. (default ‘mass’)

mult_denbool, optional

Flag for whether material cards are written in mass density if True, or mass fraction if False. (default True)

molecular_mass()

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

Parameters

atoms_per_moleculedouble, optional

Number of atoms to per molecule of material. Needed to obtain proper scaling. For example, this value for water is 3.0.

Returns

mol_massfloat

Molecular mass in [amu].

mult_by_mass()

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

Returns

nucvecdict

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()

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_densfloat, optional

The mass density from which to compute the number density in units of [g/cc].

atoms_per_moleculefloat, optional

Number of atoms to per molecule of material. For example, this value for water is 3.0.

Returns

num_densfloat

The number density [1/cc] of the material.

openmc()

Return an openmc xml element for the material

phits(frac_type='mass', mult_den=True) Return an phits card Parameters ---------- frac_type : str, optional Either 'mass' or 'atom'. Speficies whether mass or atom fractions are used to describe material composition. (default 'mass') mult_den : bool, optional Flag for whether material cards are written in mass density if True, or mass fraction if False. (default True)

Return an phits card Parameters ———- frac_type : str, optional

Either ‘mass’ or ‘atom’. Speficies whether mass or atom fractions are used to describe material composition. (default ‘mass’)

mult_denbool, optional

Flag for whether material cards are written in mass density if True, or mass fraction if False. (default True)

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

normboolean

Whether or not to normalize the returned data if True then intensities

Returns

photonsa vector of pairs of photon energies and intensities. The

intensities are in decays/s/atom material

pop(self, key, default=<object object at 0x7fb1fff76050>)

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

popitem(self)

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

set_mat()

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

Parameters

nuc_sequencesequence

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.

valuefloat

Mass value to set all nuclides in sequence to on the material.

Returns

submaterialMaterial

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()

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

Parameters

lowernuclide-name, optional

Lower bound on nuclide range.

uppernuclide-name, optional

Upper bound on nuclide range.

valuefloat

Mass value to set all nuclides on the range to on the material.

Returns

submaterialMaterial

A new mass stream object that only has nuclides on the given range.

setdefault(self, key, default=None)

sub_act()

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

Returns

submaterialMaterial

A new mass stream object that only has Actinide members.

sub_elem()

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

Returns

submaterialMaterial

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

submaterialMaterial

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

submaterialMaterial

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

submaterialMaterial

A new mass stream object that only has Minor Actinide members.

sub_mat()

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

Parameters

nuc_sequencesequence

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.

Returns

submaterialMaterial

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

submaterialMaterial

A new mass stream object that only has Plutonium members.

sub_range()

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

Parameters

lowernuclide-name, optional

Lower bound on nuclide range.

uppernuclide-name, optional

Upper bound on nuclide range.

Returns

submaterialMaterial

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

submaterialMaterial

A new mass stream object that only has Transuranic members.

sub_u()

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

Returns

submaterialMaterial

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_densmapping

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_fracsmapping

Dictionary-like object that maps nuclides to atom fractions in the material.

update(\*args, \*\*kwds)

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(self)

write_alara(self, filename)

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

Parameters

filenamestr

The file to append the material definition to.

write_hdf5()

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

Parameters

filenamestr

Path to HDF5 file to write the data out to. If the file does not exist, it will be created.

datapathstr, optional

Path to HDF5 table that represents the data. If the table does not exist, it will be created.

nucpathstr, 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.

rowfloat, 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.

chunksizeint, 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()

Writes the material to a JSON file.

Parameters

filenamestr

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

filenamestr

The file to append the material definition to.

frac_typestr, 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

filenamestr

The file to append the material definition to.

frac_typestr, optional

Either ‘mass’ or ‘atom’. Speficies whether mass or atom fractions are used to describe material composition.

write_text()

Writes the material to a plain text file.

Parameters

filenamestr

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-raysa 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()

Create a Material from a mapping of atom fractions.

Parameters

atom_fracsdict

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.

massfloat, 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.

densityfloat, optional

This is the density of the material.

atoms_per_moleculefloat, 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.

metadataJSON-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.

Returns

matMaterial

A material generated from atom fractions.

See also

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()

Create a Material object from an HDF5 file.

Parameters

filenamestr

Path to HDF5 file that contains the data to read in.

datapathstr

Path to HDF5 table or group that represents the data.

rowint, 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]).

protocolint, optional

Specifies the protocol to use to read in the data. Different protocols are used to represent different internal structures in the HDF5 file.

Returns

matMaterial

A material found in the HDF5 file.

See also

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()

Create a Material object from a simple text file.

Parameters

filenamestr

Path to text file that contains the data to read in.

massfloat, 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_moleculefloat, 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.

metadataJSON-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.

Returns

matMaterial

A material found in the HDF5 file.

See also

Material.from_text

Underlying method class method.

Examples

This method loads data into a new Material:

mat = from_text("natu.txt")

Material Library