Model Procedures

From SysCAD Documentation
Jump to: navigation, search

Navigation: PGM - Model Procedures

Related Links: PGM, MP Example Files, Evaluation Blocks, Tie, Tank, Pipe

Example projects using MP file: Nickel Copper Project, Model Procedure Example

Introduction

A model procedure is a text file with extension "mp" containing a series of commands for SysCAD to execute.

This functionality is similar to the General Controller except the commands are executed as the model is being solved. An example of the use of this model is:

  1. Fetch a value which is dependent on the feed to the model (eg. the total mass flow to the model)
  2. Use this value to calculate a required value of a setting in this model.
  3. Set this value prior to the model being evaluated this iteration.

This overcomes the iteration delay issue associated with General Controllers. Also, the same mp file can be used with any model - so you can write just one mp file to do some calculations in a pipe, and reuse this for any pipe in your model.


This functionality has only been implemented for the Tie, Tank and Pipe models at present (including the Pipe - Dynamic Mode and Tank - Dynamic Mode).

To enable this, on the Info tab page tick the "Procedures" tickbox. A new tab page called MP will appear.

Info Page - Procedures.jpg

The syntax used is almost identical to the PGM syntax that is used for the General Controller.

Note: The mp code can only access tags within the unit - it cannot fetch or set tags in other units in the project.


There is an example illustrating the basic functionality in the Examples folder distributed with SysCAD:

Different Syntax

PLEASE NOTE: GetTag and SetTag CANNOT be used.

  1. When Getting or Setting tags within a Model Procedure from within the model that has the model procedure within it:
    • To get a value use the function Get()
    • To set a value use the function Set()
    • To get a string use the function GetStr() (Only available in SysCAD 9.2 Build 135 or later)
    • To set a string use the function SetStr() (Only available in SysCAD 9.2 Build 135 or later)
  2. The tag specified should be the tag without the model name. For example, to fetch the mass flow of the feed to tie X_001, use Get("QFeed.QMt"). In a general controller you would use GetTag("X_001.QFeed.QMt").

All other PGM syntax will work in model procedures.

Syntax in SysCAD 9.3

The syntax in SysCAD 9.3 is mostly the same in the pgms and in the mps, the one difference is for tag place holders, as shown below:

Requirement Syntax Example
To get a numerical or string value from SysCAD variable = [Tag] Flow = ["Qm (t/h)"]
To get a numerical or string value from SysCAD using a tag place holder variable = Get(TagName) Flow = Get(FlowTag)
To set a numerical value in SysCAD [Tag] = variable ["Qm_Demand.Reqd (t/h)"] = FlowRequired
To set a numerical value in SysCAD using a tag place holder Set(TagName, variable) Set(FlowDemand, FlowRequired)
To set a string value in SysCAD [strTag] = variable [str"EqpDesc"] = "Plant Feed"

The tag specified should be the tag without the model name, so use the 'Copy Tag' rather than 'Copy Full Tag' when copying the required tag.

Structure of File

The file consists of global variable declarations followed by a series of optional trigger functions. In SysCAD 9.3, the functions can be defined as subroutines of the same name.

Each function/subroutine contains user defined commands which are executed by SysCAD at different stages of the evaluation of the model.

All functions/subroutines are optional, the complete list of available trigger functions/subroutines are given in the table below. The user may also define their own functions or subroutines but these must be called from one of the trigger functions/subroutines.

Any commands outside the trigger functions/subroutines (except for variable declarations) will be ignored.

Function/Subroutine Name Description
MP_PreStart Only available in SysCAD 9.3. This will be performed early, before the first iteration/time step. This is similar to the PreStart Trigger Subroutine used in PGMs.
MP_InitialiseSolution This will be performed during the initialisation of the run, before the first iteration/time step. This is similar to the OnInitialise flag and InitialiseSolution Trigger Subroutine used in PGMs.
MP_InitialiseIteration This will be performed at the start of every iteration, but only once.
NB Please be aware that the flows into the unit may change during an iteration, so this function may not use the final flows around the unit.
MP_Eval_Before This will be performed when the model is starting to be solved but before any calculations are performed. If the unit is part of a recycle in a dynamic project, this function may be called multiple times in a single time step.
MP_Eval_BeforeEB This will be performed when the model is being solved, after the feeds have been combined but prior to any Evaluation Block (EB) submodels being performed or outlets being set. Use this function if QFeed parameters from the current iteration are to be used to set internal parameters for use in this iteration. If the unit is part of a recycle in a dynamic project, this function may be called multiple times in a single time step.
MP_Eval_AfterEB This will be performed when the model is being solved, after the feeds have been combined and after any Evaluation Block (EB) submodels are performed but prior to outlets being set. Use this function if EB parameters from the current iteration are to be used to set internal parameters for use in this iteration. If the unit is part of a recycle in a dynamic project, this function may be called multiple times in a single time step.
MP_Eval_BeforeCEB This function is only relevant for a dynamic model with surge (such as a Tank). This will be performed when the model is being solved, after the feed has been combined with the previous content, but prior to any Content Evaluation Block (CEB) submodels being performed or outlets being set. Use this function if content parameters from the current iteration are to be used to set internal parameters for use in this iteration. If the unit is part of a recycle in a dynamic project, this function may be called multiple times in a single time step.
MP_Eval_AfterCEB This function is only relevant for a dynamic model with surge (such as a Tank). This will be performed when the model is being solved, after the feed has been combined with the previous content and after any Content Evaluation Block (CEB) submodels are performed but prior to outlets being set. Use this function if CEB parameters from the current iteration are to be used to set internal parameters for use in this iteration. If the unit is part of a recycle in a dynamic project, this function may be called multiple times in a single time step.
MP_Eval_After This will be performed after the model (but not the whole project) is solved (ie. after outlets have been set and all other model calculations have been performed). If the unit is part of a recycle in a dynamic project, this function may be called multiple times in a single time step.
MP_Results This will be performed after the model is solved (ie. after outlets have been set and all other model calculations have been performed), but only once. Use this function to calculate results.
MP_TerminateIteration This will be performed once at the end of each iteration (ie after all model and all control actions are completed.)
MP_TerminateSolution This will be performed during the last iteration. This is similar to the OnTerminate flag and the TerminateSolution Trigger Subroutine used in PGMs.

