From GridLAB-D Wiki
Jump to: navigation, search

The runtime class is a feature of GridLAB-D that allows any user to define and develop their own class using inline code in a .glm file. This page will go over the requirements in order to create runtime classes as well as the procedure required to build the inline code within the .glm.

Runtime Class Structure

All runtime classes have a fixed structure that must be followed in order to be properly handled by the core within GridLAB-D. The general syntax is shown below. 

class classname [inheritance] {

	// variables ...
 	GLMtype [options] property_name[[unit]];
	
	// GridLAB-D procedures ...
	intrinsic procedure (arguments) { 
		// ... 
	};
	
	// other class members ...
	public member ...;
	protected member ...;
	private member ...;
}

Variables

All GLMtype variables are published properties of the runtime class by default. A list of all GLMtypes can be seen below.

  • bool
  • char8, char32, char256, char1024
  • int8, int16, int32, int64
  • enumeration, set
  • double, complex, float, real
  • timestamp, loadshape, enduse
  • object

An example of glmtype variable is shown below. 

double frequency[Hz];

Enumeration and set types must have keywords as seen below. 

enumeration {OFF=0, ON=1} status;
set {A=1, B=2, C=4, D=8} phases;

Note that enumeration cases can be sequentially numbered but each case within a set must correspond to a sequential power of 2. For data/time applications, the timestamp type should be used. When referring to the current object, the keyword, my, should be used. for example, my->name retrieves the name of the current object.

C/C++ types are also allowed however, a scope keyword (public, private, and protected) is required at the variable's declaration. It is recommended that the private and protected scope keywords be avoided as GridLAB-D can't properly handle them. All C/C++ types can't be published properties of the class and thus can't be utilized as I/O variables.

Runtime Procedures

There are three different procedure sections within the runtime class.

Create Procedure

The argument for the create procedure is always an object. It is always the first procedure called after memory is allocated. The create procedure should only be used if the parent object is known at time of creation. Create is where all variable defaults should be located. After all defaults are set then a return of SUCCESS or FAILED is required. An example of a proper create procedure would look something like this. 

intrinsic create(object parent){
     // defualt values go here
     return SUCCESS;
};

Init Procedure

Init is where validation and in certain cases initializaion of the object's properties are done. This procedure is used to check to see if the user gave enough information for the object to perform its various functions within the follow procedure. Like create, object is the argument for init and should only be used when the parent object is known. Init also requires a return of SUCCESS or FAILED. An Example of a proper init procedure would look something like this. 

intrinsic init(object parent){
     // check values here
     return SUCCESS;
};

Presync/Sync/Postsync Procedure

The presync, sync, and postsync procedures always require two timestamp arguments, t0 and t1 for example. t0 is considered the from time. On the first iteration t0<t1, otherwise t0 = previous t1. t1 is the desired to time. These procedures are where the behavioral functions of the class should be located. As to what should be in presync, sync, or postsync is really up to the user. As an analogy think about how an average is taken. Presync is where all the data would be generated. Sync is where all the data is collected and summed together. Postsync is where that sum is divided buy number of data points. A single timestamp variable should be returned at the end of each procedure. For example, say the return variable is t2. If t2>t1, then the procedure failed and the simulation is unable to continue. If t2=t1, then the procedure failed and another iteration of the procedure is performed until t2>t1 at which time the procedure is successful. The procedure called until t1 equals the smallest of the returned t2 values from the various objects in the simulation. To tell GridLAB-D that the runtime class has reached a steady state and will no longer change t2 must equal TS_NEVER. Once all objects have their t2 = TS_NEVER then the simulation will end.If t2<0 this is treated as a soft event. Soft event means that t2 is treated as TS_NEVER if all other objects returned a TS_NEVER otherwise -t2 is used in determining the smallest returned t2 among the objects. Below is an example of the proper use of the presync/sync/postsync precedures. 

intrinsic sync(TIMESTAMP t0, TIMESTAMP t1){
     t2 = TS_NEVER;
     return t2;
};

Runtime Class Requirements Prior to Keeler (Version 4.0)

C/C++ Compiler

A C/C++ compiler is required to utilize the runtime class. When installing GridLAB-D to your computer the installation process will ask if you wish to install a list of weather files and select programs. Among these is a g++ compiler called MinGW. If MinGW was installed with your installation of GridLAB-D then the runtime class can be used. If MinGW was not installed then it can be downloaded from sourceforge. Make sure when downloading MinGW to select g++ as one of the compilers to install. For those who downloaded the repository through tortoiseSVN, MinGW can be installed buy clicking on the corresponding .exe file in \gridlab-d\tools\mingw.

Setting the Path Environment

When running .glm files that contain runtime classes GridLAB-D must be told where to find the compiler as well as a few other files. The user must have permission to write to C:\temp as this is the default folder used for working files. If the user is unable to write to this file then tmp must be pointed to another writable folder within the .glm file. This line would look something like the following. 

#set tmp=c:\mytemp

In order for GridLAB-D to find the g++ compiler the user must set the environment path to point to the .exe file. In the MinGW folder this is located in the bin folder. The following line gives an example of what this might look like. 

#setenv path=c:\mingw\bin

The last thing that is required is that the rt folder within the GridLAB-D folder be included with the .glm file. The following line gives an example of what this might look like. 

#set include=c:\gridlab-d\trunk\core

Visual Studio can also be used instead of MinGW for those who downloaded the GridLAB-D repository. In order to use Visual Studio as the g++ compiler the directory \trunk\vs2005\win32\debug within your repository folder must be added to the system path. Once this is done, there is no need to set the path to point to MinGW's bin folder in the .glm file.

Security Enhanced Linux (SELinux)

Linux systems with enhanced security must permit loading of .so files created by GridLAB-D at runtime. At this time, the simple way to do this is to disable SElinux. A better solution from a security standpoint would be to allow unconfined executables to use libraries that are not labeled texrel_shlib_t, but there seems to be no way to label anonymous libraries before they are created at runtime. See https://svn.pnl.gov/Gridlab-D/ticket/200 for more information about this issue.

See also

Retrieved from "https://gridlab-d.shoutwiki.com/w/index.php?title=Runtime_Class_User_Guide&oldid=2177"