nucname

The pyne.nucname implements a canonical form for nuclide naming that is used throughout PyNE. This is called the id or nucid. This form is simple but powerful enough to unambiguously handle all nuclide naming conventions from other codes and conventions. All other nuclide naming schemas are derived from transformations of this form.

Concisely, the format is three proton number digits (the Z-number) followed by three nucleon number digits (the A-number) followed by four state digits (the S-number). Thus we see that the full id form is ZZZAAASSSS.

This format has two important properties:

  1. It preserves a natural sort order for nuclides (hydrogen species come before helium species which come before lithium, etc.)

  2. It maximizes the amount of information that can be stored in a 32-bit signed integer.

In most applications, the state number is interpreted as a metastable state since this is the most common usage in nuclear engineering. In certain instances when specified explicitly, the state number may represent the internal excitation state of the nucleus. This usage arises most frequently in the context of radioactive decay.

No physics should be performed on the nuclide id format directly.

Rules & Conventions

The following are rules about the semantic meaning of specific classes of identifiers, in no particular order:

  • Negative nuclides have no meaning (yet).

  • Nuclides where AAA < ZZZ are physically impossible and thus not allowed.

  • Nuclides where SSSS == 0 are considered to be in the ground state.

  • Nuclides where AAA == 0 and ZZZ > 0 represent the chemical element. In most applications this takes on the natural isotopic abundances. The state number is assumed to be zero for elements

  • Humans should use a human readable format, computers should use id.

Well-Defined vs Ambiguous Situations

In situations where the input naming convention is well-defined, it is highly recommended that you use the direct <form>_to_id() functions (e.g. mcnp_to_id()) to convert from a nuclide in the given form to the id form representation. When a high level of quality assurance is required, it is advisable to require an specific input format to leverage the exactness of the direct-to-id functions.

However, in situations where arbitrary nuclide naming conventions are allowed, you must use the id() function. An example of such a situation is when accepting human input. This function attempts to resolve the underlying nuclide identifier. For most nuclides and most normal spellings, this resolution is straightforward. However, some nulcides are ambiguous between the various supported naming conventions. Other nuclide names are completely indeterminate. In the case of indeterminate species the id() function will throw an error. In the case of ambiguous forms where the input is an 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 integer resolution

  • NIST

  • name form

  • Serpent

  • LL (element symbol)

The name() function first converts functions to id form using the id() function. Thus the form order resolution for id() also applies to name().

Nuclide Forms

The following are the currently implemented nuclide naming conventions in pyne:

  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.