GridLAB-D Wiki:GridLAB-D Tutorial Chapter 2 - GridLAB-D Key Attributes

Table of Contents
 * Previous: Chapter 1 - Installing GridLAB-D
 * Next: Chapter 3 - Basic Distribution System Modeling

Depending on your background with software development, familiarity with other distribution system simulators, and the specific studies being done GridLAB-D may come across as cryptic, flexible, complicated, overwhelming, and/or limited. To help provide context and explain what makes GridLAB-D unique and the kinds of problems it can be helpful in addressing, the remainder of this chapter addresses some of the key attributes of GridLAB-D.

Open Source
GridLAB-D is open source software whose development has been largely funded through the [| United States Department of Energy]. Two distinct advantages come with being open source:
 * 1) Code is readily available for inspection. This is helpful for those trying to learn GridLAB-D as it allows access to all the inner workings of the software. There is no need for mystery about what the software is actually doing as all mechanisms are laid bare.
 * 2)  Correction or expansion of the code base to meet the user’s particular need is possible. If a bug is found, any user can correct it. If additional functionality not present in the standard distribution of the software is needed, users can modify existing code or augment it with their own to provide that functionality.

Command-Line
GridLAB-D is a pure command-line program; there is no GUI at the time of this writing. The input files that GridLAB-D uses when running a simulation are simple text files as are the most common output files. To start a simulation, users will type commands into a system terminal or command line where the on-going status of the simulation will also be displayed. While this does increase the learning curve for many users as defining systems via text files and typing commands at a text-based command prompt increases the level of abstraction, text-based simulations have advantages.
 * 1) Portability - With all inputs and outputs as text files, viewing and graphing results from a simulation is easily accomplished through any number of tools such as gnuplot or Microsoft Excel.
 * 2) Scalability - Using a GUI to directly define small systems is very convenient and intuitive but defining large systems by hand is tedious and imprecise. Defining a multi-thousand node distribution system with text manipulation and scripting tools such as Matlab, Python, Perl, or even grep allows models to be created and modified in a much more efficient manner.

Object-Based
GridLAB-D can be thought of as a core simulator with a collection of modules that contain model implementations for various entities that are relevant for distribution system simulations. Said differently, the GridLAB-D core is responsible for managing the flow of the time and interactions between a number of objects that have been assembled to simulate the effects of a distribution system as a whole. Because of the modular nature of GridLAB-D, there are a few terms that should be clarified as they will frequently come up during discussion of the design and use of GridLAB-D. When looking at a GridLAB-D model file (“.glm”), almost all the text in the file is devoted to defining objects. All of these objects are specific instances of classes (models) and their parameter definitions and relationships between each other constitute the system as a whole that is being modeled.
 * “Model”- An engineering or mathematical term (rather than programming). There are two somewhat related ways in which this term is used in the GridLAB-d world,
 * 1) A general term to describe how a particular part of GridLAB-D functions or is represented in code. For example, "How does GridLAB-D model solar panels?"
 * 2) A "model file" (commonly ending in ".glm") containing the description of the distribution system being studied. This file contains the specific statement used to model a distribution system as a whole. For example, "Where is the model you used for that assignment?"
 * "Class" - A C++ programing term with a similar usage as "model". Much of GridLAB-D is written in C++ and sometimes GridLAB-D developers and programmers will use this term somewhat interchangeably with "model", particularly after a long day of programming and trouble-shooting. To be specific, a "class" is the collection of code that contains the equations, parameter declarations, and algorithms that define how a particular entity will behave in GridLAB-D. For example, in GridLAB-D there are classes that define the operation of capacitors, air-conditioners, voltage regulators, houses, and solar panels, among others. In the air-conditioner class, there is code that defines, for example, how much current air-conditioners draw when operating, and how much cold air they put out; these types of definitions are essential to create some kind of model of an air-conditioner that interacts with the grid and buildings realistically. Also note that in a class, these kinds of model/class parameters are generic and have no specific values associated with them (though default values may be defined). The code in the class definition describes how the current from the grid relates to the amount of cold air produced but does not necessarily define any specific amount of current drawn for all air-conditioners ever created in GridLAB-D. The specific current draw will get defined when all the class parameters are given specific values as a part of a specific instance of the air-conditioner class being created in a model file (".glm").
 * "Object" - Another C++ programming term used in a very similar way to that language. In C++, an object is a specific instance of a class. That is, an object is one particular, air-conditioner, house, or solar panel that may operate slightly differently than another one next door or down the street. The inner workings of all air-conditioners are defined by the air-conditioner class but their size, efficiency, and location can be different from one particular air-conditioner to another. All air-conditioners function in the same way as defined by code for their class (e.g. turning electrical energy into cold air) but the specific values assigned to the parameters for each object will produce unique operational patterns.
 * “Module” - A collection of related classes typically defined in the same source code file. Modules will often need to be explicitly included in a model file to give GridLAB-D access to their functionality.

