updates

Author: claudioperez

source/user/manual/analysis/algorithm.rst

@@ -3,31 +3,31 @@
 algorithm
 ^^^^^^^^^
 
-This method is used to define a ``SolutionAlgorithm``, which determines the sequence of steps taken to solve the non-linear equation.
-
 .. tabs::
 
    .. tab:: Python
 
       .. py:method:: Model.algorithm(name, *args)
 
+         Configure a root-finding algorithm to solve the nonlinear residual equations.
+
    .. tab:: Tcl
 
       .. function:: algorithm name? arg1? ...
 
 
 where ``name`` is a string indentifying one of the following algorithms:
 
+
 .. toctree::
    :maxdepth: 1
 
    algorithm/LinearAlgorithm
    algorithm/Newton
    algorithm/NewtonLineSearch
    algorithm/ModifiedNewton
-   algorithm/KrylovNewton
-   algorithm/SecantNewton
-   algorithm/BFGS
+   algorithm/AcceleratedNewton
    algorithm/Broyden
    algorithm/ExpressNewton
 
+

source/user/manual/analysis/algorithm/AcceleratedNewton.rst

@@ -0,0 +1,94 @@
+.. _KrylovNewton:
+
+Accelerated Newton
+^^^^^^^^^^^^^^^^^^
+
+Accelerated Newton algorithms are designed to mitigate the slow convergence of the Modified Newton method and to accommodate complications such as tangent inconsistency, all while imposing minimal additional computational overhead.
+
+
+.. tabs::
+
+   .. tab:: Python
+      
+      .. py:method:: Model.algorithm("AcceleratedNewton", iterate='current', increment='current', maxDim=3, accelerator='raphson')
+         :no-index:
+         
+         :param iterate: tangent to iterate on, options are ``current``, ``initial``, ``None``. default is ``current``. 
+         :type iterate: |string|
+         :param increment: tangent to increment on, options are ``current``, ``initial``, ``None``. default is ``current`` 
+         :type increment: |string|
+         :param maxDim: max number of iterations within a time step before the tangent is reformed and acceleration restarts (default = 3)
+         :type maxDim: |float|
+
+   .. tab:: Tcl
+      
+      .. function:: algorithm KrylovNewton <-iterate $tangIter> <-increment $tangIncr> <-maxDim $maxDim> 
+
+      .. list-table:: 
+        :widths: 10 10 40
+        :header-rows: 1
+
+        * - Argument
+          - Type
+          - Description
+        * - $tangIter
+          - |string|
+          - tangent to iterate on, options are current, initial, noTangent. default is current. 
+        * - $tangIncr
+          - |string|
+          - tangent to increment on, options are current, initial, noTangent. default is current 
+        * - $maxDim
+          - |float|
+          - max number of iterations until the tangent is reformed and acceleration restarts (default = 3)  of iterations within a time step until a new tangent is formed
+
+
+Accelerators
+
+
+Krylov-Newton
+=============
+
+The *KrylovNewton* algorithm uses a modified :ref:`Newton` method with Krylov subspace acceleration to advance to the next time step. 
+The accelerator is described by Carlson and Miller (1998) and Scott and Fenves (2010).
+
+
+Secant 
+=======
+
+
+The *SecantNewton* algorithm uses the two-term update to accelerate the convergence of the modified Newton method. 
+
+.. note::
+
+   * The default "cut-out" values recommended by Crisfield (R1=3.5, R2=0.3) are used. 
+
+
+Examples
+--------
+
+The following examples demonstrate the command to create a SecantNewton solution algorithm.
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. code-block:: python
+
+         model.algorithm('SecantNewton', 
+                         iterate='current', 
+                         increment='current',
+                         maxDim=3)
+
+   .. tab:: Tcl
+
+      .. code-block:: tcl
+
+         algorithm SecantNewton -iterate current -increment current -maxDim 3
+
+
+References
+----------
+
+* Crisfield, M.A. "Non-linear Finite Element Analysis of Solids and Structures", Vol. 1, Wiley, 1991. 
+* Carlson and Miller "Design and Application of a 1D GWMFE Code" SIAM Journal of Scientific Computing (Vol. 19, No. 3, pp. 728-765, May 1998)
+* Scott, M.H. and G.L. Fenves. "A Krylov Subspace Accelerated Newton Algorithm: Application to Dynamic Progressive Collapse Simulation of Frames." Journal of Structural Engineering, 136(5), May 2010. DOI 

source/user/manual/analysis/algorithm/BFGS.rst

@@ -1,15 +1,15 @@
 .. _Broyden:
 
-Broyden
+Broyden/BFGS
 ^^^^^^^
 
-The Broyden algorithm object for general unsymmetric systems which performs successive rank-one updates of the tangent at the first iteration of the current time step.
+The Broyden algorithm for general unsymmetric systems which performs successive rank-one updates of the tangent at the first iteration of the current time step.
 
 .. tabs::
 
    .. tab:: Python
 
-      .. py:method:: Model.algorithm("Broyden" [, count])
+      .. py:method:: Model.algorithm("Broyden" [, count, symmetric=False])
          :no-index:
 
    .. tab:: Tcl
