### Install OpenDSSDirect.py with pip

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/README.md

Use this command to install the package with the recommended extras. It is the primary installation method for users with a Python environment.

```bash
pip install 'OpenDSSDirect.py[extras]'
```

--------------------------------

### Install editable OpenDSSDirect.py with extras and dev

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Installation.ipynb

Installs an editable version of OpenDSSDirect.py with extras and dev dependencies for development.

```bash
pip install -e '.[extras,dev]' --upgrade
```

--------------------------------

### Install minimal OpenDSSDirect.py without extras

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Installation.ipynb

Minimal installation that depends only on DSS-Python, useful for restricted environments where optional dependencies like pandas cannot be installed via pip.

```bash
pip install OpenDSSDirect.py
```

--------------------------------

### Install package and download sample circuits

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Sets up the environment for the notebook: installs opendssdirect.py[extras] when running on Colab, downloads the electricdss-tst repository snapshot, and defines the path to the IEEE 13-bus test circuit. The assertion verifies the file exists before proceeding.

```python
import os, subprocess
if os.getenv("COLAB_RELEASE_TAG"):
    print(subprocess.check_output('pip install opendssdirect.py[extras]', shell=True).decode())

# Download the sample circuits and test cases if they do not exist already
from dss.examples import download_repo_snapshot
REPO_PATH = download_repo_snapshot('.', repo_name='electricdss-tst', use_version=False)
IEEE13_PATH = REPO_PATH / 'Version8/Distrib/IEEETestCases/13Bus/IEEE13Nodeckt.dss'
assert IEEE13_PATH.exists()
```

--------------------------------

### Install OpenDSSDirect.py with extras on Windows using double quotes

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Installation.ipynb

Windows alternative to the extras installation when single quotes cause an error; uses double quotes around the package specifier.

```shell
pip install "OpenDSSDirect.py[extras]"
```

--------------------------------

### Port COM example to OpenDSSDirect.py

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Fully ported version of the COM example to OpenDSSDirect.py. It uses function-call syntax (e.g., dss.Loads.Name("675c")) instead of property assignment. The commented line shows an alternative using dss.Text.Command with a relative path.

```python
# Load OpenDSS
from opendssdirect import dss

# Run a DSS script to load a circuit
dss('Redirect "../../tests/data/13Bus/IEEE13Nodeckt.dss"')
# or dss.Text.Command('Redirect "./../../tests/data/13Bus/IEEE13Nodeckt.dss"')

# Select a load and update its kW
dss.Loads.Name("675c")
dss.Loads.kW(320)

# Solve
dss.Solution.Solve()

# Get the voltage magnitudes
voltages = dss.Circuit.AllBusVMag()
```

--------------------------------

### Print save directory

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Prints the target directory for the folder save example.

```python
print('Saving to', str(REPO_PATH / 'save_dir'))
```

--------------------------------

### Install editable OpenDSSDirect.py with escaped brackets

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Installation.ipynb

Escaped version of the editable install command for shells that require escaping brackets.

```bash
pip install -e '.\[extras,dev\]' --upgrade
```

--------------------------------

### Import required modules

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Imports required for the examples: DSSSaveFlags, the opendssdirect module, and display utilities.

```python
from dss import DSSSaveFlags
from opendssdirect import dss as odd
from IPython.display import display, Markdown
from textwrap import dedent
```

--------------------------------

### Get load data as DataFrame with dss.utils.loads_to_dataframe()

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Returns a pandas DataFrame with all load data from the current OpenDSS circuit. The output includes columns such as Idx, Phases, Class, Model, NumCust, IsDelta, Rneut, Xneut, PF, ZipV, kV, kW, kVABase, kvar, kWh, kWhDays, AllocationFactor, XfkVA, puSeriesRL, and Sensor. The example output shows 15 rows and 37 columns.

```python
dss.utils.loads_to_dataframe()
```

