APMonitor

(:title APMonitor Global Options:)

Local Options | Global Options

Global options in APMonitor configure and report application level information. Global options begin with the prefix APM. There are also Local Options that configure and report parameters associated with individual variables or parameters. Below is a list of all global options.

An option can be changed from a MATLAB or Python script. Below is a command to set an option to run the model as a Nonlinear Control application with APM.IMODE=6.

 apm_option(s,a,'apm.imode',6)

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 if the application was solved successfully by retrieving the APM.APPSTATUS value.

 success_check = apm_tag(s,a,'apm.appstatus')

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.

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 if the application was solved successfully by retrieving the APM.APPSTATUS value.

An option can be changed from a MATLAB or Python script. Below is a command to set an option to run the model as a Nonlinear Control application with APM.IMODE?=6.

 apm_option(s,a,'apm.imode',6)

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 if the application was solved successfully by retrieving the APM.APPSTATUS? value.

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.

An option can be changed from a MATLAB or Python script. An example command to define one of the options is

 apm_option(s,a,'apm.imode',5)

Output options can also be read after the solution with the command

 success_check = apm_tag(s,a,'apm.appstatus')

In this case, the argument s='https://byu.apmonitor.com' is the server address and a='myApp' is the application name.

An option can be changed from a MATLAB or Python script. An example command to define one of the options is apm_option(s,a,'apm.imode',5). Output options can also be read after the solution with the command apm_tag(s,a,'apm.appstatus'). In this case, the argument s='https://byu.apmonitor.com' is the server address and a='myApp' is the application name.

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.

Objective Functions: Estimation (EV_Type): https://apmonitor.com/do/index.php/Main/EstimatorObjective Control (CV_Type): https://apmonitor.com/do/index.php/Main/ControllerObjective Local Options: DBS Parameters for Variables  

An option can be changed from a MATLAB or Python script. An example command to define one of the options is apm_option(s,a,'apm.imode',5). Output options can also be read after the solution with the command apm_tag(s,a,'apm.appstatus'). In this case, the argument s='https://byu.apmonitor.com is the server address and a='myApp is the application name.

              8=sqe, Dynamic estimation (sequential)
              9=sqo, Dynamic control (sequential)

• APM.EV_TYPE

