Merge pull request #859 from ebranlard/f/SD-Loads

Various improvements to SubDyn
OpenFAST · Oct 8, 2021 · 3fd75f6 · 3fd75f6
2 parents 9cdd272 + 71e4c68
commit 3fd75f6
Show file tree

Hide file tree

Showing 24 changed files with 2,069 additions and 539 deletions.
diff --git a/.github/workflows/automated-dev-tests.yml b/.github/workflows/automated-dev-tests.yml
@@ -60,22 +60,22 @@ jobs:
         working-directory: ${{runner.workspace}}/openfast/build
         run: cmake --build . --target install -- -j ${{env.NUM_PROCS}}
 
+      - name: Run SubDyn tests
+        uses: ./.github/actions/tests-module-subdyn
       - name: Run AeroDyn tests
         uses: ./.github/actions/tests-module-aerodyn
         with:
           test-target: regression
-      - name: Run BeamDyn tests
-        uses: ./.github/actions/tests-module-beamdyn
-        with:
-          test-target: regression
       - name: Run HydroDyn tests
         uses: ./.github/actions/tests-module-hydrodyn
       - name: Run InflowWind tests
         uses: ./.github/actions/tests-module-inflowwind
         with:
           test-target: regression
-      - name: Run SubDyn tests
-        uses: ./.github/actions/tests-module-subdyn
+      - name: Run BeamDyn tests
+        uses: ./.github/actions/tests-module-beamdyn
+        with:
+          test-target: regression
       - name: Run OpenFAST tests
         # if: contains(github.event.head_commit.message, 'Action - Test All') || contains(github.event.pull_request.labels.*.name, 'Action - Test All') 
         uses: ./.github/actions/tests-gluecode-openfast
@@ -141,7 +141,7 @@ jobs:
             -DCTEST_PLOT_ERRORS:BOOL=ON \
             ${GITHUB_WORKSPACE}
 
-      - name: Build OpenFAST
+      - name: Build Drivers
         working-directory: ${{runner.workspace}}/openfast/build
         run: |
           cmake --build . --target aerodyn_driver -- -j ${{env.NUM_PROCS}}
@@ -150,22 +150,22 @@ jobs:
           cmake --build . --target inflowwind_driver -- -j ${{env.NUM_PROCS}}
           cmake --build . --target subdyn_driver -- -j ${{env.NUM_PROCS}}
 
+      - name: Run SubDyn tests
+        uses: ./.github/actions/tests-module-subdyn
       - name: Run AeroDyn tests
         uses: ./.github/actions/tests-module-aerodyn
         with:
           test-target: regression
-      - name: Run BeamDyn tests
-        uses: ./.github/actions/tests-module-beamdyn
-        with:
-          test-target: regression
       - name: Run HydroDyn tests
         uses: ./.github/actions/tests-module-hydrodyn
       - name: Run InflowWind tests
         uses: ./.github/actions/tests-module-inflowwind
         with:
           test-target: regression
-      - name: Run SubDyn tests
-        uses: ./.github/actions/tests-module-subdyn
+      - name: Run BeamDyn tests
+        uses: ./.github/actions/tests-module-beamdyn
+        with:
+          test-target: regression
 
       - name: Generate coverage report
         working-directory: ${{runner.workspace}}/openfast/build

diff --git a/docs/source/user/api_change.rst b/docs/source/user/api_change.rst
@@ -29,6 +29,40 @@ AirFoilTables                                 42\* UACutout_delta     "DEFAULT"
 
 
 
+-  SubDyn  
+
+   -  SubDyn Driver, applied loads input:
+
+============== ==== ================== =============================================================================================================================================================================
+Added 
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ Module        Line  Flag Name          Example Value
+============== ==== ================== =============================================================================================================================================================================
+SubDyn driver    21 [separator line]   ---------------------- LOADS --------------------------------------------------------------------
+SubDyn driver    22 nAppliedLoads              1    nAppliedLoads  - Number of applied loads at given nodes false   
+SubDyn driver    23 ALTableHeader      ALJointID    Fx     Fy    Fz     Mx     My     Mz   UnsteadyFile
+SubDyn driver    24 ALTableUnit           (-)       (N)    (N)   (N)   (Nm)   (Nm)   (Nm)     (-)
+SubDyn driver    25 ALTableLine1           10       0.0    0.0   0.0    0.0   0.0     0.0     ""
+============== ==== ================== =============================================================================================================================================================================
+
+
+   -  SubDyn: the lines at n+1 and n+2 below were inserted after line n.
+
+============== ==== ================== =============================================================================================================================================================================
+Added 
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ Module        Line  Flag Name          Example Value
+============== ==== ================== =============================================================================================================================================================================
+SubDyn           n  OutCOSM            Output cosine matrices with the selected output member forces (flag)
+SubDyn         n+1  OutCBModes         Output Guyan and Craig-Bampton modes {0: No output, 1: JSON output}, (flag) 
+SubDyn         n+2  OutFEMModes        Output first 30 FEM modes {0: No output, 1: JSON output} (flag)
+============== ==== ================== =============================================================================================================================================================================
+
+
+
+
+
+
 OpenFAST v2.6.0 to OpenFAST v3.0.0
 ----------------------------------
 

