# Tuning Parameters¶

Local Options: DBS Parameters for Variables

The following is a list of parameters that may be found in the DBS file for variables listed in the INFO file. It is a complete list of the configuration parameters for FV, MV, SV, CV type parameters and variables. Each section includes an indication of the variable type (Integer or Real), the default value, data flow, and description.

## AWS¶

Local Options | Global Options

Type: Floating Point, Output

Default Value: 0

Description: Anti-Windup Status for a Manipulated Variable 0: Not at a limit 1: An upper or lower bound is reached

Explanation: Anti-Windup Status (AWS) is terminology borrowed from classical controls such as Proportional Integral Derivative (PID) controllers. Anti-Windup refers to the integral action that is paused when the controller reaches a saturation limit. An example of a saturation limit is a valve that is limited to 0-100% open. If the controller requests -10%, the valve is still limited to 0%. The AWS indication is useful to show when a controller is being driven by an optimization objective versus constraints that limit movement. A Key Performance Indicator (KPI) of many controllers is the fraction of time that a MV is not at an upper or lower bound limit.

## BIAS¶

Type: Floating Point, Input/Output

Default Value: 0.0

Description: Additive correction factor to align measurement and model values for Controlled Variables (CVs) BIAS is additive factor that incorporates the difference between the current measured value and the initial condition of the controller. FSTATUS determines how much of the raw measurement is used to update the value of MEAS. A feedback status of 0 indicates that the measurement should not be used and the BIAS value is kept at the initial value of 0. A feedback status of 1 uses all of the measurement in updating MEAS. A feedback status in between 0 and 1 updates MEAS with a fractional contribution from LSTVAL and the new measurement. The value of BIAS is updated from MEAS and the unbiased model prediction (Model_u).

$BIAS = MEAS - Model_u$

The BIAS is added to each point in the horizon and the controller objective function drives the biased model (Model_b) to the requested set point range.

$Model_b = Model_u + BIAS$

The value of BIAS can also be set to an external value by setting the option BIAS option directly and setting FSTATUS to 0 (OFF).

## COST¶

Type: Real, Input

Default Value: 0.0

Description: Cost weight: (+)=minimize, (-)=maximize

Explanation: Multiplies the parameter by the COST value specified. This is used to scale the terms in the objective function. It is important that each term in the objective function is scaled to be of the same order of magnitude to ensure that the optimizer considers each of them (unless different weighting is specifically desired).

## CRITICAL¶

Type: Integer, Input

Default Value: 0

Description: Critical: 0=OFF, 1=ON

Explanation: Turns the application off ( REQCTRLMODE =1) if the instrument that provides the measurement has a PSTATUS =0 (bad measurement). A critical measurement has this flag on to give control back to the operator if the measurement fails to deliver a good value.

## DCOST¶

Type: Real, Input

Default Value: 0.00001

Description: Delta cost penalty for MV movement

Explanation: Adds a term to the objective function that gives a minor penalty for changing the MV. The weight of the penalty is adjusted with the input value. This is useful for systems where excessive movement to the MV causes damage to equipment or undesirable results. By assigning a weight that is small in comparison to the objective function value, optimal performance is achieved while changing the MV only when necessary.

$objective \mathrel{+}= \sum_{i=1} \left\Vert x_{i-1} - x_i \right\Vert _p$

Where p is equal to EV_TYPE (for IMODE=5or8) or CV_TYPE (for IMODE=6or9).

## DMAX¶

Type: Real, Input

Default Value: 1.0e20

Description: Delta MV maximum step per horizon interval

Explanation: Applies a hard constraint that prevents the MV from being changed by more than the specified value in one time step. This can be used to prevent large jumps in the MV value in the case where that is either undesirable or infeasible. The time step is defined as the length of the first time step in the csv file.

## DMAXHI¶

Type: Real, Input

Default Value: 1.0e20

Description: Delta MV positive maximum step per horizon interval

Explanation: Like DMAX, but only with positive changes. Applies a hard constraint that prevents the MV from being changed by more than the specified value in one time step, but this constraint only applies to increases in the MV value. This can be used to prevent large jumps in the MV value in the case where that is either undesirable or infeasible.

## DMAXLO¶

Type: Real, Input

Default Value: -1.0e20

