Model Procedures

Navigation: PGMs ➔ Model Procedures

Model Procedures	MP Example Files

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

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 (e.g. 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.

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:

• Model Procedure Example.spf
• Click here to view the MP example files

Different Syntax

The syntax is mostly the same in the PGMS and in the MPS, the one difference is for tag place holders, see table below for the syntax.

Requirement	Syntax (Recommended)	Example	Alternate Syntax	Alternate Syntax Example
To get a numerical value from SysCAD	variable = ["Tag"]	Flow = ["Qm (t/h)"]	variable = Get(Tag)	Flow = Get("Qm (t/h)")
To get a string value from SysCAD	StrVariable = ["Tag"]	FlowTagName = ["GM.Recovery.Stream"]	StrVariable = GetStr(Tag)	FlowTagName = GetStr("GM.Recovery.Stream")
To set a numerical value in SysCAD	["Tag"] = variable	["Qm_Demand.Reqd (t/h)"] = FlowRequired	Set(Tag, variable)	Set("Qm_Demand.Reqd (t/h)", FlowRequired)
To set a string value in SysCAD	[str "Tag"] = StrVariable	[str "EqpDesc"] = "Plant Feed"	SetStr(Tag, StrVariable)	SetStr("EqpDesc", "Plant Feed")

NOTES on what "Tag" refers in PGM and MP:

1. In PGM file:
   • Use Full Tag when referring to a tag. User can use the "Copy Tag for PGM" option to Copy the Tag from Access Window Right click popup list
   • Use Copy Tag (without the model name) when a tag is being concatenated
2. In MP file:
   • Use Copy Tag from Access Window Right click popup list, (this will copy with out the model tag name).
   • This is because the MP file is executed within the unit model, it will only see variable tags local to the unit.
   • For example, to fetch the mass flow of the feed to tie X_001, use ["QFeed.Qm"]. In a general controller you would use ["X_001.QFeed.Qm"].
   • When using a String variable for the tag and using [String], the string is expected to be the full tag. This differs from Get(TagString) or Set(TagString, variable). See Troubleshooting for an example.

All other PGM syntax will work in model procedures.

PLEASE NOTE:

1. The ["Tag"] syntax for an MP expects a literal string. In other words the actual tag in quotes. For example ["Qo.Qm (t/h)"]. When using String variables or string functions (e.g. concatenate), then the alternate syntax of Get() and Set() can be used.
2. If attempting to use the [TagString] syntax where TagString is a Variable then the full tag needs to be specified. See Troubleshooting for an example.

Structure of File

The file consists of global variable declarations followed by a series of optional trigger functions. 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	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 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 (i.e. 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 (i.e. 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 (i.e. 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

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 (e.g. Notepad, Excel)
• 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 (e.g. 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 (Long/Short)	Input / Calc	Description
MP (Model Procedures)
On	Check Box	The user may enable or disable the model procedures using this box.
StopForMPFileError	Tick Box	Only available in Build 139.31388 or later. Prevents project from running if there is an MP file missing or fails to load. This a global option which applies to all model procedures. Also available in Solver Settings. Will not be applied if MP is not On.
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.
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	Edit MP	This allows the user to edit the specified MP file, normally using the Notepad text editor.
Reload	Reload MP	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	Browse MP	This is used to locate an MP file.
ShowConcealed / HideConcealed	Show Concealed / Hide Concealed	This toggles the show/hide concealed variables in the MP file.
ResetConcealed	Reset Concealed	This resets the concealed tag status, use this button when concealed tag status has been modified in the MP file.
ZeroAllVars	Zero All Variables	Resets all variables to zero value.
ZeroVars	Zero Variables	Resets variables to zero value, excludes input parameters.
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.
TagList...
Input	Copy To Clipboard	Generates a list of all the writeable variables in the MP (from the Watch Variable Pages). Useful for reports.
Results	Copy To Clipboard	Generates a list of all the read only variables in the MP (from the Watch Variable Pages). Useful for reports.
All	Copy To Clipboard	Generates a list of all the variables in the MP (from the Watch Variable Pages). Useful for reports.

Watched Variables Page(s)

Tag	Input / Calc	Description
If PageLabel() is used in the PGM code, then each page label will be displayed in a new Tab. If no PageLabel() is defined, then default Tab(s) will be added. The default tab name maybe D1 for general data or M1 for matrix;
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.

Troubleshooting

As an example, when using [string] = value in model procedure (where "string" is a variable of type String), user may get a runtime error for unknown tag:

The following get value syntax will work:	Sub MP_Results() Real splitvalue@ splitvalue = ["GM.IOs.[P_002].Splt.H2O(l) (%)"] EndSub
However, if we define a string variable for split tag, and build up the tag dynamically as shown, we may get a runtime error message (in the message window): Unknown tag "GM.IOs.[P_002].Splt.H2O(l) (%)'	Real splitvalue@ String SplitTag, PipeID*{Tag}, SpeciesTag* Sub MP_Results() SplitTag = Concatenate("GM.IOs.[", PipeID, "].Splt.", SpeciesTag) splitvalue = [SplitTag] EndSub
This is because [String] expects the FULL tag (e.g.: X_001.GM.IOs.[P_002].Splt.H2O(l) (%) ) instead of partial tag. There are two possible solutions:
Solution 1: If we use Get(Tag) instead of [Tag] as shown in example, it will work.	Real splitvalue@ String SplitTag, PipeID*{Tag}, SpeciesTag* Sub MP_Results() SplitTag = Concatenate("GM.IOs.[", PipeID, "].Splt.", SpeciesTag) splitvalue = Get(SplitTag) EndSub
Solution 2: If we add [Str "Tag"] OR GetStr("Tag") to the concatenate function to form the FULL tag (as shown in the example), it will work. NOTE: When using the Concatenate string function, please make sure the second term starts with a . (dot).	Real splitvalue@ String SplitTag, PipeID*{Tag}, SpeciesTag* Sub MP_Results() SplitTag = Concatenate([Str "Tag"], ".GM.IOs.[", PipeID, "].Splt.", SpeciesTag) splitvalue = [SplitTag] EndSub