GridLAB-D Wiki:GridLAB-D Tutorial Chapter 1 - Installing GridLAB-D

Table of Contents
 * Next: Chapter 2 - GridLAB-D Key Attributes

So, we start at the beginning and for GridLAB-D the beginning is getting the software up and running on your computer. As with many open source projects, there are two basic options for doing so: using a traditional installer or compiling the software yourself. We’ll look at both methods.

Using the Installer
Assuming you’re on one of the supported platforms for GridLAB-D, using the installer of the latest version is by far the easiest method. Head to the GridLAB-D code repository and right there at the top of the screen should be a green button which will download the installer for your platform. (If you are downloading the installer for a platform different than the one that you're currently using, click on the “Browse all files”, “Gridlab-D”, “last stable version” and choose the appropriate installer.)



Once the installer has been downloaded, launch it and walk through the process of installing the software as you would for any other commercial software.

Even if you never plan on building or modifying the source code, it can be very helpful to have a copy readily available to consult if you need to understand the details of how a particular portion of GridLAB-D is operating. For this reason, it is suggested (perhaps even recommeneded) that you download a copy of the source code for the version of GridLAB-D just installed. Head to the GridLAB-D code repository and click the link of the appropriate version. Towards the top of the page should be a link to “Download Snapshot”.



This will create a .zip file with the source code which you can save somewhere for reference. Of course, if you want to go the full-nerd route and build the software locally, read on.

Building from Source
There are a couple reasons that building/compiling the software directly from the source code might be the route you need to go:
 * You are running on a platform for which GridLAB-D doesn’t have an installer.
 * You want a newer version than the latest stable release (maybe it has a new feature you want to try)
 * You plan on modifying or extending the existing code and will need to build your custom version anyway.

Fortunately, instructions on how to download and build the software are provided. If you are building 4.0 in windows please seeMinGW/Eclipse Installation guide if you are building version 4.1 of GridLAB-D please see the Building GridLAB-D on Windows with MSYS2. Regardless of the version of GridLAB-D you are building please see our Installation Guide (for Linux and OS X). If you head this route it is assumed you have an understanding and familiarity with how software is typically built and can handle things like version control and environmental variables. If these are new concepts to you, fear not; the internet is full of helpful information that will help you get up to speed, it will just take a bit more time and effort.

Installation Validation
Assuming you’ve been able to get the software installed and all appears well a good next step is to validate that this is the case. The easiest and most basic way is to ask GridLAB-D to tell you about itself. From your console/command-line/terminal type:

gridlabd --version

You should get a one-line response showing which version of the software you’ve installed including the secret version codename and platform on which it will run. If the response is anything else, it is likely an indication that GridLAB-D is either not installed or fully configured.

Getting Help with GridLAB-D
At some point, there will likely be a situation where something with GridLAB-D is not working as expected. Maybe your installation has failed, maybe a model file is throwing an error and it is unclear why, or maybe you’re trying to use a new type of object in your model and you’re unsure what the available parameters are. There are a number of avenues or getting help with GridLAB-D.


 * Source Code - The most authoritative answer to how GridLAB-D works is the source code for the version you have installed. Every definition, function, and parameter is documented somewhere in the code and GridLAB-D will function as dictated by the code; that’s what software does. That said, there is a lot of source code, it has been written by many people over many years and trying to understand such a large project will likely be slow-going, particularly at first. This tutorial will hopefully help you gain some familiarity and courage in confronting the source code but typically, for most people, this will not be the first place to consult for an answer.
 * Help:Contents The GridLAB-D wiki is a fairly detailed and comprehensive body of online documentation for GridLAB-D. Much of the inner working of GridLAB-D are exposed here and are presented in a much more human-friendly form (as compared to the source code, at least). Most of the classes have mostly comprehensive parameter lists and many of the governing equations for those classes/models are spelled out. This makes a good first place to look for help on understanding about how a particular object should be implemented. The wiki also serves as a sort of public scratch-board for the developers where proposed ideas and ideas that have been abandoned are intermingled with the documentation for existing classes and modules. It can be out of date, potentially mis-leading, and somewhat poorly organized; it can be hard to feel confident that the information you’re looking at is not superseded or supplemented by information elsewhere on the site. For this reason it is hard to consider the wiki authoritative (again, at least compared to the source code) but it often provide accurate information very quickly.
 * GridLAB-D Forums - GridLAB-D has an online user support forum that is fairly active. Many of the GridLAB-D developers are the ones providing answers and specific problems that are not clearly addressed in the wiki or seem unique to your particular model can be addressed here. Searching the forum can also be very useful as other users may have had similar problems in the past and the answers they received may be helpful to you. Keep in mind that the forums are not necessarily the fastest way to get help, though, and creating a new topic for discussion should never be your first tactic to solving your problem.
 * Existing models Examples are always a good way to understand how something is supposed to work and at the end of this user's guide is a list of all the included distribution system models that may include an implementation of an item of particular interest.
 * Training Materials
 * This user's guide; keep reading!
 * GridLAB-D wiki pages - These two pages provide earlier attempts to help new user's getting started in GridLAB-D. They are written from a different perspective by different authors, they may be useful in helping fill-out your understanding of how GridLAB-D works.
 * Getting Started Using GridLAB-D - Focused on terminology, conventions, and how GridLAB-D models work.
 * Beginner's Guide to GridLAB-D - Primarily discusses the residential class which is also covered in this tutorial as a part of the discussion of loads in general.
 * [GridLAB-D training classes - Throughout the history of GridLAB-D, the developers have periodically provided in-person and on-line training. These training sessions have been documented, mostly in the form of presentation slides and worked examples and can be found as a part of the official GridLAB-D distribution.
 * Training videos - Several years and versions ago, two of the GridLAB-D developers gave a training session with a video recording. These videos are available for download and serve as an excellent and detailed exploration of the core features of GridLAB-D. Be warned, the videos tend to be long and noting the timestamps of interesting bits is recommended.

Table of Contents
 * Next: Chapter 2 - GridLAB-D Key Attributes