4.8.3. Input Files

The user specifies the substructure model parameters, including its geometry and properties, via a primary SubDyn input file. When used in stand-alone mode, an additional driver input file is required. This driver file specifies inputs normally provided to SubDyn by FAST, including motions of the TP reference point.

No lines should be added or removed from the input files, except in tables where the number of rows is specified.

Additional input files containing soil-structure information (SSIfile) can be provided by the user specifying their paths in the main SubDyn input file under the section titled BASE REACTION JOINTS.

4.8.3.1. Units

SubDyn uses the SI system (kg, m, s, N). Angles are assumed to be in radians unless otherwise specified.

4.8.3.2. SubDyn Driver Input File

The driver input file is only needed for the stand-alone version of SubDyn and contains inputs that are normally set by FAST, and that are necessary to control the simulation for uncoupled models. It is possible to provide per-time-step inputs to SubDyn, even in stand-alone mode, by tying the driver file to an additional input file containing time-histories of the TP motion (displacements, velocities, and accelerations). A sample SubDyn driver input file is given in Section 4.8.10.

Users can set the Echo flag in this file to TRUE so that SubDyn_win32.exe echoes the contents of the driver input file (useful 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).

4.8.3.2.1. 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 \(\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.

4.8.3.2.2. 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. 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 locations of the transition piece (TP) reference points. These are normally set by OpenFAST through the ElastoDyn input files, and they are the so-called platform reference points given by PtfmRefxt, PtfmRefyt, and PtfmRefzt in ElastoDyn. The interface joints, defined in SubDyn’s main input file, are rigidly connected to these ElastoDyn platform reference points. When running the SubDyn standalone driver, the positions of these TP reference points must be defined in the driver input file instead, and prescribed motions can be defined for these transition pieces below. NTPs is the number of actual transition pieces, excluding the rigid-body reference point for a floating structure (see the Interface Joints section of the SubDyn’s main input file below). The next three lines are TP_RefPoint_X, TP_RefPoint_Y, and TP_RefPoint_Z, which should respectively contain the X, Y, and Z coordinates of each transition pieces in the global coordinate system. Each line should contain exactly NTPs entries. To utilize the same geometry definition within SubDyn’s main input file, while still allowing for different substructure orientations about the vertical, the 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 standalone mode.)

4.8.3.2.3. Input motion

Setting InputsMod = 0 sets all TP reference-point 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 section of the file—uTPInSteady, uDotTPInSteady, and uDotDotTPInSteady. Each line should contain 6 x NTPs inputs with the first six entries for the first transition piece, the next six entries for the second transition piece, and so on. The details of these inputs are consistent with those for InputsMod = 2 below.

Setting InputsMod = 2 allows the user to provide a time-series file whose name is specified via the InputsFile parameter. The time-series input file is a text-formatted file. This file has no header lines, NSteps rows, and each i^th row has the first column showing the time t. SubDyn driver will linearly interpolate the input time series as needed. The remainder of each row is made of white-space-separated columns of floating point values representing the necessary motion inputs as shown in Table 1. All motions are specified in the global, inertial-frame coordinate system. The roll, pitch, and yaw angles are Tait-Bryan angles following the intrinsic yaw first, pitch second, and roll last convention. The angular velocity and acceleration components are those about the global earth-fixed axes. Note that these are different from the time derivatives of the Tait-Bryan angles in general.

SubDyn does not check for physical consistency between the displacement, velocity, and acceleration time series specified for the TP reference points in the driver file and could provide unphysical results if the input motion is not self-consistent. Note that if a rigid-body reference point is set for a floating substructure in the main SubDyn input file (see the Interface Joints section of the main input file below), SubDyn will solve for the rigid-body motion internally based on the prescribed motion at the transition pieces. In this case, the results can be highly sensitive to small inconsistencies in the input motion. To obtain accurate results in this case, it is suggested that the time step in the input file should match the SubDyn solver time step exactly, so no time interpolation is required. Furthermore, the input displacement, velocity, and acceleration should contain enough digits to minimize inconsistencies due to truncation errors.

Table 1. Formatting of the Motion Time-Series Input File for TP Reference Points

