turbines

This section describes how wind turbines can be activated in TOSCA. By setting the -windplant flag to 1 in the control.dat file, TOSCA is prompted to read turbine and farm parameters inside the turbines directory.

windFarmProperties

The structure of a wind farm definition in TOSCA works as follows. The list of all wind turbines present in the simulation is defined in the windFarmProperties file. Here, the user can define how frequently wind turbine variables are written to file, as well as the type, model, location and activation of global wind farm controller for each wind turbine in the list. Such file has the following syntax:

# TOSCA Input file - Wind Farm Properties
# -------------------------------------------

windFarmName            string
arraySpecification      string
debug                   bool

writeSettings
{
    timeStart           scalar
    intervalType        string
    timeInterval        scalar
}

turbineArray
{
    turbineID_1
    (
        turbineType         string
        turbineModel        string
        baseLocation        vector
        windFarmController  bool
    )
    :
    :
    :
    turbineID_N
    (
        turbineType         string
        turbineModel        string
        baseLocation        vector
        windFarmController  bool
    )
}

The windFarmName identifies the name of the wind farm, and it is totally up to the user to set it. Regarding arraySpecification, TOSCA currenty only supports the onebyone specification type, which is the most generic and allows to define all types of wind farms. In the future, we might add the aligned and staggered types, which do not require to specify each wind turbine individually. Notably, these layouts can still be obtained with the current format. The debug flag prints to screen useful wind farm information at each iteration, but requires more processor communication when it is activated, so we suggest to set it to zero for production runs. The writeSettings dictionary allows to set parameters for the wind turbine acquisition system. The timeStart entry, defined in seconds, defines the time at which TOSCA starts to write turbine data to file. The frequency at which this operation happens can be specified using the next two entries. Specifically, intervalType can be set to timeStep or adjustableTime. In the first case, turbine data are written to file every timeInterval iterations (which has to be an integer), in the second case data are written every timeInterval seconds (which can be a scalar value with decimals). Notably, in this case the -adjustTimeStep flag has to be set to 1 in the control.dat file, and TOSCA will adjust the time step to land on multiples of the timeInterval specified by the user.

Regarding the definition of the wind turbine list, this can be of arbitrary length. The name of each entry (e.g. turbineID_1, turbineID_N) is a string which must be specified by the user. This will be the name of the file where TOSCA will write each turbine’s acquisition data, and it will be saved in the postProcessing/turbines/startTime folder, which will be created at the start of the simulation. At each simulation restart, the startTime will differ, so TOSCA will not overwrite the turbine data. In the follwing table, the entries required for each turbine in the windFarmProperties file are detailed.

entry	entry type	description
`turbineType`	string	Name of the file defining the wind turbine model. Different wind turbines can be present in the same wind farm. For example, if the wind turbine is ModelA, a file with this name should be contained inside the `turbines` directory. See below for entries to this file.
`turbineModel`	string	Actuator model used to represent the wind turbine in the flow domain. Inputs to the model are contained in the wind turbine type file. Available models are: `ALM`: actuator line model `ADM`: actuator disk model `uniformADM`: uniform actuator disk model `AFM`: actuator farm model
`baseLocation`	vector	vector defining the coordinates of the base location.
`windFarmController`	bool	Wether or not the wind farm controller is active. If the controller is active for this turbine, an additional file is required, located in `turbines/control`. This a look up table that should have the following format: # wind farm control table given as a function of time and pitch/DeltaCT time_1 pitch_1/DeltaCT_1 : : time_n pitch_n/DeltaCT_n Notably, the file should contain only one header line. If `turbineModel` is set to `ALM` or `ADM`, pitch in degrees should be provided in the second column, while for `uniformADM` and `AFM` the second column corresponds to a delta in thrust coefficient. Whether this is interpreted as disk based or freestream, it depends on the settings provided in the wind turbine type file. This is a simple method to impose a wind farm controller (in the context of wind farm wake mixing) with no feedback action.

As TOSCA requires individual definition of each turbine, this comes with some perks. In particular, the entries described in the above table can be different for each wind turbine. This means that the user can use different actuator models, controller activation and turbine model specification within the same simulation. This becomes useful for studies of multiple wind farm clusters which might have different turbines and be controlled differently.

turbineTypeFile

The turbine type specification is contained in a file named as the turbineType entry in the windFarmProperties file. Its syntax is defined as follows

# TOSCA Input file - Turbine Type File
# -------------------------------------------

# Global wind turbine parameters
rTip                scalar
rHub                scalar
hTower              scalar
overHang            scalar
precone             scalar
towerDir            vector
rotorDir            vector
upTilt              scalar
initialOmega        scalar  // for ALM and ADM only
nBlades             integer // for ALM and ADM only
rotationDir         string  // for ALM and ADM only
includeTower        bool
includeNacelle      bool
debug               bool

