6. API changes between versions

This page lists the main changes in the ROSCO API (input file) between different versions.

The changes are tabulated according to the line number, and flag name. The line number corresponds to the resulting line number after all changes are implemented. Thus, be sure to implement each in order so that subsequent line numbers are correct.

6.1. 2.8.0 to 2.9.0

Flag to use exteneded Bladed Interface

  • Set Ext_Interface to 1 to use the extened bladed interface with OpenFAST v3.5.0 and greater

Gain scheduling of floating feedback

  • The floating feedback gain can be scheduled on the low pass filtered wind speed signal. Note that Fl_Kp can now be an array.

Rotor position tracking

  • Control the azimuth position of the rotor with OL_Mode of 2 using a PID torque controller with gains defined by RP_Gains.

  • Control all three blade pitch inputs in open loop

New torque control mode settings

  • VS_ControlMode determines how the generator speed set point is determined: using the WSE (mode 2) or (P/K)^(1/3) (mode 3). The power signal in mode 3 is filtered using VS_PwrFiltF.

  • VS_ConstPower determines whether constant power is used (0 is constant torque, 1 is constant power)

Multiple notch filters

  • Users can list any number of notch filters and apply them to either the generator speed and/or tower top accelleration signal based on their index

Power reference control via generator speed set points

  • With this feature, enabled with PRC_Mode, a user can prescribe a set of generator speed set points (PRC_GenSpeeds) vs. the estimated wind speed (PRC_WindSpeeds), which can be used to avoid certain natural frequencies or implement a soft cut-out scheme.

  • A low pass filter with frequency PRC_LPF_Freq is used to filter the wind speed estimate. A lower value increases the stability of the generator speed reference signal.

ZeroMQ Interface

  • Each turbine is assigned a ZMQ_ID by the controller, which is tracked by a farm-level controller

Tower resonance avoidance

  • When TRA_Mode is 1, change the torque control generator speed setpoint to avoid TRA_ExclSpeed +/- TRA_ExclBand.

  • The set point is changed at a slow rate TRA_RateLimit to avoid generator power spikes. VS_RefSpd/100 is recommended.

Removed in ROSCO develop

Line

Input Name

Example Value

11

F_NotchType

2 ! F_NotchType - Notch on the measured generator speed and/or tower fore-aft motion (for floating) {0: disable, 1: generator speed, 2: tower-top fore-aft motion, 3: generator speed and tower-top fore-aft motion}

35

F_NotchCornerFreq

3.35500 ! F_NotchCornerFreq - Natural frequency of the notch filter, [rad/s]

36

F_NotchBetaNumDen

0.000000 0.250000 ! F_NotchBetaNumDen - Two notch damping values (numerator and denominator, resp) - determines the width and depth of the notch, [-]

New in ROSCO develop

Line

Input Name

Example Value

7

Ext_Interface

1 ! Ext_Interface - (0 - use standard bladed interface, 1 - Use the extened DLL interface introduced in OpenFAST 3.5.0.)

14

VS_ConstPower

0 ! VS_ConstPower - Do constant power torque control, where above rated torque varies, 0 for constant torque}

18

PRC_Mode

0 ! PRC_Mode - Power reference tracking mode{0: use standard rotor speed set points, 1: use PRC rotor speed setpoints}

38

F_NumNotchFilts

1 ! F_NumNotchFilts - Number of notch filters placed on sensors

39

F_NotchFreqs

3.3550 ! F_NotchFreqs - Natural frequency of the notch filters. Array with length F_NumNotchFilts

40

F_NotchBetaNum

0.0000 ! F_NotchBetaNum - Damping value of numerator (determines the width of notch). Array with length F_NumNotchFilts, [-]

41

F_NotchBetaDen

0.2500 ! F_NotchBetaDen - Damping value of denominator (determines the depth of notch). Array with length F_NumNotchFilts, [-]

42

F_GenSpdNotch_N

0 ! F_GenSpdNotch_N - Number of notch filters on generator speed

43

F_GenSpdNotch_Ind

0 ! F_GenSpdNotch_Ind - Indices of notch filters on generator speed

44

F_TwrTopNotch_N

1 ! F_TwrTopNotch_N - Number of notch filters on tower top acceleration signal

45

F_TwrTopNotch_Ind

1 ! F_TwrTopNotch_Ind - Indices of notch filters on tower top acceleration signal

