🎯 Objective

Demonstrate how to link an OpenDSS instance (created with py-dss-interface) to py-dss-toolkit's dss_tools so you can control OpenDSS via Python.

🧠 Key Concepts

• Linking a DSS instance to dss_tools

• py-dss-interface usage

• py-dss-toolkit model and results

• Portable DSS master file path construction

• Exporting OpenDSS data to pandas DataFrames

📜 Transcript Summary

In this tutorial Paulo Radatz walks through creating a Python script that links a DSS object (via py-dss-interface) to the dss_tools provided by py-dss-toolkit, using the IEEE 123-bus master file as an example. He demonstrates building a portable file path to the OpenDSS master, instantiating py_dss_interface.DSS, calling dss_tools.update_dss with that instance, compiling the master file in OpenDSS, and using dss_tools.model.loads_df to get load data as a pandas DataFrame. The video emphasizes the abstraction and convenience py-dss-toolkit provides compared to directly calling the interface, points learners to additional courses and resources on his Website: pauloradatz.me, and is focused on Topics: distribution systems, OpenDSS, and Python.

💬 Suggested LLM Prompts

• Show me a minimal Python example that builds a portable path to an OpenDSS master and instantiates py_dss_interface.DSS, then links it to py-dss-toolkit dss_tools.

• What's the difference between querying OpenDSS directly with py-dss-interface and using py-dss-toolkit's dss_tools.model.(functions to get data as pandas DataFrames)?

• How do I compile an OpenDSS master file from Python and convert the system loads into a DataFrame for analysis?

📖 Table of Contents

• Introduction and objectives

• Locating the IEEE 123-bus feeder

• Creating the Python script file

• Imports: py-dss-interface and py-dss-toolkit

• Constructing a portable DSS master file path

• Creating the DSS instance (py_dss_interface.dss)

• Linking the DSS instance to dss_tools (update_dss)

• Compiling the master file in OpenDSS

• Inspecting objects via py-dss-interface

• Using py-dss-toolkit to produce pandas DataFrames (loads_df)

• Abstraction and source-code note

• Conclusion and next steps

📚 Glossary

• py-dss-interface: A Python interface used to create and control a DSS object that communicates directly with OpenDSS.

• py-dss-toolkit: A higher-level Python package that builds on the DSS interface to provide convenient model, results, and utility functions, often returning pandas DataFrames.

• OpenDSS master file: The primary script file (usually named master.dss) that defines the components and simulation commands for an OpenDSS feeder model.

🐍 Python Code Examples

import os
import pathlib
import py_dss_interface

from py_dss_toolkit import dss_tools

script_path = os.path.dirname(os.path.abspath(__file__))

dss_file = pathlib.Path(script_path).joinpath("123Bus", "IEEE123Master.dss")

dss = py_dss_interface.DSS()

dss_tools.update_dss(dss)

dss.text(f"compile [{dss_file}]")
dss.text("solve")
dss.text("show voltages ln nodes")

lines = dss_tools.model.lines_df

🕒 Full Transcript

Introduction (00:00:00)

Hi everyone, it's Paulo Radatz and this is the third video of our py-dss-toolkit tutorial. In this video, we're going to talk about how to link the DSS instance into our dss_tools. I'll show you that process because this is the foundation for us to be able to leverage the advanced capabilities we have in py-dss-toolkit.

Locating the feeder test files (00:00:26)

So for that, let me first get my feeder test that we're going to use. So I'm going to go to Program Files and then go to my OpenDSS folder. You only have this folder when you download OpenDSS. And then here I have IEEE. Let me get here 123 bus. So that's great. Come back to C and then Paulo. And then here I'm going to have the toolkit. Maybe here what I'm going to do is just pass this guy here, right? 123 bus so I can have access to it. Perfect.

Creating the Python script (00:01:15)

Now, what I'm going to also do, I'm going to create a new Python file. So here I'll call two and then I'll call it, say here, dss_tools. Okay, that's what I'm going to call it.

Imports and purpose (00:01:31)

First thing I'm going to do, I'm going to import py-dss-interface, actually DSS interface. And I want from the py-dss-toolkit, I want to use dss_tools. This is one way to use py-dss-toolkit. And that's really what I want to focus here with you guys in the following videos. Maybe later I'll show you another approach, which is a little bit different. But at the end of the day, we'll be kind of having the same functionality. So here I would say from, okay, from py-dss-toolkit I want to import only the dss_tools. Okay, so I have two imports. One is the py-dss-interface, which is really what we need to use to control OpenDSS. But also I'm using dss_tools. I'm importing tools from py-dss-toolkit to give me more functionalities.

Additional imports and preparing code snippets (00:02:33)

Okay, so now I'm going to just grab a few codes here that I have so we don't take a lot of time. So let me grab two codes here. One line here, let me import the other things I also need. I need to be able to do what I'm doing here. I'll show you, I'll explain the reason. Import os and import pathlib.

