work on documentation

docs/documentation/source/demos.rst

@@ -19,7 +19,7 @@ but new demos are always welcome contributions.
 The problems are organized by type of capability, and include
 multiple examples.  For instance, the ecohydrology notebook includes
 examples of evaporation and transpiration through a broad range of
-complexity of approaches, from prescribed values to Priestly-Taylor
+complexity of approaches, from prescribed values to Priestley-Taylor
 evaporation to fully biogeophysical models.
 
 Note that ats-demos is its own repo.  This repo can be checked out

docs/documentation/source/index.rst

@@ -10,11 +10,53 @@ $$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
 
 The Advanced Terrestrial Simulator is a code for solving ecosystem-based, integrated, distributed hydrology.
 
-Capabilities are largely based on solving various forms of Richards equation coupled to a surface flow equation, along with the needed sources and sinks for ecosystem and climate models. This can (but need not) include thermal processes (especially ice for frozen soils), evapo-transpiration, albedo-driven surface energy balances, snow, biogeochemistry, plant dynamics, deformation, transport, and much more.
+Capabilities are largely based on solving various forms of Richards equation, coupled to a surface flow equation, along with the needed sources and sinks for ecosystem and climate models. This can (but need not) include thermal processes (especially ice for frozen soils), evapotranspiration, surface energy balances, snow, biogeochemistry, plant dynamics, deformation, transport, and much more.
 
 ATS is a suite of physics processes built for Amanzi.  As such documentation is split between process documentation here and framework documentation in Amanzi.  Links across the related projects attempt to build a uniform interface for the user.
 
-View our Gallery of Demo problems.
+
+Join the Community
+%%%%%%%%%%%%%%%%%%
+
+ATS is more than just a code, but a community of users with a lot of experience in both integrated hydrology, Arctic hydrology, reactive transport, and ATS code development.  Please join us on our `Google group <https://groups.google.com/forum/#!forum/ats-users>`_.  We try very hard to create a welcoming community that supports and enables our users to do their science.
+
+
+Installation
+%%%%%%%%%%%%
+
+ATS is now built as a part of Amanzi directly. Please see the `ATS installation instructions <https://github.com/amanzi/amanzi/blob/master/INSTALL_ATS.md>`_ on Amanzi's site.
+
+
+License and Copyright
+%%%%%%%%%%%%%%%%%%%%%
+
+Please see the `LICENSE <https://github.com/amanzi/ats/blob/master/LICENSE>`_ and `COPYRIGHT <https://github.com/amanzi/ats/blob/master/COPYRIGHT>`_ files included in the top level directory of your ATS download.
+
+
+
+Citation
+%%%%%%%%
+
+In all works, please cite the code:
+
+E.T. Coon, M. Berndt, A. Jan, D. Svyatsky, A.L. Atchley, E. Kikinzon, D.R. Harp, G. Manzini, E. Shelef, K. Lipnikov, R. Garimella, C. Xu, J.D. Moulton, S. Karra, S.L. Painter, E. Jafarov, and S. Molins. 2020. Advanced Terrestrial Simulator. U.S. Department of Energy, USA. Version 1.0. `DOI <https://doi.org/10.11578/dc.20190911.1>`_
+
+Additionally, consider citing one or more of the below, depending upon the application space:
+
+**Watershed Hydrology:** Coon, Ethan T., et al. "Coupling surface flow and subsurface flow in complex soil structures using mimetic finite differences." Advances in Water Resources 144 (2020): 103701. `DOI <https://doi.org/10.1016/j.advwatres.2020.103701>`_
+
+**Arctic Hydrology:** Painter, Scott L., et al. "Integrated surface/subsurface permafrost thermal hydrology: Model formulation and proof‐of‐concept simulations." Water Resources Research 52.8 (2016): 6062-6077. `DOI <https://doi.org/10.1002/2015WR018427>`_
+
+**Reactive Transport:**  Molins, Sergi, et al. "A Multicomponent Reactive Transport Model for Integrated Surface‐Subsurface Hydrology Problems." Water Resources Research 58.8 (2022): e2022WR032074. `DOI <https://doi.org/10.1029/2022WR032074>`_
+
+**Multiphysics Modeling:** Coon, Ethan T., J. David Moulton, and Scott L. Painter. "Managing complexity in simulations of land surface and near-surface processes." Environmental modelling & software 78 (2016): 134-149. `DOI <https://doi.org/10.1016/j.envsoft.2015.12.017>`_
+
+
+Wiki
+%%%%
+
+Please see our `Wiki Page <https://github.com/amanzi/ats/wiki>`_ for frequently asked questions and a Developer's Guide.
+
 
 .. toctree::
    :maxdepth: 2
@@ -23,11 +65,6 @@ View our Gallery of Demo problems.
    demos
    input_spec
 
-..   
-.. toctree::
-   :maxdepth: 2
-   :caption: Developers Guide:
-
 
 Indices and tables
 %%%%%%%%%%%%%%%%%%