Description: Delta MV negative maximum step per horizon interval

Explanation: Like DMAX, but only with negative changes. Applies a hard constraint that prevents the MV from being changed by more than the specified value in one time step, but this constraint only applies to decreases in the MV value. This can be used to prevent large jumps in the MV value in the case where that is either undesirable or infeasible.

## DPRED¶

Type: Real, Output

Default Value: 0.0

Description: Delta prediction changes for each step’

Explanation: Changes in the manipulated variables (MVs) are listed for the first 10 steps of the horizon including DPRED[1], DPRED[2], etc. Values of zero indicate that there are no changes. With REQCTRLMODE=1 (COLD), all DPRED values are zero. With REQCTRLMODE=2 (WARM), only DPRED[1] is required to be zero but the other segments may be non-zero. With REQCTRLMODE=3 (CONTROL), the first DPRED value is changing.

## FSTATUS¶

Type: Real, Input

Default Value: 1.0

Description: Feedback status: 1=ON, 0=OFF

Explanation: Determines how much of the measurement ( MEAS) to use in updating the values in the model. A feedback status of 0 indicates that the measurement should not be used either in estimation or in updating a parameter in the model. A feedback status of 1 uses all of the measurement. A feedback status in between updates the model OR parameter value (x) according to the formula:

$x = LSTVAL * (1-FSTATUS) + MEAS * FSTATUS$

## FDELAY¶

Type: Integer, Input

Default Value: 0

Description: Feedback delay: 0=No Delay, >=1 horizon steps for delay

Explanation: The feedback delay places the measurement at the appropriate point in the horizon for dynamic estimation. Typical examples are laboratory measurement or gas chromatographs that report measurements that were taken in the past, usually with a 10 min - 2 hour delay. When the new value is reported, it should be placed at the appropriate point in the data time horizon. FDELAY is the number of horizon steps in the past where the measurement was actually taken.

## LOWER¶

Type: Real, Input

Default Value: -1.0e20

Description: Lower bound

Explanation: LOWER is the lower limit of a variable. If the variable guess value is below the lower limit, it is adjusted to the lower limit. The lower limit is also checked with the upper limit to ensure that it is less than or equal to the upper limit. If the lower limit is equal to the upper limit, the variable is fixed at that value.

## LSTVAL¶

Type: Real, Output

Default Value: 1.0

Description: Last value from previous solution

Explanation: The last value (LSTVAL) is the value from the prior solution of the optimization problem or simulation.

## MEAS¶

Type: Real, Input

Default Value: 1.0

Description: Measured value

Explanation: The measurement of a variable or parameter. The value of MEAS is initialized to the initial model value. The MEAS value is used in the application if FSTATUS is greater than zero, but not when FSTATUS=0.

MEAS must be a scalar and only one measurement is loaded in each solve() command. If multiple measurements are needed, they can be loaded through the VALUE attribute in their respective locations.

## MEAS_GAP¶

Type: Real, Input

Default Value: 1.0

Description: Deadband for noise rejection of measurements in MHE

Explanation: Used in estimation problems with EV_TYPE =1 (l1-norm objective). The measurement gap (MEAS_GAP) defines a dead-band region around the measurement. If the model prediction is within that dead-band, there is no objective function penalty. Outside of that region, there is a linear penalty specified with the WMEAS parameter. The WMODEL parameter is the weighting given to deviation from the prior model prediction but does not have a deadband around the prior model prediction. The gap is only around the measured values.

## MODEL¶

Type: Real, Output

Default Value: 1.0

Description: Model predicted value

Explanation: The MODEL value is a property of SV (State Variable) and CV (Controlled Variable) types. It is the predicted value of the current time. The current time is the first time step for a simulator or controller and the last value in the horizon for estimation.

## MV_STEP_HOR¶

Type: Integer, Input