• APM.APPINFO
• APM.APPINFOCHG
• APM.APPSTATUS
• APM.AUTO_COLD
• APM.BAD_CYCLES
• APM.BNDS_CHK
• APM.COLDSTART
• APM.CSV_READ
• APM.CSV_WRITE
• APM.CTRL_HOR
• APM.CTRL_TIME
• APM.CTRL_UNITS
• APM.CTRLMODE
• APM.CV_TYPE
• APM.CV_WGT_SLOPE
• APM.CV_WGT_START
• APM.CYCLECOUNT
• APM.DBS_LEVEL
• APM.DBS_READ
• APM.DBS_WRITE
• APM.DIAGLEVEL
• APM.EV_WGT_SLOPE
• APM.EV_TYPE
• APM.FILTER
• APM.FRZE_CHK
• APM.HIST_HOR
• APM.HIST_UNITS
• APM.ICD_CALC
• APM.IMODE
• APM.ITERATIONS
• APM.LINEAR
• APM.MAX_ITER
• APM.MAX_MEMORY
• APM.MAX_TIME
• APM.MEAS_CHK
• APM.MV_DCOST_SLOPE
• APM.MV_STEP_HOR
• APM.MV_TYPE
• APM.NODES
• APM.OBJFCNVAL
• APM.OTOL
• APM.PRED_HOR
• APM.PRED_TIME
• APM.REDUCE
• APM.REPLAY
• APM.REQCTRLMODE
• APM.RTOL
• APM.SCALING
• APM.SENSITIVITY
• APM.SEQUENTIAL
• APM.SOLVER
• APM.SOLVESTATUS
• APM.SOLVETIME
• APM.SPECS
• APM.SPC_CHART
• APM.STREAM_LEVEL
• APM.TIME_SHIFT
• APM.WEB
• APM.WEB_MENU
• APM.WEB_REFRESH
• APM.WEB_PLOT_FREQ

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.

 Description: Objective function tolerance for
              successful solution

 Description: Prediction horizon
              Total horizon, including control horizon

 Description: Requested control mode
              0=off
              1=simulate
              2=predict
              3=control

 Description: Variable and Equation Scaling
              0=Off
              1=On (Automatic)
              2=On (Manual)

 Description: Sensitivity Analysis
              0=Off
              1=On

 Description: Solver options
              0 = Benchmark All Solvers
              1-5 = Available Solvers Depends on License

 Description: Secifications from restart file
              1=ON
              0=OFF

 Description: Time shift for dynamic problems
              0  = OFF
              1  = ON (1 step)
              2+ = ON (multiple steps)

 Description: Generate HTML pages
              1=ON
              0=OFF

 Description: Generate HTML navigation menus
              1=ON
              0=OFF

 Description: Automatic refresh rate on HTML pages

 Description: Application information change (new-old)
              0=no change

 Description: Cold start model
              0=warm start
              1=cold start
              2=decompose problem

 Description: CSV read
              0=Off
              1=Batch
              2=Sequential

 Description: CSV write
              0=Off
              1=Write results.csv
              2=Write results_all.csv

 Description: Control mode
              1=simulate
              2=predict
              3=control

 Description: Control horizon length where MVs
              can be adjusted by the solver

 Description: Model time units
              1=seconds
              2=minutes
              3=hours
              4=days
              5=years

 Description: Controlled variable error model type
              1=linear error with dead-band trajectory
              2=squared error to single trajectory
              3=nonlinear error approximates linear
                without slack variables

 Description: Slope for weight on future CV error
              [+] favors future steady state target
              [-] favors near-term trajectory matching

 Description: Start interval for controlled variable
              error model weights

 Description: Database read option
              0=OFF
              1={Name = Value, Status} 
              2={Name = Value, Status, Units}

 Description: Database write
              0=OFF
              1={Name = Value, Status} 
              2={Name = Value, Status, Units}

 Description: Diagnostic level
              0=none
              1=messages
              2=file checkpoints
              4=diagnostic files
              5=check 1st derivatives
              6=check 2nd derivatives

 Description: Estimated variable error model type
              1=linear error
              2=squared error
              3=approximate linear error without
                slack variables

 Description: Slope for weight on more cuurent EV error
              [+] favors matching of most recent data
              [-] favors matching of oldest horizon data

 Description: History horizon for web-interface plots

 Description: History time units on plots only
              0=same as CTRL_UNITS
              1=seconds
              2=minutes
              3=hours
              4=days
              5=years

 Description: Specifications for initial condition
              differentials (MHE only): 0=OFF, 1=ON

 Description: Model solution mode
              1=ss, Simulation (steady state)
              2=mpu, Model parameter update (steady state)
              3=rto, Real time optimization (steady state)
              4=sim, Dynamic simulation (simultaneous)
              5=est, Dynamic estimation (simultaneous)
              6=ctl, Dynamic control (simultaneous)
              7=sqs, Dynamic simulation (sequential)
              8=est, Dynamic estimation (sequential)
              9=ctl, Dynamic control (sequential)

 Description: Iterations for solution

 Description: Maximum iterations

 Description: Slope for penalization on future MV moves
              to reduce controller procrastination

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

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

 Description: Manipulated variable type
              0=zero order hold
              1=first order hold (linear)

(:title Global Options (APM):) (:keywords Global, Optimization, Estimation, Option, Configure, Default, Description:) (:description Global options in APMonitor begin with APM. They can be set from MATLAB or Python clients.:)

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 description.

• APM.APPINFO
• APM.APPINFOCHG
• APM.APPSTATUS
• APM.BNDS_CHK
• APM.COLDSTART
• APM.CSV_READ
• APM.CSV_WRITE
• APM.CTRLMODE
• APM.CTRL_HOR
• APM.CTRL_TIME
• APM.CTRL_UNITS
• APM.CV_TYPE
• APM.CV_WGT_SLOPE
• APM.CV_WGT_START
• APM.CYCLECOUNT
• APM.DBS_READ
• APM.DBS_WRITE
• APM.DIAGLEVEL
• APM.EV_TYPE
• APM.EV_WGT_SLOPE
• APM.HIST_HOR
• APM.HIST_UNITS
• APM.ICD_CALC
• APM.IMODE
• APM.ITERATIONS
• APM.MAX_ITER
• APM.MAX_TIME
• APM.MEAS_CHK
• APM.MV_DCOST_SLOPE
• APM.MV_STEP_HOR
• APM.MV_TYPE
• APM.NODES
• APM.OBJFCNVAL
• APM.OTOL
• APM.PRED_HOR
• APM.PRED_TIME
• APM.REQCTRLMODE
• APM.RTOL
• APM.SCALING
• APM.SENSITIVITY
• APM.SOLVESTATUS
• APM.SOLVER
• APM.SOLVETIME
• APM.SPECS
• APM.TIME_SHIFT
• APM.WEB
• APM.WEB_MENU
• APM.WEB_REFRESH

APM.APPINFO

APM.APPINFOCHG

APM.APPSTATUS

APM.BNDS_CHK

APM.COLDSTART

APM.CSV_READ

APM.CSV_WRITE

APM.CTRLMODE

APM.CTRL_HOR

APM.CTRL_TIME

APM.CTRL_UNITS

APM.CV_TYPE

