Merge pull request #325 from RyanDavies19/bugfixes

Improved Input File Handling and Improved Documentation

Author: RyanDavies19

README.md

@@ -7,6 +7,7 @@ MoorDyn is a lumped-mass model for simulating the dynamics of mooring systems co
 license.
 
 Read the docs here: [moordyn.readthedocs.io](https://moordyn.readthedocs.io/en/latest/)
+Example uses and instructions here: [Examples](https://github.com/FloatingArrayDesign/MoorDyn/tree/dev/example)
 
 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.
 
@@ -21,7 +22,7 @@ MoorDyn-C. The dev branch contains new features currently in development. The v1
 
 [National Renewable Energy Laboratory (NREL)](https://www.nrel.gov/):
 
-  - [Matt Hall](http://matt-hall.ca/moordyn.html)
+  - Matt Hall
   - Ryan Davies
   - Andy Platt
   - Stein Housner

docs/compiling.rst

@@ -5,8 +5,8 @@ Compiling
 
 MoorDyn is available in two forms, C and F, with two different versions, v1 and v2. V1 is
 the original MoorDyn code, containing just point and line objects. V2 is the upgraded
-version of MoorDyn v1. You can read more on the :ref:`home page <index>`. It includes that
-capability to simulate rigid bodies, non-linear tension, wave kinematics, bending 
+version of MoorDyn v1. You can read more on the :ref:`home page <index>`. It includes the
+capability to simulate rigid bodies, nonlinear tension, wave kinematics, bending 
 stiffness, and more. Further details can be found in the :ref:`theory section <theory>`
 and :ref:`structure section <structure>`. 
 
@@ -70,7 +70,7 @@ This can be done by executing the following command:
 Linux
 ^^^^^
 
-Some GNU/Linux distributions have already packages deployed for their package
+Some GNU/Linux distributions already have packages deployed for their package
 managers, which would make your life way easier.
 Otherwise, a self-extracting package is also provided.
 
@@ -96,7 +96,7 @@ However, it is strongly recommended to compile it yourself with
 To use the self-extracting package head your browser to the
 `releases page <https://github.com/FloatingArrayDesign/MoorDyn/releases>`_,
 select/expand the latest release, download the file named
-"Moordyn-X.Y.Z-Linux.sh" (with X.Y.Z the specific version you chosen) and
+"Moordyn-X.Y.Z-Linux.sh" (with X.Y.Z being the specific version you choose) and
 execute it.
 
 NOTE: The self-extracting file you have downloaded cannot be executed until you

docs/drivers.rst

@@ -8,6 +8,10 @@ MoorDyn-F contains a driver script that has a :ref:`separate input file <MDF_dri
 and MoorDyn-F compiles in OpenFAST as moordyn_driver. The MoorDyn-F driver follows all 
 the same principles as the examples below. See :ref:`compiling <compiling>` and 
 :ref:`inputs <inputs>` sections for instructions on how to use the MoorDyn-F driver. 
+Additionally, MoorDyn-F has a c-bindings interface, which allows it (along with the rest 
+of OpenFAST) to be coupled with other languages. The MoorDyn-F C interface is set up using 
+the MoorDyn V1 approach (single 6 DOF coupling), thus it requires a single coupled body to 
+be used in the MoorDyn input file.
 
 Currently MoorDyn-C v2 can be used in Python, C/C++, Fortran, and Matlab. You can
 read more on how to install MoorDyn for each different language in
@@ -80,6 +84,8 @@ MoorDyn-C can be compiled as a dynamically linked library with C bindings or a m
 sophisticated API functions and wrappers, making it accessible from a wide range of 
 programming languages.
 
+Further examples of MoorDyn-C drivers with input files can be found in the `examples folder <https://github.com/FloatingArrayDesign/MoorDyn/tree/dev/example>`_.
+
 Python
 ^^^^^^
 .. _python_wrapper:
@@ -127,11 +133,9 @@ control:
         for node_id in range(n_segs+1):
             print("  node {}:".format(node_id))
             pos = moordyn.GetLineNodePos(line, node_id)
-            printf("  pos = {}".format(pos))
+            print("  pos = {}".format(pos))
             ten = moordyn.GetLineNodeTen(line, node_id)
-            printf("  ten = {}".format(ten))
-        }
-    }
+            print("  ten = {}".format(ten))
 
     # Alright, time to finish!
     moordyn.Close(system)
@@ -811,3 +815,15 @@ After developing a coupling with MoorDyn, the DualSPHysics team has forked it in
 a seperate version called MoorDyn+, specifically dedicated to the coupling with
 DualSPHysics.
 
+OpenFOAM
+^^^^^^^^
+
+MoorDyn-C has been coupled with OpenFOAM through the `foamMooring <https://gitlab.com/hfchen20/foamMooring>`_ project.
+
+Bladed
+^^^^^^
+
+MoorDyn V1 has been coupled with DNV's Bladed software. See the following links for details:
+
+- `MoorDyn-Bladed Coupling Documentation <https://mysoftware.dnv.com/download/public/renewables/bladed/documentation/4_16/workflow/coSimulation/Bladed-MoorDynLink/Overview.html>`_
+- `MoorDyn-Bladed Coupling Theory <https://asmedigitalcollection.asme.org/OMAE/proceedings/IOWTC2023/87578/V001T01A011/1195013>`_

docs/index.rst

@@ -87,9 +87,13 @@ for the use of the MoorDyn-F driver can be found :ref:`here <MDF_driver_in>`.
 
 MoorDyn-C is designed for coupling with a wide number of codes. Some
 couplings already exist and can be found :ref:`here <coupling>` (e.g. WEC-Sim 
-and DualSPHysics). For Coupling with other codes or more manual driving of 
+and DualSPHysics). For coupling with other codes or more manual driving of 
 MoorDyn from your own script, several APIs, wrappers, and example driver 
-scripts are available :ref:`here <drivers>`.
+scripts are available :ref:`here <drivers>`. 
+
+Additionally, an example directory contains instructions for common couplings
+and basic input file set ups. A recording of the presentation that walks through
+the directory is also available `here <https://www.youtube.com/watch?v=FqW7Xpl_VNk>`_.
 
 Table of Contents:
 ------------------

docs/inputs.rst

@@ -247,10 +247,10 @@ two fixed points located far from where your system is located.
 Most of the sections are set up to contain a table of input information. These
 tables begin with two preset lines that contain the column names and the
 corresponding units. These lines are followed by any number of lines containing
-the entries in that section's table of inputs. # is the general comment chacater. If you are adding notes 
+the entries in that section's table of inputs. # is the general comment character. If you are adding notes 
 to self after any of the lines, # will prevent MoorDyn from reading them. 
 
-Examples of input files for MoorDyn-C can be found in the `test directory <https://github.com/FloatingArrayDesign/MoorDyn/tree/master/tests/Mooring>`_ (note that these do not include outputs becasue they are for tests).
+Examples of input files for MoorDyn-C can be found in the `test directory <https://github.com/FloatingArrayDesign/MoorDyn/tree/master/tests/Mooring>`_ (note that these do not include outputs because they are for tests).
 
 Examples for MoorDyn-F can be found in the `OpenFAST tests <https://github.com/OpenFAST/r-test/tree/main/modules/moordyn>`_. 
 
@@ -301,9 +301,9 @@ The columns in order are as follows:
    for end nodes (and thus end half-segments), so if simulating VIV users should ensure to include a higher number of segments. 
    Also note that VIV has only been tested with explicit time schemes (specifically rk2 and rk4). There may be unexpected behavior 
    if used with an implicit time scheme. 
- - dF - OPTIONAL - the cF +- range of non-dimensional frequnecies for the CF VIV synchronization model. If it is not
+ - dF - OPTIONAL - the cF +- range of non-dimensional frequencies for the CF VIV synchronization model. If it is not
    provided and VIV is enabled (Cl > 0) then it is default to 0.08 to align with the the theory found :ref:`here <version2>`
- - cF - OPTIONAL - the center of the range of non-dimensional frequnecies for the CF VIV synchronization model. If it is not
+ - cF - OPTIONAL - the center of the range of non-dimensional frequencies for the CF VIV synchronization model. If it is not
    provided and VIV is enabled (Cl > 0) then it is default to 0.18 to align with the the theory found :ref:`here <version2>`
 
 Note: Non-linear values for the stiffness (EA) are an option in MoorDyn. For this, a file name can be provided instead of a number. This file 
@@ -320,10 +320,10 @@ tabulated file with 3 header lines and then a strain column and a tension column
   ...       ...
 
 Note: MoorDyn has the ability to model the viscoelastic properties of synthetic lines in two ways. The first method, from work linked in the 
-:ref:`theory section <theory>`, allows a user to specify a bar-seperated constant dynamic and static stiffness. The second method allows the user 
+:ref:`theory section <theory>`, allows a user to specify a bar-separated constant dynamic and static stiffness. The second method allows the user 
 to provide a constant static stiffness and two terms to determine the dynamic stiffness as a linear function of mean load. The equation is:
 `EA_d = EA_Dc + EA_D_Lm * mean_load` where `EA_D_Lm` is the slope of the load-stiffness curve. Both of these methods allow users to provide static 
-and dynamic damping coefficients as values seperated by |. While the static damping can be described as a fraction of cricial, the dyanamic damping 
+and dynamic damping coefficients as values separated by |. While the static damping can be described as a fraction of critical, the dynamic damping 
 needs to be input as a value. Example inputs are below: 
 
 .. code-block:: none
@@ -822,7 +822,7 @@ Footnotes:
 - There are a couple additional outputs left over from OpenFAST conventions that don’t follow the 
   same format: FairTen and AnchTen. FairTen[n] is the same as Line[n]TenB. For example, the 
   fairlead tension of line 1 would be FAIRTEN1 or LINE1TENB.
-- The output list is not case sensistive, however all MoorDyn-F outputs will be printed to the output
+- The output list is not case sensitive, however all MoorDyn-F outputs will be printed to the output
   file in all caps. When searching OpenFAST output channels, users will need to search for MoorDyn
   channels in all caps. Example: the channel fairten1 would appear in the output file as FAIRTEN1.
 
@@ -886,11 +886,11 @@ follows the order of the state vector: Body degrees of freedom, rod degrees of f
 degrees of freedom. For coupled pinned bodies and rods the full 6DOF need to be provided, however the rotational 
 values will be ignored by by the MoorDyn-F driver (they can be set to zero).
 
-When using the MoorDyn driver in OpenFAST mode, the inital positions represents the offsets to the 
+When using the MoorDyn driver in OpenFAST mode, the initial positions represents the offsets to the 
 global frame. When using OpenFAST mode with the positions set to 0's, then MoorDyn objects will be 
 simulated based on the positions defined in the MoorDyn input file. If a non-zero value is provided,
-it will be incorporated into the inital positions of coupled objects. For example, if the following 
-inital positions are given:
+it will be incorporated into the initial positions of coupled objects. For example, if the following 
+initial positions are given:
 
 .. code-block:: none
   
@@ -1004,8 +1004,8 @@ data.
  0.0             0.9          0.0
  150             0.5          0.0
  1000            0.25         0.0
- 1500		         0.2	        0.0
- 5000            0.15	        0.0
+ 1500            0.2          0.0
+ 5000            0.15         0.0
  --------------------- need this line ------------------
 
 MoorDyn-F with FAST.Farm - Inputs

docs/integration_moordyn.png

@@ -97,15 +97,30 @@ 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. <https://doi.org/10.1115/IOWTC2022-98149>`_
 
+Bladed-MoorDyn Coupling:
+
+  `Alexandre, Armando, Francesc Fabregas Flavia, Jingyi Yu, Ali Bakhshandehrostami, and Steven Parkinson. "Coupling Bladed With External Finite-Element Mooring Libraries." 
+  American Society of Mechanical Engineers Digital Collection, 2023. <https://doi.org/10.1115/IOWTC2023-119346>`_
+
 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. <https://doi.org/10.1115/IOWTC2023-119524>`_
 
 Updated MoorDyn-OpenFOAM Coupling:
+  
   `Haifei Chen, Tanausú Almeida Medina, and Jose Luis Cercos-Pita, "CFD simulation of multiple moored floating structures using OpenFOAM: An open-access mooring restraints 
   library." Ocean Engineering, vol. 303, Jul. 2024. <https://doi.org/10.1016/j.oceaneng.2024.117697>`_
 
+Reef3D-MoorDyn Coupling:
+
+  `Soydan, Ahmet, Widar Weizhi Wang, and Hans Bihs. "An Improved Direct Forcing Immersed Boundary Method With Integrated Mooring Algorithm for Floating Offshore Wind 
+  Turbines." American Society of Mechanical Engineers Digital Collection, 2024. <https://doi.org/10.1115/1.4067117>`_
+
+Modeling of Bi-stable Nonlinear Energy Sinks in MoorDyn (most recent description of MoorDyn theory):
+
+  `Anargyros Michaloliakos, Wei-Ying Wong, Ryan Davies, Malakonda Reddy Lekkala, Matthew Hall, Lei Zuo, Alexander F. Vakakis, "Stabilizing dynamic subsea power cables using 
+  Bi-stable nonlinear energy sinks", Ocean Engineering, vol. 334, August 2025. <https://doi.org/10.1016/j.oceaneng.2025.121613>`_
 
 The Fortran version of MoorDyn is available as a module inside of OpenFAST:
 

docs/references.rst

@@ -7,8 +7,8 @@ main object types: Lines, Points, Rods, and Bodies. MoorDyn v1 only contained Li
 Lines are the fundamental discretized lumped-mass modeling component. Points and Rods provide a 
 means of connecting lines with additional 3- and 6-DOF properties (respectively), and Bodies 
 provide a way to create more complex 6-DOF rigid-body assemblies. These objects have predefined 
-ways or interacting. Kinematics are passed from the top down in and are used to calculate the 
-forces which are passed up back to the outside program or to output channels. This hierarchy is 
+ways of interacting. Kinematics are passed from the top down and are used to calculate the 
+forces which are passed back up to the outside program or to output channels. This hierarchy is 
 shown below:
 
 .. figure:: structure_moordyn.png

docs/structure.rst

@@ -52,7 +52,7 @@ Note that the damping ratio is with respect to the critical damping of each segm
 a mooring line, not with respect to the line as a whole or the floating platform as a 
 whole. It is just a way of letting MoorDyn calculate the damping coefficient automatically 
 from the perspective of damping non-physical segment resonances. If the model is set up 
-right, this damping can have a negligible contribution to the overall damping provided by 
+correctly, this damping can have a negligible contribution to the overall damping provided by 
 the moorings on the floating platform.  However, if the damping contribution of the mooring 
 lines on the floating platform is supposed to be significant, it is best to (1) set the BA 
 value directly to ensure that the expected damping is provided and then (2) adjust the number 
@@ -69,6 +69,26 @@ However, in contrast to the damping, which can be selected line by line, the
 time step is a constant of the whole system, and thus should be selected
 considering the minimum natural period of all lines.
 
+Catenary Solve Unsuccessful
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One of the most common issues encountered when using MoorDyn is the failure of the 
+catenary solver to converge. The catenary solver is the first step in solving the 
+initial conditions of the system. This approach tries to use the properties and geometry 
+of the mooring lines to solve for a catenary shape. 
+
+If this routine fails, you will see a "Catenary solve unsuccessful" message in the
+the console and the log file. This means that MoorDyn will initialize the lines
+as linear between the two defined end locations. After this, the ICgen process begins,
+which runs a simulation with no external forcing, allowing the lines to 'fall' into
+place. If the lines initialize as linear, then the initialization process will just take
+longer, requiring a larger `TmaxIC` value. Explanations about the different initial 
+condition generating methods can be found in the :ref:`initialization section <initialization>`.
+
+The "Catenary Solve Unsuccessful" message does not impact the performance of MoorDyn or 
+the results it produces, provided the initialization process converges before the simulation 
+begins.
+
 Python errors
 ^^^^^^^^^^^^^
 

docs/troubleshooting.rst

@@ -500,20 +500,20 @@ Water Kinematics (MoorDyn-F)
 
 MoorDyn-F has three options for simulating wave and current loads on the MoorDyn system: the Old Method, 
 the Hybrid Method, and the SeaState Method. Both the hybrid method and the SeaState method use a coupling 
-with the `OpenFAST SeaState module <https://openfast.readthedocs.io/en/main/source/user/seastate/index.html>_` 
+with the `OpenFAST SeaState module <https://openfast.readthedocs.io/en/main/source/user/seastate/index.html>`_ 
 to calculate the wave kinematics. The Old Method is a legacy method that is not coupled to SeaState. The three
 methods can be described as:
 
-- **Old Method**: MoorDyn takes wave elevation time series and current speeds with depths as inputs generates it's 
+- **Old Method**: MoorDyn takes wave elevation time series and current speeds with depths as inputs and generates its 
   own water kinematics using the equivalent of WaveGrid = 3 and Currents = 1 in MoorDyn-C.
 - **Hybrid Method**: SeaState sets up wave elevation frequencies and current speeds and then MoorDyn interpolates 
   this information to user provided wave grid and current depth discretization. This allows users to set the 
-  WaterKinematics for the whole OpenFAST or FAST.Farm system while still maintaining a courser grid for the MoorDyn
+  WaterKinematics for the whole OpenFAST or FAST.Farm system while still maintaining a coarser grid for the MoorDyn
   water kinematics, enabling computational efficiency. This method is compatible with FAST.Farm.
 - **SeaState Method**: SeaState does all the work, MoorDyn just accesses the SeaState grid data at any given 
   timestep and location. This requires the SeaState grid to encompass the whole MoorDyn system for the most
-  accurate results. If a point is quried outside the SeaState gird, it will recive the water kinematics of 
-  the nearest grid point. This method is not compataible with FAST.Farm.
+  accurate results. If a point is queried outside the SeaState grid, it will receive the water kinematics of 
+  the nearest grid point. This method is not compatible with FAST.Farm.
 
 The table below summarizes these three options.