Document -factorOnce and add missing manual pages

requirements.txt

@@ -1,4 +1,4 @@
-Sphinx>=6.0
+Sphinx>=6.0,<9.0
 sphinx_rtd_theme>=3.0.0
 sphinx_copybutton>=0.5.2
 sphinx-tabs

source/conf.py

@@ -49,6 +49,9 @@
 .. |mhs| replace:: `Michael H. Scott`_
 .. _Michael H. Scott: https://cce.oregonstate.edu/scott
 .. |fmk| replace:: **fmk**
+.. |jaabell| replace:: **José A. Abell**
+.. |mhscott| replace:: `Michael H. Scott`_
+.. |zhuminjie| replace:: **Zhu Minjie**
 .. |pedro| replace:: `Pedro Arduino`_
 .. _Pedro Arduino: https://www.ce.washington.edu/facultyfinder/pedro-arduino
 .. |peter| replace:: `Peter Mackenzie-Helnwein`_

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

@@ -1,7 +1,7 @@
 .. _ExpressNewton:
 
 ExpressNewton Algorithm
 ----------------
 This command is used to construct an ExpressNewton algorithm object for nonlinear structural dynamics. It 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. The command is of the following form:
 
 .. function:: algorithm ExpressNewton $iter $kMultiplier <-initialTangent> <-currentTangent> <-factorOnce>
@@ -12,9 +12,9 @@
 
    $iter, |integer|,  constant number of iterations. Default to 2
    $kMultiplier, |float|,  multiplier to system stiffness in evaluation of the system Jacobian matrix to support unconditional stability for hardening system. Default to 1.0. Dicussed in Reference [1]
-   -initialTangent, |string|,  optional flag to indicate to use initial stiffness in evaluation of the system Jacobian matrix
+   -initialTangent, |string|,  optional flag to indicate to use initial stiffness in evaluation of the system Jacobian matrix. Also accepted as ``-initial``; enables ``-factorOnce`` automatically.
    -currentTangent, |string|,  optional and default flag to indicate to use current stiffness in evaluation of the system Jacobian matrix
-   -factorOnce, |string|, optional flag to indicate to factorize the system Jacobian matrix only once. It is suggested to specify this flag to maximize the solution efficiency (Reference [1]). If this flag is not specified factorization will be performed on every iteraction.
+   -factorOnce, |string|, optional flag to factorize the system Jacobian matrix only once and reuse it in later analysis steps until a domain change. It is suggested to specify this flag to maximize the solution efficiency (Reference [1]). If this flag is not specified, factorization is performed at every analysis step.
 
 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.
 
@@ -26,4 +26,4 @@
 
 **References**
 
 .. [1] Xu J, Huang Y, Qu Z. 2020. `An efficient and unconditionally stable numerical algorithm for nonlinear structural dynamics <https://www.researchgate.net/publication/342098037_An_efficient_and_unconditionally_stable_numerical_algorithm_for_nonlinear_structural_dynamics>`_. `International Journal for Numerical Methods in Engineering`, 121(20):4614-29. `https://doi.org/10.1002/nme.6456 <https://doi.org/10.1002/nme.6456>`_

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

@@ -2,7 +2,7 @@
 
 Krylov-Newton Algorithm
 --------------------------------
-.. function:: algorithm KrylovNewton <-iterate $tangIter> <-increment $tangIncr> <-maxDim $maxDim> 
+.. function:: algorithm KrylovNewton <-iterate $tangIter> <-increment $tangIncr> <-maxDim $maxDim> <-factorOnce>
 
 .. list-table:: 
    :widths: 10 10 40
@@ -20,8 +20,13 @@ Krylov-Newton Algorithm
    * - $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
-
+   * - -factorOnce
+     - |string|
+     - optional flag to assemble and factor the increment tangent in the first analysis step, keep it fixed in all later steps, and update it only after a domain change (for example, nodes or elements added or removed). Also accepted as ``-factorIncrementOnce``.
+
+.. note::
 
+   Krylov-Newton already uses one increment tangent per equilibrium solve within each analysis step. ``-factorOnce`` carries that same tangent forward to later steps instead of reforming it each time. Using ``-increment initial`` with ``-iterate noTangent`` or ``-iterate initial`` also enables ``-factorOnce`` automatically. If ``-factorOnce`` is given without ``-iterate``, OpenSees warns and defaults to ``-iterate noTangent``. If ``-factorOnce`` conflicts with the chosen ``-iterate`` tangent (for example, ``-iterate current``), OpenSees warns and disables ``-factorOnce``.
 
 This command is used to construct a KrylovNewton algorithm object which uses a modified Newton method with Krylov subspace acceleration to advance to the next time step. 
 

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

@@ -2,7 +2,7 @@
 
 Modified Newton Algorithm
 --------------------------------
-.. function:: algorithm ModifiedNewton <-initial> 
+.. function:: algorithm ModifiedNewton <-initial> <-factorOnce>
 
 .. list-table:: 
    :widths: 10 10 40
