Documented Newton parameters

docs/src/changes.md

@@ -1,4 +1,13 @@
 # Changes
+## v0.8.5 Sep 1 2020
+- allow any object in Physics.data  (thanks Jan Weidner)
+- add generic operator for non-canonical problem structures
+
+## v0.8.4 July 25 2020
+- Update ExtendableGrids + ExtendableSparse
+
+## v0.8.3 June 25 2020
+- Replace splatting by dispatch on availability of data record
 
 ## v0.8.2 May 15 2020
 - Form factors are now pre-calculated and stored

src/vfvm_newtoncontrol.jl

@@ -2,94 +2,167 @@
 """
 $(TYPEDEF)
 
-Control parameter structure for Newton method.
+Control parameters for Newton method.
+
+Newton's method solves ``F(u)=0`` by the iterative procedure ``u_{i+1}=u_{i} - d_i F'(u_i)^{-1}F(u_i)``
+starting with some inital value ``u_0``, where ``d_i`` is the damping. 
 
 $(TYPEDFIELDS)
 """
 mutable struct NewtonControl
 
     """
-    Tolerance (in terms of norm of Newton update)
+    Tolerance (in terms of norm of Newton update):  
+    terminate if ``\\Delta_i=||u_{i+1}-u_i||_\\infty <`` `tol_absolute`.
+
+    Default value: `1.0e-10`.
     """
     tol_absolute::Float64
 
     """
-    Tolerance (relative to the first residual)
+    Tolerance (relative to the first residual):
+    terminate if ``\\Delta_i/\\Delta_0<`` `tol_relative`.
+
+    Default value: `1.0e-10`.
     """
     tol_relative::Float64
 
     """
-    Tolerance for roundoff error detection
+    Tolerance for roundoff error detection:
+    terminate if   ``|\\;||u_{i+1}||_1 - ||u_{i}||_1\\;|/ ||u_{i}||_1<`` `tol_round` occured `max_round` times in a row.
+
+    Default value: `1.0e-10`.
     """
     tol_round::Float64
 
     """
-    Initial damping parameter
+    Initial damping parameter ``d_0``.
+
+    Default value: `1.0`.
+
+    To handle convergence problems, set this to a value less than 1.
     """
     damp_initial::Float64
 
     """
-    Damping parameter growth factor
+    Damping parameter growth factor: ``d_{i+1}=\\min(d_i\\cdot`` `max_growth` ``,1)``
+
+    Default value: `1.2`
+
+    Generally it should be set to a value between 1 and 2.
     """
     damp_growth::Float64
 
     """
-    Maximum number of iterations
+    Maximum number of iterations.
+
+    Default value: 100
     """
     max_iterations::Int32
 
+
     """
-    Maximum number of reuses of lu factorization
+    Maximum number of reuses of lu factorization.
+    It this value is 0, linear systems are solved by a sparse direct solver, and it's LU factorization is called in every Newton step.
+
+    Otherwise, a BICGstab iterative method is used for linear system solution with an LU factorization as preconditioner which is updated only every `max_lureuse` Newton step.
+
+    Default value: 0.
     """
     max_lureuse::Int32
 
     """
     Maximum number of consecutive iterations within roundoff error tolerance
+
+    Default value: 1000 (effectively switching of this criterion).
     """
     max_round::Int32
 
-
     """
-    Tolerance of iterative linear solver
+    Tolerance of iterative linear solver.
+
+    Default value: `1.0e-4`.
     """
     tol_linear::Float64
 
     """
     Verbosity flag
+
+    Default value: `false`.
     """
     verbose::Bool      
 
     """
-    Handle exceptions
+    Handle exceptions in [`embed!`](@ref) and  [`evolve!`](@ref) methods. If `true`, exceptions in Newton solves are catched, the embedding resp. time step is lowered, and solution is retried.
+
+    Default value: `false`
     """
     handle_exceptions::Bool
 
     """
-    Parameter step for embedding
+    Initial parameter step for [`embed!`](@ref) method.
+
+    Default value: `1.0`
     """
     Δp::Float64
 
     """
-    Maximal parameter step
+    Maximal parameter step for [`embed!`](@ref) method
+
+    Default value: `1.0`
     """
     Δp_max::Float64
 
     """
-    Minimal parameter step
+    Minimal parameter step for [`embed!`](@ref) method.
+
+    Default value: `1.0e-3`
     """
     Δp_min::Float64
 
-
     """
-    Edge cutoff for rectangular triangles
+    Time step for [`evolve!`](@ref) method.
+    
+    Default value: 0.1
     """
-    edge_cutoff::Float64
-
     Δt::Float64
+
+    """
+    Maximal time step for [`evolve!`](@ref) method.
+    
+    Default value: 1
+    """
     Δt_max::Float64
+
+    """
+    Minimal time step for [`evolve!`](@ref) method.
+    
+    Default value: `1.0e-3`
+    """
     Δt_min::Float64
+
+    """
+    Maximal step size growth for  [`evolve!`](@ref) method.
+    
+    Default: 1.2
+    """
     Δt_grow::Float64
+
+    """
+    Optimal size of update for  [`evolve!`](@ref) method.
+    The algorithm keeps this value approximately constant.
+    
+    Default: 0.1
+    """
     Δu_opt::Float64
+
+    """
+    Edge cutoff for rectangular triangles.
+
+    Default value: `0.0`.
+    """
+    edge_cutoff::Float64
+
 
     NewtonControl()=NewtonControl(new())
 end

src/vfvm_solver.jl

@@ -656,7 +656,7 @@ end
 
 ################################################################
 """
-$(TYPEDSIGNATURES)
+$(SIGNATURES)
 
 Solution method for instance of abstract system.
 
@@ -665,7 +665,7 @@ solve! for each value of the parameter p from interval
 (0,1). The user is responsible for the interpretation of
 the parameter. The optional `pre()` callback can be used
 to communicate its value to the system.
-The optional`post()` callback method can be used to perform
+The optional `post()` callback method can be used to perform
 various postprocessing steps.
 
 If `control.handle_error` is true, `solve!`  throws an error, and