Quick Start

Installation

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.

Installation Verification

After installing the GridLAB-D™ Python API there are a number of ways to verify the installation is working correctly.

1. Import gridlabd using the Python REPL

% python
>>> import gridlabd
>>> 

1. Run one of the API examples in the GridLAB-D™ repository

% cd gridlabd/examples/api/
% python example_sim_start_stop.py
Start time in model: 2023-07-01 00:00:00-07:00
Stop time in model: 2023-07-01 01:00:00-07:00
New start time: 2023-06-30 23:00:00-07:00
New stop time: 2023-07-01 02:00:00-07:00

Note that a number of the API examples that create results graphs using the "matplotlib" library that should show up in a window. If this is not occuring, you'll need to do some work on your installation to correctly configure it for these images to appear. The "example_reading_data.py" script is one such example that you can use to validate this part of your environment.

Running Your Own Model

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 API return codes - Many if not all of the APIs produce a return code instead of erroring out. It is a good idea to check for a returned value of "0" (success) when using the API.
• Check messages - The GridLAB-D™ model produces a variety of console messages ranging in severity from "INFO" to "ERROR"; these messages are generally not terminal. Becuase of this, it is worthwhile to periodically check the messages using get_messages() (and clearing the messages with clear_messages()) to see if the model is behaving correctly. Catching modeling errors via these runtime checks allows you to terminate the simulation early rather than letting it run to completion and then discovering the errors.
• You don't need to set the simulation step size - You can advance simulation time using step() without first calling set_time_step(). Doing so allows GridLAB-D™ to pick its own step size based on the modeled object and will likely lead to faster simulation times (and irregular step sizes). If you want to advance simulation time at regular intervals, use `set_time_step(); otherwise, you don't even need to call it.
• The API is generally data-type aware - The data types used when interacting with the model match the types used by GridLAB-D™. That is, if a GridLAB-D™ model specifies that a value is a complex number, that is the data type returned when using the API to ask for that parameter from the specified object and the data type expected when writing to that parameter via the API.
• The API represents simulation time as an ISO 8601 string - Simulation time is always represented by and ISO 8601 string which is easily converted to a Python datetime object. Working in datetime objects makes time arthimetic much easier and provides a human-meaningful reference for all input and output data.
• Set the GridLAB-D™ working directory - The GridLAB-D™ working directory sets the reference for any relative paths in the model file (say, for a player file) so be sure to set it to an appropriate value so the model and any input files can be loaded correctly.
• TODO - API docs - Verify in final version that the following comment on read-only parameters is correct. Trying to write an object parameter that is read-only via the API will produce a warning.