Turbulent inflow generation (patch) (erf-model#1665)

* Generalized size of boxes. Start implementing CPB. Still need user input + .rst documentation

* Added my own folder in Exec, ABL_perturbation_inflow

* Generalized BPM so it can transform into CPM. Added more user input variables. Renamed BPM and CPM tags to source and direct to keep neutrality. Need to add Ec, tp, and cell_data equations for direction add.

* manually got rid of tabs

* added in calc_tpi_meanMag_firstCell() function and direct field add within TimeIntegration/ERF_Advance.cpp for CPM cases. Need to implement options to swap back and forth on use side between BPM and CPM. Switch gear and start runtime optimization.

* amr.v=0 helps with runtime. Added random numbers for PB_intervals. Added outputs for PB_amplitude/PB_updateTime in seperate file when erf.v=1. Need to find a good way to generalize amplitude. Currently breaks code when amplitude is too large. CONTINUE with CPM debug, fast_rhs_fun debug with PB, and documentation with .rst file.

* Fixed CUDA private member issue. CONTINUE with CPM debug, fast_rhs_fun debug with PB, and documentation with .rst file

* Added output format into file + verbose tags. Fixed parallel issue of boxes. Added in perturbation inflow .rst documents. CONTINUE with CPM debug, fast_rhs_fun debug with PB.

* Added output format into file + verbose tags. Fixed parallel issue of boxes. Added in perturbation inflow .rst documents. CONTINUE with CPM debug, fast_rhs_fun debug with PB.

* Get rid of trailing white space. Added output format into file + verbose tags. Fixed parallel issue of boxes. Added in perturbation inflow .rst documents. CONTINUE with CPM debug, fast_rhs_fun debug with PB.

* update DOI links for build-and-deploy fail test.

* 404 Client Error: Not Found for url error fix.

* 404 Client Error: Not Found for url error fix.

* 404 Client Error: Not Found for url error fix.

* Error 403 with Munoz-Esparza 2015 paper. Last attempt

* Added in perturbation inflow .rst documents. CONTINUE with pb tests. Currently blows up after 1st update interval.

* fix for doc push

* manual rerun for DOI link in docs

* link replacement for syntax error

* manual check for munoz link

* what is going on with these links?

* using link I know that works

* testing DeLeon link

* DeLeon: maybe it's a syntax error?

* DeLeon: Trying the other way of linking

* maybe special character problem?

* commented out links to DeLeon et al. (2018), and Munoz-Esparza et al. (2015). DOI links return Erorror 403, actual link returns Error 404.

* testing perturbation inflow method, qualitativly for now

* Added trigger tags for PBM in ERF.cpp. This should fix compile error in workflow.

* Document update

* resolved erroneous error with pseduo gravity (ignores scales with mechancial perturbation)

* resolved erroneous error with pseduo gravity (ignores scales with mechancial perturbation)

* updating PR

* fixing codespell

---------

Co-authored-by: Ting-Hsuan (Dustin) Ma <[email protected]>

Docs/sphinx_doc/BoundaryConditions.rst

@@ -226,3 +226,125 @@ The sponge data is input as a text file with 3 columns containing :math:`z, u, v
           erf.sponge_strength = 1000.0
           erf.use_xlo_sponge_damping = true
           erf.xlo_sponge_end = 4.0
+
+Inflow turbulence generation
+---------------------------
+
+ERF provides the capability to apply a perturbation zone at the inflow domain boundary to mechanically trip turbulence into the domain.
+
+.. |PBinflw| image:: figures/PBIllustration.png
+           :width: 600
+
+.. _fig:pb_fig:
+
+.. table:: Box perturbation method
+
+   +-----------------------------------------------------+
+   |                     |PBinflw|                       |
+   +-----------------------------------------------------+
+   |  Image taken from `DeLeon et al. (2018)`            |
+   +-----------------------------------------------------+
+
+Two different types of perturbation are currently available, ``source``, adopted from `DeLeon et al. (2018)`_
+
+..
+   _`DeLeon et al. (2018)`: https://doi.org/10.2514/1.J057245
+
+and ``direct``, adopted from `Munoz-Esparza et al. (2015)`_. The ``source`` option applies the perturbation amplitude range, `\pm \Phi_{PB}`, to each cell within the perturbation box as a source term. It's important to note that while this perturbation starts as white noise, it becomes colored noise due to the eddy viscosity turbulence closure. Conversely, the ``direct`` option applies the calculated temperature difference directly onto the `\rho \theta field`.
+
+The current implementation only supports West and South face perturbations, specified by ``erf.perturbation_direction``, where the 3 integer inputs represent the `x`, `y`, and `z` directions, respectively. The flow perturbation method requires the dimensions of an individual box input through ``erf.perturbation_box_dim``, with 3 integer inputs representing `nx_{pb}`, `ny_{pb}`, and `nz_{pb}`, respectively. Following the guidance of `Ma and Senocak (2023)`_,
+
+.. _`Ma and Senocak (2023)`: https://link.springer.com/article/10.1007/s10546-023-00786-1
+
+the general rule of thumb is to use `H_{PB} = 1/8 \delta` as the height of the perturbation box, where `\delta` is the boundary layer height. The length of the box in the x-direction should be `L_{PB} = 2H_{PB}`. Depending on the direction of the bulk flow, the width of the box in the y-direction should be defined as `W_{PB} = L_{PB} \tan{\theta_{inflow}}`. Note that the current implementation only accepts ``int`` entries. Therefore, considering the domain size and mesh resolution, the dimensions of a singular box can be determined.
+
+The specification of the number of layers and the offset into the domain of the perturbation boxes can be made through ``erf.perturbation_layers`` and ``erf.perturbation_offset``, respectively.
+
+::
+
+          erf.inlet_perturbation_type = "source"
+
+          erf.perturbation_direction = 1 0 0
+          erf.perturbation_box_dims = 8 8 4
+          erf.perturbation_layers = 3
+          erf.perturbation_offset = 1
+
+          erf.perturbation_nondimensional = 0.042
+          erf.perturbation_T_infinity = 300.0
+          erf.perturbation_T_intensity = 0.1
+
+Before delving into the details, it's important to note that the two methods are interchangeable. While we adhere to the guidelines from the referenced publications, the use of ``direct`` type forcing is not restricted to having unity cell height, nor is ``source`` type forcing limited to boxes. We have generalized the perturbation methods to allow for flexibility in mixing and matching different types of turbulence generation.
+
+Source type forcing
+-------------------
+
+The perturbation update interval is determined by the equation,
+
+.. math::
+
+   \frac{t_p \langle U(z) \rangle_{PB}}{D_{PB}} = 1,
+
+The change in the perturbation is defined as,
+
+.. math::
+
+   {Ri}_{PB} = \frac{g \beta \Delta \overline{\phi} H_{PB}}{{\langle U(z) \rangle}^2_{PB}}.
+
+The magnitude of the perturbation, ignoring the advection and diffusion effects in the transport equation can be made through a proportionality ratio between the update time and change in the box temperature,
+
+.. math::
+
+   \Phi_{PB} \propto \frac{\Delta \overliner{\phi}}{t_p}
+
+and the perturbation amplitude is determined by the equation,
+
+.. math::
+
+   \Phi_{PB} = \frac{Ri_{PB} {\langle U(z) \rangle}^3_{PB}}{g \beta D_{PB} H_{PB}}.
+
+The ``source`` type forcing can adopt the box perturbation method by having the following inputs list.
+
+::
+
+          erf.inlet_perturbation_type = "source"
+
+          erf.perturbation_direction = 1 0 0
+          erf.perturbation_box_dims = 8 8 4
+          erf.perturbation_layers = 3
+          erf.perturbation_offset = 1
+
+          erf.perturbation_nondimensional = 0.042 # Ri
+          erf.perturbation_T_infinity = 300.0
+          erf.perturbation_T_intensity = 0.1
+
+Direct type forcing
+-------------------
+
+The perturbation update interval is determined by the equation,
+.. math::
+
+   \frac{t_p U_{1}}{d_{c}}
+
+and the perturbation amplitude is determined by the equation,
+.. math::
+
+   Ec = \frac{{U_g}^2}{\rho c_p \theta_{pm}}.
+
+The ``direct`` type forcing can adopt the cell perturbation method by having the following inputs list.
+::
+
+          erf.inlet_perturbation_type = "direct"
+
+          erf.perturbation_direction = 1 0 0
+          erf.perturbation_box_dims = 8 8 1
+          erf.perturbation_layers = 3
+          erf.perturbation_offset = 1
+
+          erf.perturbation_nondimensional = 0.16 #Ec
+          erf.perturbation_rho_0 = 1.0
+          erf.perturbation_cp = 1250
+
+From `Munoz-Esparza et al. (2015)`_ the choice of the Eckert number is 0.16.
+
+..
+   _`Munoz-Esparza et al. (2015)`: https://doi.org/10.1063/1.4913572

Exec/DevTests/ABL_perturbation_inflow/CMakeLists.txt

@@ -0,0 +1,12 @@
+set(erf_exe_name erf_abl_perturbation_inflow)
+
+add_executable(${erf_exe_name} "")
+target_sources(${erf_exe_name}
+   PRIVATE
+     prob.cpp
+)
+
+target_include_directories(${erf_exe_name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+
+include(${CMAKE_SOURCE_DIR}/CMake/BuildERFExe.cmake)
+build_erf_exe(${erf_exe_name})

Exec/DevTests/ABL_perturbation_inflow/GNUmakefile

@@ -0,0 +1,34 @@
+# AMReX
+COMP = gnu
+PRECISION = DOUBLE
+
+# Profiling
+PROFILE       = FALSE
+TINY_PROFILE  = TRUE
+COMM_PROFILE  = FALSE
+TRACE_PROFILE = FALSE
+MEM_PROFILE   = FALSE
+USE_GPROF     = FALSE
+
+# Performance
+USE_MPI  = TRUE
+USE_OMP  = FALSE
+
+USE_CUDA = FALSE
+USE_HIP  = FALSE
+USE_SYCL = FALSE
+
+# Debugging
+DEBUG = TRUE
+
+TEST = TRUE
+USE_ASSERTION = TRUE
+
+#USE_POISSON_SOLVE = TRUE
+
+# GNU Make
+Bpack := ./Make.package
+Blocs := .
+ERF_HOME := ../../..
+ERF_PROBLEM_DIR = $(ERF_HOME)/Exec/DevTests/ABL_perturbation_inflow
+include $(ERF_HOME)/Exec/Make.ERF

Exec/DevTests/ABL_perturbation_inflow/Make.package

@@ -0,0 +1,2 @@
+CEXE_headers += prob.H
+CEXE_sources += prob.cpp

Exec/DevTests/ABL_perturbation_inflow/README

@@ -0,0 +1,7 @@
+This problem setup is for simulation of the Atmospheric Boundary Layer (ABL)
+using one of two turbulence schemes (Smagorinsky or Deardorff) and the bottom
+boundary condition possibly specified by Monin Obukhov Similarity Theory (MOST).
+
+This version of the ABL problem initializes the data from an input sounding file,
+and initializes turbulence at the inflow. The target is to transition turbulence
+from coarse to fine grid interface.

Exec/DevTests/ABL_perturbation_inflow/input_ReTau2000Ana_sounding.txt

@@ -0,0 +1,34 @@
+0.0 300.0 0.0
+1.00000000e-02 3.00000000e+02 0.00000000e+00 1.25066641e+01 0.00000000e+00
+3.22187500e-01 3.00000000e+02 0.00000000e+00 2.09762948e+01 0.00000000e+00
+6.34375000e-01 3.00000000e+02 0.00000000e+00 2.26287499e+01 0.00000000e+00
+9.46562500e-01 3.00000000e+02 0.00000000e+00 2.36048395e+01 0.00000000e+00
+1.25875000e+00 3.00000000e+02 0.00000000e+00 2.43000527e+01 0.00000000e+00
+1.57093750e+00 3.00000000e+02 0.00000000e+00 2.48404269e+01 0.00000000e+00
+1.88312500e+00 3.00000000e+02 0.00000000e+00 2.52825246e+01 0.00000000e+00
+2.19531250e+00 3.00000000e+02 0.00000000e+00 2.56566509e+01 0.00000000e+00
+2.50750000e+00 3.00000000e+02 0.00000000e+00 2.59809480e+01 0.00000000e+00
+2.81968750e+00 3.00000000e+02 0.00000000e+00 2.62671427e+01 0.00000000e+00
+3.13187500e+00 3.00000000e+02 0.00000000e+00 2.65232545e+01 0.00000000e+00
+3.44406250e+00 3.00000000e+02 0.00000000e+00 2.67550102e+01 0.00000000e+00
+3.75625000e+00 3.00000000e+02 0.00000000e+00 2.69666429e+01 0.00000000e+00
+4.06843750e+00 3.00000000e+02 0.00000000e+00 2.71613695e+01 0.00000000e+00
+4.38062500e+00 3.00000000e+02 0.00000000e+00 2.73416924e+01 0.00000000e+00
+4.69281250e+00 3.00000000e+02 0.00000000e+00 2.75095964e+01 0.00000000e+00
+5.00500000e+00 3.00000000e+02 0.00000000e+00 2.76666826e+01 0.00000000e+00
+5.31718750e+00 3.00000000e+02 0.00000000e+00 2.78142609e+01 0.00000000e+00
+5.62937500e+00 3.00000000e+02 0.00000000e+00 2.79534168e+01 0.00000000e+00
+5.94156250e+00 3.00000000e+02 0.00000000e+00 2.80850600e+01 0.00000000e+00
+6.25375000e+00 3.00000000e+02 0.00000000e+00 2.82099603e+01 0.00000000e+00
+6.56593750e+00 3.00000000e+02 0.00000000e+00 2.83287750e+01 0.00000000e+00
+6.87812500e+00 3.00000000e+02 0.00000000e+00 2.84420696e+01 0.00000000e+00
+7.19031250e+00 3.00000000e+02 0.00000000e+00 2.85503344e+01 0.00000000e+00
+7.50250000e+00 3.00000000e+02 0.00000000e+00 2.86539970e+01 0.00000000e+00
+7.81468750e+00 3.00000000e+02 0.00000000e+00 2.87534328e+01 0.00000000e+00
+8.12687500e+00 3.00000000e+02 0.00000000e+00 2.88489730e+01 0.00000000e+00
+8.43906250e+00 3.00000000e+02 0.00000000e+00 2.89409114e+01 0.00000000e+00
+8.75125000e+00 3.00000000e+02 0.00000000e+00 2.90295098e+01 0.00000000e+00
+9.06343750e+00 3.00000000e+02 0.00000000e+00 2.91150023e+01 0.00000000e+00
+9.37562500e+00 3.00000000e+02 0.00000000e+00 2.91975993e+01 0.00000000e+00
+9.68781250e+00 3.00000000e+02 0.00000000e+00 2.92774905e+01 0.00000000e+00
+1.00000000e+01 3.00000000e+02 0.00000000e+00 2.93548477e+01 0.00000000e+00

Exec/DevTests/ABL_perturbation_inflow/input_ReTau2000Ana_sponge.txt

@@ -0,0 +1,33 @@
+1.00000000e-02 1.25066641e+01 0.00000000e+00
+3.22187500e-01 2.09762948e+01 0.00000000e+00
+6.34375000e-01 2.26287499e+01 0.00000000e+00
+9.46562500e-01 2.36048395e+01 0.00000000e+00
+1.25875000e+00 2.43000527e+01 0.00000000e+00
+1.57093750e+00 2.48404269e+01 0.00000000e+00
+1.88312500e+00 2.52825246e+01 0.00000000e+00
+2.19531250e+00 2.56566509e+01 0.00000000e+00
+2.50750000e+00 2.59809480e+01 0.00000000e+00
+2.81968750e+00 2.62671427e+01 0.00000000e+00
+3.13187500e+00 2.65232545e+01 0.00000000e+00
+3.44406250e+00 2.67550102e+01 0.00000000e+00
+3.75625000e+00 2.69666429e+01 0.00000000e+00
+4.06843750e+00 2.71613695e+01 0.00000000e+00
+4.38062500e+00 2.73416924e+01 0.00000000e+00
+4.69281250e+00 2.75095964e+01 0.00000000e+00
+5.00500000e+00 2.76666826e+01 0.00000000e+00
+5.31718750e+00 2.78142609e+01 0.00000000e+00
+5.62937500e+00 2.79534168e+01 0.00000000e+00
+5.94156250e+00 2.80850600e+01 0.00000000e+00
+6.25375000e+00 2.82099603e+01 0.00000000e+00
+6.56593750e+00 2.83287750e+01 0.00000000e+00
+6.87812500e+00 2.84420696e+01 0.00000000e+00
+7.19031250e+00 2.85503344e+01 0.00000000e+00
+7.50250000e+00 2.86539970e+01 0.00000000e+00
+7.81468750e+00 2.87534328e+01 0.00000000e+00
+8.12687500e+00 2.88489730e+01 0.00000000e+00
+8.43906250e+00 2.89409114e+01 0.00000000e+00
+8.75125000e+00 2.90295098e+01 0.00000000e+00
+9.06343750e+00 2.91150023e+01 0.00000000e+00
+9.37562500e+00 2.91975993e+01 0.00000000e+00
+9.68781250e+00 2.92774905e+01 0.00000000e+00
+1.00000000e+01 2.93548477e+01 0.00000000e+00