Column Number	Input	Units
1	Time step value	s
2-4	TP 1 reference point translational displacements along X, Y, and Z	m
5-7	TP 1 reference point rotational displacements (Tait-Bryan roll, pitch, and yaw angles)	rad
8-10	TP 1 reference point translational velocities along X, Y, and Z	m/s
11-13	TP 1 reference point rotational velocities about X, Y, and Z	rad/s
14-16	TP 1 reference point translational accelerations along X, Y, and Z	m/s^2
17-19	TP 1 reference point rotational accelerations about X, Y, and Z	rad/s^2
20-22	TP 2 reference point translational displacements along X, Y, and Z	m
23-25	TP 2 reference point rotational displacements (Tait-Bryan roll, pitch, and yaw angles)	rad
26-28	TP 2 reference point translational velocities along X, Y, and Z	m/s
29-31	TP 2 reference point rotational velocities about X, Y, and Z	rad/s
32-34	TP 2 reference point translational accelerations along X, Y, and Z	m/s^2
35-37	TP 2 reference point rotational accelerations about X, Y, and Z	rad/s^2
…	…	…

4.8.3.2.4. 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:

---------------------- 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:

#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      , 100.0  , 0.0    , 0.0    , 0.0     , 0.0     , 0.0
0      , 0.0    , 0.0    , 0.0    , 0.0     , 0.0     , 0.0

4.8.3.3. SubDyn Primary Input File

The SubDyn input file defines the substructure geometry, integration and simulation options, finite-element parameters, and output channels. The geometry of members is defined by joint coordinates of the undisplaced substructure in the global reference system (inertial-frame coordinate system), with the origin at the intersection of the undeflected tower centerline with MSL or ground level for land-based structures. A member connects two joints; multiple members can use a common joint. The hydrodynamic and gravity loads are applied at the nodes, which are the resultant of member refinement into multiple (NDiv input) elements (nodes are located at the ends of each element), as calculated by the module. Member properties include outer diameter, thickness, material density, and Young’s and shear moduli. Member properties are specified at the joints; if properties change from one joint to the other, they will be linearly interpolated for the inner nodes. Unlike the geometric properties, the material properties are not allowed to change within a single member.

Future releases will allow for members of different cross-sections, i.e., noncircular members. For this reason, the input file has sections dedicated to the identification of direction cosines that in the future will allow the module to identify the correct orientation of noncircular members. The current release only accepts tubular (circular) members.

The file is organized into several functional sections. Each section corresponds to an aspect of the SubDyn model and substructure.

If this manual refers to an ID in a table entry, it is an integer identifier for the table entry and must be unique for a given table entry.

A sample SubDyn primary input file is given in Section 4.8.9.

The input file begins with two lines of header information, which is for the user but is not used by the software.

4.8.3.3.1. Simulation Control Parameters

Users can set the Echo flag to TRUE to have SubDyn echo the contents of the SubDyn input file (useful for debugging errors in the input file). The echo file has the naming convention of OutRootName.SD.ech. OutRootName is either specified in the SUBDYN section of the driver input file when running SubDyn standalone, or by FAST, when running a coupled simulation, from FAST’s main input file.

SDdeltaT specifies the fixed time step of the integration in seconds. The keyword ‘DEFAULT’ may be used to indicate that the module should employ the time step prescribed by the driver code (FAST/standalone driver program).

IntMethod specifies the integration algorithm to use. There are four options: 1) Runge-Kutta 4^th-order explicit (RK4); 2) Adams-Bashforth 4^th-order explicit predictor (AB4); 3) Adams-Bashforth-Moulton 4^th-order explicit predictor-corrector (ABM4); 4) Adams-Moulton implicit 2^nd-order (AM2). See Section on how to properly select this and the previous parameter values.

SttcSolve is a flag that specifies whether the static improvement method (SIM, see Section 4.8.6.6.6) shall be employed. Through this method, all (higher frequency) modes that are not considered by the C-B reduction are treated quasi-statically. This treatment helps minimize the number of retained modes needed to capture effects such as static gravity and buoyancy loads, and high-frequency loads transferred from the turbine. Recommended to set to True.

4.8.3.3.2. FEA and Craig-Bampton Parameters

FEMMod specifies one of the following options for finite-element formulation: 1) Euler-Bernoulli; 3) Timoshenko. Tapered formulations (2 and 4) have yet to be implemented and will be available in a future release.

NDiv specifies the number of elements per member. Analysis nodes are located at the ends of elements and the number of analysis nodes per member equals NDiv + 1. NDiv is applied uniformly to all members regardless of the member’s length, hence it could result in small elements in some members and long elements in other members. Increasing the number of elements per member may increase accuracy, with the trade-off of increased memory usage and computation time. We recommend using NDiv > 1 when modeling tapered members.

Nmodes sets the number of internal C-B modal DOF to retain in the C-B reduction. Nmodes = 0 corresponds to a Guyan (static) reduction. With Nmodes < 0 (equivalent to CBMod set to FALSE in previous versions), SubDyn will retain all C-B modes, leading to the same number of DOF as the full finite-element model.