```text
Result:
     Idx Phases Class Model NumCust IsDelta Rneut Xneut        PF   
671    1      3     1     1       1    True  -1.0   0.0  0.868243  \
634a   2      1     1     1       1   False  -1.0   0.0  0.824042   
634b   3      1     1     1       1   False  -1.0   0.0       0.8   
634c   4      1     1     1       1   False  -1.0   0.0       0.8   
645    5      1     1     1       1   False  -1.0   0.0  0.805651   
646    6      1     1     2       1    True  -1.0   0.0  0.867313   
692    7      1     1     5       1    True  -1.0   0.0  0.747652   
675a   8      1     1     1       1   False  -1.0   0.0  0.931101   
675b   9      1     1     1       1   False  -1.0   0.0  0.749838   
675c  10      1     1     1       1   False  -1.0   0.0  0.807289   
611   11      1     1     5       1   False  -1.0   0.0  0.904819   
652   12      1     1     2       1   False  -1.0   0.0   0.83005   
670a  13      1     1     1       1   False  -1.0   0.0  0.861934   
670b  14      1     1     1       1   False  -1.0   0.0  0.866622   
670c  15      1     1     1       1   False  -1.0   0.0  0.864582   

                                     ZipV  ...     kV      kW      kVABase   
671   [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...   4.16  1155.0  1330.272528  \
634a  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...  0.277   160.0   194.164878   
634b  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...  0.277   120.0        150.0   
634c  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...  0.277   120.0        150.0   
645   [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4   170.0   211.009478   
646   [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...   4.16   230.0   265.186727   
692   [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...   4.16   170.0   227.378539   
675a  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4   485.0   520.888664   
675b  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4    68.0    90.686272   
675c  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4   290.0   359.226948   
611   [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4   170.0   187.882942   
652   [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4   128.0   154.207652   
670a  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4    17.0    19.723083   
670b  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4    66.0    76.157731   
670c  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]  ...    2.4   117.0   135.325533   

       kvar  kWh kWhDays AllocationFactor XfkVA puSeriesRL Sensor  
671   660.0  0.0    30.0              0.5   0.0       50.0         
634a  110.0  0.0    30.0              0.5   0.0       50.0         
634b   90.0  0.0    30.0              0.5   0.0       50.0         
634c   90.0  0.0    30.0              0.5   0.0       50.0         
645   125.0  0.0    30.0              0.5   0.0       50.0         
646   132.0  0.0    30.0              0.5   0.0       50.0         
692   151.0  0.0    30.0              0.5   0.0       50.0         
675a  190.0  0.0    30.0              0.5   0.0       50.0         
675b   60.0  0.0    30.0              0.5   0.0       50.0         
675c  212.0  0.0    30.0              0.5   0.0       50.0         
611    80.0  0.0    30.0              0.5   0.0       50.0         
652    86.0  0.0    30.0              0.5   0.0       50.0         
670a   10.0  0.0    30.0              0.5   0.0       50.0         
670b   38.0  0.0    30.0              0.5   0.0       50.0         
670c   68.0  0.0    30.0              0.5   0.0       50.0         

[15 rows x 37 columns]
```

--------------------------------

### Run threads and measure time

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Multithreading.ipynb

Creates and starts a thread for each context, joins them, asserts all converged, and prints the elapsed time.

```python
t0 = perf_counter()
threads = []
for ctx in ctxs:
    t = threading.Thread(target=_run, args=(ctx, cases_to_run_threads, tconverged, tresults))
    threads.append(t)

for t in threads:
    t.start()

for t in threads:
    t.join()

t1 = perf_counter()

# Check if all solutions converged
assert all(tconverged.values())

dt_thread = (t1 - t0)
print(f'Done in {dt_thread:.3f} s with {num} threads')
```

```text
Output:
Done in 0.488 s with 24 threads
```

--------------------------------

### Upgrade OpenDSSDirect.py with extras

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Installation.ipynb

Upgrades an existing OpenDSSDirect.py installation to the latest version with extras.

```bash
pip install 'OpenDSSDirect.py[extras]' --upgrade
```

--------------------------------

### Run a DSS Command with dss.Command

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Execute a single DSS command using `dss.Command`. This is the recommended method over `dss.run_command` due to clearer error checking. The example redirects to a test circuit file.

```python
dss.Command('Redirect "../../tests/data/13Bus/IEEE13Nodeckt.dss"')
```

--------------------------------

