Skip to content

Add documentation for new integrators and SOE methods #183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jaabell wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Add documentation for new integrators and SOE methods #183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4b022e9
Entry for Diagonal and MPIDiagonal SOEs
jaabell Jan 21, 2026
9c2cc06
Documentation for ExplicitBather and ExplicitDifferenceStatic integra…
jaabell Jan 21, 2026
def45ae
Merge branch 'OpenSees:master' into master
jaabell Jan 21, 2026
e292711
Updated ASDPlasticMaterial3D
jaabell Jan 28, 2026
0cd3b3f
Adds documentation for NDTest. Pending validation
jaabell Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions source/user/manual/analysis/integrator.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@ Transient Integrators:
integrator/GeneralizedAlpha
integrator/TRBDF2
integrator/ExplicitDifference
integrator/ExplicitBathe
integrator/ExplicitDifferenceStatic


Utility Integrators:
Expand Down
57 changes: 57 additions & 0 deletions source/user/manual/analysis/integrator/ExplicitBathe.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
.. _ExplicitBathe:

ExplicitBathe
-------------
.. function:: integrator ExplicitBathe $p $compute_critical_timestep?

.. csv-table::
:header: "Argument", "Type", "Description"
:widths: 10, 10, 40

$p, |float|, Damping parameter (0 < p < 1, typically 0.54)
$compute_critical_timestep, |int|, Optional flag to compute critical timestep (0 or 1)

.. note::
* The method is second-order accurate and explicit.
* Only mass matrix is assembled on RHS (no tangent matrix required).
* Critical time step is approximately 2× larger than central difference method.
* For stability: :math:`\Delta t \leq \frac{2}{\omega_{max}}`
* Typical p values: 0.54-0.95 for optimal numerical damping.

Theory
^^^^^^

The ExplicitBathe method is a two-step explicit integration scheme with built-in numerical damping. The method performs two sub-steps per time step:

1. First step: :math:`t \rightarrow t + p\Delta t`
2. Second step: :math:`t + p\Delta t \rightarrow t + \Delta t`

The integration coefficients are computed from the damping parameter p:

.. math::

q_1 = \frac{1 - 2p}{2p(1-p)}

q_2 = 0.5 - p \cdot q_1

q_0 = -q_1 - q_2 + 0.5

The method offers enhanced stability compared to standard central difference, with a critical time step approximately twice as large. The parameter p controls numerical damping, with higher values providing more damping but reduced accuracy.

.. admonition:: Example

1. **Tcl Code**

.. code-block:: tcl

integrator ExplicitBathe 0.54

2. **Python Code**

.. code-block:: python

integrator('ExplicitBathe', 0.54)

.. [Noh2013] Noh, G., & Bathe, K.J. (2013). "An explicit time integration scheme for the analysis of wave propagations." Computers & Structures, 129, 178-193.

Code Developed by: |jaabell|
57 changes: 57 additions & 0 deletions source/user/manual/analysis/integrator/ExplicitDifferenceStatic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
.. _ExplicitDifferenceStatic:

ExplicitDifferenceStatic
------------------------
.. function:: integrator ExplicitDifferenceStatic

.. note::
* Uses leap-frog integration with velocities at half time steps.
* FLAC-style local non-viscous damping (α = 0.59) for pseudo-static analysis.
* Only mass matrix is required (no tangent matrix assembly).
* Velocity sign memory prevents chatter near zero velocity.
* For stability: :math:`\Delta t \leq \frac{2}{\omega_{max}}`
* Suitable for quasi-static and dynamic problems with adaptive damping.

Theory
^^^^^^

The ExplicitDifferenceStatic method is an explicit difference scheme with FLAC-style local non-viscous damping. The method uses a leap-frog approach where:

* Velocities are defined at half time steps: :math:`v_{n+1/2}`
* Displacements are defined at full time steps: :math:`d_n`

The damping force uses an adaptive FLAC-style approach:

.. math::

F_{damping} = -\alpha \cdot |F_{unbalanced}| \cdot sign(v)

where α = 0.59 by default. The method includes velocity sign memory with a deadband (1e-4) to prevent numerical chatter when velocities approach zero.