Default Value: 0 (for global MV_STEP_HOR ) or 1 (for MV(#).MV_STEP_HOR)

Description: Step length for manipulated variables: 0 uses global MV_STEP_HOR as default

Explanation: The manipulated variable step horizon (MV_STEP_HOR) is by default to allow the MV to be adjusted every time set of the collocation. There are cases where the MV should not move every time step but should be constrained to move only a certain multiple of the collocation time step. With MV_STEP_HOR = 2, the manipulated variable is allowed to move on the first step and every other step thereafter. MV_STEP_HOR = 5, the manipulated variable is allowed to move on the first step and every 5th step thereafter. There is also a global parameter MV_STEP_HOR that is used as a global configuration for all MVs when the individual MV option is set to 0.

## NEWVAL¶

Type: Real, Output

Default Value: 1.0

Description: New value implemented by the estimator or controller (NEWVAL = MEAS when not in control)

Explanation: The new value of the parameter estimate (FV) or manipulated variable (MV). This value is taken from the first step of the controller or the last step of the estimator. The NEWVAL is set equal to the measured value if the FV or MV status is off and the FSTATUS (feedback status) is ON (1).

## NXTVAL¶

Type: Real, Output

Default Value: 1.0

Description: Next value that the estimator or controller would implement if CTRLMODE=3.

Explanation: The next value (NXTVAL) to be implemented by the controller. This is especially useful for a controller in WARM mode (CTRLMODE=2) where no values are changed on the first step (still in manual mode) but the control actions are computed beyond the first step. This is a useful mode to inspect the controller performance before it is turned on.

## OBJPCT¶

Type: Real, Output

Default Value: 0.0

Description: Percent of objective function contribution considering all SV and CV variables

Explanation: The objective function percent is useful to see which controlled variables (CVs) are contributing the most to the controller overall objective function. If one of the CVs has a high OBJPCT, it may be dominating the controller action and the tuning factors WSP (CV_TYPE=2) or WSPHI/WSPLO (CV_TYPE=1) should be adjusted accordingly.

## OSTATUS¶

Type: Integer, Output

Default Value: 0

Description: Bit encoding for status messages

Explanation: Status messages encoded in binary form for transfer and decoding. This is deprecated and will be removed in a future release.

## OSTATUSCHG¶

Type: Integer, Output

Default Value: 0

Description: Change in bit encoding for status messages

Explanation: Change of status messages, encoded in binary form for transfer and decoding. This is deprecated and will be removed in a future release.

## PRED¶

Type: Real, Output

Default Value: 1.0

Description: Prediction horizon

Explanation: The first predictions of a state (SV) or controlled (CV) variable. The number of PRED values is limited to the first 10 but can be less with a shorter horizon. PRED[0] is the initial condition while PRED[1] is the first predicted step. The other values PRED[2], PRED[3], … , PRED[10] are the predicted model values up to a horizon of 10 time points.

## PSTATUS¶

Type: Integer, Input

Default Value: 1

Explanation: An indication of the instrument health. If PSTATUS is 0 then the instrument is determined to be bad and the measurement should not be used. By default, all instruments are assumed to be reporting good values.

## REQONCTRL¶

Type: Integer, Input

Default Value: 0

Description: Required for control mode to be ON (3): 1=ON, 0=OFF

Explanation: Certain Manipulated Variables (MVs) and Controlled Variables (CVs) are critical to the operation of the entire application. When any of the MVs or CVs with REQONCTRL are turned off, the entire application is turned off (CTRLMODE=1). The requested control mode (REQCTRLMODE) is the requested controller mode but this option downgrades the controller to a simulation mode if a critical MV or CV is OFF.

## SP¶

Type: Real, Input

Default Value: 0.0

Description: Set point for squared error model

Explanation: The target value for a controller that is using a squared error objective (single trajectory track). The setpoint (SP) is the final target value.

## SPHI¶

Type: Real, Input

Default Value: 1.0e20

Description: Set point high for linear error model

Explanation: The upper range of the target region (dead-band) for a controller that is using an l1-norm error objective. The setpoint high (SPHI) is the upper final target value.

## SPLO¶

Type: Real, Input

Default Value: -1.0e20

Description: Set point low for linear error model

Explanation: The lower range of the target region (dead-band) for a controller that is using an l1-norm error objective. The setpoint low (SPLO) is the lower final target value.

## STATUS¶

Type: Integer, Input

Default Value: 0

Description: Status: 1=ON, 0=OFF

Explanation: The STATUS specifies when a parameter (FV or MV) that is normally fixed (OFF) can become calculated (ON). Similarly, STATUS set to ON, allows a controlled variable (CV) to be included as a model predictive controller set point target or steady state optimizer target. The STATUS value indicates whether that variable should be included in the optimization (ON) or is merely a fixed input or prediction (OFF). It is acceptable to have only a subset of parameters (FVs or MVs) or variables (CVs) with STATUS set to ON. The STATUS can be turned ON or OFF for each cycle of the controller as needed without disrupting the overall application. An estimator uses STATUS for FVs and MVs but uses FSTATUS (not STATUS) to determine when measurements are used.

## TAU¶

Type: Real, Input

Default Value: 60.0

Description: Time constant for controlled variable response

Explanation: The time constant is a tuning parameter for the speed of response of a reference trajectory. When the set point is stepped to a new value, the time constant (TAU) adjusts the speed of response with SP_tr = (1-exp(-t/TAU)) (SPnew - SPold) + SPold where SPold is the prior set point, SPnew is the new set point, t is the time, TAU is the time constant, and SP_tr is the resultant trajectory.

## TIER¶

Type: Integer, Input

Default Value: 1

Description: Tiered order of Manipulated Variables (MVs) and Controlled Variables (CVs)

Explanation: TIER is an ascending order of precedence for optimization. Tuning an application with multiple objectives can be challenging to coordinate the weights of competing objectives although there is a clear rank priority order. TIER gives the option to split the degrees of freedom into multiple sub-optimization problems. The highest priority values are optimized first while the subsequent priority values are optimized as a next step. Valid TIER values for MVs and CVs are between 1 and 100. There are up to 100 optimization levels and individual MVs / CVs must be at the same TIER value to be included in the sub-optimization problem. The STATUS must also be ON (1) for an MV to be a degree of freedom. The STATUS must also be ON (1) for an CV to be included in the objective function. If there is a sub-optimization problem that has no MV degrees of freedom, a warning message is displayed.

## TR_OPEN¶

Type: Real, Input

Default Value: 1.0

Description: Initial trajectory opening ratio (0=ref traj, 1=tunnel, 2=funnel)

Explanation: TR_OPEN controls the trajectory opening for CV_TYPE = 1. It is the ratio of opening gap to the final gap of SPHI - SPLO. A value of TR_OPEN = 2 means that the initial trajectory is twice the width of the final gap of SPHI - SPLO. With TR_OPEN = 0, the initial trajectory starts at the same point and widens with a first order response as specified by TAU to final destinations of SPHI and SPLO. Each CV can have a different TR_OPEN.

## TR_INIT¶

Type: Integer, Input

Default Value: 0

Description: Setpoint trajectory initialization (0=dead-band, 1=re-center with coldstart/out-of-service, 2=re-center always)

Explanation: TR_INIT is an option to specify how the initial conditions of the controlled variable’s (CV) setpoint reference trajectory should change with each cycle. The trajectory is set by TAU. An option of 0 specifies that the initial conditions should start at SPHI and SPLO, creating an unchanging target over the horizon. An option of 1 makes the initial conditions equal to the current process variable value only on coldstart ( COLDSTART>=1) or with CTRLMODE <=2 when the controller is out of service. Otherwise, the reference trajectory is updated from the first step of the prior solution. When TR_INIT=2, the reference trajectory realigns to the variable’s initial condition with each cycle. Each CV can have a different TR_INIT. The trajectory is also influenced by TR_OPEN.

## UPPER¶

Type: Real, Input

Default Value: 1.0e20

Description: Upper bound

Explanation: UPPER is the the upper limit of a variable. If the variable guess value is above the upper limit, it is adjusted to the upper limit before it is given to the solver. The upper limit is also checked with the lower limit ( LOWER) to ensure that it is greater than or equal to the lower limit. If the upper limit is equal to the lower limit, the variable is fixed at that value.

## VALUE¶

Type: Real, Input/Output

Default Value: 1

Description: Value of the variable

Explanation: VALUE is a floating point number of a variable.

## VDVL¶

Type: Real, Input

Default Value: 1.0e20

Description: Delta validity limit

Explanation: VDVL is the maximum change of a measured value before it is considered an unrealistic change. The change in measured values is recorded at every cycle of the application and compared to the VDVL limit. Validity limits are placed to catch instrument errors that may otherwise create bad inputs to the application. If a delta validity limit is exceeded, the action is to either freeze the measured value at the last good value ( VLACTION =0) or change the measured value by a maximum of VDVL in the direction of the bad measurement ( VLACTION =1). Another way to minimize the impact of unrealistic changes in measurements is to set FSTATUS between 0 and 1 with values closer to 0 becoming insensitive to measurement changes.

## VLACTION¶

Type: Integer, Input

Default Value: 0

Description: Validity Limit Action

Explanation: VLACTION is the validity limit action when VDVL is exceeded. The change in measured values is recorded at every cycle of the application and compared to the VDVL limit. Validity limits are placed to catch instrument errors that may otherwise create bad inputs to the application. If a delta validity limit is exceeded, the action is to either freeze the measured value at the last good value (VLACTION=0) or change the measured value by a maximum of VDVL in the direction of the bad measurement (VLACTION=1).

## VLHI¶

Type: Real, Input

Default Value: 1.0e20

Description: Upper validity limit

Explanation: VLHI is the upper validity limit for a measured value. Validity limits are one way to protect an application against bad measurements. This gross error detection relies on a combination of change values and absolute limits to determine when a measurement should be rejected. If VLHI is exceeded, the measured value is placed at VLHI or the maximum move allowed by VDVL when VLACTION =1. If VLACTION =0, there is no change in the measured value when a limit ( VDVL, VLHI, VLLO) is exceeded.

## VLLO¶

Type: Real, Input

Default Value: -1.0e20

Description: Lower validity limit

Explanation: VLLO is the lower validity limit for a measured value. Validity limits are one way to protect an application against bad measurements. This gross error detection relies on a combination of change values and absolute limits to determine when a measurement should be rejected. If the VLLO limit is crossed, the measured value is placed at VLLO or the maximum move allowed by VDVL when VLACTION=1. If VLACTION=0, there is no change in the measured value when a limit (VDVL, VLHI, VLLO) is exceeded.

## WMEAS¶

Type: Real, Input

Default Value: 20.0

Description: Objective function weight on measured value

Explanation: A weighting factor to penalize deviation of current model predictions from measured values. This is used in estimation applications ( Modes =2, 5, or 8) where the penalty. The infinite estimation horizon approximation is especially useful for systems that have weakly observable or unobservable states. A higher WMODEL can also help to reduce the aggressiveness of the estimator in aligning with the measurements by balancing with a penalty against shifting too far from the prior predictions. The WMODEL value should never be equal to or larger than the WMEAS value for EV_TYPE =1 (l1-norm). A WMODEL value higher than WMEAS will ignore measured values in favor of matching prior model predictions.

## WMODEL¶

Type: Real, Input

Default Value: 2.0d0

Description: Objective function weight on model value

Explanation: A weighting factor to penalize deviation of current model predictions from prior model predictions. This is used in estimation applications (IMODE=2, 5, or 8) where the penalty from a prior model prediction is a “forgetting factor” that approximates an infinite estimation horizon or favors prior predictions. The infinite estimation horizon approximation is especially useful for systems that have weakly observable or unobservable states. A higher WMODEL can also help to reduce the aggressiveness of the estimator in aligning with the measurements by balancing with a penalty against shifting too far from the prior predictions. The WMODEL value should never be equal to or larger than the WMEAS value for EV_TYPE=1 (l1-norm). A WMODEL value higher than WMEAS will ignore measured values in favor of matching prior model predictions.

## WSP¶

Type: Real, Input

Default Value: 20.0

Description: Objective function weight on set point for squared error model

Explanation: A weighting factor to penalize a squared error from the setpoint trajectory with final target SP. The weighting factor is positive to drive the response to the SP trajectory and negative to drive it away from the SP. A negative WSP is highly unlikely and the value should generally be positive.

## WSPHI¶

Type: Real, Input

Default Value: 20.0

Description: Objective function weight on upper set point for linear error model

Explanation: A weighting factor to penalize deviation above the upper setpoint trajectory with final target SPHI. If there is no penalty to cross the upper setpoint, WSPHI can be set to zero.

## WSPLO¶

Type: Real, Input

Default Value: 20.0

Description: Objective function weight on lower set point for linear error model

Explanation: A weighting factor to penalize deviation below the lower setpoint trajectory with final target SPLO. If there is no penalty to cross the lower setpoint trajectory, WSPLO can be set to zero.