4. ROSCO Structure: Controller

Here, we give an overview of the structure of the ROSCO controller and how the code is implemented.

---

4.1. ROSCO File Structure

The primary functions of the ROSCO toolbox are separated into several files. They include the following:

• DISCON.f90 is the primary driver function.

• ReadSetParameters.f90 primarily handles file I/O and the Bladed Interface.

• ROSCO_Types.f90 allocates variables in memory; it is procedurally generated from rosco_registry

• Constants.f90 establishes some global constants.

• Controllers.f90 contains the primary controller algorithms (e.g. blade pitch control)

• ControllerBlocks.f90 contains additional control features that are not necessarily primary controllers (e.g. wind speed estimator)

• Filters.f90 contains the various filter implementations.

• Functions.f90 contains various functions used in the controller.

• ExtControl.f90 contains subroutines for calling external dynamic libraries

• ROSCO_Helpers.f90 contains subroutines for file I/O and other helpful routines, borrowed heavily from NWTC.IO in OpenFAST

• ROSCO_IO.f90 is procedurally generated using the rosco_registry for writing debug and checkpoint files

4.2. The DISCON.IN file

A standard file structure is used as an input to the ROSCO controller. This is, generically, dubbed the DISCON.IN file, though it can be renamed (In OpenFAST, this file is pointed to by DLL_InFile in the ServoDyn file. Examples of the DISCON.IN file are found in each of the Test Cases in the ROSCO toolbox, and in the parameter_files folder of ROSCO.

Table 4.1 DISCON.IN

Primary Section	Variable	Type	Description
DEBUG	LoggingLevel	Int	0: write no debug files, 1: write standard output .dbg-file, 2: write standard output .dbg-file and complete avrSWAP-array .dbg2-file
CONTROLLER FLAGS	F_LPFType	Int	Filter type for generator speed feedback signal. 1: first-order low-pass filter, 2: second-order low-pass filter.
	F_NotchType	Int	Notch filter on the measured generator speed and/or tower fore-aft motion (used for floating). 0: disable, 1: generator speed, 2: tower-top fore-aft motion, 3: generator speed and tower-top fore-aft motion.
	IPC_ControlMode	Int	Individual Pitch Control (IPC) type for fatigue load reductions (pitch contribution). 0: off, 1: 1P reductions, 2: 1P+2P reductions.
	VS_ControlMode	Int	Generator torque control mode type. 0: \(k\omega^2\) below rated, constant torque above rated, 1: \(k\omega^2\) below rated, constant power above rated, 2: TSR tracking PI control below rated, constant torque above rated, 3: TSR tracking PI control below rated, constant torque above rated
	PC_ControlMode	Int	Blade pitch control mode. 0: No pitch, fix to fine pitch, 1: active PI blade pitch control.
	Y_ControlMode	Int	Yaw control mode. 0: no yaw control, 1: yaw rate control, 2: yaw-by-IPC.
	SS_Mode	Int	Setpoint Smoother mode. 0: no set point smoothing, 1: use set point smoothing.
	WE_Mode	Int	Wind speed estimator mode. 0: One-second low pass filtered hub height wind speed, 1: Immersion and Invariance Estimator, 2: Extended Kalman Filter.
	PS_Mode	Int	Pitch saturation mode. 0: no pitch saturation, 1: implement pitch saturation
	SD_Mode	Int	Shutdown mode. 0: no shutdown procedure, 1: shutdown triggered by max blade pitch.
	Fl_Mode	Int	Floating feedback mode. 0: no nacelle velocity feedback, 1: nacelle velocity feedback (parallel compensation).
	Flp_Mode	Int	Flap control mode. 0: no flap control, 1: steady state flap angle, 2: PI flap control.
FILTERS	F_LPFCornerFreq	Float	Corner frequency (-3dB point) in the generator speed low-pass filter, [rad/s]
	F_LPFDamping	Float	Damping coefficient in the generator speed low-pass filter, [-]. Only used only when F_FilterType = 2
	F_NotchCornerFreq	Float	Natural frequency of the notch filter, [rad/s]
	F_NotchBetaNumDen	Float Float	Notch damping values of numerator and denominator - determines the width and depth of the notch, [-]
	F_SSCornerFreq	Float	Corner frequency (-3dB point) in the first order low pass ..filter for the set point smoother, [rad/s].
	F_FlCornerFreq	Float Float	Corner frequency and damping ratio for the second order low pass filter of the tower-top fore-aft motion for floating feedback control [rad/s, -].
	F_WECornerFreq	Float	Corner frequency (-3dB point) in the first order low pass filter for the wind speed estimate [rad/s].
	F_FlHighPassFreq	Float	Natural frequency of first-order high-pass filter for nacelle fore-aft motion [rad/s]..
	F_FlpCornerFreq	Float Float	Corner frequency and damping ratio in the second order low pass filter of the blade root bending moment for flap control [rad/s, -].
BLADE PITCH CONTROL	PC_GS_n	Int	Number of gain-scheduling table entries
	PC_GS_angles	Float array, length = PC_GS_n	Gain-schedule table: pitch angles [rad].
	PC_GS_KP	Float array, length = PC_GS_n	Gain-schedule table: pitch controller proportional gains [s].
	PC_GS_KI	Float array, length = PC_GS_n	Gain-schedule table: pitch controller integral gains [-].
	PC_GS_KD	Float array, length = PC_GS_n	Gain-schedule table: pitch controller derivative gains [\(s^2\)]. Currently unused!
	PC_GS_TF	Float array, length = PC_GS_n	Gain-schedule table: transfer function gains [\(s^2\)]. Currently unused!
	PC_MaxPit	Float	Maximum physical pitch limit, [rad].
	PC_MinPit	Float	Minimum physical pitch limit, [rad].
	PC_MaxRat	Float	Maximum pitch rate (in absolute value) of pitch controller, [rad/s].
	PC_MinRat	Float	Minimum pitch rate (in absolute value) in pitch controller, [rad/s].
	PC_RefSpd	Float	Desired (reference) HSS speed for pitch controller, [rad/s].
	PC_FinePit	Float	Below-rated pitch angle set-point, [rad]
	PC_Switch	Float	Angle above lowest PC_MinPit to switch to above rated torque control, [rad]. Used for VS_ControlMode = 0,1.
INDIVIDUAL PITCH CONTROL	IPC_IntSat	Float	Integrator saturation point (maximum signal amplitude contribution to pitch from IPC), [rad]
	IPC_KI	Float Float	Integral gain for the individual pitch controller: first parameter for 1P reductions, second for 2P reductions, [-, -].
	IPC_aziOffset	Float Float	Phase offset added to the azimuth angle for the individual pitch controller: first parameter for 1P reductions, second for 2P reductions, [rad].
	IPC_CornerFreqAct	Float	Corner frequency of the first-order actuators model, used to induce a phase lag in the IPC signal [rad/s]. 0: Disable.
VS TORQUE CONTROL	VS_GenEff	Float	Generator efficiency from mechanical power -> electrical power, [should match the efficiency defined in the generator properties!], [%]
	VS_ArSatTq	Float	Above rated generator torque PI control saturation limit, [Nm].
	VS_MaxRat	Float	Maximum generator torque rate (in absolute value) [Nm/s].
	VS_MaxTq	Float	Maximum generator torque (HSS), [Nm].
	VS_MinTq	Float	Minimum generator torque (HSS) [Nm].
	VS_MinOMSpd	Float	Cut-in speed towards optimal mode gain path, [rad/s]. Used if VS_ControlMode = 0,1.
	VS_Rgn2K	Float	Generator torque constant in Region 2 (HSS side), [N-m/(rad/s)^2]. Used if VS_ControlMode = 0,1.
	VS_RtPwr	Float	Rated power [W]
	VS_RtTq	Float	Rated torque, [Nm].
	VS_RefSpd	Float	Rated generator speed used by torque controller [rad/s].
	VS_n	Int	Number of generator PI torque controller gains. Only 1 is currently supported.
	VS_KP	Float	Proportional gain for generator PI torque controller [1/(rad/s) Nm]. (Used in the transition 2.5 region if VS_ControlMode = 0,1. Always used if VS_ControlMode = 2,3)
	VS_KI	Float	Integral gain for generator PI torque controller [1/rad Nm]. (Only used in the transition 2.5 region if VS_ControlMode = 0,1. Always used if VS_ControlMode = 2,3)
	VS_TSRopt	Float	Region 2 tip-speed-ratio [rad]. Generally, the power maximizing TSR. Can use non-optimal TSR for low axial induction rotors.
SETPOINT SMOOTHER	SS_VSGain	Float	Variable speed torque controller setpoint smoother gain, [-].
	SS_PCGain	Float	Collective pitch controller setpoint smoother gain, [-].
WIND SPEED ESTIMATOR	WE_BladeRadius	Float	Blade length (distance from hub center to blade tip), [m]
	WE_CP_n	Int	Number of parameters in the Cp array
	WE_CP	Float Float Float Float	Parameters that define the parameterized CP(lambda) function
	WE_Gamma	Float	Adaption gain for the I&I wind speed estimator algorithm [m/rad]
	WE_GearboxRatio	Float	Gearbox ratio [>=1], [-]
	WE_Jtot	Float	Total drivetrain inertia, including blades, hub and casted generator inertia to LSS, [kg m^2]
	WE_RhoAir	Float	Air density, [kg m^-3]
	PerfFileName	String	File containing rotor performance tables (Cp,Ct,Cq)
	PerfTableSize	Int Int	Size of rotor performance tables in PerfFileName, first number refers to number of blade pitch angles (num columns), second number refers to number of tip-speed ratios (num rows)
	WE_FOPoles_N	Int	Number of first-order system poles used in the Extended Kalman Filter
	WE_FOPoles_v	Float array, length = WE_FOPoles_N	Wind speeds for first-order system poles lookup table [m/s]
	WE_FOPoles	Float array, length = WE_FOPoles_N	First order system poles [1/s]
YAW CONTROL	Y_ErrThresh	Float	Yaw error threshold. Turbine begins to yaw when it passes this. [rad^2 s]
	Y_IPC_IntSat	Float	Integrator saturation (maximum signal amplitude contribution to pitch from yaw-by-IPC), [rad]
	Y_IPC_n	Int	Number of controller gains for yaw-by-IPC
	Y_IPC_KP	Float array, length = Y_IPC_n	Yaw-by-IPC proportional controller gains Kp [s]
	Y_IPC_KI	Float array, length = Y_IPC_n	Yaw-by-IPC integral controller gain Ki [-]
	Y_IPC_omegaLP	Float	Low-pass filter corner frequency for the Yaw-by-IPC controller to filtering the yaw alignment error, [rad/s].
	Y_IPC_zetaLP	Float	Low-pass filter damping factor for the Yaw-by-IPC controller to filtering the yaw alignment error, [-].
	Y_MErrSet	Float	Yaw alignment error set point, [rad].
	Y_omegaLPFast	Float	Corner frequency fast low pass filter, [rad/s].
	Y_omegaLPSlow	Float	Corner frequency slow low pass filter, [rad/s].
	Y_Rate	Float	Yaw rate, [rad/s].
TOWER FORE-AFT DAMPING	FA_KI	Float	Integral gain for the fore-aft tower damper controller [rad*s/m]. -1 = off
	FA_HPF_CornerFreq	Float	Corner frequency (-3dB point) in the high-pass filter on the fore-aft acceleration signal [rad/s]
	FA_IntSat	Float	Integrator saturation (maximum signal amplitude contribution to pitch from FA damper), [rad]
MINIMUM PITCH SATURATION	PS_BldPitchMin_N	Int	Number of values in minimum blade pitch lookup table.
	PS_WindSpeeds	Float array, length = PS_BldPitchMin_n	Wind speeds corresponding to minimum blade pitch angles [m/s]
	PS_BldPitchMin	Float array, length = PS_BldPitchMin_n	Minimum blade pitch angles [rad]
SHUTDOWN	SD_MaxPit	Float	Maximum blade pitch angle to initiate shutdown, [rad]
	SD_CornerFreq	Float	Cutoff Frequency for first order low-pass filter for blade pitch angle, [rad/s]
FLOATING	Fl_Kp	Float	Nacelle velocity proportional feedback gain [s]
FLAP ACTUATION	Flp_Angle	Float	Initial or steady state flap angle [rad]
	Flp_Kp	Float	Trailing edge flap control proportional gain [s]
	Flp_Ki	Float	Trailing edge flap control integral gain [s]
	Flp_MaxPit	Float	Maximum (and minimum) flap angle [rad]