Consolidate OpenSeesPy and OpenSees documentation

source/user/manual/material/uniaxialMaterial.rst

@@ -44,6 +44,7 @@ The following subsections contain information about **$matType**
 
       uniaxialMaterials/Concrete01
       uniaxialMaterials/Concrete02
+      uniaxialMaterials/Concrete02IS
       uniaxialMaterials/Concrete04
       uniaxialMaterials/ASDConcrete1D
       uniaxialMaterials/GMG_CyclicReinforcedConcrete
@@ -60,8 +61,8 @@ The following subsections contain information about **$matType**
 
 .. toctree::
       :maxdepth: 1
-		 
-..    uniaxialMaterials/Elastic
+
+      uniaxialMaterials/Elastic
       uniaxialMaterials/ElasticPP
       uniaxialMaterials/ElasticPP_Gap
       uniaxialMaterials/ElasticNoTension
@@ -89,14 +90,19 @@ The following subsections contain information about **$matType**
 
 .. toctree::
       :maxdepth: 1
-      
-..    uniaxialMaterials/Fatigue
+
+      uniaxialMaterials/Fatigue
       uniaxialMaterials/Parallel
       uniaxialMaterials/Series
+      uniaxialMaterials/TensionOnly
+      uniaxialMaterials/SimpleFracture
       uniaxialMaterials/InitialStrain
       uniaxialMaterials/InitialStress
       uniaxialMaterials/MinMax
       uniaxialMaterials/PathIndependent
+      uniaxialMaterials/Damper
+      uniaxialMaterials/Penalty
+      uniaxialMaterials/Multiplier
 
 #. Other Uniaxial Materials
 

source/user/manual/material/uniaxialMaterials/Concrete02IS.rst

@@ -0,0 +1,58 @@
+.. _Concrete02IS:
+
+Concrete02IS Material (Concrete02 with Initial Stiffness Control)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command is used to construct a uniaxial concrete material with the same compressive envelope and tension/cyclic behavior as :ref:`Concrete02`, but with **user-defined initial stiffness** *E*\ :sub:`0`. In Concrete02 the initial stiffness is fixed at :math:`E_c = 2f'_c/\varepsilon_{c0}`; Concrete02IS allows any *E*\ :sub:`0` (e.g. :math:`57000\sqrt{f'_c}` or secant stiffness to peak).
+
+.. function:: uniaxialMaterial Concrete02IS $matTag $E0 $fpc $epsc0 $fpcu $epsU <$lambda $ft $Ets>
+
+.. csv-table::
+   :header: "Argument", "Type", "Description"
+   :widths: 10, 10, 40
+
+   $matTag,  |integer|,  unique material tag
+   $E0,      |float|,    initial (elastic) stiffness
+   $fpc,     |float|,    concrete compressive strength at 28 days (compression negative)
+   $epsc0,   |float|,    concrete strain at maximum strength (negative)
+   $fpcu,    |float|,    concrete crushing strength (negative)
+   $epsU,    |float|,    concrete strain at crushing strength (negative)
+   $lambda,  |float|,    (optional) ratio between unloading slope at epsU and initial slope
+   $ft,      |float|,    (optional) tensile strength
+   $Ets,     |float|,    (optional) tension softening stiffness (absolute value)
+
+.. note::
+
+   Compressive parameters (*fpc*, *epsc0*, *fpcu*, *epsU*) are taken as negative; if given positive, they are converted to negative internally. The input *E*\ :sub:`0` affects the unloading/reloading stiffness in compression. The ascending branch uses the Popovics equation (Concrete02 uses the Hognestad parabola).
+
+.. admonition:: Example
+
+   1. **Tcl Code**
+
+   .. code-block:: tcl
+
+      set fc 4000.0
+      set epsc0 -0.002
+      set fcu -1000.0
+      set epscu -0.006
+      # Same initial stiffness as Concrete02
+      set Ec [expr 2.0*$fc/(-$epsc0)]
+      uniaxialMaterial Concrete02IS 1 $Ec $fc $epsc0 $fcu $epscu
+      # With tension and optional parameters
+      uniaxialMaterial Concrete02IS 2 $Ec $fc $epsc0 $fcu $epscu 0.1 500.0 1738.33
+
+   2. **Python Code**
+
+   .. code-block:: python
+
+      fc, epsc0 = 4000.0, -0.002
+      fcu, epscu = -1000.0, -0.006
+      Ec = 2.0 * fc / (-epsc0)
+      ops.uniaxialMaterial('Concrete02IS', 1, Ec, fc, epsc0, fcu, epscu)
+      ops.uniaxialMaterial('Concrete02IS', 2, Ec, fc, epsc0, fcu, epscu, 0.1, 500.0, 1738.33)
+
+.. seealso::
+
+   :ref:`Concrete02` (fixed initial stiffness). `Concrete02 with Control of the Initial Stiffness (Portwood Digital) <https://portwooddigital.com/2021/11/06/concrete02-with-control-of-the-initial-stiffness/>`_.
+
+Code developed by: Filip Filippou (Concrete02); Nasser Marafi (Concrete02IS, initial stiffness control).