APM.CV_WGT_SLOPE

APM.CV_WGT_START

APM.CYCLECOUNT

APM.DBS_READ

APM.DBS_WRITE

APM.DIAGLEVEL

APM.EV_TYPE

APM.EV_WGT_SLOPE

APM.HIST_HOR

APM.HIST_UNITS

APM.ICD_CALC

APM.IMODE

APM.ITERATIONS

APM.MAX_ITER

APM.MAX_TIME

APM.MEAS_CHK

APM.MV_DCOST_SLOPE

APM.MV_STEP_HOR

 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

APM.MV_TYPE

APM.NODES

APM.OBJFCNVAL

APM.OTOL

APM.PRED_HOR

APM.PRED_TIME

APM.REQCTRLMODE

APM.RTOL

APM.SCALING

APM.SENSITIVITY

APM.SOLVESTATUS

APM.SOLVER

APM.SOLVETIME

APM.SPECS

APM.TIME_SHIFT

APM.WEB

APM.WEB_MENU

APM.WEB_REFRESH

 Description: CSV write: 0=Off, 1=Write results.csv, 2=Write results_all.csv

• NLC.SENSITIVITY

NLC.SENSITIVITY

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Sensitivity Analysis: 0=Off, 1=On

NLC.SCALING

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Variable and Equation Scaling: 0=Off, 1=On (Automatic), 2=On (Manual)

• NLC.SCALING

 Description: Cold start model: 0=warm start, 1=cold start, 2=decompose problem

 Description: Database read: 0=OFF, 1={Name = Value, Status, Units}, 2={Name,Value} 

 Description: Database write: 0=OFF, 1={Name = Value, Status, Units}, 2={Name,Value} 

 Description: Solver options: 0 = Benchmark All Solvers, 1-5 = Available Solvers Depending on License

 Description: Solver options: 0=Benchmark All Solvers, 1=NOVA, 2=IPOPT-v2.3, 3=IPOPT-v3.5, 4=SNOPT, 5=MINOS

• NLC.APPINFO
• NLC.APPINFOCHG
• NLC.APPSTATUS
• NLC.BNDS_CHK
• NLC.COLDSTART
• NLC.CSV_READ
• NLC.CSV_WRITE
• NLC.CTRLMODE
• NLC.CTRL_HOR
• NLC.CTRL_TIME
• NLC.CTRL_UNITS
• NLC.CV_TYPE
• NLC.CV_WGT_SLOPE
• NLC.CV_WGT_START
• NLC.CYCLECOUNT
• NLC.DBS_READ
• NLC.DBS_WRITE
• NLC.DIAGLEVEL
• NLC.EV_TYPE
• NLC.EV_WGT_SLOPE
• NLC.HIST_HOR
• NLC.HIST_UNITS
• NLC.ICD_CALC
• NLC.IMODE
• NLC.ITERATIONS
• NLC.MAX_ITER
• NLC.MAX_TIME
• NLC.MEAS_CHK
• NLC.MV_DCOST_SLOPE
• NLC.MV_STEP_HOR
• NLC.MV_TYPE
• NLC.NODES
• NLC.OBJFCNVAL
• NLC.OTOL
• NLC.PRED_HOR
• NLC.PRED_TIME
• NLC.REQCTRLMODE
• NLC.RTOL
• NLC.SOLVESTATUS
• NLC.SOLVER
• NLC.SOLVETIME
• NLC.SPECS
• NLC.TIME_SHIFT
• NLC.WEB
• NLC.WEB_MENU
• NLC.WEB_REFRESH

DBS Global Variables

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

NLC.APPINFO

 Type: Integer 
 Default Value: 0
 Data Flow: Input and Output
 Description: Application information: 0=good, error otherwise

NLC.APPINFOCHG

 Type: Integer 
 Default Value: 0
 Data Flow: Output
 Description: Application information change (new-old): 0=no change

NLC.APPSTATUS

 Type: Integer 
 Default Value: 1
 Data Flow: Output
 Description: Application status: 1=good, 0=bad

NLC.BNDS_CHK

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

NLC.COLDSTART

 Type: Integer 
 Default Value: 0
 Data Flow: Input and Output
 Description: Cold start model: 0=warm start, 1=cold start

NLC.CSV_READ

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: CSV read: 0=Off, 1=Batch, 2=Sequential

NLC.CSV_WRITE

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: CSV write: 0=Off, 1=On

NLC.CTRLMODE

 Type: Integer 
 Default Value: 1
 Data Flow: Output
 Description: Control mode: 1=simulate, 2=predict, 3=control

NLC.CTRL_HOR

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Control horizon: Horizon length where MVs can be adjusted by the solver

NLC.CTRL_TIME

 Type: Real 
 Default Value: 60
 Data Flow: Input
 Description: Time for each step in the control horizon

