Nuclide Naming Module – pyne.nucname

This package is used to convert between various nuclide naming schemes. Currently the following naming conventions are supported:

  1. id (zas): This type places the charge of the nucleus out front, then has three digits for the atomic mass number, and ends with four state digits (0 = ground, 1 = first excited state, 2 = second excited state, etc). Uranium-235 here would be expressed as ‘922350000’. This is th canonical form for nuclides.
  2. name: This is the more common, human readable notation. The chemical symbol (one or two characters long) is first, followed by the atomic weight. Lastly if the nuclide is metastable, the letter M is concatenated to the end. For example, ‘H-1’ and ‘Am242M’ are both valid. Note that nucname will always return name form with the dash removed and all letters uppercase.
  3. zzaaam: This type places the charge of the nucleus out front, then has three digits for the atomic mass number, and ends with a metastable flag (0 = ground, 1 = first excited state, 2 = second excited state, etc). Uranium-235 here would be expressed as ‘922350’.
  4. zzzaaa: This type places the charge of the nucleus out front, then has three digits for the atomic mass. It contains no information about the excited state.
  5. zzllaaam: The ZZLLAAAM naming convention is similar to name form. However, it is preceded by the nuclides two AA numbers, followed by the two LL characters. Of the two LL characters, only the first letter in the chemical symbol is uppercase, the dash is always present, and the the meta-stable flag is lowercase. For instance, ‘95-Am-242m’ is the valid serpent notation for this nuclide.
  6. SZA: This type places three state digits out front, the charge of the nucleus in the middle, and then has three digits for the atomic mass number. Uranium-235M here would be expressed as ‘1092235’.
  7. MCNP: The MCNP format for entering nuclides is unfortunately non-standard. In most ways it is similar to zzaaam form, except that it lacks the metastable flag. For information on how metastable isotopes are named, please consult the MCNPX documentation for more information.
  8. Serpent: The serpent naming convention is similar to name form. However, only the first letter in the chemical symbol is uppercase, the dash is always present, and the the meta-stable flag is lowercase. For instance, ‘Am-242m’ is the valid serpent notation for this nuclide.
  9. NIST: The NIST naming convention is also similar to the Serpent form. However, this convention contains no metastable information. Moreover, the A-number comes before the element symbol. For example, ‘242Am’ is the valid NIST notation.
  10. CINDER: The CINDER format is similar to zzaaam form except that the placement of the Z- and A-numbers are swapped. Therefore, this format is effectively aaazzzm. For example, ‘2420951’ is the valid cinder notation for ‘AM242M’.
  11. ALARA: In ALARA format, elements are denoted by the lower case atomic symbol. Nuclides are specified by appending a semicolon and A-number. For example, “fe” and “fe:56” represent elemental iron and iron-56 respectively. No metastable flag exists.
  12. Groundstate: In Groundstate format, the nuclide is stored in a form similar to the standard id form, but the last four digits are zero to eliminate the information about the nuclide’s state.
  13. state_id: The state id naming convention uses the form zzzaaassss. It is different from the canonical zzzaaassss form in that ssss refers to a list of states by ordered by energy. This is derived from the levels listed in the ENSDF files for a given nuclide. Using this form is dangerous as it may change with new releases of ENSDF data.

All functionality may be found in the nucname package:

from pyne import nucname

This contains several zzaaam, zzzaaa, zzllaaam, name, MCNP, Groundstate and Serpent converter function as well as other helpful module attributes.

Naming Convention Casting Functions

pyne.nucname.id(nuc)

Converts a nuclide to its identifier form (952420000).

If the input nuclide is in id form already, then this is function does no work. For all other formats, the id() function provides a best-guess based on a heirarchy of other formats that is used to resolve ambiguities between naming conventions. For integer input the form resolution order is:

  • id
  • zz (elemental z-num only given)
  • zzaaam
  • cinder (aaazzzm)
  • mcnp
  • zzaaa

For string (or char *) input the form resolution order is as follows:

  • ZZ-LL-AAAM
  • Integer form in a string representation, uses interger resolution
  • NIST
  • name form
  • Serpent
  • LL (element symbol)

