Braid version 2.0.0, This commit just updates the docs a little

docs/Examples.md

@@ -321,17 +321,17 @@ first argument to every function.
    \endlatexonly
 
 10. **Residual** (optional): A user-defined residual can be provided with the
-    function [braid_SetResidual](@ref braid_SetResidual), which can result
-    in the substantial computational savings explained below.  *Residual* defines
+    function [braid_SetResidual](@ref braid_SetResidual) and can result
+    in substantial computational savings, as 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[ \hat{A}(u_i, u_{i-1}) = f_i, \f]
+    \f[ A_i(u_i, u_{i-1}) = f_i, \f]
 
-    where \f$ \hat{A}() \f$ is the *Residual* function and \f$ f_i = 0 \f$ on the
+    where \f$ A_i() \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,
@@ -351,35 +351,39 @@ first argument to every function.
     Users should write the *Residual* and *Step* routines such that the
     following holds:
 
-    \f[ \hat{A}( \Phi(u_{i-1}, f_i), u_{i-1} ) \approx f_i. \f]
+    \f[ A_i( \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[ \hat{A}(u_i, u_{i-1}) = u_i - \Phi(u_{i-1}) = 0. \f]
+    \f[ A_i(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
+    \f$ = \f$).  In addition, the nonzero right-hand-side *fstop* 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.  
     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.
+    Also note that in this default setting, *Step* must always be an accurate 
+    time step on the finest grid level so that residual computations are accurate.
 
 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
-    refining the initial grid according to the requested refinement factors.
-    Refinement stops when the requested factors are all one or when various
-    upper bounds are reached such as the max number of time points or max number
-    of time grid refinement levels allowed.
+   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.  For instance, returning a refinement factor of 4 in *Step* 
+   will tell XBraid to subdivide that interval into 4 evenly spaced smaller intervals
+   for the next iteration.  Refinement can only be done on the finest XBraid level.
+   \latexonly \\ \endlatexonly
+
+   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
+   refining the initial grid according to the requested refinement factors.
+   Refinement stops when the requested factors are all one or when various
+   upper bounds are reached such as the max number of time points or max number
+   of time grid refinement levels allowed.
 
 ## Running XBraid for this Example 
 

drivers/README.md

@@ -50,8 +50,8 @@ To run the examples, type
    coarsening, and thus if explicit time stepping is used, the time stepping 
    switchs to implicit on coarse XBraid grids when the CFL condition is violated.
 
-3. drive-04 is a sophisticated test bed for various PDEs, mostly parabolic.  It relies
-   on the [mfem](http://mfem.org)
+3. drive-04 is a sophisticated test bed for finite element discretizations of the 
+   heat equation. It relies on the [mfem](http://mfem.org)
    package to create general finite element discretizations for the spatial problem.
    Other packages must be installed in this order.
      + Unpack and install [Metis](http://glaros.dtc.umn.edu/gkhome/metis/metis/overview)
@@ -94,4 +94,10 @@ To run the examples, type
 
          Glvis will listen on a port to which drive-04 will dump visualization information.
 
+4. drive-05, 6, 7 and 10 are additional mfem examples compiled like drive-04.
+     + drive-05 implements advection(-diffusion) with a discontinuous Galerkin
+       discretization.
+     + drive-06 implements nonlinear diffusion, i.e., the \f$p\f$-Laplacian.
+     + drive-07 is under development.
+     + drive-10 is under development.
 

examples/README.md

@@ -52,3 +52,10 @@ To run the examples, type
    is a more sophisticated version of this simple example that supports
    explicit time stepping and spatial coarsening.
 
+3. ex-burgers implements Burger's equation in one spatial dimension, 
+   supports spatial coarsening and forward and backward Euler.  It is
+   under developement, but a fun example.  See also *viz-burgers.py*
+   for visualizing the output.
+
+4. ex-lorenz implements the Lorenz equation and is under development. 
+   See also *viz-lorenz.py* for visualizing the output.