@@ -14,5 +14,12 @@ Modified Newton Algorithm
    * - -initial
      - |string|
      - optional flag to indicate to use initial stiffness iterations
+   * - -factorOnce
+     - |string|
+     - optional flag to assemble and factor the tangent in the first analysis step, keep it fixed in all later steps, and update it only after a domain change (for example, nodes or elements added or removed).
+
+.. note::
+
+   Modified Newton already uses one tangent per equilibrium solve within each analysis step. ``-factorOnce`` carries that same tangent forward to later steps instead of reforming it each time. The fixed matrix is the current tangent by default, or the initial tangent with ``-initial``. Specifying ``-initial`` also enables ``-factorOnce`` automatically.
 
 This command is used to construct a ModifiedNewton algorithm object, which uses the modified newton-raphson algorithm to solve the nonlinear residual equation. 

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

@@ -4,15 +4,19 @@ Newton Algorithm
 ----------------
 This command is used to construct a NewtonRaphson algorithm object which is uses the Newton-Raphson algorithm to solve the nonlinear residual equation. The Newton-Raphson method is the most widely used and most robust method for solving nonlinear algebraic equations. The command is of the following form:
 
-.. function:: algorithm Newton <-initial> <-initialThenCurrent>
+.. function:: algorithm Newton <-initial> <-initialThenCurrent> <-factorOnce>
 
 .. csv-table:: 
    :header: "Argument", "Type", "Description"
    :widths: 10, 10, 40
 
    -initial, |string|,  optional flag to indicate to use initial stiffness
    -initialThenCurrent, |string|, optional flag to indicate to use initial stiffness on first step and then current on subsequent steps
+   -factorOnce, |string|, optional flag to assemble and factor the tangent on the first Newton iteration of the first analysis step, keep it fixed in later iterations and later steps, and update it only after a domain change (for example, nodes or elements added or removed).
 
+.. note::
+
+   Newton-Raphson normally reforms the tangent every Newton iteration. ``-factorOnce`` keeps the tangent from the first iteration fixed thereafter. The fixed matrix is the current tangent by default, or the initial tangent with ``-initial``. Specifying ``-initial`` also enables ``-factorOnce`` automatically. ``-factorOnce`` is not used with ``-initialThenCurrent``, which reforms the tangent every iteration.
 
 The Newton method used in finite element analysis is identical to that taught in basic calculus courses. It is just extended for the n unknown degrees-of-freedom. The method as taught in basic calculus, is a root-finding algorithm that uses the first few terms of the Taylor series of a function :math:`f(x)\,\!` in the vicinity of a suspected root :math:`x_n\,\!` to find the root :math:`x_{n+1}\,\!`. Newton's method is sometimes also known as Newton's iteration, although in this work the latter term is reserved to the application of Newton's method for computing square roots.
 

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

@@ -1,10 +1,10 @@
 .. _NewtonLineSearch:
 
 Newton Line Search Algorithm
 ----------------
 This command is used to construct a NewtonLineSearch algorithm object 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. The command is of the following form: 
 
-.. function:: algorithm NewtonLineSearch <-type $typeSearch> <-tol $tol> <-maxIter $maxIter> <-minEta $minEta> <-maxEta $maxEta> 
+.. function:: algorithm NewtonLineSearch <-type $typeSearch> <-tol $tol> <-maxIter $maxIter> <-minEta $minEta> <-maxEta $maxEta> <-factorOnce>
 
 .. csv-table:: 
    :header: "Argument", "Type", "Description"
@@ -16,6 +16,11 @@
    $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
+   -factorOnce, |string|, optional flag to assemble and factor the current tangent on the first Newton iteration of the first analysis step, keep it fixed in later iterations and later steps, and update it only after a domain change (for example, nodes or elements added or removed).
+
+.. note::
+
+   Newton line search normally reforms the current tangent every Newton iteration. ``-factorOnce`` keeps the tangent from the first iteration fixed thereafter.
 
 Theory
 ^^^^^^^^^^^^^^

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

@@ -1,8 +1,10 @@
 .. _SecantNewton:
 
-Secant Newton  Algorithm
+Secant Newton Algorithm
 ----------------
-.. function:: algorithm SecantNewton <-iterate $tangIter> <-increment $tangIncr> <-maxDim $maxDim> 
+This command is used to construct a SecantNewton algorithm object which uses the two-term update to accelerate the convergence of the modified newton method.
+
+.. function:: algorithm SecantNewton <-iterate $tangIter> <-increment $tangIncr> <-maxDim $maxDim> <-numTerms $numTerms> <-cutOut $R1 $R2> <-factorOnce>
 
 .. list-table:: 
    :widths: 10 10 40
@@ -11,22 +13,30 @@
    * - Argument
      - Type
      - Description
-   * - $tangIter
+   * - -iterate
      - |string|
-     - tangent to iterate on, options are current, initial, noTangent. default is current. 
-   * - $tangIncr
+     - tangent to iterate on, options are current, initial, noTangent. default is current.
+   * - -increment
      - |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
