Glengine

glengine - GridLAB-D engine library

class glengine { public: glengine(void) ~glengine(void); int connect(const char *command, ...); int shutdown(int code); int restart(void};  int signal(int sig);   int send(const char *name, const char *value);   int recv(const char *name, const char *buffer, int maxlen);   int sync(const char *time); public:   void set_debug_level(int n);   int get_debug_level(void); public:   void set_timeout(int n);   int get_timeout(void); public:   void set_window(bool b);   bool get_window(void); public:   pthread_t get_pid(void); public:   void set_addr(unsigned long addr);   void set_addr(unsigned char a, unsigned char b, unsigned char c, unsigned char d);   unsigned long get_addr(unsigned int part); public:   void set_port(unsigned short n);   unsigned short get_port(void); public:   int get_errorcode(void);   const char *get_errormsg(int code); }

Description
The GridLAB-D Engine is a C++ class library that allows developers to link synchronously with GridLAB-D's core using the Engine link. The GLM file must be listed among the command line arguments. The GLM file must include a link directive to enable data exchange between the application and GridLAB-D. The structure of an engine-based application is shown in Figure 1.

glengine



 * Constructs an instance of GridLAB-D asynchronously using the command line provided. If the command is included, connect is called before returning. If an error occurs an exception is thrown.

~glengine

 * Destroys an instance of GridLAB-D.

connect
The call will return once the link is established. Error result reasons include
 * Timeout : The link was not successfully established before the timeout.
 * Bad command : The command line was not valid.
 * Shell error : The shell could not be started.

shutdown

 * Shuts down an instance of GridLAB-D but retains the data buffers.

restart

 * Restarts an instance of GridLAB-D. If the instance is not shutdown, it is shutdown first and then restarted.

signal

 * Send a signal to a GridLAB-D instance. See signal for details.

send

 * Send a data element to a GridLAB-D instance. The data element must be listed in the link directive in the GLM file loaded.

recv

 * Receives a data element from a GridLAB-D instance. The data element must be listed in the link directive in the GLM file loaded.

sync

 * Send a clock synchronization message to GridLAB-D.

Example
The following example illustrates how the glengine class is used to open a link to a new gridlabd instance, synchronize with the simulation, receive and send data to the instance.


 * example.cpp

int main(int argc, char *argv[]) { 	// prepare to catch exceptions from engine calls try { // connect to a gridlabd instance running the model in 'engine.glm' glengine::set_initial_debug_level(9); glengine engine("gridlabd","-W .","--verbose --debug","example.glm",NULL); // prepare a buffer to handle the timestamp // NEVER used to indicate no return time is desired char timestamp[64] = "NEVER"; // run until sync fails while ( engine.sync(timestamp,sizeof(timestamp)) ) {	 			// prepare a buffer to receive the value char buffer[1024]; // request the value 'y0' if ( !engine.recv("y0",buffer,sizeof(buffer)) ) throw "recv failed"; // send the value for 'x0' if ( !engine.send("x0","12.34") ) throw "send failed"; } 	} 	catch (const char *msg) { 		fprintf(stderr,"example: %s\n",msg); } }
 * 1) include 
 * 2) include "glengine.h"


 * example.glm

link example.link; // fill in the rest of the model


 * Link file

target engine // fill in the rest of the link directives

Version
The glengine class was introduced in Hatwai.