MoorDyn: Coupled Pinned Bodies and bug fixes

[RyanDavies19]

Feature or improvement description
This update adds in coupled pinned bodies to MoorDyn. These objects are free in their rotational degrees of freedom while coupled in their translational degrees of freedom. The intent is to allow for a bundle of rods attached to a body to rotate about a single coupled point. In the same way coupled pinned rods are set up, the glue code still sees the object as having a full 6 DoF however moments of zero are returned by the object and the rotational kinematics inputted into MoorDyn by the glue code are ignored.

A flag to include/ignore inertial components of the forces passed to the glue code has been added as well. The flag belongs in the options list and is called “inertialF”. A value of 1 indicated include inertial components, a value of 0 indicated do not include inertial components. The default value is 0, which preserves the functionality of OpenFAST prior to this update. This flag is included because the inertial forces can cause instability due to transients in the accelerations. This issue should be resolved in OpenFAST v5 with the introduction of the tight coupling. The MoorDyn documentation will be updated accordingly shortly.

This update also removes the deprecated echo file flag and presents an updated log file as it’s replacement (the log is an existing feature, just updated now to include more information). The requires a change to the MoorDyn driver input file format to remove the echo file flag from there. The general MoorDyn input file will ignore if an echo file is called for.

The option to run MoorDyn as a standalone code with the driver has been added, when NumTurbines = -1. This ignores all tower coordinate systems and can be useful when running a system with multiple free bodies using MD as a standalone code.

Related issue, if one exists
Echo file removal and updated log file #1849

Impacted areas of the software
MoorDyn

Additional supporting information
Coupled pinned bodies were added to support the USFLOWT project’s use of buoyancy cans. Through this development process various bug were discovered and resolved including the addition of the toggle for the inclusion of inertial forces.

Test results, if applicable
Opening this PR because r-tests are not running on my computer correctly. Using GitHub actions to run tests.

@RBergua has verified this new feature with analytical solutions and comparison to other codes.

• Update the documentation version in docs/conf.py
• Update the versions in docs/source/user/api_change.rst
• Verify readthedocs builds correctly
• Create a tag in OpenFAST
• Create a merge commit in r-test and add a corresponding tag
• Compile executables for Windows builds
  • FAST_SFunc.mexw64
  • OpenFAST-Simulink_x64.dll
  • openfast_x64.exe
  • DISCON.dll
    -->

[andrew-platt]

@mattEhall, do you want to take a quick look at this?

[mattEhall]

Generally looks good to me. These are great additions. @RyanDavies19, what's the reason for moving some log file outputs from other modules into the init function?

[andrew-platt]

Requesting changes to the use of print* statements.

I also need to think about the linearization impacts of the p%dx changes.

[RyanDavies19]

Generally looks good to me. These are great additions. @RyanDavies19, what's the reason for moving some log file outputs from other modules into the init function?

@mattEhall it seemed to me that it simplified the code, rather than having the log being written to in many different files it all happens in in the main MoorDyn file. Happy to change if back though if you feel otherwise.

[andrew-platt]

Thanks @bjonkman for reviewing!

[jjonkman]

I'm not sure I understand the comment about the inertial flag and tight coupling. I was not aware of problems with the acceleration-load feedback in the existing MoorDyn coupling to OpenFAST, which I figured was because the mass of the small portion of the cables attached to the floater is much smaller than the floater mass itself. Are there existing coupling problems associated with MoorDyn within OpenFAST that I'm not aware of?

The tight coupling implementation is ongoing, but at this time, we were not planning to tightly couple MoorDyn within OpenFAST; rather, MoorDyn was going to remain loosely coupled with explicit loose coupling (along with many other OpenFAST modules). Tight coupling is focused on OpenFAST modules BeamDyn, ElastoDyn, and SubDyn. In tight coupling, implicit loose coupling will be used for OpenFAST modules ExtPtfm, HydroDyn, Orca, Simplified ElastoDyn, and AeroDyn for MHK. Explicit loose coupling will be used for AeroDyn (for wind turbines), AeroDisk, ExtInflow, ExtLd, FEAMooring, IceDyn, IceFloe, InflowWind, MAP++, MoorDyn, SoilDyn, ServoDyn, and SeaState. If there are coupling problems associated with MoorDyn, we may need to change this.

[RBergua]

@jjonkman: I have experienced quite some issues with the rods to model cans for the USFLOWT project. MoorDyn tends to crash even at the beginning of the simulation when it has to return bending moments (e.g., using Coupled attachment in MoorDyn). See below for reference:

This "extreme pitch moment" is quite surprising to me because at t = 0 s the platform, as well as the cans, don't have a platform pitch or roll angle yet (they are straight upwards). Accordingly, there shouldn't be any bending moments associated. So, I'm not sure this is related to the tight coupling. To me, it seems some kind of limitation of the glue-code to transfer bending moments between MoorDyn and EdlastoDyn or SubDyn. I may be wrong...

For reference, even the CoupledPinned attachment sometimes return similar messages when the angles rotated are significant. Note that this CoupledPinned attachment is equivalent to a ball joint (i.e., the 3 rotational DOFs are free), so it shouldn't transfer any moments.

I have also observed an unexpected behavior when using these cans that I'm trying to document at the moment... Maybe there is bug in the code.

[RyanDavies19]

@jjonkman: I have experienced quite some issues with the rods to model cans for the USFLOWT project. MoorDyn tends to crash even at the beginning of the simulation when it has to return bending moments (e.g., using Coupled attachment in MoorDyn). See below for reference:

This "extreme pitch moment" is quite surprising to me because at t = 0 s the platform, as well as the cans, don't have a platform pitch or roll angle yet (they are straight upwards). Accordingly, there shouldn't be any bending moments associated. So, I'm not sure this is related to the tight coupling. To me, it seems some kind of limitation of the glue-code to transfer bending moments between MoorDyn and EdlastoDyn or SubDyn. I may be wrong...

For reference, even the CoupledPinned attachment sometimes return similar messages when the angles rotated are significant. Note that this CoupledPinned attachment is equivalent to a ball joint (i.e., the 3 rotational DOFs are free), so it shouldn't transfer any moments.

I have also observed an unexpected behavior when using these cans that I'm trying to document at the moment... Maybe there is bug in the code.

@jjonkman I'll add that the acceleration-load feedback issues only arise with the 6 DOF coupled objects in MoorDyn, rods and bodies. We think that they have larger masses, the transients in acceleration cause large non-physical forces on the objects and cause OpenFAST to crash. Prior to this PR, the inertial responses of these objects had just been set to 0 as a workaround because they typically were small. With the USFLOWT design that's not the case and it was causing issues. @RBergua and I thought this flag was the best option because it kept the previous OpenFAST functionality but allowed for users to include the inertial terms if they didn't cause problems.

[andrew-platt]

@jjonkman, I meant to bring this up in our tight coupling meeting, but forgot. This does suggest that we may need to include MoorDyn in the tight coupling scheme, at least for models that include large buoyancy cans where the added mass effect could be large.

[andrew-platt]

@RBergua, is it possible to reduce the numerical instability using correction steps, or does it still blow up when the moments are enabled?

I'm in favor of the short term solution with the option to disable the moments and merging the code.

[RBergua]

I tried with several correction iterations, but couldn't make it work @andrew-platt. Often, the solver blows up at the first time step.