Merge pull request #2622 from OpenFAST/rc-4.0.1

Release 4.0.1

docs/changelogs/ReleaseProcess.md

@@ -0,0 +1,84 @@
+# OpenFAST release process
+
+## Prep
+### pull request
+1. Create release changelog.md
+2. Post PR with contents of the changelog/release notes
+3. Get reviews and address all issues
+
+### PR branch updates
+1. checkout branch to merge in and verify builds on VS if any changes for VS or new files added
+2. Update the documentation version in docs/conf.py
+3. Update the versions in docs/source/user/api_change.rst
+4. Verify readthedocs builds correctly
+5. Update `openfast_io/pyproject.toml`
+
+****
+
+## Posting the release
+### r-test
+1. Merge and add annotated tag
+2. Update pointer on main OF repository (not always necessary)
+
+### Main repository
+1. Merge PR
+2. Create release with new tag
+   * Copy `Changelog` section down from the changlog.md file to release notes
+   * add short intro section at top with 2 sentence synopsis (see prior release for this)
+   * copy `Precompiled Windows Binaries` section from prior release, and update as needed into the release notes
+   * check the `create discussion` box
+   * Post
+3. delete `rc-` branch if merging from one
+
+### Windows executables build and upload
+After posting and tagging release
+1. Pull main and tags
+   * `git fetch --tags OpenFAST`
+   * `git fetch OpenFAST main:main`
+   * `git checkout main`
+2. Delete `vs-build` and checkout again
+   * `rm -rf vs-build`
+   * `git checkout vs-build`
+3. Set a couple of VS files to not track changes on files that VS wants to update Windows related stuff in
+      ```
+   git update-index --assume-unchanged vs-build/MAPlib/MAP_dll.vcxproj vs-uild/Registry/FAST_Registry.vcxproj
+   ```
+
+4. Compile executables for Windows builds
+   * Run one of the executables and check the version info. Muck about with VS if there is an issue.
+   * Also run `dumpbin.exe /dependents <exe>.exe` to check static linking
+   * NOTE: build the simulink last -- it messes up some things otherwise
+    - [ ] AeroDyn_Driver_x64.exe
+    - [ ] AeroDyn_Driver_x64_OpenMP.exe
+    - [ ] AeroDyn_Inflow_C_Binding_x64.dll
+    - [ ] AeroDyn_Inflow_C_Binding_x64_OpenMP.dll
+    - [ ] BeamDyn_Driver_x64.exe
+    - [ ] DISCON.dll (x64)
+    - [ ] DISCON_ITIBarge.dll (x64)
+    - [ ] DISCON_OC3Hywind.dll (x64)
+    - [ ] DISCON_SC.dll (x64)
+    - [ ] FAST.Farm_x64.exe
+    - [ ] FAST.Farm_x64_OMP.exe
+    - [ ] FAST_SFunc.mexw64 -- build from MATLAB
+    - [ ] HydroDynDriver_x64.exe
+    - [ ] HydroDyn_C_Binding_x64.dll
+    - [ ] IfW_C_Binding_x64.dll
+    - [ ] InflowWind_Driver_x64.exe
+    - [ ] InflowWind_Driver_x64_OpenMP.exe
+    - [ ] MoorDyn_Driver_x64.exe
+    - [ ] MoorDyn_C_Binding_x64.dll
+    - [ ] OpenFAST-Simulink_x64.dll -- change `additional dependencies` in the `OpenFAST-Simulink` project in `FAST` to point to correct install of MATLAB
+    - [ ] openfast_x64.exe
+    - [ ] SubDyn_x64.exe
+    - [ ] Turbsim_x64.exe
+
+5. Upload all filesUnset the no tracking of files
+   ```
+   git ls-files -v | grep "^[a-z]"
+   git update-index --no-assume-unchanged <files-from-cmd-above>
+   ```
+## Post-release
+### Docker Image push to ghcr.io
+1. Build latest `OpenFAST/main` image locally.
+2. Push image to ghcr.io/openfast/openfast using tags `latest` and `<version>`
+

docs/changelogs/v4.0.1.md

