EEN Base Case

1600

OpenDSS
Level 2 Training

1400
1200
1000
800

MWh

600
400

200

Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec

22

19

16

Hour

13

10

Month

27 April 2009

Roger Dugan
[email protected]

Getting Started:
Installation & Basic Usage

 2009 Electric Power Research Institute, Inc. All rights reserved.

 2009 Electric Power Research Institute, Inc. All rights reserved.

Finding the Wiki

Click on More

2009 Electric Power Research Institute, Inc. All rights reserved.

Finding the Wiki, contd

Menu Expands; Select Wiki

2009 Electric Power Research Institute, Inc. All rights reserved.

Wiki Home Page (Latest documentation)

2009 Electric Power Research Institute, Inc. All rights reserved.

Release Versions Vs. Source Code

Release versions are posted irregularly
You can keep up with the latest changes by accessing
the source code and building the latest version
Some of the docs on the Wiki apply only to latest
changes
Compilers
Delphi 2007 (full IDE)
This is what we use for development
Turbo Delphi (Free)
https://downloads.embarcadero.com/free/turbodelphi

2009 Electric Power Research Institute, Inc. All rights reserved.

Accessing the SourceForge.Net Source Code

Repository with TortoiseSVN
Install a 32-bit TortoiseSVN client from tortoisesvn.net/downloads.
Recommendation: From the TortoiseSVN General Settings dialog and
click the last check box, to use "_svn" instead of ".svn" for local
working directory name.
Then, to grab the files from SourceForge:
1 - create a clean directory such as "c:\opendss"
2 - right-click on it and choose "SVN Checkout..." from the menu

3 - the repository URL is

"https://electricdss.svn.sourceforge.net/svnroot/electricdss".
change the checkout directory if it points somewhere other than
what you want.

2009 Electric Power Research Institute, Inc. All rights reserved.

Program Files
OpenDSS.EXE
OpenDSSEngine.DLL
KLUSolve.DLL
DSSgraph.DLL

Standalone EXE
In-process COM server
Sparse matrix solver
DSS graphics output

Copy these files to the directory (folder) of your choice

Typically c:\OpenDSS or c:\Program Files\OpenDSS
If you intend to drive OpenDSS from another program,
you will need to register the COM server

2009 Electric Power Research Institute, Inc. All rights reserved.

10

Registering the COM Server

In DOS window, change to the folder where you
installed it and type:
Regsvr32 OpenDSSEngine.DLL

GUID

The Server shows up as OpenDSSEngine.DSS in

the Windows Registry

2009 Electric Power Research Institute, Inc. All rights reserved.

11

Registering the COM Server, contd

If you look up the GUID

Points to OpenDSSEngine.DLL
(In-process server, Apartment Threading
model)

2009 Electric Power Research Institute, Inc. All rights reserved.

12

Accessing the COM Server

In MATLAB:
DSSobj = actxserver(OpenDSSEngine.DSS);

In VBA:
Public DSSobj As OpenDSSEngine.DSS
Set DSSobj = New OpenDSSEngine.DSS

In PYTHON:
self.engine = win32com.client.Dispatch("OpenDSSEngine.DSS")

2009 Electric Power Research Institute, Inc. All rights reserved.

13

OpenDSS Standalone EXE User Interface

Multiple script
windows

Any script window

may be used at any
time.

2009 Electric Power Research Institute, Inc. All rights reserved.

14

Executing Scripts in the Stand-alone EXE

Select all or part of a line

Right-Click to get this pop-up menu

DSS executes selected line or opens selected file name

Any script window may be used at any time.

2009 Electric Power Research Institute, Inc. All rights reserved.

15

DSS Structure

DSS Structure
Scripts

COM
Interface

Main Simulation Engine

Scripts,
Results

2009 Electric Power Research Institute, Inc. All rights reserved.

17

UserWritten
DLLs

DSS Object Structure

DSS Executive
Commands

Options
Circuit

Solution

PDElement
Line
Transformer
Capacitor
Reactor

PCElement
Load
Generator
Vsource
Isource

2009 Electric Power Research Institute, Inc. All rights reserved.

Controls
RegControl
CapControl
Relay
Reclose
Fuse

18

[Y]

Meters

General

Monitor
EnergyMeter
Sensor

LineCode
LineGeometry
WireData
LoadShape
GrowthShape
Spectrum
TCCcurve

DSS Class Structure

Instances of Objects of this class

Class

Object 1

Property Definitions

Property Values
Methods

Class Property Editor

Yprim
States

Collection Manager

Object n
Property Values
Methods

Yprim
States
2009 Electric Power Research Institute, Inc. All rights reserved.

19

DSS Classes (as of 2009)

Power Delivery (PD) Elements
Line
Transformer
Reactor
Capacitor
Power Conversion (PC) Elements
Load
Generator
Vsource
Isource
Control Elements
RegControl
CapControl
Recloser
Relay
Fuse
2009 Electric Power Research Institute, Inc. All rights reserved.

Metering Elements
Monitor
EnergyMeter
Sensor
General
LineCode
LineGeometry
Loadshape
Growthshape
Wiredata
Spectrum
TCC Curves

20

Organizing Your User

Interface

Organizing Your Main Screen

The OpenDSS saves all windows on the main screen
The appear where you left them when you shut down
The next time you start up, you can resume your work
Values are saved in a file (OpenDSS.ini) saved in the
OpenDSS.exe folder
Note: You can update the program simply by copying
in new exe and dll files.
Do not overwrite the .ini file if you want to preserve
your workspace
However, if the .ini file gets corrupted, you may
simply delete it.
It is a good idea to come up with a comfortable way to
organize your script windows
2009 Electric Power Research Institute, Inc. All rights reserved.

22

OpenDSS Registry Entries

Certain persistent values are saved to the Windows
Registry upon exiting the program

Default Editor Setting

After Redefining

2009 Electric Power Research Institute, Inc. All rights reserved.

23

Organizing Your Main Screen

Main Script Window never
goes away. Put some
frequently-used commands
here.
Annual Simulation Script
Misc. Scripts

Plotting Scripts
Project Run window

2009 Electric Power Research Institute, Inc. All rights reserved.