For well-defined situations where you know ahead of time what format the nuclide is in, you should use the various form_to_id() functions, rather than the id() function which is meant to resolve possibly ambiquous cases.

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : int

Output nuclide id.


pyne.nucname.name(nuc)

Converts a nuclide to its name form (‘Am242M’). The name() function first converts functions to id form using the id() function. Thus the form order resolution for id() also applies to here.

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : str

Output nuclide in name form.


pyne.nucname.zzaaam(nuc)

Converts a nuclide to its zzaaam form (952420).

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : int

Output nuclide in zzaaam form.


pyne.nucname.zzzaaa(nuc)

Converts a nuclide to its zzzaaa form (95242).

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : int

Output nuclide in zzzaaa form.


pyne.nucname.zzllaaam(nuc)

Converts a nuclide to its zzllaaam form (95-Am-241m).

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : str

Output nuclide in zzllaaam form.


pyne.nucname.mcnp(nuc)

Converts a nuclide to its MCNP form (92636).

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : int

Output nuclide in MCNP form.

Notes

Most metastables in this form add 300 + 100*m where m is the isomeric state (U-236m = 92636). However, MCNP special cases Am-242 and Am-242m by switching the meaning. Thus Am-242m = 95242 and Am-242 = 95642.


pyne.nucname.serpent(nuc)

Converts a nuclide to its Serepnt form (‘Am-242m’).

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : str

Output nuclide in serpent form.


pyne.nucname.nist(nuc)

Converts a nuclide to NIST form (‘242Am’).

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : str

Output nuclide in nist form.


pyne.nucname.cinder(nuc)

Converts a nuclide to its CINDER (aaazzzm) form (2420951).

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : int

Output nuclide in CINDER (aaazzzm) form.


pyne.nucname.alara(nuc)

Converts a nuclide to its ALARA form (‘am:242’).

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : str

Output nuclide in name form.


pyne.nucname.groundstate(nuc)

Converts a nuclide to its Groundstate form.

Parameters:

nuc : int or str

Input nuclide.

Returns:

newnuc : int

Output nuclide in Groundstate form.

Id Conversion Functions

pyne.nucname.zzaaam_to_id(nuc)

Converts a nuclide directly from ZZAAAM form (952420) to the canonical identifier form.

Parameters:

nuc : int or str

Input nuclide in ZZAAAM form.

Returns:

newnuc : int

Output nuclide in identifier form.


pyne.nucname.zzzaaa_to_id(nuc)

Converts a nuclide directly from ZZZAAA form (95242) to the canonical identifier form.

Parameters:

nuc : int or str

Input nuclide in ZZZAAA form.

Returns:

newnuc : int

Output nuclide in identifier form.

pyne.nucname.zzllaaam_to_id(nuc)

Converts a nuclide directly from ZZLLAAAM form (95-Am-241m) to the canonical identifier form.

Parameters:

nuc : int or str

Input nuclide in ZZLLAAAM form.

Returns:

newnuc : int

Output nuclide in identifier form.

pyne.nucname.mcnp_to_id(nuc)

Converts a nuclide directly from MCNP form (92636) to the canonical identifier form.

Parameters:

nuc : int or str

Input nuclide in MCNP form.

Returns:

newnuc : int

Output nuclide in identifier form.


pyne.nucname.serpent_to_id(nuc)

Converts a nuclide directly from Serpent form (‘Am-242m’) to the canonical identifier form.

Parameters:

nuc : int or str

Input nuclide in Serpent form.

Returns:

newnuc : int

Output nuclide in identifier form.


pyne.nucname.nist_to_id(nuc)

Converts a nuclide directly from NIST form (‘242Am’) to the canonical identifier form.

Parameters:

nuc : int or str

Input nuclide in NIST form.

Returns:

newnuc : int

Output nuclide in identifier form.


pyne.nucname.cinder_to_id(nuc)

Converts a nuclide directly from Cinder form (2420951) to the canonical identifier form.

Parameters:

nuc : int or str

Input nuclide in Cinder form.

Returns:

newnuc : int

Output nuclide in identifier form.


pyne.nucname.alara_to_id(nuc)

Converts a nuclide directly from ALARA form (‘am:242’) to the canonical identifier form.

Parameters:

nuc : int or str

