{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Materials\n",
      "\n",
      "Materials are the primary container for radionuclides. They map nuclides to **mass weights**,\n",
      "though they contain methods for converting to/from atom fractions as well.\n",
      "In many ways they take inspiration from numpy arrays and python dictionaries.  Materials\n",
      "have two main attributes which define them.\n",
      "\n",
      "1. **comp**: a normalized composition mapping from nuclides (id ints) to mass-weights (floats).\n",
      "1. **mass**: the mass of the material.\n",
      "\n",
      "By keeping the mass and the composition separate, operations that only affect one attribute\n",
      "may be performed independent of the other.  Additionally, most of the functionality is\n",
      "implemented in a C++ class by the same name, so this interface is very fast and light-weight.\n",
      "Materials may be initialized in a number of different ways.  For example, initializing from\n",
      "dictionaries of compositions are shown below."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from pyne.material import Material"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu = Material({'U238': 0.96, 'U235': 0.04}, 42)\n",
      "leu"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 2,
       "text": [
        "pyne.material.Material({922350000: 0.04, 922380000: 0.96}, 42.0, -1.0, -1.0, {})"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nucvec = {10010:  1.0, 80160:  1.0, 691690: 1.0, 922350: 1.0,\n",
      "          922380: 1.0, 942390: 1.0, 942410: 1.0, 952420: 1.0,\n",
      "          962440: 1.0}\n",
      "mat = Material(nucvec)\n",
      "print mat"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Material:\n",
        "mass = 9.0\n",
        "density= -1.0\n",
        "atoms per molecule = -1.0\n",
        "-------------------------\n",
        "H1     0.111111111111\n",
        "O16    0.111111111111\n",
        "Tm169  0.111111111111\n",
        "U235   0.111111111111\n",
        "U238   0.111111111111\n",
        "Pu239  0.111111111111\n",
        "Pu241  0.111111111111\n",
        "Am242  0.111111111111\n",
        "Cm244  0.111111111111\n"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "-------\n",
      "\n",
      "## Normalization\n",
      "\n",
      "Materials may also be initialized from plain text or HDF5 files (see ``Material.from_text()`` and\n",
      "``Material.from_hdf5()``).  Once you have a Material instance, you can always obtain the unnormalized\n",
      "mass vector through ``Material.mult_by_mass()``.  Normalization routines to normalize the mass \n",
      "``Material.normalize()`` or the composition ``Material.norm_comp()`` are also available."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu.mult_by_mass()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 4,
       "text": [
        "{922350000: 1.68, 922380000: 40.32}"
       ]
      }
     ],
     "prompt_number": 4
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mat.normalize()\n",
      "mat.mult_by_mass()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 5,
       "text": [
        "{10010000: 0.1111111111111111, 80160000: 0.1111111111111111, 691690000: 0.1111111111111111, 922350000: 0.1111111111111111, 922380000: 0.1111111111111111, 942390000: 0.1111111111111111, 942410000: 0.1111111111111111, 952420000: 0.1111111111111111, 962440000: 0.1111111111111111}"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mat.mass"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 6,
       "text": [
        "1.0"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "-----------\n",
      "\n",
      "## Material Arithmetic\n",
      "\n",
      "Furthermore, various arithmetic operations between Materials and numeric types are also defined.\n",
      "Adding two Materials together will return a new Material whose values are the weighted union\n",
      "of the two original. Multiplying a Material by 2, however, will simply double the mass."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "other_mat = mat * 2\n",
      "other_mat"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 7,
       "text": [
        "pyne.material.Material({10010000: 0.11111111111111108, 80160000: 0.11111111111111108, 691690000: 0.11111111111111108, 922350000: 0.11111111111111108, 922380000: 0.11111111111111108, 942390000: 0.11111111111111108, 942410000: 0.11111111111111108, 952420000: 0.11111111111111108, 962440000: 0.11111111111111108}, 2.0, -1.0, -1.0, {})"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "other_mat.mass"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 8,
       "text": [
        "2.0"
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "weird_mat = leu + mat * 18\n",
      "print weird_mat"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Material:\n",
        "mass = 60.0\n",
        "density= -1.0\n",
        "atoms per molecule = -1.0\n",
        "-------------------------\n",
        "H1     0.0333333333333\n",
        "O16    0.0333333333333\n",
        "Tm169  0.0333333333333\n",
        "U235   0.0613333333333\n",
        "U238   0.705333333333\n",
        "Pu239  0.0333333333333\n",
        "Pu241  0.0333333333333\n",
        "Am242  0.0333333333333\n",
        "Cm244  0.0333333333333\n"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "---------------\n",
      "\n",
      "## Raw Member Access\n",
      "\n",
      "You may also change the attributes of a material directly without generating a new \n",
      "material instance."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "other_mat.mass = 10\n",
      "other_mat.comp = {10020: 3, 922350: 15.0}\n",
      "print other_mat"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Material:\n",
        "mass = 10.0\n",
        "density= -1.0\n",
        "atoms per molecule = -1.0\n",
        "-------------------------\n",
        "H2     3.0\n",
        "U235   15.0\n"
       ]
      }
     ],
     "prompt_number": 10
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Of course when you do this you have to be careful because the composition and mass may now be out\n",
      "of sync.  This may always be fixed with normalization."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "other_mat.norm_comp()\n",
      "print other_mat"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Material:\n",
        "mass = 10.0\n",
        "density= -1.0\n",
        "atoms per molecule = -1.0\n",
        "-------------------------\n",
        "H2     0.166666666667\n",
        "U235   0.833333333333\n"
       ]
      }
     ],
     "prompt_number": 11
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "--------\n",
      "\n",
      "## Indexing & Slicing\n",
      "\n",
      "Additionally (and very powerfully!), you may index into either the material or the composition \n",
      "to get, set, or remove sub-materials.  Generally speaking, the composition you may only index \n",
      "into by integer-key and only to retrieve the normalized value.  Indexing into the material allows the \n",
      "full range of operations and returns the unnormalized mass weight.  Moreover, indexing into\n",
      "the material may be performed with integer-keys, string-keys, slices, or sequences of nuclides."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu.comp[922350000]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 12,
       "text": [
        "0.04"
       ]
      }
     ],
     "prompt_number": 12
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu['U235']"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 13,
       "text": [
        "1.68"
       ]
      }
     ],
     "prompt_number": 13
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "weird_mat['U':'Am']"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 14,
       "text": [
        "pyne.material.Material({922350000: 0.07359999999999998, 922380000: 0.8464, 942390000: 0.03999999999999998, 942410000: 0.03999999999999998}, 50.0, -1.0, -1.0, {})"
       ]
      }
     ],
     "prompt_number": 14
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "other_mat[:920000000] = 42.0\n",
      "print other_mat"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Material:\n",
        "mass = 84.0\n",
        "density= -1.0\n",
        "atoms per molecule = -1.0\n",
        "-------------------------\n",
        "H2     0.5\n",
        "U235   0.5\n"
       ]
      }
     ],
     "prompt_number": 15
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "del mat[962440, 'TM169', 'Zr90', 80160]\n",
      "mat[:]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 16,
       "text": [
        "pyne.material.Material({10010000: 0.16666666666666663, 922350000: 0.16666666666666663, 922380000: 0.16666666666666663, 942390000: 0.16666666666666663, 942410000: 0.16666666666666663, 952420000: 0.16666666666666663}, 0.666666666667, -1.0, -1.0, {})"
       ]
      }
     ],
     "prompt_number": 16
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Other methods also exist for obtaining commonly used sub-materials, such as gathering the Uranium or \n",
      "Plutonium vector.  "
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Molecular Weights & Atom Fractions\n",
      "\n",
      "You may also calculate the molecular weight of a material via the ``Material.molecular_weight`` method.\n",
      "This uses the ``pyne.data.atomic_mass`` function to look up the atomic mass values of\n",
      "the constituent nuclides."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu.molecular_weight()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 17,
       "text": [
        "237.92903775287186"
       ]
      }
     ],
     "prompt_number": 17
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Note that by default, materials are assumed to have one atom per molecule.  This is a poor\n",
      "assumption for more complex materials.  For example, take water.  Without specifying the \n",
      "number of atoms per molecule, the molecular weight calculation will be off by a factor of 3.\n",
      "This can be remedied by passing the correct number to the method.  If there is no other valid\n",
      "number of molecules stored on the material, this will set the appropriate attribute on the \n",
      "class."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "h2o = Material({10010: 0.11191487328808077, 80160: 0.8880851267119192})\n",
      "h2o.molecular_weight()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 18,
       "text": [
        "6.003521561343334"
       ]
      }
     ],
     "prompt_number": 18
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "h2o.molecular_weight(3.0)\n",
      "h2o.atoms_per_mol"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 19,
       "text": [
        "3.0"
       ]
      }
     ],
     "prompt_number": 19
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "It is often also useful to be able to convert the current mass-weighted material to \n",
      "an atom fraction mapping.  This can be easily done via the `Material.to_atom_frac()`\n",
      "method.  Continuing with the water example, if the number of atoms per molecule is \n",
      "properly set then the atom fraction return is normalized to this amount.  Alternatively, \n",
      "if the atoms per molecule are set to its default state on the class, then a truly \n",
      "fractional number of atoms is returned."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "h2o.to_atom_frac()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 20,
       "text": [
        "{10010000: 2.0, 80160000: 1.0}"
       ]
      }
     ],
     "prompt_number": 20
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "h2o.atoms_per_mol = -1.0\n",
      "h2o.to_atom_frac()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 21,
       "text": [
        "{10010000: 0.6666666666666666, 80160000: 0.3333333333333333}"
       ]
      }
     ],
     "prompt_number": 21
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Additionally, you may wish to convert the an existing set of atom fractions to a \n",
      "new material stream.  This can be done with the `Material.from_atom_frac()` method, \n",
      "which will clear out the current contents of the material's composition and replace\n",
      "it with the mass-weighted values.  Note that when you initialize a material from atom \n",
      "fractions, the sum of all of the atom fractions will be stored as the atoms per molecule \n",
      "on this class.  Additionally, if a mass is not already set on the material, the molecular\n",
      "weight will be used."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "h2o_atoms = {10010: 2.0, 'O16': 1.0}\n",
      "h2o = Material()\n",
      "h2o.from_atom_frac(h2o_atoms)\n",
      "\n",
      "print h2o.comp\n",
      "print h2o.atoms_per_mol\n",
      "print h2o.mass\n",
      "print h2o.molecular_weight()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "{10010: 0.1111425112195276, 80160000: 0.8888574887804724}\n",
        "3.0\n",
        "17.9949146196\n",
        "17.9949146196\n"
       ]
      }
     ],
     "prompt_number": 22
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Moreover, other materials may also be used to specify a new material from atom fractions.\n",
      "This is a typical case for reactors where the fuel vector is convolved inside of another \n",
      "chemical form.  Below is an example of obtaining the Uranium-Oxide material from Oxygen\n",
      "and low-enriched uranium."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "uox = Material()\n",
      "uox.from_atom_frac({leu: 1.0, 'O16': 2.0})\n",
      "print uox"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Material:\n",
        "mass = 269.918866992\n",
        "density= -1.0\n",
        "atoms per molecule = 3.0\n",
        "------------------------\n",
        "O16    0.118516462356\n",
        "U235   0.0352593415057\n",
        "U238   0.846224196138\n"
       ]
      }
     ],
     "prompt_number": 23
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "**NOTE:** Materials may be used as keys in a dictionary because they are hashable."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### User-defined Metadata\n",
      "\n",
      "Materials also have an ``attrs`` attribute which allows users to store arbitrary \n",
      "custom information about the material.  This can include things like units, comments, \n",
      "provenance information, or anything else the user desires.  This is implemented as an\n",
      "in-memory JSON object attached to the C++ class.  Therefore, what may be stored in\n",
      "the ``attrs`` is subject to the same restrictions as JSON itself.  The top-level \n",
      "of the attrs *should* be a dictionary, though this is not explicitly enforced."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu = Material({922350: 0.05, 922380: 0.95}, 15, attrs={'units': 'kg'})\n",
      "leu"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 24,
       "text": [
        "pyne.material.Material({922350000: 0.05, 922380000: 0.95}, 15.0, -1.0, -1.0, {\"units\":\"kg\"})"
       ]
      }
     ],
     "prompt_number": 24
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print leu"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Material:\n",
        "mass = 15.0\n",
        "density= -1.0\n",
        "atoms per molecule = -1.0\n",
        "units = kg\n",
        "-------------------------\n",
        "U235   0.05\n",
        "U238   0.95\n"
       ]
      }
     ],
     "prompt_number": 25
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu.attrs"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 26,
       "text": [
        "{\"units\":\"kg\"}"
       ]
      }
     ],
     "prompt_number": 26
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "a = leu.attrs\n",
      "a['comments'] = ['Anthony made this material.']\n",
      "leu.attrs['comments'].append('And then Katy made it better!')\n",
      "a['id'] = 42\n",
      "leu.attrs"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 27,
       "text": [
        "{\"comments\":[\"Anthony made this material.\",\"And then Katy made it better!\"],\"id\":42,\"units\":\"kg\"}"
       ]
      }
     ],
     "prompt_number": 27
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu.attr = {'units': 'solar mass'}\n",
      "leu.attr"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 28,
       "text": [
        "{'units': 'solar mass'}"
       ]
      }
     ],
     "prompt_number": 28
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "a"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 29,
       "text": [
        "{\"comments\":[\"Anthony made this material.\",\"And then Katy made it better!\"],\"id\":42,\"units\":\"kg\"}"
       ]
      }
     ],
     "prompt_number": 29
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "leu.attr['units'] = 'not solar masses'\n",
      "leu.attr['units']"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 30,
       "text": [
        "'not solar masses'"
       ]
      }
     ],
     "prompt_number": 30
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "As you can see from the above, the attrs interface provides a view into the underlying \n",
      "JSON object.  This can be manipulated directly or by renaming it to another variable.\n",
      "Additionally, ``attrs`` can be replaced with a new object of the appropriate type. \n",
      "Doing so invalidates any previous views into this container."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}