As an example, open up course/Tutorial/Chapter 2 - Key Attributes/Sample Model/sample_model.glm with a text editor. At the top of this model file (or simply "model") you'll see a number of module declarations such as module tape; module generators;

module powerflow{ solver_method FBS; default_maximum_voltage_error 1e-9; line_limits FALSE; };

module climate;

module residential { implicit_enduses NONE; ANSI_voltage_check FALSE; };

module powerflow { solver_method FBS; NR_iteration_limit 100; };

Each of these module statements links in a portion of the code base that enables specific functionality in this particular GridLAB-D model.

Looking further down the model you'll see that most of the statement groups begin with object such as object node { name R1-12-47-1_node_613; parent R1-12-47-1_meter_21; phases ABCN; voltage_A 7216.88+0.0j; voltage_B -3608.44-6250j; voltage_C -3608.44+6250j; nominal_voltage 7216.88; } . . . object overhead_line { groupid Distribution_Line; name R1-12-47-1_ol_299; phases ABCN; from R1-12-47-1_node_4; to R1-12-47-1_node_25; length 487.200; configuration line_configuration_22; } . . . object house { name myHouse; parent tpm2_R1-12-47-1_tm_21; floor_area random.normal(1750,400); heating_setpoint 70; cooling_setpoint 78; air_temperature 79; }

Each one of these objects is a specific instance of a particular class (node, overhead_line, house). As a part of each class are a set of algorithms and equations that define how all objects of this class should behave. For example, the code in the overhead_line class will be used to define how much of a voltage drop should occur as a given amount of current flows through the line.

There can (and often will be) multiple instances of a class in a given model (model file, ".glm") though each one will likely be unique due to the specific values associated with each parameter in the object definitions. For example, look at two particular overhead_line objects in the model:

object overhead_line { groupid Distribution_Line; name R1-12-47-1_ol_298; phases ABCN; from R1-12-47-1_node_3; to R1-12-47-1_node_21; length 167.609; configuration line_configuration_22; } . . . object overhead_line { groupid Distribution_Line; name R1-12-47-1_ol_290; phases ABCN; from R1-12-47-1_node_11; to R1-12-47-1_node_12; length 283.154; configuration line_configuration_22; }

These are both overhead_line objects and though they use the same equations to define their operation in the simulation, you can see that each has different lengths (among other differences). Because of this difference, the equations of the overhead_line</tt> class will produce a different voltage drop across each overhead_line</tt> instance, that is, each of the objects instantiated from that class.

Multi-Domain Models
GridLAB-D is commonly represented as a distribution system and/or smart grid simulator with incredibly useful built-in classes that are more than what you might find in a traditional distribution system simulator. GridLAB-D contains classes for all may common distribution components (transformers, lines, voltage regulators, capacitors, ZIP loads,...) it also contains classes for solar PV, energy storage, residences with air-conditioners and water heaters, and weather. Though each of these has impacts on the operation of the distribution system, it is their behavior outside the electrical system as it is modeled by GridLAB-D that is most compelling. A house with an air-conditioner is modeled to not only represent how much energy the air-conditioner uses when it is running but also how often it runs and for how long based the indoor temperature which in turn is driven by the thermodynamic properties of the house (how large it is, how much insulation, how many windows...) and the weather. These multi-domain interactions provide a capability not often seen in other distribution system simulators.

While GridLAB-D is commonly used to simulate distribution systems and smart grids in particular but there is no reason that it needs to be limited to this in scope. It is entirely possible to use the existing GridLAB-D framework to simulate vegetation growth, weather, or vehicle traffic patterns while simultaneously simulating an electrical distribution system. Given that very few, if any, of the GridLAB-D classes would be usable to add these features, a lot of coding would be required to define a new classes with the appropriate equations, algorithms, and parameter declarations so that, say, the grass and trees in the simulation behaved in a realistic way.

Discrete Time
GridLAB-D is a discrete time simulator meaning it does not simulate a continuous flow of time as you might see in something like a SPICE circuit simulator or Simulink model. Truth be told, these simulators are not actually continuous but the time steps used by the simulator are small enough and regularly spaced so as to closely and reasonably approximate continuous time. GridLAB-D makes no such effort and operates in a fundamentally different way.

GridLAB-D simulates time in discrete blocks that can vary in size; that is, the step size of the simulation is constant. The GridLAB-D core jumps from one discrete time to the next, asking all objects in the model (“.glm”) to update themselves based on how much time has elapsed since the last update. The algorithms and equations for each class define how objects of that class evolve over time and using these relationships, all of the objects can determine their new state at this new point in time.