92

VS_PwrFiltF

0.3140 ! VS_PwrFiltF - Low pass filter on power used to determine generator speed set point. Only used in VS_ControlMode = 3.

98

PRC_Section

!——- POWER REFERENCE TRACKING ————————————–

99

PRC_n

2 ! PRC_n - Number of elements in PRC_WindSpeeds and PRC_GenSpeeds array

100

PRC_LPF_Freq

0.07854 ! PRC_LPF_Freq - Frequency of the low pass filter on the wind speed estimate used to set PRC_GenSpeeds [rad/s]

101

PRC_WindSpeeds

3.0000 25.0000 ! PRC_WindSpeeds - Array of wind speeds used in rotor speed vs. wind speed lookup table [m/s]

102

PRC_GenSpeeds

0.7917 0.7917 ! PRC_GenSpeeds - Array of generator speeds corresponding to PRC_WindSpeeds [rad/s]

103

Empty Line

128

TRA_ExclSpeed

0.00000 ! TRA_ExclSpeed - Rotor speed for exclusion [LSS, rad/s]

129

TRA_ExclBand

0.00000 ! TRA_ExclBand - Size of the rotor frequency exclusion band [LSS, rad/s]. Torque controller reference will be TRA_ExclSpeed +/- TRA_ExlBand/2

130

TRA_RateLimit

0.00000e+00 ! TRA_RateLimit - Rate limit of change in rotor speed reference [LSS, rad/s]. Suggested to be VS_RefSpd/100.

145

Fl_n

1 ! Fl_n - Number of Fl_Kp gains in gain scheduling, optional with default of 1

147

Fl_U

0.0000 ! Fl_U - Wind speeds for scheduling Fl_Kp, optional if Fl_Kp is single value [m/s]

161

Ind_Azimuth

0 ! Ind_Azimuth - The column in OL_Filename that contains the desired azimuth position in rad (used if OL_Mode = 2)

162

RP_Gains

0.0000 0.0000 0.0000 0.0000 ! RP_Gains - PID gains and Tf of derivative for rotor position control (used if OL_Mode = 2)

186

ZMQ_ID

0 ! ZMQ_ID - Integer identifier of turbine

Changed in ROSCO develop

Line

Input Name

Example Value

12

VS_ControlMode

2 ! VS_ControlMode - Generator torque control mode in above rated conditions (0- no torque control, 1- k*omega^2 with PI transitions, 2- WSE TSR Tracking, 3- Power-based TSR Tracking)}126 OL_mode 0 ! OL_Mode - Open loop control mode {0: no open loop control, 1: open loop control vs. time, 2: rotor position control}

125

Twr_Section

!——- TOWER CONTROL ——————————————————

141

Fl_Kp

0.0000 ! Fl_Kp - Nacelle velocity proportional feedback gain [s]

153

Ind_BldPitch

0 0 0 ! Ind_BldPitch - The columns in OL_Filename that contains the blade pitch (1,2,3) inputs in rad [array]

6.2. 2.7.0 to 2.8.0