# Controllers
genControllerType   string  // for ALM and ADM only
pitchControllerType string  // for ALM and ADM only
yawControllerType   string

# Actuator model parameters
nRadPts             integer // for ALM, ADM and uniformADM only
nAziPts             integer // for ADM and uniformADM only
Uref                scalar
Ct                  scalar  // for uniformADM and AFM only
projection          string  // for ALM and AFM only
sampleType          string  // for ALM, uniformADM and AFM only
epsilon             scalar  // for ALM, ADM and unformADM only
epsilon_x           scalar  // for anisotropic AFM only
epsilon_y           scalar  // for anisotropic AFM only
epsilon_z           scalar  // for anisotropic AFM only
gaussexp_x          scalar  // for gaussexp AFM only
gaussexp_r          scalar  // for gaussexp AFM only
gaussexp_f          scalar  // for gaussexp AFM only
epsilonFactor_x     scalar  // for anisotropic ALM only
epsilonFactor_y     scalar  // for anisotropic ALM only
epsilonFactor_z     scalar  // for anisotropic ALM only

# Tower properties
towerData
{
    Cd              scalar
    epsilon         scalar
    nLinPts         integer
    rBase           scalar
    rTop            scalar
}

# Nacelle properties
nacelleData
{
    Cd              scalar
    epsilon         scalar
}

# names of the foils (for ALM and ADM only)
airfoils
{
    airfoil_1
    :
    airfoil_n
}


# Blade parameters given as:
# (radius(m) c(m) twist(deg) thickness(m, anisotropic ALM only) airfoilID)
# for ALM and ADM only
bladeData
{
    (scalar     scalar   scalar     integer)
    (:          :        :          :      )
    (scalar     scalar   scalar     integer)
}

Notably, depending on the chosen actuator model type, different parameters are needed. Indication about this are provided in the comments of the example file above. Parameters which do not contain a comment line are always required. Each of the above parameters is detailed in the table below:

entry	entry type	description
`rTip`	scalar	turbine tip radius in m.
`rHub`	scalar	turbine hub radius in m.
`hTower`	scalar	turbine tower height in m.
`overHang`	scalar	distance between rotor center and tower top in m.
`precone`	scalar	angle in degrees formed between turbine blades and the rotor plane. The rotor plane is defined as the unique plane that is formed when all blades lie in the same plane. The more positive the angle, the furthest the blade tip from the tower.
`towerDir`	vector	vector defining the tower direction from base to top. Normalized by TOSCA.
`rotorDir`	vector	vector defining the direction of the rotor, facing the wind. Normalized by TOSCA.
`upTilt`	scalar	angle in degrees formed between the normal of the rotor plane and the horizontal plane. The more positive the angle, the furthest the blade tip from the tower.
`initialOmega`	scalar	initial blade angular velocity in rpm. This is updated by the angular velocity controller if this is activated, otherwise it is kept constant. Only required when `turbineModel` is `ALM` or `ADM`.
`nBlades`	integer	number of turbine blades. Only required when `turbineModel` is `ALM` or `ADM`.
`rotationDir`	string	it can be set to cw (clockwise) or ccw (counter-clockwise). It is defined by looking at the wind turbine from upstream. Only required when `turbineModel` is `ALM` or `ADM`.
`includeTower`	bool	whether or not to model also the tower as an actuator line. Requires the `towerData` dictionary.
`includeNacelle`	bool	whether or not to model also the nacelle as an actuator point. Requires the `nacelleData` dictionary.
`debug`	bool	debug switch. Prints turbine-level information and projection error. Deactivate for performance.
`genControllerType`	string	name of the file that contains the generator control properties of this wind turbine type. Should be located inside the `turbines/control` directory and it will be described later. Only required when `turbineModel` is `ALM` or `ADM`. Set to none to disable.
`pitchControllerType`	string	name of the file that contains the collective pitch control properties of this wind turbine type. Should be located inside the `turbines/control` directory and it will be described later. Only required when `turbineModel` is `ALM` or `ADM`. Set to none to disable.
`yawControllerType`	string	name of the file that contains the yaw control properties of this wind turbine type. Should be located inside the `turbines/control` directory and it will be described later. Set to none to disable.
`nRadPts`	integer	number of radial points for the actuator model. Only required when `turbineModel` is `ALM`, `ADM` or `uniformADM`.
`nAziPts`	integer	number of azimuthal points for the actuator model. Only required when `turbineModel` is `ADM` or `uniformADM`.
`Uref`	scalar	freestream velocity for this wind turbine in m/s. The meaning of this parameter depends on the chosen actuator model. for `ALM`, `ADM` and `AFM` it is used to compute the freestream thrust coefficient when writing the turbine data to file. It does not affect thrust computation. for `uniformADM` it is used to compute thrust when `sampleType` is set to givenVelocity. For other sample types it is used to compute the freestream thrust coefficient when writing the turbine data to file and it does not affect thrust computation.
`Ct`	scalar	thrust coefficient for this wind turbine. Only required when `turbineModel` is `uniformADM` or `AFM`. The meaning of this parameter depends on the chosen actuator model. for `uniformADM` it should be the freestream thrust coefficient when `sampleType` is set to givenVelocity or rotorUpstream. Conversely, when using rotorDisk it should be the disk-based thrust coefficient. for `AFM` it should be the freestream thrust coefficient when `sampleType` is set to momentumTheory. Conversely, when using rotorDisk or integral it should be the disk-based thrust coefficient.
`projection`	string	body force projection type. Only required for `ALM` and `AFM` models. Entries specific to each model are described below. `ALM` isotropic: standard actuator line model. anisotropic: advanced actuator line model, where the gaussian projection function has different widths along the blade span, chord and thickness. The latter should be provided in the `bladeData` table. `AFM` anisotropic: anisotropic gaussian projection gaussexp: gauss-exponential projection. The latter has been subject to more validation, hence is suggested.
`sampleType`	string	velocity sampling type. Only required for `ALM`, `uniformADM` and `AFM` models. Entries specific to each model are described below. `ALM` rotorDisk: tri-linearly interpolates velocity at actuator points integral: integrates the velocity around the blade, weighted by the projection function. `uniformADM` rotorUpstream: averages velocity on a fictitious actuator disk, located 2.5 diamters upstream of the wind turbine givenVelocity: does not sample any velocity but uses the provided value of `Uref` rotorDisk: averages velocity on the rotor disk. `AFM` rotorDisk: tri-linearly interpolates velocity at the rotor center integral: integrates velocity around the rotor center, weighted by the projection function momentumTheory: computes the freestream velocity as \(U_{disk}/(1-a)\), where \(a\) is the induction factor, defined as \(\frac{1 - \sqrt{1-C_T}}{2}\).
`epsilon`	scalar	standard deviation of the projection function in m for `ALM` (when `projection` is set to isotropic), `ADM` and `uniformADM`.
`epsilon_x`	scalar	standard deviation of the projection function in along x for `AFM` (when `projection` is set to anisotropic).
`epsilon_y`	scalar	standard deviation of the projection function in along y for `AFM` (when `projection` is set to anisotropic).
`epsilon_z`	scalar	standard deviation of the projection function in along z for `AFM` (when `projection` is set to anisotropic).
`gaussexp_x`	scalar	standard deviation of the projection function in along x for `AFM` (when `projection` is set to gaussexp).
`gaussexp_r`	scalar	radial helf-decay length in m of the exponential projection function for `AFM` model, when `projection` is set to gaussexp. Usually set equal to the turbine radius.
`gaussexp_f`	scalar	smoothing parameter of the exponential projection function for `AFM` model, when `projection` is set to gaussexp.
`epsilonFactor_x`	scalar	chord multiplication factor defining the standard deviation along the blade chord of the gaussian projection function for `ALM` when `projection` is set to anisotropic.
`epsilonFactor_y`	scalar	thickness multiplication factor defining the standard deviation along the blade thickness of the gaussian projection function for `ALM` when `projection` is set to anisotropic.
`epsilonFactor_z`	scalar	\(dr\) multiplication factor defining the standard deviation along the blade radius of the gaussian projection function for `ALM` when `projection` is set to anisotropic.
`towerData`	dictionary	Dictionary defining the parameters required to represent the tower as an actuator line. Usage: towerData { Cd scalar // drag coefficient epsilon scalar // projection length // in m nLinPts integer // num. of actuator // points rBase scalar // tower base radius rTop scalar // tower top radius }
`nacelleData`	dictionary	Dictionary defining the parameters required to represent the nacelle as an actuator point. Usage: nacelleData { Cd scalar // drag coefficient epsilon scalar // projection length // in m }
`airfoils`	table	List of files storing the blade airfoil information. The list has an arbitrary length files named as the element of the list should be located inside `turbines/airfoils`. Usage: airfoils { airfoil_1 : airfoil_n } Each file should have the following format: # data provided as \| alpha \| C_l \| C_d table { (scalar scalar scalar) (: : : ) (scalar scalar scalar) }
`bladeData`	table	List of properties for each blade radial station. The list has an arbitrary length and should store radial position, chord, twist and airfoil ID. The latter is the index of one of the airfoils present in the airfoils list, starting from 0. Specifically, that which corresponds to the given radial position. When using `ALM` with `projection` set to anisotropic, blade thickness is added to the list, before the airfoil ID. Usage: bladeData { (scalar scalar scalar integer) (: : : : ) (scalar scalar scalar integer) } or bladeData { (scalar scalar scalar scalar integer) (: : : : : ) (scalar scalar scalar scalar integer) } when using `ALM` with `projection` set to anisotropic.

control

In order to complete the definition of a given wind turbine, information regarding individual turbine control should be provided. While yaw control can be applied to any actuator model, angular velocity and pitch control are only available for ALM and ADM, as these feature a more detailed description of the wind turbine. The name of the turbine control files that TOSCA will use for each specific wind turbine are defined with the entries genControllerType, pitchControllerType and yawControllerType, detailed in the previous table. The general idea is that a given controller is entirely described in a file. Hence, in most cases these entries will be equal if all three controllers are active on a given wind turbine. However, a single turbine can be also controlled with different controllers, defined in different files. Moreover, as many different controllers as desired by the user can be used within a given wind farm. The turbine control file should be contained inside the turbines/control directory, and consists of the the entires described in the following table.

entry	entry type	description
`genInertia`	scalar	rotational inertia of the electrical generator in kg/m2.
`hubInertia`	scalar	rotational inertia of the hub in kg/m2.
`bldIntertia`	scalar	rotational inertia of each blade in kg/m2.
`gbxRatioG2R`	scalar	gearbox ratio (generator / rotor).
`gbxEfficiency`	scalar	gearbox efficiency.
`genEff`	scalar	generator efficiency.
`initialGenTorque`	scalar	initial torque of the electrical generator.
`genTqControllerParameters`	dictionary	parameters defining the generator torque controller.
`pitchControllerParameters`	dictionary	parameters defining the collective pitch controller.
`yawControllerParameters`	dictionary	parameters defining the nacelle yaw controller.

Entries for the last three dictionaries are described in the following table

entry	entry type	description
genTqControllerParameters
`genSpeedFilterFreq`	scalar	corner frequency of generator-speed low-pass filter in Hz.
`cutInGenSpeed`	scalar	transitional generator speed between regions 1 and 1.5 in rpm.
`cutInGenTorque`	scalar	generator torque at cut-in wind speed in Nm.
`regTwoStartGenSpeed`	scalar	transitional generator speed between regions 1.5 and 2 in rpm.
`regTwoEndGenSpeed`	scalar	transitional generator speed between regions 2 and 3 in rpm.
`ratedGenTorque`	scalar	generator torque at rated wind speed in Nm.
`controllerPGain`	scalar	proportional gain of torque controller in Nm/rpm2
`torqueRateLimiter`	bool	activation of limit on rate of torque variation.
`rtrSpeedLimiter`	bool	activation of limit on rotor speed.
`torqueMaxRate`	scalar	maximum rate of torque variation in Nm/s.
`ratedRotorSpeed`	scalar	rotor speed at rated wind speed in rpm.
pitchControllerParameters
`pitchRateLimiter`	bool	activation of limit on rate of pitch variation.
`pitchAngleLimiter`	bool	activation of limit on pitch angle.
`pitchMaxRate`	scalar	maximum rate of pitch variation in deg/s.
`pitchMin`	scalar	minimum pitch value in deg.
`pitchMax`	scalar	maximum pitch value in deg.
`controllerPGain`	scalar	proportional gain of pitch controller in s.
`controllerIGain`	scalar	integral gain of pitch controller.
`controllerDGain`	scalar	derivative gain of pitch controller.
`pitchS2R`	scalar	blade pitch angle in deg at which the rotor power has doubled.
yawControllerParameters
`sampleType`	string	type of velocity sampling to calculate the incoming wind angle. Currently the only possibility is hubUpDistance, where the wind is sampled one rotor diameter upstream with respect to the rotor center. We are planning to implement also anemometer sampling, where the wind is sampled from the nacelle-mounted anemometer (right now this is just a place-holder and it does not do anything).
`avgWindow`	scalar	averaging window to filter the wind measurement at the sampling location.
`yawMin`	scalar	minimum yaw angle in deg (range is -180 to 180).
`yawMax`	scalar	maximum yaw angle in deg (range is -180 to 180).
`yawSpeed`	scalar	constant nacelle rotational speed in deg/s.
`allowedError`	scalar	allowed misalignment error in deg under which yaw is not changed.
`initialFlowAngle`	scalar	initial angle in deg between the incoming flow and the direction of the rotor plane with zero upTilt.