OpenDSS Level 2 Training

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.
Finding the Wiki

Click on More
Finding the Wiki, contd

Menu Expands; Select Wiki
Wiki Home Page (Latest documentation)
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
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.
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
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
11
Registering the COM Server, contd

If you look up the GUID
Points to OpenDSSEngine.DLL
(In-process server, Apartment Threading
model)
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")
13
OpenDSS Standalone EXE User Interface
Multiple script
windows
Any script window

may be used at any
time.
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.
15
DSS Structure
DSS Structure
Scripts
COM
Interface
Main Simulation Engine
Scripts,
Results
17
UserWritten
DLLs
DSS Object Structure

DSS Executive
Commands
Options
Circuit
Solution
V
PDElement
Line
Transformer
Capacitor
Reactor
PCElement
Load
Generator
Vsource
Isource
[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
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
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
22
OpenDSS Registry Entries

Certain persistent values are saved to the Windows
Registry upon exiting the program
Default Editor Setting
After Redefining
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
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
25
Organizing Master File

So Compile Doesnt Fail
26
Circuit Modeling Basics
DSS Bus Model
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)
28
DSS Terminal Definition
1
Power Delivery
or Power Conversion
Element
29
Power Delivery Elements
Terminal 1
Power Delivery
Element
Iterm = [Yprim] Vterm
30
Terminal 2
Power Conversion Elements

ITerm(t) = F(VTerm, [State], t)
F
V
Power Conversion
Element
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
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.
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
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
34
Load (a PC Element)
Compensation
Current
Yprim
(One-Line Diagram)
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
36
Load - 3-phase Delta connected
Phase 1
Yprim
Compensation
Current
Yprim
Compensation
Current
Phase 2
Yprim
Compensation
Current
Phase 3
3 Conductors/Terminal
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
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.
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
40
Computing Currents in a Branch
I1
I4
I2
I5
I3
I6
I1
I2
I3
I4
I5
I6
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
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
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
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
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
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)
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
50
Commands/Options Associated with Plot
AddMarker Bus=busname code=nn color=$00FF0000 size=3

Set Nodewidth = nn
Set MarkerCode = nn
Marker Codes
51
plot circuit Power max=1000 dots=y labels=y C1=$00FF0000
52
set nodewidth=3 markercode=24

plot circuit Power Max=2000 dots=y labels=n subs=n C1=$00FF00FF
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
54
Set nodewidth=1 daisysize=2

plot daisy Power max=2000 y n C1=$00FF0000
Need 500
kW here
55
Monitor Plot Of Feeder Currents

New Monitor.FeederVI Line.l115 1 Mode=0
Plot monitor object= feedervi channels=(7, 9, 11)
56
LoadShape Plot
(Special plot in EXE version only)
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
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
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
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)
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
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)
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
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.
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
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
69
COM Interface
Interfaces as Exposed by VBA

Object Browser in MS Excel
Text has two Properties
Text interface is simplest
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
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.
Delay=30
!Allow only one tap change per solution"
Delay=30
Delay=30
.Command = "RegControl.creg3c.maxtapchange=1
Delay=30
.Command = "RegControl.creg4b.maxtapchange=1
Delay=30
.Command = "RegControl.creg4c.maxtapchange=1
Delay=30
.Command = "Set MaxControlIter=30"

End With
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
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
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
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
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
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
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
79

OpenDSS Level 2 Training

Uploaded by

Copyright:

Available Formats

OpenDSS Level 2 Training

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OpenDSS Level 2 Training

Uploaded by

Copyright:

Available Formats

1600

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

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

Finding the Wiki

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

Finding the Wiki, contd

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

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

Accessing the SourceForge.Net Source Code

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

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

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

Registering the COM Server

The Server shows up as OpenDSSEngine.DSS in

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

Registering the COM Server, contd

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

Accessing the COM Server

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

OpenDSS Standalone EXE User Interface

Any script window

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

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

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

Main Simulation Engine

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

DSS Object Structure

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

DSS Class Structure

Instances of Objects of this class

Class Property Editor

DSS Classes (as of 2009)

Organizing Your User

Organizing Your Main Screen

OpenDSS Registry Entries

Default Editor Setting

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

Organizing Your Main Screen

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

Organizing Run Scripts

Override Some Property Settings

Selected Results Display

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

Organizing Master File

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

Circuit Modeling Basics

DSS Bus Model

Referring to Buses and Nodes

DSS Terminal Definition

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

Power Delivery Elements

Iterm = [Yprim] Vterm

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

Power Conversion Elements