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
rdugan@[Link]

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)
[Link]

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

Accessing the [Link] Source Code

Repository with TortoiseSVN
Install a 32-bit TortoiseSVN client from [Link]/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
"[Link]
change the checkout directory if it points somewhere other than
what you want.

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

Program Files
[Link]
[Link]
[Link]
[Link]

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 [Link]

GUID

The Server shows up as [Link] 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 [Link]
(In-process server, Apartment Threading
model)

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

12

Accessing the COM Server

In MATLAB:
DSSobj = actxserver([Link]);

In VBA:
Public DSSobj As [Link]
Set DSSobj = New [Link]

In PYTHON:
[Link] = [Link]("[Link]")

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
V

PDElement
Line
Transformer
Capacitor
Reactor

PCElement
Load
Generator
Vsource
Isource

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

[Y]

Controls

Meters

General

RegControl
CapControl
Relay
Reclose
Fuse

Monitor
EnergyMeter
Sensor

LineCode
LineGeometry
WireData
LoadShape
GrowthShape
Spectrum
TCCcurve

18

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 ([Link]) saved in the
[Link] 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

2 3

Referring to Buses and Nodes

Bus1=BusName.[Link]
(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

3
2
Iterm = [Yprim] Vterm

Iterm = [Yprim] Vterm

0
. . . Bus1 = BusX . . .

. . . Bus2 = BusX.[Link] . . .

(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

1
2

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 [Link] debug
Or, Dump Class.* debug
Script
Show Yprim ! Of active element
Export Yprims ! All Yprims
COM Interface
V = [Link]

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
2000

From Excel
(See Example)

Zone Losses kWh 1500

1000
500
Nov

0
3

Sep

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

23

21

17

13

Mar
19

Hour

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
0

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=[Link]]
Plot circuit quantity=7 Max=.010 dots=Y Object=[Link]
Plot General Quantity=2 Object=[Link]

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 [Link] 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 [Link] 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
[Link]=zonedump
Or
Edit [Link]
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:
[Link]
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
[Link] 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 [Link]
' Start the DSS
If Not [Link](0) Then
MsgBox "DSS Failed to Start"
Else
MsgBox "DSS Started successfully
' Assign a variable to the Text interface for easier access
Set DSSText = [Link]
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 [Link]
' Start the DSS
If Not [Link](0) Then
MsgBox "DSS Failed to Start"
Else
MsgBox "DSS Started successfully
' Assign a variable to the Text interface for easier access
Set DSSText = [Link]
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
[Link] = "clear"
' Compile the script in the file listed under "fname" cell on the main form
[Link] = "compile " + fname
Set regulator tap change limits for IEEE 123 bus test case
With DSSText
.Command = "[Link]=1
This one moves first"

Delay=15

!Allow only one tap change per solution.

.Command = "[Link]=1

Delay=30

!Allow only one tap change per solution"

.Command = "[Link]=1

Delay=30

!Allow only one tap change per solution"

.Command = "[Link]=1

Delay=30

!Allow only one tap change per solution"

.Command = "[Link]=1

Delay=30

!Allow only one tap change per solution"

.Command = "[Link]=1

Delay=30

!Allow only one tap change per solution"

.Command = "[Link]=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
[Link] = ? [Link]
S = [Link]
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 [Link]

[Link] = Compile [Link]

Set DSSCircuit = [Link]
[Link]

Retrieving array quantities into variants

V = [Link]
VL =[Link]

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 = [Link]
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 = [Link]
V = [Link]
V = [Link]

Other values are scalars

Name = [Link]
Nph = [Link]

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