Reload File in 9.3

In SysCAD 9.3 or later the MP file can not be reloaded unless the SysCAD model is stopped. If the model is stopped and the MP file is changed, the file will automatically be reloaded (once SysCAD is reactivated).

If the file is modified while the model is running then the file will be reloaded when any of the following occur after the model is stopped:

  • the SysCAD application is activated (click anywhere on it) after another application was in use (eg. Notepad, Excel, etc)
  • the user starts another run
  • the reload button is pressed

Data Sections

The default sections and variable names are described in detail in the following tables. The default Model Procedure access window consists of one tab page (MP) as part of the unit model it is associated with (eg. Tank, Tie, Pipe). The user may set up variables in the mp code that will be shown on the access window. The number of sections in the access window will depend on the number of variables chosen.

This page will only appear if the "Procedures" option has been enabled on the Info tab page.

MP Page

Tag / Symbol

Input / Calc

Description

Model Procedures

On

Check Box

The user may enable or disable the model procedures using this box.

AutoReload

Check Box

Only available in SysCAD 9.2 (Build 135) or earlier. The MP will be automatically re-loaded if the file has been changed and saved. For SysCAD 9.3 see Reload File in 9.3 section above.

MP_Name / ModelProcName

Input

The user types in the name of the MP file required for control. The file can be entered in any text editor, and must have the file extension 'mp'. The user need not always type in the full path of the file. SysCAD will first attempt to locate the file in the project folder, then in the cfgfiles folder. If the file is in neither of these folders, then the user should include the path of the file. If the unit cannot locate the file, it will alarm and send an error message to the 'State' box - NO PROGRAM. The easiest way to load in the MP file is to use the Browse MP button.

The FileState field is only available in SysCAD 9.3 or later.
FileState OK File is found and has no errors.
Not Specified The user has not specified a file.
Not Found The specified file can not be found.
Load Error There is an error in the file. The State and Message (Msg) fields will provide further information.

State

Output

The state of the PGM file once a load has been attempted. If everything is correct and operating normally, the user will see 'OK' in this box. Otherwise the unit will flag an error message which helps the user to locate the problem with the controller. These messages are also displayed in the message window.

Error:

Msg_1 to Msg_4

Output

These message lines are used to report MP compile errors or errors while the MP code is executing.

 

Edit MP

Button

This allows the user to edit the specified MP file, normally using the Notepad text editor.

Reload MP

Button

This reloads and recompiles the MP code. Use this after changes to the MP code have been made and saved. This is not necessary if the AutoReLoad check box is ticked.

Browse MP

Button

This is used to locate an MP file.

Check Tags

Button

Only available in SysCAD 9.2 (Build 135) or earlier. This can only be used while SysCAD is not solving or running. It is used to check all the tags used by the MP and their engineering units. This is done automatically when the solver starts, so you do not need to use this button.

ShowConcealed / HideConcealed

Button

This toggles the show/hide concealed variables in the MP file.

ResetConcealed

Button

This resets the concealed tag status, use this button when concealed tag status has been modified in the MP file.

ZeroVariables

Button

Resets all variables to zero value.

 

Edit Main MP

Button

This is used to edit the main MP file. The MP file name will be displayed on the button.

Edit Include x

Button

This is used to edit the include file. Each include file will have a separate button. The include file name will be displayed on the button.

NewInclude

Input

The user types in the name of the include file required to assist with control. The file can be entered in any text editor, and must have the file extension 'mp'. The user need not always type in the full path of the file. SysCAD will first attempt to locate the file in the project folder, then in the cfgfiles folder. If the file is in neither of these folders, then the user should include the path of the file. If the unit cannot locate the file, it will alarm and send an error message to the 'State' box - NO PROGRAM.

 

Watched Variables

Variable

Any variables that the user specifies as 'watched' will be shown on one or more tab pages. This may include calculated variables, which may not be changed by the user, or variables that the user may change during execution of the program.

Notes

  1. If the model is part of a recycle in a dynamic project then within one time step, the Eval procedures may be called multiple times as the solver iterates to converge a recycle. If the procedures are performing control actions, it may be best to limit these to only once per time step.
  2. The mp code can only access tags within the unit - it cannot fetch or set tags in other units in the project.
  3. If 'QProd' values are used in any of these functions, they will not necessarily be equal to the final QProd values. The QProd values returned may be any of the following:
    • The result from the previous iteration; or
    • An intermediate QProd, i.e. if it is used in the function MP_Eval_BeforeEB(), then it may be stream feeding into the Evaluation Block; or
    • An indeterminate value.
    Therefore, please take care when using 'QProd', and if necessary test the values by displaying test values from different functions.