-
-This command is used to construct a SecantNewton algorithm object which uses the two-term update to accelerate the convergence of the modified newton method. 
+     - tangent to increment on, options are current, initial, noTangent. default is current.
+   * - -maxDim
+     - |integer|
+     - max number of iterations until the tangent is reformed and acceleration restarts (default = 3).
+   * - -numTerms
+     - |integer|
+     - number of terms in the secant accelerator update (default = 2).
+   * - -cutOut
+     - |listFloat|
+     - optional flag followed by cut-out factors ``$R1`` and ``$R2`` to suppress overly aggressive secant updates. Crisfield's recommended values are 3.5 and 0.3.
+   * - -factorOnce
+     - |string|
+     - optional flag to assemble and factor the increment tangent in the first analysis step, keep it fixed in all later steps, and update it only after a domain change (for example, nodes or elements added or removed). Also accepted as ``-factorIncrementOnce``.
 
 .. note::
-  * The default "cut-out" values recommended by Crisfield (R1=3.5, R2=0.3) are used. 
+
+   Secant-Newton already uses one increment tangent per equilibrium solve within each analysis step. ``-factorOnce`` carries that same tangent forward to later steps instead of reforming it each time. Using ``-increment initial`` with ``-iterate noTangent`` or ``-iterate initial`` also enables ``-factorOnce`` automatically. If ``-factorOnce`` is given without ``-iterate``, OpenSees warns and defaults to ``-iterate noTangent``. If ``-factorOnce`` conflicts with the chosen ``-iterate`` tangent (for example, ``-iterate current``), OpenSees warns and disables ``-factorOnce``.
 
 .. note:: 
     References:
-  * Crisfield, M.A. "Non-linear Finite Element Analysis of Solids and Structures", Vol. 1, Wiley, 1991. 
-
+
+    * Crisfield, M.A. "Non-linear Finite Element Analysis of Solids and Structures", Vol. 1, Wiley, 1991.

source/user/manual/analysis/system.rst

@@ -21,6 +21,5 @@ The following contain information about systemType? and the args required for ea
    system/FullGeneral
    system/SparseSYM
    system/Mumps
-   system/Cusp
    system/Diagonal
    system/PythonSparse

source/user/manual/analysis/test/RelativeNormDispIncr.rst

@@ -0,0 +1,44 @@
+.. _RelativeNormDispIncr:
+
+Relative Norm Displacement Increment
+------------------------------------
+
+This command constructs a convergence test that uses the norm of the solution, :math:`x` vector, of the matrix equation, :math:`Ax=b`. It compares the current norm to the norm at the first step, i.e. :math:`\frac{\sqrt({x_i}^T{x_i})}{\sqrt({x_1}^T{x_1})}`. What the right-hand-side of the matrix equation is depends on integrator and constraint handler chosen. Usually, though not always, it is equal to the change in nodal displacements in the system due to the current unbalance.
+
+.. function:: test RelativeNormDispIncr $tol $iter <$pFlag> <$nType>
+
+.. csv-table::
+   :header: "Argument", "Type", "Description"
+   :widths: 10, 10, 40
+
+   $tol, |float|, the tolerance criteria used to check for convergence
+   $iter, |integer|, the max number of iterations to check before returning failure condition
+   $pFlag, |integer|, " | print flag (optional: default is 0) valid options:
+    | 0 print nothing
+    | 1 print information on norms each time test() is invoked
+    | 2 print information on norms and number of iterations at end of successful test
+    | 4 at each step it will print the norms and also the <math>\Delta U</math> and <math>R(U)</math> vectors.
+    | 5 if it fails to converge at end of $numIter it will print an error message BUT RETURN A SUCCESSFUL test."
+   $nType, |integer|, "type of norm (optional: default is 2 (0 = max-norm 1 = 1-norm 2 = 2-norm ...))"
+
+.. note::
+
+   The convergence test compares the current norm of the displacement increment with the norm of the first step to determine if convergence has been achieved. As a consequence it will always take at least two steps to achieve convergence.
+
+.. admonition:: Example
+
+   The following examples demonstrate the command to create a RelativeNormDispIncr test which allows 10 iterations till failure with a 2-norm in the :math:`x` vector of **1.0e-2**.
+
+   1. **Tcl Code**
+
+   .. code-block:: tcl
+
+      test RelativeNormDispIncr 1.0e-2  10 2
+
+   2. **Python Code**
+
+   .. code-block:: python
+
+      test('RelativeNormDispIncr', 1.0e-2, 10, 2)
+
+Code Developed by: |fmk|

source/user/manual/material/ndMaterial.rst

@@ -43,7 +43,7 @@ The following contain information about matType? and the args required for each
    ndMaterials/Parallel3D
    ndMaterials/InitStrain
    ndMaterials/ASDConcrete3D
-   ndMaterials/ASDPlasticMaterial
+   ndMaterials/ASDPlasticMaterial3D
    ndMaterials/OrthotropicRAConcrete
    ndMaterials/SmearedSteelDoubleLayer
    ndMaterials/NDTest