JDampings specifies value(s) of damping coefficients as a percentage of critical damping for the retained C-B modes. Distinct damping coefficients for each retained mode should be listed on the same line, separated by white space. If the number of JDampings is less than the number of retained modes, the last value will be replicated for all the remaining modes. (see Section 4.8.6.6.5)

GuyanDampMod Guyan damping [0=none, 1=Rayleigh Damping, 2= user specified matrix] (see Section 4.8.6.6.5)

RayleighDamp Mass and stiffness proportional damping coefficients (\((\alpha,\beta)\) Rayleigh damping) [only if GuyanDampMod=1]

GuyanDampSize Size of the square Guyan damping matrix [only if GuyanDampMod=2]. For a fixed-bottom structure, GuyanDampSize must be set to 6 x nTP where nTP is the number of independent transition pieces, i.e., the number of unique TPID in the Interface Joints section below. For a floating structure, the first six Guyan modes are always converted to rigid-body modes. Therefore, GuyanDampSize must be set to 6 x ( nTP - 1 ) because SubDyn no longer applies damping to rigid-body modes. Note that for a floating structure modeled with a rigid-body reference point, Guyan damping is only applied to the part of interface/transition piece velocity associated with elastic deflection of the structure, i.e., the velocity of the transition piece(s) relative to rigid-body motion. For more information on the rigid-body modes and the rigid-body reference point for a floating structure, see the Interface Joints section below. The next GuyanDampSize lines following this input line should provide the coefficients of the damping matrix to be applied at the interfaces/transition pieces. Each of the following lines should contain GuyanDampSize entries to provide the full square damping matrix. (see Section 4.8.6.6.5)

For more information on these parameters and guidelines on how to set them, see Sections Section 4.8.5 and Section 4.8.6.

4.8.3.3.3. Initial Rigid-Body Position

For a floating structure modeled with a rigid-body reference point, i.e., with an interface joint assigned to TPID = 0 in the Interface Joints section below, users must specify the initial displacements of this rigid-body reference point. RBSurge, RBSway, and RBHeave are the initial displacements of the rigid-body reference point in the earth-fixed X, Y, and Z directions in meters. RBRoll, RBPitch, and RBYaw are the initial rigid-body rotation angles in degrees following the order of body-fixed yaw rotation first, pitch rotation next, and roll rotation last. Setting all entries in this section to zeros corresponds to an undisplaced structure at the start of the simulation. This section is ignored if a fixed-bottom substructure is modeled or if the floating structure does not use a rigid-body reference point with TPID = 0 abscent from the Interface Joints section below.

4.8.3.3.4. Structure Joints

The finite-element model is based on a substructure composed of joints interconnected by members. NJoints is the user-specified number of joints, and determines the number of rows in the subsequent table. Because a member connects two joints, NJoints must be greater than or equal to two. Each joint listed in the table is identified by a unique integer, JointID; each integer between one and NJoints must be present in the table, but they need not be sequential. The (X,Y,Z) coordinate of each joint is specified in the substructure (SS) coordinate system, which coincides with the global inertial-frame coordinate system via JointXss, JointYss, and JointZss, respectively. This version of SubDyn does not consider overlap when multiple members meet at a common joint, therefore, it tends to overestimate the total substructure mass. Member overlap and node offset calculations will be considered in a future release of SubDyn. The fifth column specifies the JointType (see Section 4.8.6.4):

Cantilever joints (JointType=1)
Universal joint (JointType=2)
Pin joint (JointType=3)
Ball joint (JointType=4)

The three following columns specify the vector coordinates of the direction around which rotation is free for a pin joints. The last column, JointStiff specify a value of additional stiffness to be added to the “free” rotational DOFs of Ball, Pin and Universal joints.

Note for HydroDyn coupling: modeling a fixed-bottom substructure embedded into the seabed (e.g., through piles or suction buckets) requires that the lowest member joint(s) in HydroDyn lie(s) below the water depth. Placing a joint at or above the water depth will result in static and dynamic pressure loads being applied at the joint. When SubDyn is coupled to FAST, the joints and members need not match between HydroDyn and SubDyn—FAST’s mesh-mapping utility handles transfer of motion and loads across meshes in a physically relevant manner (Sprague et al. 2014), but consistency between the joints and members in HydroDyn and SubDyn is advised.

An example of joint table is given below

