Coding guide

The coding guide is intended for GridLAB-D developers of makefiles, maintenance scripts, modules, classes, and infrastructure code.

Makefiles

The makefiles are built by autotools using the files Makefile.am, aminclude.mk, configure.ac, custom.mk, and modules.mk. In addition, auxiliary support files are located in build-aux/.

Maintenance Scripts

The shell script install.sh is used to setup the host system to build GridLAB-D. It also uses auxiliary support files located in build-aux/. Some systems also require scripts and tools available in the third_party/ and utilitie/s folders.

GridLAB-D Modules

GridLAB-D modules implement GridLAB-D classes, solvers, and module globals. Modules are defined in folders using the module name. Depending on their age, modules use different core APIs, as shown in Table 1.

Table 1 - Module core API versions

Module name	API Version	Remarks
assert	3	Older classes use APIv2
climate	2
commercial	2
generators	2
industrial	3
influxdb	3
market	2
mysql	3
optimize	2
powerflow	2
powernet	3
reliability	2
revenue	3
tape	1
transactive	3

APIv3

APIv3 is used for all new modules as of GridLAB-D 4.0. This API supports a C++ class library wrapped around APIv2 callback functions for module implementation.

Table 2: Module Implementation Template for APIv3

File	Purpose	Remarks
Makefile.mk	Module makefile	Specifies how module is built
main.cpp	Module main	Includes main, initialization, and termination code
<module>.h	Module header	Includes all module headers and core linkage headers
<class>.h	Class header	Includes declaration of class and supporting data types
<class>.cpp	Class implementation	Includes implementation of class

Please see GridLAB-D 4.2 developer documentation for details.

APIv2

APIv2 is used by modules developed between GridLAB-D 2.0 and GridLAB-D 3.2. This API supports C and C++ style callback functions for module implementation. APIv2 is obsolete. Please refer for GridLAB-D 3.2 documentation for details.

APIv1

APIv1 is used by modules developed before GridLAB-D 2.0. This API supports C-style callback functions only for module implementation. APIv1 is obsolete. Please refer to GridLAB-D 1.3 documentation for details.

Infrastructure

GridLAB-D can be run on laptops, workstations, private servers, or cloud systems. The infrastructure tools provided with GridLAB-D's source code help developers build and deploy GridLAB-D on these systems.

Containers

Containers provide immutable images which can be used to ensure indefinitely reproducible results. The source code to each container can be obtained from the open-source repository from which the image was produced. The following images are generated for GridLAB-D at this time:

Host	URL	Container name	Remarks
Docker	https://hub.docker.com/repository/docker/slacgismo/gridlabd	slacgismo/gridlabd:<tag>
Amazon	https://us-west-1.console.aws.amazon.com/ec2/v2/home?region=us-west-1#LaunchInstanceWizard:	gridlabd/<major>.<minor>.<patch>-<number>-<branch>/ec2/<name>-<tag>	Search for "gridlabd" in Community AMIs

Continuous Integration

GridLAB-D branches are validated using GitHub workflows and Docker Hub. The GitHub validation is controlled by the source file .github/workflows/master.yml and .github/workflows/develop.yml. Docker Hub validation is controlled by the source file docker/Dockerfile.

At this time, there is no automated deployment of containers using CI tools.

Utilities

A number of utilities and auxiliary build files are used to build and deploy GridLAB-D. These are implemented in the build-aux/ and utilities/ folders in the source tree.

File Converters

GridLAB-D currently implements its own input and output converters, which are located in the gldcore/converters/ source folder.

The plan is to transfer these converters to the OpenFIDO project in the near future and modify GridLAB-D to use OpenFIDO for all standard input and output file conversion processes.

Subcommands

GridLAB-D supports a number of subcommand, which can be accessed either via the command line, e.g., gridlabd <subcommand> [<options> ...] or using the corresponding GLM macro, e.g., #<subcommand> [<options> ...].

Subcommands are located in the gldcore/scripts/ folder. The naming convention requires subcommands use the name gridlabd-<subcommand>. The subcommand may be implemented in any language which can be regarded as an executable by the shell environment, including shell scripts, python scripts, and binary images.