APMonitor

(:title APMonitor Local Options:)

Local Options | Global Options

Below is a list of links for configuration options for parameters and variables. It is a complete list of the configuration parameters for FV, MV, SV, CV type parameters and variables. There are also Global Options that configure and report application level information.

An option can be changed from a MATLAB or Python script. Below is a command to set an option to turn on a controlled variable named CV1 in a Nonlinear Control application with CV1.STATUS=1.

 apm_option(s,a,'cv1.status',1)

Output options can also be read after the solution with the command to access a tag from the database. If the tag does not exist, a value of -99999 is returned. In this case, the user wants to know the new value (NEWVAL) of a manipulated variable that should be implemented into the process.

 new_mv2 = apm_tag(s,a,'mv2.newval')

In this case, the argument s='https://byu.apmonitor.com' is the server address and a='myApp' is the application name. When running a local server, the server address should be changed to s='https://127.0.0.1' or s='https://localhost' .

When a parameter is declared as a Fixed Value (FV), it automatically receives the following properties: CRITICAL, DMAX, DMAXHI, DMAXLO, FSTATUS, LOWER, LSTVAL, MEAS, NEWVAL, OSTATUS, OSTATUSCHG, PSTATUS, STATUS, UPPER, VDVL, VLACTION, VLHI, VLLO. Constraints are also added to the problem to implement DMAX, DMAXHI, and DMAXLO. These properties and other properties are required to configure an FV that can either act as a measured or unmeasured process disturbance or as a single controller degree of freedom to drive controlled variables (CVs) to targets when STATUS is ON. The FV values can be adjusted by either the user or the optimizer but are restricted to one value over the data horizon.

When a parameter is declared as a Manipulated Variable or MV (adjustable at each time step), it automatically receives the following properties: AWS, COST, CRITICAL, DCOST, DMAX, DMAXHI, DMAXLO, DPRED, FSTATUS, LOWER, LSTVAL, MEAS, MV_STEP_HOR, NEWVAL, NXTVAL, OSTATUS, OSTATUSCHG, PRED, PSTATUS, REQONCTRL, STATUS, TIER, UPPER, VDVL, VLACTION, VLHI, VLLO. Equations are also added to the problem to implement the necessary constraints and objective terms. These properties are required to configure an MV that can either act as a measured or unmeasured process disturbance or a controller degree of freedom to drive controlled variables (CVs) to targets when STATUS is ON.

When a variable is declared as a State Variable (SV), it automatically receives the following properties: FSTATUS, LOWER, MEAS, MODEL, PRED, UPPER. State variables to not enter into the objective function but are mostly are quantities such as inferentials or other predictions that are viewed in the web interface.

When a variable is declared as a Controlled Variable (CV), it automatically receives the following properties: BIAS, COST, CRITICAL, FSTATUS, FDELAY, LOWER, LSTVAL, MEAS, MEAS_GAP, MODEL, OSTATUS, OSTATUSCHG, PRED, PSTATUS, SP, SPHI, SPLO, STATUS, TAU, TIER, TR_INIT, TR_OPEN, UPPER, VDVL, VLACTION, VLHI, VLLO, WMEAS, WMODEL, WSP, WSPHI, WSPLO. Equations are also added to the problem to implement the necessary constraints and objective terms. Controlled variables enter into the objective function for optimizer and control functions (IMODE=3, 6, and 9) when STATUS is ON. Controlled variables are reconciled to data by including error terms for model prediction alignment to measurements in the objective function for parameter and state estimation problems (IMODE=2, 5, 8) when FSTATUS is > 0.

The following is a list of global options that may be set to configure an APMonitor application. It is a complete list of the configuration parameters for APM type parameters. Each section includes an indication of the variable type (Integer or Real), the default value, data flow, and a brief description. While this list is exhaustive, there are typically only a few of these that are used most commonly for estimation and control.

Below is a list of links for configuration options for parameters and variables. It is a complete list of the configuration parameters for FV, MV, SV, CV type parameters and variables.

An option can be changed from a MATLAB or Python script. Below is a command to set an option to turn on a controlled variable named CV1 in a Nonlinear Control application with CV1.STATUS=1.

 apm_option(s,a,'cv1.status',1)

Output options can also be read after the solution with the command to access a tag from the database. If the tag does not exist, a value of -99999 is returned. In this case, the user wants to know the new value (NEWVAL) of a manipulated variable that should be implemented into the process.

 new_mv2 = apm_tag(s,a,'mv2.newval')

In this case, the argument s='https://byu.apmonitor.com' is the server address and a='myApp' is the application name. When running a local server, the server address should be changed to s='https://127.0.0.1' or s='https://localhost' .

The following is a list of global options that may be set to configure an APMonitor application. It is a complete list of the configuration parameters for APM type parameters. Each section includes an indication of the variable type (Integer or Real), the default value, data flow, and a brief description. While this list is exhaustive, there are typically only a few of these that are used most commonly for estimation and control.

