Remove extra factor of 0.1 in iterative lin sol tol

CHANGELOG.md

@@ -8,6 +8,8 @@
 
 ### Bug Fixes
 
+Fixed a bug where the factor provided by `ARKodeSetEpsLin` was scaled by 0.1.
+
 ### Deprecation Notices
 
 ## Changes to SUNDIALS in release 7.8.0

doc/arkode/guide/source/Mathematics.rst

@@ -2031,15 +2031,15 @@ Therefore our convergence (stopping) test for the nonlinear iteration
 for each stage is
 
 .. math::
-   R_i \left\|\delta^{(m)} \right\| < \epsilon,
+   R_i \left\|\delta^{(m)} \right\| < \epsilon_N,
    :label: ARKODE_NonlinearTolerance
 
-where the factor :math:`\epsilon` has default value 0.1.  We default
+where the factor :math:`\epsilon_N` has default value 0.1.  We default
 to a maximum of 3 nonlinear iterations.  We also declare the
 nonlinear iteration to be divergent if any of the ratios
 
 .. math::
-   `\|\delta^{(m)}\| / \|\delta^{(m-1)}\| > r_{div}`
+   \|\delta^{(m)}\| / \|\delta^{(m-1)}\| > r_{div}
    :label: ARKODE_NonlinearDivergence
 
 with :math:`m>0`, where :math:`r_{div}` defaults to 2.3.
@@ -2070,19 +2070,17 @@ and local time integration error controls, we require that the norm of
 the preconditioned linear residual satisfies
 
 .. math::
-   \|r\| \le \frac{\epsilon_L \epsilon}{10}.
+   \|r\| \le \epsilon_L \epsilon_N.
    :label: ARKODE_LinearTolerance
 
-Here :math:`\epsilon` is the same value as that is used above for the
-nonlinear error control.  The factor of 10 is used to ensure that the
-linear solver error does not adversely affect the nonlinear solver
-convergence.  Smaller values for the parameter :math:`\epsilon_L` are
-typically useful for strongly nonlinear or very stiff ODE systems,
-while easier ODE systems may benefit from a value closer to 1.  The
-default value is :math:`\epsilon_L = 0.05`, which may be modified by
-the user.  We note that for linearly
-implicit problems the tolerance :eq:`ARKODE_LinearTolerance` is similarly
-used for the single Newton iteration.
+Here :math:`\epsilon_N` is the same value as that is used above for the
+nonlinear error control.  Smaller values for the parameter :math:`\epsilon_L`
+are typically useful for strongly nonlinear or very stiff ODE systems, while
+easier ODE systems may benefit from a value closer to 1.  The default values
+are :math:`\epsilon_L = 0.05` and :math:`\epsilon_N = 0.1`, so the default
+linear residual tolerance is :math:`0.005`; :math:`\epsilon_L` may be modified
+by the user.  We note that for linearly implicit problems the tolerance
+:eq:`ARKODE_LinearTolerance` is similarly used for the single Newton iteration.
 
 
 
@@ -2416,10 +2414,10 @@ iterative mass matrix linear solver, we require that the norm of the
 preconditioned linear residual satisfies
 
 .. math::
-   \|r\| \le \epsilon_L \epsilon,
+   \|r\| \le \epsilon_L \epsilon_N,
    :label: ARKODE_MassLinearTolerance
 
-where again, :math:`\epsilon` is the nonlinear solver tolerance
+where again, :math:`\epsilon_N` is the nonlinear solver tolerance
 parameter from :eq:`ARKODE_NonlinearTolerance`.  When using iterative system
 and mass matrix linear solvers, :math:`\epsilon_L` may be specified
 separately for both tolerances :eq:`ARKODE_LinearTolerance` and

doc/arkode/guide/source/Usage/User_callable.rst