3   NJoints  - Number of joints (-)
JointID JointXss JointYss  JointZss JointType JointDirX JointDirY JointDirZ JointStiff
  (-)      (m)      (m)       (m)     (-)        (-)       (-)       (-)     (Nm/rad)
  101      0.0      0.0      50.0      1         0.0       0.0       0.0       0.0
  111      0.0      0.0      10.0      2         0.0       1.0       0.0     100.0
  102      0.0      0.0     -45.0      1         0.0       0.0       0.0       0.0

4.8.3.3.5. Base Reaction Joints

SubDyn requires the user to specify the boundary joints. NReact should be set equal to the number of joints (defined earlier) at the bottom of the structure (i.e., seabed) that are fully constrained; NReact also determines the number of rows in the subsequent table. For a fixed-bottom structure, NReact must be greater than or equal to one. Each joint listed in the table is identified by a unique integer, RJointID, which must correspond to the JointID value found in the STRUCTURE JOINTS table. The flags RctTDXss, RctTDYss, RctTDZss, RctRDXss, RctRDYss, RctRDZss indicate the fixity value for the three translations (TD) and three rotations (RD) in the SS coordinate system (global inertial-frame coordinate system). One denotes fixed and zero denotes free (instead of TRUE/FALSE). SSIfile points to the relative path and filename for an SSI information file. This version of SubDyn can, in fact, handle partially restrained joints by setting one or more DOF flags to 0 and providing the appropriate stiffness and mass matrix elements for that DOF via the SSIfile. If a DOF flag is set to 1, then the node DOF is considered restrained and the associated matrix elements potentially provided in the SSIfile will be ignored. To model a floating structure, NReact should be zero with no reaction joints specified in this section.

An example of Base Reaction Joints table is given below

------------------- BASE REACTION JOINTS
  1   NReact      - Number of Joints with reaction forces
RJointID RctTDXss RctTDYss RctTDZss RctRDXss RctRDYss RctRDZss  SSIfile
  (-)     (flag)   (flag)   (flag)   (flag)   (flag)   (flag)   (string)
  61         1        1        1        1        1        1     "SSI.txt"

4.8.3.3.6. Interface Joints

SubDyn requires the user to specify the interface joints. NInterf should be set equal to the number of joints at the top of the structure, i.e., transition pieces (TP). NInterf also determines the number of rows in the subsequent table. In SubDyn, NInterf must be greater than or equal to one. With the exception of the rigid-body reference point of a floating structure with TPID = 0, these joints will be assumed to be rigidly connected to the platform reference points of ElastoDyn instances (see FAST documentation) when coupled to FAST, or to the TP reference points if SubDyn is run in stand-alone mode. Each joint listed in the table is identified by a unique integer, IJointID, which must correspond to the JointID value found in the STRUCTURE JOINTS table. Note that only cantilever joints can serve as interface joints. Furthermore, it is not allowed to assign multiple joints belonging to the same rigid-body assembly as interface joints. (This is also redundant.)

Each interface joint must also be assigned a transition piece ID or TPID. Each transition piece, identified by its unique TPID, can deflect independently from all other transition pieces, and multiple joints can be rigidly attached to each transition piece by assigning them the same TPID. Note that all joints with the same TPID will effectively be rigidly connected to each other through their rigid connection to the shared transition piece. For a fixed-bottom structure, all TPID present in the table must form a continuous sequence of integers starting from 1. For a floating structure, one and exactly one joint can be assigned to TPID = 0. This joint is a dummy transition piece that acts as the rigid-body reference point for the floating substructure. Alternatively, TPID = 0 can be omitted for a floating structure, in which case, there can only be one and exactly one transition piece with TPID = 1 (though multiple joints can be assigned to it). In this case, the single transition piece also serves as the rigid-body reference point, replicating how previous versions of SubDyn models a floating substructure. For accuracy and numerical stability, it is recommended to select a joint near the center of the floater as the rigid-body reference point to minimize elastic deflection relative to the rigid-body displacement.

The ability to include multiple independent transition pieces is added to SubDyn to enable the modeling of substructures (both fixed-bottom and floating) of multirotor systems. For a fixed-bottom structure, interface joints assigned to TPID = 1 are rigidly coupled to the platform reference point of the first ElastoDyn instance simulating the first turbine; the interface joints assigned to TPID = 2 are rigidly coupled to the platform reference point of the second ElastoDyn instance simulating the second turbine; and so on. For a floating structure, the same applies, except for the special rigid-body reference point assigned to TPID = 0. SubDyn solves the rigid-body motion of the floater about this point, which is not coupled to any ElastoDyn instances (or transition pieces defined in the SubDyn standalone driver). The motion of the rigid-body reference point defines the displaced “rigid-body” position of the floater, and any small elastic deflection is solved relative to this rigid-body configuration. This formulation is needed to accommodate potentially large rigid-body motion, while keeping the elastic defection linear. Alternatively, for a floating system with only one turbine, the rigid-body reference point with TPID = 0 can be omitted, in which case, the only transition piece allowed (with TPID = 1) serves as both the interface to ElastoDyn and as the rigid-body reference point in SubDyn as in previous versions of OpenFAST.

