Class

From SysCAD Documentation
(Redirected from PGM Classes)
Jump to navigation Jump to search

Navigation: PGMs

PGM Main Page Defining a Class Defining a Function Tag Functions Mathematical Functions Defining a Subroutine
Example PGM Files Predefined Classes Predefined Functions Tag Functions (9.3) String Functions Trigger Subroutines

Related Topics: Access Class Members

Predefined Classes: Species Database Class, Particle Size Definition Class, StrArray Class, Array Class, Matrix Class, Noise Class, TimeClass, Plant Model Class, Tag Select Class

What is "Class" and When should it be used

  • A Class will allow a user to define a group of variables and functions into one "instance".
  • For example, a user may want to extend the functionality of the Tank and turn it into a complex CSTR. To do this, the user will need to define functions to calculate additional user variables.
  • If the code is written without the use of class, the user will need to write the same code each time a CSTR tank is used. This can lead to repeating the same code a number of times depending on the number of CSTR tanks in the project.
  • If the code is written in the form of a Class, the user can define all the CSTR Variables and Functions required as a "template", then instruct SysCAD to use this template to perform the CSTR calculations (n times) without the need to repeat the code.
  • To aid the understanding of "Writing a Class" and to explain how to use the class function, a demonstration example project is distributed with the SysCAD install. Please see project Gold Project - CSTR pgm file. We will use this file to explain the use of Class in this document.

How to Define a Class (Template of Variable and Functions)

Syntax

Class className

   Variable declaration(s)

   Function(s)

EndClass
  • The class declaration must begin with the Class keyword and end with the EndClass keyword. See Class Declaration.
  • className : is an unique name of the class. In our example, this is called CSTR.
  • Variables can be declared within the class, their scope is limited to the class, and they are available to the instance of the class.
  • When declaring variables in a class, the normal variable declaration rules will apply:
    The user can define units;
    Append * to make the variable visible and writeable in the access window; and/or
    Append @ to make the variable visible in the Access window, but read only.
    For more information, refer to Variable declaration.
  • Function, StrFunction can be declared, within the class and they are available to the instance of the class. The sequence of functions and variables within a class can be mixed and arranged as required.
  • Classes cannot be nested. (i.e. classes cannot be defined within classes)

Example PGM File

  • A very condensed extract of the CSTR Class PGM file is presented below to explain the structure and use of the Class definition, for the full PGM file, please see the Distributed Example project.
Class CSTR

 ... Various Variable Definition.....
 Str UnitTag{tag}
 ... Various Variable Definition.....

 Function Init(Str Name)
   UnitTag = Name
   SetDynTag(strcat(UnitTag, ".ResTime.Volume (m^3)"), TankVolume)
   Return 0
 EndFunct
 
 Function CalculateCSTR()
  ......Various Calculation Code .....
   Return 0
 EndFunct   
 
 Function Exec()
   ......Various Calculation Code .....
   CalculateCSTR()
   ......Various Calculation Code .....
   SetDynTag(strcat(UnitTag, ".RB.R3.Extent (%)"), CuLeachExtent)
   Return 0
 EndFunct

EndClass
  1. The name of the Class (or template) is called CSTR.
  2. All the variables that are associated with the CSTR are defined. (Detail not shown here)
  3. String tag "UnitTag" is defined here - the class uses the REAL SysCAD process unit tag when the actual calculation is performed. Using the Full SysCAD process unit tag inside the class is NOT recommended, as it will make the class not reusable.
  4. Function "Init" - initialises the class and substitutes the actual process name into 'UnitTag' when using the Class, explained in the next heading.
  5. Nested functions are allowed within a class, for example Function "CalculateCSTR" is called inside the Function "Exec"
  6. In summary, the Class(template) "CSTR" contains a number of calculations and a number of Set Value Commands.

How to use the Class (Perform actual Calculations using the Template)

Once the Class has been defined (template complete), the user can include this template in pgm files to perform calculations.

Defining Class Instances

This is best shown using an example. In our sample file, the following lines represent the actual representation of the class:

SysCAD 9.3 Syntax SysCAD 9.2 Syntax
 CSTR TankA, TankB, TankC

 Sub (InitialiseSolution)
     TankA.Init("TANK_A")
     TankB.Init("TANK_B")
     TankC.Init("TANK_C")
 EndSub

     TankA.Exec()
     TankB.Exec()
     TankC.Exec()
 CSTR TankA, TankB, TankC

 if (OnInitialise)
     TankA.Init("TANK_A")
     TankB.Init("TANK_B")
     TankC.Init("TANK_C")
 else
     TankA.Exec()
     TankB.Exec()
     TankC.Exec()
 endif
  1. Three CSTR instances are defined here, TankA, TankB & TankC.
  2. When the PGM file is evaluated during the SysCAD initialisation step, each instance of the Class is assigned a UnitTag Name. In the Gold Example Project, TANK_A, TANK_B and TANK_C are actual process unit tags.
  3. When the project is solved, at each iteration, the Exec() function is called for each of the CSTR instances.
  4. When a Class instance has been defined, SysCAD will create variables and functions for that instance. For example: For CSTR TankA, the following variable and functions can be accessed:
    • TankA.UnitTag - This is an example of the class variable.
    • TankA.Exec() - This is an example of the class function.

Defining Class Instances in an array

Class instance can also be defined in an array format, for example an equivalent of the above code can be written as:

SysCAD 9.3 Syntax SysCAD 9.2 Syntax
 CSTR Tank[4]
 ExcludeWatch Tank[0]

 Sub (InitialiseSolution)
     Tank[1].Init("TANK_A")
     Tank[2].Init("TANK_B")
     Tank[3].Init("TANK_C")
 EndSub

     Tank[1].Exec()
     Tank[2].Exec()
     Tank[3].Exec()
 CSTR Tank[4]
 ExcludeWatch Tank[0]

 if (OnInitialise)
     Tank[1].Init("TANK_A")
     Tank[2].Init("TANK_B")
     Tank[3].Init("TANK_C")
 else
     Tank[1].Exec()
     Tank[2].Exec()
     Tank[3].Exec()
 endif
  1. Four CSTR instances are defined here, Tank 0, Tank 1, Tank 2 & Tank 3.
  2. Note: The array always starts with 0, therefore, we have intentionally defined 4 instances here and we will use Tanks 1 to 3.
  3. The ExcludeWatch Keyword instructs SysCAD not to display Tank 0. In our PGM code we will skip Tank 0 and start with Tank 1.
    • Tank[1].UnitTag - This is an example of the class variable.
    • Tank[1].Exec() - This is an example of the class function.

With an array of instances of a class we can efficiently loop through these for the Exec function for each iteration. This makes it easier to change the number of tanks. The code above becomes:

SysCAD 9.3 Syntax SysCAD 9.2 Syntax
 long i
 const long TankCount = 4
 CSTR Tank[4]
 ExcludeWatch Tank[0]

 Sub (InitialiseSolution)
     Tank[1].Init("TANK_A")
     Tank[2].Init("TANK_B")
     Tank[3].Init("TANK_C")
 EndSub

     i = 1
     While (i<TankCount)
       Tank[i].Exec()
       i = i + 1
     EndWhile
 long i
 const long TankCount = 4
 CSTR Tank[4]
 ExcludeWatch Tank[0]

 if (OnInitialise)
     Tank[1].Init("TANK_A")
     Tank[2].Init("TANK_B")
     Tank[3].Init("TANK_C")
 else
     i = 1
     While (i<TankCount)
       Tank[i].Exec()
       i = i + 1
     EndWhile
 endif


Sharing Classes between Projects

The recommended method of setting up a class that will be used in a number of pgms, or projects is as follows:

  1. The CLASS definition is defined in a separate file; for example: General_Classes_and_functions.pgm
    • NOTE that this file must NOT contain the $ sign or EndFile token at the end of the file.
  2. For shared use in a single project - The class definition file can be stored in the project\controls folder, then inserted into other PGM files using include file syntax >>filename.
    • If the class definition file is stored in the same folder as the PGM file, then use >>General_Classes_and_functions.pgm to insert the file as needed.
  3. For shared use across multiple projects - The include file can be saved in a common shared folder, then inserted into other PGM files using include file syntax >>filename, the file name needs to be the relative or full path name.
    • For example: >>d:\Users\SysCAD Common Files\General_Classes_and_functions.pgm (Also See example below)