NLC.CTRL_UNITS

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Model time units (1=sec, 2=min, 3=hrs, 4=days, 5=yrs)

NLC.CV_TYPE

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Controlled variable error model type: 1=linear, 2=squared, 3=ref traj

NLC.CV_WGT_SLOPE

 Type: Real 
 Default Value: 0.0
 Data Flow: Input
 Description: Slope for weight on future CV error (e.g. [+] favors steady state)

NLC.CV_WGT_START

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Start interval for controlled variable error model weights

NLC.CYCLECOUNT

 Type: Integer 
 Default Value: 0
 Data Flow: Input and Output
 Description: Cycle count, increments every cycle

NLC.DBS_READ

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

NLC.DBS_WRITE

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

NLC.DIAGLEVEL

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Diagnostic level: 0=none, 1=messages, 2=file checkpoints, 4=diagnostic files, 5=check 1st deriv

NLC.EV_TYPE

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Estimated variable error model type: 1=linear, 2=squared, 3=approximate linear

NLC.EV_WGT_SLOPE

 Type: Real 
 Default Value: 0.0
 Data Flow: Input
 Description: Slope for weight on more cuurent EV error (e.g. favor near-term matching)

NLC.HIST_HOR

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: History horizon (SIM and CTL only): Integer >= 0

NLC.HIST_UNITS

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: History time units on plots only (0=same as CTRL_UNITS, 1=sec, 2=min, 3=hrs, 4=days, 5=yrs)

NLC.ICD_CALC

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Specifications for initial condition differentials (MHE only): 0=OFF, 1=ON

NLC.IMODE

 Type: Integer 
 Default Value: 3
 Data Flow: Input
 Description: Model solution mode: 1=ss, 2=mpu, 3=rto, 4=sim, 5=est, 6=ctl

NLC.ITERATIONS

 Type: Integer 
 Default Value: 1
 Data Flow: Output
 Description: Iterations for solution: >=1

NLC.MAX_ITER

 Type: Integer 
 Default Value: 25
 Data Flow: Input
 Description: Maximum iteration: >=1

NLC.MAX_TIME

 Type: Real 
 Default Value: 1.0e20
 Data Flow: Input
 Description: Maximum run time in seconds

NLC.MEAS_CHK

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

NLC.MV_DCOST_SLOPE

 Type: Real 
 Default Value: 0.1d0
 Data Flow: Input
 Description: Slope for penalization on future MV moves (i.e. reduces controller procrastination)

NLC.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

NLC.MV_TYPE

 Type: Integer 
 Default Value: 0
 Data Flow: Input
 Description: Manipulated variable type: 0=zero order hold, 1=linear

NLC.NODES

 Type: Integer 
 Default Value: 4
 Data Flow: Input
 Description: Nodes in each horizon step

NLC.OBJFCNVAL

 Type: Real 
 Default Value: 0.0
 Data Flow: Output
 Description: Objective function value

NLC.OTOL

 Type: Real 
 Default Value: 1.0e-6
 Data Flow: Input
 Description: Objective function tolerance for successful solution

NLC.PRED_HOR

 Type: Integer 
 Default Value: 1.0
 Data Flow: Input
 Description: Prediction horizon: Total horizon, including control horizon

NLC.PRED_TIME

 Type: Real 
 Default Value: 60.0
 Data Flow: Input
 Description: Time for each step in the horizon

NLC.REQCTRLMODE

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Requested control mode: 1=simulate, 2=predict, 3=control

NLC.RTOL

 Type: Real 
 Default Value: 1.0e-6
 Data Flow: Input
 Description: Equation solution tolerance

NLC.SOLVESTATUS

 Type: Integer 
 Default Value: 1
 Data Flow: Output
 Description: Solution solve status: 1=good

NLC.SOLVER

 Type: Integer 
 Default Value: 3
 Data Flow: Input
 Description: Solver options: 1=NOVA, 2=IPOPT-v2.3, 3=IPOPT-v3.5, 4=SNOPT, 5=MINOS

NLC.SOLVETIME

 Type: Real 
 Default Value: 1.0
 Data Flow: Output
 Description: Solution time (seconds)

NLC.SPECS

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Secifications from restart file: 1=ON, 0=OFF

NLC.TIME_SHIFT

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Time shift for dynamic problems: 1=ON, 0=OFF

NLC.WEB

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Generate HTML pages: 1=ON, 0=OFF

NLC.WEB_MENU

 Type: Integer 
 Default Value: 1
 Data Flow: Input
 Description: Generate HTML navigation menus: 1=ON, 0=OFF

NLC.WEB_REFRESH

 Type: Integer 
 Default Value: 10
 Data Flow: Input
 Description: Automatic refresh rate on HTML pages (default 10 minutes)