24

Organizing Run Scripts

Compiles the Circuit Description

Override Some Property Settings

and/or
Define Some Additional Circuit
Element
Change an option
Solve Snapshot Power Flow

Selected Results Display

2009 Electric Power Research Institute, Inc. All rights reserved.

25

Organizing Master File

So Compile Doesnt Fail

2009 Electric Power Research Institute, Inc. All rights reserved.

26

Circuit Modeling Basics

DSS Bus Model

0 1

2 3

Referring to Buses and Nodes

Bus1=BusName.1.2.3.0

(This is the default for a 3-phase circuit element)

Shorthand notation for taking the default
Bus1=BusName
Note: Sometimes this can bite you (e.g. Transformers, or
capacitors with ungrounded neutrals)
2009 Electric Power Research Institute, Inc. All rights reserved.

28

DSS Terminal Definition

1
Power Delivery
or Power Conversion
Element

2009 Electric Power Research Institute, Inc. All rights reserved.

29

Power Delivery Elements

Terminal 1

Power Delivery
Element

Iterm = [Yprim] Vterm

2009 Electric Power Research Institute, Inc. All rights reserved.

30

Terminal 2

Power Conversion Elements

ITerm(t) = F(VTerm, [State], t)

F
V
Power Conversion
Element

2009 Electric Power Research Institute, Inc. All rights reserved.

31

Circuit Elements are Connected together at the

Nodes of Buses

BusX
Terminal 1

Power Delivery
Element

Terminal 2

Terminal 1

Power Delivery
Element

2
Iterm = [Yprim] Vterm

Iterm = [Yprim] Vterm

0
. . . Bus1 = BusX . . .

. . . Bus2 = BusX.2.1.3.0 . . .

(take the default)

(Explicitly define connections)

DSS Convention: A Terminal can be connected to only one Bus. You can have any
number of Nodes at a bus.
2009 Electric Power Research Institute, Inc. All rights reserved.

32

Terminal 2

Connections for 1-Phase Residential

Transformer
! Line-to-Neutral Connected 1-phase Center-tapped transformer
New

Transformer.Example1-ph

~ Xhl=2.04

Xht=2.04

~ Buses=[bus1.1
~ kVs=[7.2 .12

phases=1

Xlt=1.36

bus2.1.0
.12]

Windings=3

%noloadloss=.2

bus2.0.2]

!!! Note polarity

! ratings of windings

~ kVAs=[25 25 25]
~ %Rs = [0.6

1.2

1.2]

~ conns=[wye wye wye]

Bus 1

! default
1

Bus 2
1
Wdg 2

Wdg 1

0
Wdg 3
0 or
2

Center-Tapped 1-Phase Transformer Model

2009 Electric Power Research Institute, Inc. All rights reserved.

33

All Terminals of a Circuit Element Have Same

Number of Conductors
DELTA-WYE
TRANSFORMER

3-Phase
Transformer

3 PHASES
2 WINDINGS
4 CONDS/TERMINAL*

2
2

3
3

(OPEN)
* MUST HAVE THE SAME NUMBER OF
CONDUCTORS FOR EACH TERMINAL
2009 Electric Power Research Institute, Inc. All rights reserved.

34

Load (a PC Element)

Compensation
Current

Yprim

(One-Line Diagram)

2009 Electric Power Research Institute, Inc. All rights reserved.

35

Load - 3-phase Y connected

Phase 1

Yprim

Compensation
Current

Yprim

Compensation
Current

Phase 2

4 Conductors/Terminal

Yprim

Compensation
Current

Phase 3

4
2009 Electric Power Research Institute, Inc. All rights reserved.

36

Load - 3-phase Delta connected

Phase 1

Yprim

Compensation
Current

Yprim

Compensation
Current

Phase 2

Yprim

Compensation
Current

Phase 3

3 Conductors/Terminal

2009 Electric Power Research Institute, Inc. All rights reserved.

37

Putting it All Together

ALL Elements
Yprim 1

Yprim 2

Yprim 3

Yprim n

PC Elements
Comp. Currents
I1
I2

Iinj

Im

Iteration Loop

2009 Electric Power Research Institute, Inc. All rights reserved.

38

Node
Voltages

Solution Speed
Distribution systems generally converge quite rapidly with
this method.
The OpenDSS program seems to be on par with the
faster commercial programs or faster
It is set up to run annual simulations easily
Our recommendation:
Err on the side of running more power flow
simulations
That is, dont worry about the solution time until it
proves to be a problem
That reveals more information about the problem.
2009 Electric Power Research Institute, Inc. All rights reserved.

39

How Do You Get Currents and Power If You

Only Solve for Node Voltages?
One thing that troubles some users who are accustomed
to other ways of solving power flows is how the branch
currents (and powers) are determined when only the
Node voltages and Compensation currents are known.
If the Y matrix is properly formed, and convergence is
achieved, the currents will be correct (obey Kirchoffs law
at nodes)
Currents and powers are determined by post processing
Power criteria are matched by converging with the
specified Load criteria
i.e., compensation currents

2009 Electric Power Research Institute, Inc. All rights reserved.

40

Computing Currents in a Branch

I1

I4

I2

I5

I3

I6

I1
I2
I3
I4
I5
I6

2009 Electric Power Research Institute, Inc. All rights reserved.

Yprim
(6 x 6)

41

V1
V2
V3
V4
V5
V6

Yprim
You can obtain the Primitive Y matrix for each element a
number of ways (after a Solve)
Dump command
Dump class.name debug
Or, Dump Class.* debug
Script
Show Yprim ! Of active element
Export Yprims ! All Yprims
COM Interface
V = DSSCircuit.ActiveElement.NumPhases

2009 Electric Power Research Institute, Inc. All rights reserved.

42

Possible Source of Error!

If the branch is extremely short (impedance is very low),
currents may be incorrectly computed
Convergence tolerance is generally 0.0001 pu
Voltage solution will be correct enough
64-bit math is used throughout
You have a fair amount of leeway
However, if voltages at both ends of branch are
nearly the same, you will be taking the difference
between two nearly equal numbers and the
multiplying it by a large number (very high
conductance)
This will magnify any error
Do not use impractically short branches
2009 Electric Power Research Institute, Inc. All rights reserved.

