Working on adding examples in the opendss folder

Author: PauloRadatz

1-buses_min_max_v.py

@@ -1,43 +1,69 @@
 # -*- coding: utf-8 -*-
 # @Author  : Paulo Radatz
 # @Email   : [email protected]
-# @File    : 1-buses_min_max_v.py
-# @Software: PyCharm
 
 import py_dss_interface
 import os
 import pathlib
 import numpy as np
 
+# Get the script's current directory
 script_path = os.path.dirname(os.path.abspath(__file__))
 
+# Construct the path to the DSS file within the 'feeders/123Bus' directory
 dss_file = pathlib.Path(script_path).joinpath("feeders", "123Bus", "IEEE123Master.dss")
 
-dss = py_dss_interface.DSS()  # using OpenDSS provided in the package
+# Initialize the OpenDSS interface using the py_dss_interface package
+dss = py_dss_interface.DSS()
+
+# Compile the DSS file for the IEEE 123-bus test feeder to load the circuit into OpenDSS
 dss.text(f"compile [{dss_file}]")
+
+# Load the bus coordinates from the 'buscoords.dat' file for visualization purposes. This file is in 'feeders/123Bus' directory
 dss.text("buscoords buscoords.dat")
+
+# Run the snapshot power flow simulation
 dss.text("solve")
 
+# Retrieve the names of all nodes in the circuit (in "Bus.Node" format)
 nodes = dss.circuit.nodes_names
+
+# Retrieve the per-unit voltage magnitudes for all circuit nodes
 voltages = dss.circuit.buses_vmag_pu
-max_voltage = max(voltages)
-max_voltage_index = voltages.index(max_voltage)
-bus_max_voltages = nodes[max_voltage_index].split(".")[0]
 
-min_voltage = min(voltages)
-min_voltage_index = voltages.index(min_voltage)
-bus_min_voltages = nodes[min_voltage_index].split(".")[0]
+# Find the maximum per-unit voltage and the node associated with it
+max_voltage = max(voltages)  # Determine the maximum voltage
+max_voltage_index = voltages.index(max_voltage)  # Get the index of this maximum voltage
+bus_max_voltages = nodes[max_voltage_index].split(".")[0]  # Extract the bus name (exclude node)
+
+# Find the minimum per-unit voltage and the node associated with it
+min_voltage = min(voltages)  # Determine the minimum voltage
+min_voltage_index = voltages.index(min_voltage)  # Get the index of this minimum voltage
+bus_min_voltages = nodes[min_voltage_index].split(".")[0]  # Extract the bus name (exclude node)
+
+# OPTIONAL (commented): Get the bus name directly using combined code
 # bus_min = dss.circuit.nodes_names[dss.circuit.buses_vmag_pu.index(min(dss.circuit.buses_vmag_pu))].split(".")[0]
 
+# Mark capacitors in the circuit diagram
 dss.text("set markcapacitor=yes")
+
+# Mark regulators in the circuit diagram
 dss.text("set markregulator=yes")
+
+# Add a red marker for the bus with the minimum voltage
 dss.text(f"AddBusMarker Bus={bus_min_voltages} code=7 color=red size=10")
+
+# Add a green marker for the bus with the maximum voltage
 dss.text(f"AddBusMarker Bus={bus_max_voltages} code=7 color=green size=10")
-dss.text("plot circuit Power max=2000 n n C1=$00FF0000")
 
+# Plot the circuit diagram with power flow results
+dss.text("plot circuit Power max=2000 n n C1=$00FF0000")
 
+# Convert the list of voltages and node names into NumPy arrays for efficient processing
 voltages_array = np.array(voltages)
 nodes_array = np.array(nodes)
 
-# Bus.Node with voltage less than 0.98 pu
-buses = nodes_array[voltages_array < 0.98]
+# Apply a filter to identify all nodes where the per-unit voltage is less than 0.98
+# This results in a list of node names (in "Bus.Node" format) with low voltage
+buses = nodes_array[voltages_array < 0.98]
+print(buses)

