Getting Started | NLR Distribution Suite

Prerequisites

Before you begin, make sure you have the following installed on your system:

terminal

Python 3.10+

Required runtime for all suite packages.

inventory_2

pip or conda

Package manager for installing dependencies.

code

Git

For cloning repos and version control.

# Verify your setup

$ python --version

Python 3.11.5

$ git --version

git version 2.42.0

Install Grid Data Models

Grid Data Models (GDM) provides the standardized schemas that every other tool in the suite depends on. It defines the vocabulary for lines, transformers, loads, and all other distribution assets.

# Install from PyPI

$ pip install grid-data-models

# Or clone for development

$ git clone https://github.com/NLR-Distribution-Suite/grid-data-models.git

$ cd grid-data-models

$ pip install -e ".[dev]"

lightbulb

Tip

Check out the GDM Tutorial repo for interactive Jupyter notebooks that walk you through every model type.

Build Your First Model

Create a simple distribution system model using GDM's Pydantic-based schemas. Every model is fully validated and serializable out of the box.

# Create a distribution bus

from gdm import DistributionBus, DistributionSubstation, DistributionFeeder

from gdm.distribution.enums import VoltageTypes, Phase

from gdm.quantities import Voltage

# Define a bus

bus = DistributionBus(

    name="bus_001",

    voltage_type=VoltageTypes.LINE_TO_LINE,

    phases=[Phase.A, Phase.B, Phase.C],

    rated_voltage=Voltage(12.47, "kilovolt"),

    substation=DistributionSubstation.example(),

    feeder=DistributionFeeder.example(),

)

# Serialize to JSON

print(bus.model_dump_json(indent=2))

info

GDM models are built on Pydantic v2 with pint-based quantities for unit conversion. You get automatic validation, serialization, and IDE autocompletion for every field.

Build a Feeder with SHIFT

SHIFT is a Python framework for building synthetic distribution feeder models from open-source geospatial data. It fetches building parcels and road networks from OpenStreetMap, constructs graph-based network topologies, and exports simulator-ready models through Grid Data Models and DiTTo.

# Install SHIFT from PyPI

$ pip install nrel-shift

# Or from source

$ git clone https://github.com/NLR-Distribution-Suite/shift.git

$ cd shift

$ pip install -e ".[dev]"

# Build a synthetic feeder from geospatial data

from shift import parcels_from_location, get_road_network

from gdm.quantities import Distance

# Fetch building parcels from OpenStreetMap

parcels = parcels_from_location("Fort Worth, TX", Distance(500, "m"))

# Fetch the road network for the same area

road_network = get_road_network("Fort Worth, TX", Distance(500, "m"))

speed

Features

SHIFT includes automated feeder generation, graph-based network modeling, equipment mapping, phase balancing, voltage mapping, and built-in Plotly visualization.

Convert Models with DiTTo

DiTTo (Distribution Transformation Tool) converts between distribution model formats — OpenDSS, CIM, CYME, Synergi, and more. It's the Rosetta Stone for grid data.

# Install DiTTo from source

$ git clone https://github.com/NLR-Distribution-Suite/ditto.git

$ cd ditto

$ pip install -e .

# Convert a CIM model to OpenDSS format

from pathlib import Path

from ditto.readers.cim_iec_61968_13.reader import Reader

from ditto.writers.opendss.write import Writer

cim_reader = Reader(ieee13_node_xml_file)

cim_reader.read()

system = cim_reader.get_system()

writer = Writer(system)

output_path = Path("./output")

writer.write(output_path=output_path, separate_substations=False, separate_feeders=False)

OpenDSS

CIM

CYME

Synergi

Connect AI Agents

The suite is designed to work with AI agents through the Model Context Protocol (MCP). This enables LLMs like Claude or GPT to interact with your grid data and simulations using natural language.

AI Agent Session — Connected via MCP

YOU

"Build a distribution feeder model for Fort Worth, TX and export it to OpenDSS format."

Fetching parcels and road network via SHIFT...

Building distribution graph and mapping equipment via GDM...

Exporting to OpenDSS via DiTTo...

Complete. Generated a 47-bus distribution feeder model. OpenDSS files saved to ./output/.

# Install GridAI — the MCP bridge

$ git clone https://github.com/NLR-Distribution-Suite/gridai.git

$ cd gridai

$ pip install -e ".[dev]"

auto_awesome

What is MCP?

The Model Context Protocol is a standard that lets AI models "see" structured data. Think of it as giving your LLM X-ray vision into your grid models, simulation results, and engineering workflows.

Set up your environment in minutes.

On This Page