@@ -2458,7 +2458,7 @@ Specify if the implicit RHS is deduced after a nonlinear solve  :c:func:`ARKodeS
 
 .. c:function:: int ARKodeSetNonlinConvCoef(void* arkode_mem, sunrealtype nlscoef)
 
-   Specifies the safety factor :math:`\epsilon` used within the nonlinear
+   Specifies the safety factor :math:`\epsilon_N` used within the nonlinear
    solver convergence test :eq:`ARKODE_NonlinearTolerance`.
 
    :param arkode_mem: pointer to the ARKODE memory block.
@@ -3199,10 +3199,11 @@ ARKLS interface requires that iterative linear solvers stop when
 the norm of the preconditioned residual satisfies
 
 .. math::
-   \|r\| \le \frac{\epsilon_L \epsilon}{10}
+   \|r\| \le \epsilon_L \epsilon_N
 
-where the default :math:`\epsilon_L = 0.05` may be modified by
-the user through the :c:func:`ARKodeSetEpsLin` function.
+where :math:`\epsilon_N` is the nonlinear solver tolerance, and the default
+:math:`\epsilon_L = 0.05` may be modified by the user through the
+:c:func:`ARKodeSetEpsLin` function.
 
 
 .. c:function:: int ARKodeSetPreconditioner(void* arkode_mem, ARKLsPrecSetupFn psetup, ARKLsPrecSolveFn psolve)

doc/cvode/guide/source/Mathematics.rst

@@ -227,11 +227,9 @@ The default stopping test for nonlinear solver iterations is related to
 the subsequent local error test, with the goal of keeping the nonlinear
 iteration errors from interfering with local error control. As described
 below, the final computed value :math:`y^{n(m)}` will have to satisfy a
-local error test :math:`\|y^{n(m)} - y^{n(0)}\| \leq \epsilon`. Letting
-:math:`y^n` denote the exact solution of :eq:`CVODE_nonlinear`, we want to ensure that the iteration
-error :math:`y^n - y^{n(m)}` is small relative to :math:`\epsilon`,
-specifically that it is less than :math:`0.1 \epsilon`. (The safety
-factor :math:`0.1` can be changed by the user.) For this, we also
+local error test :math:`\|y^{n(m)} - y^{n(0)}\| \leq 1`. Letting :math:`y^n`
+denote the exact solution of :eq:`CVODE_nonlinear`, we want to ensure that the
+iteration error :math:`y^n - y^{n(m)}` is "small". For this, we also
 estimate the linear convergence rate constant :math:`R` as follows. We
 initialize :math:`R` to 1, and reset :math:`R = 1` when :math:`M` or
 :math:`P` is updated. After computing a correction
@@ -249,16 +247,17 @@ Now we use the estimate
 
 Therefore the convergence (stopping) test is
 
-.. math:: R \|\delta_m\| < 0.1 \epsilon \, .
+.. math:: R \|\delta_m\| < \epsilon_N \, .
 
-We allow at most 3 iterations (but this limit can be changed by the user). We
-also declare the iteration diverged if any
-:math:`\|\delta_m\| / \|\delta_{m-1}\| > 2` with :math:`m > 1`. If convergence
-fails with :math:`J` or :math:`P` current, we are forced to reduce the step
-size, and we replace :math:`h_n` by :math:`h_n = \eta_{\mathrm{cf}} * h_n` where
-the default is :math:`\eta_{\mathrm{cf}} = 0.25`. The integration is halted
-after a preset number of convergence failures; the default value of this
-limit is 10, but this can be changed by the user.
+where the factor :math:`\epsilon_N` has default value 0.1.  We allow at most 3
+iterations (but this limit can be changed by the user). We also declare the
+iteration diverged if any :math:`\|\delta_m\| / \|\delta_{m-1}\| > 2` with
+:math:`m > 1`. If convergence fails with :math:`J` or :math:`P` current, we are
+forced to reduce the step size, and we replace :math:`h_n` by
+:math:`h_n = \eta_{\mathrm{cf}} * h_n` where the default is
+:math:`\eta_{\mathrm{cf}} = 0.25`. The integration is halted after a preset
+number of convergence failures; the default value of this limit is 10, but this
+can be changed by the user.
 
 When an iterative method is used to solve the linear system, its errors
 must also be controlled, and this also involves the local error test
@@ -267,7 +266,8 @@ constant. The linear iteration error in the solution vector
 Thus to ensure (or attempt to ensure) that the linear iteration errors
 do not interfere with the nonlinear error and local integration error
 controls, we require that the norm of the preconditioned residual be
-less than :math:`0.05 \cdot (0.1 \epsilon)`.
+less than :math:`\epsilon_L \epsilon_N`, with :math:`\epsilon_L = 0.05` by
+default.
 
 When the Jacobian is stored using either the :ref:`SUNMATRIX_DENSE <SUNMatrix.Dense>`
 or :ref:`SUNMATRIX_BAND <SUNMatrix.Band>` matrix

doc/cvode/guide/source/Usage/index.rst

@@ -1698,9 +1698,9 @@ preconditioned residual satisfies
 
 .. math::
 
-   \|r\| \le \frac{\epsilon_L \epsilon}{10}
+   \|r\| \le \epsilon_L \epsilon_N
 
-where :math:`\epsilon` is the nonlinear solver tolerance, and the default
+where :math:`\epsilon_N` is the nonlinear solver tolerance, and the default
 :math:`\epsilon_L = 0.05`; this value may be modified by the user through
 the :c:func:`CVodeSetEpsLin` function.
 
@@ -1736,7 +1736,7 @@ the :c:func:`CVodeSetEpsLin` function.
 
 .. c:function:: int CVodeSetEpsLin(void* cvode_mem, sunrealtype eplifac)
 
-   The function ``CVodeSetEpsLin`` specifies the factor by  which the Krylov linear solver's convergence test constant is  reduced from the nonlinear solver test constant.
+   The function ``CVodeSetEpsLin`` specifies the factor :math:`\epsilon_L` by which the Krylov linear solver's convergence test constant is  reduced from the nonlinear solver test constant.
 
    **Arguments:**
      * ``cvode_mem`` -- pointer to the CVODE memory block.
@@ -1765,15 +1765,15 @@ the :c:func:`CVodeSetEpsLin` function.
 
 .. c:function:: int CVodeSetLSNormFactor(void* cvode_mem, sunrealtype nrmfac)
 
-   The function ``CVodeSetLSNormFactor`` specifies the factor to use when  converting from the integrator tolerance (WRMS norm) to the linear solver  tolerance (L2 norm) for Newton linear system solves e.g.,  ``tol_L2 = fac * tol_WRMS``.
+   The function ``CVodeSetLSNormFactor`` specifies the factor to use when converting from the integrator tolerance (WRMS norm) to the linear solver  tolerance (L2 norm) for Newton linear system solves e.g.,  ``tol_L2 = fac * tol_WRMS``.
 
    **Arguments:**
      * ``cvode_mem`` -- pointer to the CVODE memory block.
      * ``nrmfac`` -- the norm conversion factor. If ``nrmfac`` is:
 
        - :math:`> 0` then the provided value is used.
-       - :math:`= 0` then the conversion factor is computed using the vector length, i.e., ``nrmfac = N_VGetLength(y)`` (*default*).
-       - :math:`< 0` then the conversion factor is computed using the vector dot product, i.e., ``nrmfac = N_VDotProd(v,v)`` where all the entries of ``v`` are one.
+       - :math:`= 0` then the conversion factor is computed using the vector length, i.e., ``nrmfac = sqrt(N_VGetLength(y))`` (*default*).
+       - :math:`< 0` then the conversion factor is computed using the vector dot product, i.e., ``nrmfac = sqrt(N_VDotProd(v,v))`` where all the entries of ``v`` are one.
 
    **Return value:**
      * ``CV_SUCCESS`` -- The optional value has been successfully set.
@@ -1782,7 +1782,7 @@ the :c:func:`CVodeSetEpsLin` function.
    **Notes:**
       This function must be called after the CVLS linear solver  interface has been initialized through a call to :c:func:`CVodeSetLinearSolver`.
 
-      Prior to the introduction of ``N_VGetLength`` in SUNDIALS v5.0.0  (CVODE v5.0.0) the value of ``nrmfac`` was computed using the vector  dot product i.e., the ``nrmfac < 0`` case.
+      Prior to the introduction of ``N_VGetLength`` in SUNDIALS v5.0.0 (CVODE v5.0.0) the value of ``nrmfac`` was computed using the vector  dot product i.e., the ``nrmfac < 0`` case.
 
       This routine will be called by :c:func:`CVodeSetOptions`
       when using the key "cvid.ls_norm_factor".
@@ -1855,7 +1855,7 @@ nonlinear solver.
 
 .. c:function:: int CVodeSetNonlinConvCoef(void* cvode_mem, sunrealtype nlscoef)
 
-   The function ``CVodeSetNonlinConvCoef`` specifies the safety factor used in the nonlinear convergence test (see :numref:`CVODE.Mathematics.ivp_sol`).
+   The function ``CVodeSetNonlinConvCoef`` specifies the safety factor :math:`\epsilon_N` used in the nonlinear convergence test (see :numref:`CVODE.Mathematics.ivp_sol`).
 
    **Arguments:**
      * ``cvode_mem`` -- pointer to the CVODE memory block.

doc/cvodes/guide/source/Mathematics.rst

@@ -236,11 +236,9 @@ The default stopping test for nonlinear solver iterations is related to
 the subsequent local error test, with the goal of keeping the nonlinear
 iteration errors from interfering with local error control. As described
 below, the final computed value :math:`y^{n(m)}` will have to satisfy a
-local error test :math:`\|y^{n(m)} - y^{n(0)}\| \leq \epsilon`. Letting
-:math:`y^n` denote the exact solution of :eq:`CVODES_nonlinear`, we want to ensure that the iteration
-error :math:`y^n - y^{n(m)}` is small relative to :math:`\epsilon`,
-specifically that it is less than :math:`0.1 \epsilon`. (The safety
-factor :math:`0.1` can be changed by the user.) For this, we also
+local error test :math:`\|y^{n(m)} - y^{n(0)}\| \leq 1`. Letting :math:`y^n`
+denote the exact solution of :eq:`CVODES_nonlinear`, we want to ensure that the
+iteration error :math:`y^n - y^{n(m)}` is "small". For this, we also
 estimate the linear convergence rate constant :math:`R` as follows. We
 initialize :math:`R` to 1, and reset :math:`R = 1` when :math:`M` or
 :math:`P` is updated. After computing a correction
@@ -258,16 +256,17 @@ Now we use the estimate
 
 Therefore the convergence (stopping) test is
 
-.. math:: R \|\delta_m\| < 0.1 \epsilon \, .
+.. math:: R \|\delta_m\| < \epsilon_N \, .
 
-We allow at most 3 iterations (but this limit can be changed by the user). We
-also declare the iteration diverged if any
-:math:`\|\delta_m\| / \|\delta_{m-1}\| > 2` with :math:`m > 1`. If convergence
-fails with :math:`J` or :math:`P` current, we are forced to reduce the step
-size, and we replace :math:`h_n` by :math:`h_n = \eta_{\mathrm{cf}} * h_n` where
-the default is :math:`\eta_{\mathrm{cf}} = 0.25`. The integration is halted
-after a preset number of convergence failures; the default value of this
-limit is 10, but this can be changed by the user.
+where the factor :math:`\epsilon_N` has default value 0.1.  We allow at most 3
+iterations (but this limit can be changed by the user). We also declare the
+iteration diverged if any :math:`\|\delta_m\| / \|\delta_{m-1}\| > 2` with
+:math:`m > 1`. If convergence fails with :math:`J` or :math:`P` current, we are
+forced to reduce the step size, and we replace :math:`h_n` by
+:math:`h_n = \eta_{\mathrm{cf}} * h_n` where the default is
+:math:`\eta_{\mathrm{cf}} = 0.25`. The integration is halted after a preset
+number of convergence failures; the default value of this limit is 10, but this
+can be changed by the user.
 
 When an iterative method is used to solve the linear system, its errors
 must also be controlled, and this also involves the local error test
@@ -276,7 +275,8 @@ constant. The linear iteration error in the solution vector
 Thus to ensure (or attempt to ensure) that the linear iteration errors
 do not interfere with the nonlinear error and local integration error
 controls, we require that the norm of the preconditioned residual be
-less than :math:`0.05 \cdot (0.1 \epsilon)`.
+less than :math:`\epsilon_L \epsilon_N`, with :math:`\epsilon_L = 0.05` by
+default.
 
 When the Jacobian is stored using either the :ref:`SUNMATRIX_DENSE <SUNMatrix.Dense>`
 or :ref:`SUNMATRIX_BAND <SUNMatrix.Band>` matrix

doc/cvodes/guide/source/Usage/ADJ.rst

@@ -1153,11 +1153,11 @@ potentially non-differentiable factor.
 
 .. c:function:: int CVodeSetEpsLinB(void * cvode_mem, int which, sunrealtype eplifacB)
 
-   The function :c:func:`CVodeSetEpsLinB` specifies the factor by  which the
-   Krylov linear solver's convergence test constant is reduced  from the
-   nonlinear iteration test constant.  This routine can be used in both the
-   cases where the backward problem  does and does not depend on the forward
-   sensitivities.
+   The function :c:func:`CVodeSetEpsLinB` specifies the factor
+   :math:`\epsilon_L` by which the Krylov linear solver's convergence test
+   constant is reduced from the nonlinear iteration test constant.  This routine
+   can be used in both the cases where the backward problem does and does not
+   depend on the forward sensitivities.
 
    **Arguments:**
      * ``cvode_mem`` -- pointer to the CVODES memory block.
@@ -1194,7 +1194,7 @@ potentially non-differentiable factor.
    **Arguments:**
      * ``cvode_mem`` -- pointer to the CVODES memory block.
      * ``which`` -- the identifier of the backward problem.
-     * ``nrmfac`` -- the norm conversion factor. If ``nrmfac`` is: :math:`> 0` then the provided value is used. :math:`= 0` then the conversion factor is computed using the vector length i.e., ``nrmfac = N_VGetLength(y)`` default. :math:`< 0` then the conversion factor is computed using the vector dot product ``nrmfac = N_VDotProd(v,v)`` where all the entries of ``v`` are one.
+     * ``nrmfac`` -- the norm conversion factor. If ``nrmfac`` is: :math:`> 0` then the provided value is used. :math:`= 0` then the conversion factor is computed using the vector length i.e., ``nrmfac = sqrt(N_VGetLength(y))`` default. :math:`< 0` then the conversion factor is computed using the vector dot product ``nrmfac = sqrt(N_VDotProd(v,v))`` where all the entries of ``v`` are one.
 
    **Return value:**
      * ``CVLS_SUCCESS`` -- The optional value has been successfully set.

doc/cvodes/guide/source/Usage/SIM.rst

@@ -1689,9 +1689,9 @@ preconditioned residual satisfies
 
 .. math::
 
-   \|r\| \le \frac{\epsilon_L \epsilon}{10}
+   \|r\| \le \epsilon_L \epsilon_N
 
-where :math:`\epsilon` is the nonlinear solver tolerance, and the default
+where :math:`\epsilon_N` is the nonlinear solver tolerance, and the default
 :math:`\epsilon_L = 0.05`; this value may be modified by the user through
 the :c:func:`CVodeSetEpsLin` function.
 
@@ -1727,7 +1727,7 @@ the :c:func:`CVodeSetEpsLin` function.
 
 .. c:function:: int CVodeSetEpsLin(void* cvode_mem, sunrealtype eplifac)
 
-   The function ``CVodeSetEpsLin`` specifies the factor by  which the Krylov linear solver's convergence test constant is  reduced from the nonlinear solver test constant.
+   The function ``CVodeSetEpsLin`` specifies the factor :math:`\epsilon_L` by which the Krylov linear solver's convergence test constant is reduced from the nonlinear solver test constant.
 
    **Arguments:**
      * ``cvode_mem`` -- pointer to the CVODES memory block.
@@ -1763,8 +1763,8 @@ the :c:func:`CVodeSetEpsLin` function.
      * ``nrmfac`` -- the norm conversion factor. If ``nrmfac`` is:
 
        - :math:`> 0` then the provided value is used.
-       - :math:`= 0` then the conversion factor is computed using the vector length, i.e., ``nrmfac = N_VGetLength(y)`` (*default*).
-       - :math:`< 0` then the conversion factor is computed using the vector dot product, i.e., ``nrmfac = N_VDotProd(v,v)`` where all the entries of ``v`` are one.
+       - :math:`= 0` then the conversion factor is computed using the vector length, i.e., ``nrmfac = sqrt(N_VGetLength(y))`` (*default*).
+       - :math:`< 0` then the conversion factor is computed using the vector dot product, i.e., ``nrmfac = sqrt(N_VDotProd(v,v))`` where all the entries of ``v`` are one.
 
    **Return value:**
      * ``CV_SUCCESS`` -- The optional value has been successfully set.
@@ -1773,7 +1773,7 @@ the :c:func:`CVodeSetEpsLin` function.
    **Notes:**
       This function must be called after the CVLS linear solver  interface has been initialized through a call to :c:func:`CVodeSetLinearSolver`.
 
-      Prior to the introduction of ``N_VGetLength`` in SUNDIALS v5.0.0  (CVODES v5.0.0) the value of ``nrmfac`` was computed using the vector  dot product i.e., the ``nrmfac < 0`` case.
+      Prior to the introduction of ``N_VGetLength`` in SUNDIALS v5.0.0 (CVODES v5.0.0) the value of ``nrmfac`` was computed using the vector  dot product i.e., the ``nrmfac < 0`` case.
 
       This routine will be called by :c:func:`CVodeSetOptions`
       when using the key "cvid.ls_norm_factor".
@@ -1846,7 +1846,7 @@ nonlinear solver.
 
 .. c:function:: int CVodeSetNonlinConvCoef(void* cvode_mem, sunrealtype nlscoef)
 
-   The function ``CVodeSetNonlinConvCoef`` specifies the safety factor used in the nonlinear convergence test (see :numref:`CVODES.Mathematics.ivp_sol`).
+   The function ``CVodeSetNonlinConvCoef`` specifies the safety factor :math:`\epsilon_N` used in the nonlinear convergence test (see :numref:`CVODES.Mathematics.ivp_sol`).
 
    **Arguments:**
      * ``cvode_mem`` -- pointer to the CVODES memory block.