Quick Start

To install the GridLAB-D™ Python API, use:

PyPI, baby: pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ gridlabd==1.0.13

TODO - API docs - Update the installation command once we have a released version.

Simple Model Run

As a most minimal use case, the following code is all that is required to simply run a GridLAB-D™ model.

In python:

import gridlabd

# Instantiate a GridLAB-D™ engine
gld = gridlabd.GridLabD(verbose=True)

# Load the model
gld.load("model.glm")

# Simulate the model
gld.run()

# Finish up cleanly
gld.exit_gld()

Though this simple example shows no new additional functionality as compared to running the model from the command line, including printing GridLAB-D™ messages to the console.

TODO - Example - can you add a simple line to write console messages to log? If that's an easy lift that's a nice feature show upfront

API Best Practices

TODO - API docs - Add best practices when using the API and link to sections that demonstrate each of them. Github issue #1750

  • Check GridLAB-D™ messages programmatically with .get_messages()
  • Use datetime objects to track simulation time (makes any time math easier)
  • Make checkpoints at judicious times (especially when using house objects that take a few days to initialize) TODO examples - - Waiting for checkpoints to be completed to demonstrate this.
  • Double-check simulation start and stop times
  • Check return codes on API calls to make sure they succeeded (TODO - API docs - Github #1745 requests that developers add these checks in the APIs so users don't have to.)