1-creating_dss_obj.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+# @Author  : Paulo Radatz
+# @Email   : [email protected]
+
+"""
+This script demonstrates how to create the DSS object using either the OpenDSS version (powered by EPRI) included in
+the package or the version installed on your computer.
+
+Watch this video for more information:
+https://www.youtube.com/watch?v=sUZJfwor8xs&list=PLhdRxvt3nJ8xURfBipVoAx8du1a-S5YsL&index=2
+"""
+
+import py_dss_interface
+
+# Instantiating an OpenDSS object using the py_dss_interface.DSS() class.
+# This creates an interface to use OpenDSS functionalities provided by the py_dss_interface package.
+dss = py_dss_interface.DSS()
+
+# Print the status of the OpenDSS interface and its version:
+# - `dss.started` checks whether the OpenDSS interface has been successfully initiated.
+# - `dss.dssinterface.version` returns the version of the OpenDSS executable being used.
+print(f"OpenDSS from Package started: {dss.started} \n"
+      f"Version {dss.dssinterface.version}")
+
+
+# You can use the OpenDSS version installed on your computer by providing the path to the dll_folder_param property.
+# Keep in mind that py-dss-interface has only been tested with the provided OpenDSS version,
+# so using a different version may not be fully compatible.
+dss = py_dss_interface.DSS(r"C:\Program Files\OpenDSS")
+print(f"\nOpenDSS from Computer started: {dss.started} \n"
+      f"Version {dss.dssinterface.version}")

2-futher_3ph_bus.py

@@ -1,34 +1,57 @@
 # -*- coding: utf-8 -*-
 # @Author  : Paulo Radatz
 # @Email   : [email protected]
-# @File    : 2-futher_3ph_bus.py
-# @Software: PyCharm
 
 import py_dss_interface
 import os
 import pathlib
 
+# Get the path of the current script
 script_path = os.path.dirname(os.path.abspath(__file__))
 
+# Path to the distribution feeder file to be used in OpenDSS
 dss_file = pathlib.Path(script_path).joinpath("feeders", "123Bus", "IEEE123Master.dss")
 
-dss = py_dss_interface.DSS()  # using OpenDSS provided in the package
+# Initialize an OpenDSS interface object
+dss = py_dss_interface.DSS()
+
+# Compile the specified OpenDSS model file
 dss.text(f"compile [{dss_file}]")
+
+# Add an energy meter to the feeder to define distances for the buses
 dss.text("New EnergyMeter.Feeder Line.L115 1")
+
+# Load bus coordinate data from an external file
 dss.text("buscoord buscoords.dat")
+
+# Solve the snapshot power flow:
+# the goal is to define the distances for the buses, we could do it using different commands that make the bus list
 dss.text("solve")
 
-bus_dist_actual = 0
-bus_name = None
+# Initialize variables to find the farthest three-phase bus
+bus_dist_actual = 0  # Keeps track of the maximum bus distance
+bus_name = None  # Holds the name of the farthest bus
+
+# Iterate through all bus names in the circuit
 for bus in dss.circuit.buses_names:
+    # Set the current bus as active in OpenDSS
     dss.circuit.set_active_bus(bus)
+
+    # Check if the current bus has at least 3 nodes (indicates a three-phase bus)
     if len(dss.bus.nodes) >= 3:
+        # Get the distance of the current bus
         bus_dist = dss.bus.distance
+
+        # Update the farthest bus if the current bus is farther
         if bus_dist > bus_dist_actual:
             bus_dist_actual = bus_dist
-            bus_name = bus
+            bus_name = bus  # Store the name of the farthest bus
 
+# Print the name of the farthest three-phase bus and its distance
 print(f"Bus: {bus_name} with distance: {bus_dist_actual} is the furthest Three-phase bus")
 
+# Add a bus marker to the farthest three-phase bus in the OpenDSS circuit plot
 dss.text(f"AddBusMarker Bus={bus_name} code=7 color=Red size=10")
