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.

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: 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 \(10^{-5} \cdot 7.272205217sin(\phi)\), where \(\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: 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: 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: 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: yDampingProperties { yDampingStart scalar yDampingEnd scalar yDampingDelta scalar yDampingAlpha scalar }
zDampingProperties	dictionary	Defines Reyleigh damping layer parameters, activated with -zDampingLayer 1 in control.dat. Usage: 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: 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: 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: 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: 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: 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

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 (\(2\pi/f_c\)).
geoDampingTimeWindow	scalar	time filter of the deduced geostrophic wind components. Usually set to 1/10 of the inertial oscillation period (\(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

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 \(\alpha\). It must be smaller than (xDampingEnd - xDampingStart)/2.
xDampingAlpha	scalar	damping coefficient \(\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 boundary 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 \(\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

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 \(\alpha\). It must be smaller than (yDampingEnd - yDampingStart)/2.
yDampingAlpha	scalar	damping coefficient \(\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: \(L_x\) / (xDampingEnd - xDampingStart) = yDampingNumPeriods, where \(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

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 \(\alpha\) at zDampingEnd, so setting the latter to values higher than the domain height is wrong.
zDampingAlpha	scalar	damping coefficient \(\alpha\). Usually set to \(3\sqrt{g\Gamma/\theta_0}\), where \(g\) is the value of the gravitational acceleration, \(\Gamma\) is the free atmosphere lapse rate, defined by gTop and \(\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

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

entry	entry type	description
kLeftPatchDist	scalar	width of the k Raileigh damping region, given as distance from the kLeft patch.
kLeftDampingAlpha	scalar	damping coefficient \(\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

entry	entry type	description
kRightPatchDist	scalar	width of the k Raileigh damping region, given as distance from the kRight patch.
kRightDampingAlpha	scalar	damping coefficient \(\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

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 \(4\pi C_T/(4S_xS_y)\). It is still debated if \(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.