43

Advanced Topics

Plotting

Ways to Plot
Use the built-in plotting capabilities
Plot in an external program, such as Excel or MATLAB
Maximum of value for each hour over the month.

3000
2500

From Excel
(See Example)

2000
Zone Losses kWh 1500
1000
500
Nov

Sep

2009 Electric Power Research Institute, Inc. All rights reserved.

21

23

17

Mar

19

Hour

13

15

11

Jul
May

46

Jan

Month

From Matlab

Voltage Profile Plot

1.05
1.04
1.03
1.02

Volts(pu)

1.01
1
0.99
0.98
0.97
phase A
phase B
phase C

0.96
0.95

2009 Electric Power Research Institute, Inc. All rights reserved.

4
6
8
Distance from Substation

47

10

12

From Excel
Voltage Profile Plot
1.06
1.05
1.04

Per Unit Voltage

1.03
1.02

V1

1.01

V2
V3

1
0.99
0.98
0.97
0

Distance from Substation

2009 Electric Power Research Institute, Inc. All rights reserved.

48

10

The Plot Command

Type = {Circuit | Monitor | Daisy | Zones | AutoAdd | General (bus data) }
Quantity = {Voltage | Current | Power | Losses | Capacity | (Value Index for General,
AutoAdd, or Circuit[w/ file]) }
Max = {0 | value corresponding to max scale or line thickness}
Dots = {Y | N}
Labels = {Y | N}
Object = [metername for Zone plot | Monitor name | File Name for General bus data or
Circuit branch data]
ShowLoops = {Y | N} (default=N)
R3 = pu value for tri-color plot max range [.85] (Color C3)
R2 = pu value for tri-color plot mid range [.50] (Color C2)
C1, C2, C3 = {RGB color number}
Channels=(array of channel numbers for monitor plot)
Bases=(array of base values for each channel for monitor plot). Default is 1.0 for each.
Set Base= after defining channels.
Subs={Y | N} (default=N) (show substations)
Thickness=max thickness allowed for lines in circuit plots (default=7)
Buslist=[Array of Bus Names | File=filename ] (for Daisy plot)

2009 Electric Power Research Institute, Inc. All rights reserved.

49

The Plot command, contd

Power and Losses in kW.
C1 used for default color (RGB).
Hex Format: $00FF00000
C2, C3 used for gradients, tri-color plots.
Scale determined automatically if Max = 0 or not
specified.
Examples:

Plot type=daisy quantity=power max=5000 dots=N !! Generators by default

Plot daisy power 5000 dots=N Buslist=[file=MyBusList.txt]
Plot circuit quantity=7 Max=.010 dots=Y Object=branchdata.csv
Plot General Quantity=2 Object=valuefile.csv

2009 Electric Power Research Institute, Inc. All rights reserved.

50

Commands/Options Associated with Plot

AddMarker Bus=busname code=nn color=$00FF0000 size=3

Set Nodewidth = nn
Set MarkerCode = nn
Marker Codes

2009 Electric Power Research Institute, Inc. All rights reserved.

51

plot circuit Power max=1000 dots=y labels=y C1=$00FF0000

2009 Electric Power Research Institute, Inc. All rights reserved.

52

set nodewidth=3 markercode=24

plot circuit Power Max=2000 dots=y labels=n subs=n C1=$00FF00FF

2009 Electric Power Research Institute, Inc. All rights reserved.

53

Set Genkw=100
set mode=autoadd
solve
Set nodewidth=7
plot Auto 3 dots=y labels=n subs=n C1=16711680 C2=8421376 C3=255 R3=0.95 R2=0.9

Possibly best
areas for adding
DG

2009 Electric Power Research Institute, Inc. All rights reserved.

54

Set nodewidth=1 daisysize=2

plot daisy Power max=2000 y n C1=$00FF0000

Need 500
kW here

2009 Electric Power Research Institute, Inc. All rights reserved.

55

Monitor Plot Of Feeder Currents

New Monitor.FeederVI Line.l115 1 Mode=0

Plot monitor object= feedervi channels=(7, 9, 11)

2009 Electric Power Research Institute, Inc. All rights reserved.

56

LoadShape Plot
(Special plot in EXE version only)

2009 Electric Power Research Institute, Inc. All rights reserved.

57

EnergyMeter Object

EnergyMeter
Perhaps the most complex object presently in the DSS
Emulates an actual energy meter
Except it can measure things elsewhere in the meter
zone.
Has multiple registers
Registers cleared on
reset meters (or reset)
set mode = .
Set year=
Two types: accumulators and drag hand

2009 Electric Power Research Institute, Inc. All rights reserved.

59

EnergyMeter Registers (Jan 2009)

1. KWh at the meter location.
2. Kvarh at the meter location.
3. Maximum kW at the meter location.
4. Maximum kVA at the meter location.
5. KWh in the meter zone.
6. Kvarh in the meter zone.
7. Maximum kW in the meter zone.
8. Maximum kVA in the meter zone.
9. Overload kWh in the meter zone, normal ratings.
10. Overload kWh in the meter zone, emergency ratings.
11. Energy Exceeding Normal (EEN) in the loads in the meter zone.
12. Unserved Energy (UE) in the loads in the meter zone.
13. Losses (kWh) in power delivery elements in the meter zone.
14. Reactive losses (kvarh) in power delivery elements in the meter zone.
15. Maximum losses (kW) in power delivery elements in the meter zone.
16. Maximum reactive losses (kvar) in power delivery elements in the meter
zone.
17. Load Losses kWh. I2R Losses in power delivery elements
18. Load Losses kvarh. I2X Losses in power delivery elements
19. No Load Losses kWh in shunt elements, principally transformers.
20. No Load Losses kvarh in shunt elements.
21. Max kW Load Losses during the simulation
22. Max kW No Load Losses during the simulation
23. Line Losses: Losses in LINE elements.
24. Transformer Losses: Losses in TRANSFORMER elements.
25. Line Mode Line Losses (3X Pos and neg seq losses)
26. Zero Mode Line Losses (3X zero sequence losses)
27. 3-phase Line Losses
28. 1- and 2-phase Line Losses

