GridLAB-D Wiki:GridLAB-D Tutorial Chapter 9 - Interfacing with External Software

Table of Contents
 * Previous: Chapter 8 - Built-In Distribution Models

Though the utility of GridLAB-D is relatively broad (when thinking of it as simply an electrical distribution simulator), the scope of the research in which it is employed is much broader. Rather than forcing users to implement additional functionality by extensively modifying and extending the GridLAB-D source code, GridLAB-D has implemented a number of ways in which it can programmatically interact with external software packages. This chapter will demonstrate how these interfaces work.

MATLAB Interface
MATLAB is a very common general technical computing language and environment. Because MATLAB is so general, the interface with GridLAB-D allows for a dramatic increase in functionality, allowing user written MATLAB code to interact with objects in GridLAB-D.

Building GridLAB-D with MATLAB
To enable this interaction, GridLAB-D must first be compiled from source with additional options (Chapter 1 - Installing GridLAB-D). These options are enabled when running ./configure : ./configure --with-matlab=

If this option has been correctly set, the output of the ./configure will show that the software hooks have been implemented. ... gridlabd 4.0.0: Automatic configuration OK.

Dependencies:

MinGW: ...................... no   Doxygen: .................... /usr/local/bin/doxygen libcppunit: ................. no   libxerces-c: ................ yes matlab: ..................... yes mysql-connector-c: .......... no   curses: ..................... yes

... (Once this has been verified, be sure to complete the GridLAB-D installation process.)

The core interaction between GridLAB-D and MATLAB comes in two parts. The first is a set of three MATLAB commands that can be defined, each running at a different stage in the process: initialization (on_init), each timestep (on_sync) and at the conclusion of the GridLAB-D simulation (on_term). These three functions determine what MATLAB will do, the functionality it will provide during the run of the GridLAB-D simulation.

The second portion of the interaction is the variable value exchange. Though there are probably cases in which MATLAB functions need to be called without using any data from the GridLAB-D simulation, the far more likely scenario is that the MATLAB function being called will be using values from GridLAB-D and may be returning values that need to be incorporated into GridLAB-D.

Note that the link between MATLAB and GridLAB-D can be problematic at times. If difficulties in the compiling or use of the link is not behaving properly, check the GridLAB-D forums to see if other users have encountered similar problems.

The following two examples will show how to configure the GridLAB-D model file and link file to enable the connection between MATLAB and GridLAB-D.

Example - Energy Meter
For this example, let's do something a little silly and use MATLAB as an energy meter, summing the power flow of one of the batteries in the model at each time step of the GridLAB-D simulation to calculate the total energy transfer. (This is a silly example because GridLAB-D already has meter objects that do exactly this but we can pretend that maybe this particular user is VERY new to GridLAB-D.) Open up the MATLAB_link.glm model file to see how we enable this connection from GridLAB-D.

At the very top of the file, we've added a statement that tells GriLAB-D where to look for the MATLAB link configuration. link MATLAB_energy_meter.link And that's it; that's the only change we need to make. We will still be referring to the specific variable names in the model file as we build the link file but this is the only edit that is needed.

Now open up the MATLAB_energy_meter.link file itself. The comments in the link file are mostly self-explanatory and additional details can be found on the Matlab link wiki page. The most important items in our case are: on_init b1m1_batt_energy_kWh = 0; ans=GLD_OK If this last part is not added a confusing error message will be posted when the model is run that does not affect the simulation or its results. Error using save Variable 'ans' not found. This applies to the on_term command as well.)
 * on_init - This is the MATLAB command run prior to the start of the GridLAB-D simulation. In this case, we simply use it to initialize the variable we'll be using to zero. As the comments indicate, the state of ans can be used to to test whether the command succeeded. (Somewhat paradoxically, this value can be set explicitly by making the command:
 * on_sync - This is the MATLAB command that will be run every time that GridLAB-D updates the state of all the objects in the model. Using ";" it is possible to string together a large number of MATLAB commands to form relatively complex statements though at some point it probably makes more sense to use a function call (discussed in the next example). For this function, the last statement defining is essential and must be set in the link file.
 * on_term - Similar in form and function to the on_init</tt> function but runs at the completion of the GridLAB-D simulation.
 * global clock - Required to correctly enable to connection between GridLAB-D and MATLAB.
 * import/export - Defines how the values are exchanged between GridLAB-D and MATLAB. export</tt> statements are used for values flowing from GridLAB-D to MATLAB and import</tt> for the converse. The first parameter is the GridLAB-D object name and object parameter name (joined by a ".") that is being passed between the two; the second is the MATLAB name of the same parameter. In this case we're sending the real power measurement of the triplex meter just upstream of the battery out to MATLAB.

