Introduction

Modules define many classes in a single quick and convenient directive. The largest building block for GridLAB-D™ is the module. These are DLLs that are loaded by the GridLAB-D™ core that use the core functions to register a set of classes, and a set of properties for each of those classes. The core has a small structure with handles to various parts for that DLL, including its name, the module interface functions such as init and check, and the classes registered with that module. Modules are not like class definitions that you give as a directive because they are not compiled when GridLAB-D™ is run. Instead, developers package a collection of classes and distribute a dynamic link library (as a .dll file in Windows or .so file in Linux). Static modules must be loaded before the classes they define can be used or modified (i.e., use module _name_ ;)

Module blocks may include additional information, such as assignments of the values for module globals and specification of the version number. To set a module global variable, simply include the name and value in the module block, such as

 module MyModule {
   MyStringGlobal "value";
   MyEnumGlobal A;
   MyDoubleGlobal 1.2 ft/s;
 }

To enforce verification of the module's version information, simply include the desired version in the module block: ` ``

 module MyModule {
   major 2;
   minor 1;
 }

If the version loaded is not version 2.0 or greater, an error will be displayed and the loader will stop. The minor and build numbers can also be specified, if necessary. Class blocks are used to create, modify, or verify class definitions. If a class is already defined in a static module, then a class block either modifies or verifies the definition provided by the module. Consider the following example ` ``

 module MyModule;

 class MyClass {
   char32 svalue;
   enum {A=0,B=1,C=2} evalue;
   double dvalue[W];
 }

If the properties svalue, evalue, and dvalue are already defined as specified, the class block will load successfully. However, if there are any differences between the class block and the module's definition of the class, then the loader will attempt to address the discrepancy as follows:

1. If the class defines a property differently than the module, then the loader will fail.
2. If the class defines a property that the module does not define, then the loader will extend the module's definition of the class to include this new property.
3. If the class is not defined by any loaded module, then the class is defined as a new class, and the properties are added to that new class. In this case, you may also include C++ code for the behaviors that static modules normally provide. See below for more information on runtime classes.

TODO - Review - Review list before next release. Add note here that says relase number it was last updated.

The currently supported modules are

• Climate: provides an interface that other objects may use to include weather data in their calculations. Objects such as houses and buildings rely on this data to factor outdoor weather into their calculations for internal temperature. The climate data includes temperature, humidity, and solar radiation, which is used to calculate temperature gain that is the result of heat gained from direct exposure of a surface to sunlight.
• Powerflow: provides electrical distribution system modeling for power flow solutions. A power flow calculation is performed to determine what the steady state node voltages and line currents are at each point of the system, given the system model, electrical loads connected at each node, and voltage at the substation. The power flow problem is solved using a three-phase unbalanced flow solver.
  • Reliability: runs one-off reliability analysis on Powerflow models, providing the ability to induce events on a system to evaluate their impacts, collecting outputs and metrics to a log file for user evaluation.
• Residential: models a single-family home and various home appliances
• Generators: DG models act as a load on the system.

The currently unsupported modules are

• Commercial: models office buildings
• Communications: models communications networks
• GLJava: provides JNI interface for loading modules written in Java
• Market: provides wholesale market simulation and responsive appliance controllers
• Matlab: provides a Matlab interface for defining classes in Matlab. This is superseded by the Matlab link core function.
• MatPower: solves optimal power flow using the MATPOWER solver
• Network: models balanced electric networks
• PLC: models programmable logic controllers

The following modules provide debugging and I/O functions

• Assert: contains objects that are used in test modules by breaking the simulation if observed values deviate from expected values.
• Tape: object boundary condition I/O module

Object

Within a specific module, objects describe specific instances of a thing that can respond to and/or act on other objects. A simulation can contain very many objects. It is not uncommon to see a model that contains thousands of objects. Some of the large GridLAB-D™ models have been built that contain well over 100,000 objects. Object references allow a property to describe a reference to another object in the model. These are often used to access variables or functions in other objects.

Synopsis

class name {object variable;}
object name {variable reference;}

Example

To declare an object reference use the syntax:

class name {
  object variable;
}

where name is the name of the class, and variable is the name of the object reference.

To define an object reference use the syntax:

object name {
  variable reference;
}

where name is the name of the class, variable is the name of the object reference, and reference is the name of the object being referred to. Object names can either be a <defined name> or a <canonical name>.

Object (directive)

The object directive is used to define one or more objects in the model.

Synopsis

object class {
  name object-name;
  id object-id;
  groupid group-id;
  parent parent-name;
  rank rank;
  schedule_skew schedule_skew;
  latitude degrees-minutes-seconds;
  longitude degrees-minutes-seconds;
  in date-time;
  out date-time;
  heartbeat seconds; 
  flags NONE|HASPLC|LOCKED|RECALC|FOREIGN|SKIPSAVE|RERANK|DELTAMODE;
}
object class:id { ... }
object class:from-id..to-id { ... }
object class:..count { ... }

Object properties

The valid properties for are determined by the class definition. This includes the units specification. When units are specified in the class, then the value is always stored in memory in those units. If the object definition provide the value with different (but compatible) units, then the value is automatically converted to the units specified by the class so that the behavior needn't consider units when doing calculation using the value. Consider the following example

class house {
  double floorarea[sf];
  init (object parent) {
    printf("floor area is %f sf\n", floorarea);
  };
}
object house {
  floorarea 100 m^2;
}

When init is executed, the floor area will be displayed in sf and not \(m^2\) because the loader automatically converts the value to the units specified by the class definition.

Parameter expansions

String, double, set and enumeration variables can be manipulated during expansion using parameter expansions. For example

#define AREA=1000
class house {
  double floorarea[sf];
}
object house:..5 {
  floorarea ${AREA+=100};
}

will create 5 houses with values of floorarea ranging from 1000 to 1400 by increments of 100.

Common properties

All objects share common properties that can be defined.

Property	Description
name	Specifies the unique name used to reference this object from other objects. Object names must only contain letters, numbers, and underscores. By default, object names cannot start with a number, but the global property relax_naming_rules can be set to a nonzero value to work around this. Starting an object name with a number can lead to parsing errors when linking objects at load time.
id	Specifies the unique id number used to reference this object when no name is given.
groupid	Specifies a group number to which this object belongs. This is used to help find objects that are aggregated using collectors.
parent	Specifies the parent object in the object ranks. parent string; will set an object's parent as the specifically named object. If an object is nested within another object, it will automatically use the object that it is defined within as the parent object. Entering root; into the object's property block will set an object to explicitly not have a parent.
rank	The rank of the object determines its order of execution. An object's parent will always have a numerically greater rank than its children. Object ranks can be increased, but not decreased from within a model file. Increasing an object's rank will cause it to be called later in the pre-top down and post-top down passes, and earlier in the bottom-up pass.
schedule_skew	The number of seconds to offset any input schedule signals by, used to smooth out the otherwise lock-step behavior when changing parameters. Positive and negative integers are equally valid, telling the object to use the value later or sooner, respectively.
latitude	Specifies the latitude of the object's geo-coordinates. It is valid to use decimal numbers with an N, S, E, or W to indicate the hemisphere. Note: only the formats 12N34.56 or 12N34:56 are valid.
longitude	Specifies the longitude of the object's geo-coordinates. See latitude
in	Specifies the date and time at which the object becomes active in the simulation. The default is INIT. Objects that are not in service for the entirety of a given run should not parent any objects.
out	Specifies the date and time at which the object becomes inactive in the simulation. The default is NEVER. See in.
heartbeat	The object heartbeat determines the number of seconds that elapse between calls to the heartbeat__classname_() export function. If the object heartbeat is zero or if the object's class does not export the heartbeat function, the heartbeat is not called. By default the object heartbeat is zero.
flags	Specifies the flags for special object behavior. See below for the specific meanings of the various flags * NONE: Indicates that no flags are set (default). * HASPLC: Indicates that the object has active PLC code. Deprecated as of Hassayampa (Version 3.0) * LOCKED: Indicates that the object is current locked against concurrent memory access control. * RECALC: Indicates that the object is in an inconsistent state and needs an internal recalculation to be performed at the earliest opportunity. * FOREIGN: Indicates that the object was created by a DLL and its memory cannot be freed by the core. * SKIPSAFE: Indicates that the object sync functions can be safely skipped. * RERANK: Reserved for internal use only. * DELTAMODE: Indicates that the object should be included in any subsecond processing.

Single objects

To create a single object use the syntax:

object class {
  property value ;
  // ...
}

Numbered objects

To create an object with a specific identification number use the syntax:

object class :id {
  property value ;
  // ...
}

Multiple numbered objects

To define multiple objects with identification numbers in a range use the syntax:

object class :from..to {
  property value ;
  // ...
}

Multiple objects

To define multiples objects use the syntax:

 object class :..count {
  property value ;
  // ...
}

Expansions

There are a number of intrinsic expansions available while an object is being defined:

Expansion	Description
{file}	embeds the current file (full path,name,extension)
{filename}	embeds the name of the file (no path, no extension)
{fileext}	embeds the extension of the file (no path, no name)
{filepath}	embeds the path of the file (no name, no extension)
{line}	embeds the current line number
{namespace}	embeds the name of the current namespace
{class}	embeds the classname of the current object
{id}	embeds the id of the current object
{var}	embeds the current value of the current object's variable var

Expansions are embedded using the syntax:

object class {
  property `value{expansion}value `;
}

For example, the following property assignment will embed the object id in the property my_string :

my_string `object_{id}`;

Finding Objects

Searching for objects and defining object groups both use the same syntax.

Search criteria

Object searches are usually expressed using a search criteria, such as

object class {
  group "property op value";
  // ..
}

where class is the class of object that uses the group property (e.g., collector, histogram), property is the object property to match against (e.g., name, class, parent), op is the comparison operator (e.g., =, <, !~), and value the value to match against.

The following properties are always recognized, in addition to all the properties defined by the class:

Propertie	Description
class	the name of class which implements the object
module	the name of the module which implements the class
id	the id number of the object
name	the name of the object
parent	the parent of the object (matches the name of the parent)
rank	the object's rank
latitude	the object's latitude
longitude	the object's longitude
clock	the object's clock
in_svc	the object's in-service date/time
out_svc	the object's out-of-service date.time
flags	the object's flags (see Object header properties )

Compound criteria

Multiple search criteria can be indicated using and/or as appropriate. Parenthetical operators are not supported.

The implementation of the and and or operators is incomplete and not mathematically correct. Any logical statement joined with an and will remove all objects not identified with that operation from the working set. Any logical statement joined with an or will add all objects that match that operation to the working set. There is no sense of operator precedence, and operators are processed from left to right.

For example, to build the set 'all triplex_meters with groupid blue or groupid red', the set must be 'groupid=red OR groupid=blue AND class=triplex_meter'. First the set is populated with all objects with a red or blue groupid, then is filtered for only the triplex meters in that set.

The set 'all triplex_meters with groupid blue, plus all meters with groupid red' cannot be generated with the existing system. 'groupid=red AND class=triplex_meter OR groupid=blue AND class=meter' will only return meters with the blue groupid.

Date/time values

Date and time values must be fully qualified absolute date/time stamps using the appropriate timezone. Relative time can also be given using s, m, h, d, or w suffixes as desired, e.g., 1800s to indicate 30 minutes.

Operators

Operator	Description
!=	Not equal, e.g., property!=number
<=	Less than or equal, e.g., property<=number
>=	Greater than or equal, e.g., property>=number
!~	Not like, e.g., property<=string
=	Equal, e.g., property=number
<	Less than, e.g., property<=number
>	Greater than, e.g., property>=number
~	Like, e.g., property<=string