{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Nuclide Naming Conventions\n",
      "==========================\n",
      "One of the most basic aspects of nuclear software is how to uniquely respresent \n",
      "nuclide names.  There exists the large number of different ways that people choose \n",
      "to spell these names.  Functionally, there are three pieces of information that *should* \n",
      "be included in every radionuclide's name:\n",
      "\n",
      "1. **Z Number**: The number of protons.\n",
      "2. **A Number**: The number of nucleons (neutrons + protons).\n",
      "3. **S Number**: The internal energy excitation state of the nucleus.\n",
      "\n",
      "Some common naming conventions exist. The following are currently supported by PyNE:\n",
      "\n",
      " * **id (zas)**: This type places the charge of the nucleus out front, then has three\n",
      "   digits for the atomic mass number, and ends with four state digits (0 = ground,\n",
      "   1 = first excited state, 2 = second excited state, etc).  Uranium-235 here would\n",
      "   be expressed as '922350000'.  This is the canonical form for nuclides.\n",
      " * **name**: This is the more common, human readable notation.  The chemical symbol\n",
      "   (one or two characters long) is first, followed by the atomic weight.  Lastly if\n",
      "   the nuclide is metastable, the letter *M* is concatenated to the end.  For\n",
      "   example, 'H-1' and 'Am242M' are both valid.  Note that nucname will always\n",
      "   return name form with the dash removed and all letters uppercase.\n",
      " * **zzaaam**: This type places the charge of the nucleus out front, then has three\n",
      "   digits for the atomic mass number, and ends with a metastable flag (0 = ground,\n",
      "   1 = first excited state, 2 = second excited state, etc).  Uranium-235 here would\n",
      "   be expressed as '922350'.\n",
      " * **SZA**: This type places three state digits out front, the charge of the nucleus in \n",
      "   the middle, and then has three digits for the atomic mass number. Uranium-235M here \n",
      "   would be expressed as '1092235'.  \n",
      " * **MCNP**: The MCNP format for entering nuclides is unfortunately\n",
      "   non-standard.  In most ways it is similar to zzaaam form, except that it\n",
      "   lacks the metastable flag.  For information on how metastable isotopes are\n",
      "   named, please consult the MCNPX documentation for more information.\n",
      " * **Serpent**: The serpent naming convention is similar to name form.\n",
      "   However, only the first letter in the chemical symbol is uppercase, the\n",
      "   dash is always present, and the the meta-stable flag is lowercase.  For\n",
      "   instance, 'Am-242m' is the valid serpent notation for this nuclide.\n",
      " * **NIST**: The NIST naming convention is also similar to the Serpent form.\n",
      "   However, this convention contains no metastable information.  Moreover, the\n",
      "   A-number comes before the element symbol.  For example, '242Am' is the\n",
      "   valid NIST notation.\n",
      " * **CINDER**: The CINDER format is similar to zzaaam form except that the\n",
      "   placement of the Z- and A-numbers are swapped. Therefore, this format is\n",
      "   effectively aaazzzm.  For example, '2420951' is the valid cinder notation\n",
      "   for 'AM242M'.\n",
      " * **ALARA**: In ALARA format, elements are denoted by the lower case atomic symbol. Isotopes are\n",
      "   specified by appending a semicolon and A-number. For example, \"fe\" and \"fe:56\" represent\n",
      "   elemental iron and iron-56 respectively. No metastable flag exists."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "----------------\n",
      "\n",
      "Canonical Form\n",
      "--------------\n",
      "A [canonical form](http://en.wikipedia.org/wiki/Canonical_form) is \n",
      "*\"a representation such that every object has a unique representation.\"*\n",
      "Since there are many ways to represent nuclides, PyNE chooses one of them\n",
      "to be *the* canonical form.  **Note:** this idea of \n",
      "canonical forms will come up many times in PyNE.\n",
      "\n",
      "The **id** integer form of nuclide names is the fundamental form of nuclide naming because\n",
      "it accurately captures all of the needed information in the smallest amount of space.  Given that the \n",
      "Z-number may be up to three digits, A-numbers are always three digits, and the excitation level is\n",
      "4 digits, all possible nuclides are represented on the range ``10000000 < zzaaam < 2130000000``. \n",
      "This falls well within 32 bit integers.\n",
      "\n",
      "The ``id()`` function converts other representations to the id format. "
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from pyne import nucname"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.id('U-235')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 2,
       "text": [
        "922350000"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.id('Am-242m')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 3,
       "text": [
        "952420001"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "While applications and backends should use the **id** form under-the-covers, the **name** form provides an easy way to covert nuclide to a consistent and human readable representation."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.name(10010000)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 4,
       "text": [
        "'H1'"
       ]
      }
     ],
     "prompt_number": 4
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.name('CM-244-m')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 5,
       "text": [
        "'Cm244M'"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The **name** string representations may be anywhere from two characters (16 bits)\n",
      "up to six characters (48 bits).  So in general, **id** is smaller by 50%.  \n",
      "\n",
      "Other forms do not necessarily contain all of the required information (``MCNP``) or require additional \n",
      "storage space (``Serpent``).  It may seem pedantic to quibble over the number of bits per nuclide name, \n",
      "but these identifiers are used everywhere throughout nuclear code, so it behooves us to be as small\n",
      "and fast as possible."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The other distinct advantage that integer forms have is that you can natively perform arithmetic\n",
      "on them.  For example::"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Am-242m\n",
      "nuc = 942420001\n",
      "\n",
      "# Z-number\n",
      "z = nuc/10000000\n",
      "print z\n",
      "\n",
      "# A-number\n",
      "a = (nuc/10000)%1000\n",
      "print a\n",
      "\n",
      "# state\n",
      "s = nuc%10000\n",
      "print s"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "94\n",
        "242\n",
        "1\n"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Of course, there are built in functions to do exactly this as well."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print nucname.znum(nuc)\n",
      "print nucname.anum(nuc)\n",
      "print nucname.snum(nuc)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "94\n",
        "242\n",
        "1\n"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Code internal to PyNE uses **id**, and except for human readability, you should too! Natural elements are specified in this form by having zero A-number and excitation flags."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.id('U')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 8,
       "text": [
        "920000000"
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "---------\n",
      "\n",
      "# Ambiguous Forms\n",
      "\n",
      "For some nuclides and forms, it is not automatically discernable which \n"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# name form\n",
      "nucname.id('am242m')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 9,
       "text": [
        "952420001"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# SZA form\n",
      "nucname.id(1095242)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 10,
       "text": [
        "1095240002"
       ]
      }
     ],
     "prompt_number": 10
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "To resolve such ambiquities when you *know* which form you are coming from, PyNE provides a suite of `*_to_to()` functions."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.sza_to_id(1095242)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 11,
       "text": [
        "952420001"
       ]
      }
     ],
     "prompt_number": 11
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "-------------------\n",
      "\n",
      "Examples of Use\n",
      "---------------"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.zzaaam('U235')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 12,
       "text": [
        "922350"
       ]
      }
     ],
     "prompt_number": 12
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.name(10010)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 13,
       "text": [
        "'H1'"
       ]
      }
     ],
     "prompt_number": 13
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.serpent('AM242M')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 14,
       "text": [
        "'Am-242m'"
       ]
      }
     ],
     "prompt_number": 14
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.name_zz['Sr']"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 15,
       "text": [
        "38"
       ]
      }
     ],
     "prompt_number": 15
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.zz_name[57]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 16,
       "text": [
        "u'La'"
       ]
      }
     ],
     "prompt_number": 16
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucname.alara('FE56')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 17,
       "text": [
        "'fe:56'"
       ]
      }
     ],
     "prompt_number": 17
    }
   ],
   "metadata": {}
  }
 ]
}