diff --git a/docs/source/user/subdyn/appendixF.rst b/docs/source/user/subdyn/appendixF.rst
@@ -12,8 +12,25 @@ notice, but for more information, refer to the *changelog.txt* text file
 within the official archive and the GitHub log.
 
 
+
+V1.05.00 (October 2021)
+-----------------------
+
+- Version 1.05.00 integrates with OpenFAST version 3.1+
+
+- SubDyn driver supports loads at given nodes
+
+- Outputs of Craig-Bampton/Guyan and FEM Modes to JSON format for visualization
+
+- Streamlined yaml file output, with rigid body mass matrix at different points
+
+- Bug fix for rigid assemblies.
+
+- Bug fix for mass reported in summary file
+
+
 V1.04.00 (September 2020)
-------------------------------
+-------------------------
 
 - Version 1.04.00 integrates with OpenFAST version 2.4
 

diff --git a/docs/source/user/subdyn/examples/OC4_Jacket_SD_Driver.dvr b/docs/source/user/subdyn/examples/OC4_Jacket_SD_Driver.dvr
@@ -18,4 +18,9 @@ TRUE           Echo           - Echo the input file data (flag)
 3.821E-02  1.656E-03  -4.325E-02 -1.339E-04  7.266E-02 -2.411E-03   uTPInSteady     - input displacements and rotations ( m, rads )
 1.02   2.03   5.03   0.03   0.03   0.03   uDotTPInSteady     - input translational and rotational velocities ( m/s, rads/s)
 2.02   3.03   -9.03   0.3   0.03   0.3    uDotDotTPInSteady  - input translational and rotational accelerations( m/s^2, rads/s^2)
+---------------------- LOADS --------------------------------------------------------------------
+1    nAppliedLoads  - Number of applied loads at given nodes
+ALJointID    Fx     Fy    Fz     Mx     My     Mz   UnsteadyFile
+   (-)       (N)    (N)   (N)   (Nm)   (Nm)   (Nm)     (-)
+   13        0       0     0     0       0      0      "Force_TS.csv"
 END of driver input file
diff --git a/docs/source/user/subdyn/examples/OC4_Jacket_SD_Input.dat b/docs/source/user/subdyn/examples/OC4_Jacket_SD_Input.dat
@@ -258,6 +258,8 @@ CMJointID       JMass            JMXX             JMYY             JMZZ
 ---------------------------- OUTPUT: SUMMARY & OUTFILE ------------------------------
 True             SumPrint    - Output a Summary File (flag).It contains: matrices K,M  and C-B reduced M_BB, M-BM, K_BB, K_MM(OMG^2), PHI_R, PHI_L. It can also contain COSMs if requested.
 False            OutCOSM     - Output cosine matrices with the selected output member forces (flag)
+0                OutCBModes  - Output Guyan and Craig-Bampton modes {0: No output, 1: JSON output}, (flag) 
+0                OutFEMModes - Output first 30 FEM modes {0: No output, 1: JSON output} (flag)
 False            OutAll      - [T/F] Output all members' end forces 
              1   OutSwtch    - [1/2/3] Output requested channels to: 1=<rootname>.SD.out;  2=<rootname>.out (generated by FAST);  3=both files.
 True             TabDelim    - Generate a tab-delimited output in the <rootname>.SD.out file

diff --git a/docs/source/user/subdyn/input_files.rst b/docs/source/user/subdyn/input_files.rst
@@ -42,17 +42,26 @@ for debugging errors in the driver file). The echo file has the naming
 convention of **OutRootName.dvr.ech**. **OutRootName** is specified
 in the SUBDYN section of the driver input file (see below).
 
+Environmental conditions
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 Set the gravity constant using the **Gravity** parameter. SubDyn
 expects a magnitude, so in SI units this would be set to 9.80665
 :math:`\frac{m}{s^{2}}` for standard gravity. **WtrDpth** specifies
 the water depth (depth of the seabed), based on the reference MSL, and
 must be a value greater than zero.
 
+
+SubDyn module inputs
+~~~~~~~~~~~~~~~~~~~~
+
 **SDInputFile** is the file name of the primary SubDyn input file.
 This name should be in quotations and can contain an absolute path or a
 relative path. All SubDyn-generated output files will be prefixed with
 **OutRootName**. If this parameter includes a file path, the output
