Damping refactor and enhancement

docs/sphinx/user/inputs.rst

@@ -97,6 +97,7 @@ documentation provided here might not work with older releases.
    inputs_turbulence.rst
    inputs_Momentum_Sources.rst
    inputs_Temperature_Sources.rst
+   inputs_DampingLayer.rst
    inputs_TKE_Sources.rst
    inputs_ABL.rst
    inputs_ABL_meso_forcing.rst

docs/sphinx/user/inputs_DampingLayer.rst

@@ -0,0 +1,185 @@
+.. _inputs_damping_layer:
+
+Section: DampingLayer
+~~~~~~~~~~~~~~~~~~~~~
+
+The DampingLayer physics module creates one or more spatially varying damping
+coefficient fields near selected domain boundaries. The DampingLayerSource
+source term then uses those coefficients to relax solved fields toward user-
+defined targets.
+
+Activate DampingLayer by including it in :input_param:`incflo.physics`.
+
+Activate DampingLayerSource for each equation you want to damp, for example:
+
+- ``ICNS.source_terms = DampingLayerSource``
+- ``temperature.source_terms = DampingLayerSource``
+- ``TKE.source_terms = DampingLayerSource``
+
+Additional scalar equations that expose source-term controls can also use
+``DampingLayerSource``.
+
+.. input_param:: DampingLayer.fields
+
+   **type:** List of strings, mandatory when ``DampingLayer`` is active
+
+   Field labels that will have damping-layer coefficient fields created.
+   Typical values include ``velocity``, ``temperature``, ``density``, ``tke``,
+   and ``sdr``.
+
+For each entry in :input_param:`DampingLayer.fields`, parameters are configured
+per boundary using:
+
+``DampingLayer.<field>.<boundary>.*`` where ``boundary`` is one of
+``xlo``, ``xhi``, ``ylo``, ``yhi``, ``zlo``, or ``zhi``.
+
+.. input_param:: DampingLayer.<field>.<boundary>.thickness
+
+   **type:** Real, optional
+
+   Thickness of the damping region for this boundary. A value ``> 0`` enables
+   damping on that boundary for this field.
+
+.. input_param:: DampingLayer.<field>.<boundary>.blending_fraction
+
+   **type:** Real, optional, default = 0.0
+
+   Fraction of ``thickness`` used as a ramp from full damping to zero damping.
+   The remaining fraction applies full damping.
+
+.. input_param:: DampingLayer.<field>.<boundary>.blending_function_type
+
+   **type:** String, optional, default = cosine
+
+   Shape of the ramp region. Supported values are ``linear``, ``quadratic``,
+   ``exponential``, and ``cosine``.
+
+.. input_param:: DampingLayer.<field>.<boundary>.minimum_height
+
+   **type:** Real, optional (only for ``x*`` and ``y*`` boundaries)
+
+   Adds a vertical limiter so horizontal boundary damping is only applied above
+   this height. This parameter is not valid on ``zlo`` or ``zhi``.
+
+.. input_param:: DampingLayer.<field>.<boundary>.vertical_blending_thickness
+
+   **type:** Real, mandatory when ``minimum_height`` is provided
+
+   Vertical blending thickness used by the vertical limiter activated through
+   ``minimum_height``. This parameter is only valid on ``x*`` and ``y*``
+   boundaries.
+
+.. input_param:: DampingLayer.<field>.<boundary>.vertical_blending_function_type
+
+   **type:** String, optional, default = cosine
+
+   Shape for blending in the vertical direction. Supported values are ``linear``,
+   ``quadratic``, ``exponential``, and ``cosine``. This parameter is only
+   valid on ``x*`` and ``y*`` boundaries.
+
+DampingLayerSource target parameters are configured with the same namespace:
+
+``DampingLayer.<field>.<boundary>.*``
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_type
+
+   **type:** String, mandatory when damping is active on a boundary
+
+   Target mode for the relaxed value. Supported values are ``constant``,
+   ``profile``, ``function``, and ``field``.
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_value
+
+   **type:** List of Real, mandatory for ``target_type = constant``
+
+   Constant target value per component. The number of values must match the
+   number of components in the damped field.
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_profile_heights
+
+   **type:** List of Real, mandatory for ``target_type = profile``
+
+   Monotone height coordinates used for profile interpolation.
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_profile_values
+
+   **type:** List of Real, optional for ``target_type = profile``
+
+   Convenience form for scalar or x-component profile values.
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_profile_values_x
+
+   **type:** List of Real, optional for ``target_type = profile``
+
+   x-component profile values.
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_profile_values_y
+
+   **type:** List of Real, optional for ``target_type = profile``
+
+   y-component profile values.
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_profile_values_z
+
+   **type:** List of Real, optional for ``target_type = profile``
+
+   z-component profile values.
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_function
+
+   **type:** String expression, mandatory for ``target_type = function``
+
+   Expression parsed at runtime. Available variables are ``t``, ``x``, ``y``,
+   ``z``, and ``n`` (component index).
+
+.. input_param:: DampingLayer.<field>.<boundary>.target_field
+
+   **type:** String, mandatory for ``target_type = field``
+
+   Name of another field used as the target value. This could work with a field
+   created by a utility or post-processing routine, such as an averaging field,
+   or a field created by a dedicated physics module.
+
+.. input_param:: DampingLayer.<field>.<boundary>.damped_components
+
+   **type:** List of Integer, optional
+
+   Per-component on/off mask for damping. The list length must match the
+   number of components in the damped field, and each entry must be either
+   ``0`` (off) or ``1`` (on). If omitted, all components default to ``1``.
+
+Example
+^^^^^^^
+
+.. code-block:: console
+
+   incflo.physics = ABL DampingLayer
+   DampingLayer.fields = velocity temperature
+
+   ICNS.source_terms = BoussinesqBuoyancy DampingLayerSource
+   temperature.source_terms = DampingLayerSource
+
+   DampingLayer.velocity.xlo.thickness = 150.0
+   DampingLayer.velocity.xlo.blending_fraction = 0.25
+   DampingLayer.velocity.xlo.blending_function_type = linear
+   DampingLayer.velocity.xlo.minimum_height = 100.0
+   DampingLayer.velocity.xlo.vertical_blending_thickness = 80.0
+   DampingLayer.velocity.xlo.vertical_blending_function_type = cosine
+   DampingLayer.velocity.xlo.target_type = constant
+   DampingLayer.velocity.xlo.target_value = 8.0 0.0 0.0
+   DampingLayer.velocity.xlo.damped_components = 1 0 0
+
+   DampingLayer.velocity.ylo.thickness = 120.0
+   DampingLayer.velocity.ylo.blending_fraction = 0.5
+   DampingLayer.velocity.ylo.blending_function_type = quadratic
+   DampingLayer.velocity.ylo.target_type = profile
+   DampingLayer.velocity.ylo.target_profile_heights = 0.0 500.0 1000.0
+   DampingLayer.velocity.ylo.target_profile_values_x = 6.0 7.0 8.0
+   DampingLayer.velocity.ylo.target_profile_values_y = 0.0 0.5 1.0
+   DampingLayer.velocity.ylo.target_profile_values_z = 0.0 0.0 0.0
+
+   DampingLayer.temperature.zhi.thickness = 200.0
+   DampingLayer.temperature.zhi.blending_fraction = 0.4
+   DampingLayer.temperature.zhi.blending_function_type = cosine
+   DampingLayer.temperature.zhi.target_type = function
+   DampingLayer.temperature.zhi.target_function = "300.0 + 0.01*z"

