updated theory for CMS in RST; added CMS-stress description

Author: jgerstmayr

README.rst

@@ -39,7 +39,7 @@ Exudyn
 
 **A flexible multibody dynamics systems simulation code with Python and C++**
 
-Exudyn version = 1.8.28.dev1 (Jones)
+Exudyn version = 1.8.32.dev1 (Jones)
 
 +  **University of Innsbruck**, Department of Mechatronics, Innsbruck, Austria
 

docs/RST/Examples/reinforcementLearningRobot.rst

@@ -39,7 +39,7 @@ Exudyn
 
 **A flexible multibody dynamics systems simulation code with Python and C++**
 
-Exudyn version = 1.8.28.dev1 (Jones)
+Exudyn version = 1.8.32.dev1 (Jones)
 
 +  **University of Innsbruck**, Department of Mechatronics, Innsbruck, Austria
 

docs/RST/Exudyn.rst

@@ -128,4 +128,4 @@ Further integration rules can be found in the C++ code of Exudyn, see file \ ``B
 
 
 
-\ **For further information on this topic read**\ : `theDoc.pdf <https://github.com/jgerstmayr/EXUDYN/blob/master/docs/theDoc/theDoc.pdf>`_
+

docs/RST/IntegrationPoints.rst

@@ -10,4 +10,5 @@ Theory and formulations
    DynamicsMechanicalPrinciples
    FramesRotationsAndCoordinateSystems
    IntegrationPoints
+   ModelOrderReductionAndComponentModeSynthesis
 

docs/RST/ModelOrderReductionAndComponentModeSynthesis.rst

@@ -1081,16 +1081,19 @@ Relevant Examples (Ex) and TestModels (TM) with weblink to github:
 
 Function: ComputeLinearizedSystem
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`ComputeLinearizedSystem <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L366>`__\ (\ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``useSparseSolver = False``\ )
+`ComputeLinearizedSystem <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L369>`__\ (\ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``projectIntoConstraintNullspace = False``\ , \ ``singularValuesTolerance = 1e-12``\ , \ ``returnConstraintJacobian = False``\ , \ ``returnConstraintNullspace = False``\ )
 
 - | \ *function description*\ :
-  | compute linearized system of equations for ODE2 part of mbs, not considering the effects of algebraic constraints
+  | compute linearized system of equations for ODE2 part of mbs, not considering the effects of algebraic constraints; for computation of eigenvalues and advanced computation with constrained systems, see ComputeODE2Eigenvalues; the current implementation is also able to project into the constrained space, however, this currently does not generally work with non-holonomic systems
   | - NOTE that this function is added to MainSystem via Python function ComputeLinearizedSystem.
 - | \ *input*\ :
   | \ ``simulationSettings``\ : specific simulation settings used for computation of jacobian (e.g., sparse mode in static solver enables sparse computation)
-  | \ ``useSparseSolver``\ : if False (only for small systems), all eigenvalues are computed in dense mode (slow for large systems!); if True, only the numberOfEigenvalues are computed (numberOfEigenvalues must be set!); Currently, the matrices are exported only in DENSE MODE from mbs! NOTE that the sparsesolver accuracy is much less than the dense solver
+  | \ ``projectIntoConstraintNullspace``\ : if False, algebraic equations (and constraint jacobian) are not considered for the linearized system; if True, the equations are projected into the nullspace of the constraints in the current configuration, using singular value decomposition; in the latter case, the returned list contains [M, K, D, C, N] where C is the constraint jacobian and N is the nullspace matrix (C and N may be an empty list, depending on the following flags)
+  | \ ``singularValuesTolerance``\ : tolerance used to distinguish between zero and nonzero singular values for algebraic constraints projection
+  | \ ``returnConstraintJacobian``\ : if True, the returned list contains [M, K, D, C, N] where C is the constraint jacobian and N is the nullspace matrix (may be empty)
+  | \ ``returnConstraintNullspace``\ : if True, the returned list contains [M, K, D, C, N] where C is the constraint jacobian (may be empty) and N is the nullspace matrix
 - | \ *output*\ :