The following is a list of configuration options for parameters and variables. It is a complete list of the configuration parameters for FV, MV, SV, CV type parameters and variables.

When a parameter is declared as a Manipulated Variable or MV (adjustable at each time step), it automatically receives the following properties: AWS, COST, CRITICAL, DCOST, DMAX, DMAXHI, DMAXLO, DPRED, FSTATUS, LOWER, LSTVAL, MEAS, MV_STEP_HOR, NEWVAL, NXTVAL, OSTATUS, OSTATUSCHG, PRED, PSTATUS, REQONCTRL, STATUS, TIER, UPPER, VDVL, VLACTION, VLHI, VLLO. Equations are also added to the problem to implement the necessary constraints and objective terms. These properties are required to configure an MV that can either act as a measured or unmeasured process disturbance or a controller degree of freedom to drive controlled variables (CVs) to targets when STATUS is ON.

When a variable is declared as a State Variable (SV), it automatically receives the following properties: FSTATUS, LOWER, MEAS, MODEL, PRED, UPPER. State variables to not enter into the objective function but are mostly are quantities such as inferentials or other predictions that are viewed in the web interface.

When a variable is declared as a Controlled Variable (CV), it automatically receives the following properties: BIAS, COST, CRITICAL, FSTATUS, FDELAY, LOWER, LSTVAL, MEAS, MEAS_GAP, MODEL, OSTATUS, OSTATUSCHG, PRED, PSTATUS, SP, SPHI, SPLO, STATUS, TAU, TIER, TR_INIT, TR_OPEN, UPPER, VDVL, VLACTION, VLHI, VLLO, WMEAS, WMODEL, WSP, WSPHI, WSPLO. Equations are also added to the problem to implement the necessary constraints and objective terms. Controlled variables enter into the objective function for optimizer and control functions (IMODE=3, 6, and 9) when STATUS is ON. Controlled variables are reconciled to data by including error terms for model prediction alignment to measurements in the objective function for parameter and state estimation problems (IMODE=2, 5, 8) when FSTATUS is > 0.

Each link includes an indication of the variable type (Integer or Real), the default value, data flow, a description, and a more complete explanation.

• FSTATUS

• FSTATUS

• AWS
• BIAS
• COST
• CRITICAL
• DCOST
• DMAX
• DMAXHI
• DMAXLO
• DPRED
• FDELAY
• FSTATUS
• LOWER
• LSTVAL
• MEAS
• MEAS_GAP
• MODEL
• MV_STEP_HOR
• NEWVAL
• NXTVAL
• OSTATUS
• OSTATUSCHG
• PRED
• PSTATUS
• REQONCTRL
• SP
• SPHI
• SPLO
• STATUS
• TAU
• TIER
• TR_INIT
• TR_OPEN
• UPPER
• VDVL
• VLACTION
• VLHI
• VLLO
• WMEAS
• WMODEL
• WSP
• WSPHI
• WSPLO

• COST

(:title APMonitor Options:)

(:title APMonitor Parameter and Variable Options:) (:keywords FV, Fixed, MV, Manipulated, SV, State, CV, Controlled, Variable, Optimization, Estimation, Option, Configure, Default, Description:) (:description APMonitor options for FV, MV, SV, CV types are set from MATLAB or Python clients.:)

The following is a list of configuration options for parameters and variables. 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 a brief description.

 Description: Deadband for noise rejection of 
              measurements in MHE

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

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

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

 Description: Next value that the estimator or controller
              would implement were it ON (APM.CTRLMODE=3)

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

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

 Description: Time constant for controlled variable
              response

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

 Description: Trajectory initialization
              0=dead-band
              1=re-center with restart
              2=re-center always

 Description: Objective function weight on
              measured value

 Description: Objective function weight on
              model value

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

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

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

 Description: Delta MV positive maximum step per horizon
              interval

 Description: Delta MV negative maximum step per horizon
              interval

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

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

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

• TR_INIT
• UPPER

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.

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.

• COST
• CRITICAL
• DCOST
• DMAX
• DMAXHI
• DMAXLO
• DPRED
• FSTATUS
• FDELAY
• LOWER
• LSTVAL
• MEAS
• MEAS_GAP
• MODEL
• MV_STEP_HOR
• NEWVAL
• NXTVAL
• OBJPCT
• OSTATUS
• OSTATUSCHG
• PRED
• PSTATUS
• REQONCTRL
• SP
• SPHI
• SPLO
• STATUS
• TAU
• TR_OPEN
• TR_INIT UPPER
• VDVL
• VLHI
• VLLO
• WMEAS
• WMODEL
• WSP
• WSPHI
• WSPLO

COST

 Type: Real 
 Default Value: 0.0
 Data Flow: Input
 Description: Cost weight: (+)=minimize, (-)=maximize

CRITICAL

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Critical: 0=OFF, 1=ON' 