### Example output from pandas interface for transformers

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Example output from the pandas interface showing transformer data as a DataFrame with columns like Idx, XfmrCode, IsDelta, CoreType, NumWindings, Wdg, NumTaps, MinTap, MaxTap, Tap, R, Xhl, Xht, Xlt, Rneut, Xneut, RdcOhms, WdgCurrents, WdgVoltages, and LossesByType. The output is truncated with ellipses for list columns and shows 5 rows and 22 columns.

```text
Result:
     Idx XfmrCode IsDelta CoreType NumWindings Wdg NumTaps MinTap MaxTap   
sub    1            False        0           2   2      32    0.9    1.1  \
reg1   2            False        0           2   2      32    0.9    1.1   
reg2   3            False        0           2   2      32    0.9    1.1   
reg3   4            False        0           2   2      32    0.9    1.1   
xfm1   5            False        0           2   2      32    0.9    1.1   

          Tap  ...       R    Xhl   Xht   Xlt Rneut Xneut   RdcOhms   
sub       1.0  ...  0.0005  0.008   4.0   4.0  -1.0   0.0  0.000005  \
reg1  1.05625  ...   0.005   0.01  35.0  30.0  -1.0   0.0  0.000147   
reg2   1.0375  ...   0.005   0.01  35.0  30.0  -1.0   0.0  0.000147   
reg3  1.05625  ...   0.005   0.01  35.0  30.0  -1.0   0.0  0.000147   
xfm1      1.0  ...    0.55    2.0   1.0   1.0  -1.0   0.0  0.000718   

                                            WdgCurrents   
sub   [10.886838403101137, -5.9590983105881605, -10....  \
reg1  [521.2749200067483, -285.3283304735087, -521.2...   
reg2  [-339.30622841604054, -271.7993979600724, 339....   
reg3  [-36.93235703278333, 623.9901740467176, 36.932...   
xfm1  [64.7216815965744, -50.18299905784306, -64.721...   

                                            WdgVoltages   
sub   [2401.562774320432, -0.46690091155609226, -120...  \
reg1           [2536.356120228099, -0.5793286234950956]   
reg2         [-1246.2598772664523, -2157.4877137350218]   
reg3           [-1267.5877694598496, 2196.935539327288]   
xfm1  [273.1208520924334, -15.653268696155022, -149....   

                                           LossesByType  
sub   [32.28780525899492, 262.4687364427373, 32.2878...  
reg1  [122.09388323919848, 123.85831108468119, 122.0...  
reg2  [65.34575459547341, 67.07771651400253, 65.3457...  
reg3  [135.08947523473762, 136.85396666557062, 135.0...  
xfm1  [5552.6587844858295, 10096.246342088038, 5552....  

[5 rows x 22 columns]
```

--------------------------------

### Enable NumPy array returns with OpenDSSDirect(prefer_lists=False)

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/updating_to_0.9.md

Demonstrates how to enable NumPy array returns per instance by passing prefer_lists=False to the OpenDSSDirect constructor. The constructor always binds to the default DSS engine. The example also shows that prefer_lists=True returns plain lists.

```python
from opendssdirect.OpenDSSDirect import OpenDSSDirect
from numpy import ndarray

# NOTE: this constructors ALWAYS binds to the default DSS engine.
odd_np = OpenDSSDirect(prefer_lists=False)
# Use it normally
odd_np(f"Redirect '{PATH_TO_DSS}'")
assert isinstance(odd_np.Circuit.AllBusMagPu(), ndarray)

odd_lst = OpenDSSDirect(prefer_lists=True)
# Same global instance, we can just reuse the result
assert isinstance(odd_lst.Circuit.AllBusMagPu(), list)
```

--------------------------------

### List comprehension for kW values

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Uses a list comprehension to get all kW values from the loads. The result is a list of floats.

```python
[l.kW() for l in dss.Loads]
```

--------------------------------

### Redirect circuit using low-level Text_Set_Command

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Use this snippet to redirect a circuit file via the low-level API. Note that error checking is the user's responsibility, and the command string must be encoded. The example triggers a NameError because 'dss' is not defined in the context.