2009 Electric Power Research Institute, Inc. All rights reserved.

29. Gen kWh

30. Gen kvarh
31. Gen Max kW
32. Gen Max kVA
33. Aux1 (used for segregating losses by voltage level)
34. Aux2
35. Aux3
36. Aux4
37. Aux5
38. Aux6
39. Aux7

60

Meter Zone
Collection of circuit elements downline from meter.
Only element in DSS that knows about radial circuits
Zone is established first time solution is executed
May be more time-consuming than actual solving for
very large circuits.
Rebuilt whenever bus list is rebuilt
EnergyMeter and Monitor objects are installed in a branch
terminal
New Energymeter.example Element=Line.Line1 Terminal=1

2009 Electric Power Research Institute, Inc. All rights reserved.

61

Meter Zone, contd

Zone is traced from the opposite end of the branch

TRACE FORWARD FROM

OPPOSITE END OF BRANCH IN
WHICH METER IS INSTALLED

METER ZONE

METERS AND MONITORS ARE

INSTALLED IN A BRANCH
TERMINAL (NOT A BUS)

2009 Electric Power Research Institute, Inc. All rights reserved.

62

Meter Zone, contd

Plotting Meter Zone
plot zone Power max=2000 n n object=(metername) C1=$00FF0000

Showing Meter Zone

Show zone metername

Zone dump
energymeter.metername.action=zonedump
Or
Edit energymeter.metername
action=zonedump

2009 Electric Power Research Institute, Inc. All rights reserved.

63

Some Things That Require a Meter Zone

Loss Analysis
Excess load analysis
Plotting zones if different colors
Distance from substation (distance from meter)
Reconductor Command (needs to trace back)

2009 Electric Power Research Institute, Inc. All rights reserved.

64

Monitor or Meter?
Monitor measures quantities only where it is located
Takes a sample of quantity
Voltage and current (several options)
Powers
Transformer taps
State vars

EnergyMeter measures power and integrates some,

samples others
Samples quantities throughout its zone

2009 Electric Power Research Institute, Inc. All rights reserved.

65

Introduction to Driving the

COM Server from another
Application

Active objects concept

There is one registered In-Process COM interface:
OpenDSSEngine.DSS
That is, the DSS interface is the one you instantiate
The DSS interface creates all the others.
The interfaces generally employ the idea of an
ACTIVE object
Active circuit,
Active circuit element,
Active bus, etc.
The interfaces generally point to the active object
To work with another object, change the active
object.
2009 Electric Power Research Institute, Inc. All rights reserved.

67

DSS Interface

This interface is instantiated

upon loading
OpenDSSEngine.DSS and then
instantiates all other interfaces

Call the Start(0) method to

initialize the DSS

DSS Class Functions (methods)

and Properties

2009 Electric Power Research Institute, Inc. All rights reserved.

68

Instantiate the DSS Interface and Attempt Start

Public Sub StartDSS()

' Create a new instance of the DSS

Set DSSobj = New OpenDSSengine.DSS
' Start the DSS
If Not DSSobj.Start(0) Then
MsgBox "DSS Failed to Start"
Else
MsgBox "DSS Started successfully
' Assign a variable to the Text interface for easier access
Set DSSText = DSSobj.Text
End If

End Sub

2009 Electric Power Research Institute, Inc. All rights reserved.

69

COM Interface

Interfaces as Exposed by VBA

Object Browser in MS Excel

Text has two Properties

Text interface is simplest

2009 Electric Power Research Institute, Inc. All rights reserved.

70

Assign a Variable to the Text Interface

Public Sub StartDSS()

' Create a new instance of the DSS

Set DSSobj = New OpenDSSengine.DSS
' Start the DSS
If Not DSSobj.Start(0) Then
MsgBox "DSS Failed to Start"
Else
MsgBox "DSS Started successfully
' Assign a variable to the Text interface for easier access
Set DSSText = DSSobj.Text
End If

End Sub

2009 Electric Power Research Institute, Inc. All rights reserved.

71

Now Use the Text Interface

You can issue any of the DSS script commands from the
Text interface
Always a good idea to clear the DSS when loading a new circuit
DSSText.Command = "clear"
' Compile the script in the file listed under "fname" cell on the main form
DSSText.Command = "compile " + fname
Set regulator tap change limits for IEEE 123 bus test case
With DSSText
.Command = "RegControl.creg1a.maxtapchange=1
This one moves first"

Delay=15

!Allow only one tap change per solution.

.Command = "RegControl.creg2a.maxtapchange=1

Delay=30

!Allow only one tap change per solution"

.Command = "RegControl.creg3a.maxtapchange=1

Delay=30

!Allow only one tap change per solution"

.Command = "RegControl.creg4a.maxtapchange=1

Delay=30

!Allow only one tap change per solution"

.Command = "RegControl.creg3c.maxtapchange=1

Delay=30

!Allow only one tap change per solution"

.Command = "RegControl.creg4b.maxtapchange=1

Delay=30

!Allow only one tap change per solution"

.Command = "RegControl.creg4c.maxtapchange=1

Delay=30

!Allow only one tap change per solution"

.Command = "Set MaxControlIter=30"

End With

2009 Electric Power Research Institute, Inc. All rights reserved.

72

Result Property
The Result property is a Read Only property that contains
any result messages the most recent command may have
issued.
Error messages
Requested values
Example: Query line length
DSSText.Command = ? Line.L1.Length
S = DSSText.Result
MsgBox S

2009 Electric Power Research Institute, Inc. All rights reserved.

Get the answer

Display the answer

73

Circuit Interface

This interface is used to

1) Get many of the results for the most recent
solution of the circuit
2) Select individual circuit elements in a
variety of ways

3) Select the active bus

4) Enable/Disable circuit elements

2009 Electric Power Research Institute, Inc. All rights reserved.

74

Circuit Interface

Since the Circuit interface is used often, it is recommended that a

special variable be assigned to it:
Public DSSCircuit As OpenDSSengine.Circuit

DSSText.Command = Compile xxxx.dss