-  | [ArrayLike, ArrayLike, ArrayLike]; [M, K, D]; list containing numpy mass matrix M, stiffness matrix K and damping matrix D
+  | [ArrayLike, ArrayLike, ArrayLike]; [M, K, D]; list containing numpy mass matrix M, stiffness matrix K and damping matrix D; for constraints, see options with arguments above, return values may change to [M, K, D, C, N]
 - | \ *notes*\ :
   | consider paper of Agundez, Vallejo, Freire, Mikkola, "The dependent coordinates in the linearization of constrained multibody systems: Handling and elimination", https://www.sciencedirect.com/science/article/pii/S0020740324000791
 - | \ *example*\ :
@@ -1131,19 +1134,19 @@ Relevant Examples (Ex) and TestModels (TM) with weblink to github:
 
 Function: ComputeODE2Eigenvalues
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`ComputeODE2Eigenvalues <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L443>`__\ (\ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``useSparseSolver = False``\ , \ ``numberOfEigenvalues = 0``\ , \ ``constrainedCoordinates = []``\ , \ ``convert2Frequencies = False``\ , \ ``useAbsoluteValues = True``\ , \ ``computeComplexEigenvalues = False``\ , \ ``ignoreAlgebraicEquations = False``\ , \ ``singularValuesTolerance = 1e-12``\ )
+`ComputeODE2Eigenvalues <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L502>`__\ (\ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``useSparseSolver = False``\ , \ ``numberOfEigenvalues = 0``\ , \ ``constrainedCoordinates = []``\ , \ ``convert2Frequencies = False``\ , \ ``useAbsoluteValues = True``\ , \ ``computeComplexEigenvalues = False``\ , \ ``ignoreAlgebraicEquations = False``\ , \ ``singularValuesTolerance = 1e-12``\ )
 
 - | \ *function description*\ :
-  | compute eigenvalues for unconstrained ODE2 part of mbs; the computation may include constraints in case that ignoreAlgebraicEquations=False; for algebraic constraints, however, a dense singular value decomposition of the constraint jacobian is used for the nullspace projection; the computation is done for the initial values of the mbs, independently of previous computations. If you would like to use the current state for the eigenvalue computation, you need to copy the current state to the initial state (using GetSystemState, SetSystemState, see Section :ref:`sec-mbs-systemdata`\ ); note that mass and stiffness matrices are computed in dense mode so far, while eigenvalues are computed according to useSparseSolver.
+  | compute eigenvalues for unconstrained ODE2 part of mbs; the computation may include constraints in case that ignoreAlgebraicEquations=False (however, this currently does not generally work with non-holonomic systems); for algebraic constraints, however, a dense singular value decomposition of the constraint jacobian is used for the nullspace projection; the computation is done for the initial values of the mbs, independently of previous computations. If you would like to use the current state for the eigenvalue computation, you need to copy the current state to the initial state (using GetSystemState, SetSystemState, see Section :ref:`sec-mbs-systemdata`\ ); note that mass and stiffness matrices are computed in dense mode so far, while eigenvalues are computed according to useSparseSolver.
   | - NOTE that this function is added to MainSystem via Python function ComputeODE2Eigenvalues.
 - | \ *input*\ :
   | \ ``simulationSettings``\ : specific simulation settings used for computation of jacobian (e.g., sparse mode in static solver enables sparse computation)
