{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Reaction Names\n",
      "\n",
      "In the same way that nuclides have a vareity of different spelling, so to do reactions.  Once again, PyNE aims to provide a canonical form while interfacing well with external spellings - such as MT numbers.  Similar to the `nucname` module, the canonical form is given as and integer which may be discovered via the `id()` function while the human readable name is found via `name()`.\n",
      "\n",
      "**Reaction Names:** The names themselves are strings chosen such\n",
      "that they are valid variable names in most programming languages\n",
      "(including Python and C/C++).  This strategy is known as *natural\n",
      "naming* and enables a *namespace* of reactions.  Therefore, all\n",
      "names must match the regular expression ``[A-Za-z_][A-Za-z0-9_]*``.\n",
      "For example, the elastic scattering cross section is simply\n",
      "\"elastic\" while the pair production reaction is given by\n",
      "\"pair_prod\".\n",
      "\n",
      "A number of patterns dictate how a reaction should be named.\n",
      "Foremost among these are particle names.  Where required, \"z\" is a\n",
      "variable for any incident particle.  The following table displays\n",
      "particle types and their names:\n",
      "\n",
      "| particle  | name (z) |\n",
      "|-----------|:--------:|\n",
      "| neutron   | n        |\n",
      "| proton    | p        |\n",
      "| deuterium | d        |\n",
      "| tritium   | t        |\n",
      "| Helium-3  | He3      |\n",
      "| alpha     | a        |\n",
      "| gamma     | gamma    |\n",
      "\n",
      "From this we can see that a reaction which produces a neutron and a\n",
      "proton is called \"np\".  If multiple particles of the same type are\n",
      "produced, then the number precedes the particle type.  Thus, one\n",
      "neutron and two protons are given by \"n2p\".  However if this would\n",
      "result in the name starting with a number, then the name is\n",
      "prepended with ``z_`` to indicate any incident particle.  For\n",
      "example, the reaction which yields two neutrons is \"z_2n\" (because\n",
      "\"2n\" is not a valid variable name in most programming languages).\n",
      "\n",
      "Furthermore, if a reaction name ends in ``_[0-9]+`` (underscore plus\n",
      "digits), then this means that the nucleus is left in the nth excited\n",
      "state after the interaction.  For example, \"n_0\" produces a neutron\n",
      "and leaves the nucleus in the ground state, \"n_1\" produces a neutron\n",
      "and the nucleus is in the first excited state, and so on.  However,\n",
      "\"_continuum\" means that the nucleus in an energy state in the\n",
      "continuum.\n",
      "\n",
      "If a reaction name begins with ``erel_``, then this channel is for\n",
      "the energy release from the reaction by the name without ``erel_``.\n",
      "E.g. \"erel_p\" is the energy release from proton emission.\n",
      "\n",
      "**Reaction IDs:** While the reaction names are sufficient for\n",
      "defining all possible reactions in a partially physically meaningful\n",
      "way, they do so using a variable length format (strings).  It is\n",
      "often advantageous to have a fixed-width format, namely for storage.\n",
      "To this end, unique unsigned 32-bit integers are given to each name.\n",
      "These identifiers are computed based on a custom hash of the\n",
      "reaction name.  This hash function reserves space for MT numbers by\n",
      "not producing values below 1000.  It is recommended that the\n",
      "reaction identifiers be used for most performance critical tasks,\n",
      "rather than the names that they are calculated from.\n",
      "\n",
      "**Reaction Labels:** Reaction labels are short, human-readable\n",
      "strings.  These do not follow the naming convention restrictions\n",
      "that the names themselves are subject to.  Additionally, labels need\n",
      "not be unique.  The labels are provided as a convenience for\n",
      "building user interfaces with.\n",
      "\n",
      "**Reaction Docstrings:** Similar to labels, reactions also come with\n",
      "a documentation string which gives a description of the reaction in\n",
      "a sentence or two. These provide more help and information for a\n",
      "reaction.  This may be useful in a tool tip context for user\n",
      "interfaces.\n",
      "\n",
      "**Other Canonical Forms:** This module provides mappings between\n",
      "other reaction canonical forms and the naming conventions and IDs\n",
      "used here.  The most widespread of these are arguably the MT\n",
      "numbers.  MT numbers are a strict subset of the reactions used here.\n",
      "Further information may be found at NNDC, NEA, T2, and\n",
      "JAEA.\n",
      "\n",
      "The rxname module implements a suite of functions for computing or\n",
      "retrieving reaction names and their associated data described above.\n",
      "These functions have a variety of interfaces. Lookup may occur either by\n",
      "name, ID, MT number, a string of ID, or a string of MT number.\n",
      "\n",
      "However, lookup may also occur via alternate names or abbreviations.\n",
      "For example, \"tot\" and \"abs\" will give the names \"total\" and\n",
      "\"absorption\".  Spelling out particles will also work; \"alpha\" and \"duet\"\n",
      "will give \"a\" and \"d\".  For a listing of all alternative names see the\n",
      "``altnames`` variable.\n",
      "\n",
      "Furthermore, certain reactions may be inferred from the nuclide prior\n",
      "and post reaction.  For example, if an incident neutron hit U-235 and\n",
      "Th-232 was produced then an alpha production reaction is assumed to have\n",
      "occurred. Thus most of the functions in rxname will take a from nuclide,\n",
      "a to nuclide, and z -- the incident particle type (which defaults to \"n\"\n",
      "neutron).  Note that z may also be \"decay\", indicating a radioactive\n",
      "decay occurrence."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from pyne import rxname"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Each reaction name has a unique id number"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print rxname.id(\"total\")\n",
      "print rxname.id(103)    # MT number for proton\n",
      "print rxname.id(\"abs\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "1313192322\n",
        "1104\n",
        "3163131457\n"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "These are defined on the range from `1000 < id <= 2^32` so that they do not conflict with MT numbers.\n",
      "\n",
      "----------\n",
      "\n",
      "The string names are also unique:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print rxname.name(\"total\")\n",
      "print rxname.name(103)    # MT number for proton production\n",
      "print rxname.name(\"abs\")  # an abbreviation for absorption"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "total\n",
        "p\n",
        "absorption\n"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "---------\n",
      "\n",
      "Each reaction also has meta-data that is stored as short 'labels' and longer documentation strings"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print rxname.label('p')\n",
      "print rxname.doc('p')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "(z,p)\n",
        "(z,p) Production of p\n"
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "---------\n",
      "\n",
      "Where possible, MT numbers may be looked up."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print rxname.mt('elastic')\n",
      "print rxname.mt('p')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "2\n",
        "103\n"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "-----\n",
      "Finally, nuclides themselves may also be used to look up reactions."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# From -> to\n",
      "rxname.name(\"U235\", \"U236\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 11,
       "text": [
        "'absorption'"
       ]
      }
     ],
     "prompt_number": 11
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This interface has a notion of the incident particle type (`z`).  This defaults to `n` for neutrons but may be any of the particle types listed above."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "rxname.name(\"U235\", \"Np236\", \"p\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 12,
       "text": [
        "'absorption'"
       ]
      }
     ],
     "prompt_number": 12
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "rxname.name(922350000, 912350000)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 13,
       "text": [
        "'p'"
       ]
      }
     ],
     "prompt_number": 13
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "There are also ``parent()`` and ``child()`` functions which instead let you discover the parent or child from a nuclide, the reaction, and the incidnet particle type."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "rxname.parent(\"U236\", 'abs')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 14,
       "text": [
        "922350000"
       ]
      }
     ],
     "prompt_number": 14
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "rxname.child(\"U235\", 'abs', 'p')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 15,
       "text": [
        "932360000"
       ]
      }
     ],
     "prompt_number": 15
    }
   ],
   "metadata": {}
  }
 ]
}