Merge pull request #3238 from andrew-platt/f/AMReX_reader

Add AMReX-based inflow reader to AWAE for FAST.Farm

Author: deslaughter

.github/workflows/automated-dev-tests.yml

@@ -107,6 +107,7 @@ jobs:
             -DBUILD_OPENFAST_LIB_DRIVER:BOOL=ON \
             -DBUILD_OPENFAST_CPP_DRIVER:BOOL=ON \
             -DBUILD_FASTFARM:BOOL=ON \
+            -DAMREX_READER=ON \
             ${GITHUB_WORKSPACE}
       - name: Build all
         working-directory: ${{github.workspace}}/build
@@ -116,7 +117,7 @@ jobs:
         run: |
           tar -cvf workspace.tar -C ${{github.workspace}} \
           --exclude='*.a' --exclude='*.o' --exclude='build/ftnmods' \
-          --exclude='.git' --exclude='docs' --exclude='vs-build' \
+          --exclude='docs' --exclude='vs-build' \
           .
       - name: Save workspace for other jobs
         uses: actions/upload-artifact@v4
@@ -166,6 +167,7 @@ jobs:
             -DVARIABLE_TRACKING:BOOL=OFF \
             -DBUILD_TESTING:BOOL=ON \
             -DCTEST_PLOT_ERRORS:BOOL=ON \
+            -DAMREX_READER=ON \
             ${GITHUB_WORKSPACE}
             # -DDOUBLE_PRECISION=OFF \
       - name: Build all

CMakeLists.txt

@@ -166,6 +166,35 @@ else()
   endif()
 endif()
 
+#-------------------------------------------------------------------------------
+# AMReX reader inclusion in FAST.Farm
+#-------------------------------------------------------------------------------
+# Included as an external project, cloned to `dependencies` directory
+
+option(AMREX_READER "Include AMReX reader in FAST.Farm" off)
+if (AMREX_READER)
+  if (WIN32)
+    message(FATAL_ERROR "AMREX_READER option not available on Windows (AMReX incompatible)")
+  endif()
+  include(FetchContent)
+  FetchContent_Declare(
+    AMReX
+    GIT_REPOSITORY https://github.com/AMReX-Codes/amrex.git
+    GIT_TAG        26.02
+  )
+  set(AMReX_AMRLEVEL Off CACHE BOOL "" FORCE)
+  set(AMReX_EXPORT_DYNAMIC Off CACHE BOOL "" FORCE)
+  set(AMReX_LINEAR_SOLVERS Off CACHE BOOL "" FORCE)
+  set(AMReX_LINEAR_SOLVERS_EM Off CACHE BOOL "" FORCE)
+  set(AMReX_LINEAR_SOLVERS_INCLFO Off CACHE BOOL "" FORCE)
+  set(AMReX_MPI Off CACHE BOOL "" FORCE)
+  set(AMReX_PARTICLES Off CACHE BOOL "" FORCE)
+  set(AMReX_FORTRAN On CACHE BOOL "" FORCE)
+  set(AMReX_FORTRAN_INTERFACES On CACHE BOOL "" FORCE)
+  set(AMReX_PRECISION DOUBLE CACHE STRING "" FORCE)
+  FetchContent_MakeAvailable(AMReX)
+endif ()
+
 #-------------------------------------------------------------------------------
 # Simulink
 #-------------------------------------------------------------------------------
@@ -290,9 +319,7 @@ if(BUILD_TESTING)
 
   # unit tests
   if(BUILD_UNIT_TESTING)
-    if(NOT (${CMAKE_Fortran_COMPILER_ID} STREQUAL "Flang"))
-      add_subdirectory(unit_tests)
-    endif()
+    add_subdirectory(unit_tests)
   endif()
 endif()
 
@@ -304,4 +331,3 @@ option(BUILD_DOCUMENTATION "Build documentation." OFF)
 if(BUILD_DOCUMENTATION)
   add_subdirectory(docs)
 endif()
-

docs/source/user/api_change.rst

@@ -77,6 +77,11 @@ ServoDyn                                      15       PitDamp(1)           1.4E
 ServoDyn                                      16       PitDamp(2)           1.4E6         PitDamp(2)  - Blade 2 pitch damping constant
 ServoDyn                                      17       PitDamp(3)           1.4E6         PitDamp(3)  - Blade 3 pitch damping constant *[unused for 2 blades]*
 HydroDyn                                      \*       HstMod               1             HstMod      - Method of computing hydrostatic loads. (0: Up to the still water level. 1: Up to the instantaneous free surface) *[overwrite to 0 when WaveStMod = 0 in SeaState]*