DCOST

 Type: Real 
 Default Value: 0.00001
 Data Flow: Input
 Description: Delta cost penalty for MV movement

DMAX

 Type: Real 
 Default Value: 1.0e20
 Data Flow: Input
 Description: Delta MV maximum step per horizon interval

DMAXHI

 Type: Real 
 Default Value: 1.0e20
 Data Flow: Input
 Description: Delta MV positive maximum step per horizon interval

DMAXLO

 Type: Real 
 Default Value: -1.0e20
 Data Flow: Input
 Description: Delta MV negative maximum step per horizon interval

DPRED

 Type: Real 
 Default Value: 0.0
 Data Flow: Output
 Description: Delta prediction changes for each step' 

FSTATUS

 Type: Real 
 Default Value: 1.0
 Data Flow: Input
 Description: Feedback status: 1=ON, 0=OFF

FDELAY

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Feedback delay: 0=No Delay, >=1 horizon steps for delay

LOWER

 Type: Real 
 Default Value: -1.0e20
 Data Flow: Input
 Description: Lower bound

LSTVAL

 Type: Real 
 Default Value: 1.0
 Data Flow: Output
 Description: Last value from previous solution

MEAS

 Type: Real 
 Default Value: 1.0
 Data Flow: Input
 Description: Measured value

MEAS_GAP

 Type: Real 
 Default Value: 1.0
 Data Flow: Input
 Description: Deadband for noise rejection of measurements in MHE

MODEL

 Type: Real 
 Default Value: 1.0
 Data Flow: Output
 Description: Model predicted value

MV_STEP_HOR

 Type: Integer 
 Default Value: 1 (for NLC.MV_STEP_HOR) or 0 (for MV(#).MV_STEP_HOR) 
 Data Flow: Input
 Description: Step length for manipulated variables: 0 uses NLC.MV_STEP_HOR as default

NEWVAL

 Type: Real 
 Default Value: 1.0
 Data Flow: Output
 Description: New value implemented by the estimator or controller (NEWVAL = MEAS when not in control)

NXTVAL

 Type: Real 
 Default Value: 1.0
 Data Flow: Output
 Description: Next value that the estimator or controller would implement were it on

OBJPCT

 Type: Real 
 Default Value: 0.0
 Data Flow: Output
 Description: Percent of objective function contibution considering all SV and CV variables

OSTATUS

 Type: Integer 
 Default Value: 0
 Data Flow: Input and Output
 Description: Bit encoding for status messages

OSTATUSCHG

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Change in bit encoding for status messages

PRED

 Type: Real 
 Default Value: 1.0
 Data Flow: Output
 Description: Prediction horizon

PSTATUS

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Instrument status: 1=GOOD, 0=BAD

REQONCTRL

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Required for control mode to be ON (3): 1=ON, 0=OFF

SP

 Type: Real 
 Default Value: 0.0
 Data Flow: Input
 Description: Set point for squared error model

SPHI

 Type: Real 
 Default Value: 1.0e20
 Data Flow: Input
 Description: Set point high for linear error model

SPLO

 Type: Real 
 Default Value: -1.0e20
 Data Flow: Input
 Description: Set point low for linear error model

STATUS

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Status: 1=ON, 0=OFF

TAU

 Type: Real 
 Default Value: 60.0
 Data Flow: Input
 Description: Time constant for controlled variable response

TR_OPEN

 Type: Real 
 Default Value: 1.0
 Data Flow: Input
 Description: Initial trajectory opening ratio (0=ref traj, 1=tunnel, 2=funnel)

TR_INIT

 Type: Integer
 Type: Real
 Default Value: 1
 Data Flow: Input
 Description: Traj initialization (0=dead-band, 1=re-center with coldstart/out-of-service, 2=re-center always)

UPPER

 Type: Real 
 Default Value: 1.0e20
 Data Flow: Input
 Description: Upper bound

VDVL

 Type: Real 
 Default Value: 1.0e20
 Data Flow: Input
 Description: Delta validity limit

VLHI

 Type: Real 
 Default Value: 1.0e20
 Data Flow: Input
 Description: Upper validity limit

VLLO

 Type: Real 
 Default Value: -1.0e20
 Data Flow: Input
 Description: Lower validity limit

WMEAS

 Type: Real 
 Default Value: 20.0
 Data Flow: Input
 Description: Objective function weight on measured value

WMODEL

 Type: Real 
 Default Value: 2.0d0
 Data Flow: Input
 Description: Objective function weight on model value

WSP

 Type: Real 
 Default Value: 1.0
 Data Flow: Input
 Description: Objective function weight on set point for squared error model

WSPHI

 Type: Real 
 Default Value: 1.0
 Data Flow: Input
 Description: Objective function weight on upper set point for linear error model

WSPLO

 Type: Real 
 Default Value: 1.0
 Data Flow: Input
 Description: Objective function weight on lower set point for linear error model