Enable WEC-Sim to use MoorDyn v2 capabilities

[jtgrasb]

This PR expands upon #1134 to enable WEC-Sim's use of MoorDyn's new capabilities, notably the ability to handle mooring lines between multiple dynamic bodies. This PR includes the following changes:

• Mooring Library
  • Changed the MoorDyn block to a MoorDynConnection block, which has two connections to detect the relative motion between two bodies/frames, send the displacement and velocity to the MoorDynCaller block, and receive back the forces calculates by MoorDyn
  • Added a MoorDynCaller block that programmatically receives the displacement and velocity from the MoorDynConnection block(s) and calls MoorDyn to calculate the forces.
  • There can only be one MoorDynCaller block, but it allows for multiple connection blocks to be used.
• Updated the mooring class to initialize and close MoorDyn instead of doing it within the Simulink block.
• Updated documentation to reflect the new process for using MoorDyn.
  • I added a note to indicate that the MoorDyn webinar is out of date, but need to consider updating this in the future.

A few other notes about the implementation:

• MoorDyn handles the kinematics between the body's center of gravity and the mooring connection location (based on lines.txt). Thus, as I understand it, the mooring(i).location should always be [0, 0, 0] so that the motion passed into MoorDyn is the exact motion of the body.
• The initial displacement factors into the orientation of the mooring connection and is added to the displacement before sending to MoorDyn. Any initial body displacement should also be applied to the moordyn connection.
• Updates to the MoorDyn examples in WEC-Sim Applications are in PR#57

[dav-og]

minor thing:

MoorDynCaller layout seems to be messed up?

[jtgrasb]

The MoorDynCaller block programatically adds and removes the From and Goto blocks according to the number of MoorDyn connections specified. I tried to arrange the model automatically but it seemed to give errors when doing it from the mask. I could also change the location of these placements, but it does not affect the functionality so I didn't feel it was worth it.

[jtgrasb]

Hey @dav-og, do you have any other comments or suggestions? Or is it ready to be merged?

[dav-og]

Hi @jtgrasb it seems to be running fine, I just have a couple of points:

1. Do you have a comparison between v2 and v1 to verify that the results aren't being affected?
2. Would this update be backwards-compatible with MoorDyn v1?

[RyanDavies19]

Hi @jtgrasb it seems to be running fine, I just have a couple of points:

1. Do you have a comparison between v2 and v1 to verify that the results aren't being affected?
2. Would this update be backwards-compatible with MoorDyn v1?

@dav-og For your second question, no this is not backwards compatible with MD V1. Function names have changes, as well as input file structure, and I/O between MoorDyn and the calling script (WECSim in this case). However MD V1 is no longer in development and V2 has improved a lot of the behavior of the code, and from the MoorDyn side we encourage all users to use the most up-to-date version of v2.

[dav-og]

@RyanDavies19 cheers, I assumed so from MoorDyn side, but wasn't sure if on the WEC-Sim side we'd be able to do if v1 -> use old approach, elif v2 -> use new approach ... might make life easier for someone with a complex mooring model already implemented with v1, but as you say - people should really just be upgrading to v2 👍

[RyanDavies19]

@dav-og Thats a good point, hopefully with the MD docs site it should be relatively simple (but potentially tedious) to convert from a v1 input file to a v2 input file. The format of both the v1 and the v2 input files are in there.

[RyanDavies19]

Noting that @jtgrasb and I discussed the pending reviews above and they can be closed

[jtgrasb]

@dav-og Thanks for the review.

1. The zip file for comparison can be found on PR#57 of the Applications Repo. Plotting the results for comparison yields the following figure. The notable difference is due to the fact that MD v2 has a more effective initialization. Both results converge to very similar dynamics after about 20 seconds, with a slight offset due to the updated moordyn input file (lines.txt).
   

2. The updates are not backwards compatible, as Ryan said. The main reason for this is because the MoorDyn function names have changed. For example, when WEC-Sim previously called MoorDyn, it would use LinesInit() but now must use MoorDynInit(). As far as I can tell, there is no way to make the changes backwards compatible while still updating to MD v2.

[dav-og]

Looks like there is a persistent offset in the v2 results, but it probably makes sense to trust the v2 results more.

@RyanDavies19 is there a verification reference for v2 that we can point to in our docs?

[RyanDavies19]

@dav-og for now point to here: https://moordyn.readthedocs.io/en/latest/theory.html#id2

I am working on adding more v2 theory papers to that site. In general, for the past couple years work using MoorDyn-C and/or MoorDyn-F in OpenFAST have been using MoorDyn v2.

Here are some other references I will add to the MD docs site:

https://www.nrel.gov/docs/fy23osti/83342.pdf
https://www.nrel.gov/docs/fy24osti/87481.pdf
https://www.nrel.gov/docs/fy23osti/82033.pdf

[jtgrasb]

Thanks @RyanDavies19 and @dav-og. The documentation added here points to the updated MoorDyn Documentation.
@dav-og Do you have any further review comments or is this PR and the WEC-Sim Applications PR ready for merge?

[dav-og]

ready to merge 👍