Updated some documentation. It still needs work, but it's good enough…

… for the next

release.

docs/Examples.md

@@ -62,19 +62,22 @@ first argument to every function.
 1. **Step**: This function tells XBraid how to take a time step, and is the core
    user routine.  The user must advance the vector *u* from time *tstart* to
    time *tstop*.  Note how the time values are given to the user through the
-   *status* structure and associated *Get* routine.  The *ustop* parameter
+   *status* structure and associated *Get* routine.  **Important note:** 
+   the \f$ g_i \f$ function from @ref braidoverview must be incorporated into 
+   *Step*, so that the following equation is solved by default. 
+   \f[ \Phi(u_i) = 0. \f]
+   The *ustop* parameter
    serves as an approximation to the solution at time *tstop* and is not needed
    here.  It can be useful for implicit schemes that require an initial guess
-   for a linear or nonlinear solver.  The *fstop* parameter is the right-hand
-   side of the nonlinear problem on the given time grid.  It is only needed when
+   for a linear or nonlinear solver.  The use of *fstop* is an advanced parameter 
+   (not required) and forms the the right-hand
+   side of the nonlinear problem on the given time grid.  This value is only nonzero when
    providing a residual with [braid_SetResidual](@ref braid_SetResidual).  More
    information on how to use this optional feature is given below.  Also see the
    full code listing for this example in ``examples/ex-01``.
    \latexonly \\ \endlatexonly
 
    Here advancing the solution just involves the scalar \f$ \lambda \f$.
-   **Important note:** the \f$ g_i \f$ function from @ref braidoverview must be
-   incorporated into *Step*.
 
          int
          my_Step(braid_App        app,
@@ -205,6 +208,8 @@ first argument to every function.
    set to 2, then *access* is called every XBraid iteration and on every XBraid level.  In 
    this case, querying *astatus* to determine the current XBraid level and iteration will 
    be useful. This scenario allows for even more detailed tracking of the simulation.
+   The default *access_level* is 1 and gives the user access only after the simulation ends
+   and only on the finest time-grid.
    \latexonly \\ \endlatexonly
 
    Eventually, this routine will allow for broader access to XBraid and computational steering.
@@ -316,44 +321,58 @@ first argument to every function.
    \endlatexonly
 
 10. **Residual** (optional): A user-defined residual can be provided with the
-    function [braid_SetResidual](@ref braid_SetResidual).  *Residual* defines
-    the nonlinear equation to solve at each time step with the *Step* routine.
+    function [braid_SetResidual](@ref braid_SetResidual), which can result
+    in the substantial computational savings explained below.  *Residual* defines
+    the nonlinear equation at each time step, i.e., it evaluates one block-row of the global
+    space-time operator \f$A\f$ with a right-hand side (a residual computation).  
+    It defines the equation which *Step* must solve.
     Because XBraid assumes a one-step method, the equation to solve on each grid
     level has the form
 
-    \f[ A(u_i, u_{i-1}) = f_i, \f]
+    \f[ \hat{A}(u_i, u_{i-1}) = f_i, \f]
 
-    where \f$ A() \f$ is the *Residual* function and \f$ f_i = 0 \f$ on the
+    where \f$ \hat{A}() \f$ is the *Residual* function and \f$ f_i = 0 \f$ on the
     finest grid level.  The nonzero right-hand-side on each coarse grid is
     needed to implement the FAS algorithm.  The *Step* function provides an
     approximation to the solution \f$ u_i \f$ of this equation.  That is,
 
     \f[ u_i \approx \Phi(u_{i-1}, f_i), \f]
 
-    where \f$ \Phi() \f$ is the *Step* function.  When *Residual* is provided,
+    where \f$ \Phi(u,f) \f$ is the *Step* function augmented with a right-hand side
+    term.  When *Residual* is provided,
     *Step* does not need to produce an accurate time step, especially when all
     time points are stored (see [braid_SetStorage](@ref braid_SetStorage)).
+    In this case, substantial computational savings are possible because one
+    application of *Step* becomes much cheaper than a step for sequential 
+    time-stepping.  For example if *Step* were backward Euler for a linear problem,
+    *Residual* would essentially be a matrix-vector product, while *Step* would
+    be an inaccurate solve of the corresponding linear system.
+
     Users should write the *Residual* and *Step* routines such that the
     following holds:
 
-    \f[ A( \Phi(u_{i-1}, f_i), u_{i-1} ) \approx f_i. \f]
+    \f[ \hat{A}( \Phi(u_{i-1}, f_i), u_{i-1} ) \approx f_i. \f]
 
     Note that when *Residual* is not provided, XBraid defines the residual in
     terms of the *Step* function as follows:
 
-    \f[ A(u_i, u_{i-1}) = u_i - \Phi(u_{i-1}) = 0. \f]
+    \f[ \hat{A}(u_i, u_{i-1}) = u_i - \Phi(u_{i-1}) = 0. \f]
 
     In this case, we have exact equality above (i.e., \f$ \approx \f$ becomes
     \f$ = \f$).  In addition, the nonzero right-hand-side needed on coarse grids
     to do FAS does not need to be provided to the user because the solution to
     the non-homogeneous equation is simply \f$ u_i = \Phi(u_{i-1}) + f_i \f$,
-    and this can easily be computed internally in XBraid.  Also note that here
-    *Step* must always be an accurate time step on the finest grid level.
+    and this can easily be computed internally in XBraid.  
+    In other words, the *fstop* parameter for *Step* is always zero by default.  
+    Also note that here *Step* must always be an accurate time step on the finest grid level.
 
 11. Adaptive and variable time stepping are available by first calling the
     function [braid_SetRefine](@ref braid_SetRefine) in the main driver and then
     using [braid_StepStatusSetRFactor](@ref braid_StepStatusSetRFactor) in the
     *Step* routine to set a refinement factor for interval [*tstart*, *tstop*].
+    In this way, user-defined criteria can subdivide intervals on the fly and adaptively
+    refine in time.
+
     In this example, no refinement is being done (factor = 1).  Currently, each
     refinement factor is constrained to be no larger than the coarsening factor.
     The final time grid is constructed adaptively in an FMG-like cycle by
@@ -411,7 +430,7 @@ This will run ``ex-01``. See ``examples/ex-0*`` for more extensive examples.
 In this example, we assume familiarity with @ref exampleone and describe the
 major ways in which this example differs.  This example is a full space-time
 parallel example, as opposed to @ref exampleone, which implements only a scalar
-ode for one degree-of-freedom in space.  We solve the heat equation in 2D,
+ODE for one degree-of-freedom in space.  We solve the heat equation in 2D,
 
 \f[ \delta/\delta_t \; u(x,y,t) = \Delta\, u(x,y,t) + g(x,y,t). \f]
 
@@ -772,3 +791,12 @@ can return a boolean variable to indicate correctness.
                           my_Access, my_Free, my_Clone, my_Sum, my_SpatialNorm, 
                           my_CoarsenBilinear, my_Refine);
 