@@ -0,0 +1,87 @@
+**Feature or improvement description**
+Pull request to merge `rc-4.0.1` into `main` and create a tagged release for v4.0.1
+
+See the milestone and project pages for additional information
+
+    https://github.com/OpenFAST/openfast/milestone/16
+
+Test results, if applicable
+See GitHub Actions
+
+### Release checklist:
+- [ ] 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 annotated tag
+- [ ] Compile executables for Windows builds
+    - [ ] `AeroDyn_Driver_x64.exe`
+    - [ ] `AeroDyn_Driver_x64_OpenMP.exe`
+    - [ ] `AeroDyn_Inflow_C_Binding_x64.dll`
+    - [ ] `AeroDyn_Inflow_C_Binding_x64_OpenMP.dll`
+    - [ ] `BeamDyn_Driver_x64.exe`
+    - [ ] `DISCON.dll (x64)`
+    - [ ] `DISCON_ITIBarge.dll (x64)`
+    - [ ] `DISCON_OC3Hywind.dll (x64)`
+    - [ ] `DISCON_SC.dll (x64)`
+    - [ ] `FAST.Farm_x64.exe`
+    - [ ] `FAST.Farm_x64_OMP.exe`
+    - [ ] `FAST_SFunc.mexw64`
+    - [ ] `HydroDynDriver_x64.exe`
+    - [ ] `HydroDyn_C_Binding_x64.dll`
+    - [ ] `IfW_C_Binding_x64.dll`
+    - [ ] `InflowWind_Driver_x64.exe`
+    - [ ] `InflowWind_Driver_x64_OpenMP.exe`
+    - [ ] `MoorDyn_Driver_x64.exe`
+    - [ ] `MoorDyn_C_Binding_x64.dll`
+    - [ ] `OpenFAST-Simulink_x64.dll`
+    - [ ] `openfast_x64.exe`
+    - [ ] `SubDyn_x64.exe`
+    - [ ] `Turbsim_x64.exe`
+
+# Changelog
+
+## Overview
+
+This release includes multiple small bug-fixes including compilation issues with Flang and Intel (IFX), improved diagnostics for the AeroDyn\_Inflow\_c-binding interface, user specified external loads and damping for MoorDyn, `Wind_IO` updates, a fix for a stack overflow with FAST.Farm built with Visual Studio on Windows, and other minor bugfixes.
+
+
+
+## General
+
+### Wind_IO
+
+#2603 updates to handle writing OpenFAST models from weis and wind_io (mayankchetan)
+
+
+### Build systems
+
+#2607 Windows VS build -- stack overflow with FAST.Farm (andrew-platt)
+
+#2619 ROCM Flang doesn't compile NWTC_IO.f90 (andrew-platt)
+
+#2621 Bugfix: Update `create_FAST_SFunc.m` for Windows, update docs on Simulink MEX building (andrew-platt)
+
+
+## Module changes
+
+### AeroDyn
+
+#2609 AD bugfix: aerodyn driver non-OLAF combined cases don't update wind (andrew-platt)
+
+#2615 Improve diagnostics for ADI_c interface coupling (andrew-platt)
+
+
+### MoorDyn
+
+#2597 MD: User-specified external forces and translational damping for MoorDyn point, rod, and body objects (luwang00)
+
+
+## Input file changes
+
+No input file changes are required from 4.0.0.  MoorDyn can contain an optional section for `External Loads`.
+
+Full list of changes: https://openfast.readthedocs.io/en/main/source/user/api_change.html
+
+Full input file sets: https://github.com/OpenFAST/r-test/tree/v4.0.1 (example input files from the regression testing)
+

docs/conf.py

@@ -138,7 +138,7 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut):
 # The short X.Y version.
 version = u'4.0'
 # The full version, including alpha/beta/rc tags.
-release = u'v4.0.0'
+release = u'v4.0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/install/index.rst

@@ -460,19 +460,26 @@ The CMake options specific to OpenFAST and their default settings are:
     BUILD_DOCUMENTATION            - Build documentation (Default: OFF)
     BUILD_FASTFARM                 - Enable FAST.Farm capabilities (Default: OFF)
     BUILD_OPENFAST_CPP_API         - Enable building OpenFAST - C++ API (Default: OFF)
