From 7064d7d4c8b197699f31d41694dccc1dd1047bf2 Mon Sep 17 00:00:00 2001 From: RyanDavies19 Date: Tue, 18 Jun 2024 15:03:48 -0600 Subject: [PATCH 1/2] Docs update: typos, more references, and updated FF file --- README.md | 6 ++- docs/compiling.rst | 4 +- docs/conf.py | 4 +- docs/drivers.rst | 6 +-- docs/index.rst | 4 +- docs/inputs.rst | 107 +++++++++++++++++++++++++++------------ docs/theory.rst | 23 +++++++-- docs/waterkinematics.rst | 10 ++-- source/MoorDyn2.cpp | 4 +- 9 files changed, 117 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 09dabb86..e609410f 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ MoorDyn v2 ========== +**This repository is for MoorDyn-C.** + MoorDyn is a lumped-mass model for simulating the dynamics of mooring systems connected to floating offshore structures. As of 2022 it is available under the BSD 3-Clause license. Read the docs here: [moordyn.readthedocs.io](https://moordyn.readthedocs.io/en/latest/) -It accounts for internal axial stiffness and damping forces, weight and buoyancy forces, hydrodynamic forces from Morison's equation (assuming calm water so far), and vertical spring-damper forces from contact with the seabed. MoorDyn's input file format is based on that of [MAP](https://www.nrel.gov/wind/nwtc/map-plus-plus.html). The model supports arbitrary line interconnections, clump weights and floats, different line properties, and six degree of freedom rods. +It accounts for internal axial stiffness and damping forces, weight and buoyancy forces, hydrodynamic forces from Morison's equation (assuming calm water so far), and vertical spring-damper forces from contact with the seabed. MoorDyn's input file format is based on that of [MAP](https://www.nrel.gov/wind/nwtc/map-plus-plus.html). The model supports arbitrary line interconnections, clump weights and floats, different line properties, and six degree of freedom rods and bodies. -MoorDyn is implemented both in Fortran and in C++. The Fortran version of MoorDyn (MoorDyn-F) is a core module in [OpenFAST](https://github.com/OpenFAST/openfast) and can be used as part of an OpenFAST or FAST.Farm simulation, or used in a standalone form. The C++ version of MoorDyn (MoorDyn-C) is more adaptable to different use cases and couplings. It can be compiled as a dynamically-linked library or wrapped for use in Python (as a module), Fortran, or Matlab. It features simpler functions for easy coupling with models or scripts coded in C/C++, Fortran, Matlab/Simulink, etc., including a coupling with [WEC-Sim](https://wec-sim.github.io/WEC-Sim/master/index.html). +MoorDyn is implemented both in Fortran and in C++. The Fortran version of MoorDyn (MoorDyn-F) is a core module in [OpenFAST](https://github.com/OpenFAST/openfast) and can be used as part of an OpenFAST or FAST.Farm simulation, or used in a standalone form. The C++ version of MoorDyn (MoorDyn-C) is more adaptable to different use cases and couplings. It can be compiled as a dynamically-linked library or wrapped for use in Python (as a module), Fortran, or Matlab. It features simpler functions for easy coupling with models or scripts coded in C/C++, Fortran, Matlab/Simulink, etc., including a coupling with [WEC-Sim](https://wec-sim.github.io/WEC-Sim/master/index.html). Users should take care to ensure their input file format matches the respective version of MoorDyn they are trying to use. Details on the input file differences can be found in the [documentation](https://moordyn.readthedocs.io/en/latest/inputs.html). Both forms of MoorDyn feature the same underlying mooring model, use the same input and output conventions, and are being updated and improved in parallel. They follow the same version numbering, with a "C" or "F" suffix for differentiation. diff --git a/docs/compiling.rst b/docs/compiling.rst index a42e683f..b1a3e82b 100644 --- a/docs/compiling.rst +++ b/docs/compiling.rst @@ -104,7 +104,7 @@ Windows ^^^^^^^ This section will show how to install Eigen3 and MoorDyn in the default folders -(C:\Program Files (x86)\Eigen3 and C:\Program Files (x86)\Moordyn) using CMake +(``C:\Program Files (x86)\Eigen3`` and ``C:\Program Files (x86)\Moordyn``) using CMake This documentation assumes that you are building in an MSYS2 build environment. Install the following necessary tools: @@ -159,7 +159,7 @@ the Git window select "Clone Existing Repository". The Git GUI to clone repositories -As a default, MoorDyn uses the Egien package that is internal in the source code. +As a default, MoorDyn uses the Eigen package that is internal in the source code. If you would like to use an external copy of Eigen, please follow the instructions in the :ref:`installing with external eigen ` note at this point. diff --git a/docs/conf.py b/docs/conf.py index 74f85d92..e304f416 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,11 +43,11 @@ # -- Project information ----------------------------------------------------- project = 'MoorDyn' -copyright = '2023, National Renewable Energy Laboratory' +copyright = '2024, National Renewable Energy Laboratory' author = 'Matt Hall' # The full version, including alpha/beta/rc tags -release = '2.2.2' +release = '2.3.1' # TODO: can we automate this? # -- General configuration --------------------------------------------------- diff --git a/docs/drivers.rst b/docs/drivers.rst index 434b5fb4..89bc8d1d 100644 --- a/docs/drivers.rst +++ b/docs/drivers.rst @@ -799,9 +799,9 @@ Originally, it was coupled to a modified form of FAST v7. WEC-Sim ^^^^^^^ -WEC-Sim is currently coupled with MoorDyn v1. Support for the current version of -MoorDyn-C v2, is in the process of being developed. The WEC-Sim source code can be found -`here `_. +WEC-Sim is coupled with MoorDyn-C v2 as of Spring 2024 with `WEC-Sim PR #1212 `_. +The original coupling was with MoorDyn v1 and the the publication can be found in the +:ref:`theory section `. The WEC-Sim source code can be found `here `_. DualSPHysics ^^^^^^^^^^^^ diff --git a/docs/index.rst b/docs/index.rst index b3a97bfa..17add039 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,7 +33,9 @@ The pages on this site provide information about :ref:`compiling `, MoorDyn's :ref:`input files `, how to :ref:`drive a simulation `, how MoorDyn is :ref:`structured `, and its :ref:`theory `. MoorDyn is available in multiple forms, -which are outlined below. +which are outlined below. The *latest* version of the docs is kept up-to-date with the +dev branches of both MoorDyn-C and MoorDyn-F. The *master* version of the docs is up to date with +the `latest MoorDyn-C release `_. Note: This documentation is meant for users, a `Doxygen documentation <./doxygen/html/index.html>`_ has been deployed for the diff --git a/docs/inputs.rst b/docs/inputs.rst index 427570f5..f4df85e3 100644 --- a/docs/inputs.rst +++ b/docs/inputs.rst @@ -230,14 +230,15 @@ changes from V1. Most helpfully, this new format is identical between C++ and FORTRAN versions of MoorDyn, and it is designed to support future capability enhancements without -requiring changes. +requiring format changes. This file is divided into sections, some of which are optional. Each section is identified (and detected) by a header line consisting of a key phrase (e.g. Line Types) surrounded by dashes. While a couple sections are optional, the order of the sections cannot be changed. The exact whitespace and alignment of the lines of the file is not important, as long as values are separated by at least one space. However, every column must have -a value. +a value. MoorDyn only reads the values of each column, not the column headers or units. The column +identifiers and units can be changed by the user but should use similar names to retain readability. To successfully run a simulation, MoorDyn requires at least one line. If you are aiming to simulate a system with no lines, the best approach is to create a short taut vertical line stretched between @@ -397,7 +398,7 @@ outputs are wanted. Eight output properties are currently possible: - p – node positions - v – node velocities - - U – wave velocities at each node + - U – wave/current velocities at each node - D – hydrodynamic drag force at each node - t – tension force at each segment - c – internal damping force at each segment @@ -471,7 +472,7 @@ outputs are wanted. Eight output properties are currently possible: - p – node positions - v – node velocities - - U – wave velocities at each node + - U – wave/current velocities at each node - D – hydrodynamic drag force at each node - t – tension force at each segment - c – internal damping force at each segment @@ -492,7 +493,7 @@ multiple failures for a given point, but duplicate failure configurations will b If two lines attached to a point are listed to fail (failure 1 for example), then after the failure the lines will remain attached to each other by a free point. In this multi line case, if any line reaches the tension threshold then the failure will be triggered. The theory behind failures can be -found :ref:`here `. +found :ref:`here `. .. code-block:: none @@ -506,8 +507,8 @@ found :ref:`here `. Control (MoorDyn-F only) ^^^^^^^^^^^^^^^^^^^^^^^^ -This section (optional) is only available for MoorDyn-F and describes the control channels of the -system. +This section (optional) is only available for MoorDyn-F and describes which lines are assigned to +which control channel in the ServoDyn input file. .. code-block:: none @@ -517,6 +518,11 @@ system. 1 1,2,3,4 2 5 +In the example above channel 1 is used to control lines 1-4 and channel 2 is used to control line 5. +These channel numbers must correspond to control channels in the ServoDyn input file. The ServoDyn +summary file (enabled with ``SumPrint`` option) will contain a list of all cable control channels in +use and what they are assigned to. + Options ^^^^^^^ @@ -525,6 +531,7 @@ This section (required) describes the simulation options .. code-block:: none ---------------------- OPTIONS ----------------------------------------- + 1 writeLog Write log file 0.002 dtM time step to use in mooring integration (s) 3000000 kbot bottom stiffness (Pa/m) 300000 cbot bottom damping (Pa-s/m) @@ -532,10 +539,14 @@ This section (required) describes the simulation options 10 TmaxIC max time for ic gen (s) 0.001 threshIC threshold for IC convergence (-) -Any of these lines can be omitted, in which case default values will be used (shown in -parentheses). Default value swith a C or an F indicates which version has that as the default. -As such, they are all optional settings, although some of them (such as time step -size) often needs to be set by the user for proper operation. The list of possible options is: +The options list differs from the other sections in that it uses a value + key approach. +MoorDyn reads in the value, and then assigns it to the corresponding key. This means the +order of the options list does not matter, however any options listed above the ``writeLog`` +flag will not be included in the log file. Any of these option lines can be omitted, in which +case default values will be used (shown in parentheses). Default values with a C or a F +indicate which version has that as the default. As such, they are all optional settings, although +some of them (such as time step size) often needs to be set by the user for proper operation. +The list of possible options is: - writeLog (0 C, -1 F): If >0 a log file is written recording information. The bigger the number the more verbose. Please, be mindful that big values would critically reduce the performance! @@ -633,7 +644,6 @@ shown below) for MoorDyn to know when to stop reading inputs. ANCHTEN1 ANCHTEN2 ANCHTEN3 - END ------------------------- need this line ------------------------------------- The avaible output flags are decribed in the table below: @@ -870,12 +880,18 @@ data. Details on this format can be found in the :ref:`water kinematics section MoorDyn with FAST.Farm - Inputs ------------------------------- -In FAST.Farm, a new ability to use MoorDyn at the array level to simulate shared mooring systems -has been developed. Until the main branch of OpenFAST, the FAST.Farm capability, and the MoorDyn-C -capability are merged, the shared moorings capability in FAST.Farm uses the MoorDyn v1 input file -format, with a small adjustment to reference attachments to multiple turbines. +MoorDyn is available at an array level in FAST.Farm using the MoorDyn-F v2 input file format. +A nice description of FAST.Farm is found on the OpenFAST repository README: + +"FAST.Farm extends the capabilities of OpenFAST to provide physics-based engineering simulation +of multi-turbine land-based, fixed-bottom offshore, and floating offshore wind farms. With +FAST.Farm, you can simulate each wind turbine in the farm with an OpenFAST model and capture +the relevant physics for prediction of wind farm power performance and structural loads, including +wind farm-wide ambient wind, super controller, and wake advection, meandering, and merging. +FAST.Farm maintains computational efficiency through parallelization to enable loads analysis for +predicting the ultimate and fatigue loads of each wind turbine in the farm." -https://github.com/mattEhall/openfast/tree/f/fast-farm +FAST.Farm can be obtained from the `OpenFAST repository `_. General Organization ^^^^^^^^^^^^^^^^^^^^ @@ -885,46 +901,71 @@ FAST.Farm. This ability can be used for any non-shared mooring lines in all case simulation of shared mooring lines, which are coupled with multiple turbines, an additional farm-level MoorDyn instance has been added. This MoorDyn instance is not associated with any turbine but instead is called at a higher level by FAST.Farm. Attachments to different turbines -within this farm-level MoorDyn instance are handled by specifying "TurbineN" as the type for any -points that are attached to a turbine, where "N" is the specific turbine number as listed in the -FAST.Farm input file. +within this farm-level MoorDyn instance are handled by specifying "TurbineN" as the attachment for any +points/bodies/rods that are attached to a turbine, where "N" is the specific turbine number as listed in the +FAST.Farm input file. Pinned bodies and rods are not yet supported in FAST.Farm. MoorDyn Input File ^^^^^^^^^^^^^^^^^^ The following input file excerpt shows how points can be specified as attached to specific turbines -(turbines 3 and 4 in this example). When a point has "TurbineN" as its type, it acts similarly to a -"Vessel" type, where the X/Y/Z inputs specify the relative location of the fairlead on the platform. -In the farm-level MoorDyn input file, "Vessel" point types cannot be used because it is ambiguous +(turbines 3 and 4 in this example). When a point has "TurbineN" as its attachment, it acts similarly to a +"Coupled" attachment, where the X/Y/Z inputs specify the relative location of the fairlead on the platform. +In the farm-level MoorDyn input file, "Coupled" point types cannot be used because it is ambiguous which turbine they attach to. .. code-block:: none - :emphasize-lines: 5,6,12 + :emphasize-lines: 5,6,11 ----------------------- POINTS ---------------------------------------------- - Node Type X Y Z M V CdA CA + Node Attachment X Y Z M V CdA CA (-) (-) (m) (m) (m) (kg) (m^3) (m^2) (-) 1 Turbine3 10.0 0 -10.00 0 0 0 0 3 Turbine4 -10.0 0 -10.00 0 0 0 0 2 Fixed 267.0 80 -70.00 0 0 0 0 -------------------------- LINE PROPERTIES ---------------------------------- - 2 NLines - the number of lines - Line LineType UnstrLen NumSegs NodeA NodeB Flags/Outputs - (-) (-) (m) (-) (-) (-) (-) - 1 sharedchain 300.0 20 1 2 p - 2 anchorchain 300.0 20 1 3 p + ID LineType AttachA AttachB UnstrLen NumSegs LineOutputs + (-) (-) (-) (-) (m) (-) (-) + 1 sharedchain 1 2 300.0 20 p + 2 anchorchain 1 3 300.0 20 p In this example, Line 1 is a shared mooring line and Line 2 is an anchored mooring line that has a fairlead point in common with the shared line. Individual mooring systems can be modeled in the farm-level MoorDyn instance as well. +The same approach is used for bodies and rods, where the attachment is defined as "TurbineN". +The body and rod positions and rotations are defined relative to the turbines position and rotation. +The following code snippet shows rods using the turbine convention. + +.. code-block:: none + :emphasize-lines: 12,13,17 + + ---------------------- LINE TYPES -------------------------------------------------- + TypeName Diam Mass/m EA BA/-zeta EI Cd Ca CdAx CaAx + (name) (m) (kg/m) (N) (N-s/-) (N-m^2) (-) (-) (-) (-) + 0 0.1410 35.78 2.030e+08 -1.000e+00 8.410e+03 1.200 1.000 0.20 0.00 + --------------------- ROD TYPES ----------------------------------------------------- + TypeName Diam Mass/m Cd Ca CdEnd CaEnd + (name) (m) (kg/m) (-) (-) (-) (-) + connector 0.2000 0.00 0.000 0.000 0.000 0.000 + ---------------------- RODS --------------------------------------------------------- + ID RodType Attachment Xa Ya Za Xb Yb Zb NumSegs RodOutputs + (#) (name) (#/key) (m) (m) (m) (m) (m) (m) (-) (-) + 1 connector Turbine1 -0.62 0.00 -13.22 0.62 0.00 -14.78 0 - + 2 connector Free -947.81 0.00 -150.60 -945.82 0.00 -150.75 0 - + ---------------------- LINES -------------------------------------------------------- + ID LineType AttachA AttachB UnstrLen NumSegs LineOutputs + (#) (name) (#) (#) (m) (-) (-) + 1 0 R1B R2A 299.429 10 pt + +In this example 0-length rods are used as bend-stiffeners for a suspended cable attached to +Turbine1. FAST.Farm Input File ^^^^^^^^^^^^^^^^^^^^ -In the branch of FAST.Farm that supports shared mooring capabilities, several additional lines have -been added to the FAST.Farm primary input file. These are highlighted in the example input file -excerpt below: +Several additional lines have been added to the FAST.Farm primary input file. These are highlighted +in the example input file excerpt below: .. code-block:: none :emphasize-lines: 9,10,13,14,15 diff --git a/docs/theory.rst b/docs/theory.rst index e5fef507..2a4b038d 100644 --- a/docs/theory.rst +++ b/docs/theory.rst @@ -104,13 +104,30 @@ Preliminary comparison of seabed friction formulations: `K. Devries, M. Hall, “Comparison of Seabed Friction Formulations in a LumpedMass Mooring Model”. in Proceedings of the ASME International Offshore Wind Technical Conference, San Francisco, California, Nov. 2018. `_ -Overview of MoorDyn v2: +Overview of MoorDyn v2 (bodies, rods, and line failures): - https://www.nrel.gov/docs/fy20osti/76555.pdf + `Hall, Matthew, “MoorDyn V2: New Capabilities in Mooring System Components and Load Cases.” In Proceedings of the ASME 2020 39th International + Conference on Ocean, Offshore and Arctic Engineering. virtual conference, 2020. `_ + +Seabed friction and bathymetry approach used in v2: + + `Housner, Stein, Ericka Lozon, Bruce Martin, Dorian Brefort, and Matthew Hall, “Seabed Bathymetry and Friction Modeling in MoorDyn.” Journal of + Physics: Conference Series 2362, no. 1, Nov 2022: 012018. `_ Implementation of bending stiffness modeling for power cables: - https://www.nrel.gov/docs/fy21osti/76968.pdf + `Hall, Matthew, Senu Sirnivas, and Yi-Hsiang Yu, “Implementation and Verification of Cable Bending Stiffness in MoorDyn.” In ASME 2021 3rd International Offshore Wind + Technical Conference, V001T01A011. Virtual, Online: American Society of Mechanical Engineers, 2021. `_ + +Non-linear line stiffness: + + `Lozon, Ericka, Matthew Hall, Paul McEvoy, Seojin Kim, and Bradley Ling, “Design and Analysis of a Floating-Wind Shallow-Water Mooring System + Featuring Polymer Springs.” American Society of Mechanical Engineers Digital Collection, 2022. `_ + +Viscoelastic approach for non-linear rope behavior: + + `Hall, Matthew, Brian Duong, and Ericka Lozon, “Streamlined Loads Analysis of Floating Wind Turbines With Fiber Rope Mooring Lines.” In ASME 2023 + 5th International Offshore Wind Technical Conference, V001T01A029. Exeter, UK: American Society of Mechanical Engineers, 2023. `_ The Fortran version of MoorDyn is available as a module inside of OpenFAST: diff --git a/docs/waterkinematics.rst b/docs/waterkinematics.rst index d8a5174e..fd6203dd 100644 --- a/docs/waterkinematics.rst +++ b/docs/waterkinematics.rst @@ -36,6 +36,7 @@ Below is an example program demonstrating basic usage of external wave kinematic .. code-block:: c #include + #include using namespace std; void @@ -50,9 +51,12 @@ Below is an example program demonstrating basic usage of external wave kinematic du[1] = 0.0; // y acceleration du[2] = 0.0; // z acceleration } - void main() + bool main() { - MoorDyn system = MoorDyn_Create(input_file); + + int err; + + MoorDyn system = MoorDyn_Create("Mooring/lines.txt"); if (!system) { cerr << "Failure Creating the Mooring system" << endl; return false; @@ -116,7 +120,7 @@ Below is an example program demonstrating basic usage of external wave kinematic return false; } - err = MoorDyn_Step(system, NULl, NULL, NULL, &t, &dt); + err = MoorDyn_Step(system, NULL, NULL, NULL, &t, &dt); if (err != MOORDYN_SUCCESS) { MoorDyn_Close(system); cerr << "Failure during the mooring step: " << err << endl; diff --git a/source/MoorDyn2.cpp b/source/MoorDyn2.cpp index f64a0a59..115b6fe8 100644 --- a/source/MoorDyn2.cpp +++ b/source/MoorDyn2.cpp @@ -108,11 +108,11 @@ moordyn::MoorDyn::MoorDyn(const char* infilename, int log_level) _basepath = _filepath.substr(0, lastSlash + 1); } - LOGMSG << "\n Running MoorDyn (v2.0.0, 2023-09-18)" << endl + LOGMSG << "\n Running MoorDyn (v2.3.1, 2024-5-24)" << endl // TODO: can we automate this? << " MoorDyn v2 has significant ongoing input file changes " "from v1." << endl - << " Copyright: (C) 2023 National Renewable Energy Laboratory, " + << " Copyright: (C) 2024 National Renewable Energy Laboratory, " "(C) 2014-2019 Matt Hall" << endl << " This program is released under the BSD 3-Clause license." From 2f4bd7358de9557a23a7a739bb89bb8f1a5b5a50 Mon Sep 17 00:00:00 2001 From: RyanDavies19 Date: Fri, 21 Jun 2024 08:53:37 -0600 Subject: [PATCH 2/2] More FF instructions --- docs/inputs.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/inputs.rst b/docs/inputs.rst index f4df85e3..6600bd74 100644 --- a/docs/inputs.rst +++ b/docs/inputs.rst @@ -910,9 +910,10 @@ MoorDyn Input File The following input file excerpt shows how points can be specified as attached to specific turbines (turbines 3 and 4 in this example). When a point has "TurbineN" as its attachment, it acts similarly to a -"Coupled" attachment, where the X/Y/Z inputs specify the relative location of the fairlead on the platform. -In the farm-level MoorDyn input file, "Coupled" point types cannot be used because it is ambiguous -which turbine they attach to. +"BodyN" attachment, where the X/Y/Z inputs specify the relative location of the fairlead on the platform. +ex. For a turbine located at (200, 0, 0), a vertical line attached to it's center would have +a fixed point at end A at (200, 0, 0) and a turbineN point at (0, 0, 0). In the farm-level MoorDyn input +file, "Coupled" point types cannot be used because it is ambiguous which turbine they attach to. .. code-block:: none :emphasize-lines: 5,6,11