-will be generated in that folder. **NSteps** specifies the number of
+will be generated in that folder. If this output is left empty,
+the driver filename is used (without the extension) is used.
+**NSteps** specifies the number of
 simulation time steps, and **TimeStep** specifies the time between
 steps. Next, the user must specify the location of the TP reference
 point **TP\_RefPoint** (in the global reference system). This is
@@ -67,6 +76,10 @@ user can set **SubRotateZ** to a prescribed angle in degrees with
 respect to the global *Z*-axis. The entire substructure will be rotated
 by that angle. (This feature is only available in stand-alone mode.)
 
+
+Input motion 
+~~~~~~~~~~~~
+
 Setting **InputsMod** = 0 sets all TP reference-point input motions to
 zero for all time steps. Setting **InputsMod** = 1 allows the user to
 provide steady (fixed) inputs for the TP motion in the STEADY INPUTS
@@ -105,6 +118,45 @@ Table 1. TP Reference Point Inputs Time-Series Data File Contents
 | 17-19           | TP reference point rotational accelerations about *X*, *Y*, and *Z*                                   | `rad/s^2`                                |
 +-----------------+-------------------------------------------------------------------------------------------------------+------------------------------------------+
 
+
+Applied loads
+~~~~~~~~~~~~~
+The next section of the input file provides options to apply loads at given joints of the structure.
+**nAppliedLoads** [-] specifies the number of applied loads listed in the subsequent table.
+The user can specify a combination of steady loads and unsteady loads (both are added together).
+The loads are in the global coordinate sytem.
+The steady loads are given as columns of the table
+(Fx, Fy, Fz, Mx, My, Mz), whereas the unsteady loads are provided in a CSV file.
+The CSV filename is provided in the last entry of the table. 
+If the filename is empty, the unsteady loads are not read.
+An example of applied loads table is given below:
+
+.. code::
+
+   ---------------------- LOADS --------------------------------------------------------------------
+   1    nAppliedLoads  - Number of applied loads at given nodes
+   ALJointID    Fx     Fy    Fz     Mx     My     Mz   UnsteadyFile
+      (-)       (N)    (N)   (N)   (Nm)   (Nm)   (Nm)     (-)
+      15       100      0     0     0       0      0      ""
+      23        0       0     0     0       0      0      "Force_TS.csv"
+
+In the above example, a steady applied force of 100N is applied at the joint with ID=15 of the structure,
+and an unsteady load is applied to joint 23. The time series of unsteady loads is a CSV file with
+7 columns (Time, Fx, Fy, Fz, Mx, My, Mz) and one line of header. The time vector needs to be increasing, 
+but does not need to be linear or cover the full range of the simulation. Interpolation is done in between
+time stamps, and the first are last values are used for times smaller and larger than the simulation time range respectively.
+An example of time series is shown below:
+
+.. code::
+
+   #Time_[s] , Fx_[N] , Fy_[N] , Fz_[N] , Mx_[Nm] , My_[Nm] , Mz_[Nm]
+   0.0       , 0.0    , 0.0    , 0.0    , 0.0     , 0.0     , 0.0
+   10.0      , 100.0  , 0.0    , 0.0    , 0.0     , 0.0     , 0.0
+   11.0      , 0.0    , 0.0    , 0.0    , 0.0     , 0.0     , 0.0
+
+
+
+
 .. _sd_main-input-file:
 
 SubDyn Primary Input File
@@ -556,11 +608,26 @@ specified in the SUBDYN section of the driver input file when running
 SubDyn in stand-alone mode, or in the FAST input file when running a
 coupled simulation. See Section 4.2 for summary file details.
 
-In this release, **OutCOSM** is ignored. In future releases,
+Currently, **OutCOSM** is ignored. In future releases,
 specifying **OutCOSM** = TRUE will cause SubDyn to include direction
 cosine matrices (undeflected) in the summary file for only those members
 requested in the list of output channels.
 
+The following two inputs specified whether mode shapes should be written
+to disk.  **OutCBModes** is a flag that controls the output of the Guyan
+and Craig-Bampton modes. Similarly, **OutFEMModes**, controls the output
+of the FEM modes (full sytem with constraints prior to the CB-reduction).
+For now, only the first 30 FEM modes are written to disk, but all CB modes
+selected by the users are written. 
+For both inputs, the following options are available: 0, no ouput, 1, outputs
+in JSON format. The JSON files contain nodes coordinates, connectivity between the nodes, 
+displacements for each modes and nodes, and frequencies for each modes.
+The reading of these files should be straightforward using Matlab or Python using a JSON format parser. 
+The files can be opened to visualize the modes using the tool viz3danim
+(see the `live version <https://ebranlard.github.io/viz3Danim/>`_
+, or its `github repository <https://github.com/ebranlard/viz3danim>`_).
+
+
 Specifying **OutAll** = TRUE causes SubDyn to output forces and
 moments at all of the joints (not internal nodes). That is, the static
 (elastic) and dynamic (inertia) components of the three forces and three