-  | \ ``useSparseSolver``\ : if False (only for small systems), all eigenvalues are computed in dense mode (slow for large systems!); if True, only the numberOfEigenvalues are computed (numberOfEigenvalues must be set!); Currently, the matrices are exported only in DENSE MODE from mbs! NOTE that the sparsesolver accuracy is much less than the dense solver
+  | \ ``useSparseSolver``\ : if False (only for small systems), all eigenvalues are computed in dense mode (slow for large systems!); if True, only the numberOfEigenvalues are computed (numberOfEigenvalues must be set!); Currently, the matrices are exported only in DENSE MODE from mbs, which means that intermediate matrices may become huge for more than 5000 coordinates! NOTE that the sparsesolver accuracy is much less than the dense solver
   | \ ``numberOfEigenvalues``\ : number of eigenvalues and eivenvectors to be computed; if numberOfEigenvalues==0, all eigenvalues will be computed (may be impossible for larger or sparse problems!)
   | \ ``constrainedCoordinates``\ : if this list is non-empty (and there are no algebraic equations or ignoreAlgebraicEquations=True), the integer indices represent constrained coordinates of the system, which are fixed during eigenvalue/vector computation; according rows/columns of mass and stiffness matrices are erased; in this case, algebraic equations of the system are ignored
   | \ ``convert2Frequencies``\ : if True, the eigen values are converted into frequencies (Hz) and the output is [eigenFrequencies, eigenVectors]
   | \ ``useAbsoluteValues``\ : if True, abs(eigenvalues) is used, which avoids problems for small (close to zero) eigenvalues; needed, when converting to frequencies
-  | \ ``computeComplexEigenvalues``\ : if True, the system is converted into a system of first order differential equations, including damping; only implemented for dense solver!
+  | \ ``computeComplexEigenvalues``\ : if True, the system is converted into a system of first order differential equations, including damping; for complex eigenvalues, set useAbsoluteValues=False (otherwise you will not get the complex values; values are unsorted, however!); only implemented for dense solver
   | \ ``ignoreAlgebraicEquations``\ : if True, algebraic equations (and constraint jacobian) are not considered for eigenvalue computation; otherwise, the solver tries to automatically project the system into the nullspace kernel of the constraint jacobian using a SVD; this gives eigenvalues of the constrained system; eigenvectors are not computed
   | \ ``singularValuesTolerance``\ : tolerance used to distinguish between zero and nonzero singular values for algebraic constraints projection
 - | \ *output*\ :
@@ -1163,7 +1166,6 @@ Function: ComputeODE2Eigenvalues
   mbs = SC.AddSystem()
   #
   b0 = mbs.CreateMassPoint(referencePosition = [2,0,0],
-                           initialVelocity = [2*0,5,0],
                            physicsMass = 1, gravity = [0,-9.81,0],
                            drawSize = 0.5, color=color4blue)
   #
@@ -1178,7 +1180,14 @@ Function: ComputeODE2Eigenvalues
   mbs.Assemble()
   #
   [eigenvalues, eigenvectors] = mbs.ComputeODE2Eigenvalues()
-   #==>eigenvalues contain the eigenvalues of the ODE2 part of the system in the current configuration
+  #==>eigenvalues contain the eigenvalues of the ODE2 part of the system in the current configuration
+  #
+  #compute eigenfrequencies in Hz (analytical: 100/2/pi Hz for y-direction):
+  [eigenvaluesHz, ev] = mbs.ComputeODE2Eigenvalues(convert2Frequencies=True)
+  #
+  #compute complex eigenvalues:
+  [eigenvaluesComplex, ev] = mbs.ComputeODE2Eigenvalues(computeComplexEigenvalues=True,
+                                                        useAbsoluteValues=False)
 
 
 Relevant Examples (Ex) and TestModels (TM) with weblink to github:
@@ -1191,7 +1200,7 @@ Relevant Examples (Ex) and TestModels (TM) with weblink to github:
 
 Function: ComputeSystemDegreeOfFreedom
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`ComputeSystemDegreeOfFreedom <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L660>`__\ (\ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``threshold = 1e-12``\ , \ ``verbose = False``\ , \ ``useSVD = False``\ )
+`ComputeSystemDegreeOfFreedom <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L719>`__\ (\ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``threshold = 1e-12``\ , \ ``verbose = False``\ , \ ``useSVD = False``\ )
 
 - | \ *function description*\ :
   | compute system DOF numerically, considering Grübler-Kutzbach formula as well as redundant constraints; uses numpy matrix rank or singular value decomposition of scipy (useSVD=True)