The flags ItfTDXss, ItfTDYss, ItfTDZss, ItfRDXss, ItfRDYss, ItfRDZss indicate the fixity value for the three translations (TD) and three rotations (RD) in the SS coordinate system (global inertial-frame coordinate system). One denotes fixed and zero denotes free (instead of TRUE/FALSE). This version of SubDyn cannot handle partially restrained joints, so all flags must be set to one. The latest formulation of SubDyn cannot be easily modified to support partially restrained joints, and these inputs will likely be removed in a future release.

An example of Interface Joints table is given below

------------------- INTERFACE JOINTS
  4   NInterf     - Number of interface joints locked to the Transition Piece (TP)
IJointID    TPID    ItfTDXss    ItfTDYss    ItfTDZss    ItfRDXss    ItfRDYss    ItfRDZss     ![Global Coordinate System]
  (-)       (-)      (flag)      (flag)      (flag)      (flag)      (flag)      (flag)
   1         0         1           1           1           1           1           1      ! Rigid-body reference point not actually coupled to any transition piece
   3         1         1           1           1           1           1           1      ! Joint attached to the 1st actual transition piece
   4         2         1           1           1           1           1           1      ! Joint attached to the 2nd actual transition piece
   5         2         1           1           1           1           1           1      ! Another joint also attached to the 2nd actual transition piece

4.8.3.3.7. Members

NMembers is the user-specified number of members and determines the number of rows in the subsequent table. Each member listed in the table is identified by a unique integer, MemberID. Each integer between one and NMembers must be present in the table, but they need not be sequential. For each member distinguished by MemberID, MJointID1 specifies the starting joint and MJointID2 specifies the ending joint, corresponding to an identifier (JointID) from the STRUCTURE JOINTS table. Likewise, MPropSetID1 corresponds to the identifier PropSetID from the MEMBER X-SECTION PROPERTY table (discussed next) for starting cross-section properties and MPropSetID2 specifies the identifier for ending cross-section properties, allowing for tapered members. Note that tapering is not allowed with user-defined generic beams (MType=4) below. Therefore, MPropSetID1 and MPropSetID2 must be the same for this beam type. The sixth column specify the member type MType. A member is one of the four following types (see Section 4.8.6.4):

Beams with circular cross sections (MType=1c or MType=1), Euler-Bernoulli (FEMMod=1) or Timoshenko (FEMMod=3)
Beams with rectangular cross sections (MType=1r), Euler-Bernoulli (FEMMod=1) or Timoshenko (FEMMod=3)
Pretension cables (MType=2)
Rigid link (MType=3)
Beam with arbitrary user-defined cross-section properties (MType=4), Euler-Bernoulli (FEMMod=1) or Timoshenko (FEMMod=3)
Spring element (MType=5)

The required input for MSpin/COSMID depends on the member type. For all beam types (MType=1c, 1r, or 4), users can specify a spin angle MSpin in degrees. This is a rotation of the beam member about its axis (pointing from the starting joint to the ending joint) following the right-hand convention. When MSpin = 0, the default SubDyn member orientation is used with the element local x_e axis parallel to the global XY plane. (If the beam is perfectly vertical, the element local x_e axis is parallel to the global X axis.) A nonzero MSpin effectively rotates the element local coordinate system about the member axis. For a beam with a rectangular cross section, Side A of the rectangular section is always parallel to the x_e axis, and setting MSpin allows the rectangular section to be reoriented as needed. Note that this convention is consistent with how HydroDyn defines rectangular members. Using the same member spin angle in SubDyn and HydroDyn ensures consistency across the two modules. With MType=4, the user-defined cross-section properties are also about the element local axes. Again, setting MSpin allows the cross section to be reoriented as needed. Finally, for beams with cylindrical cross sections, MSpin has no physical effect, but it does influence output channels based on the element local coordinate system. Setting MSpin allows these outputs to be given in a more convenient coordinate system orientation. For spring elements (MType=5), users can provide the IDs of user-defined member cosine matrices (COSMID); the current release uses SubDyn’s default direction cosine convention if COSMID is -1. Spring elements are defined between joints that are coincident in space and the direction cosine must be provided.

