General Controller
Navigation: Models ➔ Control Models ➔ General Controller
General Controller | PID Controller | Ratio / SetTag Controller |
---|
Related Links: PGM, Example PGM Files
General Description
This is used to simulate plant control, plant operations or calculate displays. This model is often used to customise or extend the functionality of a standard unit operation. These functions may be as simple or complex as may be required.
The General Controller reads a text file, set up by the user, which allows the user to include fairly powerful programming functions. The files are known as "pgm" files and are detailed in a separate section of the documentation PGMs. The control logic (or program code) that you write for a General Controller is executed once every iteration.
The PGM language includes the following capabilities:
- Accessing tags by name within any unit or stream on the flowsheet.
- Modification of any permissible tags within any unit or stream on the flowsheet.
- Real, Integer and Boolean arithmetic.
- Strings and string manipulation routines.
- Declaration of user tags (PGM variables) which are then accessible at run time for view, change, reporting, trending, etc.
- General-purpose functions and classes may be defined and used.
This document only describes the access window for the general controller, and some of the more common problems that may occur. The PGM help documentation contains examples of pgm files and various applications that can be simulated using this model.
For dynamic projects this is used extensively to simulate the control system as well as operator actions. It can be used to simulate events, for example the random failure of equipment.
Tags that are controlled (using SetTag) or referenced (using GetTag) by the General Controller will have a coloured triangle shown in the access window of that unit. When the user right clicks on one of these referenced tags it will indicate which controller is referencing the tag. See Controlled and Referenced Variables.
Location of Control Text files
- When the user creates a control file, SysCAD automatically creates a sub-folder in the project called Controls and stored all control files (with the extension .pgm) in this folder.
- The user may store the control files in any other location, although this is not recommended. The use of Relative File Path is allowed.
- The user may view the location of all the control files in a project by accessing Project Window - Files List.
Video Links
The Tutorial section has a number of videos showing users how to write a simple PGM file for a General Controller:
Introductory Tutorial - General Controller and PGMs
Similar Models
- Set Tag Controller - the user may carry out the simple ratio control and set multiple tags using the the Set Tag Controller model.
Diagram
The diagram shows the default drawing of the General Controller.
Inputs and Outputs
There are no connections to this unit.
Model Theory
The power of this model is contained in the program (PGM) written by the user. The pgm syntax for programing the control file is described in PGM Documentation.
Reload File
The PGM file can not be reloaded unless the model is stopped. If the model is stopped and the PGM 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
PGM Execution
- When SysCAD starts solving, only PGM code written inside the optional Trigger Subroutines InitialisePreStart(), PreStart() and InitialiseSolution() will be executed.
- When SysCAD stops, only PGM code written inside the Trigger Subroutines TerminateSolution() will be executed.
- The remaining PGM code will be executed once every iteration. So if a project was solved for 5 iterations, then the pgm file is executed 5 times.
If the user wishes to keep using the OnInitialise() and OnTerminate() functions in SysCAD 9.3 (up to Build 139), then the Old135Format box on the first Tab of the general controller must be checked, checking this box will use the SysCAD 9.2 PGM execution logic.
NOTES:
- Ticking the Old135Format affects how the PGM is executed, and prevents the use of the new Trigger Subroutines.
- Ticking the Old135Format does NOT affect other PGM functions and PGM features (implemented in SysCAD 9.3) such as DropList, [] for GetTag, etc.
- The Old135Format and OnInitialise() and OnTerminate() functions will be removed in future updates. We strongly recommend users convert any use of these to the Trigger Subroutines.
Set Tag Validation in Build139
New option "BulkSetTagsValidation" has been implemented in Build 139 where setting of tags from a General Controller (defined in a PGM file) will be validated as a group.
- This option is enabled by default.
- Data validation is required in models where the sum of all values must add up to 100, such as DSp Tab in Feeder, Size Distribution tabs in various models such a feeder, crusher, or screen, and breakage function tabs in a Crusher model and so on.
- If this option is not enabled, then data validation will be called after each tag is set (i.e. as per behaviour in Build138 or earlier). This is equivalent to a user manually entering a single value and pressing the OK button.
Data Sections
The default sections and variable names are described in detail in the following tables. The default General Controller access window consists of one section. The user may set up variables in the pgm 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,
- GControl tab - Contains general information relating to the unit.
- Any watched variables will be added to "default data tabs" (e.g. D1 for data, M1 or matrix and so on) or user defined tabs (if pagelabel is used within the PGM file).
- Info tab - Contains general settings for the unit and allows the user to include documentation about the unit and create Hyperlinks to external documents.
General Controller Page
Unit Type: GControl - The first tab page in the access window will have this name.
Tag (Long/Short) | Input / Calc | Description |
Tag | Display | This name tag may be modified with the change tag option. |
Condition | Display | OK if no errors/warnings, otherwise lists errors/warnings. |
ConditionCount | Display | The current number of errors/warnings. If condition is OK, returns 0. |
GeneralDescription / GenDesc | Display | This is an automatically generated description for the unit. If the user has entered text in the 'EqpDesc' field on the Info tab (see below), this will be displayed here. If this field is blank, then SysCAD will display the UnitType or SubClass. |
Requirements | ||
On | Check Box | The user may enable or disable the general controller using this box. |
Old135Format | Check Box | Older pgm using OnInitialise() and OnTerminate() predefined constants can still be loaded by checking this box. If this box is unchecked, and the pgm file contains OnInitialise() or OnTerminate(), then the PGM will failed to load.
|
BulkSetTagsValidation / BulkValidation | Tickbox | Available from Build 139. This option is on by default. Performs Set Tag validation as groups (model based). See Set Tag Validation |
FileName | Input | The user types in the name of the pgm file required for control. The file can be entered in any text editor, and must have the file extension 'pgm'. 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 pgm file is to use the Browse PGM button. |
Folder | Feed Back | The full path/folder of the pgm file is displayed here. |
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. |
Errors: | ||
MSG_1 to MSG_4 | Output | These message lines are used to report PGM compile errors or errors while the PGM code is executing. |
Edit | Edit PGM | This allows the user to edit the specified PGM file, normally using the Notepad text editor. |
Reload | Reload PGM | This reloads and recompiles the PGM code. Use this after changes to the PGM code have been made and saved. This is not necessary if the AutoReLoad check box is ticked. |
Browse | Browse PGM | This is used to locate a PGM file. |
RuntimeDebug | Enable Debug / Disable Debug | Available from Build 139.32530. This feature toggles the PGM Runtime Debug mode on or off for the General controller. To locate where runtime errors (like divide by zero) occur in the code, click the ‘Enable Debug’ button. This action will reload the PGM, examine the code for potential division by zero errors, and store line numbers that could potentially cause such an error. This information is then used to report any runtime errors in the message window. Please note that at the next project load, any models in RuntimeDebug mode will revert to normal operation. |
Concealed | Show Concealed / Hide Concealed | This toggles the show/hide concealed variables in the PGM file. |
ResetConcealed | Reset Concealed | This resets the concealed tag status, use this button when concealed tag status has been modified in the PGM file. |
ZeroAllVars | Zero All Variables | Resets ALL variables to zero value and strings to empty. |
ZeroVars | Zero Variables | Resets all result and internal variables to zero value and strings to empty. User input fields are left unchanged. |
InitVars | Init Variables | Available from Build 139.33127. Reset all variables to the user defined initial values. That is variables that have been declared with an Init value in the PGM code. A count of the number of controller variable tags with Init values is shown in comment on RHS of the button. |
EditMainPGM | Button | This is used to edit the main PGM file. The PGM 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 'pgm'. 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... | ||
Inputs | Copy To Clipboard | Generates a list of all the writeable variables in the PGM (from the Watch Variable Pages). A context menu of options is given to allow selection of different groups of tags with or without conversions. Useful for reports. |
Results | Copy To Clipboard | Generates a list of all the read only variables in the PGM (from the Watch Variable Pages). A context menu of options is given to allow selection of different groups of tags with or without conversions. Useful for reports. |
All | Copy To Clipboard | Generates a list of all the variables in the PGM (from the Watch Variable Pages). A context menu of options is given to allow selection of different groups of tags with or without conversions. Useful for reports. |
Global Settings | ||
ExecuteTimeout | Input | This is the maximum time SysCAD will spend evaluating/executing the PGM code for one step. It is designed to prevent logic that causes an endless loop from freezing SysCAD. If a timeout error occurs, you should review the PGM logic. This a global option which applies to all general controllers. Also available in Plant Model - FlwSolve Tab. |
StopForPGMFileError | Tick Box | Available from Build 139.31388. Prevents project from running if there is a PGM file missing or fails to load. This a global option which applies to all general controllers. Also available in Solver Settings. Will not be applied if General Controller is not On. |
Track.DivideZeroByZero / Track.DivZeroByZero | Tick Box | Available from Build 139.32139. This is used for tracking the special case of zero divide by zero (0/0). If this box is not ticked, then runtime warnings are not reported while running PGM code, the result is 0 (as before). This tick box does not apply to the normal division by zero cases, the "some value/0" cases will always return a runtime warning. |
Watched Variables Page(s)
Tag | Input / Calc | Description |
| ||
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. |
TagRefs Page
Tag | Input / Calc | Description |
TagRefs.... | ||
Tag References | ||
ClearDuringInit | Tickbox | If this is selected, the Reference Unit Tags will be cleared during initialisation. |
TagCount | Feedback | The number of tags referenced in the PGM code. |
UnitCount | Feedback | The number of unit models referenced in the PGM code. |
Clear | Clear | If this is selected, the Reference Unit Tags will be cleared during initialisation. |
TryFixTags | Change Old Tags | If the PGM code was written in an earlier build, where some of the SysCAD variable names may be different, using this button may fix the PGM code. If the PGM code was changed, SysCAD will generate a message in the message window as well as the bottom of the PGM file. Please see SysCAD 9.3 Tag Changes for more information. Note: This method uses a tag list based on the PGM code when loaded. |
TryFixTags2 | Change Old Tags | If the PGM code was written in an earlier build, where some of the SysCAD variable names may be different, using this button may fix the PGM code. If the PGM code was changed, SysCAD will generate a message in the message window as well as the bottom of the PGM file. Please see SysCAD 9.3 Tag Changes for more information. Note: This method uses a tag list based on the PGM code when solved. Therefore, this button will be greyed out before the project has been solved at least once after load. |
TagList | Copy To Clipboard | Generates a list of SysCAD Variable tags used in the PGM code. This includes both get tag and set tags.
Plant_Feed.QmReqd
P815_.Qo.Qm
P814_.Qo.Qm
P800.Qo.Qm
P1050.Qo.Qm
H2SO4_Source.Total.Qm
Air_Source.Total.Qm
P101.Qo.QEl.Ni
P408.Qo.QEl.Ni
P101.Qo.QEl.Cu
P304.Qo.QEl.Cu
P612.Qo.QEl.Cu |
Reference Unit Tags | ||
UnitTagxxx | Feedback | The unit tag name(s) referenced by the PGM code. |
UnitsTagList | Copy To Clipboard | Generates a list of SysCAD Unit tags used in the PGM code. This includes both get tag and set tags.
For example: Plant_Feed
P815_
P814_
P800
P1050
H2SO4_Source
Air_Source
P101
P408
P304
P612 |
UnitTags | Find | Opens Find dialog with the list of Unit tags from UnitsTagList selected. Not shown before first solve or if no tags referenced in the model. |
Adding this Model to a Project
Add to Configuration File
Sort either by DLL or Group:
DLL: | Control1.dll |
→ | Units/Links | → | Control: General | |
or | Group: | General |
→ | Units/Links | → | Control: General |
See Model Selection for more information on adding models to the configuration file.
Insert into Project Flowsheet
Insert Unit | → | Control | → | General |
See Insert Unit for general information on inserting units.
Hints and Comments
- If the pgm file contains a tag that is invalid, SysCAD will not begin execution, but will flag that user that there is an error in the pgm. Check the Messages window for a list of the invalid tags.
- If the user edits the pgm file, loads it using the 'Reload' button, but does not see the expected changes, it may be that the pgm file has not been saved before reloading.
- If there is more than one copy of the pgm file in various folders, it is always a good idea to open the file using the 'Edit' button on the access window. This will ensure that you are editing the file that the unit is accessing.
- It is always a good idea to pause or stop the SysCAD execution before reloading a pgm file into the general controller. This is because if there is an error in the file, the unit will cease all control functions, which may cause problems in the project.
Please see Example PGM Files for some sample PGM files.