Set DSSCircuit = DSSobj.ActiveCircuit
DSSCircuit.Solution.Solve

Retrieving array quantities into variants

V = DSSCircuit.AllBusVmagPu
VL =DSSCircuit.AllElementLosses

2009 Electric Power Research Institute, Inc. All rights reserved.

75

Solution Interface

The Solution Interface is used to

1) Execute a solution
2) Set the solution mode
3) Set solution parameters (iterations,
control iterations, etc.)
4) Set the time and time step size

2009 Electric Power Research Institute, Inc. All rights reserved.

76

Solution Interface

Assuming the existence of a DSSCircuit variable

referencing the Circuit interface
Set DSSSolution = DSSCircuit.Solution
With DSSSolution

.LoadModel=dssAdmittance

Use the With statement in

VBA to simplify coding

.dblHour = 750.75
.solve

End With

2009 Electric Power Research Institute, Inc. All rights reserved.

77

CktElement Interface

This interface provides specific values of the

Active Circuit Element
Some values are returned as variant arrays
V = DSSCircuit.ActiveElement.Powers
V = DSSCircuit.ActiveElement.seqCurrents
V = DSSCircuit.ActiveElement.Yprim

Other values are scalars

Name = DSSCircuit.ActiveElement.Name

Nph = DSSCircuit.ActiveElement.NumPhases

2009 Electric Power Research Institute, Inc. All rights reserved.

78

Properties Interface

This interface gives access to a String value of

each public property of the active element
Val is a read/write property

2009 Electric Power Research Institute, Inc. All rights reserved.

79

Properties Interface
With DSSCircuit.ActiveElement
Get all the property names
VS = .AllPropertyNames
Get a property value by numeric index
V = .Properties(2).Val
Get same property value by name (VS is 0 based)
V = .Properties(VS(1)).Val
Set Property Value by Name
DSSCircuit.SetActiveElement(Line.L1)
.Properties(R1).Val = .068
End With

The last two statements are equivalent to:

DSSText.Command = Line.L1.R1=.068

2009 Electric Power Research Institute, Inc. All rights reserved.

80

Lines Interface

This interface is provided to iterate through all

the lines in the circuit and change the most
common properties of Lines.

2009 Electric Power Research Institute, Inc. All rights reserved.

81

Example: Setting all LineCodes to a Value

Set DSSLines = DSSCircuit.Lines
.

iL = DSSLines.First

sets active

Do While iL>0
DSSLines.LineCode = MyNewLineCode
iL = DSSLines.Next

get next line

Loop

2009 Electric Power Research Institute, Inc. All rights reserved.

82

VBA Example
Option Explicit

Define some public variables that are

used throughout the project

Public DSSobj As OpenDSSengine.DSS

Public DSSText As OpenDSSengine.Text
Public DSSCircuit As OpenDSSengine.Circuit
Public Sub StartDSS()
' Create a new instance of the DSS
Set DSSobj = New OpenDSSengine.DSS
' Assign a variable to the Text interface for easier
access
Set DSSText = DSSobj.Text

This routine instantiates the DSS

and starts it. It is also a good idea at
this time to assign the text interface
variable.

' Start the DSS

If Not DSSobj.Start(0) Then MsgBox "DSS
Failed to Start"
End Sub

2009 Electric Power Research Institute, Inc. All rights reserved.

83

VBA Example
Public Sub LoadCircuit(fname As String)
' Always a good idea to clear the DSS when loading a new
circuit
DSSText.Command = "clear"
' Compile the script in the file listed under "fname" cell on the
main form
DSSText.Command = "compile " + fname
' The Compile command sets the current directory the that of
the file
' Thats where all the result files will end up.
' Assign a variable to the Circuit interface for easier access
Set DSSCircuit = DSSobj.ActiveCircuit
End Sub

2009 Electric Power Research Institute, Inc. All rights reserved.

84

This subroutine loads the circuit

from the base script files using
the Compile command through
the Text interface. fname is a
string contains the name of the
master file.
There is an active circuit now,
so assign the DSSCircuit
variable.

VBA Example
This Sub puts the sequence voltage onto a
spreadsheet

Public Sub LoadSeqVoltages()

' This Sub loads the sequence voltages onto Sheet1 starting in Row 2

Define a variable for the Bus interface

Dim DSSBus As OpenDSSengine.Bus

Dim iRow As Long, iCol As Long, i As Long, j As Long
Dim V As Variant
Dim WorkingSheet As Worksheet

Define a variant to pick up the arrays

Set WorkingSheet = Sheet1 'set to Sheet1 (target sheet)

iRow = 2
For i = 1 To DSSCircuit.NumBuses ' Cycle through all buses

Cycle through all the buses

Set DSSBus = DSSCircuit.Buses(i) ' Set ith bus active

Get the bus name

' Bus name goes into Column 1

WorkingSheet.Cells(iRow, 1).Value = DSSCircuit.ActiveBus.Name
' Load sequence voltage magnitudes of active bus into variant array
V = DSSBus.SeqVoltages

Get the voltages

into the variant array

' Put the variant array values into Cells

' Use Lbound and UBound because you don't know the actual range
iCol = 2
For j = LBound(V) To UBound(V)
WorkingSheet.Cells(iRow, iCol).Value = V(j)
iCol = iCol + 1
Next j
iRow = iRow + 1
Next i

Put them on the

spreadsheet

End Sub
2009 Electric Power Research Institute, Inc. All rights reserved.

85

Running OpenDSS From Matlab

Starting the DSS
%Start up the DSS
[DSSStartOK, DSSObj, DSSText] = DSSStartup;

function [Start,Obj,Text] = DSSStartup

% Function for starting up the DSS
%
%instantiate the DSS Object

Obj = actxserver('OpenDSSEngine.DSS');
%
%Start the DSS.

Only needs to be executed the first time w/in a

%Matlab session
Start = Obj.Start(0);

% Define the text interface to return

Text = Obj.Text;

2009 Electric Power Research Institute, Inc. All rights reserved.

86

Using the DSS through the DSSText Interface from