Example 1. Class to calculate the Agitator Power required in a Vessel

The user wants to calculate the required agitator power in a number of vessels in a project. This functionality will be used in a number of different projects, and hence the file with the class will be stored on the network where it can be accessed by a number of users and projects.

A formula that may be used to calculate the agitator power for turbulent flow is:

[math]\mathbf{\mathit{P = P_{0} N^{3} D^{5} Density}}[/math]

where:
P - Agitation Power;
P0 - the dimensionless power number, which is a function of impeller geometry;
N - agitator rotational speed;
D - Diameter of the impeller;
Density - Density of the material in the vessel.

The class is saved in a file called AgitatorPower.pgm and is saved on the network at n:\Users\SysCAD Common Files\

The Class file is as follows:

Class    AgitatorPower
TextLabel()
real   Po*
real   N{i, comment("Rotation per second")}
real   D{i, ("L", "m"), comment("ImpellerDiameter")}
string DensityTag@{ Tag}
real   Density@("Rho", "kg/m^3")
real   Power@("Pwr", "kW")

Function Init(string UnitName)
  DensityTag = Concatenate(UnitName, ".QProd.SLRho (kg/m^3)")
  return 0
EndFunct

Function Exec()
  Density = [DensityTag]
  Power = Po * N^3 * D^5 * Density
  return 0
EndFunct

EndClass

The main pgm file may have the following structure:

SysCAD 9.3 Syntax SysCAD 9.2 Syntax
PageLabel(Agitators)

>>n:\Users\SysCAD Common Files\AgitatorPower.pgm

AgitatorPower Tank1, Tank2, StorageTank1

Sub (InitialiseSolution())
  Tank1.Init("Tank_01")
  Tank2.Init("Tank_02")
  StorageTank1.Init("StorageTank_01")
EndSub

  Tank1.Exec()
  Tank2.Exec()
  StorageTank1.Exec()
  
$ ; --- end of file ---
PageLabel(Agitators)

>>n:\Users\SysCAD Common Files\AgitatorPower.pgm

AgitatorPower Tank1, Tank2, StorageTank1

if (OnInitialise)
  Tank1.Init("Tank_01")
  Tank2.Init("Tank_02")
  StorageTank1.Init("StorageTank_01")
  
else
  Tank1.Exec()
  Tank2.Exec()
  StorageTank1.Exec()
  
endif
$ ; --- end of file ---


And the access window of the controller will show the following fields:

Class 1.png

Notes:

  1. The user may follow the same rules for individual functions that may be useful in a number of pgms or in separate projects.

Example User Defined Classes

  1. Gold Project - demonstrates the use of Classes in the CSTR pgm file. This is used to calculate the gold and copper leaching and adsorption values in a number of individual tanks.
  2. See Example Class Files for some example uses of user specified class definitions.

Predefined Classes in SysCAD

Predefined Class Brief Description
Useful classes include:
Species Database Class This class gives access to information about species and phases within a project. For example, users can obtain species Density, Saturated Temperature or Pressure, number of solid species in a project, etc.
Particle Size Definition Class This class gives access to information about the Particle Size Definition (PSD) within a project. For example, users can find the number of Size Intervals in a PSD, the Top and bottom Size, etc.
Array Class This Class lets user define an array to read or store numeric values.
StrArray Class This Class lets user define an array to read or store (in memory) string values.
Matrix Class This Class lets user define an matrix to read or store values.
TimeClass This Class contains some function to manipulate the time readings.
Tag Select Class This Class provides a function to retrieve a list of model tags meeting a SQL type select query, similar to the Excel Tag Select Reports.
Plant Model Class This Class provides a function to retrieve a list of global tags available in the plant model, can be used in PGM or MP files.
Some Old but still usable classes include:
NOTE these two classes have been converted into SysCAD models, users can use the Insert Unit operations to insert them onto the flowsheet.
Noise Class This has been implemented into SysCAD as the Noise Process unit.