This package defines classes to represent mixture of nuclides. The classes are not used directly, they serve as parent classes providing base functionality for example, to the pirs.mcnp.Material class.
The basic element of any material mixture is a nuclide represented by the pirs.core.tramat.Nuclide class. Instances of this class have attributes for mass and charge numbers, for molar mass and for the isomeric state. The main functionality of this class is to ‘understand’ nuclide specifications of different forms; it also defines arithmetical operations of addition of two nuclides and multiplication of a nuclide by scalar.
How nuclides can be defined:
from pirs.core.tramat import Nuclide
n1 = Nuclide((2, 4, 0)) # tuple (Z, A, I)
n2 = Nuclide('He-4') # string
n3 = Nuclide('Ag-110m') # string for isomer
n4 = Nuclide(2004) # ZAID integer
n5 = Nuclide(n4) # copy of n4.
for n in [n1, n2, n3, n4, n5]:
print repr(n), n.name, n.ZAID, n.M()
<pirs.core.tramat.mixer.Nuclide object at 0x2b3e87433a10> He-004 2004 3.968219
<pirs.core.tramat.mixer.Nuclide object at 0x2b3e874339d0> He-004 2004 3.968219
<pirs.core.tramat.mixer.Nuclide object at 0x2b3e874560d0> Ag-110m 47510 108.961963
<pirs.core.tramat.mixer.Nuclide object at 0x2b3e87456110> He-004 2004 3.968219
<pirs.core.tramat.mixer.Nuclide object at 0x2b3e87456150> He-004 2004 3.968219
In all these examples the molar mass was not specified. In this case, it is taken from the class attribute pirs.core.tramat.Nuclide.AWR_SET, which is a dictionary of the form ZAID: awr. By defualt, this class attribute links to the pirs.core.tramat.data_masses.xsdir1 dictionary, which contains awr masses from the xsdir file distributed with MCNP5.
Two nuclide instances can be added and an instance can be multiplied by a scalar:
a = n1 + n2
b = 3*n1
Both operations result in an instance of the pirs.core.tramat.Mixture class. In the example, a is a mixture of one mole of nuclide n1 and one mole of nuclide n2, and b is a mixture consisting of 3 moles of nuclide n1.
The pirs.core.tramat.Mixture class represents a mixture of nuclides or other mixtures. Its constructor takes arguments that define the mixture recipe – what materials at which amount constitute the mixture. In the most simple case, there can be only one integer argument specifying ZAID, or a string specifying chemical name. In general case, the constructor accepts several tuples each defining material and its amount used to construct the mixture.
from pirs.core.tramat import Mixture
m1 = Mixture(1001) # mixture conatins only H-1
m2 = Mixture('He') # mixture of He nuclide with nat. abund.
# Mixture does not accept string representation of a nuclide:
# m2 = Mixture('He-4') # will cause an error
m3 = Mixture((m1, 0.1, 1), (m2, 0.9, 1)) # 0.1 mole of m1 and 0.9 moles of m2
m4 = Mixture((m1, 0.1, 2), (m2, 0.9, 2)) # 0.1 g of m1 and 0.9 g of m2
m5 = Mixture((m1, 0.1, 1), (m2, 0.9, 2)) # 0.1 mole of m1 and 0.9 g of m2.
m1.dens = 1.0 # g/cm3
m6 = Mixture((m1, 0.1, 3), (m2, 0.9, 1)) # 0.1 cm3 of m1 and 0.9 moles of m2
for m in [m1, m2, m3, m4, m5, m6]:
print m.report()
print '='*30
In this example, m1 is a mixture consisting of one nuclide H-1, and m2 is a mixture of He isotopes with natural abundancies. Note that the string representation of a nuclide, in the form 'He-4' cannot be used in the Mixture constructor, while a string is assumed to define a chemical element name. Mixtures m3, m4 etc. are defined using the general form of constructor arguments. Each tuple defines the material, amount and units in which amound should be understood: 1 for moles, 2 for grams and 3 for cubic cm; the latter is only possible for materials with specified density or concentration.
In the above example, mixture m3 has two ingredients: 0.1 mole (last tuple element is 1) of m1 and 0.9 moles of m2. Mixture m4 is defined using grams: it consists of 0.1 g of m1 and 0.9 g of m2. Note that one can mix units, see definition of m5.
One can specify ingredient amount in cubic centimeters, as for the mixture m6 above. For this to have sense, the ingredient material, m1 in this case, should have the pirs.core.tramat.Mixture.dens or pirs.core.tramat.Mixture.conc attribute defined.
Main properties of a mixture can be inquired by the pirs.core.tramat.Mixture.report() method. It returns a multi-line string where mixture ingredients and mixture nuclide composition is summarized. The above script produces the following output:
Mixture H-001
< 1001 0.9992>: 1.0 mol
total: 1.0 mol or 1.00782474906 g or 1.00782474906 cc
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 1.00000e+00 1.00000e+00
==============================
Mixture He
< 2003 2.9901>: 1.34e-06 mol
< 2004 3.9682>: 0.99999866 mol
total: 1.0 mol or 4.0026021646 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 2003 2.9901> 1.34000e-06 1.00971e-06
< 2004 3.9682> 9.99999e-01 9.99999e-01
==============================
Mixture He-H
< H-001 0.9992>: 0.1 mol
<He 3.9682>: 0.9 mol
total: 1.0 mol or 3.70312442304 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 1.00000e-01 2.72155e-02
< 2003 2.9901> 1.20600e-06 9.82233e-07
< 2004 3.9682> 8.99999e-01 9.72783e-01
==============================
Mixture He-H
< H-001 0.9992>: 0.1 g
<He 3.9682>: 0.9 g
total: 0.324077323627 mol or 1.0 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 3.06173e-01 1.00000e-01
< 2003 2.9901> 9.29729e-07 9.08742e-07
< 2004 3.9682> 6.93826e-01 8.99999e-01
==============================
Mixture He-H
< H-001 0.9992>: 0.1 mol
<He 3.9682>: 0.9 g
total: 0.3248537234 mol or 1.00078247491 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 3.07831e-01 1.00704e-01
< 2003 2.9901> 9.27507e-07 9.08031e-07
< 2004 3.9682> 6.92168e-01 8.99295e-01
==============================
Mixture He-H
< H-001 0.9992>: 0.1 cc
<He 3.9682>: 0.9 mol
total: 0.999223600227 mol or 3.70234194814 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 9.93007e-02 2.70099e-02
< 2003 2.9901> 1.20694e-06 9.82441e-07
< 2004 3.9682> 9.00698e-01 9.72989e-01
==============================
The name of a mixture, printed in the first line returned by the report() method, is given by the pirs.core.tramat.Mixture.name attribute. If not specified explicitly by the user (as in the example above), it is generated based on the chemical element names that constitute the mixture.
The first part of report, between the lines Mixture ... and Nuclide composition:, lists ingredients used to construct the mixture. The second part, after the line Nuclide composition:, shows nuclide composition, computed from the mixture recipe and recipies of its ingredients, recursively.
Mixtures can be added to each other and multiplied by a scalar, as shown in the follwing example.
from pirs.core.tramat import Mixture
h1 = Mixture('H')
he = Mixture('He')
m1 = h1 + he
m2 = 2*h1
m3 = 2*h1 + 3*he
m4 = 2*m1 + 3*m2
m1.name = 'm1'
m2.name = 'm2'
m3.name = 'm3'
m4.name = 'm4'
for m in [m1, m2, m3, m4]:
print m.report()
print '='*30
Mixture m1
< 1001 0.9992>: 0.999885 mol
< 1002 1.9968>: 0.000115 mol
< 2003 2.9901>: 1.34e-06 mol
< 2004 3.9682>: 0.99999866 mol
total: 2.0 mol or 5.01054263557 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 4.99943e-01 2.01118e-01
< 1002 1.9968> 5.75000e-05 4.62269e-05
< 2003 2.9901> 6.70000e-07 8.06595e-07
< 2004 3.9682> 4.99999e-01 7.98835e-01
==============================
Mixture m2
<H 0.9993>: 2.0 mol
total: 2.0 mol or 2.01588094194 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 9.99885e-01 9.99770e-01
< 1002 1.9968> 1.15000e-04 2.29797e-04
==============================
Mixture m3
< 1001 0.9992>: 1.99977 mol
< 1002 1.9968>: 0.00023 mol
< 2003 2.9901>: 4.02e-06 mol
< 2004 3.9682>: 2.99999598 mol
total: 5.0 mol or 14.0236874357 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 3.99954e-01 1.43715e-01
< 1002 1.9968> 4.60000e-05 3.30329e-05
< 2003 2.9901> 8.04000e-07 8.64568e-07
< 2004 3.9682> 5.99999e-01 8.56251e-01
==============================
Mixture m4
< 1001 0.9992>: 0.999885 mol
< 1002 1.9968>: 0.000115 mol
< 2003 2.9901>: 1.34e-06 mol
< 2004 3.9682>: 0.99999866 mol
< 1001 0.9992>: 2.999655 mol
< 1002 1.9968>: 0.000345 mol
total: 5.0 mol or 8.03436404848 g
Nuclide composition:
Nuclide At.frac Wgt.frac
< 1001 0.9992> 7.99908e-01 5.01699e-01
< 1002 1.9968> 9.20000e-05 1.15316e-04
< 2003 2.9901> 2.68000e-07 5.03024e-07
< 2004 3.9682> 2.00000e-01 4.98185e-01
==============================
Result of adition of two mixtures is a new mixture that is a mix of the operands in equal proportions. Note, however, that the resulting mixture recipe does not refer directly to the operands, they are first expanded to nuclides (see the pirs.core.tramat.Mixture.expanded() method). In the above example, the recipe of m1 consists of 4 nuclides, not of two mixtures h1 and he.
Multiplication of a mixture by a scalar returns a new mixture with only one ingredient – the operand, which amount in moles is given by the scalar, see mixture m2. Note, in this case the operand is not expanded to nuclides.
Note that the total amount of ingredients in the mixture m4 sums up to 5 moles, although it is defined as 2*m1 + 3*m2, where m1 and m2 have itself 2 moles in their recipes. This behaviour is chosen deliberately, the scalar before the mixture is not a coefficient for the amount of its ingredients, it specifies the amount of mixture itself.
Mapping between charge numbers and chemical names are defined in the pirs.core.tramat.data_names module. This module also contains functions to parse nuclide names and to define isomeric names from special ZAIDS.
Default awr masses are taken from the pirs.core.tramat.data_masses module.
Naturall abundancies of isotopes are taken from the module pirs.core.tramat.data_natural.
Representation of a nuclide. A nuclide is defined by its mass and charge numbers, A and Z, isomeric state I, and by its molar mass M.
The A, Z and I properties of a nuclide instance can be changed. The nuclide mass, represented by the property M, cannot be changed.
The constructor argument ID specifies Z, A and I and can be given in several forms:
- a tuple (Z, A, I),
- a string of the form ‘cc-AAA[m[I]]’, for example, ‘Pu-241’, ‘O-16’, ‘Te-129m’
- an integer of the form ZZAAA.
- another instance of Nuclide class; in this case, the copy of ID is created.
If M is not specified, values derived from xsdir file will be used (the xsdir file is not read. Mass is actually taken from the data_masses module, where nuclide masses in awr units are stored. These values are originally taken from an xsdir file).
The class supports some arithmetical operations:
- An instance of the Nuclide class can be multiplied by a scalar c. The result is an instance of the Mixture class meaning c moles of the nuclide.
- Two Nuclide instances can be added, n1 + n2. This creates a Mixture representing one mole of n1 mixed with one mole of n2.
Mass number A of the nuclide (integer). Can be set.
>>> n1 = Nuclide('H-1')
>>> n1.A = 5
>>> n1.ZAID
1005
Nuclide isomeric state.
Returns the nuclide molar mass. If the molar mass was not specified at the initialization of the instance, the value in AWR will be set depending on the nuclide ID:
>>> n1 = Nuclide(1001, 1.)
>>> n1.M()
1.0
>>> n2 = Nuclide(1001)
>>> n2.M()
0.999167
Charge number, Z, of the nuclide. Can be set.
>>> n1 = Nuclide('O-16')
>>> n1.Z = n1.Z/2
>>> n1.name
'Be-016'
ZAID (integer) of the nuclide. Can be set to any integer of the form AAZZZ.
Support for isomeric states.
Check conditions specified in kwargs in the form ATTR=VAL. Attr can be usual attribute or a method. In the latter case, the result returned by the method is compared against VAL. Only methods without arguments can be checked.
>>> n1 = Nuclide(1001)
>>> n1.check_attributes(A=1, Z=1)
True
>>> n1.check_attributes(M=0.999167)
True
Returns True if one of the fissionable isotopes 92235, 94239 or 94241.
The name (string) of the nuclide in the form ‘Cc-AAA[m[I]]’. For example, ‘Pu-241’.
Can be set. in this case, attributes A, Z and I wil be changed accordingly.
Mixture of nuclides or other mixtures.
A mixture is defined by specifying a recipe – a sequence of ingredients (a nuclide or another mixture) each supplemented with certain amount.
Since all ingredeints in the recipe have particular amount, the total amount of all ingrediants can be computed. However, if a mixture is defined using another, previously defined mixture, the amount of latter is not “propagated”.
The constructor takes arbitrary amount of arguments specifying the mixture ingredients:
m = Mixture(arg1, arg2, arg3, ... argN)
Each argument must be a string, an integer or an instance of Nuclide or Mixture class, or a tuple of the form (MAT, a) or (MAT, v, t), where MAT can be an integer, a string or an instance of the Nuclide or Mixture class. The other tuple elements represent the amount: a is an instance of the Amount() class, v, t are value and unit to define the amount.
If a mixture used as ingredient in a new mixture has itself only one ingredient, this ingredient will be used in the new mixture.
If the argument is an integer, it is understood as ZAID of a nuclide. This argument adds one mole of the nuclide to the recipe.
If the argument is a string, it is considered as the name of a chemical element. This argument defines one mole of the mixture of naturally occuring isotopes of this chemical element.
When the argument is an instance of the Nuclide or Mixture class, it denotes one mole of it.
When a tuple is given, its first element is understood as described above. The second and third elements define amount and unit in which the amount is expressed, they both have default values 1. The third element is 1 for moles, 2 for grams and 3 for cubic centimeters.
Effective molar mass of the recipe.
Returns the total amount of ingredients, specified in the recipe definition. The t argument defines the units (moles, g or cc).
Returned value is an instance of the Amount class.
See also methods cc, grams and moles.
returns total volume in cubic centimeters of the ingredients, specified in the recipe definition.
Returned value is an instance of the Amount class.
Some ingredients might have no density/concentration property, in this case the direct evaluation of the sum of ingredients volumes is not possible. In this case, the value
self.grams() / self.dens
will be returned. If the density/concentration of self is not defined, None is returned.
Concentration of the mixture, 1/cc.
Concentration can be computed from the material inrgedients, or set explicitly. The computed value ( see derived_conc method) is used only if the concentration not set explicitly.
Use the dens property to set concentration in terms of density [g/cc].
Density of the mixture, g/cc.
Density can be computed from the recipe ingredients, or set explicitly to the mixture. The computed value is returned only if the density is not set explicitly.
Internally, density is saved as concentration. Thus, if a density was set to a recipe and than the molar mass of recipe (or its ingredients) was changed, the density will be changed also.
Returns computed concentration of the recipe, 1/cc.
This can be done only if all recipe ingredients have their conentration/density attributes either set explicitly or can be computed.
The derived name is composed from the element names entering the mixture. The general form of the derived name is
‘E1-E2-E3-‘
where E1, E2, E3 are the chemical element names of the mixture ingredients. 3 element names accounted at maximum. If there are other elements, the name ends with ‘-‘, as shown above.
The element names are listed in the decreasing order of its molar amount in the mixture.
If the mixture consists of only one nuclide, the nuclide name will be used.
Returns a new mixture instance with all ingredients resolved down to nuclides with amounts expressed in moles.
The sum of moles of each ingredient nuclide is equal to the amount of originally defined recipe.
>>> r1 = Mixture( ('H', 2), ('O', 1) )
>>> r2 = r1.expanded()
>>> r1.amount() == r2.amount()
True
>>> for (m,a) in r2.recipe():
... print m, a
...
< 1001 0.9992> 1.99977 mol
< 1002 1.9968> 0.00023 mol
< 8016 15.8575> 0.99757 mol
< 8017 16.8531> 0.00038 mol
< 8018 17.8445> 0.00205 mol
returns total mass in grams of the ingredients, specified in the recipe defition.
Returned value is an instance of the Amount class.
Computes amount of specified ingredients or nuclides entering the mixture.
Computes the amount in units specified by the argument t of the mixture ingredients specified by *args, or of nuclides specified by **kwargs.
Only t=1 (moles) or t=2 (grams) can be used.
Returned value is an instance of the Amount class.
Arguments *args and **kwargs cannot be used simultaneously. If *args are specified, the **kwargs have no effect.
When *args are specified, they must be nuclides, mixtures or integers (meaning ZAID) entering to the mixture recipe. The returned value is the total amount of all specified in *args materials. The materials are searched only in the recipe, i.e. a nuclide will be accounted only if it was specified directly in the recipe. If it enters the mixture only indirectly, it is not accounted for:
>>> r = Mixture( 'Fe', 8016 )
>>> print r.how_much(1, 8016)
1.0 mol
>>> print r.how_much(1, 'Fe')
1.0 mol
>>> print r.how_much(1, 'Fe', 8016)
2.0 mol
The optional keyword arguments, **kwargs, specify properties of nuclides that should be accounted for. In this case, the mixture first expanded so that nuclides of the mixture ingredients are also taken into account.
>>> r = Mixture( 'Fe', 8016 )
>>> print r.how_much(1, ZAID=8016)
1.0 mol
>>> print r.how_much(1, Z=26)
1.0 mol
If neither *args nor **kwargs are specified, how_much(t) is equal to amount(t).
Returns index of the ingredient i in the mixture’s recipe. Similar to the index method of a list.
Argument i can be an instance of the Nuclide or Mixture class, in which case the index of this ingredient is returned (if any).
If i is an integer, it is internally converted into Nuclide(i).
>>> m = Mixture('Fe')
>>> m.index(26054)
0
>>> m.index(26056)
1
>>> m.index(26058)
3
Returns True if the mixture contains one of the following nuclides: 92235, 94239, 94241.
Returns total amount of moles of the ingredients, specified in the recipe definition.
Returned value is an instance of the Amount class.
Name of the mixture, a string.
The mixture name can be specified explicitly. If not specified explicitly, it will be derived from the recipe definition, see the derived_name() method.
>>> r = Mixture(('O', 2), ('U', 1))
>>> r.name
'O-U'
>>> r.name = 'mox'
>>> r.name
'mox'
>>> steel = Mixture( 'Fe', 'Cr', 'Mo', 'Ni') # more than 4 elements.
>>> steel.name
'Fe-Cr-Mo-'
Change the amounts of ingredients in the recipe proportionally, so that the resulting amount is a (if a is a float, one has to specify also units by setting t=1, 2 or 3).
>>> r = Mixture('O', 'U', 'O') # r has 3 moles
>>> r.dens = 10. # set density so the cc amount has sense
>>> r.normalize(1, 1)
>>> print r.amount(1), r.amount(2), r.amount(3)
1.0 mol 90.0092422778 g 9.00092422778 cc
>>> r.normalize(1, 2)
>>> print r.amount(1), r.amount(2), r.amount(3)
0.0111099702063 mol 1.0 g 0.1 cc
>>> r.normalize(1, 3)
>>> print r.amount(1), r.amount(2), r.amount(3)
0.111099702063 mol 10.0 g 1.0 cc
Returns a list of tuples, representing the recipe of the mixture .
The resulting list can be passed to the mixture constructor to create another mixture:
>>> r1 = Mixture( 'O' )
>>> r2 = Mixture( *r1.recipe() )
>>> r1.recipe() == r2.recipe()
True
Check the mixture and join equal materials. Changes are made in-place.
Only the materials specified directly in the recipe are compared.
If a material is mentioned in the recipe several times, only one entry with the total amount will remain. The units are defined by the first mentioning of the material in the recipe.
>>> r = Mixture('O', 'U', 'O')
>>> r.remove_duplicates()
>>> for (m,v) in r.recipe():
... print m, v
...
<O 15.8620> 2.0 mol
<U 235.9841> 1.0 mol
Returns a multi-line string, describing the mixture.
Changes the mixture recipe to satisfy objective function.
The objective argument is a function taking as argument an instance of the Mixture class.
The var argument is a list of two elements each of them can be a nuclide, mixture or an integer (meaning ZAID), that were used in the definition of the mixture.
The method changes the amount of materials var[0] and var[1] in the mixture recipe, so that the objective function returns value with the module less than the err argument.
>>> # mixture m contains several Fe isotopes.
>>> m = Mixture('Fe')
>>> # objective function. Returns 0 if amount of Fe-56
>>> # and Fe-54 in its argument is equal.
>>> def o(mix):
... a4 = mix.how_much(1, 26054)
... a6 = mix.how_much(1, 26056)
... return (a4 - a6).v
...
>>> # change mixture m in place, now it has the same
>>> # fraction of Fe-54 and Fe-56.
>>> m.tune(o, [26056, 26057])
A place where sets of isotopic masses are defined.
A set of masses (the term “set” here means a collection of isotopic masses consistent to each other, not the python type) must be representad by python dictionary of the form
d = { ZAID1: mass1,
ZAID2: mass2,
...
'avogadro': Na,
'reference': 'the data origin'}
where keys are integer ZAIDs and values are isotope masses. Additionally, each dictionary must have the key ‘avogadro’, which value is a float specifying the Avogadro Number correspondent to the mass units, and the ‘reference’ key, which is a string specifying the origin of data.
Dictionary ZAID: awr with awr masses taken from the xsdir file distributed with MCNP5. See also the 'reference' key in this dictionary.
Module contains mapping from Z number to chemical element names. For the chemical element names, the following rules apply:
- each name is a string of length 2. If chemical name is of length one, it is preceeded by space.
- The first letter is capital. The second (if any) – small.
There are two dictionaries defined in the module: name and charge defining mappings Z: name and name: Z.
Returns (Z, A, I) tuple for the nuclide specified by its ZAID.
Rules to construct ZAIDs for isomeric states are from https://www.oecd-nea.org/dbprog/RPSD2008-endf70-paper2.pdf
if I < 1:
ZAID = Z*1000 + A
else:
ZAID = Z*1000 + (A + 300) + I*100
Similar to the module data_masses, there can be several data sets of the natural isotopic compositions of chemical elements, originated from different sources.
Each data set is a dictionary of the form ZAID_i: af_i. The key ZAID_i is the integer of the form ZZZAAA of isotope (Z and A are charge and mass numbers of the isotope), correspondent value, af_i, is the naturally occuring atomic fraction of this isotope in the chemical element with charge number Z.
Additionally to the ZAID keys, the reference key contains a string referencing the origin of the natural abundancies.