```python
dss.dss_lib.Text_Set_Command('Redirect ./../../tests/data/13Bus/IEEE13Nodeckt.dss'.encode())
```

```text
Error (truncated):
----> 1 dss.dss_lib.Text_Set_Command('Redirect ./../../tests/data/13Bus/IEEE13Nodeckt.dss'.encode())



NameError: name 'dss' is not defined
```

--------------------------------

### Get dense SystemY matrix (compatibility)

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/SystemY.ipynb

Returns the full dense System Y matrix. Not recommended for large circuits because it is memory intensive. Provided for compatibility with the official OpenDSS COM implementation.

```python
dss.Circuit.SystemY() # avoid, this is a dense matrix (memory intensive)
```

--------------------------------

### Plot sparsity pattern with matplotlib spy

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/SystemY.ipynb

Plots the sparsity pattern of the systemY matrix using matplotlib.pyplot.spy. Requires matplotlib to be installed.

```python
from matplotlib import pyplot as plt
plt.spy(systemY)
```

--------------------------------

### Time native iteration for kW values

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Times the native Python iteration approach to get kW values. The output shows the timing result.

```python
%timeit load_kW = [l.kW() for l in dss.Loads]
```

--------------------------------

### Original COM API code with win32com

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Original code written for the official OpenDSS COM API using win32com. It loads a circuit via dss.Text.Command, selects a load by name, sets its kW, solves, and reads voltage magnitudes. This is the starting point for migrating to OpenDSSDirect.py or DSS-Python.

```python
# Load OpenDSS
import win32com.client
dss = win32com.client.Dispatch('OpenDSSengine.DSS')

# Run a DSS script to load a circuit
# (NOTE: typically you would use either the full path here since the official OpenDSS implementation changes the current working directory of the process)
dss.Text.Command = 'Redirect "../../tests/data/13Bus/IEEE13Nodeckt.dss"'

# Select a load and update its kW
dss.ActiveCircuit.Loads.Name = "675c"
dss.ActiveCircuit.Loads.kW = 320

# Solve
dss.ActiveCircuit.Solution.Solve()

# Get the voltage magnitudes
voltages = dss.ActiveCircuit.AllBusVmag
```

--------------------------------

### Get Loads.kW property value

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Calls dss.Loads.kW() with no arguments to get the current value of the kW property for the active load. The output shows the value 120.0.

```python
dss.Loads.kW()
```

--------------------------------

### Import OpenDSSDirect and print versions

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Import the dss instance and print the version information for the engine and the package.

```python
from opendssdirect import dss
```

```python
print('OpenDSSDirect.py and engine versions:', dss.Version())
```

```text
Output:
OpenDSSDirect.py and engine versions: DSS C-API Library version DEV revision UNKNOWN based on OpenDSS SVN UNKNOWN [FPC 3.2.2] (64-bit build) MVMULT INCREMENTAL_Y CONTEXT_API PM 20240206090705; License Status: Open 
DSS-Python version: 0.0dev
OpenDSSDirect.py version: 0.0dev
```

--------------------------------

### Compare voltage magnitudes from both APIs

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Shows how to use OpenDSSDirect.py after obtaining the DSS-Python instance, and verifies that the voltage magnitudes from both APIs are equal. The output is True.

```python
# Get the voltage magnitudes using OpenDSSDirect.py
voltages2 = odd.Circuit.AllBusVMag()

list(voltages) == list(voltages2)
```

```text
Result:
True
```

--------------------------------

### Load a circuit with redirect

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Loads a circuit using the redirect command. Required before saving.

```python
# Don't forget to load a circuit first:
odd(f'redirect "{IEEE13_PATH}"')
```

--------------------------------

### Import matplotlib.pyplot

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/VoltageProfilePlot.ipynb

Imports matplotlib.pyplot for creating the voltage profile plot.

```python
import matplotlib.pyplot as plt
```

--------------------------------

### Create and use multiple DSS contexts with NewContext()

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/updating_to_0.9.md

Shows how to create and use multiple DSS engine contexts. It disables changing the working directory, creates two contexts, runs commands on each, and verifies the active circuit names.