+# More Complicated Examples
+
+We have Fortran90 and C++ interfaces.  See ``examples/ex-01f.f90``, ``braid.hpp``
+and the various C++ examples in ``drivers/drive-**.cpp``.  For discussion of
+more complex problems please see our project
+[publications website](http://computation.llnl.gov/projects/parallel-time-integration-multigrid/publications)
+for our recent publications concerning some of these varied applications. 
+
+

docs/Introduction.md

@@ -35,7 +35,11 @@ success has been shown primarily for problems with some parabolic character.
 While there are ongoing projects (here and elsewhere) looking at varied
 applications such as hyperbolic problems, computational fluid dynamics, power
 grids, medical applications, and so on, expectations should take this fact into
-account.  That being said, we strongly encourage new users to try our code for
+account.  Please see our project
+[publications website](http://computation.llnl.gov/projects/parallel-time-integration-multigrid/publications)
+for our recent publications concerning some of these varied applications. 
+
+That being said, we strongly encourage new users to try our code for
 their application.  Every new application has its own issues to address and
 this will help us to improve both the algorithm and the software.
 
@@ -81,7 +85,7 @@ a wave, and this wave propagates sequentially across space as time increases.
 XBraid instead begins with a solution guess over all of space-time, which for demonstration, 
 we let be random. An XBraid iteration does
 
-1. Relaxation on the fine grid, i.e., the grid that contains all of the desired time values
+1. Relaxation on the fine grid, i.e., the grid that contains all of the desired time values.
    Relaxation is just a local application of the time stepping scheme, e.g., backward Euler.
 2. Restriction to the first coarse grid, i.e., interpolate the problem to a grid that 
    contains fewer time values, say every second or every third time value.
@@ -261,6 +265,9 @@ The spacing between each \f$ I \f$ is \f$ m-1 \f$ block rows.  While injection
 is simple, XBraid always does an F-relaxation sweep before the application of \f$R\f$, 
 which is equivalent to using the transpose of harmonic interpolation for restriction 
 (see [Parallel Time Integration with Multigrid](https://computation.llnl.gov/project/linear_solvers/pubs/mgritPaper-2014.pdf) ).
+Another interpretation is that the F-relaxation compresses the residual into the 
+C-points, i.e., the residual at all F-points after an F-relaxation is 0.  Thus, 
+it makes sense for restriction to be injection.
 
 To define the coarse grid equations, we apply the Full Approximation
 Scheme (FAS) method, which is a nonlinear version of multigrid.  This is to
@@ -269,7 +276,7 @@ the solution guess and residual (i.e., \f$ \mathbf{u}, \mathbf{g} - A
 \mathbf{u}\f$) are restricted.  This is in contrast to linear multigrid which
 typically restricts only the residual equation to the coarse grid.  This
 algorithmic change allows for the solution of general nonlinear problems.  For more
-details, see 
+details, see this
 [PDF](http://computation.llnl.gov/casc/people/henson/postscript/UCRL_JC_150259.pdf)
 by Van Henson for a good introduction to FAS.  However, FAS was originally invented 
 by Achi Brandt.
@@ -282,7 +289,9 @@ coarse time step size \f$ \Delta T = m \delta t \f$.  For example, if \f$ \Phi
 = (I - \delta t A)^{-1} \f$ for some backward Euler scheme, then \f$
 \Phi_{\Delta} = (I - m \delta t A)^{-1} \f$ would be one choice.
 
-With a \f$ \Phi_{\Delta} \f$ defined, the coarse grid equation
+With this \f$ \Phi_{\Delta} \f$ and letting \f$ \mathbf{u}_{\Delta} \f$ be the 
+restricted fine grid solution and \f$ \mathbf{r}_{\Delta} \f$ be the restricted
+fine grid residual, the coarse grid equation
    \f[
    A_{\Delta}(\mathbf{v}_{\Delta})  = A_{\Delta}(\mathbf{u}_{\Delta}) + \mathbf{r}_{\Delta} 
    \f]
@@ -370,7 +379,7 @@ In summary, a few points are
   figure, a 3 level hierarchy is shown.  Three levels are chosen because there are
   six time points, \f$m = 2\f$ and \f$ m^2 < 6 \le m^3 \f$.
   If the coarsening rate had been \f$m = 4\f$ then there would only be two
-  levels because, there would be no more points to coarsen!
+  levels because there would be no more points to coarsen!
    \latexonly
    \begin{figure}[!ht] \centering 
        \subfloat{\includegraphics[width=0.6\textwidth]{../img/3_levels.pdf}}
@@ -442,6 +451,12 @@ XBraid
     requirements of XBraid are significantly reduced when compared to storing
     all of the time values.
 
+  Overall, the memory multiplier per processor when using XBraid is \f$ O(1)
+  \f$ if space-time coarsening (see @ref exampleone) is used and \f$ O(\log_m N)
+  \f$ for time-only coarsening.  The time-only coarsening option is the default
+  and requires no user-written spatial interpolation/restriction routines
+  (which is the case for space-time coasrening).  We note that the base of the
+  logarithm is \f$ m \f$, which can be quite large.
 
 ## Cycling and relaxation strategies {#cyclingrelaxation}
 
@@ -476,6 +491,9 @@ Next, we make a few points about F- versus V-cycles.
 - But, F-cycles often converge more quickly.  For some test cases, this difference can be 
   quite large.  The cycle choice for the best time to solution will be problem
   dependent.  See @ref twodheat_scaling for a case study of cycling strategies. 
+- For exceptionally strong F-cycles, the option [braid_SetNFMGVcyc](@ref braid_SetNFMGVcyc)
+  can be set to use multiple V-cycles as relaxation.  This has proven useful
+  for some problems with a strongly advective nature.
 
 The number of FC relaxation sweeps is another important algorithmic setting.
 Note that at least one F-relaxation sweep is always 
@@ -545,7 +563,7 @@ Setting a tolerance involves these three XBraid options:
    obtain a global norm over space and time.  It is this global norm that
    then controls halting. 
 
-   There are three options for setting the *tnorm* value passed to 
+   There are three *tnorm* options supported by
    [braid_SetTemporalNorm](@ref braid_SetTemporalNorm). We let the summation
    index *i* be over all C-point values on the fine time grid, *k* refer to the
    current XBraid iteration, *r* be residual values, *space_time* norms be a