Okay, so here's what I'm doing. You see that I have two lines of code. And the idea is to create DSS file, okay, which will be a string pointing to the master file of OpenDSS. So the first thing I do, I have a line that gets the current path of this file, this Python file that I'm using, dss_tools. And then I just build on top of that another file so I can delete this. So from the folder or the directory we have our dss_tools. I want then get into 123 bus and then I will go into the master, okay. So master is this guy we need to run, right? So here is what I'm doing from that folder, get into 123 bus and then run the master.

Debugging and inspecting the DSS file path (00:03:51)

So if I go here and just let me stop in debug mode. Stop here, right click, right click. You see here debug to dss_tools. Let's stop there. You're going to see in one second that I have my DSS file. You can see the variable here, but here's the variable. You see it's a path. In my case, Windows, I'm using Windows. But if you're using other, you know, operating system, you're going to see maybe Linux path here. But here's where I have my master, right? See Paulo Radatz's tutorial, 123 and master.

So why I add those two lines? It's because if you have a different folder that you are working, my script, it will still work for you because selecting the DSS file path is based on your location, your own file. So I like to have those lines instead of just, you know, I could come here. For instance, I'll show you what I mean. I could come here and then I go here. Where's the master here? Then I hold shift, right click and then I copy this path and then it could go to my code and then replace it, right? Maybe R and then control V. And then this is the, you know, the exact location. But then if you run it, you're going to have problems because you don't have this folder probably, right? You don't have my name in there. So this gives us that flexibility.

Creating a DSS instance (00:05:21)

The next thing I want to do, I want to create a DSS instance or a DSS object. So pretty much here, I'm going to do py-dss-interface.dss. So again, there are a bunch of concepts and things you can learn when using DSS. And I do recommend that if you are willing to learn more about it, to go to my website pauloradatz.me, open the link, you know, I'll put the link below. There's this py-dss-interface course that covers very well how you work with py-dss-interface. There are also two other courses, the snapshot, which gives you the basics and also how to run snapshot simulations and also the time series. But again, back to my code. So if you want to learn more about it, I do recommend you to really, you know, watch that, follow that course.

Updating dss_tools with the DSS object (00:06:16)

So the next step we need to do as soon as we have the DSS, you're going to see, you know, DSS, meters, monitors. We have a bunch of things we can have here, right? And those are like just meant to communicate or talk to OpenDSS, right? Just the interface. That's the reason of the name. But then what I can do, I can say dss_tools. Okay. And then here I have a bunch of functionalities, but the first one is really update DSS. Okay. And then what I just do here, I just pass my DSS that I just created. Now I can control OpenDSS using the DSS, you know, the interface, or I can control OpenDSS through the tools.

Compiling the master file and inspecting objects (00:07:06)

So I'll give you one example here. Let me start with my 123 bus here. Let's just run this guy. Let me just put the code here. I can start by saying dss.text, right? And then I can do app, compile, and then correct. And then here. Okay. And then I do DSS file. So this command is asking OpenDSS to compile this file, right? And then what I can do here, you know, I'll stop here in debug mode so you can see a little bit more. So now I could come here, right? And then, you know, three dots, three dots, and then evaluate expression, say dss.loads, right? And then maybe you can see here load names. Okay. Maybe do I have names? I believe we have. So it's going to return me something. OpenDSS, hey, I want to know the names of the loads. And then it's going to give you a list of it, right? Okay. It's nice.

Using dss_tools to extract models and data frames (00:08:20)

But also now, since you have the dss_tools capabilities, we have a bunch of easy ways to access data. We're going to cover models, results, you know, we're going to talk about the interactive view, simulation, things like that. But just for you to understand what I'm trying to convey here and show you how good the package is, I could go model, right? DSS model. And maybe here, load state to frame. Okay. Before I used py-dss-interface to get the load names, but now I'm using the tools that provides me a bunch of capabilities, right? This is the guy. This is the guy. Okay. And now if I evaluate it, you're going to see I have a data frame. It has the names and the properties. Then now it's data, okay? And I can work with, you know, just pandas, the data frame code to kind of parse and select and do things, right? It's pretty easy now because it's just now Python. I don't need to talk to OpenDSS anymore if I'm interested in, you know, more about the loads of the system.

Abstraction and design of the toolkit (00:09:31)

And another thing I want to show you is that this structure is actually hiding. If you go to the source code, this is the source code, right? This is load state frame. So it's hiding a lot of code from you guys. It's creating this abstraction. So I developed this in a way that I wanted to make sure that for you, it's really easy to use. It's just like, oh, loads data frame. It's going to be dss_tools. It's going to be model and then loads data frame, right? So you don't need to do all the work I did because I did it for you.

Conclusion and next video (00:10:12)

All right, so I think this is what I wanted to show you. This video is only meant to show you how you connect those two guys, right? That's the way. And then you have the capabilities available for you. And then in the next video, we're going to explore the capabilities itself. So we're going to see results, data frames, what we mean by those guys, and then they'll be very, very fun, I guess. So I hope you are enjoying this tutorial. Leave comments if you have anything in mind. Don't forget to subscribe to my channel and leave the thumbs up. Thanks so much and see you in the next video.