docs/documentation/source/input_spec/ATSNativeSpec_dev.rst

@@ -431,7 +431,7 @@ passing info between an parent mesh and an extracted mesh.
 Specified by `"mesh type`" of `"extracted`".
 
 .. _mesh-extracted-spec:
-..admonition:: mesh-extracted-spec
+.. admonition:: mesh-extracted-spec
 
    * `"parent domain`" ``[string]`` **domain** Parent mesh's name.
 
@@ -452,8 +452,7 @@ Specified by `"mesh type`" of `"extracted`".
      of this mesh is the same as the parent mesh.  If true, the communicator of
      this mesh is the subset of the parent mesh comm that has entries on the
      surface.
-
-
+
 
 Aliased Mesh
 ============
@@ -616,8 +615,8 @@ Column Surface Meshes
 
 Specified by `"mesh type`" of `"column surface`".
 
-.. _mesh-column-spec:
-.. admonition:: mesh-column-spec
+.. _mesh-column-surface-spec:
+.. admonition:: mesh-column-surface-spec
 
    * `"parent domain`" ``[string]`` The name of the 3D mesh from which columns are generated.
      Note that the `"build columns from set`" parameter must be set in that mesh.
@@ -1892,7 +1891,7 @@ daily (which all defaults are set for).
 .. admonition:: snow-distribution-spec
 
     * `"distribution time`" ``[double]`` **86400.** Interval of snow precip input dataset. `[s]`
-    * `"precipitation function`" ``[function-spec]`` Snow precipitation Function_ spec.
+    * `"precipitation function`" ``[function-spec]`` Snow precipitation function, see Functions_.
 
     * `"diffusion`" ``[pde-diffusion-spec]`` Diffusion drives the distribution.
       Typically we use finite volume here.  See PDE_Diffusion_
@@ -3227,6 +3226,7 @@ provided in a few forms:
 
 Constant
 ^^^^^^^^
+.. _EvaluatorIndependentConstant:
  A field evaluator with no dependencies, a constant value.
 
 This evaluator is typically used for providing data that is a simple constant
@@ -5814,12 +5814,6 @@ gravity- and wind-driven redistributions, respectively.
 
 
 
-Common Land Model (ParFlow-CLM)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This is included here because it should eventually get split into
-evaluators.  Currently, the CLM SEB model is a PK only, see `Common
-Land Model PK`_.
 
 Snow evaluators
 ---------------
@@ -6357,7 +6351,7 @@ Initial condition specs are used in three places:
 * Within the PK_ spec which describes the initial condition of primary variables (true
   initial conditions).
 
-* In `IndependentVariableEvaluator Constant <Constant_>`_
+* In `EvaluatorIndependentConstant`_
 
 The first may be of multiple types of data, while the latter two are
 nearly always fields on a mesh (e.g. CompositeVectors).  The specific
@@ -7432,7 +7426,57 @@ the action of the Jacobian.  They are documented in Knoll & Keyes 2004 paper.
 
 Solver: Newton with Line Search
 -------------------------------
-** DOC GENERATION ERROR: file not found ' SolverBT ' **
+ Line search on the provided correction as a solver.
+
+Line Search accepts a correction from the Jacobian, then uses a
+process to attempt to minimize or at least ensure a reduction in the residual
+while searching *in that direction*, but not necessarily with the same
+magnitude, as the provided correction.  The scalar multiple of the search
+direction is given by :math:`\alpha`.
+
+This globalization recognizes that a true inverse Jacobian is a local
+measurement of the steepest descent direction, and so while the direction is
+guaranteed to be the direction which best reduces the residual, it may not
+provide the correct magnitude.
+
+The algorithm is a reimplementation based on PETSc SNES type BT, which in turn
+is from Numerical Methods for Unconstrained Optimization and Nonlinear
+Equations by Dennis & Schnabel, pg 325.
+
+Note, this always monitors the residual.
+
+.. _solver-line-search-spec:
+.. admonition:: solver-line-search-spec
+
+    * `"nonlinear tolerance`" ``[double]`` **1.e-6** defines the required error
+      tolerance. The error is calculated by a PK.
+
+    * `"limit iterations`" ``[int]`` **50** defines the maximum allowed number
+      of iterations.
+
+    * `"diverged tolerance`" ``[double]`` **1.e10** defines the error level
+      indicating divergence of the solver. The error is calculated by a PK.
+      Set to a negative value to ignore this check.
+
+    * `"max error growth factor`" ``[double]`` **1.e5** defines another way to
+      identify divergence pattern on earlier iterations. If the PK-specific
+      error changes drastically on two consecutive iterations, the solver is
+      terminated.
+
+    * `"modify correction`" ``[bool]`` **false** allows a PK to modify the
+      solution increment. One example is a physics-based clipping of extreme
+      solution values.
+
+    * `"accuracy of line search minimum [bits]`" ``[int]`` **10**
+
+    * `"min valid alpha`" ``[double]`` **0**
+
+    * `"max valid alpha`" ``[double]`` **10.**
+
+    * `"max line search iterations`" ``[int]`` **10**
+
+
+
 
 Solver: Nonlinear Continuation
 ------------------------------
