[CDB-READER] Add strain energy to beam.py

docs/cdb/post/strain_energy.rst

@@ -0,0 +1,85 @@
+Strain Energy
+-------------
+
+The strain energy can be calculated from the internal forces obtained from
+SOFiSTiK, together with the relevant cross-sectional properties and the
+element length.
+
+Under the hyphoteses of:
+
+* small displacements and
+* constant material and cross-sectional properties of the beam along its length,
+
+the general expression for the strain energy of an elastic beam is:
+
+.. math::
+    :label: strain_energy_general
+
+    U = \frac{1}{2} \int_{0}^{L} \left(
+            \frac{N^{2}\left(x\right)}{EA} +
+            \frac{M_{Y}^{2}\left(x\right)}{EI_{Y}} +
+            \frac{M_{Z}^{2}\left(x\right)}{EI_{Z}} +
+            \frac{k_{Y}V_{Y}^{2}\left(x\right)}{GA} +
+            \frac{k_{Z}V_{Z}^{2}\left(x\right)}{GA} +
+            \frac{T^{2}\left(x\right)}{GJ}
+        \right) dx
+
+where :math:`N` is the axial force, :math:`M_Y` and :math:`M_Z` are the
+bending moments, :math:`V_Y` and :math:`V_Z` are the shear forces, :math:`T` is
+the torsional moment, :math:`E` and :math:`G` are the normal and shear moduli,
+:math:`A`, :math:`I_Y` and :math:`I_Z` are the area and the two second moments
+of area of the cross-section. :math:`k_Y` and :math:`k_Z` are the two shear
+factors.
+
+This expression is particularized and further developed for each type of finite
+element in the next paraghraps.
+
+.. important::
+
+   The strain energy calculated by this module is approximate only. Further
+   details are provided below.
+
+   Although efforts have been made to ensure that the relevant engineering
+   theory has been correctly implemented, it remains the user's
+   responsibility to verify and validate the results, particularly with
+   regard to whether the adopted simplifications are appropriate for the
+   intended use.
+
+Beam elements
+"""""""""""""
+
+If the contributions of shear forces and torsion can be neglected, the
+expression :eq:`strain_energy_general` can be simplified to:
+
+.. math::
+    U = \frac{1}{2E} \int_{0}^{L} \left(
+            \frac{N^{2}\left(x\right)}{A} +
+            \frac{M_{Y}^{2}\left(x\right)}{I_{Y}} +
+            \frac{M_{Z}^{2}\left(x\right)}{I_{Z}}
+        \right) dx
+
+If we assume a generic linear variation for any of the internal force of the type:
+
+.. math::
+    Q(x) = a + bx
+
+Its square integral over the beam length is:
+
+.. math::
+    \int_{0}^{L} Q(x)^{2}dx = \frac{L}{3} \left( Q_{1}^{2} + Q_{1}Q_{2}+ Q_{2}^{2}\right)
+
+Where :math:`Q_1` and :math:`Q_2` are the values of :math:`Q` at beam end nodes
+
+Therefore the :
+
+.. math::
+
+   U = \frac{L}{6E} \left[
+           \frac{N_{1}^{2} + N_{1}N_{2} + N_{2}^{2}}{A}
+           +
+           \frac{M_{Y1}^{2} + M_{Y1}M_{Y2} + M_{Y2}^{2}}{I_Y}
+           +
+           \frac{M_{Z1}^{2} + M_{Z1}M_{Z2} + M_{Z2}^{2}}{I_Z}
+       \right]
+
+This equation, which is the one implemented, is valid if the

docs/cdb/post_processing.rst

@@ -0,0 +1,20 @@
+.. _cdb_post_processing:
+
+Post-processing
+===============
+
+The CDBReader module provides functionality to calculate and/or manipulate
+basic quantities extracted from the SOFiSTiK database, in addition to direct
+access to raw data.
+
+Available functionality includes:
+    * calculation of strain energy
+
+The following subsections provide further details on this post-processing
+capabilities.
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    post/strain_energy

docs/cdb/test_setup.rst

@@ -89,6 +89,7 @@ the temporary environment variable approach, open an MSYS2 MINGW64 shell, naviga
 
     tests/beam_data
     tests/beam_result
+    tests/beam_strain_energy
     tests/cable_data
     tests/cable_load
     tests/cable_result

docs/cdb/tests/beam_strain_energy.rst