source/user/manual/material/uniaxialMaterials/Damper.rst

@@ -0,0 +1,34 @@
+.. _Damper:
+
+Damper Material Wrapper
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command is used to construct a Damper uniaxial material wrapper. The wrapper uses the stress-strain response of any UniaxialMaterial as a **stress versus strain-rate** relationship for damping. The conversion is done by passing strain rate as strain and the material tangent as the damping tangent in the state determination.
+
+.. function:: uniaxialMaterial Damper $matTag $otherTag <-factors $fact1 $fact2 ...>
+
+.. csv-table::
+   :header: "Argument", "Type", "Description"
+   :widths: 10, 10, 40
+
+   $matTag,   |integer|,  unique material tag
+   $otherTag, |integer|,  tag of a previously-defined UniaxialMaterial
+   $fact1 ..., |float|,   (optional) factors for multiple materials
+
+.. admonition:: Example
+
+   1. **Tcl Code**
+
+   .. code-block:: tcl
+
+      uniaxialMaterial Elastic 1 100.0
+      uniaxialMaterial Damper 2 1
+
+   2. **Python Code**
+
+   .. code-block:: python
+
+      ops.uniaxialMaterial('Elastic', 1, 100.0)
+      ops.uniaxialMaterial('Damper', 2, 1)
+
+Code developed by: |mhs|

source/user/manual/material/uniaxialMaterials/Fatigue.rst