Optional Inputs - ROSCO now reads in the whole input file and searches for keywords to set the inputs. Blank spaces and specific ordering are no longer required. - Input requirements depend on control modes. E.g., open loop inputs are not required if OL_Mode = 0` Cable Control - Can control OpenFAST cables (MoorDyn or SubDyn) using ROSCO Structural Control - Can control OpenFAST structural control elements (ServoDyn) using ROSCO Active wake control - Added Active Wake Control (AWC) implementation

New in ROSCO 2.8.0

Line

Input Name

Example Value

6

Echo

0 ! Echo - (0 - no Echo, 1 - Echo input data to <RootName>.echo)

25

AWC_Mode

0 ! AWC_Mode - Active wake control mode [0 - not used, 1 - complex number method, 2 - Coleman transform method]

28

CC_Mode

0 ! CC_Mode - Cable control mode [0- unused, 1- User defined, 2- Open loop control]

29

StC_Mode

0 ! StC_Mode - Structural control mode [0- unused, 1- User defined, 2- Open loop control]

139

Ind_CableControl

0 ! Ind_CableControl - The column(s) in OL_Filename that contains the cable control inputs in m [Used with CC_Mode = 2, must be the same size as CC_Group_N]

140

Ind_StructControl

0 ! Ind_StructControl - The column(s) in OL_Filename that contains the structural control inputs [Used with StC_Mode = 2, must be the same size as StC_Group_N]

148

Empty Line

149

AWC_Section

!——- Active Wake Control —————————————————–

150

AWC_NumModes

1 ! AWC_NumModes - AWC- Number of modes to include [-]

151

AWC_n

1 ! AWC_n - AWC azimuthal mode [-] (only used in complex number method)

152

AWC_harmonic

1 ! AWC_harmonic - AWC Coleman transform harmonic [-] (only used in Coleman transform method)

153

AWC_freq

0.03 ! AWC_freq - AWC frequency [Hz]

154

AWC_amp

2.0 ! AWC_amp - AWC amplitude [deg]

155

AWC_clockangle

0.0 ! AWC_clockangle - AWC clock angle [deg]

165

Empty Line

166

CC_Section

!——- Cable Control ———————————————————

167

CC_Group_N

3 ! CC_Group_N - Number of cable control groups

168

CC_GroupIndex

2601 2603 2605 ! CC_GroupIndex - First index for cable control group, should correspond to deltaL

169

CC_ActTau

20.000000 ! CC_ActTau - Time constant for line actuator [s]

170

Empty Line

171

StC_Section

!——- Structural Controllers ———————————————————

172

StC_Group_N

3 ! StC_Group_N - Number of cable control groups

173

StC_GroupIndex

2818 2838 2858 ! StC_GroupIndex - First index for structural control group, options specified in ServoDyn summary output

6.3. 2.6.0 to 2.7.0

Pitch Faults - Constant pitch actuator offsets (PF_Mode = 1) IPC Saturation Modes - Added options for saturating the IPC command with the peak shaving limit

New in ROSCO 2.7.0

Line

Input Name

Example Value

22

PA_Mode

0 ! PA_Mode - Pitch actuator mode {0 - not used, 1 - first order filter, 2 - second order filter}

23

PF_Mode

0 ! PF_Mode - Pitch fault mode {0 - not used, 1 - constant offset on one or more blades}

56

IPC_SatMode

2 ! IPC_SatMode - IPC Saturation method (0 - no saturation (except by PC_MinPit), 1 - saturate by PS_BldPitchMin, 2 - saturate sotfly (full IPC cycle) by PC_MinPit, 3 - saturate softly by PS_BldPitchMin)

139

PF_Section

!——- Pitch Actuator Faults ———————————————————

140

PF_Offsets

0.00000000 0.00000000 0.00000000 ! PF_Offsets - Constant blade pitch offsets for blades 1-3 [rad]

141

Empty Line

6.4. 2.5.0 to develop

IPC - A wind speed based soft cut-in using a sigma interpolation is added for the IPC controller

Pitch Actuator - A first or second order filter can be used to model a pitch actuator

External Control Interface - Call another control library from ROSCO

ZeroMQ Interface - Communicate with an external routine via ZeroMQ. Only yaw control currently supported

Updated yaw control - Filter wind direction with deadband, and yaw until direction error changes signs (https://iopscience.iop.org/article/10.1088/1742-6596/1037/3/032011)

New in ROSCO 2.6.0

Line

Input Name

Example Value

19

TD_Mode

0 ! TD_Mode - Tower damper mode {0: no tower damper, 1: feed back translational nacelle accelleration to pitch angle}

22

PA_Mode

0 ! PA_Mode - Pitch actuator mode {0 - not used, 1 - first order filter, 2 - second order filter}

23

Ext_Mode

0 ! Ext_Mode - External control mode {0 - not used, 1 - call external dynamic library}

24

ZMQ_Mode

0 ! ZMQ_Mode - Fuse ZeroMQ interaface {0: unused, 1: Yaw Control}

33

F_YawErr

0.17952 ! F_YawErr - Low pass filter corner frequency for yaw controller [rad/s].

54

IPC_Vramp

9.120000 11.400000 ! IPC_Vramp - Start and end wind speeds for cut-in ramp function. First entry: IPC inactive, second entry: IPC fully active. [m/s]

96

Y_uSwitch

0.00000 ! Y_uSwitch - Wind speed to switch between Y_ErrThresh. If zero, only the first value of Y_ErrThresh is used [m/s]

133

Empty Line

N/A

134

PitchActSec

!——- Pitch Actuator Model —————————————————–

135

PA_CornerFreq

3.140000000000 ! PA_CornerFreq - Pitch actuator bandwidth/cut-off frequency [rad/s]

136

PA_Damping

0.707000000000 ! PA_Damping - Pitch actuator damping ratio [-, unused if PA_Mode = 1]

137

Empty Line

138

ExtConSec

!——- External Controller Interface —————————————————–

139

DLL_FileName

“unused” ! DLL_FileName - Name/location of the dynamic library in the Bladed-DLL format

140

DLL_InFile

“unused” ! DLL_InFile - Name of input file sent to the DLL (-)

141

DLL_ProcName

“DISCON” ! DLL_ProcName - Name of procedure in DLL to be called (-)

142

Empty Line

143

ZeroMQSec

!——- ZeroMQ Interface ———————————————————

144

ZMQ_CommAddress

tcp://localhost:5555” ! ZMQ_CommAddress - Communication address for ZMQ server, (e.g. “tcp://localhost:5555”)

145

ZMQ_UpdatePeriod

2 ! ZMQ_UpdatePeriod - Call ZeroMQ every [x] seconds, [s]

Modified in ROSCO 2.6.0

Line

Input Name

Example Value

97

Y_ErrThresh

4.000000 8.000000 ! Y_ErrThresh - Yaw error threshold/deadbands. Turbine begins to yaw when it passes this. If Y_uSwitch is zero, only the second value is used. [deg].

98

Y_Rate

0.00870 ! Y_Rate - Yaw rate [rad/s]

99

Y_MErrSet

0.00000 ! Y_MErrSet - Integrator saturation (maximum signal amplitude contribution to pitch from yaw-by-IPC), [rad]

Removed in ROSCO 2.6.0

Line

Input Name

Example Value

96

Y_IPn

1 ! Y_IPC_n - Number of controller gains (yaw-by-IPC)

99

Y_IPC_omegaLP

0.20940 ! Y_IPC_omegaLP - Low-pass filter corner frequency for the Yaw-by-IPC controller to filtering the yaw alignment error, [rad/s].

100

Y_IPC_zetaLP

1.00000 ! Y_IPC_zetaLP - Low-pass filter damping factor for the Yaw-by-IPC controller to filtering the yaw alignment error, [-].

102

Y_omegaLPFast

0.20940 ! Y_omegaLPFast - Corner frequency fast low pass filter, 1.0 [rad/s]

103

Y_omegaLPSlow

0.10470 ! Y_omegaLPSlow - Corner frequency slow low pass filter, 1/60 [rad/s]

6.5. ROSCO v2.4.1 to ROSCO v2.5.0

Two filter parameters were added to - change the high pass filter in the floating feedback module - change the low pass filter of the wind speed estimator signal that is used in torque control

Open loop control inputs, users must specify: - The open loop input filename, an example can be found in Examples/Example_OL_Input.dat - Indices (columns) of values specified in OL_Filename

IPC - Proportional Control capabilities were added, 1P and 2P gains should be specified

Line

Input Name

Example Value

20

OL_Mode

0 ! OL_Mode - Open loop control mode {0: no open loop control, 1: open loop control vs. time, 2: open loop control vs. wind speed}

27

F_WECornerFreq

0.20944 ! F_WECornerFreq - Corner frequency (-3dB point) in the first order low pass filter for the wind speed estimate [rad/s].

29

F_FlHighPassFreq

0.01000 ! F_FlHighPassFreq - Natural frequency of first-order high-pass filter for nacelle fore-aft motion [rad/s].

50

IPC_KP

0.000000 0.000000 ! IPC_KP - Proportional gain for the individual pitch controller: first parameter for 1P reductions, second for 2P reductions, [-]

125

OL_Filename

“14_OL_Input.dat” ! OL_Filename - Input file with open loop timeseries (absolute path or relative to this file)

126

Ind_Breakpoint

1 ! Ind_Breakpoint - The column in OL_Filename that contains the breakpoint (time if OL_Mode = 1)

127

Ind_BldPitch

2 ! Ind_BldPitch - The column in OL_Filename that contains the blade pitch input in rad

128

Ind_GenTq

3 ! Ind_GenTq - The column in OL_Filename that contains the generator torque in Nm

129

Ind_YawRate

4 ! Ind_YawRate - The column in OL_Filename that contains the generator torque in Nm