docs/RST/TheoryAndFormulationsIndex.rst

@@ -83,7 +83,7 @@ Function: SolverSuccess
 
 Function: ComputeLinearizedSystem
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`ComputeLinearizedSystem <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L366>`__\ (\ ``mbs``\ , \ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``useSparseSolver = False``\ )
+`ComputeLinearizedSystem <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L369>`__\ (\ ``mbs``\ , \ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``projectIntoConstraintNullspace = False``\ , \ ``singularValuesTolerance = 1e-12``\ , \ ``returnConstraintJacobian = False``\ , \ ``returnConstraintNullspace = False``\ )
 
 
 - | **NOTE**\ : this function is directly available in MainSystem (mbs); it should be directly called as mbs.ComputeLinearizedSystem(...). For description of the interface, see the MainSystem Python extensions,  :ref:`sec-mainsystemextensions-computelinearizedsystem`\ 
@@ -94,7 +94,7 @@ Function: ComputeLinearizedSystem
 
 Function: ComputeODE2Eigenvalues
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`ComputeODE2Eigenvalues <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L443>`__\ (\ ``mbs``\ , \ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``useSparseSolver = False``\ , \ ``numberOfEigenvalues = 0``\ , \ ``constrainedCoordinates = []``\ , \ ``convert2Frequencies = False``\ , \ ``useAbsoluteValues = True``\ , \ ``computeComplexEigenvalues = False``\ , \ ``ignoreAlgebraicEquations = False``\ , \ ``singularValuesTolerance = 1e-12``\ )
+`ComputeODE2Eigenvalues <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L502>`__\ (\ ``mbs``\ , \ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``useSparseSolver = False``\ , \ ``numberOfEigenvalues = 0``\ , \ ``constrainedCoordinates = []``\ , \ ``convert2Frequencies = False``\ , \ ``useAbsoluteValues = True``\ , \ ``computeComplexEigenvalues = False``\ , \ ``ignoreAlgebraicEquations = False``\ , \ ``singularValuesTolerance = 1e-12``\ )
 
 
 - | **NOTE**\ : this function is directly available in MainSystem (mbs); it should be directly called as mbs.ComputeODE2Eigenvalues(...). For description of the interface, see the MainSystem Python extensions,  :ref:`sec-mainsystemextensions-computeode2eigenvalues`\ 
@@ -105,7 +105,7 @@ Function: ComputeODE2Eigenvalues
 
 Function: ComputeSystemDegreeOfFreedom
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`ComputeSystemDegreeOfFreedom <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L660>`__\ (\ ``mbs``\ , \ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``threshold = 1e-12``\ , \ ``verbose = False``\ , \ ``useSVD = False``\ )
+`ComputeSystemDegreeOfFreedom <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L719>`__\ (\ ``mbs``\ , \ ``simulationSettings = exudyn.SimulationSettings()``\ , \ ``threshold = 1e-12``\ , \ ``verbose = False``\ , \ ``useSVD = False``\ )
 
 
 - | **NOTE**\ : this function is directly available in MainSystem (mbs); it should be directly called as mbs.ComputeSystemDegreeOfFreedom(...). For description of the interface, see the MainSystem Python extensions,  :ref:`sec-mainsystemextensions-computesystemdegreeoffreedom`\ 
@@ -119,7 +119,7 @@ Function: ComputeSystemDegreeOfFreedom
 
 Function: CheckSolverInfoStatistics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`CheckSolverInfoStatistics <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L747>`__\ (\ ``solverName``\ , \ ``infoStat``\ , \ ``numberOfEvaluations``\ )
+`CheckSolverInfoStatistics <https://github.com/jgerstmayr/EXUDYN/blob/master/main/pythonDev/exudyn/solver.py\#L806>`__\ (\ ``solverName``\ , \ ``infoStat``\ , \ ``numberOfEvaluations``\ )
 
 - | \ *function description*\ :
   | helper function for solvers to check e.g. if high number of memory allocations happened during simulation