@@ -28,3 +28,9 @@ The Broyden algorithm object for general unsymmetric systems which performs succ
           - number of iterations within a time step until a new tangent is formed
 
 
+BFGS 
+====
+
+
+BFGS implements the `Broyden–Fletcher–Goldfarb–Shanno <https://en.wikipedia.org/wiki/BFGS>`_  (BFGS) algorithm for symmetric systems.
+This performs successive rank-two updates of the tangent at the first iteration of the current time step.

source/user/manual/analysis/algorithm/Broyden.rst

@@ -3,7 +3,8 @@
 ExpressNewton
 ^^^^^^^^^^^^^
 
-*ExpressNewton* accepts the solution after a constant number of Newton-Raphson iterations using a constant system Jacobian matrix. It is advised to be combined with transient integrators only. 
+*ExpressNewton* accepts the solution after a constant number of Newton-Raphson iterations using a constant system Jacobian matrix. 
+It is advised to be combined with transient integrators only. 
 
 .. tabs::
 
@@ -31,6 +32,7 @@ ExpressNewton
 
 The strategy of the *ExpressNewton* algorithm is to adopt a typical transient integrator and accept the solution after a constant number of iterations using a constant system Jacobian matrix. The algorithm inherits the advantages of the host transient integrators, such as the unconditional stability, the order of accuracy, and the numerical dissipation that helps suppress the spurious high-frequency oscillation. Using a constant Jacobian matrix is vital to minimizing the computational expense associated with matrix operations. The algorithm helps achieve an exponential efficiency improvement in a response history analysis with any transient integrator.
 
+
 .. warning::
 
    There is no check on the convergence of the model in this algorithm. It iterates a constant number of iterations and then proceeds to the next time step.

source/user/manual/analysis/algorithm/ExpressNewton.rst

@@ -6,18 +6,36 @@ Line Search
 This command is used to select a NewtonLineSearch algorithm which introduces line search to the Newton-Raphson algorithm to solve the nonlinear residual equation. 
 Line search increases the effectiveness of the Newton method when convergence is slow due to roughness of the residual. 
 
-.. function:: algorithm NewtonLineSearch <-type $typeSearch> <-tol $tol> <-maxIter $maxIter> <-minEta $minEta> <-maxEta $maxEta> 
+.. tabs::
 
-.. csv-table:: 
-   :header: "Argument", "Type", "Description"
-   :widths: 10, 10, 40
+   .. tab:: Python 
 
-   typeSearch, |string|,  Line Search algorithm. Optional, default is ``InitialInterpolated``. Valid types are: ``Bisection``, ``Secant``, ``RegulaFalsi``
-   ``InitialInterpolated``.
-   tol, |float|,  tolerance for search. optional. The default is 0.8.
-   maxIter, |integer|, maximum number of iteration to try. The default is 10.
-   minEta, |float|, a minimum :math:`\eta` value. Optional; The default is 0.1
-   maxEta, |float|, a maximum :math:`\eta` value. Optional; The default is 10.0
+      .. py:method:: Model.algorithm("NewtonLineSearch", ratio, maxIter, minEta, maxEta, type="InitialInterpolated")
+         :no-index: 
+
+         Configure the *NewtonLineSearch* algorithm.
+
+         :param ratio: limiting ratio between the residuals before and after the incremental update (between 0.5 and 0.8)
+         :param maxIter: integer value of the maximum number of iterations to try. Optional; default is 10.
+         :param minEta: float value of a minimum :math:`\eta` value. Optional; default is 0.1.
+         :param maxEta: float value of a maximum :math:`\eta` value. Optional; default is 10.0.
+         :param type: string specifying the line search algorithm. Optional; default is ``InitialInterpolated``. Valid types are: ``Bisection``, ``Secant``, ``RegulaFalsi``, ``InitialInterpolated``.
+   
+
+   .. tab:: OpenSees
+
+      .. function:: algorithm NewtonLineSearch <-type $typeSearch> <-tol $tol> <-maxIter $maxIter> <-minEta $minEta> <-maxEta $maxEta> 
+
+      .. csv-table:: 
+         :header: "Argument", "Type", "Description"
+         :widths: 10, 10, 40
+
+         typeSearch, |string|,  Line Search algorithm. Optional, default is ``InitialInterpolated``. Valid types are: ``Bisection``, ``Secant``, ``RegulaFalsi``
+         ``InitialInterpolated``.
+         tol, |float|,  tolerance for search. optional. The default is 0.8.
+         maxIter, |integer|, maximum number of iteration to try. The default is 10.
+         minEta, |float|, a minimum :math:`\eta` value. Optional; The default is 0.1
+         maxEta, |float|, a maximum :math:`\eta` value. Optional; The default is 10.0
 
 
 Theory
@@ -40,3 +58,22 @@ The different line search algorithms use different root finding methods to obtai
 with :math:`s_0 \triangleq \delta-U R(U_n)`
 
 Code Developed by: |fmk|
+
+
+Examples
+--------
+
+
+.. tabs::
+   
+   .. tab:: Python
+
+      .. code-block:: python
+
+         model.algorithm("NewtonLineSearch", 0.6)
+
+   .. tab:: OpenSees
+
+      .. code-block:: tcl
+
+         algorithm NewtonLineSearch 0.6