Input nuclide in ALARA form.

Returns:

newnuc : int

Output nuclide in identifier form.

Number Functions

pyne.nucname.znum(nuc)

Retrieves a nuclide’s charge number (95).

Parameters:

nuc : int or str

Input nuclide.

Returns:

z : int

The number of protons in the nucleus.


pyne.nucname.anum(nuc)

Retrieves a nuclide’s nucleon number (95).

Parameters:

nuc : int or str

Input nuclide.

Returns:

a : int

The number of protons and neutrons in the nucleus.


pyne.nucname.snum(nuc)

Retrieves a nuclide’s excitation number (95).

Parameters:

nuc : int or str

Input nuclide.

Returns:

s : int

The excitation level the nucleus.

Conversion Dictionaries

pyne.nucname.name_zz

Dictionary that is used to convert an elemental symbol (str) to its charge Z-number (int). For example:

nucname.name_zz["HE"] = 2
nucname.name_zz["U"]  = 92
pyne.nucname.zz_name

Dictionary that is used to convert a charge Z-number (int) to its elemental symbol (str). For example:

nucname.name_zz[1]  = "H"
nucname.name_zz[94] = "PU"

Element Groups (name)

Element groups for the Lanthanides, Actinides, Transuranics, Minor Actinides, and Fission Products.

nucname.LAN
nucname.ACT
nucname.TRU
nucname.MA
nucname.FP

The groups are defined as follows:

nucname.LAN = set(['CE', 'DY', 'ER', 'EU', 'GD', 'HO', 'LA', 'LU', 'ND', 'PM', 'PR', 'SM', 'TB', 'TM', 'YB'])

nucname.ACT = set(['AC', 'AM', 'BK', 'CF', 'CM', 'ES', 'FM', 'LR', 'MD', 'NO', 'NP', 'PA', 'PU', 'TH', 'U'])

nucname.TRU = set(['AM', 'BH', 'BK', 'CF', 'CM', 'CN', 'DB', 'DS', 'ES', 'FL', 'FM', 'HS', 'LR', 'LV', 'MD',
                   'MT', 'NO', 'NP', 'PU', 'RF', 'RG', 'SG'])

nucname.MA  = set(['AM', 'BK', 'CF', 'CM', 'ES', 'FM', 'LR', 'MD', 'NO', 'NP'])

nucname.FP  = set(['AG', 'AL', 'AR', 'AS', 'AT', 'AU', 'B',  'BA', 'BE', 'BI', 'BR', 'C',  'CA', 'CD', 'CE',
                         'CL', 'CO', 'CR', 'CS', 'CU', 'DY', 'ER', 'EU', 'F',  'FE', 'FR', 'GA', 'GD', 'GE',
                         'H',  'HE', 'HF', 'HG', 'HO', 'I',  'IN', 'IR', 'K',  'KR', 'LA', 'LI', 'LU', 'MG',
                         'MN', 'MO', 'N',  'NA', 'NB', 'ND', 'NE', 'NI', 'O',  'OS', 'P',  'PB', 'PD', 'PM',
                         'PO', 'PR', 'PT', 'RA', 'RB', 'RE', 'RH', 'RN', 'RU', 'S',  'SB', 'SC', 'SE', 'SI',
                         'SM', 'SN', 'SR', 'TA', 'TB', 'TC', 'TE', 'TI', 'TL', 'TM', 'V',  'W',  'XE',  'Y',
                         'YB', 'ZN', 'ZR'])

Element Groups (zz)

Element groups for the Lanthanides, Actinides, Transuranics, Minor Actinides, and Fission Products.

nucname.lan
nucname.act
nucname.tru
nucname.ma
nucname.fp

The groups are defined as follows:

nucname.lan = set([57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71])

nucname.act = set([89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103])

nucname.tru = set([93,  94,  95,  96,  97,  98, 99, 100, 101, 102, 103, 104, 105,
                   106, 107, 108, 109, 110, 111, 112, 114, 116])

nucname.ma  = set([93, 95, 96, 97, 98, 99, 100, 101, 102, 103])

nucname.fp  = set([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28,
                  29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53,
                  54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78,
                  79, 80, 81, 82, 83, 84, 85, 86, 87, 88])