Updates

claudioperez · claudioperez · commit 221cf972297b · 2025-08-01T17:21:01.000-07:00
diff --git a/source/conf.py b/source/conf.py
@@ -82,6 +82,7 @@
 
 """
 
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -116,7 +117,7 @@
     "user/index.rst",
     "user/manual/model/geomTransf/frame/index.rst",
     "user/manual/analysis/integrator/gimmeMCK.rst",
-    "user/manual/analysis/modalProperties.rst",
+#   "user/manual/analysis/modalProperties.rst",
     "user/manual/analysis/responseSpectrumAnalysis.rst",
     "user/manual/model/damping/elementalDamping.rst",
     "user/manual/model/eleLoad.rst",
diff --git a/source/user/guides/conventions.rst b/source/user/guides/conventions.rst
@@ -0,0 +1,30 @@
+.. _conventions:
+
+Conventions 
+^^^^^^^^^^^
+
+
+Degrees of Freedom
+------------------
+
+Several commands may accept an integer argument to specify a degree of freedom (DOF) in the model.
+This is always a 1-based index, meaning that the first DOF is 1, the second DOF is 2, and so on (as opposed to 0-based indexing, which is common in some programming languages).
+The DOFs are ordered as follows:
+
+.. csv-table::
+   :header: "ndm", "ndf", "Order of components"
+   :widths: 10, 10, 40
+
+   1, 1, "u1"
+   2, 2, "u1, u2"
+   3, 3, "u1, u2, u3"
+   2, 3, "u1, u2, r3"
+   3, 6, "u1, u2, u3, r1, r2, r3"
+   3, 6+n, "u1, u2, u3, r1, r2, r3, d4, d5, ..., d6+n"
+
+where:
+
+* ``u1, u2, u3`` are the translational displacements in the x, y, and z directions respectively,
+* ``r1, r2, r3`` are the rotational displacements about the x, y, and z axes respectively.
+
+
diff --git a/source/user/guides/index.rst b/source/user/guides/index.rst
@@ -8,5 +8,6 @@ For a great guide to Tcl programming, see `this <https://antirez.com/articoli/tc
    :maxdepth: 1
 
    install
+   conventions
    signatures
    references
diff --git a/source/user/manual/analysis/analysis.rst b/source/user/manual/analysis/analysis.rst
@@ -3,8 +3,6 @@
 analysis
 ^^^^^^^^
 
-This is the command issued to configure an analysis.
-
 .. tabs::
 
    .. tab:: Python
diff --git a/source/user/manual/analysis/codeExample/responseSpectrumAnalysisExample.py b/source/user/manual/analysis/codeExample/responseSpectrumAnalysisExample.py
@@ -1,4 +1,4 @@
-from opensees import *
+from opensees.openseespy import *
 from math import sqrt
 
 wipe()
diff --git a/source/user/manual/analysis/codeExample/responseSpectrumAnalysisExample.tcl b/source/user/manual/analysis/codeExample/responseSpectrumAnalysisExample.tcl
@@ -5,27 +5,27 @@ model basic -ndm 3 -ndf 6
 
 # the response spectrum function
 set Tn {0.0 0.06 0.1 0.12 0.18 0.24 0.3 0.36 0.4 0.42 \
-		0.48 0.54 0.6 0.66 0.72 0.78 0.84 0.9 0.96 1.02 \
-		1.08 1.14 1.2 1.26 1.32 1.38 1.44 1.5 1.56 1.62 \
-		1.68 1.74 1.8 1.86 1.92 1.98 2.04 2.1 2.16 2.22 \
-		2.28 2.34 2.4 2.46 2.52 2.58 2.64 2.7 2.76 2.82 \
-		2.88 2.94 3.0 3.06 3.12 3.18 3.24 3.3 3.36 3.42 \
-		3.48 3.54 3.6 3.66 3.72 3.78 3.84 3.9 3.96 4.02 \
-		4.08 4.14 4.2 4.26 4.32 4.38 4.44 4.5 4.56 4.62 \
-		4.68 4.74 4.8 4.86 4.92 4.98 5.04 5.1 5.16 5.22 \
-		5.28 5.34 5.4 5.46 5.52 5.58 5.64 5.7 5.76 5.82 \
-		5.88 5.94 6.0}
+        0.48 0.54 0.6 0.66 0.72 0.78 0.84 0.9 0.96 1.02 \
+        1.08 1.14 1.2 1.26 1.32 1.38 1.44 1.5 1.56 1.62 \
+        1.68 1.74 1.8 1.86 1.92 1.98 2.04 2.1 2.16 2.22 \
+        2.28 2.34 2.4 2.46 2.52 2.58 2.64 2.7 2.76 2.82 \
+        2.88 2.94 3.0 3.06 3.12 3.18 3.24 3.3 3.36 3.42 \
+        3.48 3.54 3.6 3.66 3.72 3.78 3.84 3.9 3.96 4.02 \
+        4.08 4.14 4.2 4.26 4.32 4.38 4.44 4.5 4.56 4.62 \
+        4.68 4.74 4.8 4.86 4.92 4.98 5.04 5.1 5.16 5.22 \
+        5.28 5.34 5.4 5.46 5.52 5.58 5.64 5.7 5.76 5.82 \
+        5.88 5.94 6.0}
 set Sa {1.9612 3.72628 4.903 4.903 4.903 4.903 4.903 4.903 4.903 4.6696172 \
-		4.0861602 3.6321424 3.2683398 2.971218 2.7241068 2.5142584 2.3348086 2.1788932 2.0425898 1.9229566 \
-		1.8160712 1.7199724 1.6346602 1.5562122 1.485609 1.4208894 1.3620534 1.3071398 1.2571292 1.211041 \
-		1.166914 1.1267094 1.0894466 1.054145 1.0217852 0.990406 0.960988 0.9335312 0.9080356 0.8835206 \
-		0.8599862 0.838413 0.8168398 0.7972278 0.7785964 0.759965 0.7432948 0.7266246 0.710935 0.6952454 \
-		0.6805364 0.666808 0.6540602 0.6285646 0.6040496 0.5814958 0.5609032 0.5403106 0.5206986 0.5030478 \
-		0.485397 0.4697074 0.4540178 0.4393088 0.4255804 0.411852 0.3991042 0.3863564 0.3755698 0.3638026 \
-		0.353016 0.34321 0.333404 0.3245786 0.3157532 0.3069278 0.2981024 0.2902576 0.2833934 0.2755486 \
-		0.2686844 0.2618202 0.254956 0.2490724 0.2431888 0.2373052 0.2314216 0.2265186 0.220635 0.215732 \
-		0.210829 0.205926 0.2020036 0.1971006 0.1931782 0.1892558 0.1853334 0.181411 0.1774886 0.1735662 \
-		0.1706244 0.166702 0.1637602}
+        4.0861602 3.6321424 3.2683398 2.971218 2.7241068 2.5142584 2.3348086 2.1788932 2.0425898 1.9229566 \
+        1.8160712 1.7199724 1.6346602 1.5562122 1.485609 1.4208894 1.3620534 1.3071398 1.2571292 1.211041 \
+        1.166914 1.1267094 1.0894466 1.054145 1.0217852 0.990406 0.960988 0.9335312 0.9080356 0.8835206 \
+        0.8599862 0.838413 0.8168398 0.7972278 0.7785964 0.759965 0.7432948 0.7266246 0.710935 0.6952454 \
+        0.6805364 0.666808 0.6540602 0.6285646 0.6040496 0.5814958 0.5609032 0.5403106 0.5206986 0.5030478 \
+        0.485397 0.4697074 0.4540178 0.4393088 0.4255804 0.411852 0.3991042 0.3863564 0.3755698 0.3638026 \
+        0.353016 0.34321 0.333404 0.3245786 0.3157532 0.3069278 0.2981024 0.2902576 0.2833934 0.2755486 \
+        0.2686844 0.2618202 0.254956 0.2490724 0.2431888 0.2373052 0.2314216 0.2265186 0.220635 0.215732 \
+        0.210829 0.205926 0.2020036 0.1971006 0.1931782 0.1892558 0.1853334 0.181411 0.1774886 0.1735662 \
+        0.1706244 0.166702 0.1637602}
 timeSeries Path 1 -time $Tn -values $Sa
 
 # a uniaxial material for transverse shear
@@ -144,21 +144,21 @@ set dmp [lrepeat [llength $eigs] 0.05]
 set scalf [lrepeat [llength $eigs] 1.0]
 # CQC function
 proc CQC {mu lambdas dmp scalf} {
-	set u 0.0
-	set ne [llength $lambdas]
-	for {set i 0} {$i < $ne} {incr i} {
-		for {set j 0} {$j < $ne} {incr j} {
-			set di [lindex $dmp $i]
-			set dj [lindex $dmp $j]
-			set bij [expr [lindex $lambdas $i]/[lindex $lambdas $j]]
-			set rho [expr \
-				((8.0*sqrt($di*$dj)*($di+$bij*$dj)*($bij**(3.0/2.0))) / \
-				(pow(1.0-$bij**2.0,2.0) + 4.0*$di*$dj*$bij*(1.0+pow($bij,2.0)) + \
-				4.0*(pow($di,2.0) + pow($dj,2.0))*pow($bij,2.0)))]
-			set u [expr $u + [lindex $scalf $i]*[lindex $mu $i] * [lindex $scalf $j]*[lindex $mu $j] * $rho]
-		}
-	}
-	return [expr sqrt($u)]
+    set u 0.0
+    set ne [llength $lambdas]
+    for {set i 0} {$i < $ne} {incr i} {
+        for {set j 0} {$j < $ne} {incr j} {
+            set di [lindex $dmp $i]
+            set dj [lindex $dmp $j]
+            set bij [expr [lindex $lambdas $i]/[lindex $lambdas $j]]
+            set rho [expr \
+                ((8.0*sqrt($di*$dj)*($di+$bij*$dj)*($bij**(3.0/2.0))) / \
+                (pow(1.0-$bij**2.0,2.0) + 4.0*$di*$dj*$bij*(1.0+pow($bij,2.0)) + \
+                4.0*(pow($di,2.0) + pow($dj,2.0))*pow($bij,2.0)))]
+            set u [expr $u + [lindex $scalf $i]*[lindex $mu $i] * [lindex $scalf $j]*[lindex $mu $j] * $rho]
+        }
+    }
+    return [expr sqrt($u)]
 }
 
 # ========================================================================
@@ -175,10 +175,10 @@ set My {}
 set f [open $filename "r"]
 set lines [split [read $f] "\n"]
 foreach line $lines {
-	if {[llength $line] > 0} {
-		set tokens [split $line " "]
-		lappend My [lindex $tokens 2]
-	}
+    if {[llength $line] > 0} {
+        set tokens [split $line " "]
+        lappend My [lindex $tokens 2]
+    }
 }
 close $f
 
@@ -190,7 +190,7 @@ puts "Do CQC combination in post processing."
 puts "Use Tn and Sa lists.\n"
 puts [format "%10s %15s" "Mode" "My"]
 for {set i 0} {$i < [llength $eigs]} {incr i} {
-	puts [format "%10g %15f" [expr $i+1] [lindex $My $i]]
+    puts [format "%10g %15f" [expr $i+1] [lindex $My $i]]
 }
 puts [format "%10s %15f" "CQC" $MyCQC]
 
@@ -208,10 +208,10 @@ set My {}
 set f [open $filename "r"]
 set lines [split [read $f] "\n"]
 foreach line $lines {
-	if {[llength $line] > 0} {
-		set tokens [split $line " "]
-		lappend My [lindex $tokens 2]
-	}
+    if {[llength $line] > 0} {
+        set tokens [split $line " "]
+        lappend My [lindex $tokens 2]
+    }
 }
 close $f
 
@@ -223,7 +223,7 @@ puts "Do CQC combination in post processing."
 puts "Use a Path timeSeries to store Tn-Sa pairs.\n"
 puts [format "%10s %15s" "Mode" "My"]
 for {set i 0} {$i < [llength $eigs]} {incr i} {
-	puts [format "%10g %15f" [expr $i+1] [lindex $My $i]]
+    puts [format "%10g %15f" [expr $i+1] [lindex $My $i]]
 }
 puts [format "%10s %15f" "CQC" $MyCQC]
 
@@ -236,9 +236,9 @@ puts [format "%10s %15f" "CQC" $MyCQC]
 remove recorder 0
 set My {}
 for {set i 0} {$i < [llength $eigs]} {incr i} {
-	responseSpectrumAnalysis $direction -Tn $Tn -Sa $Sa -mode [expr $i+1]
-	set force [eleResponse 1 section 1 force]
-	lappend My [lindex $force 2]
+    responseSpectrumAnalysis $direction -Tn $Tn -Sa $Sa -mode [expr $i+1]
+    set force [eleResponse 1 section 1 force]
+    lappend My [lindex $force 2]
 }
 
 # post process the results doing the CQC modal combination for the My response (3rd column in section forces)
@@ -247,7 +247,7 @@ puts "\n\nTEST 02:\nRun a Response Spectrum Analysis mode-by-mode."
 puts "Grab results during the loop and do CQC combination with them.\n"
 puts [format "%10s %15s" "Mode" "My"]
 for {set i 0} {$i < [llength $eigs]} {incr i} {
-	puts [format "%10g %15f" [expr $i+1] [lindex $My $i]]
+    puts [format "%10g %15f" [expr $i+1] [lindex $My $i]]
 }
 puts [format "%10s %15f" "CQC" $MyCQC]
 
diff --git a/source/user/manual/analysis/index.rst b/source/user/manual/analysis/index.rst
@@ -36,14 +36,13 @@ These include:
    algorithm
    analyze
    constraints
-   numberer
    system
    test
    eigen
-
-..
-   analysis/modalProperties
-   analysis/responseSpectrumAnalysis
+   modalProperties
+   responseSpectrumAnalysis
 
 
+..
+   numberer
 
diff --git a/source/user/manual/analysis/integrator.rst b/source/user/manual/analysis/integrator.rst
@@ -55,14 +55,14 @@ The type of integrator used in the analysis is dependent on whether it is a :ref
    :caption: Transient Integrators
    :maxdepth: 1
 
-   integrator/CentralDifference
    integrator/Newmark
-   integrator/HHT
    integrator/GeneralizedAlpha
    integrator/TRBDF2
-   integrator/ExplicitDifference
-
 
+..
+   integrator/CentralDifference
+   integrator/HHT
+   integrator/ExplicitDifference
 
 References
 ----------
diff --git a/source/user/manual/analysis/integrator/GeneralizedAlpha.rst b/source/user/manual/analysis/integrator/GeneralizedAlpha.rst
@@ -1,7 +1,7 @@
 .. _GeneralizedAlphaMethod:
 
-Generalized Alpha Method
-^^^^^^^^^^^^^^^^^^^^^^^^
+Generalized Alpha
+^^^^^^^^^^^^^^^^^
 
 .. function:: integrator GeneralizedAlpha $alphaM $alphaF <$gamma $beta> 
 
diff --git a/source/user/manual/analysis/modalProperties.rst b/source/user/manual/analysis/modalProperties.rst
@@ -1,7 +1,7 @@
 .. _modalProperties:
 
 modalProperties
-***************
+^^^^^^^^^^^^^^^
 
 This command is used to compute the modal properties of a model after an :ref:`eigen`.
 This command computes the following modal properties:
@@ -13,7 +13,7 @@ This command computes the following modal properties:
 *  :math:`MPF` : The modal participation factors.
 *  :math:`MPM` : The modal participation masses.
 *  :math:`MPMc` : The cumulative modal participation masses.
-*  :math:`MPM\left(\%\right)` : The modal participation masse ratios.
+*  :math:`MPM\left(\%\right)` :  The modal participation masse ratios.
 *  :math:`MPMc\left(\%\right)` : The cumulative modal participation masse ratios.
 
 .. function:: modalProperties <-print> <-return> <-file $reportFileName> <-unorm>
@@ -181,7 +181,7 @@ This command computes the following modal properties:
    *  Only the values in :math:`gm` and :math:`MPF` depend on the normalization of the eigenvectors. This normalization depends on the solver used in the :ref:`eigen`. The default -genBandArpack uses a mass-normalization, so that the :math:`gm` is the identity. On the contrary, the -fullGenLapack uses a displacement-normalization, so that the largest component of the eigenvector is 1. If you use the -genBandArpack, but want a displacement-normalization of the eigenvectors, use the **-unorm** option.
 
 Theory
-^^^^^^
+======
 The eigenvalues :math:`\lambda` and the eigenvectors :math:`\Phi` can be obtained after solving the *generalized eigenvalue problem* for two symmetric matrices :math:`K` (stiffness) and :math:`M` (mass) given by:
 
 .. math::
diff --git a/source/user/manual/analysis/numberer.rst b/source/user/manual/analysis/numberer.rst
@@ -17,7 +17,7 @@ Although this has no effect on the solution, it can have a significant effect on
 
          :param string type: The numberer type.
          :param args: A sequence of arguments for that type.
-   
+
    .. tab:: Tcl
 
       .. function:: numberer type? args? ...
diff --git a/source/user/manual/analysis/responseSpectrumAnalysis.rst b/source/user/manual/analysis/responseSpectrumAnalysis.rst
@@ -1,21 +1,19 @@
 .. _responseSpectrumAnalysis:
 
 responseSpectrumAnalysis
-************************
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-|  This command is used to perform a response spectrum analysis.
-|  The response spectrum analysis performs N linear analysis steps, where N is the number of eigenvalues requested in a previous call to :ref:`eigen`.
-|  For each analysis step, it computes the modal displacements. When the i-th analysis step is complete, all previously defined recorders will be called, so they will record all the results requested by the user, pertaining to the current modal displacements.
-|  The modal combination of these modal displacements (and derived results such as beam forces) is up to the user, and can be easily done via TCL or Python scripting.
+This command is used to perform a response spectrum analysis.
+The response spectrum analysis performs N linear analysis steps, where N is the number of eigenvalues requested in a previous call to :ref:`eigen`.
+For each analysis step, it computes the modal displacements. When the i-th analysis step is complete, all previously defined recorders will be called, so they will record all the results requested by the user, pertaining to the current modal displacements.
+The modal combination of these modal displacements (and derived results such as beam forces) is up to the user, and can be easily done via TCL or Python scripting.
 
-|  The command can be called in two different ways, depending on how you store the Tn/Sa (response spectrum function) values.
-|  They can be either stored in a timeSeries ...
+.. function:: responseSpectrumAnalysis $direction -Tn $Tn -Sa $Sa <-scale $scale> <-mode $mode>
 
-.. function:: responseSpectrumAnalysis $tsTag $direction <-scale $scale> <-mode $mode>
+.. note::
 
-|  ... or in two lists
-
-.. function:: responseSpectrumAnalysis $direction -Tn $Tn -Sa $Sa <-scale $scale> <-mode $mode>
+   This is the only form of the command that is supported by |xara|. 
+   The variant using a time series is not supported.   
 
 .. csv-table:: 
    :header: "Argument", "Type", "Description"
@@ -33,15 +31,21 @@ responseSpectrumAnalysis
    $mode, |integer|, "The 1-based index of the unique mode to process."
 
 .. note::
+
    *  This command can be used only if a previous call to :ref:`eigen` and :ref:`modalProperties` has been performed.
    *  It computes only the modal displacements, any modal combination is up to the user.
-   *  The scale factor (-scale $scale) for the output modal displacements is not used now, and it's there for future implementations. When your model is linear elastic there is no need to use this option. It will be useful in future when we will allow using this command on a nonlinear model as a **linear perturbation** about a certain nonlinear state. In that case, the scale factor can be set to a very small number, so that the computed modal displacements will be very small (linear perturbation) and will not alter the nonlinear state of your model. Then the inverse of the scale factor can be used to post-multiply any result for post-processing.
+   *  The ``scale`` factor for the output modal displacements is not used now, and it's there for future implementations. 
+      When your model is linear elastic there is no need to use this option. 
+      It will be useful in future when we will allow using this command on a nonlinear model as a *linear perturbation* about a certain nonlinear state. 
+      In that case, the scale factor can be set to a very small number, so that the computed modal displacements will be very small (linear perturbation) and will not alter the nonlinear state of your model. Then the inverse of the scale factor can be used to post-multiply any result for post-processing.
 
 Theory
-^^^^^^
-|  Once the eigenvalue problem (:ref:`eigen`) has been solved, and once the modal properties (:ref:`modalProperties`) have been computed, the modal displacements :math:`U` for mode :math:`i` at node :math:`n` and DOF :math:`j` is given by
+------
+
+Once the eigenvalue problem (:ref:`eigen`) has been solved, and once the modal properties (:ref:`modalProperties`) have been computed, the modal displacements :math:`U` for mode :math:`i` at node :math:`n` and DOF :math:`j` is given by
 
 .. math::
+
    U_{ij}^n = \frac{\Phi_{ij}^n \cdot MPF_{ij} \cdot RSf\left(T_i\right)}{\lambda_i}
 
 |  where:
@@ -52,6 +56,10 @@ Theory
    *  :math:`RSf\left(T_i\right)` is the response spectrum function value at period :math:`T_i`
    *  and :math:`T_i` is the period :math:`\frac{2\pi}{\sqrt{\lambda_i}}`
 
+
+Examples
+--------
+
 .. admonition:: Example 1: Simple call
    
    The following example shows how to call the responseSpectrumAnalysis command for all modes, using the time series 1 (or lists Tn and Sa) along the DOF 1 (Ux)
diff --git a/source/user/manual/analysis/static.rst b/source/user/manual/analysis/static.rst
@@ -35,7 +35,6 @@ Newton schemes, are based on the *linearization* of the residual :math:`\boldsym
 
 .. math::
 
-
    \mathcal{L} \boldsymbol{r}(\boldsymbol{u}, \lambda)(\boldsymbol{u}_{n},\lambda_n) = \lambda_n^{(i)} \boldsymbol{p}_f 
     - \boldsymbol{p}_{\sigma}\left(\boldsymbol{u}_{n}^{(i)} \right) - \left[
    \begin{array}{cc}
diff --git a/source/user/manual/modules/units.rst b/source/user/manual/modules/units.rst
diff --git a/source/user/manual/section/ElasticFrame.rst b/source/user/manual/section/ElasticFrame.rst

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-from opensees import *`
	`1`	`+from opensees.openseespy import *`
`2`	`2`	`from math import sqrt`
`3`	`3`
`4`	`4`	`wipe()`