+
+# Plot the circuit with the farthest three-phase bus
 dss.text("plot circuit Power max=2000 n n C1=$00FF0000")

2-text_method.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+# @Author  : Paulo Radatz
+# @Email   : [email protected]
+
+"""
+This script demonstrates that anything you can do in OpenDSS standalone can also be done through Python.
+
+Watch this video for more explanation:
+https://www.youtube.com/watch?v=BIMcjZWpJek&list=PLhdRxvt3nJ8w36keL4uGBNbWs5SRxEyW0
+"""
+
+import os
+import pathlib
+import py_dss_interface
+
+# Get the current script's directory path
+script_path = os.path.dirname(os.path.abspath(__file__))
+
+# Construct the full path to the OpenDSS feeder file (IEEE 123-node test feeder)
+# This assumes the `feeders/123Bus/IEEE123Master.dss` file structure is within the same directory containing the script
+dss_file = pathlib.Path(script_path).joinpath("feeders", "123Bus", "IEEE123Master.dss")
+
+# Initialize the DSS interface
+dss = py_dss_interface.DSS()
+
+# Use the OpenDSS Text interface to compile the .dss file.
+# The file path to the DSS model is passed within square brackets.
+dss.text(f"compile [{dss_file}]")
+
+# Set the simulation mode to "Snapshot"
+dss.text("set mode=SnapShot")
+
+# Solve the snapshot power flow for the loaded circuit.
+dss.text("solve")
+
+# Generate and display a report of the line-to-neutral (LN) voltages at each node.
+dss.text("Show Voltage LN Nodes")
+
+# Open up an interactive form to edit a line object named "Line.L1" within the DSS model
+# This allows for visually inspecting or modifying the parameters for the specified line.
+dss.text('FormEdit "Line.L1"')
+
+# Export voltage information to a file and also store the command's return value as a string in the `result` variable.
+result = dss.text("export voltages")  # Text method returns strings. It could be useful.
+

3-max_load_mult.py

@@ -1,34 +1,60 @@
 # -*- coding: utf-8 -*-
 # @Author  : Paulo Radatz
 # @Email   : [email protected]
-# @File    : 3-max_load_mult.py
-# @Software: PyCharm
 
 import py_dss_interface
 import os
 import pathlib
 
+# Getting the absolute directory path of the current script
 script_path = os.path.dirname(os.path.abspath(__file__))
 
+# Building the full path to the IEEE 123-bus feeder model
 dss_file = pathlib.Path(script_path).joinpath("feeders", "123Bus", "IEEE123Master.dss")
 
-dss = py_dss_interface.DSS()  # using OpenDSS provided in the package
+# Instantiating the DSS interface object that allows interaction with OpenDSS
+dss = py_dss_interface.DSS()
 
+# Initializing a flag to track when the voltage drops below the threshold (0.95 per unit)
 under_voltage = False
+
+# Counter for iteration
 i = 0
-while not under_voltage and i < 100:
-    i = i + 1
+load_mult = 1
+
+# Start iterating to find the maximum permissible load multiplier without causing undervoltage
+while not under_voltage and i < 100:  # Stop either when undervoltage is found or after 100 iterations
+    i = i + 1  # Incrementing the iteration counter
+
+    # Calculating the load multiplier as 1 + i/100
     load_mult = 1 + i / 100
+
+    # OpenDSS commands:
+    # Reloading the DSS model
     dss.text(f"compile [{dss_file}]")
+
+    # Creating a new energy meter at Line "L115" in case you want to check the voltage profile commented out below
     dss.text("New EnergyMeter.Feeder Line.L115 1")
+
+    # Setting the load multiplier (scale factor for system loads)
     dss.text(f"set loadmult={load_mult}")
+
+    # Solving the distribution power flow for the current conditions
     dss.text("solve")
 