```python
from opendssdirect import dss as odd_default

# When using multiple contexts, it's better avoid changing the 
# working directory of the process
odd_default.Basic.AllowChangeDir(False)

odd1 = odd_default.NewContext()
odd2 = odd_default.NewContext()

odd1('new circuit.circuit1')
odd2('new circuit.circuit2')

assert odd1.Circuit.Name() == 'circuit1'
assert odd2.Circuit.Name() == 'circuit2'
```

--------------------------------

### Time Iterator usage

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Times the Iterator approach to get kW values. The output shows a DeprecationWarning and the timing result.

```python
%timeit load_kW = [i() for i in Iterator(dss.Loads, 'kW')]
```

--------------------------------

### Get sparse Y matrix with scipy.sparse

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/SystemY.ipynb

Constructs a sparse CSC matrix from the system Y matrix. This is the preferred method for large circuits.

```python
from scipy.sparse import csc_matrix

systemY = csc_matrix(dss.YMatrix.getYsparse())

systemY
```

--------------------------------

### Import libraries and set path to DSS script

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Multithreading.ipynb

Imports required modules and defines the path to the IEEE 13-bus test circuit. Adjust the path as needed.

```python
import os
import threading
from time import perf_counter
import numpy as np

from opendssdirect.OpenDSSDirect import OpenDSSDirect # for type hints
from opendssdirect import dss

# Adjust this if required
PATH_TO_DSS_SCRIPT = './../../tests/data/13Bus/IEEE13Nodeckt.dss'
```

--------------------------------

### Use DSS-Python via odd.to_dss_python()

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Hybrid approach that uses OpenDSSDirect.py (imported as odd) to obtain a DSS-Python instance via odd.to_dss_python(). This lets you keep the COM-style property syntax (e.g., dss.ActiveCircuit.Loads.kW = 320) while still having access to OpenDSSDirect.py functions. Only the first lines differ from the original COM code.

```python
# Load OpenDSSDirect.py
from opendssdirect import dss as odd
# Get the equivalent DSS-Python instance for the engine. For the default DSS engine, this would be equivalent to `from dss import dss`
dss = odd.to_dss_python()

# Run a DSS script to load a circuit
dss.Text.Command = 'Redirect "../../tests/data/13Bus/IEEE13Nodeckt.dss"'

# Select a load and update its kW
dss.ActiveCircuit.Loads.Name = "675c"
dss.ActiveCircuit.Loads.kW = 320

# Solve
dss.ActiveCircuit.Solution.Solve()

# Get the voltage magnitudes
voltages = dss.ActiveCircuit.AllBusVmag
```

--------------------------------

### Define Storage elements and solve circuit

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/ActiveClass.ipynb

Loads the IEEE 13-node test feeder, defines two Storage elements using the `dss.Command` method with formatted strings, and solves the circuit. Requires the `extras` dependencies.

```python
from opendssdirect import dss

dss('Redirect "../../tests/data/13Bus/IEEE13Nodeckt.dss"')

dss.Circuit.AllBusNames()

dss.Command(
    "New Storage.{bus_name} Bus1={bus_name} phases=1 kV=2.2 kWRated={rating} kWhRated={kwh_rating} kWhStored={initial_state} %IdlingkW=0 %reserve=0 %EffCharge=100 %EffDischarge=100 State=CHARGING".format(
        bus_name='675',
        rating=20,
        kwh_rating=20,
        initial_state=20
    ))


dss.Command(
    "New Storage.{bus_name} Bus1={bus_name} phases=1 kV=2.2 kWRated={rating} kWhRated={kwh_rating} kWhStored={initial_state} %IdlingkW=0 %reserve=0 %EffCharge=100 %EffDischarge=100 State=CHARGING".format(
        bus_name='611',
        rating=20,
        kwh_rating=20,
        initial_state=20
    ))

dss.Solution.Solve()

```

--------------------------------

### Get active load name using high-level API

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Retrieves the name of the active load element using the high-level interface. The result is '670c'.

```python
dss.Loads.Name()
```

```text
Result:
'670c'
```

--------------------------------

### Count lines with len(dss.Lines)

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Get the number of lines in the circuit using len() on the dss.Lines iterator. The output shows 12 lines for the sample circuit.