Matlab (harmonics example)
%Compile the DSS circuit script
DSSText.Command = 'compile master.dss';
% get an interface to the active circuit called "DSSCircuit"
DSSCircuit = DSSObj.ActiveCircuit;
%Determine which connection type for the source and call
%appropriate DSS file
switch XFMRType
case 1
DSSText.Command = 'redirect directconnectsource.DSS';
case 2
DSSText.Command = 'redirect deltadelta.DSS';
case 3
DSSText.Command = 'redirect deltawye.DSS';
otherwise
disp('Unknown source Connection Type')
end
%Set the system frequency and vsource frequency for harmonic requested
DSSText.Command = ['set frequency=(' num2str(Freq) ' 60 *)'];
DSSText.Command = ['vsource.source.frequency=(' num2str(Freq) ' 60 *)'];

2009 Electric Power Research Institute, Inc. All rights reserved.

87

Using the DSS through the DSSText Interface from

Matlab (harmonics example) (contd)
% Vary the parameters according to a random distribution
% If more parameters need to be varied, just add them to the below
% list.

Set ParamNum to total number of parameters varied

ParamNum = 6;

%ParamNum used for sorting/plotting

for Case_Count = 1:Max_Cases

%Create index in the OutputData matrix to keep the cases in order
OutputData(Case_Count,1) = Case_Count;
% Generate random new coordinates for each conductor
[x1 y1 x2 y2 x3 y3 geomean] = RandomGeometry(8,0.75,30);
(... etc. etc. )
%define a new line geometry with random spacing
DSSText.Command = ['New LineGeometry.OHMOD nconds=3 nphases=3 cond=1 wire=acsr336
num2str(x1) '
' num2str(y1) '
units=ft cond=2 wire=acsr336
x=' num2str(x2) '
num2str(y2) '
units=ft cond=3 wire=acsr336
x=' num2str(x3) '
' num2str(y3) '
units=ft'];
%Solve the circuit
DSSText.Command = 'solve';

(etc. etc.)

2009 Electric Power Research Institute, Inc. All rights reserved.

88

x='
'

User-Written Controls

From the COM Interface

Basic Control Loop Flow Chart

You can single-step
through this

If you set Number=1,

you can break in
here

Initialize Loop

Solve Circuit
Next Time Step
Check Controls

NO

YES
Control Actions Done?

2009 Electric Power Research Institute, Inc. All rights reserved.

90

Control Loop (Actual Pascal Code)

FUNCTION TSolutionObj.SolveSnap:Integer; // solve for now once
VAR
TotalIterations :Integer;
Begin
SnapShotInit;
TotalIterations
:= 0;
REPEAT
Inc(ControlIteration);
Result := SolveCircuit; // Do circuit solution w/o checking controls
{Now Check controls}
CheckControls;
{For reporting max iterations per control iteration}
If Iteration > MostIterationsDone THEN MostIterationsDone := Iteration;
TotalIterations := TotalIterations + Iteration;
UNTIL ControlActionsDone or (ControlIteration >= MaxControlIterations);
If Not ControlActionsDone and (ControlIteration >= MaxControlIterations) then Begin
DoSimpleMsg('Warning Max Control Iterations Exceeded. ' + CRLF + 'Tip: Show
Eventlog to debug control settings.', 485);
SolutionAbort := TRUE;
// this will stop this message in dynamic power flow modes
End;
If ActiveCircuit.LogEvents Then LogThisEvent('Solution Done');
Iteration := TotalIterations; { so that it reports a more interesting number }
End;

2009 Electric Power Research Institute, Inc. All rights reserved.

91

External Script and COM Interface Options

Take Immediate action or keep track of time yourself
Set Number=1
Sample after solution step
Execute command to change element state
Use the DSS Control Queue through COM Proxy
Set Number=1
Step through solution
Push control commands onto DSS control queue
(Allows DSS to keep track of when control actions
happen)
Write routines to handle pending actions
2009 Electric Power Research Institute, Inc. All rights reserved.

92

Control Proxy in COM Interface

COM Interface Control Proxy Operation
COM Interface
COM CONTROL
Proxy
DoPendingAction

USER CODE

POP

CONTROL

Action List

DISPATCHER
PUSH

POP

CONTROL OBJECT
ACTION 1

ALL PUSHES
ARE SORTED
BY TIME

DoPendingAction
ACTION 2
ACTION 3
...

CONTROL OBJECT

ACTION N
DoPendingAction

DSS Control Queue

Time
Action Code
Proxy Handle
Control Addr

2009 Electric Power Research Institute, Inc. All rights reserved.

93

Misc. Hints and Tips,

Known Issues, etc.

Transformer PPM_antifloat Property

Admittance matrix formulations can suffer from
Y matrix singularities if part of the circuit is
isolated from ground voltage reference, such
as for a floating delta winding. The DSS by
default increases the diagonal elements of the
Yprim matrix by 1 part in 1 million (1 ppm)
which is equivalent to attaching a small
reactance to ground at each terminal as
shown.

The DSS uses 64-bit arithmetic throughout, so

this is usually not a problem with precision.
If you dont want this, you can set
PPM_Antifloat = 0.

2009 Electric Power Research Institute, Inc. All rights reserved.

95

Transformer PPM_antifloat Property, contd

A common error is to specify a very large transformer
(e.g., 1000000 kVA or higher) to represent a very low
impedance transformer
This works for the leakage impedance
However, the small anti-float reactances are no longer
small !!!
This will sometimes draw more current than the load!
Better approach
Use a reasonable kVA value and set XHL= small value
Set PPM_Antifloat = 0 or a small number
Make sure you can do this without getting floating
networks!
2009 Electric Power Research Institute, Inc. All rights reserved.

96

Wye-connected Generator
Sometimes the normal power flow will not converge well
for direct-connect Y-connected DG.
Workaround:

Set
Xdmodel = Xd - X0
Xdmodel= Xd - X0
Set XHL = X0 of DG

2009 Electric Power Research Institute, Inc. All rights reserved.

97

Model DG as Deltaconnected generator

behind Y-Delta
transformer

How Do I Make One of Those 3-D Plots?

Maximum of value for each hour over the month.

3000

We call this an E-3 plot

after the San Francisco
economics firm who taught
us how to do it (see
http://ethree.com)

2500
2000
Zone Losses kWh 1500
1000
500
Nov

Sep

2009 Electric Power Research Institute, Inc. All rights reserved.

98

23

21

Mar

19

17

May

15

Hour

13

11

Jul

Jan

Month

Procedure for 3D Annual Plot

Run an annual simulation (Set Mode=Yearly)
Turn on the Demand Interval feature of the EnergyMeter
object
Or, simply use a Monitor object
Import the resulting CSV file into MS Excel where a 3-D
plot has been defined
(See SampleDSSDriver.XLS for an example macro for
importing a field from a CSV file.)

2009 Electric Power Research Institute, Inc. All rights reserved.

99

Annual Simulation Script

set casename=MyCaseName
set mode=yearly

! This will be the folder name + year number

! Sets Number=8760, 1 hr time step, resets meters

! Set "DemandInterval" to true so that energy quantities recorded by energy

meters are recorded for
! each time step and set "casename" to define a directory under default
directory in which all of the
! demand interval data is recorded. (NOTE: Setting DemandInterval=true
resets all energymeters.)
Set
Set
set
set

overloadreport=true
voltexcept=true
DemandInterval=true
DIVerbose=true

! TURN OVERLOAD REPORT ON (optional)

! TURN VOLT Exception REPORT ON
! Capture demand interval data

Set Year=1
solve
Set Year=2
solve
Closedi

! Do this after final year

2009 Electric Power Research Institute, Inc. All rights reserved.

100

Executing Part of Annual Simulation

set casename=MyCaseName

set mode=yearly

! This will be the folder name + year number

! Sets Number=8760, 1 hr time step, resets meters

! Set "DemandInterval" to true so that energy quantities recorded by energy

meters are recorded for
! each time step and set "casename" to define a directory under default
directory in which all of the
! demand interval data is recorded. (NOTE: Setting DemandInterval=true
resets all energymeters.)
Set
Set
set
set

overloadreport=true
voltexcept=true
DemandInterval=true
DIVerbose=true

Set Year=1
Set hour=5000
solve Number=168
Closedi

! TURN OVERLOAD REPORT ON (optional)

! TURN VOLT Exception REPORT ON
! Capture demand interval data

! Start at hour 5000 into loadshapes

! Solve one week; redefine Number

! Do this after final year

2009 Electric Power Research Institute, Inc. All rights reserved.

101

Demand Interval Files

After an annual simulation, the results are saved in the
directory structure as a collection of CSV files
Circuit Root
CaseName
DI_yr_1
DI_yr_2
DI_yr_3
DI_yr_4

DI_yr_N
2009 Electric Power Research Institute, Inc. All rights reserved.

102

Inside a DI_Yr_nn Directory

The results are saved as a series of CSV files.

(one week simulation)

2009 Electric Power Research Institute, Inc. All rights reserved.

103

Snip from CSV file loaded into Excel

Hour
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226

"kWh"
"kvarh"
"Max kW" "Max kVA" "Zone kWh" "Zone kvarh" "Zone Max kW""Zone Max kVA"
"Overload kWh
"Overload
Normal"
kWh
"Load
Emerg"
EEN""Load
20430.7 775.005 20430.7 20445.4
39147.9
1908.31
39147.9 39194.4
0
0 2576.61
244
21438 744.841
21438 21450.9
41086.8
1875.58
41086.8 41129.5
0
0 2629.76 2490
22450.5 810.443 22450.5 22465.2
43024.8
2013.08
43024.8 43071.9
0
0 2669.37 2527
23559.8 928.416 23559.8 23578.1
45143
2243.88
45143 45198.7
0
0 2812.75 2663
24688.2 1012.56 24688.2 24708.9
47300.2
2413.44
47300.2 47361.7
8.9537
0 1968.41 3339
26375.6 1079.88 26375.6 26397.7
50532.5
2563.64
50532.5 50597.5 26.9063 8.05913 2401.86
224
28516.4 1149.75 28516.4 28539.6
54634.9
2726.26
54634.9 54702.8 41.4067 22.5873 2757.64 2579
30231 1242.84
30231 30256.5
57915
2919.27
57915 57988.6
47.904 29.1057
2943.3 2729
31459.5 1263.09 31459.5 31484.8
60271.7
2977.84
60271.7 60345.3 49.6115 30.8222 3000.93 2769
32448.5 1232.52 32448.5 32471.9
62175.8
2945.17
62175.8 62245.5 50.9358
32.15 3025.13 2798
33111.5 1189.47 33111.5350
33132.9
63455.3
2884.76
63455.3 63520.8 52.2198 33.4349 3041.49
282
33959.2 1222.36 33959.2 33981.2
65078.8
2957.43
65078.8
65146 52.1848 33.4068 3059.37 2827
34387.3
1225.1 34387.3300
34409.1
65901.7
2970.85
65901.7 65968.7 48.9837 30.2053 2983.32 2753
34678.5 1175.29 34678.5 34698.4
66468.7
2892.75
66468.7 66531.6 34.5677 15.7739 2607.68 2423

Loss Plot

kW

250
200

"Zone Losses kWh"

150

"Load Losses kWh"

100
50
0
5200

5250

5300
Hour

2009 Electric Power Research Institute, Inc. All rights reserved.

104

5350

5400

Enable/Disable
Once a circuit element is defined in a script, it can be
Enabled (default)
Disabled
Redefined (Edit)
Use Enable/Disable to temporarily add or delete elements
from the circuit
Enable/Disable Commands
Disable Line.Line1
Line.Line1.Enabled = No
Edit Line.Line1 . Enabled=No

2009 Electric Power Research Institute, Inc. All rights reserved.

105

Open/Close
You can open any terminal of any device that is active in
the circuit:
Open Line.Line1 2 (opens Terminal 2)
Open Line.Line1 2 3 (opens phase 3 of terminal 2)
Caveat: Voltage at open terminal is inaccessible (does not
exist)
Alternative:
Line.Line1.Bus2=Term2_Open
Redefine Bus2 to another bus with nothing else
Term2_open voltage is accessible

2009 Electric Power Research Institute, Inc. All rights reserved.

106

Load Models (Present version)

1:Standard constant P+jQ load. (Default)

2:Constant impedance load.
3:Const P, Quadratic Q (like a motor).
4:Nominal Linear P, Quadratic Q (feeder mix). Use this with
CVRfactor.
5:Constant Current Magnitude
6:Const P, Fixed Q
7:Const P, Fixed Impedance Q

2009 Electric Power Research Institute, Inc. All rights reserved.

107

Standard P + jQ Load Model

When the voltage goes out of the normal range for a load
the model reverts to a linear load model
This generally guarantees convergence
Even when a fault is applied
To change break points to +/- 10%:
Load.Load1.Vmaxpu=1.10
Load.Load1.Vminpu=0.90
Note: to solve some of the IEEE Radial Test feeders
and match the published results, you have to set
Vminpu to less than the lowest voltage published

2009 Electric Power Research Institute, Inc. All rights reserved.

108

Standard P + jQ Load Model (Model=1)

DSS P,Q Load Characteristic

Const Z

1.3
1.2

105%

1.1

(Defaults*)

1
0.9

|I| = |S/V|

95%

PU Voltage

0.8
0.7
0.6

Const Z

0.5
0.4
0.3

* Change by setting Vminpu and

Vmaxpu Properties

0.2
0.1
0
0

0.2

0.4

0.6

0.8

PU Current
2009 Electric Power Research Institute, Inc. All rights reserved.

109

1.2

Other Load Models

1:Standard constant P+jQ load. (Default)
2:Constant impedance load.
3:Const P, Quadratic Q (like a motor).
4:Nominal Linear P, Quadratic Q (feeder mix).
Use this with CVRfactor.
5:Constant Current Magnitude
6:Const P, Fixed Q
7:Const P, Fixed Impedance Q

2009 Electric Power Research Institute, Inc. All rights reserved.

110

Two Terminal Caps, Reactors, Faults

Capacitors, Reactors, and Faults are special 2-terminal
PDElements with special defaults for bus connections
DEFAULT AFTER
BUS1 IS DEFINED

BASIC DEFINITION

DELTA
CONNECTION

Bus1 = B1
Bus2 = B2
(Series
Connection)

Bus1=B1
(Bus2 is
ignored)
Bus1=B1
(BUS2=B1.0.0.0) (default)

2009 Electric Power Research Institute, Inc. All rights reserved.

111

MAKING A N
UNGROUNDED
WY E

Bus1 = B1
Bus2 = B1.4.4.4

Common Errors

A Buss Life
In contrast to other power system analysis programs, Bus
objects do not exist until required
These commands will force building of the bus list
Solve
CalcVoltageBases
MakeBusList
The Bus list is built from the currently enabled devices
Editing circuit element properties often requires rebuilding
the bus list
If no changes, the bus list is not re-built
2009 Electric Power Research Institute, Inc. All rights reserved.

113

Specifying Transformer Neutral Reactor

DELTA-WYE
TRANSFORMER

Whats Wrong With This?

New Transformer.T1 phases=3 Wind=2

With Neutral Grounding Reactor

1

2
2

~ Buses=[DeltaBus WyeBus]
~ Conns=[Delta Wye]

3
3

~ kVAs=[10000 10000]
~ kVs=[115 12.47]

~ Wdg=2 Rneut=0 Xneut=4

4
(OPEN)

2009 Electric Power Research Institute, Inc. All rights reserved.

114

Specifying Transformer Neutral Reactor

DELTA-WYE
TRANSFORMER
With Neutral Grounding Reactor

Whats Wrong With This?

1

New Transformer.T1 phases=3 Wind=2

2
2

~ Buses=[DeltaBus WyeBus]
~ Conns=[Delta Wye]

3
3

~ kVAs=[10000 10000]
~ kVs=[115 12.47]

Expands to

~ Wdg=2 Rneut=0 Xneut=4

4
(OPEN)

WyeBus.1.2.3.0

2009 Electric Power Research Institute, Inc. All rights reserved.

Shorts The Reactor !!!

115

Line Length and Distance from Meter

Distance from the upstream meter is accumulated for
each branch and bus as the meter zone is traced
The Length= and Units= properties of the Line definition
are used to convert the length to km
Problem: Unit-less lines
Line impedance may be computed by entering the
impedance value in actual ohms and setting the
length=1.
However, this will be interpreted as a 1 km line!!
Usage of the distance value will be suspect
Distance is available from the COM Bus interface

2009 Electric Power Research Institute, Inc. All rights reserved.

116

Single-Phase to 3-phase Line

SOURCE

THIS SECTION IS ISOLATED

Diagnosing: This may cause a floating point error in normal snapshot power flow.
1) Look at voltage after CalcVoltageBases
2) Do Solve Mode=Direct; then look at voltages (Show Voltage LN Nodes)

2009 Electric Power Research Institute, Inc. All rights reserved.

117

Wrong Voltage Base on Load or Generator

Dont forget to specify kv= property!
3-phase Load
New Load.Load1 Phases=3 Bus1=B1 kV=12.47 kW=100 PF=.95

3 Single-phase Loads
New Load.Load1a Phases=1 Bus1=B1.1 kV=7.2 kW=33.33 PF=.95
New Load.Load1b Phases=1 Bus1=B1.2 kV=7.2 kW=33.33 PF=.95
New Load.Load1c Phases=1 Bus1=B1.3 kV=7.2 kW=33.33 PF=.95

Make sure these have different names

2009 Electric Power Research Institute, Inc. All rights reserved.

118

A Tricky One Sequence dependencies

Compile xxxx
Set VoltageBases=[12.47 .48 .208]
CalcVoltageBases
! Now define energymeter to get voltage base register
New EnergyMeter.Main Line.Line1 1
Reconductor Line50 Line60
LineCode=795ACSR
Causes an error that says Line50 and Line60 not in a meter zone or not in same meter zone
Why?

Nothing has happened since the definition of the EnergyMeter object to force it to compute its
zone.
Resolution:
Issue Solve or MakeBusList to force meterzone. Then issue Reconductor

2009 Electric Power Research Institute, Inc. All rights reserved.

119

Questions?