-    if min(dss.circuit.buses_vmag_pu) < 0.95:
-        under_voltage = True
+    # Plot profile, I would run it in debug mode to plot each profile individually.
+    # dss.text("Plot profile phases=all")
+
+    # Checking the minimum voltage magnitude (in per unit) in all buses of the circuit
+    if min(dss.circuit.buses_vmag_pu) < 0.95:  # If any bus voltage drops below 0.95 pu
+        under_voltage = True  # Set the flag for undervoltage
+
+        # Adjust the load multiplier to the value before the last increment (i.e., the last safe value)
         load_mult = 1 + (i - 1) / 100
 
-if under_voltage:
-    print(f"The max loadmult: {load_mult}")
-else:
-    print(f"No problem with max loadmult of: {load_mult}")
+
+# Once the loop finishes, print the results
+if under_voltage:  # If the loop stopped due to undervoltage
+    print(f"The max loadmult: {load_mult}")  # Print the maximum safe load multiplier
+else:  # If the loop reached 100 iterations without causing undervoltage
+    print(f"No problem with max loadmult of: {load_mult}")

4-line_dataframe.py

@@ -1,43 +1,66 @@
 # -*- coding: utf-8 -*-
 # @Author  : Paulo Radatz
 # @Email   : [email protected]
-# @File    : 4-line_dataframe.py
-# @Software: PyCharm
 
 import py_dss_interface
 import os
 import pathlib
 import pandas as pd
 
+# Get the directory path of the current script
 script_path = os.path.dirname(os.path.abspath(__file__))
 
+# Define the path to the DSS model file
 dss_file = pathlib.Path(script_path).joinpath("feeders", "123Bus", "IEEE123Master.dss")
 
+# Create an instance of the OpenDSS interface
 dss = py_dss_interface.DSS()
-dss.text(f"compile [{dss_file}]")
 
-dss.lines.first()
-line_properties = dss.cktelement.property_names
+# Compile the DSS file to load the model into the OpenDSS engine
+dss.text(f"compile [{dss_file}]")
 
+# Prepare an empty dictionary to store the data we will collect
 dict_to_df = dict()
 
+# Initialize a list to store the names of all the lines in the model
 line_name_list = list()
+
+# Get the first line in the loaded DSS file - it is the first line loaded into the OpenDSS memory
 dss.lines.first()
-for _ in range(dss.lines.count):
-    line_name_list.append(dss.lines.name)
-    dss.lines.next()
+
+# Retrieve the list of property names for the current circuit element
+line_properties = dss.cktelement.property_names
+
+# Loop through all lines in the model to collect their names
+for _ in range(dss.lines.count):  # Loop over the total number of lines
+    line_name_list.append(dss.lines.name)  # Add the current line's name to the list
+    dss.lines.next()  # Move to the next line in the DSS model
+
+# Add the collected line names to the dictionary with the key "name"
 dict_to_df["name"] = line_name_list
 
+# Loop through all the circuit (line) element properties
 for line_property in line_properties:
+    # Prepare a list to store the values of the current property for all lines
     property_list = list()
 
+    # Move to the first line in the DSS model
     dss.lines.first()
-    for _ in range(dss.lines.count):
-        property_list.append(dss.dssproperties.value_read(str(dss.cktelement.property_names.index(line_property) + 1)))
-        dss.lines.next()
 
-    dict_to_df[line_property] = property_list
+    # Loop through all lines in the model to collect the property values
+    for _ in range(dss.lines.count):  # Loop over the total number of lines
+        # Retrieve the value of the current property and add it to the list
+        property_index = str(dss.cktelement.property_names.index(line_property) + 1)  # Property index is 1-based
+        property_list.append(dss.dssproperties.value_read(property_index))
+        dss.lines.next()  # Move to the next line
 
+    # Add the collected property values to the dictionary with the property name as the key
+    dict_to_df[line_property] = property_list
 
+# Convert the dictionary into a Pandas DataFrame and set the line names as the index
 df = pd.DataFrame().from_dict(dict_to_df).set_index("name")
+print(df.head(3))
+
+# Print a message to state that the process is complete.
+# If you liked it, you might find this project interesting "https://github.com/PauloRadatz/py_dss_tools"
 print("This is cool!")