An example of member table is given below

   2   NMembers    - Number of frame members
MemberID   MJointID1   MJointID2   MPropSetID1   MPropSetID2   MType   MSpin/COSMID
  (-)         (-)         (-)          (-)           (-)        (-)      (deg/-)
   10         101         102           2             2          1c         0
   11         102         103           2             2          1c         0

4.8.3.3.8. Member Cross-Section Properties

Beam members in SubDyn are assumed to be straight, possibly tapered, and hollow, with circular, rectangular, or user-defined generic cross sections. These beam cross-section properties are defined in three separate tables.

Properties of circular beam cross sections needed by SubDyn are material Young’s modulus, YoungE, shear modulus, ShearG, and density, MatDens, member outer diameter, XsecD, and member wall thickness, XsecT. Note that setting XsecT to a value less than or equal to zero implies a solid section. Users will need to create an entry in the first table within this section of the input file identified by PropSetID, for each unique combination of these five properties. The member property-set table contains NPropSetsCyl rows. The member property sets are referred to by their PropSetID in the MEMBERS table above. Note, however, that although diameter and thickness will be linearly interpolated within an individual member, SubDyn will not allow material properties to change within an individual member.

Properties of rectangular beam cross sections needed by SubDyn are the same as those for circular beam cross sections, except that the section diameter XsecD is replaced with the lengths of the two sides of the rectangular section XsecSa (length of Side A) and XsecSb (length of Side B). Side A is parallel to the element local x_e axis and Side B is parallel to the element local y_e axis. Again, setting XsecT to a value less than or equal to zero implies a solid section. Note that SubDyn can automatically compute the shear areas and torsion constant for solid rectangular sections and thin-walled rectangular sections. For sections of intermediate wall thickness, the thin-walled approximation will be used, which might not be accurate. This is different from circular sections for which the shear area and torsion constant can be automatically computed by SubDyn for arbitrary wall thickness. The properties of unique rectangular beam sections are entered on separate rows of the second table of this input file section. Again, the table should have NPropSetsRec rows.

The third table in this section of the input file have NXPropSets rows and have additional entries when compared to the two previous tables, including: cross-sectional area (XsecA), cross-sectional shear area along the local principal axes x and y (XsecAsx, XsecAsy), cross-sectional area second moment of inertia about x and y (XsecJxx, XsecJyy), cross-sectional polar area moment of inertia (XsecJ0), and the cross-sectional torsion constant (XsecJt). The cross-section properties defined in this section can be used with the arbitrary beam type with MType=4 in the MEMBERS table. The cross section can be reoriented through the MSpin input in the MEMBERS section, similar to rectangular members.

4.8.3.3.9. Cable Properties

Members that are specified as pretension cables (MType=2), have their properties defined in the cable properties table. The table lists for each cable property: the property ID (PropSetID), the cable tension stiffness (EA), the material density (MatDens), the pretension force (T0), and the control channel (CtrlChannel). The control channel is only used if ServoDyn provides dedicated control signal, in which case the cable tension (given in terms of a length change \(\Delta l\)) is dynamically changed (see Section 4.8.6.4.5.3). The FEM representation of pretension cable is given in Section 4.8.6.4.5.

An example of cable properties table is given below:

-------------------------- CABLE PROPERTIES  -------------------------------------
             2   NCablePropSets   - Number of cable cable properties
PropSetID   EA     MatDens    T0    CtrlChannel
  (-)      (N)     (kg/m)    (N)      (-)
   11      210E7   7850.0    2E7       1
   10      210E7   7850.0    1E7       0

4.8.3.3.10. Rigid link Properties

Members that are specified as rigid links (MType=3), have their properties defined in the rigid link properties table. The table lists the material density (MatDens) for each rigid link property. The FEM representation of rigid links is given in Section 4.8.6.4.7.

An example of rigid link properties table is given below

----------------------- RIGID LINK PROPERTIES ------------------------------------
             1   NRigidPropSets - Number of rigid link properties
PropSetID   MatDens
  (-)       (kg/m)
   12       7850.0
    3       7000.0

4.8.3.3.11. Spring Properties

Members that are specified as spring elements (MType=5), have their properties defined in the spring element properties table. The table lists for each spring property: the property ID (PropSetID) and the stiffness coefficients (K11, K12, K13, K14, K15, K16, K22, K23, K24, K25, K26, K33, K34, K35, K36, K44, K45, K46, K55, K56, K66). The stiffness matrix is considered symmetric and includes diagonal (kii) and cross-coupling (kij) coefficients. The FEM representation of the spring element is given in Section 4.8.6.4.8.

