From GridLAB-D Wiki
Jump to: navigation, search

Module functions - Required and optional module export functions

Synopsis

Required functions
EXPORT CLASS *init(CALLBACKS *fntable, MODULE *module, int argc, char *argv[]);
EXPORT void term(void);
CDECL int do_kill();
Optional functions
EXPORT int check();
EXPORT int export(const char *file);
EXPORT int import(const char *file);
EXPORT int kmldump( int(*)(const char *file,...), OBJECT *obj);
EXPORT void test(int argc, const char *argv[]);
EXPORT size_t stream(void *ptr, size_t len, bool is_str=false, void *match==NULL);
Subsecond functions
EXPORT unsigned long deltamode_desired(int *flags);
EXPORT unsigned long preupdate(MODULE *module, TIMESTAMP t0, unsigned int64 dt);
EXPORT SIMULATIONMODE interupdate(MODULE *module, TIMESTAMP t0, unsigned int64 delta_time, unsigned long dt, unsigned int iteration_count_val);
EXPORT STATUS postupdate(MODULE *module, TIMESTAMP t0, unsigned int64 dt);

Required functions

init

The init function is required for all GridLAB-D modules. It is called once when the module is loaded. The init should use this opportunity to register all classes and module globals. The template for this function as of Hassayampa (Version 3.0) is: 

// module/main.cpp (init template)
#define DLMAIN
#include <stdlib.h>
#include "gridlabd.h"
EXPORT CLASS *init(CALLBACKS *fntable, MODULE *module, int argc, char *argv[])
{
  if (set_callback(fntable)==NULL)
  {
    errno = EINVAL;
    return NULL;
  }
  // TODO: add gl_global_create() calls here (see module globals for details)
  // TODO: call new for each class here (see create class for details)
  return NULL; // TODO: return oclass member of first new class
}

do_kill

The do_kill function is required for all GridLAB-D modules. It is called when GridLAB-D terminates. The do_kill function should be used only to cleanup temporary files and memory allocation used by the module. 

// module/main.cpp (do_kill template)
#define DLMAIN
#include <stdlib.h>
#include "gridlabd.h"
CDECL int do_kill()
{
  // TODO: perform cleanup actions if needed
  return 0;
}

Optional functions

term

The term function is called when the simulation stop (normally or on error). 

// module/main.cpp (do_kill template)
#define DLMAIN
#include <stdlib.h>
#include "gridlabd.h"
EXPORT void term(void)
{
  // TODO: perform simulation end operations
}

check

The check function is used to allow user to perform module checks before running a simulation. These can be used to verify model consistency, disk space available, and other verification procedures that are not always needed, but can be helpful in diagnosing problems. 

// module/main.cpp (do_kill template)
#define DLMAIN
#include <stdlib.h>
#include "gridlabd.h"
CDECL int check()
{
  // TODO: perform check operations and report issues
  return 0;
}

export

The export function allows a module to define a method for exporting a GridLAB-D to an arbitrary file format. If defined, the export routine is called after the simulation is completed.

module/main.cpp
EXPORT int (*export)(const char *file)
{
  // your export code 
  return count; // count of entities exported
}

import

The import function is used to load a model from an arbitrary file format. The import GLM directive is used to initiative the import process. 

EXPORT int import(const char *file)
{
  // import processing code
  return n; // n=0: failed; n<0: error after loading n entities; n>0: successfully loaded n entities
}

kmldump

The kmldump function is used to output KML (Google Earth) data. 

typedef int (*KMLOUT)(const char *format, ...);
EXPORT int kmldump(KMLOUT kmlout, OBJECT *obj)
{
  kmlout("kml data");
  return 0; // return value is ignored
}

See Google KML Documentation for details on the KML format.

test

The test function is relatively unused and was intended to support module tests.

stream

The stream function will soon be required to support checkpoints.

 TODO: 

Subsecond functions

See Dev:Subsecond for details.

Contingent functionalities

Modules may have runtime functionalities that are not always available, e.g., when an external application is not installed. In such cases, it is highly recommended that the module create a global flag variable only when the functionality is available. You can create a global variable in init, for example: 

bool mytool_ok = false;
if ( load_mytool() )
{
  mytool_ok = true;
  gl_create_global("module-name",PT_bool, &mytool,NULL);
}

This will allow users to create GLM files that have contingent models depending on the presence of the external tools: 

#ifdef module-name
class ...
object ...
#endif

Some examples of contingent functionalities are MATLAB and MYSQL.

VS2005
Often these functionalities are only supported when the proper libraries are installed on the build machine. These modules usually have a special flag set, e.g., HAVE_MYSQL or HAVE_MATLAB so that Linux/Mac machine can automatically build the proper code based on what is installed. In Windows this is not possible. If the libraries are not available, we recommend you unload the project and not build it rather than changing the flag.

Version

Prior to Hassayampa (Version 3.0)
The implementation functions and file structures are different and deprecated.

See also

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