oklo 0.1

OKLO: A toolkit for modeling nuclides and nuclear reactions
===========================================================

The OKLO package provides a set of convenient tools for modeling
nuclides and the reactions between them. It provides methods to
uniquely identify the known nuclides, define unique reactions which
allow transitions from one nuclide to another, associate arbitrary
user-specified data to these objects, and treat collections of
nuclides and reactions as a single network.

While this package was initially designed for the purpose of
calculating the flux of antineutrinos emitted by nuclear reactors, it
is designed in a generic fashion for a broad range of applications
(e.g. solar physics, supernova physics, etc.).


Installation:
=============

Installion is most convenient via the pip utility:
::
$ pip install oklo

Description:
============

Here follows a brief description of the core tools provided by the
OKLO package.

Nuclide:
--------

A nuclide is a unique nuclear state identified by the number of
protons and number of neutrons in the nucleus, as well as an optional
metastable isomeric energy level. Each nuclide serves as a data
'whiteboard'. Users can associate arbitrary data with a nuclide using
a standard (key, value) approach.
::
>>> from oklo.core.ids import NuclideId
>>> from oklo.core.nuclide import Nuclide
>>> C_12_id = NuclideId(Z=6,A=12,M=0) # Create unique ID for Carbon-12
>>> C_12 = Nuclide(nucl_id=C_12_id) # Create nuclide object
>>> C_12.Z
6
>>> C_12.A
12
>>> C_12.M
0
>>> C_12.N
6
>>> C_12.name
'Carbon_12'
>>> C_12.element_name
'Carbon'
>>> C_12.element_abbrev
'C'
>>> C_12['current_abundance'] = 0.8 # Associate user-defined data
>>> C_12['current_abundance']
0.8


Reaction:
---------

A reaction is a unique type of nuclear transition between nuclides,
such as the beta decay of 12B to 12C. Each reaction serves as a data
'whiteboard'. Users can associate arbitrary data with a reaction
using a standard (key, value) approach.
::
>>> from oklo.core.ids import NuclideId, ReactionId
>>> from oklo.core.defs import ReactionType
>>> from oklo.core.reaction import Reaction
>>> B_12_beta_decay_id = ReactionId(init_nucl_id=NuclideId('Boron_12'), \
reac_type=ReactionType.BetaDecay)
>>> B_12_beta_decay = Reaction(reac_id=B_12_beta_decay_id)
>>> B_12_beta_decay.initial_nuclide_id.name
Boron_12
>>> B_12_beta_decay.final_nuclide_id.name
Carbon_12
>>> from oklo.core.units import Hz
>>> B_12_beta_decay['current_rate'] = 1.0 * Hz
>>> B_12_beta_decay['current_rate'] / Hz
1.0


ReactionNetwork:
----------------

A ReactionNetwork is a collection of nuclides and reactions relating
these nuclides. This class serves as a standard entry point for
calculation of quantities of interest. For example, users can iterate
over the nuclides and reactions within the network to calculate total
quantities for the network.

This class is effectively a 'graph' data structure in computer science
lingo, where a set of nodes (nuclides) are connected by a set of links
(reactions).

Physical Models (NuclideModel and ReactionModel):
-------------------------------------------------

A physical model is a user-defined class which defines rules for
automating the addition of user-specified data to the whiteboards
Nuclides or Reactions. For example, you could specify the relative
abundance of each nuclide present within the sun according to your
preferred physical model.

Users should define their own physical model class which inherits from
either NuclideModel or ReactionModel base classes, and implements a
'process(nuclide)' or 'process(reaction)' function which adds the
appropriate data to the whiteboard based on the unique nuclide or
reaction ID.

Factories (NuclideFactory and ReactionFactory):
-----------------------------------------------

Factories provide a convenient method to populate a ReactionNetwork
given one or a set of physical models.

Examples:
=========

For a more advance example, demonstrating the use of models and
factories, execute the following::
$ python -i oklo/examples/antineutrino_spectrum_endf.py

This builds a reaction network for modeling a nominal commercial PWR
reactor. The network is populated with tabulated nuclear data on
cumulative fission yields and beta decay spectra. The network is then
used to estimate the average antineutrino energy spectrum emitted per
fission in the reactor.

If matplotlib is installed, then associated figures will also be
generated.