# Class

Functions Sub Routines Classes
Defining a Function Predefined Functions Tag Functions Mathematical Functions String Functions Defining a Subroutine Trigger Subroutines Defining a Class

Related Links: User Defined Class and Functions

# 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.
• 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.....
String UnitTag{tag}
Real	TankVolume*("Vol","m^3"), CuLeachExtent*("Frac", "%")
;... Various Variable Definition.....

Function Init(Str Name)
UnitTag = Name
[concatenate(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 .....
[concatenate(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:

 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()

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:

 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()

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:

 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


# 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) • See Include Files for more information. ## 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: $\mathbf{\mathit{P = P_{0} N^{3} D^{5} Density}}$ 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: The main pgm file may have the following structure: 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  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 --- 

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

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.