@@ -0,0 +1,130 @@
+BeamStrainEnergy
+----------------
+
+Related test suite: ``test_beam_strain_energy.py``
+
+There are two test suites for beam strain energy and therefore two expected CDB
+files. The first one tests usual beam element without internal subdivisions
+(DIV), while the second tests beams with subdivisions.
+
+Part I
+""""""
+
+Expected CDB file name: ``BEAM_STRAIN_ENERGY.cdb``
+
+Runs with: SOFiSTiK 2025
+
+Version: 1
+
+.. code-block:: text
+
+    +PROG AQUA
+    HEAD MATERIAL AND SECTIONS
+        NORM EN 199X-200X
+        STEE NO 1 TYPE S 355 ES 210000.0 GAM 78.5 TITL 'S355'
+        PROF 1 TYPE CHS 300.0 10.0 MNO 1
+        PROF 2 TYPE CHS 200.0 10.0 MNO 1
+    END
+
+    +PROG SOFIMSHA
+    HEAD GEOMETRY REV-1-SOF-2025
+    SYST 3D GDIR NEGY GDIV 10
+        NODE NO 1 X 00.0 Y 0.0 Z +0.0 FIX MX,PX,PY,PZ
+        NODE NO 2 X 05.0 Y 0.0 Z +0.0
+        NODE NO 3 X 10.0 Y 0.0 Z +0.0 FIX PP
+
+        GRP 10 TITL 'BEAM_DIV'
+            BEAM NO 1 NA 1 NE 2 NCS 1 DIV 1 AHIN MT
+            BEAM NO 2 NA 2 NE 3 NCS 2.1 EHIN NMYMZ
+    END
+
+    +PROG SOFILOAD
+    HEAD LOADS
+        LC 20 TITL 'LOAD-1'
+            NODE 2 TYPE PYY -30.0
+        LC 30 TITL 'LOAD-2'
+            NODE 2 TYPE PXX +150.0
+    END
+
+    +PROG ASE
+    HEAD LINEAR ANALYSIS
+        SYST PROB LINE
+        LC 1000 DLY 0.0 TITL 'LC 1000'
+            LCC 20 FACT 1.0
+    END
+
+    +PROG ASE
+    HEAD LINEAR ANALYSIS
+        SYST PROB LINE
+        LC 1001 DLY 0.0 TITL 'LC 1001'
+            LCC 30 FACT 1.0
+    END
+
+    +PROG ASE
+    HEAD LINEAR ANALYSIS
+        SYST PROB LINE
+        LC 1002 DLY 0.0 TITL 'LC 1002'
+            LCC 20 FACT 1.0
+            LCC 30 FACT 1.0
+    END
+
+Part II
+"""""""
+
+Expected CDB file name: ``BEAM_STRAIN_ENERGY_WITH_DIV.cdb``
+
+Runs with: SOFiSTiK 2025
+
+Version: 1
+
+.. code-block:: text
+
+    +PROG AQUA
+    HEAD MATERIAL AND SECTIONS
+        NORM EN 199X-200X
+        STEE NO 1 TYPE S 355 ES 210000.0 GAM 78.5 TITL 'S355'
+        PROF 1 TYPE CHS 300.0 10.0 MNO 1
+        PROF 2 TYPE CHS 200.0 10.0 MNO 1
+    END
+
+    +PROG SOFIMSHA
+    HEAD GEOMETRY REV-1-SOF-2025
+    SYST 3D GDIR NEGY GDIV 10
+        NODE NO 1 X 00.0 Y 0.0 Z +0.0 FIX MX,PX,PY,PZ
+        NODE NO 2 X 05.0 Y 0.0 Z +0.0
+        NODE NO 3 X 10.0 Y 0.0 Z +0.0 FIX PP
+
+        GRP 10 TITL 'BEAM_DIV'
+            BEAM NO 1 NA 1 NE 2 NCS 1 DIV 5 AHIN MT
+            BEAM NO 2 NA 2 NE 3 NCS 2.1 EHIN NMYMZ
+    END
+
+    +PROG SOFILOAD
+    HEAD LOADS
+        LC 20 TITL 'LOAD-1'
+            BEAM 101 TYPE PYY -10.0
+        LC 30 TITL 'LOAD-2'
+            NODE 2 TYPE PXX +150.0
+    END
+
+    +PROG ASE
+    HEAD LINEAR ANALYSIS
+        SYST PROB LINE
+        LC 1000 DLY 0.0 TITL 'LC 1000'
+            LCC 20 FACT 1.0
+    END
+
+    +PROG ASE
+    HEAD LINEAR ANALYSIS
+        SYST PROB LINE
+        LC 1001 DLY 0.0 TITL 'LC 1001'
+            LCC 30 FACT 1.0
+    END
+
+    +PROG ASE
+    HEAD LINEAR ANALYSIS
+        SYST PROB LINE
+        LC 1002 DLY 0.0 TITL 'LC 1002'
+            LCC 20 FACT 1.0
+            LCC 30 FACT 1.0
+    END

docs/index.rst

@@ -53,6 +53,12 @@ for the terms and conditions of use.
     installation
     usage
 
+.. toctree::
+    :caption: CDB Reader
+    :hidden:
+
+    cdb/post_processing
+
 .. toctree::
     :caption: Testing
     :maxdepth: 1