```python
print(len(dss.Lines))
```

```text
Output:
12
```

--------------------------------

### Open elements before saving with IsOpen flag

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Opens a line terminal before saving to reproduce the SystemY matrix. The first block redirects to the IEEE13 test case and opens Line.671692 at terminal 1. The second block saves the circuit with the IsOpen flag to include the open element.

```python
odd(f'''
    redirect "{IEEE13_PATH}"
    open Line.671692 terminal=1
''')

```

```python
print(odd.Circuit.Save('', DSSSaveFlags.SingleFile|DSSSaveFlags.ToString|DSSSaveFlags.ExcludeDefault|DSSSaveFlags.KeepOrder|DSSSaveFlags.IsOpen))

```

--------------------------------

### Get active load kW using low-level API

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Reads the kW value of the active load element using the low-level function Loads_Get_kW. The result is 117.0.

```python
dss.dss_lib.Loads_Get_kW()
```

```text
Result:
117.0
```

--------------------------------

### Get transformer data as DataFrame with dss.utils.transformers_to_dataframe()

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/GettingStarted.ipynb

Returns a pandas DataFrame with all transformer data from the current OpenDSS circuit. This function is part of the optional pandas interface in the utils module.

```python
dss.utils.transformers_to_dataframe()
```

--------------------------------

### Initialize result dictionaries

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Multithreading.ipynb

Creates dictionaries to store results and convergence flags for threaded and sequential runs.

```python
tresults = {}
tconverged = {}
sresults = {}
sconverged = {}
```

--------------------------------

### Redirect to IEEE 13-bus test circuit

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/VoltageProfilePlot.ipynb

Loads the IEEE 13-bus test feeder file using the DSS Redirect command.

```python
dss('Redirect "../../tests/data/13Bus/IEEE13Nodeckt.dss"')
```

--------------------------------

### Get active load kW using high-level API after set

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Reads the kW value of the active load element using the high-level interface after setting it. The result is 120.0, confirming the set operation.

```python
dss.Loads.kW()
```

```text
Result:
120.0
```

--------------------------------

### Create list of cases to run

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Multithreading.ipynb

Creates a list of 100 cases with LoadMult values from 0.9 to 1.1 for the given DSS script. Copies are made for threaded and sequential runs.

```python
fns = [PATH_TO_DSS_SCRIPT]

cases = []
for fn in fns:
    for load_mult in np.linspace(0.9, 1.1, 100):
        cases.append((fn, load_mult))

cases_to_run_threads = list(cases)
cases_to_run_seq = list(cases)
```

--------------------------------

### Trigger and handle DSSException with dss.Command

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Run a DSS command that fails because the file does not exist, demonstrating the automatic error handling that raises a DSSException.

```python
dss.Command('Redirect this_file_does_not_exist.dss')
```

```text
Error (truncated):
    259     self._errorPtr[0] = 0
--> 260     raise DSSException(error_num, self._get_string(self._lib.Error_Get_Description()))
    262 return result

DSSException: (#243) Redirect file not found: "this_file_does_not_exist.dss"
```

--------------------------------

### Import networkx

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/VoltageProfilePlot.ipynb

Imports the networkx library, used for building and analyzing the graph.

```python
import networkx as nx
```

--------------------------------

### Plot voltage profile for phase A

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/VoltageProfilePlot.ipynb

Uses the create_graph function to generate and plot the voltage profile for phase A.

```python
fig, axs = plt.subplots(1, 1, figsize=(16, 10))

ax = axs
G, pos = create_graph(phase=1)
nx.draw_networkx_nodes(G, pos, ax=ax)
nx.draw_networkx_labels(G, pos, ax=ax, labels={x: x for x in G.nodes()})
nx.draw_networkx_edges(G, pos, ax=ax)

ax.grid()
ax.set_ylabel("Voltage in p.u.")
ax.set_xlabel("Distances in km")
ax.set_title("Voltage profile plot for phase A");
```

--------------------------------

### Determine number of threads and create DSS contexts

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Multithreading.ipynb

Sets the number of threads to the minimum of case count and CPU count, then creates a new DSS context for each thread. Prints the number of contexts created.