The central difference equations are:

.. math::

v_{n+1/2} = v_{n-1/2} + \Delta t \cdot a_n

d_{n+1} = d_n + \Delta t \cdot v_{n+1/2}

This integrator is particularly effective for quasi-static analysis and problems where adaptive local damping is beneficial, such as rock mechanics and soil-structure interaction problems.

.. admonition:: Example

1. **Tcl Code**

.. code-block:: tcl

integrator ExplicitDifferenceStatic

2. **Python Code**

.. code-block:: python

integrator('ExplicitDifferenceStatic')

.. [Cundall1987] Cundall, P.A. (1987). "Distinct Element Models of Rock and Soil Structure." In Analytical and Computational Methods in Engineering Rock Mechanics, 129-163.

Code Developed by: |jaabell|
1 change: 1 addition & 0 deletions source/user/manual/analysis/system.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,4 @@ The following contain information about systemType? and the args required for ea
system/SparseSYM
system/Mumps
system/Cusp
system/Diagonal
129 changes: 129 additions & 0 deletions source/user/manual/analysis/system/Diagonal.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
Diagonal & MPIDiagonal System
-----------------------------

This command is used to construct a Diagonal linear system of equation object. This system stores only the diagonal entries of the coefficient matrix, making it extremely memory efficient for problems where off-diagonal coupling can be neglected or lumped into the diagonal. The system is solved by direct inversion of the diagonal entries. The following command is used to construct such a system:

.. function:: system (Diagonal|MPIDiagonal) <-lumped>

**Optional Parameter:**

* **-lumped** - If specified, off-diagonal matrix entries are added (lumped) to the diagonal before solving. This is useful for mass matrix lumping or when converting a coupled system to a diagonal approximation.

A diagonal system stores only the diagonal entries of an n×n matrix **A**, where:

:math:`K = \begin{bmatrix} k_{11} & 0 & \cdots & 0 \\ 0 & k_{22} & \cdots & 0 \\ \vdots & \vdots & \ddots & \vdots \\ 0 & 0 & \cdots & k_{nn} \end{bmatrix}`

The solution for :math:`K u = f` is obtained directly as:

:math:`u_i = \frac{f_i}{k_{ii}} \quad \text{for } i = 1, \ldots, n`

.. note::

1. This solver requires that all diagonal entries are non-zero.
2. The system only stores n values instead of n² for a full matrix, providing significant memory savings
3. When using the **-lumped** option, the solver accumulates all off-diagonal entries in each row/column into the corresponding diagonal entry

Mass Lumping
^^^^^^^^^^^^

When the **-lumped** option is specified, the Diagonal or MPIDiagonal system performs **mass lumping** (also called diagonal lumping or row-sum lumping). This technique converts a consistent (coupled) mass matrix into a diagonal form by summing all entries in each row and placing the total on the diagonal.

**Mathematical Formulation:**

For a consistent mass matrix **M** with entries :math:`m_{ij}`, the lumped diagonal entry is:

:math:`\tilde{m}_{ii} = \sum_{j=1}^{n} m_{ij}`

All off-diagonal entries are set to zero: :math:`\tilde{m}_{ij} = 0` for :math:`i \neq j`

\end{bmatrix}


.. warning::

1. This system is only appropriate when the problem structure allows diagonal treatment
2. Mass lumping is generally only recommended for the mass matrix in dynamic analysis (ExplicitDifference integrator or CentralDifference integrator if no damping matrix is used or only mass proportional Rayleigh damping is used)
3. Lumping the stiffness matrix is rarely appropriate and can lead to poor results
4. For static analysis or implicit dynamics use full sparse solvers.
5. Ideally, lumping should be handled at the element level, especially for high-order elements (like the TenNodeTetrahedron or SixNodeTriangle) where this technique leads to negative mass values (!!).

**Implementation Details:**

When **-lumped** is specified:

.. code-block:: none

For each element matrix entry m(i,j) at DOF locations id(i), id(j):
A[id(i)] += m(i,i) // Add diagonal entry
if (lumped):
for all j ≠ i:
A[id(i)] += m(j,i) // Add all column entries to diagonal

