-
Notifications
You must be signed in to change notification settings - Fork 1
Coding guide
The coding guide is intended for GridLAB-D developers of makefiles, maintenance scripts, modules, classes, and infrastructure code.
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/.
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 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 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 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 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.
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 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 |
GridLAB-D branches are validated using GitHub Actions and Docker Hub. The GitHub validation process is controlled by the source files under the folder .github/workflows and the Docker Hub validation is controlled by the source file docker/Dockerfile.
At this time, there is no automated deployment of containers using CI tools.
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.
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.
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.