```python
# Use the number of threads as CPU count, number of cases
num = min(len(cases), os.cpu_count())

# Initialize a new context for each of the threads
ctxs = [dss.NewContext() for n in range(num)]
print(f"Using {len(ctxs)} DSS contexts")
```

```text
Output:
Using 24 DSS contexts
```

--------------------------------

### Run sequentially for comparison

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Multithreading.ipynb

Runs the same cases sequentially using the main DSS context and prints the elapsed time.

```python
t0 = perf_counter()

_run(dss, cases_to_run_seq, sconverged, sresults)

t1 = perf_counter()
dt_seq = (t1 - t0)
print(f'Done in {dt_seq:.3f} s sequentially')
```

```text
Output:
Done in 5.615 s sequentially
```

--------------------------------

### Redirect to IEEE 13-Bus test circuit

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/SystemY.ipynb

Loads a DSS script. The comment notes that the path may need updating if the notebook is downloaded separately.

```python
# If you downloaded just the notebook, remember to update the path to the DSS script below

dss('Redirect "../../tests/data/13Bus/IEEE13Nodeckt.dss"')
```

--------------------------------

### Iterate over loads with for loop

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Iterates over all loads using a for loop, printing the name and kW for each. The output shows the load names and their kW values.

```python
for load in dss.Loads:
    print(
        'Name={name} \t kW={kW}'.format(
            name=load.Name(), 
            kW=load.kW()
        )
    )
```

--------------------------------

### Display Circuit.Save docstring

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Displays the full docstring of Circuit.Save as formatted Markdown.

```python
display(Markdown(dedent(odd.Circuit.Save.__doc__)))
```

--------------------------------

### Import opendssdirect

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/SystemY.ipynb

Imports the OpenDSS Direct Python module.

```python
from opendssdirect import dss
```

--------------------------------

### Save circuit to a single file and print contents

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Saves the circuit to a single DSS file using the SingleFile flag, then reads and prints the file contents. The saved file includes a comment with the engine version, sets DefaultBaseFreq and EarthModel, but does not include CalcVoltageBases by default.

```python
odd.Circuit.Save('saved_circuit.dss', DSSSaveFlags.SingleFile)
with open('saved_circuit.dss', 'r') as f:
    saved_data = f.read()

print(saved_data)
```

--------------------------------

### Inspect Circuit.Save signature

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Shows the signature and documentation of the Circuit.Save method in a Jupyter notebook.

```python
? odd.Circuit.Save
```

--------------------------------

### Save circuit with IncludeOptions flag

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Saving.ipynb

Saves the circuit including the circuit options by adding the IncludeOptions flag to the Save call. This is important to fully reproduce the circuit.

```python
print(odd.Circuit.Save('', DSSSaveFlags.SingleFile|DSSSaveFlags.ToString|DSSSaveFlags.ExcludeDefault|DSSSaveFlags.KeepOrder|DSSSaveFlags.IsOpen|DSSSaveFlags.IncludeOptions))

```

--------------------------------

### Set legacy property name style with Settings.SetPropertyNameStyle

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/updating_to_0.9.md

Shows how to toggle the DSS property name capitalization style to the legacy style using Settings.SetPropertyNameStyle. There is also a DSSPropertyNameStyle.Lowercase option that may simplify comparisons.

```python
from opendssdirect import dss as odd, enums as dss_enums
odd.Settings.SetPropertyNameStyle(dss_enums.DSSPropertyNameStyle.Legacy)
```

--------------------------------

### Query DSS engine with dss() and dss.Text.Result()

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Example-OpenDSSDirect.py.ipynb

Use the dss callable to send a query command and retrieve the text result from the Text interface.

```python
dss('? Load.634a.kW')
dss.Text.Result()
```

```text
Result:
'160'
```

--------------------------------

### Clone OpenDSSDirect.py repository

Source: https://github.com/dss-extensions/opendssdirect.py/blob/master/docs/notebooks/Installation.ipynb

Clones the OpenDSSDirect.py repository from GitHub for development purposes.

```bash
git clone https://github.com/dss-extensions/OpenDSSDirect.py.git
```