This ensures that the total contribution from each element is preserved while creating a diagonal system.


.. admonition:: Example

The following examples show how to construct a Diagonal system

**1. Tcl Code - Basic diagonal system (no lumping)**

.. code-block:: tcl

system Diagonal

**2. Tcl Code - Diagonal system with mass lumping for explicit dynamics**

.. code-block:: tcl

# Explicit dynamic analysis with lumped mass
system Diagonal -lumped

constraints Plain
numberer Plain
test NormDispIncr 1.0e-6 10 0
algorithm Linear
integrator CentralDifference
analysis Transient

**3. Python Code - Basic diagonal system**

.. code-block:: python

ops.system('Diagonal')

**4. Python Code - Lumped mass for explicit analysis**

.. code-block:: python

# Setup for explicit central difference method
ops.system('Diagonal', '-lumped')
ops.constraints('Plain')
ops.numberer('Plain')
ops.integrator('CentralDifference')
ops.analysis('Transient')

**5. Python Code - Complete explicit dynamics example**

.. code-block:: python

import openseespy.opensees as ops

# ... model definition ...

# Analysis setup for blast/impact with lumped mass
ops.system('Diagonal', '-lumped')
ops.constraints('Plain')
ops.numberer('Plain')
ops.test('NormDispIncr', 1.0e-6, 10, 0)
ops.algorithm('Linear')
ops.integrator('CentralDifference')
ops.analysis('Transient')

# Time step (must satisfy CFL condition)
dt = 0.0001
ops.analyze(1000, dt)

Code Developed by: |fmk|


55 changes: 55 additions & 0 deletions source/user/manual/material/matTestCommands.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,4 +82,59 @@ The command getResponse returns material or section specific information.
:widths: 10, 10, 40

$args, |list|, list of the arguments for the material/section response

NDTest Commands for Direct Material Testing
===========================================

For more advanced and direct testing of nDMaterial objects, OpenSees provides the :ref:`NDTest Command <NDTest>` which offers additional functionality beyond the basic material testing environment.

The NDTest command provides comprehensive testing capabilities including:

- Direct strain control with ``NDTest SetStrain``
- State management with ``NDTest CommitState``
- Parameter updates during runtime
- Enhanced response queries
- Real-time material state inspection

Key differences between the basic material testing environment and NDTest:

- **Basic Testing**: Uses ``testNDMaterial`` with ``setStrain``/``getStress`` commands
- **NDTest**: Uses ``NDTest`` with more extensive command set and real-time parameter updates

For complete documentation of NDTest commands, see :ref:`NDTest`.

Example comparing both approaches:

TCL:

.. code-block:: tcl

# Basic testing approach
testNDMaterial 1
setStrain 0.001 0.0 0.0 0.0 0.0 0.0
set stress [getStress]

# NDTest approach
NDTest SetStrain 1 0.001 0.0 0.0 0.0 0.0 0.0
set stress [NDTest GetStress 1]
NDTest CommitState 1
# Additional capabilities:
set tangent [NDTest GetTangentStiffness 1]
NDTest UpdateDoubleParameter 1 1 2.1e-5

Python:

.. code-block:: python

# Basic testing approach
op.testNDMaterial(1)
op.setStrain(0.001, 0.0, 0.0, 0.0, 0.0, 0.0)
stress = op.getStress()

# NDTest approach
op.NDTest("SetStrain", 1, 0.001, 0.0, 0.0, 0.0, 0.0, 0.0)
stress = op.NDTest("GetStress", 1)
op.NDTest("CommitState", 1)
# Additional capabilities:
tangent = op.NDTest("GetTangentStiffness", 1)
op.NDTest("UpdateDoubleParameter", 1, 1, 2.1e-5)
1 change: 1 addition & 0 deletions source/user/manual/material/ndMaterial.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ The following contain information about matType? and the args required for each
ndMaterials/ASDPlasticMaterial
ndMaterials/OrthotropicRAConcrete
ndMaterials/SmearedSteelDoubleLayer
ndMaterials/NDTest

Concrete Damage Model
Plane Stress Material
Expand Down
Loading
Loading