When we use GridLAB-D to run a simulation of this model, MATLAB gets called (the MATLAB launch splash screen may or may not show up) and the power measurements GridLAB-D makes get passed to it. Looking the definition of the b1m1_batt</tt> and b1m1_batt_inv</tt>, we can see the the battery is operating at 3 kW and the simulation runs for half an hour which means the total energy discharged should be 1.5 kWh. The on_term</tt> function has MATLAB write this value out to a CSV and opening that up shows, indeed, the total energy from the battery is 1.5 kWh (the negative indicating the battery was discharging).

Example - Battery Control
The above example is not the most useful application for MATLAB so let's try something a little more complicated and control the output of the battery using a MATLAB function. Open up MATLAB_battery_control.glm and MATLAB_battery_control.link. The general structure of the file is similar to the last example though there are a few items of note.

The on_sync</tt> MATLAB command is a function call using two values from GridLAB-D and returning a third. Looking down at the bottom of the file to the import</tt> and export</tt> section, we can see that a single GridLAB object parameter is both import</tt>ed and export</tt>ed (which is perfectly fine) but each of these statements assigns a separate MATLAB name to avoid confusion in the MATLAB function.

Opening up the MATLAB function ("battery_controller.m") reveals a simple function that charges the battery until it is almost full and then discharges until it is almost empty. Each time the function is called, the input variables are appended to a CSV.

The on_init</tt> and on_term</tt> play supporting roles with the former deleting any previous results file hanging around to provide a clean slate for the run and the later reading in the results CSV and making a plot. Note that both of these lines use multiple MATLAB commands strung together with ";" at the end of each and either or both could have been packaged into stand-alone function files like the on_sync</tt>. Doing so might have been a good idea to increase readability of the file (particularly with the lengthy on_term</tt> command) but they work just fine as is and demonstrate what is possible from inside the link file.

When running the model, like before, MATLAB is called by GridLAB-D, the simulation runs, and two output files are produced: the raw data CSV and an image of the graph MATLAB produced of that raw data.



As the graph shows, the simple controller functions as expected, keeping the battery with certain state-of-charge range. Though this is a very simple controller, it is easy to imagine a much more complex controller being implemented in MATLAB, using perhaps a wider variety of input data and running more complex calculations to determine the battery's output. Without having to learn the broader architecture of GridLAB-D source code, in this way MATLAB can be used to implement custom functionality.

FNCS
FNCS (Framework for Networked Co-Simulation) is a companion software package developed at PNNL, which, as the name implies, allows GridLAB-D to interact with other supported software as co-simulators. Using FNCS allows GridLAB-D to interface with more than just a single MATLAB instance and by doing so enables very large collections of simulation instances to exchange information and effectively simulate a single aggregated system.

For example, FNCS allows the simulation of both the bulk transmission system and one or more distribution systems in such a way that the results of each affect the other. A single transmission system model solved in MATPOWER could be used to define nodal voltage values. GridLAB-D models of distribution systems can be attached to these transmission system nodes and, in turn, use this voltage information to solve its system and define a load value seen at that transmission system node. This proces then repeats AS MATPOWER uses this new updated load information to redefine the nodal voltages throughout the transmission system. This exchange of information overcomes traditional analysis barriers by allowing changes in the transmission system to affect the distribution system and vice versa.

As of this writing, FNCS is still in early development though demonstrations exactly like the one described above (and including a communication system modeled in a customized version of NS-3) have been completed. Further documentation on installing and setting up FNCS can be found in the code repository.

Table of Contents
 * Previous: Chapter 8 - Built-In Distribution Models