+FAST.Farm                                     35                            --- AMBIENT WIND: AMReX MODULE --- [used only for Mod_AmbWind=4]
+FAST.Farm                                     36       WindDirPrefix        "inflow/ffboxes"   WindDirPrefix - Directory prefix of AMReX wind sub-volumes {0=low-res, 1+=high-res} (quoted string)
+FAST.Farm                                     37       DirStartIndex        00110              DirStartIndex - AMReX sub-volume directory suffix to consider as time=0 (quoted string)
+FAST.Farm                                     38       DT_Low-AMReX         2.0                DT_Low-AMReX  - Time step for low-resolution wind data interpolation; will be used as the global FAST.Farm time step (s) [>0.0]
+FAST.Farm                                     39       DT_High-AMReX        1.0                DT_High-AMReX - Time step for high-resolution wind data interpolation (s) [>0.0]
 ============================================= ======== ==================== ========================================================================================================================================================================================================
 
 

docs/source/user/fast.farm/InputFiles.rst

@@ -81,14 +81,18 @@ simulation length set in the OpenFAST primary input file of each wind
 turbine in the wind farm.
 
 **Mod_AmbWind** [switch] indicates the ambient wind source. There are
-three options: 1) use ambient wind data generated by a high-fidelity
+four options: 1) use ambient wind data generated by a high-fidelity
 precursor simulation in VTK format **[Mod_AmbWind=1]**, 2) use ambient
 wind data as defined by the FAST.Farm interface to the *InflowWind*
-module, with one instance of *InflowWind* **[Mod_AmbWind=2]**, or 3) use
+module, with one instance of *InflowWind* **[Mod_AmbWind=2]**, 3) use
 ambient wind data as defined by the FAST.Farm interface to the
 *InflowWind* module, with multiple instances of *InflowWind*
-**[Mod_AmbWind=3]**. The distinct Ambient Wind subsections below pertain
-to each option.
+**[Mod_AmbWind=3]**, or 4) use ambient wind data generated by a
+high-fidelity precursor simulation stored in AMReX plot file format
+**[Mod_AmbWind=4]**. The distinct Ambient Wind subsections below pertain
+to each option. Note that **Mod_AmbWind** = 4 requires FAST.Farm to be
+compiled with AMReX support (``-DAMREX_READER=ON`` in CMake, not available when
+compiling with Visual Studio).
 
 **Mod_WaveField** [switch] indicates how the wave field should be treated.  The
 two options are: 1) use individual HydroDyn inputs at each turbine without
@@ -297,6 +301,55 @@ there are spaces in the file or path names, these quotes are required.
 See :numref:`FF:AmbWindIfW` for information on the contents of
 this file.
 
+.. _FF:Input:AMReX:
+
+Ambient Wind: Precursor in AMReX Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The input parameters in this section are only used when **Mod_AmbWind**
+= 4, indicating the use of ambient wind from a high-fidelity precursor
+simulation stored in `AMReX <https://amrex-codes.github.io>`__ plot file
+format. This option requires FAST.Farm to be compiled with the AMReX
+library enabled (``-DAMREX_READER=ON`` with CMake). The grid dimensions, origin,
+and spatial discretization are read directly from the AMReX plot file
+headers and do not need to be specified in the input file.
+
+**WindDirPrefix** [quoted string] specifies the path prefix for the
+AMReX wind sub-volume directories. Sub-volume directories follow the
+naming convention *<WindDirPrefix>_<sv>_<index>*, where *<sv>* is the
+sub-volume number (0 for the low-resolution domain; 1 through
+**NumTurbines** for the high-resolution domain of each turbine) and
+*<index>* is a zero-padded integer directory index. The path can be
+specified relative to the location of the FAST.Farm primary input file
+or with an absolute path. It is recommended to use quotes around the
+path. See :numref:`FF:AmbWindAMReX` for further details on the expected
+directory structure.
+
+**DirStartIndex** [quoted string] specifies the directory index suffix
+(e.g., ``"00000"``) corresponding to the simulation start time
+:math:`t=0`. The string length determines the zero-padding width applied
+to all directory index numbers; the number of leading zeros in
+**DirStartIndex** sets the total field width used when constructing
+subsequent directory names. FAST.Farm automatically searches for all
+available time steps beginning from this index. It is recommended to use
+quotes around this value.
+
+**DT_Low-AMReX** [sec] sets the time step of the low-resolution ambient
+wind data and the global (driver/glue-code) time step of FAST.Farm. All
+FAST.Farm modules are called every **DT_Low-AMReX** seconds, although
+OpenFAST and its modules may use a time step that is an integer multiple
+smaller than or equal to **DT_Low-AMReX**. The value must match the time
+step used when generating the precursor simulation data.
+
+**DT_High-AMReX** [sec] sets the time step of the high-resolution
+ambient wind data and **must be an integer multiple smaller than or
+equal to DT_Low-AMReX**. It must match the time resolution of the
+high-resolution sub-volumes in the precursor data. **DT_Low-AMReX**
+should be consistent with the timescales of wake dynamics (e.g., on the
+order of seconds), and **DT_High-AMReX** should be sufficient for
+accurate aerodynamic load calculations (e.g., on the order of fractions
+of a second). Further guidance is given in :numref:`FF:ModGuidance`.
+
 .. _FF:Input:WT:
 
 Wind Turbines
