Runtime module API

---

Detailed Description

The GridLAB-D external module header file.

The runtime module API links the GridLAB-D core to modules that are created to perform various modeling tasks. The core interacts with each module according to a set script that determines which exposed module functions are called and when. The general sequence of calls is as follows:

• Registration: A module registers the object classes it implements and registers the variables that each class publishes.
• Creation: The core calls object creation functions during the model load operation for each object that is created. Basic initialization can be completed at this point.
• Definition: The core sets the values of all published variables that have been specified in the model being loaded. After this is completed, all references to other objects have been resolved.
• Validation: The core gives the module an opportunity to check the model before initialization begins. This gives the module an opportunity to validate the model and reject it or fix it if it fails to meet module-defined criteria.
• Initialization: The core calls the final initialization procedure with the object's full context now defined. Properties that are derived based on the object's context should be initialized only at this point.
• Synchronization: This operation is performed repeatedly until every object reports that it no longer expects any state changes. The return value from a synchronization operation is the amount time expected to elapse before the object's next state change. The side effect of a synchronization is a change to one or more properties of the object, and possible an update to the property of another object.

Note that object destruction is not supported at this time.

GridLAB-D modules usually require a number of functions to access data and interaction with the core. These include

• memory locking,
• memory exception handlers,
• variable publishers,
• output functions,
• management routines,
• module management,
• class registration,
• object management,
• property management,
• object search,
• random number generators, and
• time management.

Todo:

Many of the module API macros would be better implemented as inline functions (ticket #9)

Modules
	Publishing variables
	Modules must register public variables that are accessed by other modules, and the core by publishing them.
	Exception handling
	Module exception handling is provided for modules implemented in C to perform exception handling, as well to allow C++ code to throw exceptions to the core's main exception handler.
	Output functions
	Module may output messages to stdout, stderr, and the core test record file using the output functions.
	Memory allocation functions
	The core is responsible for managing any memory that is shared.
	Core access functions
	Most module function use core library functions and variables.
	Class registration
	Class registration is used to make sure the core knows how objects are implemented in modules.
	Object management
	Object management macros are create to allow modules to create, test, control ranks, and reveal members of objects and registered classes.
	Property management
	Use the property management functions to provide and gain access to published variables from other modules.
	Object search
	Searches and navigates object lists.
	Random numbers
	The random number library provides a variety of random number generations for different distributions.
	Time handling functions
	Global variables
	Locking memory
	Memory locking is implemented using compare and exchange methods.
CDECL EXPORT EXTERN CALLBACKS *callback	INIT (NULL)
	Newton-Raphson branch data pointer array.
Defines
#define	PADDR(X)   ((char*)&(this->X)-(char*)this)
	The PUBLISH_ENUM(C,N,E) macro is used to define a keyword for an enumeration variable.

---

Define Documentation

#define PADDR

(

X

)

((char*)&(this->X)-(char*)this)

The PUBLISH_ENUM(C,N,E) macro is used to define a keyword for an enumeration variable.

The PUBLISH_SET(C,N,E) macro is used to define a keyword for a set variable

Definition at line 161 of file gridlabd.h.

Referenced by capacitor::capacitor(), comm::comm(), house::house(), house_e::house_e(), link::link(), meter::meter(), plc::plc(), substation::substation(), and waterheater::waterheater().

---

Function Documentation

GLOBAL OBJECT *last_node INIT

(

NULL

)

Newton-Raphson branch data pointer array.

restoration object of the system

Newton-Raphson swing bus.