@@ -0,0 +1,95 @@
+.. _Fatigue:
+
+Fatigue Material Wrapper
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command is used to construct a Fatigue uniaxial material wrapper. The wrapper uses a modified rainflow cycle-counting algorithm to accumulate damage in the wrapped material using Miner's rule, based on Coffin-Manson log-log relationships for low-cycle fatigue. It does not change the stress-strain (or force-deformation) response of the wrapped material until fatigue life is exhausted; then the wrapper returns zero stress and zero tangent.
+
+.. function:: uniaxialMaterial Fatigue $matTag $otherTag <-E0 $e0> <-m $m> <-min $epsmin> <-max $epsmax>
+
+.. csv-table::
+   :header: "Argument", "Type", "Description"
+   :widths: 10, 10, 40
+
+   $matTag,   |integer|,  unique material tag
+   $otherTag, |integer|,  tag of a previously-defined UniaxialMaterial
+   $e0,       |float|,    (optional) strain at which one cycle causes failure; default 0.191
+   $m,        |float|,    (optional) slope of Coffin-Manson curve in log-log space; default -0.458
+   $epsmin,   |float|,    (optional) global minimum strain/deformation for failure; default -1e16
+   $epsmax,   |float|,    (optional) global maximum strain/deformation for failure; default 1e16
+
+Description
+"""""""""""
+
+The model accounts for low-cycle fatigue. A modified rainflow cycle counter tracks strain amplitudes and is used with a linear strain-accumulation model (Miner's rule) and Coffin-Manson relationships. When the damage level reaches 1.0, the force (or stress) of the wrapped material is set to zero (numerically 1e-8). If failure is triggered in compression, the stress is dropped at the next zero-force crossing. The material treats each point as the last point of the history for damage tracking; if failure is not triggered, that pseudo-peak is discarded. Failure can also be triggered by exceeding the optional minimum or maximum strain limits (defaults are very large so that only fatigue controls). The default E0 and m are calibrated from low-cycle fatigue tests on European steel sections (Ballio and Castiglioni 1995); see Uriz (2005) for calibration details.
+
+Valid recorder responses for the wrapped material are ``stress``, ``tangent``, ``strain``, ``stressStrain``, and ``damage``. The stress, strain, and tangent options must be supported by the wrapped material.
+
+Damage recorder
+"""""""""""""""
+
+To record fatigue damage, use the element recorder with the ``damage`` response.
+
+**Fiber section elements:** The argument after ``material`` (or ``fiber``) is the **fiber index**, not the material tag. Using ``material`` or ``fiber`` gives the same result. To target a fiber by coordinates, add one more argument after ``fiber`` (y and z, or the appropriate coordinate).
+
+**Truss elements:** Use ``material`` **without** a tag after it. Adding a material tag after ``material`` will not work.
+
+1. **Tcl Code**
+
+.. code-block:: tcl
+
+   # Fiber section: record damage of 1st fiber (index 0) — "material" and "fiber" equivalent
+   recorder Element -xml Damage1.out -time -ele 1 2 section 1 material 0 damage
+   recorder Element -xml Damage2.out -time -ele 1 2 section 1 fiber 0 damage
+
+   # Fiber section: record damage of fiber near center by coordinates
+   recorder Element -xml Damage3.out -time -ele 1 2 section 1 fiber 0.1 0.1 damage
+
+   # Truss: use "material" with no tag
+   recorder Element -file Damage4.out -time -ele 1 material damage
+
+2. **Python Code**
+
+.. code-block:: python
+
+   # Fiber section: record damage of 1st fiber
+   ops.recorder('Element', '-xml', 'Damage1.out', '-time', '-ele', 1, 2, 'section', 1, 'material', 0, 'damage')
+
+   # Truss: use "material" with no tag
+   ops.recorder('Element', '-file', 'Damage4.out', '-time', '-ele', 1, 'material', 'damage')
+
+.. note::
+
+   For theory and implementation details see Uriz (2005) and the OpenSees wiki.
+
+.. seealso::
+
+   `Fatigue Material (OpenSees wiki) <http://opensees.berkeley.edu/wiki/index.php/Fatigue_Material>`_
+
+.. admonition:: Example
+
+   Wrapping Steel01 with default fatigue parameters (E0 = 0.191, m = -0.458):
+
+   1. **Tcl Code**
+
+   .. code-block:: tcl
+
+      uniaxialMaterial Steel01 1 50.0 2000.0 0.01
+      uniaxialMaterial Fatigue 2 1
+      # with explicit defaults: uniaxialMaterial Fatigue 2 1 -E0 0.191 -m -0.458
+
+   2. **Python Code**
+
+   .. code-block:: python
+
+      ops.uniaxialMaterial('Steel01', 1, 50.0, 2000.0, 0.01)
+      ops.uniaxialMaterial('Fatigue', 2, 1)
+      # with explicit defaults: ops.uniaxialMaterial('Fatigue', 2, 1, '-E0', 0.191, '-m', -0.458)
+
+References
+""""""""""
+
+- Uriz, P. (2005). "Towards Earthquake Resistant Design of Concentrically Braced Steel Structures," Ph.D. Dissertation, UC Berkeley.
+- Ballio, G., and Castiglioni, C. A. (1995). "A Unified Approach for the Design of Steel Structures under Low and/or High Cycle Fatigue." Journal of Constructional Steel Research, 34, 75-101.
+
+Code developed by: Patxi Uriz, Exponent; modifications by Kevin Mackie.

source/user/manual/material/uniaxialMaterials/InitialStrain.rst

@@ -0,0 +1,38 @@
+.. _InitialStrain:
+
+InitStrain Material Wrapper
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command is used to construct an InitStrain (or InitialStrain) uniaxial material wrapper. The wrapper imposes an initial strain on the wrapped material so that the effective strain seen by the wrapped material is the applied strain plus the initial strain. After the constructor, no special state is maintained.
+
+.. function:: uniaxialMaterial InitStrain $matTag $otherTag $eps0
+
+.. csv-table::
+   :header: "Argument", "Type", "Description"
+   :widths: 10, 10, 40
+
+   $matTag,   |integer|,  unique material tag
+   $otherTag, |integer|,  tag of a previously-defined UniaxialMaterial
+   $eps0,     |float|,    initial strain
+
+.. note::
+
+   It is good practice to run one analysis step with dt = 0 when using initial strain (and initial stress) wrappers so that the model is in equilibrium.
+
+.. admonition:: Example
+
+   1. **Tcl Code**
+
+   .. code-block:: tcl
+
+      uniaxialMaterial Hardening 1 3.0 1.0 0.1
+      uniaxialMaterial InitStrain 2 1 -0.1
+
+   2. **Python Code**
+
+   .. code-block:: python
+
+      ops.uniaxialMaterial('Hardening', 1, 3.0, 1.0, 0.1)
+      ops.uniaxialMaterial('InitStrain', 2, 1, -0.1)
+
+Code developed by: |mhs|

source/user/manual/material/uniaxialMaterials/InitialStress.rst

@@ -0,0 +1,38 @@
+.. _InitialStress:
+
+InitStress Material Wrapper
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command is used to construct an InitStress (or InitialStress) uniaxial material wrapper. The wrapper imposes an initial stress on the wrapped material. After the constructor, the wrapper passes through the wrapped material response with the initial stress offset.
+
+.. function:: uniaxialMaterial InitStress $matTag $otherTag $sig0
+
+.. csv-table::
+   :header: "Argument", "Type", "Description"
+   :widths: 10, 10, 40
+
+   $matTag,   |integer|,  unique material tag
+   $otherTag, |integer|,  tag of a previously-defined UniaxialMaterial
+   $sig0,     |float|,    initial stress
+
+.. note::
+
+   Run one analysis step with dt = 0 (e.g. static with integrator LoadControl 0.0) so that initial stresses are in equilibrium.
+
+.. admonition:: Example
+
+   1. **Tcl Code**
+
+   .. code-block:: tcl
+
+      uniaxialMaterial Hardening 1 3.0 1.0 0.1
+      uniaxialMaterial InitStress 2 1 0.3
+
+   2. **Python Code**
+
+   .. code-block:: python
+
+      ops.uniaxialMaterial('Hardening', 1, 3.0, 1.0, 0.1)
+      ops.uniaxialMaterial('InitStress', 2, 1, 0.3)
+
+Code developed by: |mhs|

source/user/manual/material/uniaxialMaterials/MinMax.rst

@@ -0,0 +1,39 @@
+.. _MinMax:
+
+MinMax Material Wrapper
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This command is used to construct a MinMax uniaxial material wrapper. The wrapper forwards strain to the wrapped material and returns its stress and tangent until the material strain goes above a maximum or below a minimum. Once that condition is met in ``commitState()``, the wrapper stops updating the wrapped material (the material is treated as failed).
+
+.. function:: uniaxialMaterial MinMax $matTag $otherTag <-min $minStrain> <-max $maxStrain>
+
+.. csv-table::
+   :header: "Argument", "Type", "Description"
+   :widths: 10, 10, 40
+
+   $matTag,   |integer|,  unique material tag
+   $otherTag, |integer|,  tag of a previously-defined UniaxialMaterial
+   $minStrain, |float|,   (optional) minimum strain; default -1.0e16
+   $maxStrain, |float|,   (optional) maximum strain; default 1.0e16
+
+.. note::
+
+   After the strain limit is exceeded, the wrapper no longer calls the wrapped material.
+
+.. admonition:: Example
+
+   1. **Tcl Code**
+
+   .. code-block:: tcl
+
+      uniaxialMaterial Hardening 1 3.0 1.0 0.1
+      uniaxialMaterial MinMax 2 1 -min -0.8
+
+   2. **Python Code**
+
+   .. code-block:: python
+
+      ops.uniaxialMaterial('Hardening', 1, 3.0, 1.0, 0.1)
+      ops.uniaxialMaterial('MinMax', 2, 1, '-min', -0.8)
+
+Code developed by: |mhs|

source/user/manual/material/uniaxialMaterials/Multiplier.rst

@@ -0,0 +1,34 @@
+.. _Multiplier:
+
+Multiplier Material Wrapper
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command is used to construct a Multiplier uniaxial material wrapper. The wrapper multiplies the stress and tangent of its wrapped UniaxialMaterial by a factor. Typical uses include overstrength factors for materials and p-y multipliers for shadowing effects in pile groups.
+
+.. function:: uniaxialMaterial Multiplier $matTag $otherTag $multiplier
+
+.. csv-table::
+   :header: "Argument", "Type", "Description"
+   :widths: 10, 10, 40
+
+   $matTag,     |integer|,  unique material tag
+   $otherTag,   |integer|,  tag of a previously-defined UniaxialMaterial
+   $multiplier, |float|,    factor applied to stress and tangent of the wrapped material
+
+.. admonition:: Example
+
+   1. **Tcl Code**
+
+   .. code-block:: tcl
+
+      uniaxialMaterial Elastic 1 100.0
+      uniaxialMaterial Multiplier 2 1 0.8
+
+   2. **Python Code**
+
+   .. code-block:: python
+
+      ops.uniaxialMaterial('Elastic', 1, 100.0)
+      ops.uniaxialMaterial('Multiplier', 2, 1, 0.8)
+
+Code developed by: |mhs|