.. _ablProperties-section: `ABLProperties.dat` ~~~~~~~~~~~~~~~~~~~ When the ``-abl`` flag is activated in the ``control.dat`` file, TOSCA is prompted to read the ``ABLProperties.dat`` file. This contains important settings that can be activated for ABL or wind farm simulations with potential temperature stratification. For example, this file contains settings for the potential temperature profile, it allows to activate velocity controllers, used to drive the flow when laterally-periodic simulations are applied, the potential temperature controller, used to fix the potential temperature profile over time, fringe and damping regions, as well as the geostrophic damper, which avoids inertial oscillations produced when the flow is not initialized in geostrophic balance and the Coriolis force is active. It is also in this file that one can activate TOSCA's canopy model or the concurrent precursor method. Primarily, this file contains entries that are required by TOSCA when the ``-abl`` flag is activated. In addition, it contains dictionaries that are required when additional flags are activated in the ``control.dat`` file, which are only used for ABL flows. For example, the ``xDampingProperties`` dictionary is only read if ``-xDampingLayer`` is set to 1 in the ``control.dat`` file. The folliwing table summarizes all entries and dictionaries available in the ``ABLProperties.dat``. A description of entries specific to each dictionaries is given in the subsequent tables. .. table:: :widths: 32, 15, 53 :align: center =================================== ============== ================================================== **entry name** **entry type** **description** ----------------------------------- -------------- -------------------------------------------------- ``hRough`` scalar equivalent roughness length in m used to set set the initial velocity condition when ``internalField`` is set to *ABLFlow* in the ``boundary/U`` file. ----------------------------------- -------------- -------------------------------------------------- ``uRef`` 2D vector reference velocity in m/s used to set set the initial condition when ``internalField`` is set to *ABLFlow* in the ``boundary/U`` file. The initial wind will be a logarthmic profile with this value of velocity at ``hRef``. It is also used by the velocity controller when ``controllerType`` is set to *pressure* inside the ``controllerProperties`` dictionary. Must be specified as: .. code-block:: C uRef (uRef_x uRef_y) where ``uRef_x`` and ``uRef_y`` are the x and y velocity components, respectively. The vertical component is always set to zero. ----------------------------------- -------------- -------------------------------------------------- ``hRef`` scalar reference height in m used to set set the initial condition when ``internalField`` is set to *ABLFlow* in the ``boundary/U`` file. The initial wind will be a logarthmic profile with velocity ``uRef`` at this height. It is also used by the velocity controller when ``controllerType`` is set to *pressure* inside the ``controllerProperties`` dictionary. ----------------------------------- -------------- -------------------------------------------------- ``hInv`` scalar inversion layer height in m used to set set the initial potential temperature condition when ``internalField`` is set to *ABLFlow* in the ``boundary/T`` file. ----------------------------------- -------------- -------------------------------------------------- ``dInv`` scalar inversion layer wifth in m used to set set the initial potential temperature condition when ``internalField`` is set to *ABLFlow* in the ``boundary/T`` file. ----------------------------------- -------------- -------------------------------------------------- ``gInv`` scalar inversion layer strength in K used to set set the initial potential temperature condition when ``internalField`` is set to *ABLFlow* in the ``boundary/T`` file. ----------------------------------- -------------- -------------------------------------------------- ``gTop`` scalar lapse rate above inversion in K/m used to set set the initial potential temperature condition when ``internalField`` is set to *ABLFlow* in the ``boundary/T`` file. ----------------------------------- -------------- -------------------------------------------------- ``gABL`` scalar lapse rate below inversion in K/m used to set set the initial potential temperature condition when ``internalField`` is set to *ABLFlow* in the ``boundary/T`` file. ----------------------------------- -------------- -------------------------------------------------- ``tRef`` scalar reference potential temperaure used to set set the initial potential temperature condition when ``internalField`` is set to *ABLFlow* in the ``boundary/T`` file. This is also assumed as a reference temperature throughout the simulation. ----------------------------------- -------------- -------------------------------------------------- ``vkConst`` scalar von Karman constant. ----------------------------------- -------------- -------------------------------------------------- ``smearT`` scalar smearing parameter used to define how sharp the initial potential temperaure profile is, when when ``internalField`` is set to *ABLFlow* in the ``boundary/T`` file. Suggested value is 0.33. ----------------------------------- -------------- -------------------------------------------------- ``coriolisActive`` bool Coriolis force activation flag. ----------------------------------- -------------- -------------------------------------------------- ``fCoriolis`` scalar Coriolis parameter. Should be computed as :math:`10^{-5} \cdot 7.272205217sin(\phi)`, where :math:`\phi` is latitude. ----------------------------------- -------------- -------------------------------------------------- ``controllerActive`` bool Velocity controller activation flag. Requires ``controllerProperties`` dictionary. ----------------------------------- -------------- -------------------------------------------------- ``controllerActiveT`` bool Temperature controller activation flag. The target laterally-averaged potential temperature profile that the controller aims at maintaining is the initial one. Requires ``controllerProperties`` dictionary. ----------------------------------- -------------- -------------------------------------------------- ``controllerActivePrecursorT`` bool Temperature controller activation flag. Same as ``controllerActiveT``, but for the concurrent precursor simulation. Requires ``controllerProperties`` dictionary. ----------------------------------- -------------- -------------------------------------------------- ``precursorControllerTypeMismatch`` bool Requires ``xDampingLayer`` active in the ``control.dat`` file, and ``uBarSelectionType`` set to 3, corresponding to the concurrent precursor method, inside ``xDampingProperties`` dictionary. Should be activated if the concurrent precursor's velocity controller differs from the successor's. For example, if precursor uses ``controllerAction`` *write*, while successor reads the momentum sources computed by the precursor using ``controllerAction`` *read* and ``controllerType`` *timeSeriesFromPrecursor* in the ``controllerProperties`` dictionary. It requires the ``fringeControllerProperties`` dictionary in order to specify the controller parameters for the concurrent precursor domain. ----------------------------------- -------------- -------------------------------------------------- ``controllerTypeT`` string Available types are: - *initial* - *directProfileAssimilation* - *indirectProfileAssimilation* Type *initial* tries to maintain the initial horizontally averaged potential temperature profile. Types *directProfileAssimilation* and *indirectProfileAssimilation* calculate source terms to follow a provided time-series of potential temperature profile. They require additional entries in the ``controllerProperties`` subdictionary, i.e. ``relaxPI``, ``lowestSrcHeight``, ``highestSrcHeight``. Moreover, ``polynomialOrder`` is also required for controller type *indirectProfileAssimilation*. ----------------------------------- -------------- -------------------------------------------------- ``perturbations`` bool Adds divergence-free sinusoidal perturbations to triger turbulence in the initial condition when ``internalField`` is set to *ABLFlow* in the ``boundary/U`` file. ----------------------------------- -------------- -------------------------------------------------- ``controllerProperties`` dictionary Contains inputs for velocity and temperature controllers. Required when ``controllerActive``, ``controllerActiveT`` or ``controllerActivePrecursorT`` are set to 1. Usage: .. code-block:: C controllerProperties { controllerAction string controllerType string relaxPI scalar alphaPI scalar timeWindowPI scalar geostrophicDamping bool geoDampingAlpha scalar geoDampingStartTime scalar geoDampingTimeWindow scalar hGeo scalar alphaGeo scalar uGeoMag scalar controllerAvgStartTime scalar controllerMaxHeight scalar } ----------------------------------- -------------- -------------------------------------------------- ``fringeControllerProperties`` dictionary Contains inputs for precursor velocity controller. Required when ``precursorControllerTypeMismatch`` is set to 1. Usage is similar to ``controllerProperties`` Usage: .. code-block:: C fringeControllerProperties { controllerAction string controllerType string relaxPI scalar alphaPI scalar timeWindowPI scalar mesoScaleInput bool geostrophicDamping bool geoDampingAlpha scalar geoDampingStartTime scalar geoDampingTimeWindow scalar hGeo scalar alphaGeo scalar uGeoMag scalar controllerAvgStartTime scalar controllerMaxHeight scalar } ----------------------------------- -------------- -------------------------------------------------- ``xDampingProperties`` dictionary Defines fringe region parameters, activated with ``-xDampingLayer`` 1 in ``control.dat``. Usage: .. code-block:: C xDampingProperties { xDampingStart scalar xDampingEnd scalar xDampingDelta scalar xDampingAlpha scalar xDampingAlphaControlType scalar xDampingLineSamplingYmin scalar xDampingLineSamplingYmax scalar xDampingTimeWindow scalar uBarSelectionType integer // additional parameters depending // on uBarSelectionType (see next // table) } The *uBarSelectionType* entry defines how the reference wind field is calculated inside the fringe region, and it requires additional parameters depending on the type. The **concurrent precursor** (i.e. when this reference field is solved concurrently with the main simulation) is activated by setting the *uBarSelectionType* to 3. TOSCA creates the second simulation instance automatically, without requiring additional user parameters. ----------------------------------- -------------- -------------------------------------------------- ``yDampingProperties`` dictionary Defines lateral fringe region parameters, activated with ``-yDampingLayer`` 1 in ``control.dat``. Usage: .. code-block:: C yDampingProperties { yDampingStart scalar yDampingEnd scalar yDampingDelta scalar yDampingAlpha scalar } ----------------------------------- -------------- -------------------------------------------------- ``zDampingProperties`` dictionary Defines Reyleigh damping layer parameters, activated with ``-zDampingLayer`` 1 in ``control.dat``. Usage: .. code-block:: C zDampingProperties { zDampingStart scalar zDampingEnd scalar zDampingAlpha scalar zDampingAlsoXY bool zDampingXYType integer } ----------------------------------- -------------- -------------------------------------------------- ``advectionDampingXProperties`` dictionary Defines x-advection damping regions parameters. This corresponds to the technique developed by Lanzilao and Meyers (2022a). It is activated with ``-advectionDampingX`` 1 in ``control.dat``. Usage: .. code-block:: C advectionDampingXProperties { advDampingStart scalar advDampingEnd scalar advDampingDeltaStart scalar advDampingDeltaEnd scalar } ----------------------------------- -------------- -------------------------------------------------- ``advectionDampingYProperties`` dictionary Defines y-advection damping regions parameters. Requires ``-yDampingLayer`` set to 1 in ``control.dat``. This is only available when ``uBarSelectionType`` is set to 3, corresponding to the concurrent precursor method. This corresponds to the technique developed by Lanzilao and Meyers (2022a). It is activated with ``-advectionDampingY`` 1 in ``control.dat``. Usage: .. code-block:: C advectionDampingYProperties { advDampingStart scalar advDampingEnd scalar advDampingDeltaStart scalar advDampingDeltaEnd scalar } ----------------------------------- -------------- -------------------------------------------------- ``kLeftDampingProperties`` dictionary Defines Rayleigh damping layer at the *kLeft* patch. Requires ``-kLeftRayleigh`` set to 1 in ``control.dat``. Damping transitions from zero to max across a layer of width *kLeftFilterWidth* centered at *kLeftFilterHeight* and is applied between the *kLeft* patch and a plane at a distance *kLeftPatchDist* from the *kLeft* patch to obtain the desired velocity *kLeftDampingUBar*. Usage: .. code-block:: C kLeftDampingProperties { kLeftPatchDist scalar kLeftDampingAlpha scalar kLeftDampingUBar vector kLeftFilterHeight scalar kLeftFilterWidth scalar } ----------------------------------- -------------- -------------------------------------------------- ``kRightDampingProperties`` dictionary Defines Rayleigh damping layer at the *kRight* patch. Requires ``-kRightRayleigh`` set to 1 in ``control.dat``. Damping transitions from zero to max across a layer of width *kRightFilterWidth* centered at *kRightFilterHeight* and is applied between the *kRight* patch and a plane at a distance *kRightPatchDist* from the *kRight* patch to obtain the desired velocity *kRightDampingUBar*. Usage: .. code-block:: C kRightDampingProperties { kRightPatchDist scalar kRightDampingAlpha scalar kRightDampingUBar vector kRightFilterHeight scalar kRightFilterWidth scalar } ----------------------------------- -------------- -------------------------------------------------- ``canopyProperties`` dictionary Defines input parameters for the canopy model. Requires ``-canopy`` set to 1 in ``control.dat`` file. Usage: .. code-block:: C canopyProperties { xStartCanopy scalar xEndCanopy scalar yStartCanopy scalar yEndCanopy scalar zStartCanopy scalar zEndCanopy scalar cftCanopy scalar diskDirCanopy vector } =================================== ============== ================================================== The meaning of the entires required in the dictionaries listed in the above table are described in the following tables. controllerProperties & fringeControllerProperties ************************************************* .. table:: :widths: 35, 20, 45 :align: center ============================= ================== ===================================================================================== **entry** **entry type** **description** ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``relaxPI`` scalar controller gain. To be set between 0 and 1. Used by all controllers characterized by a ``controllerAction`` of type *write*. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``controllerMaxHeight`` although it is good practice to apply the source term throughout the whole vertical extent of the domain, this can be used to avoid applying the driving source term above a specified height, to be specified in meters. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``controllerAction`` string can be set to *write* or *read*. The former controls the flow based on different types of calculated driving pressure gradients, then writes the source terms to file. The latter reads these previously written source terms and directly applies them with no feedback controlling action. This keyword has to be set in combination with ``controllerType``. Types *pressure*, *geostrophic*, *directProfileAssimilation* and *indirectProfileAssimilation* require ``controllerAction`` set to *write*, while *timeSeries*, *timeAverageSeries* and *timeHeightSeries* require ``controllerAction`` set to *read*. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``controllerType`` string Available types are: - *pressure* - *geostrophic* - *timeSeries* - *timeAverageSeries* - *timeHeightSeries* - *directProfileAssimilation* - *indirectProfileAssimilation* - *waveletProfileAssimilation* Type *pressure* is the basic PI controller for ABL simulations, it tries to maintain a wind speed of magnitude ``uRef`` at ``hRef``. It writes the required source terms to file, which can be used later in wind farm simulations that employ inlet-outlet BCs. This is done through the *timeSeries* or *timeAverageSeries*, where source terms are read at each time step or averaged, respectively, from the ``inflowDatabase/momentumSource`` file. When trying to attain a specific wind at ``hRef`` inside the boundary layer and the Coriolis force is active, the *pressure* controller produces inertial oscillations of the geostrophic wind, since it is impossible to initialize the flow in geostrophic balance. In this case, one should either use ``geostrophicDamping`` or controller type *geostrophic*. The latter tries to attain a velocity ``uGeoMag`` at ``hGeo`` (which should be set above the boundary layer). The wind field is then rotated such that the flow is aligned with the x-axis at ``hRef``. Notably, at every restart the initial geostrophic wind angle ``alphaGeo`` w.r.t. the x-axis **should be correctly set** (the user can take this info in the last iteration of the previous run, printed on the log file). The *pressure* type controller is the preferred one and the most tested. TOSCA also features profile assimilation techniques, used to drive the flow using observation profiles. These can be set with controller types *directProfileAssimilation* or *indirectProfileAssimilation*, and require the observed time series inside ``inflowDatabase/mesoscaleData``. An example can be found in *tests/IndirectProfileAssimilationTest*. Once these controllers compute and write the time series of source terms to file, this can be re-applied within a wind farm simulation using the controller type *timeHeightSeries*. Recently, the *waveletProfileAssimilation* controller type has been also introduced. To use this controller, please see the *tests/WaveletProfileAssimilationTest*. Note that it requires TOSCA to be compiled with the USE_PYTHON flag set to 1. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``alphaPI`` scalar proportional over integral controlling action used by all controllers characterized by a ``controllerAction`` of type *write*. A too low value makes the controller unstable, usually set between 0.6 and 0.9. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``timeWindowPI`` scalar time filter for integral part of the controller, used by all controllers characterized by a ``controllerAction`` of type *write*. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``mesoScaleInput`` bool allows to simulate prescribed wind direction changes. Available only for controller type *pressure*. The target velocity data should be contained inside the ``inflowDatabase/mesoscaleData`` directory. See *tests/IndirectProfileAssimilationTest* for an example of the required data format. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``geostrophicDamping`` bool activates geostrophic damping to remove inertial oscillations. Only for controller type *pressure*. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``geoDampingAlpha`` scalar ratio of damping over critical damping coefficient, usually set to 1.0 (critical damping). Values above 1.0 mean over-damping, values below 1.0 mean under-damping. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``geoDampingStartTime`` start time of geostrophic damping action. Has to be long enough to provide a good guess on the geostrophic wind components. Usually set greater than one period of inertial oscillation (:math:`2\pi/f_c`). ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``geoDampingTimeWindow`` scalar time filter of the deduced geostrophic wind components. Usually set to 1/10 of the inertial oscillation period (:math:`0.2\pi/f_c`). ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``hGeo`` scalar height used to sample the geostrophic wind components if the controller is of type *geostrophic*, disregarded otherwise. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``alphaGeo`` scalar initial wind angle with respect to the x-axis at ``hGeo``. **This as to be set at every restart of the simulation**. For the first run, one can initialize the wind aligned with the x-axis and this parameter to zero. Then, the controller will start to slowly rotate the wind. The wind angle at ``hGeo`` will be printed in the log file and the user can set this parameter to the value obtained at the last iteration of the previous run when restarting. Note, only for controller of type *geostrophic*, disregarded otherwise. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``uGeoMag`` scalar desired geostrophic wind magnitude is the controller is of type *geostrophic*, disregarded otherwise. At the first run, the initial flow should match this value at ``hGeo`` to avoid inertial oscillations. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``controllerAvgStartTime`` scalar time after which source terms are averaged before being applied. Used for controller type *timeAverageSeries*. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``avgSources`` bool whether or not to filter the calculated source terms for controller types *directProfileAssimilation* and *indirectProfileAssimilation*. Requires ``movingAvgWindow``. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``movingAvgWindow`` scalar moving average time window used by controller types *directProfileAssimilation* and *indirectProfileAssimilation* to filter the calculated source terms. Usually on the order of 100 s. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``lowestSrcHeight`` scalar Source term is constant below this height. Used by controller types *directProfileAssimilation* and *indirectProfileAssimilation* to avoid interfering with the SGS model inside the boundary layer. Usually set to the mean boundaryr layer height. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``highestSrcHeight`` scalar Source term is constant above this height. Used by controller types *directProfileAssimilation* and *indirectProfileAssimilation*. Usually not required so set above the max domain height. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``polynomialOrder`` integer Polynomial order for source term fitting used by controller type *indirectProfileAssimilation*. Usually set to 5th order. ============================= ================== ===================================================================================== xDampingProperties ****************** .. table:: :widths: 35, 20, 45 :align: center ============================= ================== ===================================================================================== **entry** **entry type** **description** ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xDampingStart`` scalar start x coordinate of the x fringe region in meters. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xDampingEnd`` scalar end x coordinate of the x fringe region in meters. Should be greather than ``xDampingStart``. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xDampingDelta`` scalar distance over which the damping action goes from 0 to :math:`\alpha`. It must be smaller than (``xDampingEnd`` - ``xDampingStart``)/2. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xDampingAlpha`` scalar damping coefficient :math:`\alpha`. Usually set to 0.3. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``uBarSelectionType`` integer type of reference velocity computation within the fringe region. This allows to activate the concurrent precursor method. * ``uBarSelectionType`` 0 : corresponds to inletFunction 2 throughout the fringe region, requires the same parameters inside ``xDampingProperties``. * ``uBarSelectionType`` 1: corresponds to inletFunction 3 throughout the fringe region, requires the same parameters inside ``xDampingProperties``. * ``uBarSelectionType`` 2: corresponds to inletFunction 4 throughout the fringe region, requires the same parameters inside ``xDampingProperties``. * ``uBarSelectionType`` 3: corresponds concurrent precursor, no additional parameters are required, TOSCA creates a child case inferring all inputs from files. * ``uBarSelectionType`` 4: corresponds to inletFunction 5 throughout the fringe region, requires the same parameters inside ``xDampingProperties``. See section :ref:`boundary-subsection` for details on inletFunctions. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xDampingAlphaControlType`` string type of alpha computation, only for concurrent precursor method (i.e. ``uBarSelectionType`` = 3). Most used type is *alphaFixed*, where the damping coefficient is specified by ``xDampingAlpha``. Moreover, we developed an experimental variable-alpha fringe region, selectable using *alphaOptimized*, where the damping coefficient is optimized in time. In particular, TOSCA tries to find the minimum :math:`\alpha` that allows to obtain an average velocity over a line spanning the domain along y, located at ``hRef`` and close to the exit of the fringe region, which is as close as possibe to the velocity sampled on the same line defined in the concurrent precursor domain. Alpha is slowly increased until the two velocity match. This is meant to be used for tuning runs with a coarse mesh. The resulting alpha can then be set using *alphaFixed* for production runs. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xDampingLineSamplingYmin`` scalar minimum y of the line located at the fringe exit and at a height of ``hRef``. Only required if ``xDampingAlphaControlType`` is set to *alphaOptimized*. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xDampingLineSamplingYmax`` scalar maximum y of the line located at the fringe exit and at a height of ``hRef``. Only required if ``xDampingAlphaControlType`` is set to *alphaOptimized*. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xDampingTimeWindow`` scalar time window for error filtering. Sould be greater or equal than a fringe flow turnover time. Only required if ``xDampingAlphaControlType`` is set to *alphaOptimized*. ============================= ================== ===================================================================================== yDampingProperties ****************** .. table:: :widths: 35, 20, 45 :align: center ============================= ================== ===================================================================================== **entry** **entry type** **description** ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``yDampingStart`` scalar start y coordinate of the y fringe region in meters. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``yDampingEnd`` scalar end y coordinate of the y fringe region in meters. Should be greather than ``yDampingStart``. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``yDampingDelta`` scalar distance over which the damping action goes from 0 to :math:`\alpha`. It must be smaller than (``yDampingEnd`` - ``yDampingStart``)/2. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``yDampingAlpha`` scalar damping coefficient :math:`\alpha`. Usually set to 0.3. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``yDampingNumPeriods`` integer TOSCA uses a tiling approach which maps data from the x fringe region to the y fringe region in order to define the unperturbed velocity and temperature fields within the y fringe region. Hence, y fringe region is only available when also the x fringe region is active, and when the ``uBarSelectionType`` is set to 3. Usage of the y fringe region is subject to two main constraints: * :math:`L_x` / (``xDampingEnd`` - ``xDampingStart``) = ``yDampingNumPeriods``, where :math:`L_x` is the streamwise domain length. * the end of the x fringe region should coincide with a mesh coordinate in the x axis. These two constraints are checked, so not satisfying them will result in an error. ============================= ================== ===================================================================================== zDampingProperties ****************** .. table:: :widths: 35, 20, 45 :align: center ============================= ================== ===================================================================================== **entry** **entry type** **description** ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``zDampingStart`` scalar start z coordinate of the z Rayleigh damping layer in meters. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``zDampingEnd`` scalar end z coordinate of the z Rayleigh damping layer in meters. Should be greather than ``zDampingStart``, usually it is set coincident with the top of the computational domain. Notably, the damping action goes from 0 at ``zDampingStart`` to :math:`\alpha` at ``zDampingEnd``, so setting the latter to values higher than the domain height is wrong. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``zDampingAlpha`` scalar damping coefficient :math:`\alpha`. Usually set to :math:`3\sqrt{g\Gamma/\theta_0}`, where :math:`g` is the value of the gravitational acceleration, :math:`\Gamma` is the free atmosphere lapse rate, defined by ``gTop`` and :math:`\theta_0` is the reference potential temperature, defined by ``tRef``. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``zDampingAlsoXY`` bool If set to 0, damping only acts on the vertical velocity with null velocity as the reference state (classic Rayleigh damping). If set to 1, horizontal components are also damped as specified by ``zDampingXYType``. This is usually set to 0, as horizontal velocity components should be damped with x and y fringes or kLeft and kRight Rayleigh damping layers. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``zDampingXYType`` integer Specifies how to chose the reference velocity used to perform horizontal damping. If set to 1, velocity is averaged for each j index, along the i index of the mesh (the simulation setup should be such that they correspond to z and y, respectively) at the kLeft patch. The resulting vertical velocity profile is used as reference state. If set to 2, velocity is horizontally averaged from the concurrent precursor domain ( requires x fringe with ``uBarSelectionType`` 3). ============================= ================== ===================================================================================== advectionDampingProperties ************************** .. table:: :widths: 35, 20, 45 :align: center ============================= ================== ===================================================================================== **entry** **entry type** **description** ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``advDampingStart`` scalar start x coordinate of the x advection damping layer in meters. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``advDampingEnd`` scalar end x coordinate of the x advection damping layer in meters. Should be greather than ``advDampingStart``. See Lanzilao & Meyers (2022): An Improved Fringe-Region Technique for the Representation of Gravity Waves in Large Eddy Simulation with Application to Wind Farms for optimal setup of these parameters with respect to the location of the x fringe region. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``advDampingDeltaStart`` scalar distance over which the damping action goes from 0 to 1 (complete removal of horizontal advection of vertical velocity). The sum of ``advDampingDeltaStart`` and ``advDampingDeltaEnd`` should be less than ``advDampingEnd`` - ``advDampingStart``. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``advDampingDeltaEnd`` scalar distance over which the damping goes back to 1. Usually larger than ``advDampingDeltaStart``. ============================= ================== ===================================================================================== kLeftDampingProperties ********************** .. table:: :widths: 35, 20, 45 :align: center ============================= ================== ===================================================================================== **entry** **entry type** **description** ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kLeftPatchDist`` scalar width of the k Raileigh damping region, given as distance from the kLeft patch. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kLeftDampingAlpha`` scalar damping coefficient :math:`\alpha`. Usually set to 0.3. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kLeftDampingUBar`` vector reference unpertuerbed velocity that should be obtained when the flow exits the Rayleigh damping region. Notably, if the kLeft is the inlet patch, this should be consistent with the inlet boundary condition, which should be steady above ``kLeftFilterHeight``. This can be obtained by using inletFunction type 4 with ``n1Merge`` activated, so that extrapolated values are averaged in time. To know the ``kLeftDampingUBar``, the user can run a tentative simulation with a dummy ``kLeftDampingUBar`` and the ``n1Merge`` activated. At simulation startup. after averaging the inflow data, velocity values will be printed in the TOSCA log file. The consistent ``kLeftDampingUBar`` will be the value at the highest cell. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kLeftFilterHeight`` scalar Filter height for turbulent flow. It should be set to the height of the incoming boundary layer, damping will only be applied above, while turbulence will allowed through below. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kLeftFilterWidth`` scalar Sharpness of the filter in m. The filtering function is such that damping is 1% at ``kLeftFilterHeight`` - ``kLeftFilterWidth``/2 and 99% at ``kLeftFilterHeight`` + ``kLeftFilterWidth``/2. ============================= ================== ===================================================================================== kRightDampingProperties *********************** .. table:: :widths: 35, 20, 45 :align: center ============================= ================== ===================================================================================== **entry** **entry type** **description** ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kRightPatchDist`` scalar width of the k Raileigh damping region, given as distance from the kRight patch. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kRightDampingAlpha`` scalar damping coefficient :math:`\alpha`. Usually set to 0.3. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kRightDampingUBar`` vector reference unpertuerbed velocity that should be obtained when the flow exits the Rayleigh damping region. It should be consistent with the incoming flow. As kRight and kLeft damping are usually employed together, ``kRightDampingUBar`` and ``kLeftDampingUBar`` should be the same. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kRightFilterHeight`` scalar Filter height for turbulent flow. It should be set to the height of the incoming boundary layer, damping will only be applied above, while turbulence will allowed through below. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``kRightFilterWidth`` scalar Sharpness of the filter in m. The filtering function is such that damping is 1% at ``kRightFilterHeight`` - ``kRightFilterWidth``/2 and 99% at ``kRightFilterHeight`` + ``kRightFilterWidth``/2. ============================= ================== ===================================================================================== canopyProperties **************** .. table:: :widths: 35, 20, 45 :align: center ============================= ================== ===================================================================================== **entry** **entry type** **description** ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xStartCanopy`` scalar start x coordinate of the canopy box. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``xEndCanopy`` scalar end x coordinate of the canopy box. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``yStartCanopy`` scalar start y coordinate of the canopy box. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``yEndCanopy`` scalar end y coordinate of the canopy box. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``zStartCanopy`` scalar start z coordinate of the canopy box. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``zEndCanopy`` scalar end z coordinate of the canopy box. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``cftCanopy`` scalar planform averaged thrust coefficient for the canopy model. It can be evaluated as :math:`4\pi C_T/(4S_xS_y)`. It is still debated if :math:`C_T` should be the freestream or the disk based thrust coefficient. Here we suggest disk based. ----------------------------- ------------------ ------------------------------------------------------------------------------------- ``diskDirCanopy`` vector vector that defines the direction of the force applied from the canopy to the flow. It is automatically normalized by TOSCA. ============================= ================== =====================================================================================