docs/RST/cInterface/MainSystem.rst

@@ -19,15 +19,27 @@ BUG numbers refer to the according issue numbers.
 
 General information on current version:
 
-+  Exudyn version = 1.8.28.dev1, 
-+  last change =  2024-05-04, 
-+  Number of issues = 1834, 
-+  Number of resolved issues = 1622 (28 in current version), 
++  Exudyn version = 1.8.32.dev1, 
++  last change =  2024-05-09, 
++  Number of issues = 1837, 
++  Number of resolved issues = 1626 (32 in current version), 
 
 ***********
 Version 1.8
 ***********
 
+ * Version 1.8.32: resolved Issue 1832: theory docu (docu)
+    - description:  add description of computation of stresses for FFRFreducedOrder
+    - date resolved: **2024-05-09 17:12**\ , date raised: 2024-05-03 
+ * Version 1.8.31: resolved Issue 1836: ComputeLinearizedSystem (extension)
+    - description:  output constraint and nullspace matrices for constrained systems
+    - date resolved: **2024-05-05 16:18**\ , date raised: 2024-05-05 
+ * Version 1.8.30: resolved Issue 1835: ComputeLinearizedSystem (extension)
+    - description:  add option to compute linearized system of constrained system
+    - date resolved: **2024-05-05 16:18**\ , date raised: 2024-05-05 
+ * Version 1.8.29: resolved Issue 1834: ComputeLinearizedSystem (change)
+    - description:  remove sparse solver option useSparseSolver, as it is not implemented
+    - date resolved: **2024-05-05 16:17**\ , date raised: 2024-05-05 
  * Version 1.8.28: resolved Issue 1833: ComputeODE2EigenValues (extension)
     - description:  extend to complex eigenvalues
     - **notes:** added TestModel complexEigenvaluesTest.py
@@ -61,7 +73,7 @@ Version 1.8
     - description:  change type in AddObject, AddMarker, AddSensor, AddLoad, AddNode from pyObject: dict to pyObject: Any in order to resolve typing errors
     - date resolved: **2024-04-21 19:16**\ , date raised: 2024-04-19 
  * Version 1.8.18: resolved Issue 1819: KinematicTreePendulum.py (example)
-    - description:  Version 1.7.71 broke example „kinematicTreePendulum“ with transition from SensorObject to SensorBody
+    - description:  Version 1.7.71 broke example kinematicTreePendulum with transition from SensorObject to SensorBody
     - **notes:** changed SensorObject(objectNumber=oKT into SensorBody(bodyNumber=oKT
     - date resolved: **2024-04-17 16:13**\ , date raised: 2024-04-17 
     - resolved by: P. Manzl
@@ -80,7 +92,7 @@ Version 1.8
     - description:  .pyi files do not contain correct default args for C++ interfaces
     - date resolved: **2024-04-14 16:15**\ , date raised: 2024-04-14 
  * Version 1.8.13: resolved Issue 1815: stub files (fix)
-    - description:  .pyi files contain _ instead of _ from latex documentation
+    - description:  .pyi are missing backslash before underscore (for latex) documentation
     - date resolved: **2024-04-14 15:15**\ , date raised: 2024-04-14 
  * Version 1.8.12: resolved Issue 1812: GetMarkerOutput (fix)
     - description:  not working for MarkerKinematicTreeRigid in case of Reference configuration; adjustments done in CObjectKinematicTree::ComputeTreeTransformations to avoid the need for velocities in the retrieval of positions
@@ -5273,10 +5285,6 @@ Version 0.1
 Open issues
 ***********
 
- * **open issue 1832:** theory docu         
-    - description:  add description of computation of stresses for FFRFreducedOrder
-    - date raised: 2024-05-03 
-
  * **open issue 1825:** GraphicsDataCube    
     - description:  rename to GraphicsDataBrick... functions; use assignment to keep previous functionality
     - date raised: 2024-04-25