docs/sphinx/user/inputs_Momentum_Sources.rst

@@ -307,6 +307,16 @@ Section: Momentum Sources
    when the form drag is known to be under-resolved.
 
 
+The following arguments are used when ``DampingLayerSource`` is included in
+:input_param:`ICNS.source_terms`.
+
+   See :ref:`inputs_damping_layer` for the full list of
+   ``DampingLayer.velocity.<boundary>.*`` options, including
+   ``target_type`` modes (``constant``, ``profile``, ``function``, ``field``),
+   component filtering with ``damped_components``, and blending controls from
+   the DampingLayer physics module.
+
+
 The following arguments are influential when ``GravityForcing`` is included in :input_param:`ICNS.source_terms`.
 
    .. input_param:: ICNS.use_perturb_pressure

docs/sphinx/user/inputs_Temperature_Sources.rst

@@ -30,6 +30,12 @@ Section: Temperature Sources
    the time step size.
 
 
+When ``DampingLayerSource`` is included in
+:input_param:`temperature.source_terms`, configure it using
+``DampingLayer.temperature.<boundary>.*`` parameters documented in
+:ref:`inputs_damping_layer`.
+
+
 The following list of inputs are used with the `Temperature.source_terms = PerturbationForcing` option to add perturbation to the 
 temperature field to generate flow structures for LES when the inflow data is coarse or uniform flow condition. Not 
 recommended for use with RANS models. 

docs/sphinx/user/inputs_incflo.rst

@@ -12,7 +12,7 @@ as initial conditions and discretization options.
 
    Specify a string or a list of strings for each type of physics to initialize and simulate.
    Physics is additive and more than one type of physics may be used.
-   Current implemented physics include FreeStream, SyntheticTurbulence, ABL, Actuator, RayleighTaylor, BoussinesqBubble, TaylorGreenVortex, and ScalarAdvection (which is an example of using a passive scalar advection) among others.
+   Current implemented physics include FreeStream, SyntheticTurbulence, ABL, DampingLayer, Actuator, RayleighTaylor, BoussinesqBubble, TaylorGreenVortex, and ScalarAdvection (which is an example of using a passive scalar advection) among others.
    For multiphase simulations, the MultiPhase physics must be specified, and for forcing wave profiles into the domain, the OceanWaves physics must be specified as well.
    For immersed boundary forcing method, :ref:`TerrainDrag <inputs_terraindrag>` or :ref:`ChannelBuilder <inputs_channel_builder>` can be used.
    For representing forested regions :ref:`ForestDrag <inputs_forestdrag>` must be specified, which has two file-based approaches to parameterize forest drag models.

src/equation_systems/CMakeLists.txt

@@ -11,3 +11,4 @@ add_subdirectory(sdr)
 add_subdirectory(levelset)
 add_subdirectory(vof)
 add_subdirectory(passive_scalar)
+add_subdirectory(source_terms)

src/equation_systems/source_terms/CMakeLists.txt

@@ -0,0 +1,3 @@
+target_sources(${kynema_sgf_lib_name} PRIVATE
+  DampingLayerSource.cpp
+  )