+    BUILD_OPENFAST_CPP_DRIVER      - Enable building OpenFAST C++ driver using C++ CFD API (Default: OFF)
+    BUILD_OPENFAST_LIB_DRIVER      - Enable building OpenFAST driver using C++ Library API (Default: OFF)
     BUILD_OPENFAST_SIMULINK_API    - Enable building OpenFAST for use with Simulink (Default: OFF)
     BUILD_SHARED_LIBS              - Enable building shared libraries (Default: OFF)
     BUILD_TESTING                  - Build the testing tree (Default: OFF)
+    BUILD_UNIT_TESTING             - Enable unit testing (Default: ON)
     CMAKE_BUILD_TYPE               - Choose the build type: Debug Release (Default: Release)
     CMAKE_Fortran_MODULE_DIRECTORY - Set the Fortran Modules directory
     CMAKE_INSTALL_PREFIX           - Install path prefix, prepended onto install directories.
-    CODECOV                        - Enable infrastructure for measuring code coverage (Default: OFF)
+    CMAKE_MACOSX_RPATH             - Use RPATH runtime linking (Default: ON)
+    CODECOVERAGE                   - Enable infrastructure for measuring code coverage (Default: OFF)
     DOUBLE_PRECISION               - Treat REAL as double precision (Default: ON)
     FPE_TRAP_ENABLED               - Enable Floating Point Exception (FPE) trap in compiler options (Default: OFF)
     GENERATE_TYPES                 - Use the openfast-registry to autogenerate types modules (Default: OFF)
     OPENMP                         - Enable OpenMP support (Default: OFF)
-    ORCA_DLL_LOAD                  - Enable OrcaFlex library load (Default: OFF)
+    ORCA_DLL_LOAD                  - Enable OrcaFlex library load (Default: ON)
     USE_DLL_INTERFACE              - Enable runtime loading of dynamic libraries (Default: ON)
+    USE_LOCAL_STATIC_LAPACK        - Enable downloading and building static LAPACK and BLAS libs (Default: OFF)
+    VARIABLE_TRACKING              - Enables variable tracking for better runtime debugging output. May increase compile time. Valid only for GNU. (Defualt: ON)
+
 
 Additional system-specific options may exist for a given system, but those
 should not impact the OpenFAST configuration. As mentioned above, the
@@ -754,6 +761,27 @@ through the Intel oneAPI distributions.
 
 .. _installation_appendix:
 
+Simulink
+~~~~~~~~
+To build the MEX function for coupling OpenFAST into Simulink, there are two
+options depending on platform.
+
+Windows with Visual Studio
+--------------------------
+For Windows, build with the `Release_Matlab` option from the Visual Studio
+project in `vs-build/FAST/FAST.sln`.  Then run
+`glue-codes/simulink/src/create_FAST_SFunc.m` from MATLAB (instructions at the
+top of this file).
+
+CMake
+-----
+For CMake builds on all platforms, enable the `-DBUILD_OPENFAST_SIMULINK_API=On`
+option in CMake and build the `FAST_SFunc` target.  This will place the
+resulting `FAST_SFunc.mexXXXX` in
+`<build-dir>/glue-codes/simulink/FAST_SFunc.mexXXXX` (and in the install
+directory at `install/bin/FAST_SFunc.mexXXXX` if `make install` was called).
+
+
 Appendix
 ~~~~~~~~
 The following are additional methods for installation which may not be fully

docs/source/user/api_change.rst

@@ -11,6 +11,23 @@ Thus, be sure to implement each in order so that subsequent line numbers are cor
 
 
 
