Add scientific description to documentation

docs/src/references.bib

@@ -1,20 +1,91 @@
-@Article{Morel-Maritorena-2001,
+@article{Moore-2008,
+	Author = {J. K. Moore and O. Braucher},
+	Date-Added = {2018-06-07 17:29:42 +0000},
+	Date-Modified = {2018-06-07 17:30:17 +0000},
+	Journal = {Biogeosciences},
+	Pages = {631--656},
+	Title = {Sedimentary and mineral dust sources of dissolved iron to the world ocean},
+	Volume = {5},
+	Year = {2008}}
+
+@article{Moore-2007,
+	Author = {J. K. Moore and S. C. Doney},
+	Date-Added = {2018-06-07 17:29:04 +0000},
+	Date-Modified = {2018-06-07 17:29:35 +0000},
+	Journal = {Global Biogeochem. Cycles},
+	Title = {Iron availability limits the ocean nitrogen inventory stabilizing feedbacks between marine denitrification and nitrogen fixation},
+	Volume = {21},
+	Year = {2007}}
+
+@article{Moore-2004,
+	Author = {J. K. Moore and S. C. Doney and K. Lindsay},
+	Date-Added = {2018-06-07 17:17:57 +0000},
+	Date-Modified = {2018-06-07 17:18:35 +0000},
+	Journal = {Global Biogeochem. Cycles},
+	Title = {Upper ocean ecosystem dynamics and iron cycling in a global three-dimensional model},
+	Volume = {18},
+	Year = {2004}}
+
+@article{Moore-2002,
+	Author = {J. K. Moore and S. Doney and J. Kleypas and D. Glover and I. Fung},
+	Date-Added = {2018-06-07 17:16:25 +0000},
+	Date-Modified = {2018-06-07 17:17:17 +0000},
+	Journal = {Deep-Sea Res. II},
+	Pages = {403--462},
+	Title = {An intermediate complexity marine ecosystem model for the global domain},
+	Volume = {49},
+	Year = {2002}}
+
+@article{Krishnamurthy-2007,
+	Author = {A. Krishnamurthy and J. K. Moore and C. S. Zender and C. Luo},
+	Date-Added = {2018-06-07 17:13:45 +0000},
+	Date-Modified = {2018-06-07 17:14:36 +0000},
+	Journal = {J. Geophys. Res.},
+	Title = {The effects of atmospheric inorganic nitrogen deposition on ocean biogeochemistry},
+	Volume = {112},
+	Year = {2007}}
+
+@article{Geider-1998,
+	Author = {R. Geider and H. MacIntyre and T. Kana},
+	Date-Added = {2018-06-07 17:11:13 +0000},
+	Date-Modified = {2018-06-07 17:12:03 +0000},
+	Journal = {Limnology and Oceanography},
+	Pages = {679--694},
+	Title = {A dynamic regulatory model of phytoplankton acclimation to light, nutrients, and temperature},
+	Volume = {43},
+	Year = {1998}}
+
+@article{Doney-2009,
+	Author = {S. C. Doney and I. Lima and J.K. Moore and K. Lindsay and M.J. Behrenfeld and T.K. Westberry and N. Mahowald and D.M. Glover and T. Takahashi},
+	Date-Added = {2018-06-07 17:01:30 +0000},
+	Date-Modified = {2018-06-07 17:03:16 +0000},
+	Journal = {J. Mar. Systems},
+	Pages = {95--112},
+	Title = {Skill metrics for confronting global upper ocean ecosystem-biogeochemistry models against field and remote sensing data},
+	Volume = {76},
+	Year = {2009}}
+
+@article{Morel-2001,
 	Author = {Morel, Andr{\'e} and Maritorena, St{\'e}phane},
 	Doi = {10.1029/2000jc000319},
+	Date-Modified = {2018-06-07 17:00:54 +0000},
 	Journal = {J. Geophys. Res.},
 	Month = {Apr},
 	Number = {C4},
 	Pages = {7163--7180},
 	Title = {Bio-optical properties of oceanic waters: A reappraisal},
 	Volume = {106},
-	Year = {2001}}
+	Year = {2001},
+	Bdsk-Url-1 = {https://dx.doi.org/10.1029/2000jc000319}}
 
-@article{Morel-1998,
+@article{Morel-1988,
 	Author = {Morel, Andr{\'e}},
 	Doi = {10.1029/jc093ic09p10749},
+	Date-Modified = {2018-06-07 16:57:25 +0000},
 	Journal = {J. Geophys. Res.},
 	Number = {C9},
 	Pages = {10749-10768},
 	Title = {{Optical modeling of the upper ocean in relation to its biogenous matter content (case I waters)}},
 	Volume = {93},
-	Year = {1988}}
+	Year = {1988},
+	Bdsk-Url-1 = {https://dx.doi.org/10.1029/jc093ic09p10749}}

docs/src/sci-guide/index.rst

@@ -4,9 +4,36 @@
 MARBL scientific documentation
 ==============================
 
+The default MARBL configuration invokes the Biogeochemical Elemental Cycling (BEC) model  :cite:`Moore-2004`. which is an ecosystem/biogeochemistry model designed to run within the ocean circulation component of CESM.
+
+The ecosystem includes multiple phytoplankton functional groups (diatoms, diazotrophs, small phytoplankton, and coccolithophores) and multiple potentially growth limiting nutrients (nitrate, ammonium, phosphate, silicate, and iron) :cite:`Moore-2002,Moore-2004`.
+There is one zooplankton group, dissolved organic material (semi-labile), sinking particulate pools and explicit simulation of the biogeochemical cycling of key elements (C, N, P, Fe, Si, O, plus alkalinity) :cite:`Moore-2004`.
+The ecosystem component is coupled with a carbonate chemistry module based on the Ocean Carbon Model Intercomparison Project (OCMIP) :cite:`Doney-2009` allowing dynamic computation of surface ocean pCO2 and air-sea CO2 flux.
+
+The model allows for water column denitrication, whereby nitrate is consumed during remineralization in place of O2 once ambient O2 concentrations fall below 4 micro-molar :cite:`Moore-2007`.
+Photoadaptation is calculated as a variable phytoplankton ratio of chlorophyll to nitrogen based on Geider et al. :cite:`Geider-1998`.
+The model allows for variable Fe/C and Si/C ratios with an optimum and minimum value prescribed.
+As ambient Fe (or Si for diatoms) concentrations decline the phytoplankton lower their cellular quotas.
+Phytoplankton N/P ratios are fixed at the Redfield value of 16, but the diazotroph group has a higher N/P atomic ratio of 50 (see detailed description of the model in Moore et al., 2002 :cite:`Moore-2002`, and Moore et al., 2004 :cite:`Moore-2004`).
+Thus, community N/P uptake varies with the phytoplankton community composition.
+
+The ecosystem model results have been compared extensively against in situ data (e.g., JGOFS time series stations) and SeaWiFS satellite ocean color observations in a global mixed layer only variant and coupled with a full-depth, global 3-D general circulation model :cite:`Moore-2002,Moore-2004,Doney-2009`.
+In both cases, the simulated output is in generally good agreement with bulk ecosystem observations (e.g., total biomass, productivity, nutrients, export) across diverse ecosystems that include both macro-nutrient and iron-limited regimes as well as very different physical environments from high latitude sites to the mid-ocean gyres.
+The model also incorporates the work of Moore and Braucher :cite:`Moore-2008`, who incorporated an improved sedimentary iron source and scavenging parameterization, greatly improving simulated iron fields relative to observations, and the work of Krishnamurthy et al. :cite:`Krishnamurthy-2007`, who describe the impact of atmospheric deposition of nitrogen.
+
+.. note::
+  This description is still under development.
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
    phytoplankton-growth.rst
    light-attenuation.rst
+
+.. only:: html
+
+  .. rubric:: References
+
+.. bibliography:: ../references.bib
+   :filter: docname in docnames

docs/src/sci-guide/light-attenuation.rst

@@ -4,11 +4,11 @@
  Light attenuation formulation
 ===============================
 
-Starting point is equation 6 of :cite:`Morel-Maritorena-2001`
+Starting point is equation 6 of :cite:`Morel-2001`
 
 .. math::
    :label: ze_chl_tot
-	  
+
    Z_e =
    \begin{cases}
    912.5 \left[ \mathrm{Chl_{tot}} \right]^{-0.839} & 10 < Z_e < 102 \\
@@ -24,9 +24,9 @@ averaged over the euphotic zone
 
 .. math::
    :label: chl_tot_def
-      
+
    \left[ \mathrm{Chl_{tot}} \right] =  Z_e \overline{\left[ \mathrm{Chl} \right]}
-   
+
 The crossover point :math:`Z_e=102` corresponds to
 :math:`\left[ \mathrm{Chl_{tot}} \right]=13.65`, which is equivalent to
 :math:`\overline{\left[ \mathrm{Chl} \right]}=0.1338`.
@@ -39,12 +39,12 @@ and solving for :math:`Z_e` yields
 
    Z_e =
    \begin{cases}
-	   40.710 \overline{\left[ \mathrm{Chl} \right]}^{-0.4562} & \overline{\left[ \mathrm{Chl} \right]} > 0.1338 \\
-   50.105 \overline{\left[ \mathrm{Chl} \right]}^{-0.3536} & \overline{\left[ \mathrm{Chl} \right]} < 0.1338
+     40.710 \overline{\left[ \mathrm{Chl} \right]}^{-0.4562} & \overline{\left[ \mathrm{Chl} \right]} > 0.1338 \\
+     50.105 \overline{\left[ \mathrm{Chl} \right]}^{-0.3536} & \overline{\left[ \mathrm{Chl} \right]} < 0.1338
    \end{cases}
 
 The euphotic zone depth is defined to be the depth where PAR is 1\% of its surface value
-:cite:`Morel-1998`.
+:cite:`Morel-1988`.
 
 We denote the attenuation coefficient of PAR as :math:`K`, and its effective average over the
 euphotic zone as :math:`\overline{K}`.
@@ -67,7 +67,7 @@ solving for :math:`\overline{K}` yields
 
 .. math::
    :label: Kbar_chl_avg
-   
+
    \overline{K} =
    \begin{cases}
    0.1131 \overline{\left[ \mathrm{Chl} \right]}^{0.4562} & \overline{\left[ \mathrm{Chl} \right]} > 0.1338 \\
@@ -84,8 +84,9 @@ The units of :math:`K` in equation :eq:`Kbar_chl_avg` are 1/m.
 
 Model units are cm, so the model implementation includes multiplication by 0.01.
 
-.. rubric:: References
-
-.. bibliography:: ../references.bib 
-   :cited:
-
+.. only:: html
+
+  .. rubric:: References
+
+.. bibliography:: ../references.bib
+  :filter: docname in docnames