An example of spring properties table is given below:

-------------------------- SPRING ELEMENT PROPERTIES  ----------------------------
         1   NSpringPropSets - Number of spring properties
PropSetID   k11     k12     k13     k14     k15     k16     k22     k23     k24     k25     k26     k33     k34     k35     k36     k44      k45      k46      k55      k56      k66
  (-)      (N/m)   (N/m)   (N/m)  (N/rad) (N/rad) (N/rad)  (N/m)   (N/m)  (N/rad) (N/rad) (N/rad)  (N/m)  (N/rad) (N/rad) (N/rad) (Nm/rad) (Nm/rad) (Nm/rad) (Nm/rad) (Nm/rad) (Nm/rad)
   2        2E7      0      0        0      0       0       1E12     0        0     0        0       1E12   0       0        0       1E12     0     0         1E8      0        1E12

4.8.3.3.12. Member Cosine Matrices COSM (i,j)

NCOSMs rows, one for each unique member orientation set, will need to be provided. Each row of the table will list the nine entries of the direction cosine matrices (COSM11, COSM12,…COSM33) for matrix elements. Each row is a vector in the global coordinate system for principal axes in the x (COSM11, COSM12, COSM13), y (COSM21, COSM22, COSM23) and z (COSM31, COSM32, COSM33) directions respectively. Internally, SubDyn transposes this provided matrix to make it consistent with the definition of direction cosine matrix \([ \mathbf{D_c} ]\) used in SubDyn (Eq. (4.110)). The vectors provided need to be specified with an extremely high level of precision for results to be equivalent to an internal calculation.

4.8.3.3.13. Joint Additional Concentrated Masses

SubDyn can accept NCmass lumped masses/inertias defined at the joints. The subsequent table will have NCmass rows, in which for each joint distinguished by CMJointID (corresponding to an identifier, JointID, from the STRUCTURE JOINTS table), JMass specifies the lumped mass value, and JMXX, JMYY, JMZZ specify the mass second moments of inertia with respect to the SS coordinate system (not the element system). Latest version of SubDyn accept 6 additional columns (JMXY, JMXZ, JMYZ, MCGX, MCGY, MCGZ) to specify off-diagonal terms.

The additional mass matrix added to the node is computed in the SS system as follows:

\[\begin{split}M_\text{add}= \begin{bmatrix} m & 0 & 0 & 0 & z m & -y m \\ 0 & m & 0 & -z m & 0 & x m \\ 0 & 0 & m & y m & -x m & 0 \\ 0 & -z m & y m & J_{xx} + m (y^2+z^2) & J_{xy} - m x y & J_{xz} - m x z \\ z m & 0 & -x m & J_{xy} - m x y & J_{yy} + m (x^2+z^2) & J_{yz} - m y z \\ -y m & x m & 0 & J_{xz} - m x z & J_{yz} - m y z & J_{zz} + m (x^2+y^2)\\ \end{bmatrix}\end{split}\]

with \(m\) the parameter JMass, and \(x,y,z\), the CG offsets.

An example of concentrated mass table is given below:

     2  NCmass - Number of joints with concentrated masses; (SS coord system)
CMJointID  JMass    JMXX    JMYY    JMZZ   JMXY     JMXZ   JMYZ   MCGX  MCGY MCGZ
  (-)       (kg)  (kgm^2) (kgm^2) (kgm^2) (kgm^2) (kgm^2) (kgm^2)  (m)  (m)  (m)
   1        4090     0       0       0       0        0       0      0    0    0
   3        4.2e6    0       0     3.3e9     0        0       0      0    0    0

4.8.3.3.14. Output: Summary and Outfile

In this section of the input file, the user sets flags and switches for the desired output behavior.

Specifying SumPrint = TRUE causes SubDyn to generate a summary file with name OutRootName.SD.sum*. OutRootName is either 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.

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 , or its github repository).

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.

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 moments at the end node of each member connected to a given joint are output for all joints. These outputs are included within the OutRootName.SD.out* output file in addition to those directly specified through the output channels section below.

If OutSwtch is set to one, outputs are sent to a file with the name OutRootName.SD.out*. If OutSwtch is set to two, outputs are sent to the calling program (FAST) for writing in its main output file (not available in stand-alone mode). If OutSwtch is set to three, both file outputs occur. In stand-alone mode, setting OutSwtch to two results in no output file being produced.

If TabDelim is set to TRUE and OutSwtch is set to one, the output file OutRootName.SD.out* will be tab-delimited.

