added support for tikz extension in sphinx and included first part of theory section

docs/source/conf.py

@@ -23,7 +23,7 @@ sys.path.insert(0, os.path.abspath('../sphinxext'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.pngmath']
+extensions = ['sphinx.ext.pngmath', 'sphinxcontrib.tikz']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -188,7 +188,14 @@ latex_documents = [
    u'Massachusetts Institute of Technology', 'manual'),
 ]
 
-latex_elements = {'preamble': '\\usepackage{enumitem}\\setlistdepth{9}'}
+latex_elements = {
+'preamble': '''
+\usepackage{enumitem}
+\setlistdepth{9}
+\usepackage{tikz}
+\usetikzlibrary{shapes,snakes,shadows,arrows,calc,decorations.markings,patterns,fit,matrix,spy}
+'''
+}
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.

docs/source/methods/cmfd.rst

@@ -36,3 +36,78 @@ and :math:`h` are also listed as superscripts here. The group :math:`g` is the
 group of interest and, if present, :math:`h` is all groups. Finally, any
 parameter surrounded by :math:`\left\langle\cdot\right\rangle` represents a
 tally quantity that can be edited from an MC solution.
+
+------
+Theory
+------
+
+NDA is a diffusion model that has equivalent physics to a transport model. There
+are many different methods that can be classified as NDA. The CMFD method is a
+type of NDA that represents second order multigroup diffusion equations on a
+coarse spatial mesh.  Whether a transport model or diffusion model is used to
+represent the distribution of neutrons, these models must satisfy the *neutron
+balance equation*. This balance is represented by the following formula for a
+specific energy group :math:`g` in cell :math:`(l,m,n)`:
+
+.. math::
+    :label: eq_neut_bal
+
+    \sum\limits_{u\in(x,y,z)}\left(\left\langle\overline{J}^{u,g}_{l+1/2,m,n}
+    \Delta_m^v\Delta_n^w\right\rangle -
+    \left\langle\overline{J}^{u,g}_{l-1/2,m,n}
+    \Delta_m^v\Delta_n^w\right\rangle\right)
+    +
+    \left\langle\overline{\overline\Sigma}_{t_{l,m,n}}^g
+    \overline{\overline\phi}_{l,m,n}^g\Delta_l^u\Delta_m^v\Delta_n^w\right\rangle
+    = \\
+    \sum\limits_{h=1}^G\left\langle
+    \overline{\overline{\nu_s\Sigma}}_{s_{l,m,n}}^{h\rightarrow
+    g}\overline{\overline\phi}_{l,m,n}^h\Delta_l^u\Delta_m^v\Delta_n^w
+    \right\rangle
+    +
+    \frac{1}{k_{eff}}\sum\limits_{h=1}^G
+    \left\langle\overline{\overline{\nu_f\Sigma}}_{f_{l,m,n}}^{h\rightarrow
+    g}\overline{\overline\phi}_{l,m,n}^h
+    \Delta_l^u\Delta_m^v\Delta_n^w\right\rangle.
+
+In eq. :eq:`eq_neut_bal` the parameters are defined as:
+
+* :math:`\left\langle\overline{J}^{u,g}_{l\pm
+  1/2,m,n}\Delta_m^v\Delta_n^w\right\rangle` --- surface area-integrated net
+  current over surface :math:`(l\pm 1/2,m,n)` with surface normal in direction
+  $u$ in energy group :math:`g`. By dividing this quantity by the transverse
+  area, :math:`\Delta_m^v\Delta_n^w`, the surface area-averaged net current can
+  be computed.
+* :math:`\left\langle\overline{\overline\Sigma}_{t_{l,m,n}}^g
+  \overline{\overline\phi}_{l,m,n}^g\Delta_l^u\Delta_m^v\Delta_n^w\right\rangle`
+  --- volume-integrated total reaction rate over energy group :math:`g`.
+  * :math:`\left\langle\overline{\overline{\nu_s\Sigma}}_{s_{l,m,n}}^{h\rightarrow
+  g}
+  \overline{\overline\phi}_{l,m,n}^h\Delta_l^u\Delta_m^v\Delta_n^w\right\rangle`
+  --- volume-integrated scattering production rate of neutrons that begin with
+  energy in group :math:`h` and exit reaction in group :math:`g`. This reaction
+  rate also includes the energy transfer of reactions (except fission) that
+  produce multiple neutrons such as (n, 2n); hence, the need for :math:`\nu_s`
+  to represent neutron multiplicity.
+* :math:`k_{eff}` --- core multiplication factor.
+* :math:`\left\langle\overline{\overline{\nu_f\Sigma}}_{f_{l,m,n}}^{h\rightarrow
+  g}\overline{\overline\phi}_{l,m,n}^h\Delta_l^u\Delta_m^v\Delta_n^w\right\rangle`
+  --- volume-integrated fission production rate of neutrons from fissions in
+  group :math:`h` that exit in group :math:`g`.
+
+Each quantity in :math:`\left\langle\cdot\right\rangle` represents a scalar value that
+is obtained from an MC tally. A good verification step when using an MC is
+to make sure that tallies satisfy this balance equation within statistics. No
+NDA acceleration can be performed if the balance equation is not satisfied.
+
+There are three major steps to consider when performing NDA: (1) calculation of
+macroscopic cross sections and nonlinear parameters, (2) solving an eigenvalue
+problem with a system of linear equations, and (3) modifying MC source
+distribution to align with the NDA solution on a chosen mesh. This process is
+illustrated as a flow chart below. After a batch of neutrons
+is simulated, NDA can take place. Each of the steps described above is described
+in detail in the following sections.
+
+.. tikz:: Flow chart of NDA process 
+   :libs: shapes, snakes, shadows, arrows, calc, decorations.markings, patterns, fit, matrix, spy
+   :include: cmfd_tikz/cmfd_flow.tikz

docs/source/methods/cmfd_tikz/cmfd_flow.tikz

@@ -0,0 +1,19 @@
+\begin{tikzpicture}
+	\matrix[every node/.style={draw, thick, minimum width=3cm, minimum height=1cm, align=center}, column sep=2cm, row sep=1cm] (m) {
+\node[draw, fill=red!40] (start) {Batch $i$ \\ tally NDA}; & \\
+ \node[draw, diamond, aspect=2, fill=green!40] (cmfd) {Run NDA?}; & \node[draw, fill=red!40] (end) {Batch $i + 1$ \\ tally NDA};  \\
+\node[draw, fill=blue!40] (xs) {Calculate XS \& DC}; & \node[draw, fill=blue!40] (modify) {Modify MC Source}; \\
+\node[draw, fill=blue!40] (nonlinear) {Calculate Equivalence}; &  \node[draw, fill=blue!40] (eqs) {Solve NDA eqs.};\\
+};
+
+\begin{scope}[every path/.style={->,very thick,draw}]
+        \draw (start.south) -- (cmfd.north);
+        \draw (cmfd.east)  -- node[above] {no} (end.west);
+        \draw (cmfd.south)  -- node[right] {yes} (xs.north);
+		\draw (xs.south)  --  (nonlinear.north);
+		\draw (nonlinear.east)  --  (eqs.west);
+		\draw (eqs.north)  --  (modify.south);
+		\draw (modify.north)  --  (end.south);
+    \end{scope}
+
+\end{tikzpicture}