@@ -8282,6 +8326,7 @@ Example:
 Other Common Specs
 ##################
 
+
 IOEvent
 =======
  IOEvent: base time/timestep control determing when in time to do something.
@@ -8332,6 +8377,7 @@ The IOEvent is used for multiple objects that need to indicate simulation times
 
 
 
+
 Verbose Object
 ==============
 
@@ -8372,6 +8418,7 @@ Example:
 
 
 
+
 Debugger
 ========
  A mesh and vector structure aware utility for printing info.
@@ -8397,6 +8444,7 @@ from the `"Verbose Object`" spec is set to `"high`" or higher.
 
 
 
+
 Residual Debugger
 =================
 
@@ -8417,9 +8465,9 @@ process for use with vis tools.
 
 
 
+Functions
+=========
 
-Function
-===================
  A base class for all functions of space and time.
 
 Analytic, algabraic functions of space and time are used for a variety of
@@ -9481,7 +9529,7 @@ Function values u:
 
   /f[:] = (f_0(z_0), f_1(z_1), ..., f_n(z_n))
 
-.. _column-initialization-spec
+.. _column-initialization-spec:
 .. admonition:: column-initialization-spec
 
    * `"file`" ``[string]`` HDF5 filename
@@ -9491,6 +9539,7 @@ Function values u:
 
 
 
+
 Exodus File Initialization
 --------------------------
 

docs/documentation/source/input_spec/ATSNativeSpec_dev.rst.in

@@ -536,6 +536,7 @@ provided in a few forms:
 
 Constant
 ^^^^^^^^
+.. _EvaluatorIndependentConstant:
 { EvaluatorIndependentConstant }
 
 From Function
@@ -1090,12 +1091,6 @@ Bare Soil Surface Energy Balance
 
 { seb_threecomponent_evaluator }
 
-Common Land Model (ParFlow-CLM)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This is included here because it should eventually get split into
-evaluators.  Currently, the CLM SEB model is a PK only, see `Common
-Land Model PK`_.
 
 Snow evaluators
 ---------------
@@ -1358,7 +1353,7 @@ Solver: Jacobian-Free Newton Krylov
 
 Solver: Newton with Line Search
 -------------------------------
-{ SolverBT }
+{ SolverLS }
 
 Solver: Nonlinear Continuation
 ------------------------------
@@ -1453,26 +1448,30 @@ ML (Trilinos AMG)
 Other Common Specs
 ##################
 
+
 IOEvent
 =======
 { IOEvent }
 
+
 Verbose Object
 ==============
 { VerboseObject }
 
+
 Debugger
 ========
 { Debugger }
 
+
 Residual Debugger
 =================
 { ResidualDebugger }
 
 
+Functions
+=========
 
-Function
-===================
 { Function }
 
 It is straightforward to add new functions as needed.

src/executables/ats_mesh_factory.hh

@@ -223,7 +223,7 @@ passing info between an parent mesh and an extracted mesh.
 Specified by `"mesh type`" of `"extracted`".
 
 .. _mesh-extracted-spec:
-..admonition:: mesh-extracted-spec
+.. admonition:: mesh-extracted-spec
 
    * `"parent domain`" ``[string]`` **domain** Parent mesh's name.
 
@@ -244,8 +244,7 @@ Specified by `"mesh type`" of `"extracted`".
      of this mesh is the same as the parent mesh.  If true, the communicator of
      this mesh is the subset of the parent mesh comm that has entries on the
      surface.
-
-
+     
 
 Aliased Mesh
 ============
@@ -408,8 +407,8 @@ Column Surface Meshes
 
 Specified by `"mesh type`" of `"column surface`".
 
-.. _mesh-column-spec:
-.. admonition:: mesh-column-spec
+.. _mesh-column-surface-spec:
+.. admonition:: mesh-column-surface-spec
 
    * `"parent domain`" ``[string]`` The name of the 3D mesh from which columns are generated.
      Note that the `"build columns from set`" parameter must be set in that mesh.

src/pks/flow/snow_distribution.hh

@@ -25,7 +25,7 @@ daily (which all defaults are set for).
 .. admonition:: snow-distribution-spec
 
     * `"distribution time`" ``[double]`` **86400.** Interval of snow precip input dataset. `[s]`
-    * `"precipitation function`" ``[function-spec]`` Snow precipitation Function_ spec.
+    * `"precipitation function`" ``[function-spec]`` Snow precipitation function, see Functions_.
 
     * `"diffusion`" ``[pde-diffusion-spec]`` Diffusion drives the distribution.
       Typically we use finite volume here.  See PDE_Diffusion_