Since many of the objects in a model interact with each other, having outputs that affect other objects’ inputs, the GridLAB-D core may re-iterate a time step asking all the models to re-update themselves using any new changes to their inputs to recalculate their state. This process may repeat many times until all of the objects have reached a new steady-state.

As a last step in the update process, all of the objects register with GridLAB-D the next time they need to be updated. Since by this point all the objects have reached a steady-state, most of them will indicate that they never need to be updated. Unless there is some external inciting event, their state will not change. There are only a few special objects that end up driving the simulation forward by requiring they be updated at particular times.

As an example, open up course/Tutorial/Chapter 2 - Key Attributes/Discrete Time/discrete_time_demo.glm with a text editor. Even not knowing any of the details of GridLAB-D, you can see this is a very small model. With not too much effort, you could probably guess that this model will run from July 1st, 2001 to July 8th, 2001 (lines 10 and 11) and uses the weather from Spokane, WA (lines 14-16). You can also see on line 21 that a house is included in the model with a number of specific parameters defined.

Also attached to the house is an object called a recorder (lines 34-38). This object is one of the primary means of collecting data from a simulation and it is one of those special objects which regularly tells the GridLAB-D core when it next needs to be updated. One of the parameters of the recorder is its  which is the number of seconds between data collection times. The recorder interval is currently 3600 seconds, indicating it will log a value once an hour. Running this simulation with the profiler turned on...

gridlabd discrete_time_demo.glm --profile

...shows the following...

Core profiler results

=
=========

Total objects                 4 objects Parallelism                   1 thread Total time                  1.0 seconds Core time                 0.9 seconds (86.1%) Compiler                0.5 seconds (47.8%) Instances               0.0 seconds (0.0%) Random variables        0.0 seconds (0.0%) Schedules               0.0 seconds (0.1%) Loadshapes              0.0 seconds (0.0%) Enduses                 0.0 seconds (0.0%) Transforms              0.0 seconds (0.0%) Model time                0.1 seconds/thread (13.9%) Simulation time               7 days Simulation speed            672 object.hours/second Passes completed            552 passes Time steps completed        552 timesteps Convergence efficiency     1.00 passes/timestep Read lock contention       0.0% Write lock contention      0.0% Average timestep          1096 seconds/timestep Simulation rate         604800 x realtime

Model profiler results

=
=========

Class           Time (s) Time (%) msec/obj climate           0.128     92.1%    128.0 house             0.005      3.6%      5.0 recorder          0.003      2.2%      3.0 triplex_meter     0.003      2.2%      3.0

=
=== ======== ======== ======== Total             0.139    100.0%     34.8 (Your specific values will likely be different depending on the computer used for running these simulation.) For our purposes, note the total simulation time in the lower table.

Now go back to the model file, change the interval</tt> to 6</tt> and re-run the simulation. Core profiler results

=
=========

Total objects                 4 objects Parallelism                   1 thread Total time                  4.0 seconds Core time                 2.2 seconds (55.8%) Compiler                0.5 seconds (12.2%) Instances               0.0 seconds (0.0%) Random variables        0.0 seconds (0.0%) Schedules               0.0 seconds (0.0%) Loadshapes              0.0 seconds (0.0%) Enduses                 0.0 seconds (0.3%) Transforms              0.0 seconds (0.5%) Model time                1.8 seconds/thread (44.2%) Simulation time               7 days Simulation speed            168 object.hours/second Passes completed         101355 passes Time steps completed     101355 timesteps Convergence efficiency     1.00 passes/timestep Read lock contention       0.0% Write lock contention      0.0% Average timestep             6 seconds/timestep Simulation rate         151200 x realtime

Model profiler results

=
=========

Class           Time (s) Time (%) msec/obj house             0.586     33.1%    586.0 triplex_meter     0.542     30.6%    542.0 recorder          0.325     18.4%    325.0 climate           0.317     17.9%    317.0

=
=== ======== ======== ======== Total             1.770    100.0%    442.5

Note the difference in total simulation time; it should be significant. By asking the recorder to collect data every 6 seconds instead of every 3600 seconds, we have forced GridLAB-D to update all the objects much more often which requires significantly more calculation. Comparing the entries in the lower table individually, you can see that when we updated every 3600 seconds, the vast majority of the simulation time was spent in the climate class, updating the weather being experienced by the house. When we move the time step down to 6 seconds, now the calculations of the house are largest, followed closely by the power flow of the meter attached to the house.

This example should make it clear that when we change the interval on the recorder, we are not simply changing which results are written out to a file, as if the results were calculated at a very fine time step and sampled as needed by the recorder. By changing the interval on the recorder, we are changing how often the simulation stops to recalculate the state of the system. For many simulations, the effective timestep of the simulation ends up being defined by the recorder, due to its special status in driving the simulation forward.

Table of Contents
 * Previous: Chapter 1 - Installing GridLAB-D
 * Next: Chapter 3 - Basic Distribution System Modeling