General Controller

From SysCAD Documentation
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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

Models-Controller-Image001.gif

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

  1. When SysCAD starts solving, only PGM code written inside the optional Trigger Subroutines InitialisePreStart(), PreStart() and InitialiseSolution() will be executed.
  2. When SysCAD stops, only PGM code written inside the Trigger Subroutines TerminateSolution() will be executed.
  3. 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.

Old135format.png

NOTES:

  1. Ticking the Old135Format affects how the PGM is executed, and prevents the use of the new Trigger Subroutines.
  2. Ticking the Old135Format does NOT affect other PGM functions and PGM features (implemented in SysCAD 9.3) such as DropList, [] for GetTag, etc.
  3. 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.

Bulkvalidation.png
  • 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,

  1. GControl tab - Contains general information relating to the unit.
  2. 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).
  3. 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.
  • We recommend changing the use of OnInitialise() or OnTerminate() to Trigger Subroutines as this feature will be removed in future updates.
  • NOTE:: Please see PGM Execution for more information..
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
  • 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 the default Tab will be D1;
  • If the PGM file uses of user defined Classes with the ClassAsPageLabel() defined, then each class instance declared will be displayed on a new tab page.
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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Retrieved from "https://help.syscad.net/index.php?title=General_Controller&oldid=79254"