With OutDec set to an integer value greater than one, the output file data rate will be decimated, and only every OutDec-th value will be written to the file. This applies only to SubDyn’s output file (OutRootName.SD.out*)—not FAST’s.

The OutFmt and OutSFmt parameters control the formatting of SubDyn’s output file for the output data and the channel headers, respectively. SubDyn currently does not check the validity of these format strings. They need to be valid Fortran format strings. OutSFmt is used for the column header and OutFmt is used for the channel data. Therefore, in order for the headers and channel data to align properly, the width specification should match. For example:

“ES11.4” OutFmt

“A11” OutSFmt.

4.8.3.3.15. Member Output List

SubDyn can output load and kinematic quantities at up to nine locations for up to nine different members, for a total of 81 possible local member output locations. NMOutputs specifies the number of members that output is requested for. The user must create a table entry for each requested member. Within a row of this table, MemberID is the ID specified in the MEMBERS table, and NOutCnt specifies how many nodes along the member will generate output. NodeCnt specifies those node numbers (a separate entry on the same line for each node) for output as an integer index from the start-joint (node 1) to the end-joint (node NDiv + 1) of the member. The outputs specified in the SDOutList section determines which quantities are actually output at these locations.

4.8.3.3.16. Output Channels- SDOutList Section

This section specifies which quantities are output by SubDyn. Enter one or more lines containing quoted strings that in turn contain one or more output parameter names. Separate output parameter names by any combination of commas, semicolons, spaces, and/or tabs. If a parameter name is prefixed with a minus sign, “-”, underscore, “_”, or the characters “m” or “M”, SubDyn will multiply the value for that channel by –1 before writing the data. The parameters are written in the order they are listed in the input file. SubDyn allows the use of multiple lines so that users can break their lists into meaningful groups and so the lines can be shorter. Comments may also be entered after the closing quote on any of the lines. Entering a line with the string “END” at the beginning of the line or at the beginning of a quoted string found at the beginning of the line will cause SubDyn to quit scanning for more lines of channel names. Modal kinematics and member-node-, base-, and interface-related kinematic and load quantities can be selected. Member-node-related data follow the organization described in Section . If SubDyn encounters an unknown/invalid channel name, it prints an error message and halts execution. Please refer to Section 4.8.11 for a complete list of possible output parameters and their names.

4.8.3.4. SSI Input File

Individual SSI files (SSIfiles) can be provided for each restrained node, therefore the maximum number of SSIfiles is NReact. In an SSIfile, up to 21 elements for the SSI mass matrix and up to 21 SSI stiffness matrix elements can be provided. The mass and stiffness elements account for both pile and soil effects. No additional damping can be provided at this point.

The order of the elements is not important, because each element value is accompanied by a string label that identifies the actual element. The stiffness matrix accepted labels are: ‘Kxx’, ‘Kxy’, ‘Kyy’, ‘Kxz’, ‘Kyz’, ‘Kzz’, ‘Kxtx’, ‘Kytx’, ‘Kztx’, ‘Ktxtx’, ‘Kxty’, ‘Kyty’,’Kzty’, ‘Ktxty’, ‘Ktyty’, ‘Kxtz’, ‘Kytz’, ‘Kztz’, ‘Ktxtz’, ‘Ktytz’, ‘Ktztz’.

If any matrix element is not provided it will be set to infinity (i.e., machine ‘huge’) by default.

For the mass matrix the accepted labels are: ‘Mxx’,’Mxy’,’Myy’,’Mxz’,’Myz’, ‘Mzz’,’Mxtx’,’Mytx’,’Mztx’, ‘Mtxtx’, ‘Mxty’, ‘Myty’, ‘Mzty’, ‘Mtxty’, ‘Mtyty’, ‘Mxtz’, ‘Mytz’, ‘Mztz’, ‘Mtxtz’, ‘Mtytz’, ‘Mtztz’. If any matrix element is not provided it will be set to 0 by default. The labels contain ‘K’ or ‘M’ to specify stiffness or mass matrix elements, and then the directions they apply to, e.g., ‘Kxy’ refers to the force along x due to a unit displacement along y; the ‘t’ refers to the rotation about one of the ‘x’,’y’, or ’z’ axes in the global coordinate system.

Units are in SI system (N/m; N/m/rad; Nm/rad, Kg, kgm, kgm2).

Note that by selecting fixities of 1 in the various DOFs of the restrained nodes, the columns and rows associated with those DOFs will be removed, therefore the associated matrix elements will be ignored.

A sample SubDyn SSI input file is given in Section 4.8.11.