diff --git a/docs/source/user/subdyn/theory.rst b/docs/source/user/subdyn/theory.rst
@@ -2158,8 +2158,16 @@ where
 Note that the overbar is used on the input vector to denote that the
 forces apply to the interface nodes only.
 
+
+
 The outputs to HydroDyn and other modules are the deflections,
-velocities, and accelerations of the substructure:
+velocities, and accelerations of the substructure. 
+Two meshes are introduced to store these motions, noted :math:`y_2` and :math:`y_3`.
+The two meshes have different displacements for th floating case, where :math:`y_2` 
+only has the Guyan motion, whereas :math:`y_3` has the full elastic motion. 
+This distinction is not made in the following equations. The full elastic motion is assumed 
+in :math:`y_2` in this section. For more details, see section :numref:`SD_summary`.
+The output motion is: 
 
 .. math:: :label: y2
 
@@ -2203,7 +2211,10 @@ Using the expression of :math:`\ddot{q}_m` from Eq. :eq:`ddotqm`, the internal a
                 - \tilde{K}_{mm} q_m \right]
 
 
-In the floating case, the Guyan part of the motion are replaced by the analytical rigid body motion (see details in section :numref:`SD_summary`). 
+In the floating case, some subtles changes are introduced: 1) the Guyan part of the motion are replaced by the analytical rigid body motion, 
+2) the elastic displacements are set to zero to avoid a coupling issue with HydroDyn (see details in section :numref:`SD_summary`). 
+Because of 2), a third mesh was introduced, :math:`y_3`, which always contains the full elastic motion (full elastic displacements, velocities and accelerations, including the analytical tigid body motion in the floating case). 
+The third mesh is used for instance by Moordyn.
 
 
 The output equation for :math:`y_2`: can then be written as:
@@ -2557,6 +2568,7 @@ Output: nodal motions
 
 
 Note: :math:`F_L` contains the "extra moment" if user-requested with **GuyanLoadCorrection**.
+The meshes :math:`y_2` and :math:`y_3` are identical (Guyan displacements computed using :math:`Phi_R`, elastic displacements are included, together with the elastic velocities/accelerations).
 
 
 
@@ -2579,7 +2591,11 @@ Note: :math:`F_L` contains the "extra moment" if user-requested with **GuyanLoad
                 - \tilde{C}_{mm} \dot{q}_m
                 - \tilde{K}_{mm} q_m \right]
 
-where: 1) :math:`F_L` does not contain the extra moment, 2) the operators :math:`R_{g2b}` and :math:`R_{b2g}` are when GuyanLoadCorrection is True,  3) the elastic displacements were set to 0 for stability purposes (assuming that these are small) 4) the Guyan motion is computed using the exact rigid body motions. For a given node :math:`P`, located at the position :math:`r_{IP,0}` from the interface in the undisplaced configuration, the position (from the interface point), displacement, translational velocity and acceleration due to the rigid body motion are:
+where: 1) :math:`F_L` does not contain the extra moment, 
+2) the operators :math:`R_{g2b}` and :math:`R_{b2g}` are when GuyanLoadCorrection is True,  
+3) the elastic displacements are set to 0 for stability purposes (assuming that these are small) in :math:`y_2` (used by HydroDyn), but not set to 0 for :math:`y_3` (used by MoorDyn).
+4) the Guyan motion (:math:`U_{L,\text{rigid}}`) is computed using the exact rigid body motions. 
+For a given node :math:`P`, located at the position :math:`r_{IP,0}` from the interface in the undisplaced configuration, the position (from the interface point), displacement, translational velocity and acceleration due to the rigid body motion are:
 
 
 .. math::
@@ -2610,7 +2626,5 @@ Outputs to file:
 **Motions**: nodal motions written to file are in global coordinates, and for the floating case they contain the elastic motion :math:`\bar{U}_L  = U_{L,\text{rigid}} + \Phi_m q_m +  U_{L,\text{SIM}}` (whereas these elastic motions are not returned to the glue code)
 
 
-**Loads**: 
-
-Nodal loads are written to file in the element coordinate system. The procedure are the same for fixed-bottom and floating cases. 
+**Loads**: Nodal loads are written to file in the element coordinate system. The procedure are the same for fixed-bottom and floating cases.