+OpenFAST v4.0.0 to OpenFAST v4.0.1
+----------------------------------
+
+No input file changes are required.  MoorDyn can contain an option section for
+`External Loads` (see the MoorDyn documentation for details `here <https://moordyn.readthedocs.io/en/latest/inputs.html#the-v2-input-file>`__).
+
+============================================= ======== ==================== =================================================================================================================================================================================================
+Modified in OpenFAST `v4.0.1`                             
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+Module                                        Line     Flag Name            Example Value
+============================================= ======== ==================== =================================================================================================================================================================================================
+MoorDyn                                       \*                            New optional sections for `EXTERNAL LOADS` (freeform file).  See MoorDyn documentation for details (`here <https://moordyn.readthedocs.io/en/latest/inputs.html#the-v2-input-file>`__)
+============================================= ======== ==================== =================================================================================================================================================================================================
+
+\*Exact line number depends on number and size of preceeding sections.
+
+
 OpenFAST v3.5.5 to OpenFAST 4.0.0
 ---------------------------------
 
@@ -23,7 +40,7 @@ New modules AeroDisk (see :numref:`ADsk`), Simplified-ElastoDyn (see
 documentation on those modules for exmple input files.
 
 ============================================= ======== ==================== ========================================================================================================================================================================================================
-Modified in OpenFAST `dev`                             
+Modified in OpenFAST `v4.0.0`                             
 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 Module                                        Line     Flag Name            Example Value
 ============================================= ======== ==================== ========================================================================================================================================================================================================
@@ -56,7 +73,7 @@ ElastoDyn blade file                          15                            Remo
 InflowWind driver                             27                            ----  Output VTK slices  ------------------------------------------------------
 InflowWind driver                             28       NOutWindXY           0            NOutWindXY    -- Number of XY planes for output <RootName>.XY<loc>.t<n>.vtk (-) [0 to 9]
 InflowWind driver                             29       OutWindZ             90           OutWindZ      -- Z coordinates of XY planes for output (m) [1 to NOutWindXY] [unused for NOutWindXY=0]
-MoorDyn                                       --                            New optional sections (freeform file).  See MoorDyn documentation for details
+MoorDyn                                       --                            New optional sections (freeform file).  See MoorDyn documentation for details (`here <https://moordyn.readthedocs.io/en/latest/inputs.html#the-v2-input-file>`__)
 SubDyn                                        8         --removed--         removed: GuyanLoadCorrection
 SubDyn                                        12        --removed--         removed: CBMod
 SubDyn                                        56\*                                              ----------------------- SPRING ELEMENT PROPERTIES -------------------------------------

glue-codes/simulink/CMakeLists.txt

@@ -84,6 +84,6 @@ endif()
 install(TARGETS FAST_SFunc
   EXPORT "${CMAKE_PROJECT_NAME}Libraries"
   RUNTIME DESTINATION bin
-  LIBRARY DESTINATION lib
+  LIBRARY DESTINATION bin
   ARCHIVE DESTINATION lib
 )

glue-codes/simulink/src/create_FAST_SFunc.m

@@ -1,24 +1,30 @@
 %% INSTRUCTIONS
-% This script is used to manually build a Simulink mex file which uses the openfastlib shared library (.dll, .so, .dylib).
-% If you are building OpenFAST with CMake on linux or macOS or windows, you can automatically generate the mex file
-% by specifying -DBUILD_OPENFAST_SIMULINK_API=ON when running cmake, you do not need to use this script.
+% This script is used to manually build a Simulink mex file on Windows with Visual Studio. It uses the openfastlib shared
+% library (.dll).
 %
-% Before running this script, you must have compiled OpenFAST for Simulink to create a DLL (i.e., a shared library like .so, .dylib, .lib, etc.).
-% - If cmake was used, make sure the install directory is specified properly in the `installDir` variable below,
-%   and if using Windows, set `built_with_visualStudio` to false.
+% If you are using Windows and building with CMake, do not use this script.  Instead use cmake to build the FAST_SFunc.mexXXXX directly.
+%
+% If you are not using Windows, do not use this script.  Instead use cmake to build the FAST_SFunc.mexXXXX directly.
+%
+% Alternative building with CMAKE:
+% specify -DBUILD_OPENFAST_SIMULINK_API=ON when running cmake
+%  - "make FAST_SFunc" will place the resulting mex file at <build-dir>/glue-codes/simulink/FAST_SFunc.mexXXXX
+%  - "make install" will place the resulting mex file at install/bin/FAST_SFunc.mexXXXX
+%
+%
+% Before running this script, you must have compiled OpenFAST for Simulink to create a DLL (i.e., a shared library .lib).
 % - If the Visual Studio Solution file contained in the vs-build directory was used to create the DLL on Windows,
 %   make sure `built_with_visualStudio` is set to true.
 % - The name of the library that was generated must match the `libname` variable below
 %   and should be located in the directory specified by `libDir`.
 % - The `includeDir` variable must specify the directory that contains the following header files:
-%   "FAST_Library.h", "OpenFOAM_Types.h", and "SuperController_Types.h"
-% - The `outDir` variable indicates where the resulting mex file will reside.
+%   "FAST_Library.h", "OpenFOAM_Types.h", "SuperController_Types.h", and "ExtLoadsDX_Types.h" 
 %
 % Run `mex -setup` in Matlab to configure a C compiler if you have not already done so.
 
 mexname = 'FAST_SFunc'; % base name of the resulting mex file
 
-built_with_visualStudio = false; %if the libraries were built with cmake, set to false
+built_with_visualStudio = true; %if the libraries were built with cmake, set to false
 
 
 if (ispc && built_with_visualStudio)   
@@ -42,28 +48,19 @@
 else    
 %% defaults for cmake builds:
 
-    if ( ismac )  % Apple MacOS
-        installDir = '../../../install';
-        outDir = fullfile(installDir, 'lib');
-    elseif ( ispc ) % Windows PC
-        installDir = '../../../install';
-        outDir = fullfile(installDir, 'lib');
-        % If there are shared libraries does it work for outDir to be the local directory?
-    else
-        installDir = '../../../install';
-        outDir = '.';
-    end
+   fprintf( '\n----------------------------\n' );
+   fprintf( 'Do not use this script with Mac/Linux.  Follow the CMake instructions at the top of the script instead.' );
+   fprintf( '\n----------------------------\n' );
 
-    libDir = fullfile(installDir, 'lib');
-    includeDir = fullfile(installDir, 'include');
-    libName = 'openfastlib_mex';
 end
 
-%% BUILD COMMAND
-fprintf( '\n----------------------------\n' );
-fprintf( 'Creating %s\n\n', [outDir filesep mexname '.' mexext] );
+
 
 if ispc () % Windows PC
+   %% BUILD COMMAND
+   fprintf( '\n----------------------------\n' );
+   fprintf( 'Creating %s\n\n', [outDir filesep mexname '.' mexext] );
+
 
     mex('-largeArrayDims', ...
         ... % '-v', ... %add this line for "verbose" output (for debugging)
@@ -72,27 +69,10 @@
         ['-I' includeDir], ...
         '-I../../../modules/supercontroller/src', ... % needed for visual studio builds to find "SuperController_Types.h"
         '-I../../../modules/externalinflow/src',  ... % needed for visual studio builds to find "ExternalInflow_Types.h"
+        '-I../../../modules/extloads/src', ... % needed for visual studio builds to find "ExtLoadsDX_Types.h"
         '-outdir', outDir, ...
         ['COMPFLAGS=$COMPFLAGS -MT -DS_FUNCTION_NAME=' mexname], ...
         '-output', mexname, ...
         'FAST_SFunc.c');
 
-else % mac/unix
-
-    mex('-largeArrayDims', ...
-        ... '-v', ... %add this line for "verbose" output (for debugging)
-        ['-L', libDir], ...
-        ['-l', libName], ...
-        '-lgfortran', ...
-        '-lquadmath', ...
-        '-llapack', ...
-        '-lblas', ...
-        '-ldl', ...
-        ['-I', includeDir], ...
-        '-outdir', outDir, ...
-        ['CFLAGS=$CFLAGS -DS_FUNCTION_NAME=' mexname], ...
-        ... ['CXXFLAGS=$CXXFLAGS -DS_FUNCTION_NAME=' mexname], ...
-        '-output', mexname, ...
-        'FAST_SFunc.c');
-
 end