@@ -1056,6 +1109,71 @@ used (**WindType** = 1). When using full-field turbulent wind data in
    *X-Y-Z* offsets of each turbine origin relative to the origin of the
    inertial frame coordinate system.
 
+.. _FF:AmbWindAMReX:
+
+Ambient Wind Precursor Files in AMReX Plot File Format
+------------------------------------------------------
+
+When using **Mod_AmbWind** = 4, the ambient wind data must be
+pre-generated and stored as `AMReX
+<https://amrex-codes.github.io>`__ plot files. AMReX plot files are
+directories containing a ``Header`` file and one or more cell-data files
+storing three-component (*X*, *Y*, *Z*) velocity fields on a structured
+Cartesian grid. FAST.Farm reads the grid dimensions, origin, and
+spacing from the ``Header`` and requires exactly three velocity
+components (``x_velocity``, ``y_velocity``, ``z_velocity`` or equivalent
+names in order).
+
+The sub-volume directories must follow the naming convention
+*<WindDirPrefix>_<sv>_<index>*, where:
+
+-  **WindDirPrefix** is the path prefix specified in the FAST.Farm
+   primary input file.
+
+-  *<sv>* is the sub-volume number: ``0`` for the low-resolution domain
+   and ``1`` through **NumTurbines** for the high-resolution domain of
+   each wind turbine.
+
+-  *<index>* is a zero-padded integer index with the same field width as
+   **DirStartIndex**. The index for time step :math:`n` is
+   :math:`\text{DirStartNum} + n \times \Delta_\text{index}`, where
+   :math:`\text{DirStartNum}` is the integer value of **DirStartIndex**
+   and :math:`\Delta_\text{index}` is the stride between successive
+   directory indices (determined automatically by FAST.Farm by scanning
+   the available directories).
+
+During initialization, FAST.Farm reads the header of the starting
+sub-volume for each domain (low-resolution sub-volume 0 and each
+high-resolution sub-volume 1 through **NumTurbines**) to obtain the
+grid properties, then calls the directory-discovery routine to confirm
+that a sufficient number of time steps exist and that the grid
+properties are consistent across all time steps. Specifically, FAST.Farm
+verifies:
+
+-  That at least **NumDT** low-resolution and high-resolution
+   directories are available for the simulation duration.
+
+-  That the grid dimensions, origin, and spacing are identical across
+   all time steps for a given sub-volume.
+
+-  That the grid dimensions are the same for all high-resolution
+   sub-volumes (one per turbine).
+
+Because the grid properties are determined from the precursor data
+files, the user does not specify low- or high-resolution grid dimensions
+or origins in the FAST.Farm primary input file when using
+**Mod_AmbWind** = 4. The Wind Turbines table also requires only the
+standard four columns (**WT_X**, **WT_Y**, **WT_Z**, **WT_FASTInFile**),
+without the six additional high-resolution grid columns that are needed
+for **Mod_AmbWind** = 2 or 3.
+
+.. note::
+
+   AMReX support is only available when compiling with CMake and must be enabled at
+   compile time by passing ``-DAMREX_READER=ON`` during configuration. If FAST.Farm
+   is compiled without AMReX support, setting **Mod_AmbWind** = 4 will
+   produce a fatal error.
+
 .. _FF:Input:OFInput:
 
 OpenFAST Input Files

glue-codes/fast-farm/src/FAST_Farm.f90

@@ -26,6 +26,7 @@
 PROGRAM FAST_Farm
 
    USE FAST_Farm_Subs
+   USE amrex_utils
 
    IMPLICIT NONE
 
@@ -83,6 +84,9 @@ PROGRAM FAST_Farm
       call NormStop()
    endif
 
+   ! Initialize AMReX library
+   call amrex_init(arg_parmparse=.false.)
+
    CALL FAST_ProgStart( Farm_Ver ) ! put this after CheckArgs because CheckArgs assumes we haven't called this routine, yet.
 
    IF ( TRIM(FlagArg) == 'RESTART' ) THEN ! Restart from checkpoint file
@@ -157,6 +161,9 @@ PROGRAM FAST_Farm
    !...............................................................................................................................         
 
    call FARM_End(farm, ErrStat, ErrMsg)
+
+   ! Finalize AMReX library
+   call amrex_finalize()
 
    CALL RunTimes( ProgStrtTime, ProgStrtCPU, SimStrtTime, SimStrtCPU, t )   
    call NormStop()
@@ -190,6 +197,8 @@ SUBROUTINE CheckError(ErrID,Msg,ErrLocMsg)
             END IF
 
             call FARM_End(farm, ErrStat2, ErrMsg2)                                 
+            ! Finalize AMReX library
+            call amrex_finalize()
             call ProgAbort('', TrapErrors=.FALSE., TimeWait=3._ReKi )
 
          END IF