The Open Distribution System Simulator

OpenDSS Manual
June 2013
Program Revision: 7.6
Reference Guide
The Open Distribution System Simulator
(OpenDSS)
RogerC.Dugan
Sr.TechnicalExecutive
ElectricPowerResearchInstitute,Inc.
June2013
Page 1 of 180
OpenDSS Manual
June 2013
Page 2 of 180
OpenDSS Manual
June 2013
License
Copyright(c)20082013,ElectricPowerResearchInstitute,Inc.
Allrightsreserved.
Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
Neither the name of the Electric Power Research Institute, Inc., nor the names
of its contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY Electric Power Research Institute, Inc., "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL Electric Power Research Institute, Inc., BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Page 3 of 180
OpenDSS Manual
June 2013
TableofContents
LICENSE.................................................................................................................................................3
SUMMARY..........................................................................................................................................13
BRIEFHISTORYANDOBJECTIVESOFOPENDSS.....................................................................................16
WHYDELPHI?...............................................................................................................................................18
INSTALLATION.....................................................................................................................................20
COMAUTOMATION......................................................................................................................................20
FILES...........................................................................................................................................................20
OTHERREGISTRYENTRIES...............................................................................................................................23
OTHERFILES.................................................................................................................................................23
Examples,Docs,andTestCases
23
SUMMARYOFSIMULATIONCAPABILITIES...........................................................................................25
POWERFLOW...............................................................................................................................................25
FAULTSTUDIES.............................................................................................................................................26
HARMONICFLOWANALYSIS............................................................................................................................27
DYNAMICS...................................................................................................................................................27
LOADPARAMETRICVARIATION.........................................................................................................................28
GEOMAGNETICALLYINDUCEDCURRENT(GIC)ANALYSIS.......................................................................................28
BASICUSAGE.......................................................................................................................................30
OPENDSSCONTROLPANEL.............................................................................................................................30
EXPORTMENUCOMMANDS............................................................................................................................32
PLOTMENUCOMMANDS................................................................................................................................34
OVERALLCIRCUITMODELCONCEPT.....................................................................................................40
BUSANDTERMINALMODELS..............................................................................................................41
BUSDEFINITION............................................................................................................................................41
TERMINALDEFINITION....................................................................................................................................41
BUSNAMING................................................................................................................................................42
BUSINSTANTIATIONANDLIFE..........................................................................................................................42
TERMINALREFERENCES...................................................................................................................................43
PHASESANDOTHERCONDUCTORS....................................................................................................................43
SPECIFYINGCONNECTIONS..............................................................................................................................44
POWERDELIVERYELEMENTS...............................................................................................................46
POWERCONVERSIONELEMENTS.........................................................................................................47
PUTTINGITALLTOGETHER..................................................................................................................49
DSSCOMMANDLANGUAGESYNTAX...................................................................................................51
COMMANDSYNTAX.......................................................................................................................................51
PARAMETERS................................................................................................................................................52
PROPERTIES..................................................................................................................................................52
DELIMITERSANDOTHERSPECIALCHARACTERS....................................................................................................53
ARRAYPROPERTIES[ANDQUOTEPAIRS]............................................................................................................53
StandardWaystoDefineArrayProperties
EnhancedSyntax
SpecialReservedFileName
54
54
54
Page 4 of 180
OpenDSS Manual
June 2013
MATRIXPROPERTIES......................................................................................................................................54
STRINGLENGTH............................................................................................................................................55
DEFAULTVALUES...........................................................................................................................................55
INLINEMATH..............................................................................................................................................56
RPNExpressions
RPNExamples
56
57
DSSCOMMANDREFERENCE................................................................................................................59
SPECIFYINGOBJECTS......................................................................................................................................59
COMMANDREFERENCE..................................................................................................................................60
(comment)and!(inlinecomment)
**/BlockComments
CustomizingSolutionProcesses
?[ObjectPropertyName]
About
AddMarker
AlignFile
AllocateLoads
BatchEdit
BuildY
BusCoords
CalcVoltageBases
Capacity
CDDirectoryname
CktLosses
Clear
Close[Object][Term][Cond]
CloseDI
Comparecases
CompileorRedirect[fileName]
Currents
DI_plot
Disable[Object]
Distribute
DOScmd/c...commandstring...
Dump<CircuitElement>[Debug]
Edit[Object][EditString]
Enable[Object]
Estimate
Export<Quantity>[Filenameorswitch]
Fileedit[filename]
Formedit[Class.Object]
Get[Opt1][opt2]etc.
Guids
Help
Init
Interpolate{All|MeterName}
LatLongCoords
60
60
60
61
61
61
61
62
62
62
62
62
63
63
63
63
63
63
64
64
64
64
64
64
65
65
65
66
66
66
67
67
68
69
69
69
69
69
Page 5 of 180
OpenDSS Manual
June 2013
Losses
MakeBusList
MakePosSeq
More|M|~|[EditString]
New[Object][EditString]
[ObjectPropertyName]=value
NodeDiff
Obfuscate
Open[Object][Term][Cond]
PhaseLosses
Plot(options)
Powers
Pstcalc
ReconductorLine1=name1Line2=name2{Linecode=|Geometry=}
Redirect[filename]
Reduce{All|MeterName}
Rephase
ReprocessBuses
Reset{Meters|Monitors}
Rotateangle=degrees
Sample
Save
Select[elementname][terminal]
SeqCurrents
SeqPowers
SeqVoltages
Set[option1=value1][option2=value2](Options)
SetkVBase[bus=][kvll=..]
Show<Quantity>
Solve[seesetcommandoptions]
Summary
Totals
UpdateStorage
Variable
Varnames
VarValues
Vdiff
Visualize
Voltages
YearlyCurves
Ysc
Zsc
Zsc10
ZscRefresh
69
69
69
70
70
71
72
72
72
72
72
75
75
75
76
76
76
77
77
77
77
77
78
78
78
78
78
78
79
80
81
81
81
81
81
81
81
81
82
82
82
82
83
83
OPTIONSREFERENCE......................................................................................................................................84
%growth=
84
%mean=
84
%Normal=
84
Page 6 of 180

%stddev=
Addtype=
Algorithm=
AllocationFactors=
AllowDuplicates=
AutoBusList=
Basefrequency=
Bus=
capkVAR=
casename=
Cfactors=
circuit=
CktModel=
Class=
ControlMode=
Datapath=
DefaultBaseFrequency=
DefaultDaily=
DefaultYearly=
DemandInterval=
DIVerbose=
EarthModel=
Editor=
Element=
Emergvmaxpu=
Emergvminpu=
Frequency=
Genkw=
GenMult=
Genpf=
h=
Harmonics=
Hour=
KeepList=
LDcurve=
LoadModel=
LoadMult=
Log=
LossRegs=
LossWeight=
Markercode=
Markswitches=
Marktransformers=
Maxcontroliter=
Maxiter=
Mode=
Mode=Snap:
Mode=Daily:
OpenDSS Manual
June 2013
84
84
84
84
85
85
85
85
85
85
85
86
86
86
86
86
86
87
87
87
87
87
87
87
87
87
87
87
88
88
88
88
88
88
88
88
88
89
89
89
89
89
90
90
90
90
90
90
Page 7 of 180

Mode=Direct:
Mode=Dutycycle:
Mode=Dynamics:
Mode=FaultStudy:
Mode=Harmonics:
Mode=Yearly:
Mode=LD1
Mode=LD2
Mode=M1
Mode=M2
Mode=M3
Mode=MF
Mode=Peakdays:
Nodewidth=
Normvmaxpu=
Normvminpu=
NumAllocIterations=
Number=
Object(orName)=
Overloadreport=
PriceCurve=
PriceSignal=
Random=
Recorder=
ReduceOption=
Sec=
ShowExport=
Stepsize(orh)=
Switchmarkercode=
Terminal=
Time=
tolerance=
TraceControl=
TransMarkerCode=
TransMarkerSize=
Trapezoidal=
Type=
Ueregs=
Ueweight=
Voltagebases=
Voltexceptionreport=
Year=
ZoneLock=
OpenDSS Manual
June 2013
90
91
91
91
91
91
91
92
92
92
92
92
93
93
93
93
93
93
93
93
93
94
94
94
94
94
95
95
95
95
95
95
95
95
95
96
96
96
96
96
97
97
97
GENERALOPENDSSOBJECTPROPERTYDESCRIPTIONS.........................................................................98
LINECODE....................................................................................................................................................98
LINEGEOMETRY...........................................................................................................................................100
LINECONSTANTSEXAMPLES..........................................................................................................................101
Page 8 of 180
OpenDSS Manual
June 2013
LOADSHAPE................................................................................................................................................101
GROWTHSHAPE..........................................................................................................................................103
TCC_CURVE...............................................................................................................................................104
WIREDATA.................................................................................................................................................105
SOURCEANDOTHEROBJECTS...........................................................................................................107
VSOURCEOBJECT........................................................................................................................................107
ISOURCEOBJECT..........................................................................................................................................109
FAULTOBJECT............................................................................................................................................110
POWERDELIVERYELEMENTS(PDELEMENT).......................................................................................112
CAPACITOROBJECT......................................................................................................................................112
LINEOBJECT...............................................................................................................................................114
REACTOROBJECT........................................................................................................................................117
TRANSFORMEROBJECT.................................................................................................................................120
GICTRANSFORMEROBJECT...........................................................................................................................122
GeneratorStepUpBanks
ThreeWindingTransformers
Autotransformers
122
123
125
POWERCONVERSIONELEMENTS(PCELEMENT).................................................................................129
GICLINEOBJECT.........................................................................................................................................129
LOADOBJECT..............................................................................................................................................132
GENERATOROBJECT....................................................................................................................................136
GeneratorDynamicsModel
139
STORAGEOBJECT......................................................................................................................................140
Examples
145
CONTROLELEMENTS.........................................................................................................................146
CAPCONTROLOBJECT..................................................................................................................................146
REGCONTROLOBJECT..................................................................................................................................149
METERELEMENTS.............................................................................................................................152
ENERGYMETEROBJECT................................................................................................................................152
Registers
MeterZones
ZonesonMeshedNetworks
Sampling
EENandUEDefinitions
EnergyMeterEENandUERegisters
Registers9and10:OverloadEENandUE
Properties
152
153
154
155
156
156
157
158
MONITOROBJECT.......................................................................................................................................160
DEFAULTCIRCUIT..............................................................................................................................162
EXAMPLES.........................................................................................................................................163
EXAMPLECIRCUIT1.....................................................................................................................................163
DSSCircuitDescriptionScript
163
EXAMPLECIRCUIT2.....................................................................................................................................165
DSSCircuitDescriptionScript
165
Page 9 of 180
OpenDSS Manual
June 2013
COMINTERFACEREFERENCE.............................................................................................................167
DSSINTERFACE...........................................................................................................................................168
bOK=DSSObj.Start(0)
ActiveCircuit
ActiveClass
AllowForms
Circuits
Classes
ClearAll
DataPath
DefaultEditor
DSSProgress
Error
Events
Executive
NewCircuit
NumCircuits
Reset
SetActiveClass(ClassnameasString)
ShowPanel
Text
UserClasses
Version
168
168
168
168
168
168
168
169
169
169
169
169
169
169
169
169
169
169
169
169
170
EXAMPLEMSEXCELVBACODEFORDRIVINGTHECOMINTERFACE....................................................................171
Declarations
171
Startup
171
CompilingtheCircuit
171
SolvingtheCircuit
172
BringingResultsintotheSpreadsheet
172
EXAMPLE:OBTAININGALLCAPACITORNAMESANDLOCATIONSINMICROSOFTEXCELVBA.......................................176
EXAMPLE:GICCALCULATION........................................................................................................................177
OpenDSSScriptforExampleSystem
179
Page 10 of 180
OpenDSS Manual
June 2013
Figures
FIGURE1.OPENDSSSTRUCTURE..........................................................................................................15
FIGURE2.OPENDSSENGINEINTHEWINDOWSREGISTRY.....................................................................22
FIGURE3.GUIDPOINTSTOTHEINPROCESSSERVERFILE(OPENDSSENGINE.DLL)................................22
FIGURE4.OPENDSSVALUESINREGISTRY............................................................................................23
FIGURE5.EXAMPLEOFTHECONTROLPANELWINDOWFORTHEDSS..................................................31
FIGURE6.DOCOMMANDANDSPEEDBUTTONS..............................................................................31
FIGURE7.COMPILINGAFILECONTAININGACIRCUITDESCRIPTIONSCRIPTFROMASCRIPTWINDOWIN
THECONTROLPANEL...........................................................................................................................32
FIGURE8:COLORSHADEDHEATPLOTOFHARMONICRESONANCE..................................................36
FIGURE9:THICKNESSWEIGHTEDPLOTOFHARMONICRESONANCE....................................................37
FIGURE10.VOLTAGEPROFILEPLOTFROMIEEE8500NODETESTFEEDER............................................38
FIGURE11:ELECTRICALCIRCUITWITHCOMMUNICATIONSNETWORK.................................................40
FIGURE12:BUSDEFINITION................................................................................................................41
FIGURE13:TERMINALDEFINITION......................................................................................................42
FIGURE14:POWERDELIVERYELEMENTDEFINITION............................................................................46
FIGURE15:POWERCONVERSIONELEMENTDEFINITION......................................................................47
FIGURE16.COMPENSATIONCURRENTMODELOFPCELEMENTS(ONELINE).......................................48
FIGURE17.OPENDSSSOLUTIONLOOP.................................................................................................49
FIGURE18:DEFINITIONOFCAPACITOROBJECT.................................................................................112
FIGURE19.THREEPHASEMODELOFAGENERATORSTEPUPTRANSFORMER....................................122
FIGURE20.GSUMODELINOPENDSS.................................................................................................123
FIGURE21.THREEPHASEMODELOFATHREEWINDINGTRANSFORMER(GROUNDEDWYE,
GROUNDEDWYE,DELTA)..................................................................................................................124
FIGURE22.TWOWINDINGANDTHREEWINDINGTRANSFORMERMODELINDSS............................124
FIGURE23THREEPHASEMODELOFATHREEWINDINGAUTOTRANSFORMER..................................125
FIGURE24.TWOWINDINGANDTHREEWINDINGAUTOTRANSFORMERMODELINDSS...................126
FIGURE25.GICLINEMODEL..............................................................................................................129
FIGURE26.SUBSTATIONLOCATIONCOORDINATES...........................................................................130
FIGURE27.NOMINALGENERATORMODELINDYNAMICSMODE.......................................................140
FIGURE28.DEFAULTMETERZONESFORASIMPLENETWORK............................................................155
FIGURE29.USINGADDITIONALMETERSTOCONTROLTHEDEFINITIONOFMETERZONES.................155
FIGURE30.DEFAULTCIRCUIT............................................................................................................162
FIGURE31.OPENDSSENGINECOMINTERFACEASSEENWITHMSEXCELVBA.....................................174
FIGURE32.VBAOBJECTBROWSERLISTINGOFTHEOPENDSSCIRCUITINTERFACE.............................175
FIGURE33.ONELINEDIAGRAMOFEXAMPLEGICSYSTEM................................................................177
Page 11 of 180
OpenDSS Manual
June 2013
TABLE1.GICEXAMPLESUBSTATIONLOCATIONANDGRIDRESISTANCE.............................................178
TABLE2.GICEXAMPLETRANSMISSIONLINEDATA...........................................................................178
TABLE3.GICEXAMPLETRANSFORMERDATA...................................................................................179
Page 12 of 180
OpenDSS Manual
June 2013
Summary
TheOpenDistributionSystemSimulator(OpenDSS,orsimply,DSS)isacomprehensiveelectrical
system simulation tool for electric utility distribution systems. OpenDSS refers to the open
sourceimplementationoftheDSS.Itisimplementedasbothastandaloneexecutableprogram
and an inprocess COM server DLL designed to be driven from a variety of existing software
platforms.Theexecutableversionhasabasictextbaseduserinterfaceonthesolutionengineto
assistusersindevelopingscriptsandviewingsolutions.
The program supports nearly all rms steadystate (i.e., frequency domain) analyses commonly
performedforutilitydistributionsystemsplanningandanalysis.Inaddition,itsupportsmany
newtypesofanalysesthataredesignedtomeetfutureneeds,manyofwhicharebeingdictated
by the deregulation of utilities worldwide and the advent of the smart grid. Many of the
features found in the program were originally intended to support distributed generation
analysisneeds.Otherfeaturessupportenergyefficiencyanalysisofpowerdelivery,smartgrid
applications,andharmonicsanalysis.TheDSSisdesignedtobeindefinitelyexpandablesothatit
canbeeasilymodifiedtomeetfutureneeds.
TheOpenDSSprogramhasbeenusedfor:
DistributionPlanningandAnalysis
GeneralMultiphaseACCircuitAnalysis
AnalysisofDistributedGenerationInterconnections
AnnualLoadandGenerationSimulations
RiskbasedDistributionPlanningStudies
ProbabilisticPlanningStudies
SolarPVSystemSimulation
WindPlantSimulations
NuclearPlantStationAuxiliaryTransformerModeling
DistributionAutomationControlAssessment
ProtectionSystemSimulation
StorageModeling
DistributionFeederSimulationwithAMIData
DistributionStateEstimation
GroundVoltageRiseonTransmissionSystems
GeomagneticallyInducedCurrents(GIC)
EVImpactsSimulations
CosimulationofPowerandCommunicationsNetworks
AnalysisofUnusualTransformerConfigurations
HarmonicandInterharmonicDistortionAnalysis
NeutraltoearthVoltageSimulations
DevelopmentofIEEETestfeedercases
PhaseShifterSimulation
ArcFurnaceSimulation
ImpulseLoads(carcrushers,etc.)
Andmore.
Page 13 of 180
OpenDSS Manual
June 2013
Theprogramhasseveralbuiltinsolutionmodes,suchas
SnapshotPowerFlow
DailyPowerFlow
YearlyPowerFlow
Harmonics
Dynamics
Faultstudy
MonteCarloFaultstudy
Andothers
Thesemodeswereaddedastheprogramevolvedtomeettheanalysisneedsofspecificprojects
theauthorswereinvolvedwith.However,theprogramwasdesignedwiththerecognitionthat
developers would never be able to anticipate everything users will want to do with it. A
Component Object Model (COM) interface was implemented on the inprocess server DLL
version of the program to allow knowledgable users to use the features of the program to
performnewtypesofstudies.
ThroughtheCOMinterface,theuserisabletodesignandexecutecustomsolutionmodesand
features from an external program and perform the functions of the simulator, including
definitionofthemodeldata.Thus,theDSScouldbeimplementedentirelyindependentlyofany
database or fixed text file circuit definition. For example, it can be driven entirely from a MS
Office tool through VBA, or from any other 3rd party analysis program that can handle COM.
UserscommonlydrivetheOpenDSSwiththefamiliarMathworksMATLABprogram,Python,C#,
R, and other languages. This provides powerful external analytical capabilities as well as
excellentgraphicsfordisplayingresults.
Manyusersfindthetextscriptinginterfaceofthestandaloneexecutableversionsufficientfor
nearlyalltheirwork.Asusersfindthemselvesrepeatedlyneedingafeaturefortheirwork,the
featureisimplementedwithinthebuiltinsolutioncontrolmoduleandconnectedtothetext
basedcommandinterface.
TheCOMinterfacealsoprovidesdirectaccesstothetextbasedcommandinterfaceaswellas
access to numerous methods and properties for accessing many of the properties of the
simulator's models. Through the textbased command interface, userwritten programs can
generatescriptstodoseveraldesiredfunctionsinsequence.Theinputmayberedirectedtoa
text file to accomplish the same effect as macros in programming environments and also
provide some databaselike characteristics (although the program does not technically have a
database). Many of the results can be retrieved through the COM interface as well as from
various output files. Many output or export files are written in CommaSeparated Value (CSV)
format that import easily into other tools such as Microsoft Excel or MATLAB for post
processing.
TheexperiencedsoftwaredeveloperhastwoadditionaloptionsforusingtheOpenDSStool:
1. Downloadingthesourcecodeandmodifyingittosuitspecialneeds.
2. Developing DLLs that plug into generic containers the OpenDSS provides. This allows
Page 14 of 180
OpenDSS Manual
June 2013
developerstoconcentrateonthemodelofthedeviceofinterestwhilelettingtheDSS
executivetakecareofallotheraspectsofthedistributionsystemmodel.SuchDLLscan
bewritteninmostcommonprogramminglanguages.
ThenominalOpenDSSstructureisdepictedinFigure1
Figure 1. OpenDSS Structure
AtVersion7.6,a64bitversionofthe programwasintroducedtoaccommodatetheneedsof
usersneedingtoaccesstheprogramfroma64bitprogramortorunverylargemodels.Both
the 32bit and 64bit versions can coexist on the same computer to support users who need
both versions. For example, MATLAB is frequently installed as a 64bit app while Microsoft
Office programs are frequently installed as 32bit applications. Windows will automatically
selecttheproperversionofOpenDSS.
Page 15 of 180
OpenDSS Manual
June 2013
Brief History and Objectives of OpenDSS

DevelopmentoftheOpenDSSprogrambeganinApril1997atElectrotekConcepts,Inc.Atthat
timetheprogramwassimplycalledDSSforDistributionSystemSimulator.RogerDuganwas
theprincipalauthorofthesoftwaresupportedshortlythereafterbyTomMcDermott.Thetwo
comprised the development team until late 2001 when Tom left Electrotek. Roger continued
maintainingandevolvingtheprogramaloneuntilrecentlywhenTomagainbecamepartofthe
developmentteamthroughtheOpenDSSproject.TheDSShadbeenacquiredbyEPRISolutions
in2004,whichwasunitedwithEPRIin2007.In2008,EPRIreleasedthesoftwareunderanopen
sourcelicensetocooperatewithothergridmodernizationeffortsactiveintheSmartGridarea.
ThereweretwoeventsthattriggeredthedevelopmentoftheDSSin1997:
1. EPRI had issued an RFP earlier for software to support the application of distributed
generationtodistributionsystems.WhileElectrotekwasnotawardedacontractthere
hadbeen enoughthinkingaboutthe projecttohavearrivedatafunctional specfora
simulator that would support the vast majority of electrical system analysis for
evaluatingDGfordistributionplanningpurposes.
2. RogerDuganwasservingasChairoftheIEEEPESSoftwareEngineeringWorkingGroup
and one of the hot topics at that time was objectoriented programming and data
representations.ThelateMarkEnnsofElectroconhadissuedachallengetothegroup
for someone to implement some of the principles we had been discussing in a power
systemanalysisprogram.Thedistributionsystemsimulatorconceptseemedtheperfect
vehicletoexperimentwithsomeofthoseideasandalsoprovideausefultooltosupport
the needs of a consulting company that was involved in leadingedge research in
distributionsystemanalysis.
Prior to 1997, Electrotek had been performing DG studies for distribution planning using
conventionaldistributionsystemanalysismethodsthatarestillemployedbymanytoolstoday.
We were well aware of the limitations of these methods and wanted a tool that was more
powerfulandflexible.OneissuewediscoveredearlyonisthatnotwoDGplanningstudieswere
exactlyalikeandwewerefrequentlyhavingtoadjustourmodelsandaddnewfeaturestoour
tools. Thus, we needed a tool that would not lock us in to particular types of analysis. Other
issueswesetouttoaddresswere:
1. The distribution system model data we received from utilities came in all sorts of
different formats, each with various strengths and various modeling limitations. One
design goal was to develop an objectoriented circuit description language that
minimizedtheconversioneffort.
2. Windowbased programs can be very user friendly, but we noticed some of the
distribution system analysis tools really limited what you can do by limiting the
interaction to what is available on the dialog forms. By being fundamentally script
driven, the DSS program approach gets around much of the limiteddialog issue and
allowstheusertobetteradapttheanalysisprocesstotheproblemathand.
3. The greater value of DG is often found on the subtransmission system serving a
distribution planning area. Many distribution planning tools represent only the radial
distribution system. Because of the methods employed by the economists we were
Page 16 of 180
OpenDSS Manual
June 2013
working with at the time, we wanted a tool that would allow us to model several
substations and the distribution circuits between them simultaneously. This is actually
the concept of distribution used by much of the rest of the world outside North
America.
4. A key capability desired for the tool was to capture both the time and location
dependentvalueofDG.ThelocationdependentvalueiscapturedbymodelingtheDG
in its actual location on the circuit. Capturing the timedependent value requires
extraordinaryloadshapemodelingcapabilitytosupportsequentialtimesimulations.
5. There are many instances where it becomes necessary to model elements with many
phasesnotjustone,two,orthree.Forexample,powerpolesinNorthAmericawith
multiple circuits may have as many as 4 circuits sharing a common neutral. Also, we
wanted to be able to model what happens when a 69 kV line falls into the 13.2 kV
distributionline.Ortomodelacommunicationssignalpassingfromonevoltagelevelto
anotherthroughtheinterwindingcapacitanceofthetransformerthiswasnotpossible
withmanytraditionaldistributionsystemanalysistools.
6. Wewantedatoolthatcouldseamlesslyincorporateharmonicsanalysisintothepower
flow analysis without requiring the user to laboriously enter nonlinear device models.
Wealsorecognizedthatwewouldneedatleastsimpledynamicsanalysissufficientfor
DG interconnection evaluation. Simple dynamics models are presently built in to the
programandthisfeaturecontinuestobedeveloped.
7. Recognizingthatdistributionautomationwasgoingtobecomeincreasinglyimportant,
wewantedatestbeduponwhichtoevaluatecontrolalgorithmsandtheirimpactonthe
operationofthesystem.
8. Recognizing that it was impossible to satisfy all possible user needs, we wanted a
program that would allow users to write their own models or solution procedures
commensuratewiththeircapabilities.
9. Wewantedaprogramthatwouldsimulatethebehaviorofdevicesonthedistribution
system as they would actually occur for changing load and system faults and other
disturbances.ThisisimportantformodelingDGinteractionsanditalsoallowsthetool
tobeusedformanyotherthingsaswell,suchasenergyefficiencyanalysis.
ThepresentversionoftheOpenDSShasachievedthemajorityofthesegoalsandhasevolved
intoanextraordinarytoolthathasacquiredmanyotherfeaturesnotcommonlyfoundinother
distributionsystemanalysistools.WhileDGanalysiscontinuestobeoneofitskeyuses,many
othertypesofanalysishavebeenperformedwiththetool.Newfeaturesarecontinuallybeing
addedtosupportongoingresearch.
TheOpenDSSisageneralpurposefrequencydomainsimulationenginethathasspecialfeatures
for creating models of electric power distribution systems and performing many types of
analysesrelatedtodistributionplanningandpowerquality.Itdoesnotperformelectromagnetic
transients(timedomain)simulations;alltypesofanalysisarecurrentlyinthefrequencydomain
(i.e., sinusoidal steady state, but not limited to 60 Hz). It does perform electromechanical
transients,ordynamicsanalysis.
Most electrical engineers learned how to write nodal admittance equations in their early
University courses, and this is how the DSS represents circuits. Each element of the system is
Page 17 of 180
OpenDSS Manual
June 2013
represented by a primitive nodal admittance (Y) matrix. This is generally straightforward,

althoughitcanbetrickyforsomepowersystemelementssuchastransformers.EachprimitiveY
isthencoalescedintoonelargesystemYmatrix,andthesystemofequationsrepresentingthe
distributionsystemissolvedusingsparsematrixsolvers.Onetrickisthatnonlinearbehaviorsof
some devices (e.g., some load models) are modeled by current source injections, which some
refertoascompensationcurrents.Thatis,thecurrentpredictedfromthelinearportionofthe
modelthatresidesinthesystemYmatrixiscompensatedbyanexternalinjectiontoiteratively
obtain the correct current. This is a common technique for representing loads in distribution
system analysis tools. One advantage of this method is that it allows for quite flexible load
models, which is important for performing some types of analysis such as done in energy
efficiencystudies.
The programs heritage is closer to a harmonic flow analysis program, or even a dynamics
program,thanatypicalpowerflowprogram.Thismayseemastrangeplacetostartdesigninga
tool that will be used mostly for power flow studies, but it gives the tool great modeling
flexibility, particularly for accommodating all sorts of load models and unusual circuit
configurations.Itiseasiertomakeaharmonicsflowsimulationprogramsolvethepowerflow
problemthantheopposite.
W HY D ELPHI ?
ThetopstructureoftheOpenDSSthatmaintainsthedatadefinitionsofthecircuitelementsis
written in Object Pascal using the Delphi environment (originally from Borland, now from
Embarcadero.com).ThevarioussparsematrixsolversemployedbytheDSSovertheyearshave
beenwritteninCandC++.
SincePascalisseldomtaughtinengineeringeducationanymore,weareoftenasked why we
used Delphi. At the time the DSS was started, the main developer, Roger Dugan, had been
tinkeringwiththerelativelynew32bitversionsofDelphiforacoupleofyearsandwantedto
tryitonalarge,hardworkingengineeringprogramthatwouldnothavetheusualfixedproblem
sizelimitationsoftypicalengineeringprogramsofthetime.Arapiddevelopmentenvironment
wasneededbecausehewasalsodoingengineeringworkandtheDSSwasmainlydevelopedin
sparetime.AnotherreasonstemsfromthedesiretohaveaCOMinterfacetoalloweasyaccess
fromotherprograms.Delphiprovidedaneasywaytobuildtheseinterfacesearlyon.Themain
alternative at the time would have been Visual Basic, but the performance of VB was not
acceptable. Fortunately, when Tom McDermott joined Electrotek a few months later, he also
knewPascalandwasabletocontributeimmediatelytothedevelopment.Thus,thediewascast
andthemainpartoftheprogramhasremainedinDelphiasithasevolved.
While the choice of programming languages is largely one of personal preference, here are a
fewthingsthatmightbeconsideredadvantageswithDelphi:
1. Thecompilerisfast.Atypicalfullbuildofthe60,000+lineprogramtakesonlyabout10
15seconds.Rebuildsareevenfaster.Thisallowsfastdebugandtestcycles.
2. Bydefault,theprogramiscompletelylinkedintoonerelativelycompactEXEfileandcan
beinstalledsimplybycopyingtheprogramtoadesireddisklocation.Thishasmadeit
convenient to distribute new versions to users. No complicated installs. (The 64bit
version has introduced some complications, but installs can still be accomplished
Page 18 of 180
OpenDSS Manual
June 2013
manuallyifdesired.)
3. Thetextprocessingspeedforreadingcircuitscriptshasexceededexpectationsandhas
proven more than adequate for the task. Our previous experience with other
engineeringprogramshadledustobelievethiswasgoingtobeaproblem,butwewere
pleasantlysurprisedthatitwasnot.YoushouldfindthattheOpenDSSprocesseslarge
circuitdescriptionscriptswithrelativeease.Themathprocessingspeedappearstobe
comparabletoanycompiledprogramminglanguage.Thishasimprovedovertheyears
as the Delphi environment has introduced function inlining, which is exploited in the
program.
4. WritingCOMinterfacesandDLLsarerelativelyeasytasksforaprogrammer.
5. The structure of the Pascal language enforces a discipline that helps avoid the
introductionofbugs.Mostofthetime,onceyoucangetittocompileitwillwork.You
shouldalsofindthecodefairlyreadable.Soifyouareonlyinterestedinseeinghowwe
didsomething,itshouldbeeasytounderstand.
WhilewedevelopusingtheprofessionalDelphiversion,thereareopensourcePascalcompilers
available on the Web, such as Free Pascal/Lazarus, that we strive to maintain as much
compatibilitywithaspossible.
Page 19 of 180
OpenDSS Manual
June 2013
Installation
ThisinstallationprocedureappliestoVersion7.6andlaterversions.
The7.6versionisthefirstto bedeliveredinboth 32bit (X86) and64bit (X64)versions. The
OpenDSSInstallerdownloadincludesboth,alongwithoptionaldocumentationandexamples.
If you have 64bit Windows, you may install both the 64bit and 32bit versions. The 32bit
version is required if you plan to automate OpenDSS from Excel or any other 32bit program.
The64bitversionisrequiredtoautomateOpenDSSfromMatLabona64bitsystem.
The installer will give you a choice to install the executables and optional files under a target
directoryofyourchoice,suchasc:\opendss.Filesthatarespecifictothe32bitversionwillbe
written to an x86 subdirectory, such as c:\opendss\x86. Files that are specific to the 64bit
version will be written to an x64 subdirectory, such as c:\opendss\x64. The EXE and DLL files
shouldnotbemovedafterinstallation,butmaybeupdatedinplacewithnewerversions.
Ona64bitsystem,youmayinstallanduseboththe32bitand64bitversionswithnoconflict
betweenthem.
ShortcutstotheprogramandmanualarecreatedunderStartMenu/OpenDSS.
Themostuptodatereferenceinformationonobjectsandtherepropertieswillalwaysbefound
throughthesoftware's"Help/DSSHelp"menucommand.
COM A UTOMATION
TheCOMServerinOpenDSSEngine.DLLmaybeautomated.Theinstallerwillregistereitheror
both versions, depending on your selection. Even though the file names and registration
commandsmatch,theyareinseparatelocationsandWindowswillactivatethecorrectversion
required by the calling program. For example, 64bit MATLAB will call the 64bit
OpenDSSEngine.DLLand32bitMicrosoftExcelwillcallthe32bitversion.
(Note:The64bitversionofExcelisrarelyinstalled.)
F ILES
Althoughithasgottenalittlemorecomplicated,installationoftheOpenDSSprogramisstillone
oftheeasiestyouwillencounterinprogramstoday:Simplycopytheprogramfilestoafolderof
yourchoosing(suchasC:\OpenDSSorC:\Users\MyUserName\OpenDSS)andstarttheprogram.
Thefollowingarethekeyprogramfiles:
1. OpenDSS.exe (Standaloneexecutable)
2. OpenDSSEngine.DLL
(TheinprocessCOMserverversion)
3. KLUSolve.DLL (Sparsematrixsolver)
4. DSSView.exe
(ViewerforDSSgraphicsoutput)
Page 20 of 180
OpenDSS Manual
June 2013
TheOpenDSSEngine.DLLserverwillhavetoberegisteredifyouintendtoaccessitfromother
programs/languagessuchasMATLABandVBAinMSOffice.Thiswilloccurautomaticallyifyou
usetheinstallerfromthedownload.IfyoudonotintendtoautomateOpenDSS,andsimplyuse
theexeversion,youmayskipthisstep.
Youcanmanuallyregistertheserverbyissuingthefollowingcommandtothe(DOS)command
promptwheninthefolderyouhaveplacedthefiles:
Regsvr32
OpenDSSEngine.DLL
Note:YoumayneedAdministratorprivilegesonyourcomputertodothis.Thismoreevidenton
Windows7andVistathanWindowsXP.(Seebelow.)
TheRegisterDSSEngine.BATfileprovidedwithinthestandardzipfiledownloadtoperformthis
action.Registrationneedonlybedoneonce.Youmaysimplydoubleclickonthe.BATfileandit
willexecutetheregistration.
OnWindowsVistaand7youwillhavetoexecutethe.BATfilefromanelevatedAdminstatus.
OnewaytodothisisgotoAllPrograms>AccessoriesandrightclickontheCommandPrompt
andselectRunasAdministrator.Thenrunthe.BATfile.
Afterregistration,ifyoustarttheWindowsregistryeditor(Typeregeditinthecommandbox
onthestartmenu)youwillfindtheOpenDSSEnginelistedunderClassesasshowninFigure2.If
youthenlookuptheGUIDintheregistry,itshouldpointtotheOpenDSSEngine.DLLfileinthe
folderwhereyouinstalledit(Figure3).
The OpenDSSEngine will show up as OpenDSS Engine or OpenDSSEngine.DSS in the list of
availableobjectreferencesinmostdevelopmentenvironments.Forexample,toinstantiatean
OpenDSSEngineobjectinMATLAB,youwouldissuethefollowingstatement:
%instantiate the DSS Object
Obj = actxserver('OpenDSSEngine.DSS');
Whenboththe32bitand64bitversionsareavailable,Windowswillloadtheappropriateone
foryourapplication.
ExceptforthetwoDLLsindicated,theprograminitspresentformiscompletelyselfcontained.
If you are solely interested in creating scripts and executing the program manually, you can
simply start the EXE file and operate the OpenDSS through the user interface provided. Most
usersfindthismodeadequatemostofthetime.Forconvenience,youmightdragashortcutto
the desktop or some other convenient spot. You may also pin the EXE file to your startmenu
(rightclickontheEXEfileandlookatyouroptions).
Page 21 of 180
OpenDSS Manual
June 2013
GUID
TheServershowsupasOpenDSSEngine.DSSinthe
WindowsRegistry
Figure 2. OpenDSSEngine in the Windows Registry
Figure 3. GUID points to the In-Process Server File (OpenDSSEngine.DLL)
Thekeyshownisforthe64bitversionCLSIDon Windows7pointing totheserverinthex64

folder.Thefullregistrykeyis:
HKEY_CLASSES_ROOT\CLSID\{6FE9D1B8-C064-4877-94C0-F13882ADBDB6}
Notethaton64BitWindows7systems,the32bitserverversionCLSIDwillberegisteredunder
theWow6432Nodekeywithakeylikethis:
HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{6FE9D1B8-C064-4877-94C0-F13882ADBDB6}
Thisistheregistrykeyforthe32bitWindowsonWindows(WoW)partoftheregistry.Thisis
howWindowsknowswhichversionoftheservertoloadeventhoughtheGUIDsarethesame.
Page 22 of 180
OpenDSS Manual
June 2013
O THER R EGISTRY E NTRIES

Note: The .ini files that were created in previous versions no longer exist. The Windows
Registry is now used for this purpose. The values are stored under the
HKEY_USERS/Software/OpenDSSkey.SeeFigure4.
Thepurposeofsavingthesevaluesistorememberthecontentsoftheusercontrolpanelsand
someglobalsettingssuchasthedefaultBaseFrequencyandthepathfortheuserspreferred
editor. Thus, the program will start the next time with the same script window contents and
defaultsasattheendoftheprevioussessionthatissuccessfullyclosed.
Figure 4. OpenDSS Values in Registry
O THER F ILES
DSSView.EXE is a custom 32bit program that can read special output files from the OpenDSS
Plot command and display simple charts and graphs. The program is automatically started by
theOpenDSSPlotcommandoryoumaystartitatanytimeandaccesspreviouslycreated.DSV
files.OpenDSSdoesnothavetoberunningtoreproducetheseplots.Manyofthesesamecharts
can be reproduced in MATLAB and other program from data exported using the Export
commandorbyaccessingthevaluesthroughtheCOMinterface.SeethePythonexamples.
IndMach012.DLL is a DLL file containing a special symmetrical component (012) model of an
inductionmachinethatcanbeconnectedtoaGeneratorobjectmodel.Thisisprovidedbothas
aworkingmodelandasanexampleofhowtobuildsuchaDLL.Thesourcecodeisprovidedon
theSourceForge.Netsite.
Examples, Docs, and Test Cases

Inadditiontotheprogramdownloads,thereareexampleanddocumentationdownloads.These
are available as a compressed file download on the main OpenDSS download site or you may
selectivelydownloadfoldersandfilesdirectlyfromthesourcecoderepository.Thecontentsof
theExamplefoldersare:
Excel: Examples of use Microsoft Excel to access the COM interface. You will need to
allowmacrostoexecute.
Page 23 of 180
OpenDSS Manual
June 2013
GICExample:Examplescriptsforgeomagneticallyinducedcurrent(GIC)testcase.
LoadShapes: Several typical annual distribution system loadshapes. Also, solar PV

loadshapes.
Manual:Examplesfromthisdocument.
Python:SomePythoncodeexamplesforaccessingtheCOMinterface.
Scripts: Several script templates for common, and uncommon, simulation processes.
Someconductor(wire)data,too.
Stevenson:ScriptsforthepowerflowcasefromtheW.Stevensontextbook.
IntheDocsfolderareseveraldocumentsthatsupplementtheinformationfoundinthisUsers
Manual.
TheIEEETestCasesfoldercontainsimplementationsofmostoftheIEEETestFeedersandother
IEEEtestcasesinDSSscriptformat.Formoreinformationonthese,gotothisURL:
http://www.ewh.ieee.org/soc/pes/dsacom/testfeeders/index.html
TheEPRITestCircuitfolderscontainsDSSscriptversionsofdistributioncircuitmodelsthathave
beenmadeavailableforpublicuse.
Page 24 of 180
OpenDSS Manual
June 2013
Summary of Simulation Capabilities

ThepresentversionoftheDSSiscapableofperformingthefollowinganalyses/simulations:
P OWER F LOW
Whilethepowerflowproblemisprobablythemostcommonproblemsolvedwiththeprogram,
the OpenDSS is not best characterized as a power flow program. Its heritage is from general
purpose power system harmonics analysis tools. Thus, it works differently than most existing
powerflowtools.Thisheritagealsogivesitsomeuniqueandpowerfulcapabilities.Theprogram
was originally designed to perform nearly all aspects of distribution planning for distributed
generation (DG), which includes harmonics analysis. It is relatively easy to make a harmonics
analysis program solve a power flow, while it is quite difficult to make a power flow program
performharmonicsanalysis.Tolearnmoreabouthowthealgorithmworksforthepowerflow
problem,seePuttingItAllTogetherbelow.
The OpenDSS is designed to perform a basic distributionstyle power flow in which the bulk
powersystemisthedominantsourceofenergy.However,itdiffersfromthetraditionalradial
circuit solvers in that it solves networked (meshed) distribution systems as easily as radial
systems.Itisintendedtobeusedfordistributioncompaniesthatmayalsohavetransmissionor
subtransmission systems. Therefore, it can also be used to solve small to mediumsized
networkswithatransmissionstylepowerflow.
The circuit model employed can be either a full multiphase model or a simplified positive
sequence model. The default is the full multiphase model. For capacity studies, the latter is
often sufficient and will execute faster. Due to the complex multiphase models that may be
createdwithmyriadunbalances,theusermayhavetocreatepositivesequencemodelsoutside
theDSSbydefiningasinglephasemodelofthecircuit.However,theMakePosSeqcommand
with attempt to convert a multiphase model to a positivesequence model. By setting the
properflag,allpowerreportsforapositivesequenceequivalentwillreport3phasequantities.
The power flow executes in numerous solution modes including the standard single Snapshot
mode, Daily mode, Dutycycle Mode, Monte Carlo mode, and several modes where the load
variesasafunctionoftime.(SeetheHelpcommandforthe"Mode"optionfortheuptodate
listingofsolutionmodes).Thetimecanbeanyarbitrarytimeperiod.Commonly,forplanning
purposesitwillbea24hourday,amonth,orayear.Usersmayalsowriteexternalmacrosor
programstodrivetheloadmodelsinsomeothermanner.
When a power flow is completed, the losses, voltages, flows, and other information are
availableforthetotalsystem,eachcomponent,andcertaindefinedareas.Foreachinstantin
time,thelossesarereportedaskWlosses,forexample.Energymetermodelsmaybeusedto
integratethepoweroveratimeinterval,.
The power flow can be computed for both radial distribution (MV) circuits and network
(meshed)systems.Whiletheaccuracyofsomealgorithms,suchasthecalculationofexpected
unservedenergy,maydependonpartofthecircuitmodelbeingradial,thepowerflowsolution
isgeneral.Itworksbestonsystemsthathaveatleastonestiffsource.
Thetwobasicpowerflowsolutiontypesare
Page 25 of 180
OpenDSS Manual
June 2013
1. Iterativepowerflow
2. Directsolution
Fortheiterativepowerflow,loadsanddistributedgeneratorsaretreatedasinjectionsources.
IntheDirectsolution,theyareincludedasadmittancesinthesystemadmittancematrix,which
isthensolveddirectlywithoutiterating.Eitherofthesetwotypesofsolutionsmaybeusedfor
anyoftheseveralsolutionmodesbysettingtheglobalLoadModelpropertytoAdmittanceor
Powerflow(canbeabbreviatedAorP).ThedefaultisPowerflow.
Therearetwoiterativepowerflowalgorithmscurrentlyemployed:
1. "Normal"currentinjectionmode
2. "Newton"mode.
TheNormalmodeisfaster,buttheNewtonmodeissomewhatmorerobustforcircuitsthatare
difficult to solve. The default is Normal. The Normal mode method is a simple fixedpoint
iterative method and works well for nearly all distribution systems with a stiff bulk power
source.ItisthepreferredmethodforYearlymodesimulationsduetoitsspeed.
Typically,powerflowcalculationswilluseaniterativesolutionwithnonlinearloadmodels,and
faultstudieswilluseadirectsolutionwithlinearloadmodels.
F AULT S TUDIES
TheOpenDSSwillperformshortcircuitfaultstudiesinseveralways:
Aconventionalfaultstudyforallbuses("SetMode=Faultstudy"),reportingcurrentsand
voltagesonallphasesforalltypesoffaults:Allphasefault,SLGfaultsoneachphase,L
L and LLG faults. Since transformers will be represented in actual winding
configuration, this is an excellent circuit model debugging tool as well as a tool for
settingrelaysandsizingfuses.
Asinglesnapshotfault.Theuserplacesone,ormore,faultsonthesystematselected
buses,definingthetypeoffaultandthevalueofthefaultresistance.Afaultisacircuit
element (a resistor network) just like any other element and can be manipulated the
sameway.
Applying faults randomly. (Monte Carlo fault study mode solution mode= "MF").
User defines Fault objects at locations where faults are desired. The program
automaticallyselectsoneatatime.Thisisusefulforsuchanalysesasexaminingwhat
voltages are observed at a DG site for various faults on the utility system, computing
voltagesagindices,etc.
Page 26 of 180
OpenDSS Manual
June 2013
H ARMONIC F LOW A NALYSIS

The OpenDSS is a generalpurpose frequency domain circuit solver. Therefore, harmonic flow
analysisisquitenaturalandoneoftheeasiestthingstodowiththeprogram.Theuserdefines
variousharmonicspectratorepresentharmonicsourcesofinterest.(Thereareseveraldefault
spectra.) The spectra are connected to Load, Generator, voltage source (Vsource), current
source(Isource)objectsandafewotherpowerconversionelementsasdesired.Morerecently,
PVSystem and Storage models that contribute harmonics have been added. There are
reasonabledefaultspectraforeachoftheseelements.
Asnapshotpowerflowisfirstperformedtoinitializetheproblem.Thesolutionmustconverge
beforeproceeding.Ifconvergenceisdifficulttoachieve,adirectsolutionisgenerallysufficient
to initialize the harmonic solution. Harmonic sources are then initialized to appropriate
magnitudesandphasesanglestomatchthesolution.
Onceapowerflowsolutionisachieved,theusersimplyissuesthecommand:
Solve mode=harmonics
The OpenDSS then solves for each frequency presently defined for any of the harmonic
producingcircuitelements(theseareallpresentlyPowerConversionclasselements).Usersmay
also specify which harmonics are to be computed. Monitors are placed around the circuit to
capturetheresults.
Frequency sweeps are performed similarly. The user defines spectra containing values for the
frequencies (expressed as harmonics of the fundamental) of interest and assigns them to
appropriatevoltageorcurrentsources.Thesesourcesmaybedefinedtoperformthesweepsin
threedifferentways:
1. Positive Sequence: Phasors in 3phase sources maintain a positivesequence
relationship at all frequencies. That is, all three voltages and currents are equal in
magnitudeanddisplacedby120degreesinnormalABC,or123,rotation.
2. ZeroSequence:Allthreevoltagesorcurrentsareequalinmagnitudeandinphase.
3. Nosequence:Phasorsareinitializedwiththepowerflowsolutionandarepermittedto
rotateindependentlywithfrequency.Iftheyareinapositivesequencerelationshipat
fundamental frequency, they will be in a negative sequence relationship at the 2nd
harmonic,andazerosequencerelationshipatthe3rdharmonic,etc.Inbetweeninteger
harmonics, the phasors will be somewhere in between (the difficulty will be deciding
whatthatmeans!).
D YNAMICS
The OpenDSS can perform basic electromechanical transients, or dynamics, simulations. The
capabilityofOpenDSShasbeenexpandingsteadilyduetoneedsininvertermodelingandother
applications where machine dynamics are important. The original intent was to provide
sufficient modeling capability to evaluate DG interconnections for unintentional islanding
studies.ThebuiltinGeneratormodelhasasimplesinglemassmodelthatisadequateformany
DGstudiesforcommondistributionsystemfaultconditions.Inadditional,usersmayimplement
Page 27 of 180
OpenDSS Manual
June 2013
more sophisticated models by writing a DLL for the Generator model or by controlling the
Generatormodelfromanexternalprogramcontainingamoredetailedgovernorand/orexciter
model.
An induction machine model was developed and used to help develop the IEEE Test Feeder
benchmark dealing with large induction generation on distribution systems. This is called
IndMach01a.DLL and is provided with the program along with its source code for Delphi (it
couldbeanotherlanguage).Itcanperformbothpowerflowanddynamicssimulationsusinga
simplesymmetricalcomponentmodel.
L OAD P ARAMETRIC V ARIATION

Thecapabilitiesfordoingparametricevaluationareprovidedforavarietyofvariables.Certain
variableswillbeallowedtovaryaccordingtoafunction(e.g.,loadgrowth)orvaryrandomlyfor
Monte Carlo and statistical studies. See the Set Mode command documentation for
descriptionsoftheMonteCarlosolutionmodes.
G EOMAGNETICALLY I NDUCED C URRENT (GIC) A NALYSIS

OpenDSS is capable of performing geomagnetically induced current (GIC) analysis of power
systems. Currently, the analysis capability is limited to threephase systems, and cannot be
integratedintoothertypesofsimulations,e.g.loadflow.TheGICanalysistakesadvantageof
theNphasemodelingcapabilityofOpenDSStoperformtheanalysisonathreephasebasisas
opposedtoasinglephasebasis.
GIC are quasidc; thus, GIC simulations involve performing a low frequency (typically 0.1 Hz)
analysisoftheresultingdcnetwork.ThedrivingforcebehindtheflowofGICinthenetworkis
theinducedvoltageinthetransmissionlines1.Theinducedvoltageisgeneratedbythecoupling
of the transmission lines with the induced geoelectric field at the surface of the earth.
Specialized quasidc models, which are described in other sections of the manual, have been
added to the program circuit element models for transmission lines, transformers, substation
groundgrids,andGICblockingdevices.
OncethedcmodelofthenetworkhasbeenconstructedthefollowingtwoOpenDSScommands
areusedtoperformtheanalysis:
Set frequency=0.1
Solve
The solution frequency is set to 0.1 Hz and then a standard OpenDSS snapshot solution is
performed. The sources in the problem at this frequency are the voltages induced along the
lines.ThesesourcesarecontainedintheGICLinemodel.Transformersaremodeledbyspecial
transformermodelsusingtheGICTransformerelement.
D.H. Boteler, R.J. Pirjola, Modeling Geomagnetically Induced Currents Produced by Realistic and
Uniform Electric Fields, IEEE Transactions on Power Delivery, Vol. 13, No. 4, pp. 13031308, October
1998.
Page 28 of 180
OpenDSS Manual
June 2013
Page 29 of 180
OpenDSS Manual
June 2013
Basic Usage
O PEN DSS C ONTROL P ANEL
There is a multiplewindow "Control Panel" for constructing and testing scripts and executing
them.Themainaccesstoscriptsandresultsisgenerallythroughscriptfilesandoutputfilesor
the COM interface. However, you may put large scripts into a window on the Control Panel if
youwish.
Communication to the DSS is fundamentally accomplished through text strings passed to the
OpenDSS command processor. However, if you are driving the DLL inprocess COM server
version from another program, there are many functions provided in the COM interface to
directlyexecutecommoncommands(like"solve")andsetpropertiesofcircuitelementswithout
goingthroughthecommandlanguage.Thatmightbealittlefasterforsomeoperationsthatare
executedrepeated,althoughtheOpenDSScommandprocessorstextparsingisoftenmorethan
fastenoughformostapplications.
SimulationresultscanbereturnedasarraysofvaluesintheCOMinterfaceorintextthrough
CSV files. A few standard text file reports are provided by the base OpenDSS software
component (see Show and Export commands). The intent for users demanding more
sophisticated reports is for users to design them through Excel worksheets or whatever
applicationtheyusetocontroltheOpenDSSinspecialways.
The OpenDSS control panel automatically appears in the EXE version. The panel may also be
invoked from the OpenDSS COM interface using the Panel or Show Panel commands or the
ShowPanelmethodintheCOMinterface.
(Caveat:WheninvokedfromaMSExcelapplication,Excelmaytrapsomeofthekeystrokes,so
it doesn't always work as smoothly as it does in the standalone EXE application. This may
happen in other programs as well, but seems to work OK in userwritten software that is not
trappingkeystrokes.)
Thecontrolpanel(Figure5)isatypicalWindowsmultipledocumentinterface.Thereisaparent
window containing several child windows. In Figure 5, the windows are tiled. There can be
multiplescriptwindowsopenatanyonetime.Theusermayexecuteascript,oraportionofa
script, in any of the open windows at any time. This allows the user to organize scripts in a
logicalmannerandhavethemavailableatanytime.Allscriptsoperateonthepresentlyactive
circuit,ortheymaydefineanewcircuitthatbecomesactive.
Scripts or script fragments are executed by selecting the script lines to be executed. The user
canrightclickontheselectionandthenclickontheDoSelectedoption,whichhasashortcut
key(ctrld).TheselectionmayalsobeexecutedfromtheDomenuorthespeedbuttondirectly
belowtheDomenuitem(Figure6).
Ofcourse,thescriptinthewindowscanredirecttheOpenDSScommandinputtoafile,which
can, in turn, redirect to another file. Thus, scripts can be quite voluminous without having to
appearinawindowonthecontrolpanel.
Page 30 of 180
OpenDSS Manual
June 2013
Figure 5. Example of the Control panel window for the DSS
Figure 6. Do command and speed buttons
EachscriptwindowontheControlpanelimplementsaWindowsRichEdittextform.Thus,ithas
manyofthestandardtexteditingfeaturesonemightexpect.However,thirdpartytexteditors
(weuseEditplus)canprovidesubstantiallymorecapability.Itisrecommendedthatoneofthe
firstcommandstoissueafterstartingtheDSSforthefirsttimeis
SetEditor=filename
Wherefilenameisthefullpathnameofthetexteditoryouwishtouse.Thisshouldbeaplain
texteditor.EditorssuchasWordorWordpadmayaddtextthatisnotproperlyinterpretedby
OpenDSS. You may reformat the text in a window while the program is running, but these
formattingcommandsarenotsavedtotheDSSfile.
Page 31 of 180
OpenDSS Manual
June 2013
It is generally necessary to issue the Set Editor command only one time. The program will
rememberthisvalueintheWindowsRegistryafteritisshutdown.Likewise,thedefaultbase
frequency(50or60Hz)issetonetime.Theassumeddefaultbasefrequencyisdisplayedatthe
topofthemainscreen.Ifyouworkonbothtypesofsystems(aswedo),alwaysmakesureitis
settothecorrectvalue!
Whenauserrightclicksonafilenameinoneofthescriptwindows,thepopupmenugivesthe
usertheoptionofOpenorEditfortheselectedfile(Figure7).Openwillopentheselected
fileinanotherscriptwindowintheDSSprogram.EditwillopentheselectedfileintheEditor
oftheuserschoosing.IfnoEditorwasspecified,theprogramwillattempttoopentheNotepad
editorsuppliedwithWindows.
If the file name contains no blanks, one need only click anywhere within the file name to
executetheOpenorEditcommands.
Figure 7. Compiling a File containing a circuit description script from a script window in
the control panel.
YoumaychangethefontforawindowbyclickingtheFontbutton.Thesizeofthefontmost
recentlyusedisrememberedbytheprogram.Fontinformationisnotkeptwiththescriptfiles:
thesearesimpletextfiles.
E XPORT M ENU C OMMANDS

Thevoltageandcurrentexportshavebeenupdatedtobemoreconsistentandusefulwhenyou
loadthemintoExceloranotherprogram.
Theoutputtablesnowstretchouthorizontallyinsteadofvertically.Thisisalsodoneto
fitinbetterwithmodificationstothePlotcommand
Note:Currentexportsarekeyedondevice(CircuitElement)name
Page 32 of 180
OpenDSS Manual
June 2013
Note:Voltageexportsarekeyedonbusname
Residualvaluesarealsoprovided(sumofallconductorsornodesatabranchorbus).
This is also true for the sequence current and sequence voltage exports because the
residualscanbedifferentthanthezerosequencevalues.
Theexportoptionsinclude(checkthehelptherearefrequentlyupdated):
Export Command [Filename]
Export Voltages
Default File Name

EXP_VOLTAGES.CSV
Export SeqVoltages
EXP_SEQVOLTAGES.CSV
Export Currents
EXP_CURRENTS.CSV
Export Overloads
EXP_OVERLOADS.CSV
Export Capacity
EXP_CAPACITY.CSV
Export Estimation
EXP_ESTIMATION.CSV
Export Unserved
EXP_UNSERVED.CSV
[UEonly]
Export SeqCurrents
EXP_SEQCURRENTS.CSV
Export Powers [MVA]
EXP_POWERS.CSV
Export P_ByPhase
Export SeqPowers [MVA]
EXP_P_BYPHASE.CSV
EXP_SEQPOWERS.CSV
Export Faultstudy
EXP_FAULTS.CSV
Export Generators
[Filename | /m ]
Export Loads
Export Meters
[Filename | /m ]
EXP_GENMETERS.CSV
Export Monitors monitorname

Export YPrims
file name is assigned

EXP_YPRIMS.CSV
Export Y
EXP_Y.CSV
Export SeqZ
EXP_SEQZ.CSV
Export Summary
EXP_SUMMARY.CSV
Export Profile
EXP_Profile.CSV
EXP_LOADS.CSV
EXP_METERS.CSV
Description
Voltage, magnitude and
angle
Sequence voltage,
magnitude only
All currents, magnitude
and angle
overload for overloaded
elements
Capacity report on
lines and transformers
Results of Estimate
command
Unserved energy values;
requires energymeter
Sequence currents,
magnitude
Powers into each
terminal, kW and kvar
Powers by phase
Positive-, negative-,
and zero-sequence
powers
Results of Solve
Mode=Faultstudy
Values of Generator
Energy Meters
Values for each Load
Energy meter exports.
Adding the switch
"/multiple" or "/m"
will cause a separate
file to be written for
each meter.
Specified monitor value
All primitive Y
matrices
System Y matrix (full,
complex). Could be
huge!
Sequence Impedances at
each bus
Time-stamped summary of
present solution.
(Cumulative) One record
per solution
Data to enable you to
recreate a voltage
profile plot in another
program.
Page 33 of 180
OpenDSS Manual
June 2013
ForadditionaldescriptionseetheExportCommanddescriptioninthecommandreference.Also,
seethehelpfromrunningtheprogram.Therearefrequentadditions.
The circuit name or casename is prepended onto the file names above. This is the name you
gavethecircuitwhenitwascreated.Youcanalsochangethenamethatgetsprependedbythe
SetCasename=option.
AttheconclusionofanExportoperation(aswellasanyotherOpenDSSoperationthatwritesa
file)thenameoftheoutputfileappearsintheResultwindow.Youcanquicklydisplay/editthe
filebyoneofthefollowingmeans:
1. Edit|ResultFilemenuitem
2. ctrlR(thisisashortcutfortheabovecommand)
3. Thereisabuttononthetoolbarforthispurpose(seehintsbyholdingthemouseover
thebuttons)
Alternatively, you may set the option Set Showexport=Yes and the exported file will be
automaticallydisplayedinthedefaulttexteditor.Normallythisoptionisoffsothatfilesarenot
poppingupduringsimulations.1
P LOT M ENU C OMMANDS

ThePlotcommandhasseveraloptionsandcanbeconfusing.ChecktheWikionSourceForge.net
and the Help in the executable for uptodate information. The Plot command has its own
sectionintheHelpmenu.
Asofthiswriting,thehelptextfortheTypepropertyofthePlotcommandis:
One of {Circuit | Monitor | Daisy | Zones | AutoAdd | General (bus data) |
Loadshape | Tshape | Priceshape |Profile}
A "Daisy" plot is a special circuit plot that places a marker at each Generator
location or at buses in the BusList property, if defined. A Zones plot shows the
meter zones (see help on Object). Autoadd shows the autoadded generators. General
plot shows quantities associated with buses using gradient colors between C1 and
C2. Values are read from a file (see Object). Loadshape plots the specified
loadshape. Examples:
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
type=circuit quantity=power
Circuit Losses 1phlinestyle=3
Circuit quantity=3 object=mybranchdata.csv
daisy power max=5000 dots=N Buslist=[file=MyBusList.txt]
General quantity=1 object=mybusdata.csv
Loadshape object=myloadshape
Tshape object=mytemperatureshape
Priceshape object=mypriceshape
Profile
Profile Phases=Primary
Profile Phases=LL3ph
See the description of the Plot command below in this document or refer to the online
information in the Help menu and on the Wiki site. Some tips on creating plots are provided
here.
Page 34 of 180
OpenDSS Manual
June 2013
TheexistingcircuitplotcreatesdisplaysonwhichthethicknessesofLINEelementsarevaried
accordingto:
Power
Current
Voltage
Losses
Capacity(remaining)
Circuit plots are usually unicolor plots (specified by color C1). However, Voltage plots are
multicolordepicting3levelsforvoltage.Meterzoneplotsuseadifferentcolorforeachfeeder.
The following example will display the circuit with the line thickness proportional to POWER
relativetoamaxscaleof2000kW:
plot circuit Power Max=2000 dots=n labels=n subs=n C1=$00FF0000
ColorsmaybespecifiedbytheirRGBcolornumberorstandardcolornames.Theaboveexample
expresses the number in hexadecimal, which is a common form. The last 6 digits of the
hexadecimal form give the intensity of the colors in this format: $00BBGGRR. In this way, any
colorcanbeproduced.Thestandardcolornamesare:
Black
Maroon
Green
Olive
Navy
Purple
Teal
Gray
Silver
Red
Lime
Yellow
Blue
Fuchsia
Aqua
LtGray
DkGray
White
The general plot creates displays on which the color of bus marker dots (see Markercode=
optiondescriptionlaterinthisdocument)arevariedaccordingtoanarbitraryquantityentered
throughaCSVfile.ThefollowinggivesaniceyellowredheatplotvariationofCSVfiledatafield
1(thebusnameisassumedtobeinthefirstcolumn,orfield0,ofthecsvfile;fieldquantity1
referstocolumn2oftheCSVfile)withthemindisplayedascolorC1($0080FFFF=yellow)and
themax=0.003beingC2($000000FF=red).Valuesinbetweenarevariousshadesoforange.
Page 35 of 180
OpenDSS Manual
June 2013
plot General quantity=1 Max=.003 dots=n labels=n subs=y object=filename.csv

C1=$0080FFFF C2=$000000FF
Exampleresults:Thisplotclearlyshowstheextentofharmonicresonanceinvolvingtheresidual
current(likely,thezerosequence,too)onthecircuit.
Figure 8: Color-shaded heat plot of harmonic resonance
Thereisalsoanoptionontheplotcircuitcommandthatwillpermityoutodrawthecircuitwith
LINE object widths proportional to some arbitrary quantity imported from a CSV file. The first
column in the file should be the LINE name specified either by complete specification
LINE.MyLineNameorsimplyMyLineName.Ifthecommandcanfindalinebythatnamein
thepresentcircuit,itwillplotit.
Theusualthingyouwoulddoistoexportafilethatiskeyedonbranchname,suchas
Exportcurrents,or
Exportseqcurrents
Thenyouwouldissuetheplotcommand,forexample,toplotthefirstquantityaftertheLine
objectname:
Plot circuit quantity=1 Max=.001
dots=n
labels=n Object=feeder_exp_currents.CSV
TheOpenDSSdifferentiatesthisfromthestandardcircuitplotby:
1. Anumericvalueforquantity(representingthefieldnumber)insteadofPower,etc
2. A nonnull specification for Object (the specified file must exist for the command to
proceed).
InthestandaloneEXEversionoftheprogram,thePlot>CircuitPlots>GeneralLineDatamenu
willguideyouthroughthecreationofthiscommandwithmenusandlistprompts(Hint:turnthe
Page 36 of 180
OpenDSS Manual
June 2013
VCRbuttonrecorderon).Thefirst(header)rowintheCSVfileisassumedtocontainthefield
names,whichiscommonforCSVfiles.
Forexample,thesameplotasabovewithlinethicknessesinsteadofcoloreddots.
Figure 9: Thickness-weighted plot of harmonic resonance
MuchmoreinformationisavailableontheWikisite.
ProfilePlots
Voltageprofileplotsarequiteuseful.Figure10showsaprofileplotfromtheunbalancedIEEE
8500Node Test Feeder case. This was generated by issuing the following command after the
solution:
Plot Profile
Phases=ALL
TheoptionsforthePhasespropertyforLineNeutralvoltagesare:
Plot profile
! default 3-phase portion of the circuit
Plot profile phases=all
Plot profile phases=primary
OptionsforLineLinevoltagesare:
Plot profile phases=LL3ph
Plot profile phases=LLall
Plot profile phases=LLprimary
PrerequisitesforthiscommandaretohaveanEnergymeterattheheadofthefeederandhave
thevoltagebasesdefined.Theprogramplotstheperunitvoltagemagnitudeateachnodefor
eachLineobjectintheEnergymeterszone.LV(secondary)Lineobjectsareplottedasadotted
line.Thisputsthebeardontheplot.
Page 37 of 180
OpenDSS Manual
June 2013
Figure 10. Voltage Profile Plot from IEEE 8500-Node Test Feeder
Linesthatdroptowardzerointheprofileplotarefornodesthatlikelydonothaveaconnection
to the main power source (i.e., are floating). These may have no impact on the solution, but
shouldbeinvestigatedandcorrectedifnecessary.
To get the best profile plot, each LINE object should have the Length and Units properties
specified.IftheUnitspropertyisomittedandtheLengthpropertyis1.0,itwillbeassumedthat
thisisa1kmline,whichusuallyisnotcorrect.Adistortedprofilewillresult.
Thehorizontallinesontheplotcoincidewiththesettingsforthenormvminpuandnormvmaxpu
options for the active circuit. These default to 0.95 and 1.05, respectively. To change them,
executeascriptlikethis:
Set normvminpu=0.90
Set normvmaxpu=1.10
Note:YoumayalsoexportthedataforthisplotusingtheExportProfilecommand.Theresulting
CSVfilegivesyoucoordinatesyoumayuseinothergraphicstools.Theformatissimilartothe
Plotcommand:
Page 38 of 180
OpenDSS Manual
June 2013
ExportProfilePhases=option[optionalfilename]
The Phases property has the same options as the Plot command. A snippet of the CSV file
exportedforthecommandExportProfilePhases=Allforthesamecaseasaboveisshownhere
(theheaderrowiswrapped):
Name, Distance1, puV1, Distance2, puV2, Color, Thickness, Linetype, Markcenter,
Centercode, NodeCode, NodeWidth,Title=L-N Voltage Profile, Distance in km
LN5815900-1, 0, 1.04836, 0.0195933, 1.04802,1, 2, 0, 0, 0, 16, 1
LN5815900-1, 0, 1.04669, 0.0195933, 1.0464,2, 2, 0, 0, 0, 16, 1
LN5815900-1, 0, 1.05016, 0.0195933, 1.05005,3, 2, 0, 0, 0, 16, 1
LN5742828-1, 0.0195933, 1.04802, 0.0448456, 1.04758,1, 2, 0, 0, 0, 16, 1
LN5742828-1, 0.0195933, 1.0464, 0.0448456, 1.04602,2, 2, 0, 0, 0, 16, 1
LN5742828-1, 0.0195933, 1.05005, 0.0448456, 1.0499,3, 2, 0, 0, 0, 16, 1
TPX226195333C0, 0.0448456, 1.04037, 0.0600856, 1.03503,1, 2, 2, 0, 0, 16, 1
TPX226195333C0, 0.0448456, 1.04473, 0.0600856, 1.04596,2, 2, 2, 0, 0, 16, 1
LN5742828-2, 0.0448456, 1.04758, 0.114118, 1.04638,1, 2, 0, 0, 0, 16, 1
LN5742828-2, 0.0448456, 1.04602, 0.114118, 1.04499,2, 2, 0, 0, 0, 16, 1
LN5742828-2, 0.0448456, 1.0499, 0.114118, 1.04951,3, 2, 0, 0, 0, 16, 1
LN5473414-1, 0.114118, 1.04638, 0.221067, 1.04454,1, 2, 0, 0, 0, 16, 1
LN5473414-1, 0.114118, 1.04499, 0.221067, 1.0434,2, 2, 0, 0, 0, 16, 1
LN5473414-1, 0.114118, 1.04951, 0.221067, 1.04891,3, 2, 0, 0, 0, 16, 1
LN5714974-1, 0.221067, 1.04454, 0.343671, 1.04243,1, 2, 0, 0, 0, 16, 1
LN5714974-1, 0.221067, 1.0434, 0.343671, 1.04159,2, 2, 0, 0, 0, 16, 1
LN5714974-1, 0.221067, 1.04891, 0.343671, 1.04823,3, 2, 0, 0, 0, 16, 1
LN5896798-1, 0.343671, 1.04243, 0.387831, 1.04167,1, 2, 0, 0, 0, 16, 1
LN5896798-1, 0.343671, 1.04159, 0.387831, 1.04094,2, 2, 0, 0, 0, 16, 1
LN5896798-1, 0.343671, 1.04823, 0.387831, 1.04799,3, 2, 0, 0, 0, 16, 1
LN5775442-1, 0.387831, 1.04167, 0.493392, 1.03986,1, 2, 0, 0, 0, 16, 1
LN5775442-1, 0.387831, 1.04094, 0.493392, 1.03937,2, 2, 0, 0, 0, 16, 1
LN5775442-1, 0.387831, 1.04799, 0.493392, 1.04745,3, 2, 0, 0, 0, 16, 1
TPX223658A0, 0.493392, 1.03242, 0.508632, 1.03085,1, 2, 2, 0, 0, 16, 1
TPX223658A0, 0.493392, 1.03424, 0.508632, 1.03402,2, 2, 2, 0, 0, 16, 1
Page 39 of 180
OpenDSS Manual
June 2013
Overall Circuit Model Concept
Inf. Bus
(Voltage, Angle)
Power Delivery
System
Comm
Msg Queue 1
Power Conversion
Element
("Black Box")
Control
Center
Comm
Msg Queue 2
Control
Figure 11: Electrical Circuit with Communications Network
TheOpenDSSconsistsofamodeloftheelectricalpowerdistributionsysteminthermssteady
state, overlaid with a communications network that interconnects controls on power delivery
elementsandonpowerconversionelements.
[Thecommunicationsmessagequeuesarenotcompletelydevelopedinthisversiononeofthe
control queues is functional and used by the controls that are implemented. Preliminary
simulationsofpacketsinacommunicationsnetworkhavebeenperformedusingseparatetools
andthescriptingcapabilityofOpenDSS.Thisworkcontinues.]
Page 40 of 180
OpenDSS Manual
June 2013
Bus and Terminal Models

B US D EFINITION
Abusisacircuitelementhaving[1..N]nodes.Busesaretheconnectionpointforallothercircuit
elements.Inmanypowersystemanalysisprograms,busandnodearenearlysynonymous,
buttheyaredistinctivelydifferentinOpenDSS.BusisthecontainerofNodeobjects.Thatisto
say,aBushasNodes.
The main electrical property of a Bus is voltage. Each node has a voltage with respect to the
zerovoltagereference(remoteground).Thereisanodaladmittanceequationwrittenforevery
node(i.e.,thecurrentissummedateachnode).Thatbasicallydictatesthesizeoftheproblem
thatmustbesolved,althoughthereisalsocomputationaloverheadcomputingtheinjection,or
compensation,currents.
2 3
Figure 12: Bus Definition
T ERMINAL D EFINITION
Eachelectricalelementinthepowersystemhasoneormoreterminals.Eachterminalhasone
ormoreconductors.EachconductorconceptuallycontainsadisconnectswitchandaTCC(fuse)
curve [The Fuse simulation in the terminal conductors has been disabled in this version and is
beingredesigned;aRelayobjectoraseparateFuseobjectcanbeused,ifneeded,tocontrolthe
switchesintheterminalconductors.].Theconductorsarenumbered[1,2,3,].
If the terminal is connected to an Nphase device, the first N conductors are assumed to
correspond to the phases, in order. The remaining conductors may be virtually any other
conductorbutarefrequentlyneutralsorothernonpowerconductors.
TheOpenDSSbusisaconnectingplacewith1ormorenodesforconnectingindividualphases
and other conductors from the terminals of both power delivery elements and power
conversionelements.
Busesarenamedwithnullterminatedstringsofarbitrarylength.Therefore,youmayusequite
longnames.
Node 0 of each bus is implicitly connected to the voltage reference (i.e., the node's voltage is
alwayszeroandisneverexplicitlyincludedintheYmatrix).
Page 41 of 180
OpenDSS Manual
June 2013
1
Power Delivery
or Power Conversion
Element
Figure 13: Terminal Definition
B US N AMING
Busesarenamedbyanalphanumericstringofcharacters.Thenamesmaybenumbers,butare
alwaystreatedasstrings.Internally,buseswillbenumbered(actually,eachnodeisnumbered),
butarereferencedthroughtheCOMorcommandinterfacebyname.Theinternalindexnumber
issubjecttochangeifsomethinginthecircuitchangesandisnotareliablewaytorefertoabus
ornode.SeeBusInstantiationandLifebelow.
Itisbetterifnamesdonotcontainblanks,tabs,orotherwhitespaceorcontrolcharacters.If
the name contains a blank, for example, it must be enclosed in quotes (single or double,
parentheses,orbrackets).Thiscanbeasourceoferrorsbecauseofthedifferententrypoints
for the names (user interface, files, COM interface). However, names from models in other
programssuchasPSS/Emaycontainnames(mayalsobeduplicates).
Names may be any length and are passed to the OpenDSS through the COM interface as
standard nullterminated strings (actually, widestrings). This is the common way for
representing strings in the Windows environment. Thus, it is a simple matter to drive the
OpenDSSfrommostprogramminglanguages.
B US I NSTANTIATION AND L IFE

OneofthefeaturesoftheOpenDSSthattakessomegettingusedtoforusersfamiliarwithother
powersystemanalysisplatformsisthataBusdoesnotexistuntilitisneededforasolutionor
someotherpurpose.Alistofbusesismadefromthepresentlyenableddevicesinthecircuit.
Theneachbusisinstantiated.Likewise,abusmaydisappearduringasimulation.
The reason for this behavior of the OpenDSS is to avoid having to define all the buses in the
problem ahead of time. This allows users a great deal of flexibility in simulating distribution
circuitsinwhichthetopologyischangingduringthesimulation.Ifyouwanttoaddanewbus,
simply define a device that is connected to the bus or edit the bus connections of an existing
device. Since the OpenDSS does not need to know the voltage bases to perform its solution,
there is no need to define the base voltages ahead of time. However, the voltage bases are
useful for reports and certain simulations. Just remember to set the voltage bases AFTER the
busesexistandbeforethereportisgenerated.
Page 42 of 180
OpenDSS Manual
June 2013
Bus instantiation can be forced without performing a solution by issuing the MakeBusList
command.
The CalcVoltageBases command will automatically set the voltage bases where practical by
performinganoloadpowerflow.Thelegalvoltagebasesforaproblemaredefinedusingthe
SetVoltagebases=[arrayofvoltagebasesinkVLL].
Otherwise, you can use the SetkVBase command to set the voltage base for a selected bus.
Often,userswillcreateseparatescriptfileswithallthenecessarySetkVBasecommands.These
execute quickly but are used only when it is difficult to automatically discern between two
voltagebasesinaproblem.
Thebuslistisreorganizedwheneverthereisachangeinthecircuit.
Implications/SideEffectsofBusInstantiationRules:
You cant define the voltage base for a bus until it exists. The CalcVoltageBases
command is a solution type that will automatically instantiate all the buses currently
defined.
Youcantdefineabusscoordinatesuntilthebusexists.
Oncethebuslistexists,propertiesareautomaticallycopiedtonewbusobjectswhena
change occurs that requires rebuilding the bus list. However, if there are new buses
createdbythechanges,theywillnothaveanyofthespecialpropertiessuchasvoltage
baseorcoordinatesdefined.Thatmustbedonesubsequently,ifnecessary.
Itdoesnothurttoredefinebasevoltageorcoordinatesifthereisanyquestionwhether
theyhavethepropervalue.
Onceinstantiated,abusobjectwillpersistuntilanothercommandforcesrebuildingthe
buslist.Thus,ifthereareeditsperformedonthecircuitelements,thebuslistcouldbe
outofsynchwiththepresentconfiguration.
ThereisalsoaNodelistthatisconstructedatthesametimeasthebuslist.Theorderof
elementsinthesystemYmatrixisgovernedbytheorderoftheNodelist.TheNodelist
order is basically the order in which the nodes are defined during the circuit model
buildingprocess.
T ERMINAL R EFERENCES
Terminals are not named separately from the device. Each device will have a name and a
definednumberofmultiphaseterminals.Terminalswillbereferencedexplicitlybynumber[1,
2,3]orbyinference,inthesequenceinwhichtheyappear.Internally,theywillbesequenced
bypositioninalist.
P HASES AND OTHER C ONDUCTORS

Eachterminalhasoneormorephases,ornormalpowercarryingconductorsand,optionally,a
number of other conductors to represent neutral, or grounding, conductors or conductors for
any other purpose. By convention, if a device is declared as having N phases, the first N
conductorsofeachterminalareassumedtobethephaseconductors,inthesamesequenceon
eachterminal.Remainingconductorsateachterminalrefertoneutralorgroundor"earth"
conductors.However,theconductorscanrepresentotherpowercarryingconductors.Thereis
Page 43 of 180
OpenDSS Manual
June 2013

nohardrule.
All terminals of a device are defined to have the same number of conductors. For most
devices,thiscausesnoambiguity,butfortransformerswithbothdeltaandwye(star)winding
connections, there will be an extra conductor at the deltaconnected terminal. The neutral is
explicit to allow connection of neutral impedances to the wyeconnected winding. The extra
conductor for the delta connection is simply connected to ground (voltage reference) and the
admittancesareallsettozero.Thus,theconductoreffectivelydoesnotappearintheproblem;
itisignored.However,youmayseeitappearinreportsthatexplicitlylistallthevoltagesand
currentsinacircuit.
Theterminalconductorsandbusnodesmaybecombinedtoformanypracticalconnection.
Buses have Nodes: A bus may have any number of nodes (places to connect device terminal
conductors).Nodesareintegernumbers.Thenodesmaybearbitrarilynumbered.However,the
firstNarebydefaultreservedfortheNphasesofdevicesconnectedtothem.Thus,ifabushas
3phasedevicesconnectedtoit,connectionswouldbeexpectedtonodes1,2,and3.Sothe
DSSwouldusethesevoltagestocomputethesequencevoltages,forexample.Phase1would
nominallyrepresentthesamephasethroughoutthecircuit,althoughthereisnothingtoenforce
that standard. It is up to the user to maintain a consistent definition. If only the default
connectionsareused,theconsistencyisgenerallymaintainedautomatically,althoughtherecan
beexceptions.
Any other nodes would simply be points of connection with no special meaning. Each Bus
objectkeepstrackoftheallocationanddesignationofitsnodes.
Node0ofabusisalwaysthevoltagereference(a.k.a,ground,orearth).Thatis,italwayshasa
voltageofexactlyzerovolts.
S PECIFYING C ONNECTIONS
Theusercandefinehowterminalsaretobeconnectedtobusesinthreeways,notjustoneway:
1. Generically connect a circuit elements terminal to a bus without specifying nodeto
conductor connections. This is the default connection. Normal phase sequence is
assumed. Phase 1 of the terminal is connected to Node 1 of the Bus, and so on.
Neutralsdefaulttoground(Node0).
2. Explicitly specify the first phase of the device is connected to node j of the bus. The
remainingphasesareconnectedinnormal3phasesequence(123rotation).Neutral
conductorsdefaulttoground(Node0).
3. Explicitly specify the connection for all phases of each terminal. Using this mode,
neutrals (star points) may be left floating. Any arbitrary connection maybe achieved.
Thesyntaxis:
BUSNAME.i.j.kwherei,j,krefertothenodesofabus.
This is interpreted as the first conductor of the terminal is connected to node i of the bus
designatedbyBUSNAME;the2ndconductorisconnectedtonodej,etc.
Page 44 of 180
OpenDSS Manual
June 2013
Thedefaultnodeconventionforaterminaltobusconnectionspecificationinwhichthenodes
arenotexplicitlydesignatedis:
BUSNAME.1.0.0.0.0.0.0.{Singlephaseterminal)
BUSNAME.1.2.0.0.0.0.0.{twophaseterminal)
BUSNAME.1.2.3.0.0.0.0{3phaseterminal}
If the desired connection is anything else, it must be explicitly specified. Note: a bus object
"learns" its definition from the terminal specifications. Extra nodes are created on the fly as
needed.Theyaresimplydesignationsofplacestoconnectconductorsfromterminals.Fora3
phasewyeconnectedcapacitorwithaneutralreactor,specifytheconnectionsasfollows:
BUSNAME.1.2.3.4{for3phasewyeconnectedcapacitor}
BUSNAME.4{for1phaseneutralreactor(2ndterminaldefaultstonode0)}
Page 45 of 180
OpenDSS Manual
June 2013
Power Delivery Elements

Power delivery elements usually consist of two or more multiphase terminals. Their basic
function is to transport energy from one point to another. On the power system, the most
commonpowerdeliveryelementsarelinesandtransformers.Thus,theygenerallyhavemore
than one terminal (capacitors and reactors can be an exception when shuntconnected rather
than seriesconnected). Power delivery elements are standard electrical elements generally
completelydefinedinthermssteadystatebytheirimpedances.Thus,theycanberepresented
fullybytheprimitiveymatrix(Yprim).
Terminal 1
Power Delivery
Element
Terminal 2
Iterm = [Yprim] Vterm
Figure 14: Power Delivery Element Definition
Page 46 of 180
OpenDSS Manual
June 2013
Power Conversion Elements

Power conversion elements convert power from electrical form to some other form, or vice
versa. Some may temporarily store energy and then give it back, as is the case for reactive
elements. Most will have only one connection to the power system and, therefore, only one
multiphaseterminal.Thedescriptionofthemechanicalorthermalsideofthepowerconversion
is contained within the "Black box" model. The description may be a simple impedance or a
complicatedsetofdifferentialequationsyieldingacurrentinjectionequationoftheform:
ITerm(t)=F(VTerm,[State],t)
The function F will vary according to the type of simulation being performed. The power
conversionelementmustalsobecapableofreportingthepartialsmatrixwhennecessary:
V
Insimplecases,thiswillsimplybetheprimitivey(admittance)matrix;thatis,theymatrixfor
thiselementalone.
Power Conversion
Element
Figure 15: Power Conversion Element Definition
Within the OpenDSS, the typical implementation of a PC element is as shown in Figure 16.
Nonlinear elements, in particular Load and Generator elements, are treated as Norton
equivalents with a constant Yprim and a compensation current or injection current that
compensatesforthenonlinearportion.Thisworkswellformostdistributionloadsandallowsa
widerangeofmodelsofloadvariationwithvoltage.Itconvergeswellforthevastmajorityof
typical distribution system conditions. The Yprim matrix is generally kept constant for
Page 47 of 180
OpenDSS Manual
June 2013
computationalefficiency,althoughtheOpenDSSdoesnotrequirethis.Thislimitsthenumberof
times the system Y matrix has to be rebuilt, which contributes greatly to computational
efficiencyforlongruns,suchasannualloadingsimulations.
Yprim
Compensation
Current
Figure 16. Compensation Current Model of PC Elements (one-line)
TheCompensationcurrentisthe currentthatisaddedintothe injection currentvectorinthe

mainsolver(seenextsection).Thismodelaccommodatesalargevarietyofloadmodelsquite
easily.TheLoadelementmodelspresentlyimplementedare:
1. Conventional constant P, Q load model. This, and all load models, revert to linear
(constant Z) model outside the normal voltage range in an attempt to guarantee
convergence even when the voltage drops very low. This is important for performing
annualsimulations.
2. ConstantZloadmodel.PandQvarybythesquareofthevoltage.Willusuallyconverge
inanycondition.
3. ConstantPbutQismodeledasaconstantreactance.
4. P and Q variation defined by exponential values. For example this is used for
ConservationVoltageReduction(CVR)studies.
5. Constant current magnitude (common in distribution system analysis). P and Q vary
linearlywithvoltagemagnitude.
6. Constant P that can be modified by loadshape multipliers, but Q is a fixed value
independentoftime.
7. Similarto6,butQiscomputedfromafixedreactance(varieswithsquareofvoltage)
8. AZIPmodelcontainingPandQexponentsforeachofthethreetypesofloadmodels
Except where noted, P and Q can be modified by Loadshape multipliers. Loads can also be
exemptfromloadshapemulitipliers.
Page 48 of 180
OpenDSS Manual
June 2013
Putting it All Together

Figure17illustrateshowtheDSSputsallthePDelementsandPCelementstogethertoperform
asolution.
ALL Elements
Yprim 1
Yprim 2
Yprim 3
Yprim n
PC Elements
I1
I2
Iinj
Node
Voltages
Im
Iteration Loop
Figure 17. OpenDSS Solution Loop
Basically,theupperstructureoftheOpenDSS(the partthatis writteninDelphi) managesthe

creationandmodificationoftheprimitiveymatrices(Yprim)foreachelementinthecircuitas
well as managing the bus lists, the collection of results through Meter elements, and the
execution of Control elements. The Yprim matrices are fed to the sparse matrix solver, which
constructsthesystemYmatrix.
An initial guess at the voltages is obtained by performing a zero load power flow. That is, all
shuntelementsaredisconnectedandonlytheseriespowerdeliveryelementsareconsidered.
This gets all the phase angles and voltage magnitudes in the proper relationship. This is
importantbecausetheOpenDSSisdesignedtosolvearbitrarynphasenetworksinwhichthere
canbeallsortsoftransformerratiosandconnections.
Theiterationcyclebeginsbyobtainingtheinjectioncurrentsfromallthepowerconversion(PC)
elementsinthesystemandaddingthemintotheappropriateslotintheIinj vector.Thesparse
set is then solved for the next guess at the voltages. The cycle repeats until the voltages
convergetotypically0.0001pu.ThesystemYmatrixistypicallynotrebuiltduringthisprocess
sotheiterationsgoquickly.
This simple iterative solution has been found to converge quite well for most distribution
systems that have adequate capacity to serve the load. The key is to have a dominant bulk
powersource,whichisthecaseformostdistributionsystems.IntheDSS,thisistheNormal
solution algorithm. There is also a Newton algorithm for more difficult systems (not to be
confusedwiththetypicalNewtonRaphsonpowerflowmethod).
Page 49 of 180
OpenDSS Manual
June 2013
WhenperformingDailyorYearlysimulations,thesolutionatthepresenttimestepisusedasthe
startingpointforthesolutionatthenexttimestep.Unlessthereisalargechangeinload,the
solution will typically converge in 2 iterations one to do the solution and one to check it to
makesureitisconverged.Thus,theDSSisabletoperformsuchcalculationsquiteefficiently.
Control iterations are performed outside this loop. That is, a converged solution is achieved
beforecheckingtoseeifcontrolactionsarerequired.
Page 50 of 180
OpenDSS Manual
June 2013
DSS Command Language Syntax

TheDSSisdesignedsuchthatallfunctionscanbecarriedoutthroughtextbasedDSSCommand
Languagescripts.Thetextstreamsmaycomefromanyofthesesources:
9. SelectingandexecutingascriptonaControlPanelwindow,
10. ThroughtheCOMinterface,or
11. From a standard text file to which the command interpreter may be temporarily
redirected(CompileorRedirectcommands).
ThismakestheDSSaneasilyaccessibletoolforuserswhosimplywanttokeyinasmallcircuit
anddoaquickstudyaswellastothosewhoperformquitecomplicatedstudies.Italsomakes
the DSS more easily adapted by others who have a great deal invested in their own database
andwouldputforthmuchefforttoconformtoanother.Textfilesarethemostcommonmeans
oftransferringdatafromonesourceintoanother.TheDSSscriptscanoftenbeconfiguredtobe
closetovariousdatatransferformats.
Always refer to the Help command for the latest commands and property names that are
recognizedbytheDSS.
C OMMAND S YNTAX
Thecommandlanguageisoftheform:
Command
parm1,
parm2
parm3
parm 4 .
Parameters (parm1, etc) may be separated by commas (,) or white space (blank, tab). If a
parameterincludesadelimiter,encloseitineither
doublequotes(),
singlequotes(),or
parentheses(),or..
brackets[..],or
braces{..}.
While any of these will work, double or single quotes are preferred for strings. Brackets are
preferredforarrays,andcurlybracesarepreferredforinlinemath.
Note:BecarefulofusingparanthesesonWindows&forfilenamescontainingfullpathnames
becauseWindowsusesthestring(x86)for32bitprogramsinthedefaultProgramFilesfolders.
Usesomeotherdelimiter.Doublequotesworkfine.
Page 51 of 180
OpenDSS Manual
June 2013
P ARAMETERS
Parametersmaybepositionalornamed(tagged).Ifnamed,an"="signisexpected.
1. Name=value(thisisthenamedform)
2. Value(valuealoneinpositionalform)
Forexample,thefollowingtwocommandsareequivalent.
New
New
Object="Line.First Line"
Line.First Line,
b1240
Bus1=b1240
32
Bus2=32
LineCode=336ACSR,
336ACSR,
Thefirstexampleusesnamedparameters,whichareshowninthedefaultorder.Thesecond
examplesimplygivesthevaluesoftheparametersandtheparserassumesthattheyareinthe
default order. Note that the name of the object contains a blank, which is a standard DSS
delimitercharacter.Therefore,itisenclosedinquotesorparentheses,etc..
You may mix named parameters and positional parameters. Using a named parameter
repositionstheparser'spositionalpointersothatsubsequentparametersneednotbenamed.
The order of parameters is always given in the DSS help command window. The DSS help
windowallowsfordisplayofcommandsandpropertiesineitheralphabeticalorderorpositional
(numerical) order. The properties of elements are by default processed in positional order
unlessthe=appearsinthefield.
Some commands are interpreted at more than one lexical level inside the OpenDSS. In this
example, the main DSS command interpreter interprets the New command and essentially
passes the remainder of the string to the Executive for adding new circuit elements. It
determinesthetypeofelementtoadd(e.g.,aLine)andconfirmsthatitisindeedaregistered
class. It then passes the remainder of the text line on to the module that handles the
instantiationanddefinitionsofLineobjects.OnlytheLinemodelcodeneedstoknowhowto
interpret the property definitions it receives via the parameter list. This design allows great
flexibilityforfuturemodificationstotheLinemodelthatmightrequireaddingnewproperties.
ThishappenswithregularityandthemainDSSexecutivedoesnothavetobemodified;onlythe
moduleaffected.
FortheNewcommand,thefirsttwoparametersarealwaysrequiredandpositional:
TheNewcommanditself,and
Thenameoftheobjecttoadd.
For circuit elements, the next one, or two, parameters are normally the bus connection
properties,whichareprocessedandstoredwiththecircuitelementmodel.Thenthedefinition
oftheobjectbeingcreatedcontinues,usinganeditingfunctionexpresslydevotedtothatclass
ofcircuitelement.
P ROPERTIES
Theparametersofcircuitelementeditingcommandsarereferredtoasproperties.Properties
generally set values of some data field in the targeted object, but may also have some side
Page 52 of 180
OpenDSS Manual
June 2013
effects.Propertiesbehavelikepropertiesinobjectorientedprogramminglanguages.Theymay
performanactionaswellassettingavalue.
For example, setting the PF property of a Load object also causes the kvar property to be
updated.
Many objects have multiple properties that essentially set the same internal data value. For
example,youcansetthekVAratingbyeitherthekVAorMVApropertyissomeelements.
Thisisadifferentapproachthanprogramsusingdatabasestypicallytakewherethevaluesare
staticandthedatafieldsgenerallyfixed.
D ELIMITERS AND O THER S PECIAL C HARACTERS

TheDSSrecognizesthesedelimitersandotherspecialcharacters:
Arrayorstringdelimiterpairs:
[]
{}
()

Matrixrowdelimiter:|(verticalbar)
Valuedelimiters:
Comma(,)
anywhitespace(taborspace)
Class,Object,Bus,orNodedelimiter:period(.)
Keyword/valueseparator:=
Continuationofpreviousline: ~(actuallyasynonymfortheMorecommand)
Commentline: //or!
Inlinecomment:!
Queryaproperty:?
A RRAY P ROPERTIES [ AND Q UOTE P AIRS ]

Array parameters are sequences of numbers. Of necessity, delimiters must be present to
separate the numbers. To define an array, simply enclose the sequence in any of the quote
pairs. Square brackets, [..], are the preferred method, although any of the other quote pairs:
..,..,(..),{..}willwork.Forexample,fora3windingtransformeryoucoulddefinearrayssuch
as:
Page 53 of 180
OpenDSS Manual
June 2013
kvs = [115, 6.6, 22]

kvas=[20000 16000 16000]
Standard Ways to Define Array Properties

Arrayscanbedefinedbythefollowingmethods:
Enteringthenumericvaluesdirectly
mult=[1, 2, 3, 4, ...]
Enteringthenumbersfromasinglecolumntextfile:
mult=[File=MyTextDataFile.CSV]
Enteringthedatafromapackedbinaryfileofdoubles:
mult=[dblFile=MyFileOfDoubles.dbl]
Enteringthedatafromapackedbinaryfileofsingles:
mult=[sngFile=MyFileOfDoubles.sng]
Enhanced Syntax
The'File=...'capabilityfortextfileshasbeenenhancedtoallowyoutoextractacolumnofdata
from a multicolumn CSV file (like you might get from an Excel spreadsheet or the OpenDSS
Exportcommand).Thecompletesyntaxis:
mult=[File=myMultiColumnFile.CSV, Column=n, Header=Yes/No]
Enter n forthecolumnnumberyouwant.Thedefaultisalwayssetto1foreacharray.
Specifying Header=Yes causes the first record in the CSV file to be skipped. This allows for a
singlelineofnonnumericdatainthefirstline,asiscommoninOpenDSSExportfiles.Defaultis
Header=No.
Example
New Loadshape.Ramp2 npts=4000 sInterval=1
~ mult= (file=MultiChannelTest.csv, column=3, header=yes)
Special Reserved File Name

The name %result% is now used to designate the last result file. For example, if you want to
export a file (such as a monitor file) and then immediately read in column 5 to do something
with,youcoulddoitwiththefollowingsyntax:
mult=[File=%result%, Column=5, Header=Yes]
Thismustbeexecutedbeforeanothercommandisissuedthatwritesaresultfile.
M ATRIX P ROPERTIES
Matrix parameters are entered by extending the Array syntax: Simply place a vertical bar (|)
characterbetweenrows,forexample:
Page 54 of 180
OpenDSS Manual
June 2013

Xmatrix=[1.2
.3
.3 | .3
1.2
3 | .3
.3
1.2]
(3x3 matrix)
Symmetricalmatriceslikethisexamplemayalsobeenteredinlowertriangleformtobemore
compact.
Xmatrix=[ 1.2
| .3 1.2
| .3
.3
1.2 ]
(3x3 matrix lower triangle)
S TRING L ENGTH
The DSS Command strings may be as long as can be reasonably passed through the COM
interface.Thisisverylong.TheymustgenerallyNOTbesplitintoseparatelinessincethereis
no concept of a line of text in the standard DSS COM interface; only separate commands.
However,NewandEditcommandscanbecontinuedonasubsequenttextlinewiththeMoreor
~command.
Ingeneral,stringvaluesinDSSscriptscanbeaslongasdesired.Thereare,ofcourse,limitations
to what can be reasonably deciphered when printed on reports. Also, the DSS hashes bus
names, device names and any other strings that are expected to result in long lists for large
circuits. This is done for fast searching. There have been various hashing algorithms
implemented and it is difficult to keep the documentation up with the present release. Some
algorithmswouldhashonlythefirst8characters.Thisdoesnotmeanthatcomparisonsareonly
8characters;comparisonsaredoneonfullstringlengths.
AbbreviationsareallowedbydefaultinDSScommandsandelementPropertynames.However,
ifthecircuitisverylarge,scriptprocessingwillactuallyproceedmoreefficientlyifthenamesof
commands and properties are spelled out completely. It wont matter on small circuits. The
reasonisthatthehashlistsaremuchshorterthanthelinearlists.IftheDSSdoesnotfindthe
abbreviatednameinahashlist,itwillthensearchthewholelistfromtoptobottom.Thiscan
slowperformanceiftherearethousandsofnamesinthelist.
D EFAULT V ALUES
WhenaNewcommandresultsintheinstantiationofaDSSelement,theelementisinstantiated
withreasonablevalues.Onlythosepropertiesthatneedtobechangedtocorrectlydefinethe
objectneedbeincludedinthecommandstring.Commonly,onlythebusconnectionsandafew
keypropertiesneedbedefined.Also,anewelementneednotbedefinedinonecommandline.
It may be edited as many times as desired with subsequent commands (see Edit, More and ~
commands).
When an element is created or selected by a command, it becomes the Active element.
Thereafter, property edit commands are passed directly to the active element until another
elementisdefinedbytheNewcommandorselectedbysomeothercommand.Inthatrespect,
thecommandlanguagemirrorsthebasicCOMinterface.
Allchangesarepersistent.Thatis,aparameterchangedwithonecommandremainsasitwas
defineduntilchangedbyasubsequentcommand.Thismightbeasourceofmisunderstanding
withnovicesusingtheprogramwhomightexpectvaluestoresettoabasecaseastheydoin
someotherprograms.Whenthisisaconcern,issueaclearcommandandredefinethecircuit
fromscratch.
Page 55 of 180
OpenDSS Manual
June 2013
ChangesmadeontheflyareNOTsavedbacktotheoriginalscriptfiles.Ifyouwishtocapture
the present state of the circuit for future analysis, execute the Save Circuit command, which
saves the present circuit to a separate folder. It will not overwrite an existing folder. Some
manualfixupmayberequiredtogetthesavedcircuittocompileproperly.
I N LINE M ATH
TheDSSscriptinglanguageusesaformofReversePolishNotation(RPN)toaccommodateinline
math. This feature may be used to preprocess input data before simulation. The parser will
evaluate RPN expressions automatically if you enclose the expression in any of the quoted
formats(quotationmarksoranyofthematchedparentheses,brackets,etc.).
RPN Expressions
Basically, you enter the same keystrokes as you would with an RPN calculator (such as an HP
48). One difference is that you separate numbers, operators, and functions by a space or
comma.TheRPNcalculatorinOpenDSShasa"stack"of10registersjustlikesomecalculators.In
the function descriptions that follow, the first stack register is referred to as "X" and the next
higheras"Y"asontheHPcalculator.Whenanewnumberisentered,theexistingregistersare
rolledupandthenewnumberisinsertedintotheXregister.
Thesefunctionsoperateonthefirsttworegisters,XandY:
+
Addthelasttwooperands(XandYregisters;resultinX;X=X+Y)
X=YX
X=X*Y
X=Y/X
(exponentiation)X=YtotheXpower
TheseunitaryfunctionsoperateontheXregisterandleavetheresultinX.
sqr
X=X*X
sqrt
takethesquarerootofX
inv
(inverseofX=1/X)
ln
(naturallogofX)
exp
(etotheX)
log10 (Logbase10ofX)
sin
forXindegrees,takethesine
cos
forXindegrees,takethecosine
Page 56 of 180
OpenDSS Manual
June 2013

tan
forXindegrees,takethetangent
asin
taketheinversesine,resultindegrees
acos taketheinversecosine,resultindegrees
atan
takethearctangent,resultindegrees
atan2 take the arc tangent with two arguments, Y=rise and X = run,
resultindegreesoverallfourquadrants
Thefollowingfunctionsmanipulatethestackofregisters
Rollup shiftallregistersup
Rolldn shiftallregistersdn
Swap swapXandY
Thereisoneconstantpreprogrammed:pi
RPN Examples
Forexample,thefollowingDSScodewillcalculateX1fora1mHinductanceusinginlineRPN:
// convert 1 mH to ohms at 60 Hz, note the last * operator
line.L1.X1 = (2 pi * 60 * .001 *)
Theexpressioninparenthesesisevaluatedlefttoright.'2'isenteredfollowedby'pi'.Thenthe
two are multiplied together yielding 2. The result is then multiplied by 60 to yield (2f).
Finally,theresultismultipliedby1mHtoyieldthereactanceat60Hz.Tospecifythevaluesof
anarrayusinginlinemath,simplynestthequotesorparentheses:
// Convert 300 kvar to 14.4 kV, 2 steps
Capacitor.C1.kvar = [(14.4 13.8 / sqr 300 *), (14.4 13.8 / sqr 300 *)]
TheEdit|RPNEvaluatormenucommandbringsupamodalforminwhichyoucanenteranRPN
expressionandcomputetheresult.ClickingtheOKbuttononthisformautomaticallycopiesthe
resulttotheclipboard.ThepurposeofthisfeatureistoenableyoutointerpretRPNstringsyou
findintheDSSscriptortosimplifytheabovescriptbycomputingtheresultandreplacingthe
RPNstringwiththefinalvalueifyouchoose:
Capacitor.C1.kvar = [ 326.65, 326.65] ! 300 kvar converted to 14.4 kV, 2 steps
This next example shows how to use RPN expressions inside an array. Two different delimiter
typesarenecessarytodifferentiatethearrayfromtheexpressions.
// set the winding kvs to (14.4 20)
New Transformer.t
kvs=("24.9 3 sqrt /" "10 2 *")
Page 57 of 180
OpenDSS Manual
June 2013
Page 58 of 180
OpenDSS Manual
June 2013
DSS Command Reference

Nearly all DSS commands and parameter names may be abbreviated. This is for convenience
when typing commands in directly. However, there is not necessarily any speed benefit to
abbreviating for machinegenerated text. (See String Length above.) Thus, commands and
parameter names should be spelled out completely when placed in script files that are auto
generated from other computer data sources. Abbreviate only when manually typing
commandstotheDSS.
S PECIFYING O BJECTS
AnyobjectintheDSS,whetheracircuitelementorageneralDSSobject,canbereferencedby
itscompletename:
Object=Classname.objname
Forexample,
object=vsource.source.
Innearlyallcircumstances,the'object='maybeomittedasitcanforanyothercommandline
parameter.Theobjectnameisalmostalwaysexpectedtobethefirstparameterimmediately
followingthecommandverb.
Ifthe'classname'prefixisomitted(i.e.,nodotintheobjectname),thepreviouslyusedclass
(theactiveDSSclass)isassumed.Forexample,
New line.firstline . . .
New secondline . . .
Thesecondcommandwillattempttocreateanewlineobjectcalled'secondline'.
Ifthereisanychancetheactiveclasshasbeenreset,usethefullyqualifiedname.Alternatively,
usetheSetClasscommandtoestablishtheactiveclass:
Set class=Line
New secondline . . .
Recommendation: Always used the full element name (classname.elementname) to avoid

confusionatalaterdate.Itisbettertomakethetexthumanreadablethanexploitshortcutsthe
programallows.
Page 59 of 180
OpenDSS Manual
June 2013
C OMMAND R EFERENCE
The following documents selected command definitions as of this writing. There are 98
commands as of this writing. Newer builds of the DSS may have additional properties and
commands.ExecutetheHelpcommandwhilerunningtheDSStoviewthepresentcommands
availableinyourversion.
// (comment) and ! (inline comment)

The appearance of // in the command position indicates that this statement is a comment
line.ItisignoredbytheDSS.Ifyouwishtoplaceaninlinecommentattheendofacommand
line,usethe!character.Theparserignoresallcharactersfollowingthe!character.
//Thisisacommentline
Newline.line4linecode=336acsrlength=2.0!thisisaninlinecomment
/* */ Block Comments
Newatversion7.6,youcannowcommentoutwholesections(wholelinesofscript)usingthe
blockcommentcapability.Theblockcommentmustbeginwith/*intheFIRSTcolumnofthe
line.Theblockcommentterminatesaftertheappearanceof*/anywhereinalineorwiththe
endofascriptfileorselectioninascriptwindow.Example:
Compile "C:\Users\prdu001\DSSData\CDR\Master3.DSS"
New Monitor.Line1-PQ Line.LINE1 1 mode=1 ppolar=no
New Monitor.Line1-VI Line.LINE1 1 mode=0 VIpolar=Yes
/*
comment out the next two monitors
New Monitor.Source-PQ Vsource.source 1 mode=1 ppolar=no
New Monitor.source-VI Vsource.source 1 mode=0 VIpolar=Yes
****/ End of block comment
New Monitor.Tran2-VI Transformer.PHAB
New Monitor.Tran3-VI Transformer.PHAB
2 mod=0 VIPolar=no
3 mod=0 VIPolar=no
Solve
Customizing Solution Processes

Thenextsevencommands,allbeginningwithanunderscore(_)character,allowyoutoscript
yourownsolutionprocessbyprovidingaccesstothedifferentstepsofthesolutionprocess.
_DoControlActions
For step control of solution process: Pops control actions off the control queue
accordingtothepresentcontrolmoderules.Dispatchescontolactionstopropercontrol
element"DoPendingAction"handlers.
_InitSnap
For step control of solution process: Intialize iteration counters, etc. that normally
occursatthestartofasnapshotsolutionprocess.
_SampleControls
For step control of solution process: Sample the control elements, which push control
actionrequestsontothecontrolqueue.
Page 60 of 180
OpenDSS Manual
June 2013
_ShowControlQueue
Forstepcontrolofsolutionprocess:Showthepresentcontrolqueuecontents.
_SolveDirect
Forstepcontrolofsolutionprocess:InvokedirectsolutionfunctioninDSS.Noniterative
solutionofYmatrixandactivesourcesonly.
_SolveNoControl
For step control of solution process: Solves the circuit in present state but does not
checkforcontrolactions.
_SolvePFlow
Forstepcontrolofsolutionprocess:InvokeiterativepowerflowsolutionfunctionofDSS
directly.
? [Object Property Name]

The ? command allows you to query the present value of any published property of a DSS
circuitelement.Forexample,
?Monitor.mon1.mode
isonewaytogetthemodedefinedfortheMonitornamedMon1.
The value is returned in the "Result" property of the DSS COM Text interface (See COM
interface).ItalsoappearsintheResultwindowofthestandaloneexecutableimmediatelyafter
executionofthecommand.
About
Displaysthe"About"box.TheResultstringissettotheversionstring.
AddBusMarker
Addamarkertoabusinacircuitplot.MarkersmustbeaddedbeforeissuingthePlotcommand.
EffectispersistentuntilcircuitisclearedorClearBusMarkerscommandisissued.Example:
ClearBusMarkers
!...Clears any previous bus markers
AddBusMarker Bus=Mybusname1 code=5 color=Red size=3
AddBusMarker Bus=Mybusname2 code=5 color=Red size=3
...
YoucanuseanyofthestandardcolornamesorRGBnumbers.SeeHelponC1propertyinPlot
command.
To clear the present definitions of bus markers, issue the ClearBusMarkers command. If you
specify a busname that doesnt exist, it is simply ignored. See Set Markercode= description
belowtoseealistofmarkercodespresentlyimplemented.
AlignFile
Aligns the commands and properties of DSS script files into even columns for easier reading.
CreatesanewfilewiththestringAligned_prependedandopensthefileinthedefaulteditor.
Youmayusethecreatedfileinplaceoftheoriginalifdesired.
Page 61 of 180
OpenDSS Manual
June 2013
Alignfile [file=]filename.
AllocateLoads
Estimates the allocation factors for loads that are defined using the XFKVA property. Requires
thatenergymeterobjectsbedefinedwiththePEAKCURRENTpropertyset.Loadsthatarenotin
thezoneofanenergymetercannotbeallocated.Thiscommandadjuststheallocationfactors
fortheappropriateloadsuntilthebestmatchpossibletothemetervaluesisachieved.Loads
areadjustedbyphase.Thereforeallsinglephaseloadsonthesamephasewillendupwiththe
sameallocationfactors.
IfloadsarenotdefinedwiththeXKVAproperty,theyareignoredbythiscommand.
BatchEdit
Batcheditobjectsinthesameclass.Usefulforwholesalechangestoobjectsofthesameclass.
Example:
BatchEdit Load..* duty=duty_shape
In place of the object name, supply a PERL regular expression. .* matches all names. The
subsequent parameter string is applied to each object selected. This example is equivalent to
creatingascriptfilecontainingthefollowingcommands,forexample:
Load.Load1.duty=dutyshape
Etc.
BuildY
ForcesrebuildofYmatrixuponnextSolvecommandregardlessofneed.Theusualreasonfor
doing this would be to reset the matrix for another load level when using
LoadModel=PowerFlow(thedefault),ifthesystemisdifficulttosolvewhentheloadisfarfrom
its base value. Some of the load elements will recompute their primitive Y to facilitate
convergence. Works by invalidating the Y primitive matrices for all the Power Conversion
elements.
BusCoords
Definex,ycoordinatesforbuses.ExecuteafterSolveorMakeBusListcommandisexecutedso
thatbuslistsaredefined.ReadscoordinatesfromaCSVfilewithrecordsoftheform:
busname, x, y.
Youmayusespacesandtabsaswellascommasforvalueseparators.
Example:
BusCoords [file=]xxxx.csv
SeealsoLatLongCoords.
CalcVoltageBases
Estimatesthevoltagebaseforeachbusbasedonthearrayofvoltagebasesdefinedwitha"Set
Voltagebases=..." command. Performs a zerocurrent power flow considering only the series
Page 62 of 180
OpenDSS Manual
June 2013
powerdelivery elements of the system. No loads, generators, or other shunt elements are
includedinthesolution.Thevoltagebaseforeachbusisthensettothenearestvoltagebase
specifiedinthevoltagebasearray.
Alternatively, you may use the SetkVBase command to set the voltage base for each bus
individually.NotethattheOpenDSSdoesnotneedthevoltagebaseformostcalculations,but
usesitforreporting.ExceptionsincludeprocessesliketheAutoAddsolutionmodewherethe
program needs to specify the voltage rating of capacitors and generators it will automatically
addtothesystem.Also,somecontrolsmayneedthebasevoltagetoworkbetter.
Itisusefultoshowthebusvoltagesaftertheexecutionofthiscommand.Thiswillhelpconfirm
thateverythinginthecircuitisconnectedasitshouldbe.Itisespeciallyusefulfordeviceswith
unusualconnections.SupplementthischeckwithaFaultstudymodesolutiontoverifythatthe
systemimpedancesarealsoproperlyspecified.
Capacity
Find the maximum load the active circuit can serve in the PRESENT YEAR. Gradually increases
the load until something in the circuit is overloaded. Uses the EnergyMeter objects with the
registers set with the SET UEREGS= (..) command for the AutoAdd functions. Syntax (defaults
shown):
capacity [start=]0.9 [increment=]0.005
Returns the metered kW (load + losses generation) and the per unit load multiplier for the
loading level at which something in the system reports an overload or undervoltage. If no
violations,thenitreturnsthemeteredkWforpeakloadfortheyear(1.0multiplier).Abortsand
returns0ifnoenergymeters.
CD Directoryname
Changesthecurrentdirectorytothespecifieddirectory.Thecurrentdirectoryisalsochangedif
afullpathnameissuppliedfortheCompilecommand.
CktLosses
ReturnsthetotallossesfortheactivecircuitintheResultstringinkW,kvar.
Clear
Clears all circuit element definitions from the DSS. This statement is recommended at the
beginningofallMasterfilesfordefiningDSScircuits.
ClearBusMarkers
ClearallbusmarkerscreatedwiththeAddBusMarkercommand.
Close [Object] [Term] [Cond]

OppositeofOpencommand.
CloseDI
CloseallDemandInterval(DI)files.Thismustbeissuedattheendofthefinalyearlysolutionin
aYearlyorDailymoderunwhereDIfilesareleftopenwhilechangesaremadetothecircuit.
Reset and Set Year=nnn will also close the DI files. See Set DemandInterval= option. DI files
Page 63 of 180
OpenDSS Manual
June 2013
remain open once the yearly simulation begins to allow for changes and interactions from
outside programs during the simulation. They must be closed before viewing the results.
OtherwisecomputersystemI/Oerrorsmayresult.
Comparecases
[Case1=]casename [case2=]casename [register=](register number) [meter=]{Totals* |
SystemMeter|metername}.
Compares yearly simulations of two specified cases with respect to the quantity in the
designatedregisterfromthedesignatedmeterfile.Defaults:Register=9,Meter=Totals.
Example:
Comparecases base pvgens 10
Compile or Redirect [fileName]

The Compile and Redirect commands simply redirect the command interpreter to take input
directlyfromatextfileratherthanfromtheCommandpropertyoftheCOMTextinterface(the
default method of communicating with the DSS) or the text form of the EXE version. The
commandsaresimilarexceptthatRedirectreturnstothedirectoryfromwhichitwasinvoked
whileCompileresetthecurrentdirectorytothatofthefilebeingcompiled.InDSSconvention,
useCompilewhendefininganewcircuitandRedirectwithinscriptfilestosignifythattheinput
isredirectedtoanotherfiletemporarilyforthepurposeofnestingscriptfiles.Useexactlythe
same syntax that you would supply to the Command property of the COM interface. Do not
wraplines;thereisnolineconceptwiththeDSScommands.Eachcommandmustbeonitsown
lineinthefile.UsetheMorecommandoritsabbreviation~tocontinueeditinganewline.
Currents
Returns the currents for each conductor of ALL terminals of the active circuit element in the
Resultstring.(SeeSelectcommand.)Returnedascommaseparatedmagnitudeandangle.
DI_plot
[case=]casename [year=]yr [registers=](reg1, reg2,...)
[meter=]metername
[peak=]y/n
Plots demand interval (DI) results from yearly simulation cases. Plots selected registers from
selected meter file (default = DI_Totals.CSV). Peak defaults to NO. If YES, only daily peak of
specifiedregistersisplotted.Example:
DI_Plot basecase year=5 registers=(9,11) no
Disable [Object]
Disablesobjectinactivecircuit.AllobjectsareEnabledwhenfirstdefined.Usethiscommandif
you wish to temporarily remove an object from the active circuit, for a contingency case, for
example.Ifthisresultsinisolatingaportionofthecircuit,thevoltagesforthosebuseswillbe
computedtobezero.(AlsoseeOpen,Closecommands.)
Distribute
kw=nn how={Proportional | Uniform |Random | Skip} skip=nn PF=nn
file=filename MW=nn
Page 64 of 180
OpenDSS Manual
June 2013
Distributes generators over the system in the manner specified by "how". This command is
usefulforstudyingdistributedrooftopsolarPVforexample.Afileissavedthatmaybeedited,if
necessary,andusedinsubsequentsimulations.
kW=totalgenerationtobedistributed(default=1000)
how=processnameasindicated(default=proportionaltoload)
skip=no.ofbusestoskipfor"How=Skip"(default=1)
PF=powerfactorfornewgenerators(default=1.0)
file=nameoffiletosave(default=distgenerators.txt)
MW=alternatewaytospecifykW(default=1)
Example
Distribute kW=2000 how=proportional PF=1 file=MyPVGenfile.DSS
DOScmd /c ...command string ...

ExecuteaDOScommandfromwithintheDSS.Closesthewindowwhenthecommandisdone.
TokeeptheDOSwindowopen,use/kswitch.
Dump <Circuit Element> [Debug]

WritesatextfileshowingallthepropertiesofthecircuitobjectanddisplaysitwiththeDSStext
editor.Youwouldusethiscommandtocheckthedefinitionofelements.Itisalsoprintedina
format that would allow it to be fed back into the DSS with no, or only minor, editing. If the
dump command is used without an object reference, all elements in the active circuit are
dumpedtoafile,whichcouldbequitevoluminous.
If the Debug option is specified, considerably more information is dumped including the
primitiveYmatricesandotherinternalDSSinformation.
Youcanlimitthedumptoallelementsofaspecificclassbyusingthewildcard,*,character:For
example,
Dump Transformer.* debug
Willdumpallinformationonalltransformers.Leavedebugofftojustseepropertyvalues.
Edit [Object] [Edit String]

Editstheobjectspecified.TheobjectClassandNamefieldsarerequiredandmustdesignatea
validobject(previouslyinstantiatedbyaNewcommand)intheproblem.Otherwise,nothingis
doneandanerrorisposted.
The edit string is passed on to the object named to process. The DSS main program does not
attempt to interpret property values for circuit element classes. These can and do change
periodically.
Page 65 of 180
OpenDSS Manual
June 2013
Enable [Object]
CancelsapreviousDisablecommand.AllobjectsareautomaticallyEnabledwhenfirstdefined.
Therefore,theuseofthiscommandisunnecessaryuntilanobjecthasbeenfirstdisabled.(Also
seeOpen,Closecommands.)
Estimate
Executestateestimatoronpresentcircuitgivenpresentsensorvalues.SeealsoAllocateLoads.
Export <Quantity> [Filename or switch]

Writesatextfile(.CSV)ofthespecifiedquantityforthemostrecentsolution.DefaultstoExport
Voltages. The purpose of this command is to produce a file that is readily readable by other
programssuchasMATLAB(usecsvread),spreadsheetprograms,ordatabaseprograms.
Thefirstrecordisaheaderrecordprovidingthenamesofthefields.Theremainingrecordsare
fordata.Forexample,thevoltageexportlookslikethis:
Bus, Node Ref., Node, Magnitude, Angle, p.u., Base kV
sourcebus
1,
1,
6.6395E+0004,
0.0,
1.000,
115.00
sourcebus
2,
2,
6.6395E+0004, -120.0,
1.000,
115.00
sourcebus
3,
3,
6.6395E+0004,
120.0,
1.000,
115.00
subbus
4,
1,
7.1996E+0003,
30.0,
1.000,
12.47
subbus
5,
2,
7.1996E+0003,
-90.0,
1.000,
12.47
subbus
6,
3,
7.1996E+0003,
150.0,
1.000,
12.47
Thisformatiscommonformanyspreadsheetsanddatabases,althoughdatabasesmayrequire
fieldtypesandsizesfordirectimport.Thecolumnsarealignedforbetterreadability.
Validsyntaxforthecommandcanbeoneofthefollowingstatementprototypesinbold.Ifthe
Filenameisomitted,thefilenamedefaultstothenameshowninitalicsinparantheses.(This
list is incomplete. Check Help for the Export commands on line. When in doubt, execute the
exportandobservetheresult.)
ExportVoltages[Filename](EXP_VOLTAGES.CSV).Exportsvoltagesforeverybusand
activenodeinthecircuit.(Magnitudeandangleformat).
ExportSeqVoltages[Filename](EXP_SEQVOLTAGES.CSV)Exportsthesequencevoltage
magnitudesandthepercentofnegativeandzerosequencetopositivesequence.
ExportCurrents[Filename](EXP_CURRENTS.CSV)Exportscurrentsinmagnitudeand
angleforeachphaseofeachterminalofeachdevice.
Export Overloads [Filename] EXP_OVERLOADS.CSV) Exports positive sequence
current for each device and the percent of overload for each power delivery element
thatisoverloaded.
Export SeqCurrents [Filename] (EXP_SEQCURRENTS.CSV) Exports the sequence
currentsforeachterminalofeachelementofthecircuit.
Page 66 of 180
OpenDSS Manual
June 2013
Export Powers [MVA] [Filename] (EXP_POWERS.CSV) Exports the powers for each
terminal of each element of the circuit. If the MVA switch is specified, the result are
specifiedinMVA.Otherwise,theresultsareinkVAunits.
Export Faultstudy [Filename] (EXP_FAULTS.CSV) Exports a simple report of the 3
phase,1phaseandmaxLLfaultateachbus.
Export Loads[Filename] (EXP_LOADS.CSV) Exportsthefollowdataforeachload
objectinthecircuit:ConnectedKVA,AllocationFactor,Phases,kW,kvar,PF,Model.
Export Monitors monitorname (file name is assigned) Automatically creates a
separate filename for each monitor. Exports the monitor record corresponding the
monitor'smode.Thiswillvaryfordifferentmodes.
Export Meters [Filename | /multiple ] (EXP_METERS.CSV)
Export Generators [Filename | /multiple ] (EXP_GENMETERS.CSV)
EnergyMeter and Generator object exports are similar. Both export the time and the
values of the energy registers in the two classes of objects. In contrast to the other
Exportoptions,eachinvocationoftheseexportcommandsappendsarecordtothefile.
For Energymeter and Generator, specifying the switch "/multiple" (or /m) for the file
namewillcauseaseparatefiletobewrittenforeachmeterorgenerator.Thedefaultis
forasinglefilecontainingallmeterorgeneratorelements.
ExportYprims[Filename](EXP_Yprims.CSV).ExportsallprimitiveYmatricesforthe
presentcircuittoaCSVfile.
ExportY[Filename](EXP_Y.CSV).ExportsthepresentsystemYmatrixtoaCSVfile.
Usefulforimportingintoanotherapplication.Note:ThisfilecanbeHUGE!
ExportSeqZ [Filename] (EXP_SEQZ.CSV).Exportsthe equivalentsequenceshort
circuit impedances at each bus. Should be preceded by a successful Solve
Mode=Faultstudycommand.Thiswillinitializetheshortcircuitimpedancematricesat
eachbus.
Fileedit [filename]
Editspecifiedfileindefaulttextfileeditor(seeSetEditor=option).
Fileedit EXP_METERS.CSV
(brings up the meters export file)
Formedit [Class.Object]
BringsupformeditortodisplaythepresentpropertyofthespecifiedactiveDSSobject.Youmay
changethevaluesofpropertiesonthisformforthepresentsolution.However,thechangesare
NOTautomaticallysavedtotheoriginalscriptfiles.YoumustexecuteaSaveCircuittocapture
the changes. This command may be executed from the speed button to the right of the two
dropdownboxesatthetopofthecontrolpanel.(totherightofthe1000KVAboxinthefigure
below).Theresultisshowninthefigure.
Page 67 of 180
OpenDSS Manual
June 2013
Get [Opt1] [opt2] etc.

Basically,theoppositeoftheSETcommand.ReturnsDSSpropertyvaluesforoptionssetusing
theSetcommand.ResultisreturnedintheResultpropertyoftheTextinterface.
VBAExample:
DSSText.Command = "Get mode"
Answer = DSSText.Result
Multiplepropertiesmayberequestedononeget.Theresultsareappendedandtheindividual
valuesseparatedbycommas.Arrayvaluesarereturnedseparatedbycommas.
Page 68 of 180
OpenDSS Manual
June 2013
SeeSetcommanddescription.
Guids
ReadGUIDS(Globallyuniqueidentifiers)forclassnames.Taborcommadelimitedfilewithfull
objectnameandGUID
Help
Bringsupahelpwindowwithatreeviewofallthecommandsandpropertynamescurrently
acceptedbytheDSS.(Thisisgenerallymoreuptodatethantheprintedmanualsbecausenew
featuresarebeingcontinuallyadded.)Clickingonthecommandswilldisplayabriefdescription
ofhowtousetheparticularcommandorproperty.
Init
This command forces reinitialization of the solution for the next Solve command. To minimize
iterations,mostsolutionsstartwiththeprevioussolutionunlesstherehasbeenacircuitchange.
However,iftheprevioussolutionisbad,itmaybenecessarytoreinitialize.Inmostcases,are
initialization results in a zeroload power flow solution with only the series power delivery
elementsconsidered.
Interpolate {All | MeterName}

Default is "All". Interpolates coordinates for missing bus coordinates in meter zones. Only
affects buses on line sections contained in a Energymeter zone. Fills in evenly spaced
coordinatesbetweenexistingcoordinates.
LatLongCoords
Definex,ycoordinatesforbusesusingLatitudeandLongitudevalues(decimalnumbers).Similar
toBusCoordscommand.ExecuteafterSolvecommandorMakeBusListcommandisexecutedso
thatbuslistsaredefined.ReadscoordinatesfromaCSVfilewithrecordsoftheform:
busname, Latitude, Longitude.
Example:
LatLongCoords [file=]xxxx.csv
Note:LongitudeismappedtoxcoordinateandLatitudeismappedtoycoordinate.
Losses
Returnsthetotallossesfortheactivecircuitelement(seeSelectcommand)intheResultstring
inkW,kvar.
MakeBusList
Updates the buslist, if needed, using the currently enabled circuit elements. (This happens
automaticallyforSolvecommand.)SeeReprocessBuses
MakePosSeq
Attempts to convert the present 3phase, or multiphase, circuit model to a singlephase
positivesequenceequivalent.ItisrecommendedthatyouexecuteaSaveCircuitafterissuing
this and edit the saved version to correct possible misinterpretations. Some devices such as
Page 69 of 180
OpenDSS Manual
June 2013

singlephaseregulatorswillhavetobemanuallyconverted.
More | M | ~ | [Edit String]

TheMorecommand continuesediting theactiveobjectlastselectedbyaNew,Edit,orSelect
command.Itsimplypassestheeditstringtotheobject'seditingfunction(actually,theactive
objects editing function simply takes control of the parser afterit is determined that this is a
Morecommand).
TheMorecommandmaybeabbreviatedwithsimplyMor~.
Examples:
!Line from Bs1 to Bs2
New Line.Lin2 Bs1 Bs2
More R1=.01 X1=.5 Length=1.3
New Line.Lin2 Bs1 Bs2 R1=.01 X1=.5 Length=1.3
M
C1=3.4 R1 = .02
! define C1 and re-define R1
New Object=Line.Lin2
~ Bus1=Bs1 Bus2=Bs2.2.3.1
! Transposition line
~ R1=.01 X1=.5
~ Length=1.3
New [Object] [Edit String]

Adds an element described on the remainder of the line to the active circuit. The first
parameter(Object=)isrequiredfortheNewcommand.Ofcourse,Object=maybeomitted
andoftenisforaesthetics.
The remainder of the command line is processed by the editing function of the specified
elementtype.Allcircuitobjectsareinstantiatedwithareasonablesetofvaluessothattheycan
likelybeincludedinthecircuitandsolvedwithoutmodification.Therefore,theEditStringneed
onlyincludedefinitionsforpropertyvaluesthataredifferentthanthedefaults.
Examples:
New Object=Line.Lin2
New Line.Lin2
New Line.Lin2 Bs1 Bs2
! Min required
! Same, sans object=
R1=.01 X1=.5 Length=1.3
The Edit String does not have to be complete at the time of issuing the New command. The
objectinstantiatedmaybeeditedagainatanylatertimebyinvokingtheEditcommandorby
continuingwiththenextcommandline(seeMoreor~).Thelatertimedoesnothavetooccur
immediately after definition. One can make up a script later that edits one or more object
properties.
ImmediatelyafterissuingtheNewcommand,theinstantiatedobjectremainstheactiveobject
andtheEditcommanddoesnothavetobegiventoselecttheobjectforfurtherediting.You
can simply issue the More command, or one of its abbreviations (~), and continue to send
editinginstructions.Actually,theDSScommandinterpreterdefaultstoeditingmodeandyou
Page 70 of 180
OpenDSS Manual
June 2013

maysimplyissuethecommand
Property=value(andothereditingstatements)
The"="isrequiredwhenusingthisformat.WhentheDSSparserseesthis,itwillassumeyou
wish to continue editing and are not issuing a separate DSS Command. To avoid ambiguity,
whichisalwaysrecommendedforreadability,youmayspecifytheelementcompletely:
Class.ElementName.Property=Value
Morethanonepropertymaybesetonthesamecommand,justasifyouhadissuedtheNewor
Editcommands.
Class.ElementName.Property1=Value1property2=value2
Note that all DSS objects have a Like property inherited from the base class. Users are
somewhatatthemercyofdevelopers toensure theyhaveimplemented theLikefeature,but
thishasbeendoneonallDSSobjectstodate.Whenanotherelementofthesameclassisvery
similartoanewonebeingcreated,usetheLikeparametertostartthedefinitionthenchange
onlytheparametersthatdiffer.IssuetheLike=nnnnpropertyfirst.Commandlinesareparsed
fromlefttorightwiththelateronestakingprecedence.ThroughouttheDSS,thedesigngoalis
thatapropertypersistentlyremainsinitslaststateuntilsubsequentlychanged.
New Line.Lin3 like=Lin2 Length=1.7
WhilealldeviceshaveaLikeproperty,forLineobjectsandTransformerobjects,usersgenerally
prefer to use the Linecode and Xfmrcode properties instead when objects have the same
properties.
[Object Property Name] = value

ThissyntaxpermitsthesettingofanypublishedpropertyvalueofaDSScircuitelement.Simply
specifythecompleteelementandpropertyname,=,andavalue.Forexample,
Monitor.mon1.mode=48
Setsthemonitormodequeriedinthepreviousexample.TheDSScommandinterpreterdefaults
totheEditcommand.Ifitdoesnotrecognizethecommanditlooksforthe"="andattemptsto
edit a property as specified. Thus, in this example, this method simply invokes the Monitor
objects editor and sets the value. If there is more text on the string, the editor continues
editing.Forexample,
Line.line1.R1=.05
.12
.1
.4
willsettheR1,X1,R0,X0propertiesofLine.line1insequence usingpositionalpropertyrules.
This is a convenient syntax to use to change properties in circuit elements that have already
beendefined.
Page 71 of 180
OpenDSS Manual
June 2013
NodeDiff
The global result variable is set to voltage difference, volts and degrees, (Node1 Node2)
betweenanytwonodes.Syntax:
NodeDiff Node1=MyBus.1 Node2=MyOtherBus.1
IntheEXEversion,thisvaluewillshowupintheResultwindow.FromtheCOMserver,youcan
accessthevaluefromtheResultpropertyintheTextinterface.
Obfuscate
Change Bus and circuit element names to generic values to remove identifying names.
Generally,youwillfollowthiscommandimmediatelyby
Save Circuit Dir=MyDirName.
Thisisusefulwhenmakingacircuitmodelpublicandyouwishthescrubamodelofidentifying
names.
Open [Object] [Term] [Cond]

Opens a specified terminal conductor switch. All conductors in the terminals of all circuit
elementshaveaninherentswitch.Thiscommandcanbeusedtoopenoneormoreconductors
inaspecifiedterminal.Ifthe'Cond='fieldis0oromitted,allphaseconductorsareopened.Any
otherconductorstheremightbeareunaffected.Otherwise,openoneconductoratatime(one
percommand).Forexample:
Open object=line.linxx term=1
! opens all phase conductors of
terminal 1 of linxx
Open line.linxx 2 3
! opens 3rd conductor of 2nd terminal of linxx
line object
Open load.LD3 1 4
! opens neutral conductor of wye-connected 3-phase
load
Noactionistakenifeithertheterminalorconductorspecificationsareinvalid.
Note,thisactiondisconnectstheterminalfromthenodetowhichitisnormallyconnected.The
noderemainsintheproblem.Ifitbecomesisolated,atinyconductanceisattachedtoitandthe
voltage computes to zero. But you have to worry less about it causing a floating point
exception.
PhaseLosses
Returns the losses for the active circuit element (see Select command) for each PHASE in the
ResultstringincommaseparatedkW,kvarpairs.
Plot (options )
ChecktheHelpintheEXEversionforadditionstothePlotcommand.Therearemanyoptionsto
thePlotcommandandithasbeenmovedtoitsownbranchintheHelptree.
Plotisarathercomplexcommandthatdisplaysavarietyofresultsinavarietyofmannerson
graphs.Youshouldusethecontrolpaneltoexecutetheplotcommandwiththerecorderonto
seeexamplesofhowtoconstructtheplotcommand.Implementedoptionsinclude(inorder):
Page 72 of 180
OpenDSS Manual
June 2013
Type={Circuit|Monitor|Daisy|Zones|AutoAdd|General(busdata)|Loadshape|Tshape|
Priceshape|Profile}.ACircuitplotrequiresthatthebuscoordinatesbedefined.By
defaultthethicknessofthecircuitlinesisdrawnproportionaltopower.ADaisy
plotisaspecialcircuitplotthatshowsauniquesymbolforgenerators.(When
therearemanygeneratorsatthesamebus,theplotresemblesadaisy.)The
MonitorplotplotsoneormorechannelsfromaMonitorelement.TheZonesplot
drawstheenergymeterzones.Autoaddshowsautoaddedelementsonthecircuit
plot.GeneralexpectsaCSVfileofbusdatawithbusnameandanumberofvalues.
SpecifywhichvaluetoplotinQuantity=property.Buscolorsareinterpolatedbased
onthespecificationofC1,C2,andC3.
Quantity={Voltage|Current|Power|Losses|Capacity|(ValueIndexforGeneral,AutoAdd,
orCircuit[w/file])}Specifyquantityorvalueindextobeplotted.
Max={0|valuecorrespondingtomaxscaleorlinethickness}
Dots={Y|N}Turnson/offthedotsymbolforbuslocationsonthecircuitplot.
Labels={Y|N}Turnson/offthebuslabelsonthecircuitplot(withallbuslabelsdisplayed,the
plotcangetclutteredzoomintoseeindividualnames)
Object=[meternameforZoneplot|Monitorname|FileNameforGeneralbusdataorCircuit
branchdata|Loadshapename].Specifieswhatobjecttoplot:meterzones,
monitororCSVfile,orpreviouslydefinedLoadshape.Note:forLoadshapeplot,
boththeMultandQmultproperties,ifdefined,areplotted.
ShowLoops={Y|N}(default=N).Showstheloopsinmeterzoneinred.NotethattheDSShas
noproblemsolvingloops;Thisistohelpdetectunintentionalloopsinradialcircuits.
R3=puvaluefortricolorplotmaxrange[0.85](ColorC3)
R2=puvaluefortricolorplotmidrange[0.50](ColorC2)
C1,C2,C3={RGBcolornumber}.Threecolorvariablesusedforvariousplots.
Channels=(arrayofchannelnumbersformonitorplot).Morethanonemonitorchannelcanbe
plottedonthesamegraph.Ex:Channels=[1,3,5]
Bases=(arrayofbasevaluesforeachchannelformonitorplot).Defaultis1.0foreach.Thiswill
perunitizetheplottothespecifiedbases.SetBases=[]afterdefiningchannels.
Subs={Y|N}(default=N)(showsubstations)SeeTransformerdefinition
Thickness=maxthicknessallowedforlinesincircuitplots(default=7).Usefulforcontrolling
aestheticsoncircuitplots.
Buslist={ArrayofBusNames|File=filename}ThisisfortheDaisyplot.
Plot daisy power max=5000 dots=N Buslist=[file=MyBusList.txt]
A"daisy"markerisplottedforeachbusinthelist.Busnamesmayberepeated,
whichresultsinmultiplemarkersdistributedinacirclearoundthebuslocation.
Thisgivestheappearanceofadaisyifthereareseveralsymbolsatabus.Not
neededforplottingactivegenerators.
Phases={default*|ALL|PRIMARY|LL3ph|LLALL|LLPRIMARY|(phasenumber)}ForProfile
plot.Specifywhichphasesyouwantplotted.
default=plotonlynodes13at3phasebuses(default)
ALL=plotallnodes
PRIMARY=plotallnodesprimaryonly(voltage>1kV)
Page 73 of 180
OpenDSS Manual
June 2013
LL3ph=3phbusesonlyLLvoltages)
LLALL=plotallnodesLLvoltages)
LLPRIMARY=plotallnodesLLvoltagesprimaryonly)
(phasenumber)=plotallnodesonselectedphase
Note:Onlynodesdownlinefromanenergymeterareplotted.
Loadshapesmaybeplottedfromthecontrolpaneloftheuserinterface.
PowerandLossesarespecifiedinkW.C1usedfordefaultcolor.C2,C3usedforgradients,tri
colorplots.ScaledeterminedautomaticallyofMax=0ornotspecified.Someexamples:
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
Plot
circuit quantity=7 Max=.010 dots=Y Object=branchdata.csv

General Quantity=2 Object=valuefile.csv
type=circuit quantity=power
Circuit Losses 1phlinestyle=3
Circuit quantity=3 object=mybranchdata.csv
daisy power 5000 dots=N
daisy power max=5000 dots=N Buslist=[file=MyBusList.txt]
General quantity=1 object=mybusdata.csv
Loadshape object=myloadshape
Tshape object=mytemperatureshape
Priceshape object=mypriceshape
Profile
Profile Phases=Primary
AutoAddandGeneralPlots
Youcanmakeplotsthatshowvaluescomputedforbusesinacoupleofdifferentways.Ifyou
are auto adding generators, the DSS keeps an "DSS_autoaddlog.csv" file. You can plot the
valuesinthecolumnsofthisfilebysayingsomethinglikethis(theDSSuserinterfacewillhelp
youconstructthiscommandifyouturnontherecorder):
plot type=Auto quantity=3 Max=2000 dots=n labels=n C1=16711680 C2=8421376
C3=255 R3=0.75 R2=0.5
Maxdoesn'tmeananythinghere,buttheOpenDSSEXEwillthrowitinanyway.
Quantity=3: Column 3 is % improvement in losses. The DSS will put colored marker
circles on the node points, with one of the 3 colors indicated. First the min and max
valuesinthefileisdeterminedtosettherangeoftheplot.Thenthefileisreadinagain
andthenodemarkersareaddedtotheplotintheorderthey areencounteredin the
file.IfthevalueisgreaterthanfractionofthetotalrangedesignatedbyR3,colorC3is
used. If between R2 and R3, then C2 is used, else C1 is used. In this example, C1 is
blue,c2isgreenandC3isred.
If you have a lot of overlapping nodes, you may wish to sort the CSV file (use Excel) on the
columnofinterestbeforeplotting.Usually,youwillwanttosortthecolumnascending.That
way, in the example, the C3 nodes will show up clearly on a background of C2 and C1
respectively.That'susuallywhatyouwant.
TheAutoaddplotisaspecialcaseoftheGeneralplot.HereisanexampleofaGeneralplot.
plot General quantity=1 Max=2000 dots=n labels=n
Page 74 of 180
OpenDSS Manual
June 2013
object=(C:\Projects\PosSeqModelNoSw2\16-500KW-amps_Fault.csv) C1=16777088
C2=255
Note that this only uses two colors and an object must be specified. This is the file name
containingatleasttwocolumns:thebusnamefollowedbyoneormorecolumnsofvalues.In
thiscase,thefirstvalueisused.Again,themax=issuperfluous.
ForaGeneralplot,thevaluesaredepictedasatransitionfromcolorC1toC2.C2representsthe
highendoftherangeandC1isthelowend.ThecolorsareinterpolatedmaintainingtheirRGB
proportions.Generally,you'llwantC2tobesomedarkcolorsuchassolidredandC1alighter
color.And,ifthenodemarkersoverlap,itisgenerallybesttosortthefileyouareplottingin
ascendingorderbeforeexecutingthiscommand.
GeneralCircuitPlots
Ifyouwishtogenerateacircuitplotwiththewidthofthelinescontrolledbysomethingother
thanvoltage,current,losses,power,orcapacity,createacsvfilewiththefirstcolumnbeingthe
fullnameofthelineandoneormorecolumnsofvalues.SettheQuantity=propertytothevalue
columnofinterest.SpecifythefilenameintheObject=property.
The program will generate a circuit plot of the quantity specified with the width being
proportionaltothevaluecomparedtotheMax=property.
Powers
Returnsthepowers(complex)goingintoeachconductorsofALLterminalsoftheactivecircuit
element in the Result string. (See Select command.) Returned as commaseparated kW and
kvar.
Pstcalc
Pstestimation.
PstCalc Npts=nnn Voltages=[array] dt=nnn freq=nn lamp=120 or 230.
Set Npts to a big enough value to hold the incoming voltage array. dt = time increment in
seconds. default is 1. freq = base frequency in Hz 50 or 60. Default is default base frequency.
Lamp=120forNorthAmerica;230forEurope.Defaultis120.Example:
PSTCalc Npts=1900 V=[file=MyCSVFile.CSV, Col=3, Header=y] dt=1 freq=60
lamp=120
Reconductor Line1=name1 Line2=name2 {Linecode= | Geometry=}

TheReconductorcommandwillchangetheLinecodeorGeometrydefinitionforallLineobjects
betweenLine1andLine2.YoucanspecifyLine1andLine2ineitherorder;theOpenDSSfigures
outhowtotracebetweenthem,ifthereisapath.TheOpenDSSwilltracebetweenLine1and
Line2,replacingeithertheLinecodepropertyortheGeometrypropertywiththevaluespecified.
Thereiserrorcheckingtomakesurethatthelinesexistandthereisapathbetweenthem.The
commandworkslikemostotherDSScommands.Therightmostspecificationofapropertytakes
precedence.Normally,youwouldspecifyonlyoneofLinecodeorGeometry.Itisnotpossibleto
applyboth.
Page 75 of 180
OpenDSS Manual
June 2013
BothlinesmustbewithinanEnergymeterzoneandmustbeinthesamezone.Onelinemustbe
uplinefromtheotherinthepathbacktotheEnergymeterlocation.Otherwise,anerroroccurs.
Line names are specified without the "Line." prefix since only Line objects are expected.
However,ifyouspecifyafullyqualifiedlinename(line.xxxx),the"Line."prefixissimplyignored.
Note: The action of the Reconductor command applies only to the active session. It does not
change your input scripts. You have to save the circuit to a new circuit script to save the
changes.However,youcansimplyaddtheReconductorcommandtoyourexistingscriptsothat
itchangestheconductorseachtimeyouloadthescript.Thecommandwouldbeplaced after
the meter zones are established, which occurs after the initial Solve command or the
MakeBusListcommand.
Redirect [filename]
Redirects the OpenDSS input stream to the designated file that is expected to contain DSS
commands. It processes them as if they were entered directly into the command line. Do not
wrap lines in the DSS files (you may use the ~, or more, command.) Similar to "Compile", but
leaves current directory where it was when Redirect command was invoked. Will temporarily
change to subdirectories if there are nested Redirect commands that change to other folders.
SeeCompile.
Example:
redirect filename
Note:Ifyouusearelativefilename(noorpartialpath)thefileexpectedtobeinthecurrent
default data directory. If you get an unexpected message that a file was notfound, check the
path listed in the window caption (EXE control panel). Often, if you rightclick on the script
windowandclickontheChangetothisdirectoryoption,theproblemisresolve.Usefullpath
names for librarytype files of general data that are kept in other folders. (See also the CD
command.)
Reduce {All | MeterName}

Default is "All". Reduce the circuit according to circuit reduction options. See "Set
ReduceOptions" and "Set Keeplist" options The Energymeter objects actually perform the
reduction."All"causesallmeterstoreducetheirzones.
Rephase
Generatesascriptfiletochange thephasedesignationofallLineobjectsdownstreamfroma
startingLine.Usefulforsuchthingsasmovingasinglephaselateralfromonephasetoanother
whilekeepingthephasedesignationconsistentforreportingfunctionsthatneedittobe(Note:
thisisnotrequiredforsimplysolvingpowerflow.TheOpenDSSdoesntcarewhatyoucallthe
nodes.).
Parameters
StartLine=...
PhaseDesignation="..."
EditString="..."
ScriptFileName=...
Page 76 of 180
OpenDSS Manual
June 2013
StopAtTransformers=Y/N/T/F
Enclose the PhaseDesignation in quotes since it contains periods (dots). You may add an
optionalEditStringtoeditanyotherlineproperties.
Example:
Rephase StartLine=Line.L100 PhaseDesignation=".2"
ScriptFile=Myphasechangefile.DSS Stop=No
EditString="phases=1"
This produces a script file that you may edit to achieve the desired result (some complex
connectionsmaygetmisinterpreted).Includethisscriptinsubsequentsimulationstomovethe
lines in question after building the base circuit. This command was used in the EPRI Green
Circuitsprojecttoinvestigatetheimpactsofbalancingthephasesbymovingentirelaterals.
ReprocessBuses
Forces reprocessing of bus definitions whether there has been a change or not. Use for
rebuilding meterzonelistswhenalinelength changes,forexampleorsomeothereventthat
wouldnotnormallytriggeranupdatetothebuslist.Maybedoneatanytime,butisgenerally
notnecessaryunlessyounoticesomethingsuchasalinelengthchangeisnotrepresentedona
profileplot.TheseplotsarecreatedfromEnergymeterzonesanditmaybenecessarytorefresh
thezonestoreflecttheproperlengths.
Reset {Meters | Monitors }

{Monitors | Meters | (no argument) } Resets all Monitors or Energymeters as specified. If no
argumentspecified,resetsmetersandmonitors.
Rotate angle=degrees
Rotate the circuit plot coordinates by the specified number of degrees. This comes in handy
sometimestoalignwithmaps,etc.
Sample
Force all monitors and Energymeters to take a sample for the most recent solution. Keep in
mindthatEnergymeterswillperformintegrationeachtimetheytakeasample.
Save
Syntax:
[class=]{Meters | Circuit | Voltages | (classname)} [file=]filename
[dir=]directory
Defaultclass=Meters,whichsavesthepresentvaluesinbothmonitorsandenergymetersin
theactivecircuit.
"Save Circuit" saves the present enabled circuit elements to the specified subdirectory in
standard DSS form with a Master.txt file and separate files for each class of data. If Dir= not
specifiedauniquenamebasedonthecircuitnameiscreatedautomatically.IfDir=isspecified,
anyexistingfilesareoverwritten.
"SaveVoltages"savesthepresentsolutioninasimpleCSVformatinatextfile.UsedforVDIFF
Page 77 of 180
OpenDSS Manual
June 2013

command.
Anyclasscanbesavedtoafile.Ifnofilenameisspecified,theclassnameisused.
ThefilenameofthefilewrittenappearsintheResultwindowafterexecutionofthiscommand.
Select [elementname] [terminal]

Selects an element and makes it the active element. You can also specify the active terminal
(default=1).Syntax:
Select [element=]elementname
[terminal=]terminalnumber
Examples:
Select Line.Line1
~ R1=.1(continue editing)
Select Line.Line1 2
Voltages (returns voltages at terminal 2 in Result)
SeqCurrents
Returns the sequence currents into all terminals of the active circuit element (see Select
command) in Result string. Returned as commaseparated magnitude only values. Order of
returnedvalues:0,1,2(foreachterminal).
SeqPowers
Returns the sequence powers into all terminals of the active circuit element (see Select
command) in Result string. Returned as commaseparated kw, kvar pairs.Order of returned
values:0,1,2(foreachterminal).
SeqVoltages
Returns the sequence voltages at all terminals of the active circuit element (see Select
command) in Result string. Returned as commaseparated magnitude only values.Order of
returnedvalues:0,1,2(foreachterminal).
Set [option1=value1] [option2=value2] (Options)

TheSetcommandsetsvariousglobalvariablesandoptionshavingtodowithsolutionmodes,
userinterfaceissues,andthelike.WorksliketheEditcommandexceptthatyoudon'tspecify
objecttypeandname.
See the Options Reference for descriptions of the various options you can set with the Set
command.
TherearenewSetcommandvaluesaddedperiodically.ChecktheHelpontheDSSwhileitis
running.
SetkVBase [bus=] [kvll=..]

Commandtoexplicitlysetthebasevoltageforabus.Busmustbepreviouslydefined.Thiswill
override the definitions determined by CalcVoltageBases. When there are only a few voltage
bases in the problem, and they are very distinct, the CalcvoltageBases command will work
nearlyeverytime.Problemsariseiftherearetwovoltagebasesthatareclosetogether,suchas
Page 78 of 180
OpenDSS Manual
June 2013
12.47kVand13.2kV.UseascriptcomposedofSetkVBasecommandstoremoveambiguity.
Parametersinorderare:
Bus={busname}
kVLL=(linetolinebasekV)
kVLN=(linetoneutralbasekV)
kV base is normally given in linetoline kV (phasephase). However, it may also be
specifiedbylinetoneutralkV.Thefollowingexampesareequivalent:
setkvbaseBus=B9654kVLL=13.2
setkvbaseB965413.2
setkvbaseB9654kvln=7.62
Show <Quantity>
SeetheseparatehelpontheShowcommandintheOpenDSSexecutable.Showcommandsare
addedfrequently,oftenmakingthisdocumentoutofdate.
The Show commands generally writes a text file report of the specified quantity for the most
recentsolutionandopensaviewer(thedefaultEditore.g.,Notepadorsomeothereditor)to
display the file. Defaults to Show Voltages so if you mistype the name of the quantity you
want,youwillgetthesequencevoltages.
Quantitycanbeoneof:
CurrentsShowsthecurrentsintoeachdeviceterminal.
Monitor <monitor name> Shows a text (CSV) file with the voltages and currents
presentlystoredinthespecifiedmonitor.
FaultsShowsresultsofFaultstudymodesolution:allphase,onephase,andadjacent
2phasefaultcurrentsateachbus.
ElementsShowsalltheelementsintheactivecircuit.
BusesShowsallbusesintheactivecircuit.
PanelSameasPanelCommand.OpenstheinternalDSScontrolpanel.
Metershowsthepresentvaluesintheenergymeterregistersintheactivecircuit.
Generators Each generator has its own energy meter. Shows the present values in
eachgeneratorenergymeterregisterintheactivecircuit.
LossesLosssummary.
Page 79 of 180
OpenDSS Manual
June 2013
Powers [MVA|kVA*] [Seq* | Elements] Show the power flow in various units. Default
(*)issequencepowerinkVA.
Voltages[LL |LN*][Seq*|Nodes| Elements].Showsthevoltagesindifferentways.
Default(*)issequencequantitieslinetoneutral.
ZoneEnergyMeterName[Treeview]Differentwaystoshowtheselectedenergymeter
zone.
AutoAdded(seeAutoAddsolutionmode)
Tapsshowsthetapsonregulatedtransformers
OverloadsOverloadedPDelementsreport
Unserved[UEonly]Unservedenergyreport.Loadsthatareunserved.
EVentlogShowtheeventlog(capacitorswitching,regulatortapchanges)
VariablesShowstatevariablevaluesinpresentcircuit.
IsolatedShowisolatedbusesandcircuitsections
RatingsDeviceratingreport.
LoopsShowswhereloopsoccurinpresentcircuit
Yprim(showsYprimforactivecktelement)
Y(showsthesystemYmatrix)Maybehuge!!!
BusFlow busname [MVA|kVA*] [Seq* | Elements]. Power flow report centered on
specifiedbus.Canshowvaluesbysequencequantitiesorbyelements(detailedreport).
LineConstants [frequency] [none|mi|km|kft|m|ft|in|cm] Show line constants results,
at the specified frequency and normalized length, for all the presentlydefined
LineGeometryobjects.
Solve [ see set command options ]

Executes the solution mode specified by the Set Mode = command. It may execute a single
solutionorhundredsofsolutions.TheSolutionisaDSSobjectassociatedwiththeactivecircuit.
Ithasseveralpropertiesthatyoumaysettodefinewhichsolutionmodewillbeperformednext.
ThiscommandinvokestheSolvemethodoftheSolutionobject,whichproceedstoexecutethe
designated mode. You may also specify the Mode and Number options directly on the Solve
commandlineifyouwish:
Solve Mode=M1 Number=1000,
forexample.NotethatthereisalsoaSolvemethodintheSolutioninterfaceintheDSSCOM
serverimplementation.ThisisgenerallyfasterwhendrivingtheDSSfromuserwrittencodefor
Page 80 of 180
OpenDSS Manual
June 2013

acustomsolutionalgorithmthatmustexecutemanysolutions.
YoumayusethesameoptionsontheSolvecommandlineasyoucanwiththeSetcommand.In
fact, the Solve command is simply the Set command that performs a solution after it is done
settingtheoptions.Forexample:
Solve mode=daily
stepsize=15m
number=96
Summary
Returnsapowerflowsummaryofthemostrecentsolutionintheglobalresultstring.
Totals
TotalofallEnergyMeterobjectsinthecircuit.Reportsregistertotalsintheresultstring.
UpdateStorage
UpdateStorageelementsbasedonpresentsolutionandtimeinterval.CausesthekWhstored
valuestobeupdated(integrated)basedonthepresentkWchargeordischargevaluesandthe
presenttimeinterval.Thisisdoneautomaticallybymosttimesequentialsolutionmodes.This
commandisprovidedforscriptingsimulations.
Variable
Syntax:
Variable [name=] MyVariableName
[Index=] IndexofMyVariable
Returns the value of the specified state variable of the active circuit element, if a PCelement.
AppliesonlytoPCelements(Load,Generator,etc)thatcontainstatevariables.Returnsthevalue
asastringintheResultwindowortheText.ResultinterfaceifusingtheCOMserver.
You may specify the variable by name or by its index. You can determine the index using the
VarNamescommand.Ifanypartoftherequestisinvalid,theResultisnull.Thesemaychange
fromtimetotime,soitisalwaysgoodtocheck.
Varnames
ReturnsallvariablenamesforactiveelementifPCelement.Otherwise,returnsnull.
VarValues
ReturnsallvariablevaluesforactiveelementifPCelement.Otherwise,returnsnull.
Vdiff
Displays the difference between the present solution and the last one saved using the SAVE
VOLTAGEScommand.
Visualize
[What=]{Currents*|Voltages|Powers}[element=]full_element_name(class.name).
Showsthecurrents,voltages,orpowersforselectedelementonadrawinginphasorquantities.
Forexample:
Page 81 of 180
OpenDSS Manual
June 2013
Visualize what=currents element= Line.Line1

Visualize powers Line.Line1
Voltages
ReturnsthevoltagesfortheACTIVETERMINALONLYoftheactivecircuitelementintheResult
string. For setting the active circuit element, see the Select command or the Set Terminal=
property. Returned as magnitude and angle quantities, comma separated, one set per
conductoroftheterminal.
YearlyCurves
[cases=](case1,case2,...)[registers=](reg1,reg2,...)[meter=]{Totals*|SystemMeter|
metername}
Plotsyearlycurvesforspecifiedcasesandregisters.
Default:meter=Totals.Example:
yearlycurves cases=(basecase, pvgens) registers=9
Ysc
Returns full short circuit admittance, Ysc, matrix for the ACTIVE BUS in commaseparated
complexnumberformG+jB.
Zsc
Returns full Short circuit impedance, Zsc, matrix for the ACTIVE BUS in commaseparated
complexnumberform.
Page 82 of 180
OpenDSS Manual
June 2013
Zsc10
Returnssymmetricalcomponentshortcircuitimpedances,Z1,Z0fortheACTIVEBUSincomma
separatedR+jXform.
ZscRefresh
RefreshesZscmatrixfortheACTIVEBUS.
Check the online Help while the DSS is running for information on additional commands that
mighthavebeenaddedsincetheprintingofthismanual.
Page 83 of 180
OpenDSS Manual
June 2013
O PTIONS R EFERENCE
DSSoptionsaresetusingeithertheSetcommandortheSolvecommand.TheSolvecommand
firstexecutestheSetandthenexecutesasolution.Thisallowsformoreconcisesyntaxforsome
cases.Forexample,thesequence
Set mode=snapshot
Solve
Set mode=harmonics
Solve
Maybeaccomplishedwithjust2lines:
Solve mode=snapshot
Solve mode=harmonics
Selected Options currently implemented are described below. Options are added frequently.
ChecktheonlineHelp.
%growth =
Set default annual growth rate, percent, for loads with no growth curve specified.
Defaultis2.5.
%mean =
Percentmeantouseforgloballoadmultiplier.Defaultis65%.
%Normal =
SetstheNormalratingofalllinestoaspecifiedpercentoftheemergencyrating.Note:
This action takes place immediately. Only the inmemory value is changed for the
durationoftherun.
%stddev =
PercentStandarddeviationtouseforgloballoadmultiplier.Defaultis9%.
Addtype =
{Generator|Capacitor}DefaultisGenerator.TypeofdeviceforAutoAddMode.
Algorithm =
{Normal | Newton} Solution algorithm type. Normal is a fixed point currentinjection
iterationthatisalittlequicker(abouttwiceasfast)thantheNewtoniteration.Normal
isadequateformostdistributionsystems.Newtonismorerobustforcircuitsthatare
difficulttosolve.
AllocationFactors =
Setsallallocationfactorsforallloadsintheactivecircuittothevaluegiven.Usefulfor
makinganinitialguessorforcingaparticularallocationofload.Theallocationfactors
maybesetautomaticallybytheenergymeterelementsbyplacingenergymetersonthe
circuit, defining the PEAKCURRENT property, and issuing the ALLOCATELOADS
command.ThefactorsareappliedtotheXFkVApropertyofLoadobjects.
Page 84 of 180
OpenDSS Manual
June 2013
AllowDuplicates =
{YES/TRUE|NO/FALSE}DefaultisNo.FlagtoindicateifitisOKtohavedevicesofsame
nameinthesameclass.IfNo,thenaNewcommandistreatedasanEditcommandbut
adds an element if it doesn't exist already. If Yes, then a New command will always
resultinadevicebeingadded.
AutoBusList =
Array of bus names to include in AutoAdd searches. Or, you can specify a text file
holding the names, one to a line, by using the syntax (file=filename) instead of the
actual array elements. Default is null, which results in the program using either the
busesintheEnergyMeterobjectzonesor,ifnoEnergyMeters,allthebuses,whichcan
makeforlengthysolutiontimes.
Examples:
Setautobuslist=(bus1,bus2,bus3,...)
Setautobuslist=(file=buslist.txt)
Basefrequency =
Default=60.Setthefundamentalfrequencyforharmonicsolutionandthedefaultbase
frequency for all impedance quantities. Side effect: also changes the value of the
solutionfrequency.SeealsoDefaultBaseFrequency.
Bus =
Set Active Bus by name. Can also be done with Select and SetkVBase commands and
the "Set Terminal=" option. The bus connected to the active terminal becomes the
activebus.SeeZscandZsc012commands.
capkVAR =
Sizeofcapacitor,kVAR,toautomaticallyaddtosystem.Defaultis600.0.
casename =
Nameofcaseforyearlysimulationswithdemandintervaldata.Becomesthenameof
thesubdirectoryunderwhichalltheyeardataarestored.Default=circuitname
SideEffect:Setstheprefixforoutputfiles
CapMarkerCode =
Numericmarkercodeforcapacitors.Defaultis37.SeeMarkerCodeoption.
CapMarkerSize =
SizeofCapacitordevicemarker.Defaultis3.
Cfactors=
SimilartoSetAllocationfactors=exceptthisappliestothekWhbillingpropertyofLoad
objects. Sets all Load Cfactor properties to the same value. A typical value is 4. See
onlinehelpontheLoadobject.
Page 85 of 180
OpenDSS Manual
June 2013
circuit =
Settheactivecircuitbyname.(Currentversionallowsonlyonecircuitatatime,sothis
optionisbasicallyignoredatpresent.)
CktModel =
{Multiphase | Positive} Default = Multiphase. Designates whether circuit model is to
interpreted as a normal multiphase model or a positivesequence only model. If
Positivesequence,allpowerquantitiesaremulitipliedby3inreportsandthroughany
interface that reports a power quantity. Any line with sequence parameter inputs will
usethelonglineequivalentpisection.
Class =
SynonymforType=.setsclass(type)fortheActiveDSSObject.ThisbecomestheActive
DSSClass.
ControlMode =
{OFF|STATIC|EVENT|TIME}Defaultis"STATIC".Controlmodeforthesolution.Set
toOFFtopreventcontrolsfromchanging.
STATIC=Timedoesnotadvance.Controlactionsareexecutedinorderofshortesttime
toactuntilallactionsareclearedfromthecontrolqueue.Usethismodeforpowerflow
solutions which may require several regulator tap changes per solution. This is the
defaultforthestandardSnapshotmodeaswellasDailyandYearlysimulationswhere
thestepsizeistypicallygreaterthan15min.
EVENT=solutioniseventdriven.Onlythecontrolactionsnearestintimeareexecuted
andthetimeisadvancedautomaticallytothetimeoftheevent.
TIME = solution is time driven. Control actions are executed when the time for the
pendingactionisreachedorsurpassed.Usethisfordutycyclemodeanddynamicmode.
Controlsmayresetandmaychoosenottoactwhenitcomestheirtimetorespond.
Use TIME mode when modeling a control externally to the DSS and a solution mode
suchasDAILYorDUTYCYCLEthatadvancestime,orsetthetime(hourandsec)explicitly
fromtheexternalprogram.
Datapath =
SetthedatapathforfileswrittenorreadbytheDSS.Defaultstothestartuppath.May
be Null. Executes a CHDIR to this path if nonnull. Does not require a circuit defined.
Youcanalsousethecdcommandfromascript.
DefaultBaseFrequency=
Set Default Base Frequency, Hz. The default value when first installed is 60 Hz. Side
effect: Sets the solution Frequency and default Circuit Base Frequency. This value is
savedintheWindowsRegistrywhentheDSSclosesdown.Therefore,itneedonlybeset
onetime.Thisisusefulforusersstudying50Hzsystems.
Page 86 of 180
OpenDSS Manual
June 2013
DefaultDaily =
Default daily load shape name. Default value is "default", which is a 24hour curve
definedwhentheDSSisstarted.
DefaultYearly =
Default yearly load shape name. Default value is "default", which is a 24hour curve
defined when the DSS is started. If no other curve is defined, this curve is simply
repeatedwheninYearlysimulationmode.
DemandInterval =
{YES/TRUE | NO/FALSE} Default = no. Set for keeping demand interval data for daily,
yearly,etc,simulations.SideEffect:Resetsallmeters!!!
DIVerbose =
{YES/TRUE|NO/FALSE}Default=FALSE.SettoYes/Trueifyouwishaseparatedemand
interval (DI) file written for each meter. Otherwise, only the totalizing meters are
written.
EarthModel =
Oneof{Carson|FullCarson|Deri*}.DefaultisDeri,whichisafittotheFullCarson
thatworkswellintohighfrequencies."Carson"isthesimplifiedCarsonmethodthatis
typicallyusedfor50/60Hzpowerflowprograms.AppliesonlytoLineobjectsthatuse
LineGeometryobjectstocomputeimpedances.
Editor=
Setthecommandstringrequiredtostartuptheeditorpreferredbytheuser.Defaults
toNotepad.ThisisusedtodisplaycertainreportsfromtheDSS.Usethecompletepath
nameforanyotherEditor.Doesnotrequireacircuitdefined.Thisvalueissavedinthe
WindowsRegistryandneedonlybespecifiedonetime.EPRIusestheEditPluseditor.
Element =
Sets the active DSS element by name. You can use the complete object spec
(class.name)orjustthename.iffullnameisspecifed,classbecomestheactiveclass,
also.SeealsotheSelectcommand.
Emergvmaxpu =
Maximumpermissibleperunitvoltageforemergency(contingency)conditions.Default
is1.08.
Emergvminpu =
Minimumpermissibleperunitvoltageforemergency(contingency)conditions.Default
is0.90.
Frequency =
setsthefrequencyforthenextsolutionoftheactivecircuit.
Genkw =
Sizeofgenerator,kW,toautomaticallyaddtosystem.Defaultis1000.0
Page 87 of 180
OpenDSS Manual
June 2013
GenMult =
Global multiplier for the kW output of every generator in the circuit. Default is 1.0.
Applies to Snapshot, Daily, and DutyCycle solution modes. Ignored if generator is
designatedasStatus=Fixed.
Genpf =
Powerfactorofgeneratortoassumeforautomaticaddition.Defaultis1.0.
h =
Alternatenamefortimestepsize(seeStepsize).
Harmonics =
{ALL | (list of harmonics) } Default = ALL. Array of harmonics for which to perform a
solutioninHarmonicsmode.IfALL,thensolutionisperformedforallharmonicsdefined
inspectracurrentlybeingused.Otherwise,specifyamorelimitedlistsuchas:
SetHarmonics=(1571113)
Hour=
setsthehourtobeusedforthestarttimeofthesolutionoftheactivecircuit.(Seealso
Time)
KeepList =
Arrayofbusnamestokeepwhenperformingcircuitreductions.Youcanspecifyatext
fileholdingthenames,onetoaline,byusingthesyntax(file=filename)insteadofthe
actualarrayelements.Commandiscumulative(resetkeeplistfirst).Reductionalgorithm
may
keep
other
buses
automatically.
Examples:
Reset Keeplist
(sets all buses to FALSE (no keep))
Set KeepList=(bus1, bus2, bus3, ... )
Set KeepList=(file=buslist.txt)
LDcurve =
nameoftheLoadshapeobjecttousefortheglobalcircuitLoadDurationcurve.Usedin
solutionmodesLD1andLD2(seebelow).Mustbesetbeforeexecutingthosemodes.
Simplydefinetheloaddurationcurveasaloadshapeobject.Default=nil.
LoadModel=
{"POWERFLOW"|"ADMITTANCE"}Setstheloadmodel.IfPOWERFLOW(abbreviated
P), loads do not appear in the System Y matrix. For iterative solution types (Mode
Direct)loads(actuallyallPCElements)arecurrentinjectionsources.IfADMITTANCE,all
PCelementsappearintheSystemYmatrixandsolutionmodeshouldbesettoDirect
(below)becausetherewillbenoinjectioncurrents.
LoadMult =
global load multiplier to be applied to all "variable" loads in the circuit for the next
solution.Loadsdesignatedas"fixed"arenotaffected.Notethatnotallsolutionmodes
Page 88 of 180
OpenDSS Manual
June 2013
usethismultiplier,butmanydo,includingallsnapshotmodes.SeeModebelow.The
default LoadMult value is 1.0. Remember that it remains at the last value to which it
wasset.SolutionmodessuchasMonteCarloandLoadDurationmodeswillalterthis
multiplier. Its value is usually posted on DSS control panels. Loads defined with
"status=fixed" are not affected by load multipliers. (The default for loads is
"status=variable".)
Log =
{YES/TRUE | NO/FALSE} Default = FALSE. Significant solution events are added to the
EventLog,primarilyfordebugging.
LossRegs =
WhichEnergyMeterregister(s)touseforLossesinAutoAddMode.Maybeoneormore
registers. if more than one, register values are summed together. Array of integer
values>0.Defaultsto13(forZonekWhLosses).
For a list of EnergyMeter register numbers, do the "Show Meters" command after
definingacircuit.
LossWeight =
Weighting factor for Losses in AutoAdd functions. Defaults to 1.0. Autoadd mode
minimizes
(Lossweight * Losses + UEweight * UE).
If you wish to ignore Losses, set to 0. This applies only when there are EnergyMeter
objects.Otherwise,AutoAddmodeminimizestotalsystemlosses.
Markercode =
Numbercodefornodemarkeroncircuitplots(thesearecurrentlytheSDLComponents
MarkAtoptionswiththisversion).Markercodesare:
Markswitches =
{YES/TRUE|NO/FALSE}DefaultisNO.Marklinesthatareswitchesorareisolatedwith
asymbol.SeeSwitchMarkerCode.
Page 89 of 180
OpenDSS Manual
June 2013
MarkCapacitors =
{YES/TRUE|NO/FALSE}DefaultisNO.MarkCapacitorobjectlocationswithasymbol.
SeeCapMarkerCode.Thefirstbuscoordinatemustexist.
MarkPVSystems =
{YES/TRUE | NO/FALSE} Default is NO. Mark PVSystem locations with a symbol. See
PVMarkerCode.Thebuscoordinatemustexist.
MarkRegulators =
{YES/TRUE|NO/FALSE}DefaultisNO.MarkRegControlobjectlocationswithasymbol.
See RegMarkerCode. The bus coordinate for the controlled transformer winding must
exist.
MarkStorage =
{YES/TRUE|NO/FALSE}DefaultisNO.MarkStoragedevicelocationswithasymbol.See
StoreMarkerCode.Thebuscoordinatemustexist.
Marktransformers =
{YES/TRUE|NO/FALSE}DefaultisNO.Marktransformerlocationswithasymbol.See
TransMarkerCode. The coordinate of one of the buses for winding 1 or 2 must be
definedforthesymboltoshow
Maxcontroliter =
Maxcontroliterationspersolution.Defaultis10.
Maxiter =
Setsthemaximumallowableiterationsforpowerflowsolutions.Defaultis15.
Mode=
Specify the solution mode for the active circuit. Mode can be one of (unique
abbreviationwillsuffice,aswithnearlyallDSScommands):
Mode=Snap:
Solveasinglesnapshotpowerflowforthepresentconditions.Loadsaremodifiedonly
by the global load multiplier (LoadMult) and the growth factor for the present year
(Year).
Mode=Daily:
Doaseriesofsolutionsfollowingthedailyloadcurves.TheStepsizedefaults to3600
sec (1 hr). Set the starting hour and the number of solutions (e.g., 24) you wish to
execute.Monitorsareresetatthebeginningofthesolution.Thepeakofthedailyload
curveisdeterminedbythegloballoadmultiplier(LoadMult)andthegrowthfactorfor
thepresentyear(Year).
Mode=Direct:
Solve a single snapshot solution using an admittance model of all loads. This is non
iterative;justadirectsolutionusingthecurrentlyspecifiedvoltageandcurrentsources.
Page 90 of 180
OpenDSS Manual
June 2013
Mode=Dutycycle:
Followthedutycyclecurveswiththetimeincrementspecified.Performthesolutionfor
thenumberoftimesspecifiedbytheNumberparameter(seebelow).
Mode=Dynamics:
Sets the solution mode for a dynamics solution. Must be preceded by a successful
powerflowsolutionsothatthemachinescanbeinitialized.Changestoadefaulttime
step of 0.001s and ControlMode = TIME. Generator models are changed to a voltage
source behind the value specified for transient reactance for each generator and
initializedtogiveapproximatelythesamepowerflowastheexistingsolution.Besureto
setthenumberoftimestepstosolveeachtimetheSolvecommandisgiven.
Mode=FaultStudy:
Doafullfaultstudysolution,determiningtheTheveninequivalentsforeachbusinthe
active circuit. Prepares all the data required to produce fault study report under the
ShowFaultcommand.
Mode=Harmonics:
Sets the solution mode for a Harmonics solution. Must be preceded by a successful
power flow solution so that the machines and harmonics sources can be initialized.
Loads are converted to harmonic current sources and initialized based on the power
flowsolutionaccordingtotheSpectrumobjectassociatedwitheachLoad.Generators
are converted to a voltage source behind subtransient reactance with the voltage
spectrumspecifiedforeachgenerator.ADirectsolutionisperformedforeachharmonic
frequency(moreprecisely,nonpowerfrequency).ThesystemYmatrixisbuiltforeach
frequencyandsolvedwiththedefinedinjectionsfromallharmonicsources.Asolution
isperformedforeachfrequencyfoundtobedefinedinallthespectrabeingusedinthe
circuit. Note that to perform a frequency scan of a network, you would define a
SpectrumobjectwithasmallfrequencyincrementandassignittoeitheranIsourceor
Vsourceobject,asappropriate.
Mode=Yearly:
Doasolutionfollowingtheyearlyloadcurves.Thesolutionisrepeatedasmanytimes
as the specified by the Number= option. Each load then follows its yearly load curve.
Loadisdeterminedsolelybytheyearlyloadcurveandthegrowthmultiplier.Thetime
stepinpastrevisionswasalways1hour.However,itmaynowbeanyvalue..Meters
andMonitorsareresetatthebeginningofsolutionandsampledaftereachsolution.If
theyearlyloadcurveisnotspecified,thedailycurveisusedandsimplyrepeatedifthe
numberofsolutionsexceeds24hrs.Thismodeisnominallydesignedtosupport8760
hrsimulationsofload,butcanbeusedforanysimulationthatusesanhourlytimestep
andneedsmonitorsormeters.
Mode=LD1
(LoadDurationMode1):Solvesforthejointunionofaloaddurationcurve(definedas
aLoadshapeobject)andtheDailyloadshape.NominallyperformsaDailysolution(24
hr)foreachpointontheLoadduration(LD)curve.Thus,thetimeaxisoftheLDcurve
represents days at that peak load value. LD curves begin at zero (0) time. Thus, a
yearly LD curve would be defined for 0..365 days. A monthly LD curve should be
Page 91 of 180
OpenDSS Manual
June 2013
defined for 0..31 days. Energy meters and monitors are reset at the beginning of the
solution.Attheconclusion,theenergymetervaluesrepresentthetotalofallsolutions.
If the LD curve represent one year, then the energy will be for the entire year. This
modeisintendedforthoseapplicationsrequiringasingleenergynumberforanentire
year,month,orothertimeperiod.Loadsaremodifiedbygrowthcurvesaswell,soset
theyearbeforeproceeding.Also,settheLDcurve(seeLdcurveoption).
Mode=LD2
(LoadDurationMode2):SimilartoLD1modeexceptthatitperformstheLoadduration
solutionforonlyaselectedhouronthedailyloadshape.Setthedesiredhourbefore
executingtheSolvecommand.Themetersandmonitorsareresetatthebeginningof
thesolution.Attheconclusion,theenergymetershaveonlythevaluesforthathourfor
theyear,ormonth,orwhatevertimeperiodtheLDcurverepresents.Thesolversimply
solvesforeachpointontheLDcurve,multiplyingtheloadattheselectedhourbythe
LDcurvevalue.Thismodehasbeenusedtogeneratea3Dplotofenergyvs.month
andhouroftheday.
Mode=M1
(Monte Carlo Mode 1): Perform a number of solutions allowing the loads to vary
randomly.ExecutesnumberofcasesspecifiedbytheNumberoption(seebelow).At
eachsolution,eachloadismodifiedbyarandommultiplieradifferentoneforeach
load. In multiphase loads, all phases are modified simultaneously so that the load
remainsbalanced.Therandomvariationmaybeuniformorgaussianasspecifiedbythe
globalRandomoption(seebelow).Ifuniform,theloadmultipliersarebetween0and1.
Ifgaussian,themultipliersarebasedonthemeanandstandarddeviationoftheYearly
loadshapespecifiedfortheload.Besureoneisspecifiedforeachload.
Mode=M2
(MonteCarloMode2):ThismodeisdesignedtoexecuteanumberofDailysimulations
withtheglobalpeakloadmultiplier(LoadMult)varyingrandomly.Settimestepsize(h)
andNumberofsolutionstorun."h"defaultsto3600sec(1Hr).Numberofsolutions
refers to the number of DAYS. For Random = Gaussian, set the global %Mean and
%Stddev variables, e.g. "Set %Mean=65 %Stddev=9". For Random=Uniform, it is not
necessarytospecify%Mean,sincethegloballoadmultiplierisvariedfrom0to1.For
eachday,theglobalpeakloadmultiplierisgeneratedandthena24hourDailysolution
isperformedatthespecifiedtimestepsize.
Mode=M3
(MonteCarloMode3):ThismodeissimilartotheLD2modeexceptthattheglobalload
multiplierisvariedrandomlyratherthanfollowingaloaddurationcurve.SettheHour
ofthedayfirst(eitherSetTime=orSetHour=).Metersandmonitorsareresetatthe
beginningofthesolution.Energyattheconclusionofthesolutionrepresentsthetotal
of all random solutions. For example, one might use this mode to estimate the total
annualenergyatagivenhourbyrunningonly50or100solutionsateachhour(rather
than365)andratioingupforthefullyear.
Mode=MF
(MonteCarloFaultmode).Oneofthefaultsdefinedintheactivecircuitisselectedand
Page 92 of 180
OpenDSS Manual
June 2013
its resistance value randomized. All other Faults are disabled. Executes number of
casesspecifiedbytheNumberparameter.
Mode=Peakdays:
Do daily solutions (24hr) only for those days in which the peak exceeds a specified
value.
Nodewidth =
Widthofnodemarkerincircuitplots.Default=1.
Normvmaxpu =
Maximumpermissibleperunitvoltagefornormalconditions.Defaultis1.05.
Normvminpu =
Minimumpermissibleperunitvoltagefornormalconditions.Defaultis0.95.
NumAllocIterations =
Default is 2. Maximum number of iterations for load allocations for each time the
AllocateLoads or Estimate command is given. Usually, 2 are sufficient, but some cases
are more difficult. Execute an Export Estimation report to evaluate how well the load
allocationhasworked.
Number=
specify the number of time steps or solutions to run or the number of Monte Carlo
casestorun.
Object (or Name)=

sets the name of the Active DSS Object. Use the complete object specification
(classname.objname),orsimplytheobjname,todesignatetheactiveobjectwhichwill
be the target of the next command (such as the More command). If 'classname' is
omitted,youcansettheclassbyusingtheClass=field.
Overloadreport =
{YES/TRUE | NO/FALSE} Default = FALSE. For yearly solution mode, sets overload
reportingon/off.DemandIntervalmustbesettotrueforthistohaveeffect.
NeglectLoadY=
{YES/TRUE | NO/FALSE} Default is NO. For Harmonic solution, neglect the Load shunt
admittancebranchthatcansiphonoffsomeoftheLoadinjectioncurrent.
IfYES,thecurrentinjectedfromtheLOADatharmonicfrequencieswillbenearlyideal.
PriceCurve =
Setsthecurvetousetoobtainforpricesignal.Defaultisnone(nullstring).Ifnone,price
signal either remains constant or is set by an external process. Curve is defined as a
loadshape (not normalized) and should correspond to the type of analysis being
performed(daily,yearly,loadduration,etc.).
Page 93 of 180
OpenDSS Manual
June 2013
PriceSignal =
Setsthepricesignal($/MWh)forthecircuit.Initialvalueis25.
PVMarkerCode =
NumericmarkercodeforPVSystemdevices.Defaultis15.SeeMarkerCodeoption.
PVMarkerSize =
SizeofPVSystemdevicemarker.Defaultis1.
Random=
specify the mode of random variation for Monte Carlo studies: One of [Uniform |
Gaussian|Lognormal|None]forMonteCarloVariablesMayabbreviatevalueto"G",
L, or "U" where G = gaussian (using mean and std deviation for load shape); L =
lognormal (also using mean and std dev); U = uniform (varies between 0 and 1
randomly).Anythingelse:randomizationdisabled.
Recorder =
{YES/TRUE | NO/FALSE} Default = FALSE. Opens DSSRecorder.DSS in DSS install folder
andenablesrecordingofallcommandsthatcomethroughthetextcommandinterface.
Closed by either setting to NO/FALSE or exiting the program. When closed by this
command,thefilenamecanbefoundintheResult.Doesnotrequireacircuitdefined.
ReduceOption =
{ Default or [null] | Stubs [Zmag=nnn] | MergeParallel | BreakLoops | Switches |
TapEnds[maxangle=nnn]|Ends}Strategyforreducingfeeders.Defaultistoeliminate
alldanglingendbusesandbuseswithoutload,caps,ortaps.
"Stubs[Zmag=0.02]"mergesshortbrancheswithimpedancelessthanZmag(default=
0.02ohms
"MergeParallel"mergeslinesthathavebeenfoundtobeinparallel
"Breakloops"disablesoneofthelinesattheheadofaloop.
"Tapends [maxangle=15]" eliminates all buses except those at the feeder ends, at tap
pointsandwherethefeederturnsbygreaterthanmaxangledegrees.
"Ends"eliminatesdanglingendsonly.
"Switches"mergesswitcheswithdownlinelinesandeliminatesdanglingswitches.
Markingbuseswith"Keeplist"willpreventtheirelimination.
RegMarkerCode =
NumericmarkercodeforRegulators.Defaultis47.SeeMarkerCodeoption.
RegMarkerSize =
SizeofRegControldevicemarker.Defaultis1.
Page 94 of 180
OpenDSS Manual
June 2013
Sec =
setsthesecondsfromthehourforthestarttimeforthesolutionoftheactivecircuit.
(SeealsoTime)
ShowExport=
{YES/TRUE|NO/FALSE}Default=FALSE.IfYES/TRUEwillautomaticallyshowtheresults
ofanExportcommandafteritiswritten.Normally,theresultofanExportcommand(a
CSVfile)isnotautomaticallydisplayed.
Stepsize (or h)=

sets the time step size (default unit is sec) for the solution of the active circuit.
Normally,specifiedfordynamicsolutionbutisalso,usedfordutycycleloadfollowing
solutions.Yearlysimulationstypicallygohourbyhouranddailysimulationsfollowthe
smallestincrementofthedailyloadcurves.Yearlysimulationscanalsogoinanytime
increment. Reasonable default values are set when you change solution modes. You
mayspecifythestepsizeinseconds,minutes,orhoursbyappendings,m,orhtothe
size value. If omitted, s is assumed. Example: set stepsize=15m is the same as set
stepsize=900.Donotleaveaspacebetweenthevalueandthecharacter.
Switchmarkercode =
Numericmarkercodeforlineswithswitchesorareisolatedfromthecircuit.Defaultis
4.Seemarkswitchesoptionandmarkercodeoption.
Terminal =
Set the active terminal of the active circuit element. May also be done with Select
command.
Time=
Specifythesolutionstarttimeasanarray:time="hour,sec"ortime=(hour,sec):e.g.,
time=(23,370)designate6minutes,10secpastthe23rdhour.
tolerance=
Setsthesolutiontolerance.Defaultis0.0001.
TraceControl =
{YES/TRUE | NO/FALSE} Set to YES to trace the actions taken in the control queue.
CreatesafilenamedTRACE_CONTROLQUEUE.CSVinthedefaultdirectory.Thenamesof
allcircuitelementstakinganactionarelogged.
TransMarkerCode =
Numericmarkercodefortransformers.Defaultis35.SeeMarkTransformersoptionand
MarkerCodeoption.
TransMarkerSize =
Sizeoftransformermarker.Defaultis1.
StoreMarkerCode =
NumericmarkercodeforStoragedevices.Defaultis9.SeeMarkerCodeoption.
Page 95 of 180
OpenDSS Manual
June 2013
StoreMarkerSize =
SizeofStoragedevicemarker.Defaultis1.
Trapezoidal =
{YES/TRUE | NO/FALSE} Default is "No". Specifies whether to use trapezoidal
integration for accumulating energy meter registers. Applies to EnergyMeter and
Generatorobjects.Defaultmethodsimplymultipliesthepresentvalueoftheregisters
times the width of the interval. Trapezoidal is more accurate when there are sharp
changesinaloadshapeorunequalintervals.Trapezoidalisautomaticallyusedforsome
loadduration curve simulations where the interval size varies considerably. Keep in
mind that for Trapezoidal, you have to solve one more point than the number of
intervals. That is, to do a Daily simulation on a 24hr load shape, you would set
Number=25 to force a solution at the first point again to establish the last (24th)
interval.
Type=
SetstheactiveDSSclasstype.SameasClass=...
Ueregs =
Which EnergyMeter register(s) to use for UE in AutoAdd Mode. May be one or more
registers. if more than one, register values are summed together. Array of integer
values>0.Defaultsto11(forLoadEEN).
For a list of EnergyMeter register numbers, do the "Show Meters" command after
definingacircuit.
Ueweight=
Weighting factor for UE/EEN in AutoAdd functions. Defaults to 1.0.
Autoaddmodeminimizes
(Lossweight*Losses+UEweight*UE).
IfyouwishtoignoreUE,setto0.ThisappliesonlywhenthereareEnergyMeterobjects.
Otherwise,AutoAddmodeminimizestotalsystemlosses.
Voltagebases=
Definelegalbusvoltagebasesforthiscircuit.Enteranarrayofthelegalvoltagebases,
inphasetophasevoltages,forexample:
setvoltagebases=[.208,.480,12.47,24.9,34.5,115.0,230.0]
WhentheCalcVoltageBasescommandisissued,asnapshotsolutionisperformedwith
noloadinjectionsandthebusbasevoltageissettothenearestlegalvoltagebase.The
defaultsareasshownintheexampleabove.
TheDSSdoesnotuseperunitvaluesinitssolution.Youonlyneedtosetthevoltage
bases if you wish to see per unit values on the reports or if you intend to use the
AutoAddfeature.
Page 96 of 180
OpenDSS Manual
June 2013
Voltexceptionreport=
{YES/TRUE | NO/FALSE} Default = FALSE. For yearly solution mode, sets voltage
exceptionreportingon/off.DemandIntervalmustbesettotrueforthistohaveeffect.
Year=
setstheYeartobeusedforthenextsolutionoftheactivecircuit;thebasecaseisyear
0.Usedtodeterminethegrowthmultiplierforeachload.Eachloadmayhaveaunique
growthcurve(definedasaGrowthshapeobject).
ZoneLock =
{YES/TRUE | NO/FALSE} Default is No. if No, then meter zones are recomputed each
timethereisachangeinthecircuit.IfYes,thenmeterzonesarenotrecomputedunless
they have not yet been computed. Meter zones are normally recomputed on Solve
commandfollowingacircuitchange.
Page 97 of 180
OpenDSS Manual
June 2013
General OpenDSS Object Property Descriptions

TheseareobjectscommontoallcircuitsintheOpenDSS(theremaybeseveralcircuitsloaded
intomemoryatanyonetime).AnycircuitcanreferencethedatacontainedintheGeneralDSS
Objects
Thefollowingdescribeseachobjectclassandtheparametersthatmaybedefinedthroughthe
commandinterface.
Note that all DSS objects have a Like parameter. When another element of the same class is
very similar to a new one being created, use the Like parameter to start the definition then
change the parameters that differ. Issue the Like=nnnn parameter first. Command lines are
parsedandexecutedfromlefttoright.
L INE C ODE
LineCodeobjectsaregenerallibraryobjectsthatcontainimpedancecharacteristicsforlinesand
cables.Theterm"linecode"isanoldtermthatsimplyreferstoacodethatwasmadeupby
programmers to describe a line construction. In most distribution analysis programs, one can
describealinebyitsLineCodeanditslength.LineCodeobjectsweredefinedinaseparatefile.
Thiscollectionofobjectsemulatestheoldlinecodefiles,exceptthattheconceptisalittlemore
powerful.
Ultimately, the impedance of a line is described by its series impedance matrix and nodal
capacitiveadmittancematrix.Thesematricesmaybespecifieddirectlyortheycanbegenerated
by specifying the symmetrical component data. Note that the impedances of lines may be
specifieddirectlyandonedoesnotneedtousealinecode,althoughthelinecodewillbemore
convenientmostofthetime.Theremaybehundredsoflines,butonlyafewdifferentkindsof
lineconstructions.
LineCodecanalsoperformaKronreduction,reducingoutthelastconductorintheimpedance
matrices, which is assumed to be a neutral conductor. This applies only if the impedance is
specifiedasamatrix.Iftheimpedanceisdefinedassymmetricalcomponents,thisfunctiondoes
notapplybecausesymmetricalcomponentvaluesalreadyassumethereduction.
By specifying the values of Rg, Xg, and rho, the DSS will take the base frequency impedance
matrix values and adjust the earth return component for frequency. Skin effect in the
conductorsisnotmodified.Torepresentskineffect,youhavetodefinethegeometry.
Thisassumestheimpedancematrixisconstructedasfollows:
Z 11 Zg
Z R jX Z 21 Zg
Z 31 Zg
Z 12 Zg
Z 22 Zg
Z 32 Zg
Z 13 Zg
Z 23 Zg
Z 33 Zg
Where,usingthe1sttermofCarsonsformulation,
Page 98 of 180
Rg 0
OpenDSS Manual
June 2013
/m
Xg 0

ln 658.5
/m
2
f
Xii 0
1
ln
/m
2 GMRi
Xij 0
1
ln / m
2 dij
0 4 10 7
(Alldimensionalvaluesinmeters.)
TheLineCodeproperties,inorder,are:(notcasesensitive)
Nphases= Numberofphases.Default=3.
R1=
PositiveSequenceresistance,ohmsperunitlength.
X1=
PositiveSequencereactance,ohmsperunitlength.
R0=
ZeroSequenceresistance,ohmsperunitlength.
X0=
ZeroSequencereactance,ohmsperunitlength.
C1=
PositiveSequencecapacitance,nanofaradsperunitlength
C0=
ZeroSequencecapacitance,nanofaradsperunitlength
Units=
{mi|km|kft|m|ft|in|cm}Lengthunits.Ifnotspecified,itisassumedthatthe
unitscorrespondtothelengthbeingusedintheLinemodels.
IfanyoftheSymmetricalComponentdataisspecified,theimpedancematricesaredetermined
fromthatdata.Youmayalsoenterthematricesdirectlyusingthefollowingthree
parameters.Theorderofmatricesexpectedisthenumberofphases.Thematrices
maybeenteredinlowertriangleformorfullmatrix.Theresultisalways
symmetrical.Matricesarespecifiedbythesyntaxshownbelow.The"|"separates
rows.Extraneousnumbersoneachrowareignored.
Rmatrix="11|2122|313233"
Rmatrix=
Seriesresistancematrix,ohmsperunitlength..
Xmatrix=
Seriesreactancematrix,ohmsperunitlength.
Cmatrix=
Shuntnodalcapacitancematrix,nanofaradsperunitlength.
BaseFreq=BaseFrequencyatwhichtheimpedancevaluesarespecified.Default=60.0Hz.
Normamps=Normalampacity,amps.
Emergamps=Emergencyampacity,amps.
Page 99 of 180
OpenDSS Manual
June 2013
Faultrate=Numberoffaultsperyearperunitlength.Thisisthedefaultforthisgeneralline
construction.
Pctperm= Percentofthefaultthatbecomepermanent(requiringalinecrewtorepairanda
sustainedinterruption).
Kron=
Y/N.Default=N.PerformKronreductionontheimpedancematrixafteritis
formed,reducingorderby1.Dothisonlyoninitialdefinitionaftermatricesare
defined.Ignoredforsymmetricalcomponents.
Rg=
Carsonearthreturnresistanceperunitlengthusedtocomputeimpedancevalues
atbasefrequency.Seedescriptionabove.Formakingbetteradjustmentsofline
impedancevaluesforfrequencyforharmonicsstudies.Default=0.01805ohmsper
1000ftat60Hz.Ifyoudonotwishtoadjusttheearthreturnimpedancefor
frequency,setbothRgandXgtozero.GenerallyavoidKronreductionifyouwillbe
solvingatfrequenciesotherthanthebasefrequencyandwishtoadjusttheearth
returnimpedance.
Xg=
Carsonearthreturnreactanceperunitlengthusedtocomputeimpedancevaluesat
basefrequency.Seedescriptionabove.Formakingbetteradjustmentsofline
impedancevaluesforfrequencyforharmonicsstudies.Default=0.155081ohmsper
1000ftat60Hz.Ifyoudonotwishtoadjusttheearthreturnimpedancefor
frequency,setbothRgandXgtozero.GenerallyavoidKronreductionifyouwillbe
solvingatfrequenciesotherthanthebasefrequencyandwishtoadjusttheearth
returnimpedance.
Rho=
Earthresistivityusedtocomputeearthcorrectionfactor.Default=100meterohms.
Like=
NameofanexistingLineCodeobjecttobuildthislike.
L INE G EOMETRY
Thisclassofdataisusedtodefinethepositionsoftheconductors.
Nconds=
Numberofconductorsinthisgeometry.Defaultis3.Triggersmemoryallocations.
Definefirst!
Nphases= Numberofphases.Default=3;Allotherconductorsareconsideredneutralsand
mightbereducedout.
Cond=
Setthistonumberoftheconductoryouwishtodefine.Defaultis1.
Wire=
CodefromWireData.MUSTBEPREVIOUSLYDEFINED.nodefault.
X=
xcoordinate.
H=
Heightofconductor.
Units=
Unitsforxandh:{mi|kft|km|m|Ft|in|cm}Initialdefaultis"ft",butdefaultstolast
unitdefined
Normamps=Normalampacity,amperesfortheline.Defaultstofirstconductorifnotspecified.
Emergamps=Emergencyampacity,amperes.Defaultstofirstconductorifnotspecified.
Reduce={
Yes|No}Default=no.ReducetoNphases(KronReduction).Reduceoutneutrals.
Like=
Makelikeanotherobject,e.g.:
NewCapacitor.C2like=c1...
Page 100 of 180
OpenDSS Manual
June 2013
L INE C ONSTANTS E XAMPLES

Definethewiredata:
New Wiredata.ACSR336 GMR=0.0255000 DIAM=0.7410000 RAC=0.3060000
~ NormAmps=530.0000
~ Runits=mi radunits=in gmrunits=ft
New Wiredata.ACSR1/0 GMR=0.0044600 DIAM=0.3980000 RAC=1.120000
~
NormAmps=230.0000
~
Runits=mi radunits=in gmrunits=ft
DefinetheGeometrydata:
New Linegeometry.HC2_336_1neut_0Mess nconds=4 nphases=3
~ cond=1 Wire=acsr336 x=-1.2909 h=13.716 units=m
~ cond=2 Wire=acsr336 x=-0.502
h=13.716 !units=m
~ cond=3 Wire=acsr336 x=0.5737
h=13.716 !units=m
~ cond=4 Wire= ACSR1/0 x=0
h=14.648 ! units=m
! neutral
Definea300ftlinesection:
New Line.Line1 Bus1=xxx
Bus2=yyy
~
Geometry= HC2_336_1neut_0Mess
~
Length=300
units=ft
Check out the line constants at 60 and 600 Hz in per km values. This command shows line
constantsforalldefinedgeometries:
Show lineconstants freq=60 units=km
Show lineconstants freq=600 units=km
If the number of conductors = 3, this Show command will also give you the sequence
impedances.Ifyourgeometryhasmorethan3conductorsandyouwanttoseethesequence
impedance,define
nconds = (...whatever...)
nphases = 3
Reduce=Yes
This will force the impedance matrices to be reduced to 3x3 and the Show LineConstants
command will automatically give the sequence impedances. Note: make sure the phase
conductorsaredefinedfirstinthegeometrydefinition.
No automatic assembly of bundled conductors is available yet. However, you can specifically
definethepositionofeachconductorinthegeometrydefinitionandconnectthemupexplicitly
intheDSS,forexample,foratwoconductorbundle:
New Line.2Bundled bus1=FromBus.1.1.2.2.3.3 ToBus.1.1.2.2.3.3
~ Geometry=2BundleGeometry Length= etc. etc.
L OAD S HAPE
A Loadshape object is very important for all types of sequential power flow solutions. A
LoadShape object consists of a series of multipliers, typically ranging from 0.0 to 1.0 that are
applied to the base kW values of the load to represent variation of the load over some time
period.
Page 101 of 180
OpenDSS Manual
June 2013
Loadshapesaregenerallyfixedinterval,butmayalsobevariableinterval.Forthelatter,both
thetime,hr,andthemultipliermustbespecified.
All loadshapes, whether they be daily, yearly, or some arbitrary duty cycle, are maintained in
thisclass.Eachloadsimplyreferstotheappropriateshapebyname.
The loadshape arrays may be entered directly in command line, or the load shapes may be
storedinoneofthreedifferenttypesoffilesfromwhichtheshapesareloadedintomemory.
ThepropertiesforLoadShapeobjectsare:
Npts=
Numberofpointstoexpectwhendefiningthecurve
Interval=
timeintervalofthedata,Hr.Default=1.0.Iftheloadshapehasnonuniformly
spacedpoints,specifytheintervalas0.0.
mInterval= SpecifyIntervalinminutes.
sInterval= SpecifyIntervalinseconds.
Mult=
Arrayofmultipliervalues.LookingforNptsvalues.Toenteranarray,simply
encloseaseriesofnumbersindoublequotes,singlequotes,or
parentheses(..).Omittedvaluesareassumedtobezero.Extravaluesareignored.
Youmayalsousethesyntax:
Mult=[file=myfile.txt]
Mult=[dblfile=myfile.dbl]
Mult=[sngfile=myfile.sng]
Thissyntaxwillworkonjustaboutanypropertyofanyclassofelementinthe
OpenDSSwhereanarrayofnumbersisexpected.Theadditionofthecapabilityto
handlethetwopackedbinaryfiletypesshouldsignificantlyspeeduptheimporting
ofAMIdataintoLoadshapeobjects.(seeUseActualproperty)Also,thewaythe
MeanandStdDeviationcalculationisdonehasbeenchangedtodelaycalculation
untilthesevaluesareactuallyneeded.Thisshouldminimizethecomputing
overheadonreadingloadshapesbackin
Hour=
Arrayofhourvaluescorrespondingtothemultipliers.NotrequiredifInterval>0.
Youmayalsousethesyntax:hour=(file=filename.ext)inwhichthehourarray
valuesareenteredoneperlineinthetextfilereferenced.Again,thisisnot
requiredforfixedintervalloadshapecurves.
QMult=
Arrayofmultipliervalues.SamepropertyrulesastheMultproperty.Ifspecified,
themultiplierisappliedtotheLoad(orGenerator)kvarvalue.Ifomitted,thevalue
ofMultisappliedtothekvarvalue.
Mean=
Meanofthemultiplierarray.Inpriorversions,themeanandstandarddeviation
werealwayscomputedafteranarrayofpointsareenteredornormalized(see
below).Fromversion7.3,themeanandstandarddeviationarecomputedonlyif
requestedtosametimewhenprocessingmanyAMIcurves.Ifyouaredoingonly
parametricloadstudiesusingtheMonteCarlosolutionmode,onlytheMeanand
StdDeviationarerequiredtodefinealoadshape.Thesetwovaluesmaybedefined
directlyratherthanbysupplyingthecurve.Ofcourse,themultiplierpointsarenot
generated.
Stddev=
StandardDeviation(seeMean,above).
Page 102 of 180
OpenDSS Manual
June 2013
The next three properties instruct the LoadShape object to get its data from a file. Three
different formats are allowed. If Interval>0 then only the multiplier is entered. For variable
intervaldata,setInterval=0.0andenterboththetime(inhours)andmultiplier,inthatorderfor
eachinterval.
Csvfile=
NameofaCSVfilecontainingloadshapedata,oneintervaltoaline.Forvariable
intervaldataenterone(hour,multiplier)pointtoalinewiththevaluesseparated
byacomma.Otherwisethereissimplyonevaluetoaline.
Sngfile=
Nameofabinaryfileofsingleprecisionfloatingpointvaluescontainingtheload
shapedata.Thefileispacked.Forfixedintervaldata,themultipliersarepackedin
order.Forvariableintervaldata,startwiththefirsthourpointandalternatewith
themultipliervalue.
Dblfile=
Nameofabinaryfileofdoubleprecisionfloatingpointvaluescontainingtheload
shapedata.Thefileispacked.Forfixedintervaldata,themultipliersarepackedin
order.Forvariableintervaldata,startwiththefirsthourpointandalternatewith
themultipliervalue.
Action=
{Normalize|DblSave|SngSave}Afterdefiningloadcurvedata,setting
action=normalizewillmodifythemultiplierssothatthepeakis1.0.Themeanand
stddeviationarerecomputed.Settingaction=DblSaveorSngSavewillcausethe
presentmultandqmultvaluestobewrittentoeitherapackedfileofdoubleor
single,respectively.Thefilenameistheloadshapename.Themultarraywillhavea
"_P"appendedonthefilenameandtheqmultarray,ifitexists,willhave"_Q"
appended.
UseActual={Yes|No*|True|False*}Iftrue,signalstoLoad,Generator,orotherobjectstouse
thevalueofthemultiplierastheactualkW,kvarvalueratherthanamultiplier.
NominallyforenteringAMIdata.DonotuseAction=NormalizewithUseActual=Yes.
Pmax,Qmax=IfyoudefinetheLoadShapeobjectwithUseActual=Yes,whenyoudefineanyof
theDuty,Daily,orYearlypropertiesofaloadorgenerator,thekWpropertyis
redefinedtothekWandkvarvaluesatthetimeofthepeakkWintheloadshape.
ThiswillbethevalueusedfortheinitialSnapshotsolution.Ifyoudefinemorethan
oneloadshapeobject,thelastoneoverridesanypreviousdefinition,aswithall
OpenDSSproperties.YoucanquerythePmaxandQmaxpropertiesofthe
Loadshapeobjecttoseewhatwascomputed.KeepinmindthattheQmaxvalueis
thevalueofkvaratthetimeofmaximumkW,ifdefinedusingtheQmultproperty.
Ifyouwantsomethingdifferent,youmayoverridethecomputedvaluesbysetting
eitherorbothofthesepropertiesafterreadingintheloadshapes.Ifyouwant
somethingelse,youwillneedtoredefinekWandkvar(orkW,PF)afteryousetthe
Duty,Daily,orYearlyproperties.
Pbase=
BasePvaluefornormalization.Defaultiszero,meaningthepeakwillbeused.
Like=Nameofanexistingloadshapeobjecttobasethisoneon.
G ROWTH S HAPE
AGrowthShapeobjectissimilartoaLoadshapeobject.However,itisintendedtorepresentthe
growthinloadyearbyyearandthewaythecurve isspecifiedisentirely different. You must
enterthegrowthforthefirstyear.Thereafter,onlytheyearswherethereisachangemustbe
entered.Otherwiseitisassumedthegrowthstaysthesame.
Growth rate is specified by specifying the multiplier for the previous year's load. Thus, if the
Page 103 of 180
OpenDSS Manual
June 2013
loadgrows2.5%in1999,themultiplierforthatyearwillbespecifiedas1.025.
(Ifnogrowthshapeisspecified,theloadgrowthdefaultstothecircuit'sdefaultgrowthrate
seeSet%Growthcommand).
Theparametersare:
Npts=Numberofpointstoexpectwhendefiningthecurve.
Year=
Arrayofyearvaluescorrespondingtothemultipliervalues.Enteronlythoseyears
inwhichthemultiplierchanges.Yeardatamaybeanyintegersequencejustso
it'sconsistentforallgrowthcurves.SettingtheglobalsolutionvariableYear=0
causesthegrowthfactortodefaultto1.0,effectivelyneglectinggrowth.Thisis
whatyouwoulddoforallbaseyearanalyses.
Youmayalsousethesyntax:year=(file=filename.ext)inwhichthearrayvaluesare
enteredoneperlineinthetextfilereferenced.
Mult=
ArrayofMultipliervaluescorrespondingtotheyearvalues.Entermultiplierby
whichtheloadwillgrowinthisyear.
Example:
Newgrowthshape.namenpts=3year="199920032007"mult="1.101.051.025"
Thisdefinesagrowthshapethea10%growthratefor19992002.Beginningin
2003,thegrowthtapersoffto5%andthento2.5%for2007andbeyond.
Normally,onlyafewpointsneedbeenteredandtheaboveparameterswillbe
quitesufficient.However,provisionhasbeenmadetoenterthe(year,multiplier)
pointsfromfilesjustliketheLoadShapeobjects.Youmayalsousethesyntax:
mult=(file=filename.ext)inwhichthearrayvaluesareenteredoneperlineinthe
textfilereferenced.
Csvfile=
Nameofacsvfilecontainingone(year,mult)pointperline.Separatetheyear
fromthemultiplierbyacomma.
Sngfile=
Nameofafileofsingleprecisionnumberscontaining(year,mult)pointspacked.
Dblfile=
Nameofafileofsingleprecisionnumberscontaining(year,mult)pointspacked.
Like=
NameofanexistingGrowthShapeobjecttobasethisoneon.
TCC_C URVE
ATCC_CurveobjectisdefinedsimilarlytoLoadshapeandGrowthshapeobjectsinthattheyall
are defined by curves consisting of arrays of points. Intended to model timecurrent
characteristics for overcurrent relays, TCC_Curve objects are also used for other relay types
requiringtimecurves.BoththetimearrayandtheCarraymustbeentered.
Thepropertiesare:
Npts=
Numberofpointstoexpectwhendefiningthecurve.
C_Array=
Arrayofcurrent(orvoltageorwhatever)valuescorrespondingtotimevaluesin
T_Array(seeT_Array).
T_Array=
Arrayoftimevaluesinsec.Typicalarraysyntax:
Page 104 of 180
OpenDSS Manual
June 2013
t_array=(1,2,3,4,...)
Youmayalsosubstituteafiledesignation:t_array=(file=filename).Thespecified
filehasonevalueperline.
Like=
NameofanexistingGrowthShapeobjecttobasethisoneon.
W IRE D ATA
Thisclassofdatadefinestherawconductordatathatisusedtocomputetheimpedancefora
linegeometry.
Note that you can use whatever units you want for any of the dimensional data be sure to
declaretheunits.Otherwise,theunitsareallassumedtomatch,whichwouldbeveryrarefor
conductor data. Conductor data is usually supplied in a hodgepodge of units. Everything is
convertedtometersinternallytotheDSS
Rdc=
dcResistance,ohmsperunitlength(seeRunits).DefaultstoRacifnotspecified.
Rac=
Resistanceat60Hzperunitlength.DefaultstoRdcifnotspecified.
Runits=
Lengthunitsforresistance:ohmsper{mi|kft|km|m|Ft|in|cm}Default=none.
GMRac=
GMRat60Hz.Defaultsto.7788*radiusifnotspecified.
GMRunits=UnitsforGMR:{mi|kft|km|m|Ft|in|cm}Default=none.
Radius=
Outsideradiusofconductor.DefaultstoGMR/0.7788ifnotspecified.
Radunits= Unitsforoutsideradius:{mi|kft|km|m|Ft|in|cm}Default=none.
Normamps=Normalampacity,amperes.DefaultstoEmergencyamps/1.5ifnotspecified.
Emergamps=Emergencyampacity,amperes.Defaultsto1.5*NormalAmpsifnotspecified.
Diam=
Diameter;Alternativemethodforenteringradius.
Like=
Makelikeanotherobjectofthisclass:
SeeHelpintheEXEversionoftheprogramformoreGeneralobjects.
Page 105 of 180
OpenDSS Manual
June 2013
DSS Circuit Element Object Descriptions

ThefollowingaredescriptionsofkeyDSScircuitelements.Thissectionisbynomeanscomplete
andoftenlagswellbehindimplementationsofnewelements.However,thisshouldbeenough
togetyoustartedwithDSSsimulations.Newcircuitelementclassesmaybeaddedatanytime.
Checktheonlinehelpforbriefhelponnewelements.
Page 106 of 180
OpenDSS Manual
June 2013
Source and Other Objects

V SOURCE O BJECT
Voltage source. This is a special power conversion element. It is special because voltage
sourcesareusedtoinitializethepowerflowsolutionwithallotherinjectionsourcessettozero.
A Vsource object is a twoterminal, multiphase Thevenin equivalent. That is, it is a voltage
source behind an impedance. The data are specified as it would commonly be for a power
systemsourceequivalent:Linelinevoltage(kV)andshortcircuitMVA.
Themostcommonwaytouseavoltagesourceobjectiswiththefirstterminalconnectedtothe
busofinterestwiththesecondterminalconnectedtoground(voltagereference).Inthisusage,
theconnectionofthesecondterminalmaybeomitted.In2009,thevoltagesourcewaschanged
from a singleterminal device to a twoterminal device. This allows for the connection of a
voltagesourcebetweentwobuses,whichisconvenientforsometypesofstudies.
Thepropertiesare,inorder:
Bus1=
Nameofbustowhichthesource'sfirstterminalisconnected.Rememberto
specifythenodeorderiftheterminalsareconnectedinsomeunusualmanner.Side
effect:TheprocessingofthispropertyresultsinthesettingoftheBus2propertyso
thatallconductorsinterminal2areconnectedtoground.Forexample,
Bus1=
busname
HasthesideeffectofsettingBus2=busname.0.0.0
Bus2=
Nameofbustowhichthesourcessecondterminalisconnected.Ifomitted,the
secondterminalisconnectedtoground(node0)atthebusdesignatedbytheBus1
property.
basekv=
baseorratedLinetolinekV.
pu=
Actualperunitatwhichthesourceisoperating.Assumedbalancedforallphases.
Angle=
Baseangle,degrees,ofthefirstphase.
Frequency=frequencyofthesource.
Phases=
Numberofphases.Default=3.0.
Mvasc3=
3phaseshortcircuitMVA=kVBase2/ZSC
Mvasc1=
1phaseshortcircuitMVA.Thereissomeambiguityconcerningthemeaningofthis
quantityFortheDSS,itisdefinedaskVBase2/Z1phasewhere
Z1phase=1/3(2Z1+Z0)
Thus,unlessaneutralreactorisused,itshouldbeanumberonthesameorderof
magnitudeasMvasc3.
x1r1=
RatioofX1/R1.Default=4.0.
x0r0=
RatioofX0/R0.Default=3.0.
Isc3=
Alternatemethodofdefiningthesourceimpedance.3phaseshortcircuitcurrent,
amps.Defaultis10000.
Page 107 of 180
OpenDSS Manual
June 2013
Isc1=
Alternatemethodofdefiningthesourceimpedance.singlephaseshortcircuit
current,amps.Defaultis10500.
R1=
Alternatemethodofdefiningthesourceimpedance.Positivesequenceresistance,
ohms.Defaultis1.65.
X1=
Alternatemethodofdefiningthesourceimpedance.Positivesequencereactance,
ohms.Defaultis6.6.
R0=
Alternatemethodofdefiningthesourceimpedance.Zerosequenceresistance,
ohms.Defaultis1.9.
X0=
Alternatemethodofdefiningthesourceimpedance.Zerosequencereactance,
ohms.Defaultis5.7.
ScanType= {pos*|zero|none}Maintainspecifiedsymmetricalcomponentsequenceto
assumeforHarmonicmodesolution.Defaultispositivesequence.Otherwise,angle
betweenphasesrotatesfreelywithharmonic.
Sequence= {pos*|neg|zero}Setthephaseanglerelationshipsforthespecifiedsymmetrical
componentsequenceforsolutionmodesotherthanHarmonics.Defaultispositive
sequence.
Spectrum= Nameofharmonicspectrumforthissource.Defaultis"defaultvsource",whichis
definedwhentheDSSstarts.
Z1
Positivesequenceimpedance,ohms,asa2elementarrayrepresentingacomplex
number.Example:
Z1=[1,2]!represents1+j2
Ifdefined,Z1,Z2,andZ0areusedtodefinetheimpedancematrixoftheREACTOR.
Z1MUSTBEDEFINEDTOUSETHISOPTIONFORDEFININGTHEMATRIX.
SideEffect:SetsZ2andZ0tosamevaluesunlesstheywerepreviouslydefined.
Z2
Negativesequenceimpedance,ohms,asa2elementarrayrepresentingacomplex
number.Example:
UsedtodefinetheimpedancematrixoftheREACTORifZ1isalsospecified.
Note:Z2defaultstoZ1ifitisnotspecificallydefined.IfZ2isnotequaltoZ1,the
impedancematrixisasymmetrical.
Z0
Zerosequenceimpedance,ohms,asa2elementarrayrepresentingacomplex
number.Example:
Note:Z0defaultstoZ1ifitisnotspecificallydefined.
BaseFreq=BaseFrequencyforimpedancespecifications.Defaultis60Hz.
like=NameofanexistingVsourceobjectonwhichtobasethisone.
Page 108 of 180
OpenDSS Manual
June 2013
I SOURCE O BJECT
Currentsource.Thisisaoneterminalcurrentsourceobjectthatcanbeconnectedtoanybus.
Its most common use is likely to be used to represent harmonic sources and to be used in
frequencyresponsescansofcircuitmodels.Youcanperformpositiveorzerosequencescans.
YoucangenerallyattachasmanyIsourceobjectstoabusasyouwant.AnIsourceisassumedto
beidealanditsYprimmatrixiszero.
Properties:
phases
Numberofphases.Defaultsto3.For3orless,phaseshiftdefaultsto120degrees.
bus1
Nameofbustowhichsourceisconnected.
bus1=busname
bus1=busname.1.2.3
amps
Magnitudeofcurrentsource,eachphase,inAmps.
angle
Phaseangleindegreesoffirstphase:e.g.,Angle=10.3.
Phaseshiftbetweenphasesdefaultsto120degreeswhennumberofphases<=3
frequency Sourcefrequency.Defaultstocircuitfundamentalfrequency.
scantype
{pos*|zero|none}Maintainspecifiedsequenceforharmonicsolution.Defaultis
positivesequence.Otherwise,anglebetweenphasesrotateswithharmonic.
sequence
{pos*|neg|zero}Setthephaseanglesforthespecifiedsymmetricalcomponent
sequenceforsolutionmodesotherthanHarmonics.Defaultispositivesequence.
spectrum
Harmonicspectrumassumedforthissource.Defaultis"default".
Inheritedproperties
basefreq
BaseFrequencyforratings.
enabled
{Yes|NoorTrue|False}Indicateswhetherthiselementisenabled.
like
NewIsource.Is2like=Is1...
Page 109 of 180
OpenDSS Manual
June 2013
F AULT O BJECT
AFaultobjectisaresistornetworkthatcanbeconfiguredinavarietyofways.Itisnominally
designedwiththesamephilosophyastheCapacitor.Thatis,itisatwoterminaldeviceinwhich
thesecondterminaldefaultstoground.Thisisoftenwhatisdesiredwhensimulatingafault.
However,theOpenDSSFaultobjectmaybeconfiguredtodomuchmoreandcanbeconfigured
torepresentanytypeoffault.Forexample,itcanbeconnectedbetweentransmissionoverbuild
anddistributionunderbuildtosimulatethetransmissionfallingonthedistributioncircuit.
AFaultobjectisastandardPowerDeliverycomponent.YoucanhaveasmanyFaultobjectson
thecircuitasyouwish(somemaycausethepowerflowsolutiontodivergeifso,switchtoa
directsolutionoradynamicsolution).ForMonteCarlofaultmode(MF)youwilldistributeFault
objects all over the circuit is some proportion. The solver will enable one at a time for each
solution.
SincetheFaultobjectisnothingmorethanaresistornetwork,youmayuseitforpurposesother
than modeling short circuit faults anything that requires a resistor model. With the Gmatrix
property a very complex resistive network can be modeled. For example, you may wish to
representafaultthathasoneresistanceLLandanotherLground.Notethatitisspecifiedasa
nodalconductancematrix.
IntimemodesimulationssuchasDynamics,theinitiationofthefaultcanbedelayed(ONtime
property) and it will automatically clear itself when the current drops below a certain level
(MinAmpsproperty)ifthefaultisdeclaredtobeTemporary.
phases
NumberofPhases.Defaultis1.
bus1
Nameoffirstbus.Examples:
bus1=busname
bus1=busname.1.2.3
bus2
Nameof2ndbus.Defaultstoallphasesconnectedtofirstbus,node0,ifnot
specified.(ShuntWyetogroundconnection)
Resistance,eachphase,ohms.Defaultis0.0001.AssumedtobeMeanvalueif
gaussianrandommode.Maxvalueifuniformmode.AFaultisactuallyaseries
resistancethatdefaultstoawyeconnectiontogroundonthesecondterminal.You
mayreconnectthe2ndterminaltoachievewhateverconnection.UsetheGmatrix
propertytospecifyanarbitraryconductancematrix.
Gmatrix
Usethistospecifyanodalconductance(G)matrixtorepresentsomearbitrary
resistancenetwork.SpecifyinlowertriangleformasusualforDSSmatrices.
MinAmps
Minimumampsthatcansustainatemporaryfault.Defaultis5.
ONtime
Time(sec)atwhichthefaultisestablishedfortimevaryingsimulations.Defaultis
0.0(onatthebeginningofthesimulation)
pctperm
Percentoffailuresthatbecomepermanent.(notused)
Temporary {Yes|No}DefaultisNo.Designatewhetherthefaultistemporary.ForTime
varyingsimulations,thefaultwillberemovedifthecurrentthroughthefaultdrops
belowtheMINAMPScriteria.
%stddev
PercentstandarddeviationinresistancetoassumeforMonteCarlofault(MF)
Page 110 of 180
OpenDSS Manual
June 2013
solutionmodeforGAUSSIANdistribution.Defaultis0(novariationfrommean).
StandardInheritedProperties(maynotapplytoFaultelements)
normamps Normalratedcurrent.
emergamps Maximumcurrent.
basefreq
faultrate
No.offailuresperyear.
repair
Hourstorepair.
enabled
like
NewFault.F2like=F1...
Page 111 of 180
OpenDSS Manual
June 2013
Power Delivery Elements (PDelement)

C APACITOR O BJECT
The capacitor model is basically implemented as a twoterminal power delivery element.
However, if you don't specify a connection for the second bus, it will default to the 0 node
(groundreference)ofthesamebustowhichthefirstterminalisconnected.Thatis,itdefaults
toagroundedwye(star)shuntcapacitorbank.
BASIC DEFINITION
DEFAULT AFTER
BUS1 IS DEFINED
DELTA
CONNECTION
MAKING AN
UNGROUNDED
WYE
Figure 18: Definition of Capacitor Object
Ifyouspecifytheconnectiontobe"delta"thenthesecondterminaliseliminated.
Ifyouwishaseriescapacitor,simplyspecifyasecondbusconnection.
Ifyouwishanungroundedwyecapacitor,setallthesecondterminalconductorstoanempty
nodeonthefirstterminalbus,e.g.:
Bus1=B1
bus2 = B1.4.4.4
! for a 3-phase capacitor
Ofcourse,anyotherconnectionispossiblybyexplicitlyspecifyingthenodes.
While the Capacitor object may be treated as if it were a single capacitor bank, it is actually
implemented as a multistep tuned filter bank. Many of the properties can be specified as
arrays.SeeNumstepsproperty.
Ifyouwishtorepresentafilterbank,specifyeithertheXLorHarmproperty.WhenaCapcontrol
objectswitchesacapacitor,itdoessobyincrementingordecrementingtheactivestep.
Properties,inorder,are:
Bus1=
Definitionfortheconnectionofthefirstbus.Whenthisisset,Bus2issettothe
samebusname,exceptwithallterminalsconnectedtonode0(groundreference).
SetBus2atsometimelaterifyouwishadifferentconnection.
Bus2=
Busconnectionforsecondterminal.MustalwaysbespecifiedafterBus1forseries
capacitor.Notnecessarytospecifyfordeltaorgrdwyeshuntcapacitor.Mustbe
specifiedtoachieveanungroundedneutralpointconnection.
Page 112 of 180
OpenDSS Manual
June 2013
Phases=
Numberofphases.Defaultis3.
Kvar=
Mostcommonofthreewaystodefineapowercapacitor.RatedkvaratratedkV,
totalofallphases.Eachphaseisassumedequal.NormampsandEmergamps
automaticallycomputed.Defaultis600.0kvar.Totalkvar,ifonestep,orARRAYof
kvarratingsforeachstep.Evenlydividedamongphases.SeerulesforNUMSTEPS.
Kv=
RatedkVofthecapacitor(notnecessarilysameasbusrating).ForPhases=2or
Phases=3,enterlinetoline(phasetophase)ratedvoltage.Forallothernumbers
ofphases,enteractualcanrating.(ForDeltaconnectionthisisalwayslinetoline
ratedvoltage).Defaultis12.47kV.
Conn=
Connectionofbank.Oneof{wye|ln}forwyeconnectedbanksor{delta|ll}for
delta(lineline)connectedbanks.Defaultiswye(orstraightthroughforseries
capacitor).
Cmatrix=
Alternatemethodofdefiningacapacitorbank.Enternodalcapacitancematrixin
f.Canbeusedtodefineeitherseriesorshuntbanks.Formshouldbe:
Cmatrix=[c11|c21c22|c31c32c33]
Allstepsareassumedthesameifthispropertyisused.
Cuf=
Alternatemethodofdefiningacapacitorbank.EnteravalueorARRAYofvaluesfor
Cinf.ARRAYofCapacitance,eachphase,foreachstep,microfarads.SeeRulesfor
NumSteps.
R=
ARRAYofseriesresistanceineachphase(line),ohms.Defaultis0.0
XL=
ARRAYofseriesinductivereactance(s)ineachphase(line)forfilter,ohmsatbase
frequency.UsethisOR"h"propertytodefinefilter.Defaultis0.0.
Harm=
ARRAYofharmonicstowhicheachstepistuned.Zeroisinterpretedasmeaning
zeroreactance(nofilter).Defaultiszero.
Numsteps=Numberofstepsinthiscapacitorbank.Default=1.Forcesreallocationofthe
capacitance,reactor,andstatesarray.Rules:Ifthispropertywaspreviously=1,the
valueinthekvarpropertyisdividedequallyamongthesteps.Thekvarproperty
doesnotneedtoberesetifthatiscorrect.IftheCuforCmatrixpropertywasused
previously,allstepsaresettothevalueofthefirststep.Thestatespropertyisset
toallstepson.Allfilterstepsareinitiallysettothesameharmonic.Ifthisproperty
waspreviously>1,thearraysarereallocated,butnovaluesarealtered.Youmust
SUBSEQUENTLYassignallarrayproperties.
states=
ARRAYofintegers{1|0}statesrepresentingthestateofeachstep(on|off).Defaults
to1whenreallocated(on).Capcontrolwillmodifythisarrayasitturnsstepsonor
off.
Normamps=Normalcurrentrating.Automaticallycomputedifkvarisspecified.Otherwise,you
needtospecifyifyouwishtouseit.
Emergamps=Overloadrating.Defaultsto135%ofNormamps.
Faultrate= Annualfailurerate.Failureeventsperyear.Defaultis0.0005.
Pctperm= Percentoffaultsthatarepermanent.Defaultis100.0.
Basefreq= Basefrequency,Hz.Defaultis60.0
Like=
NameofanotherCapacitorobjectonwhichtobasethisone.
Page 113 of 180
OpenDSS Manual
June 2013
L INE O BJECT
TheLineelementisusedtomodelmostmultiphase,twoportlinesorcables.ItisaPimodel
with shunt capacitance. This is a Power Delivery element described by its impedance.
Impedances may be specified by symmetrical component values or by matrix values.
Alternatively, you may simply refer to an existing LineCode object from which the impedance
valueswillbecopied.OryoumayspecifyanexistingGeometryobjectandthelineimpedances
willbecomputed.
YoucandefinethelineimpedanceatabasefrequencydirectlyinaLineobjectdefinitionoryou
can import the impedance definition from a LineCode object. Both of these definitions of
impedancearequitesimilarexceptthattheLineCodeobjectcanperformKronreduction.(See
LineCodeObject).
IftheGeometrypropertyisspecified,allpreviousdefinitionsareignored.TheDSSwillcompute
theimpedancematricesfromthespecifiedgeometryeachtimethefrequencychanges.
Whicheverdefinitionisthemostrecentapplies,aswithnearlyallDSSfunctions.
Notetheunitsproperty;youcandeclareanylengthmeasurementinwhateverunitsyouplease.
Internally,everythingisconvertedtometers.Justbesuretodeclaretheunits.Otherwise,they
areassumedtobecompatiblewithotherdataorirrelevant.
The default Line object is a 1000ft overhead line with 336 MCM ACSR conductor on a 8ft
crossarm.Itisdefinedbysymmetricalcomponentvalues:
R1
X1
R0
X0
C1
C0
=
=
=
=
=
=
0.0580 ohms per 1000

0.1206 ohms per 1000
0.1784 ohms per 1000
0.4047 ohms per 1000
3.4e-9 nF per 1000ft
1.6e-9 nF per 1000ft
ft
ft
ft
ft
ThecorrespondingvaluesofRgandXgforRho=100and60Hzare:
Rg = 0.01805
Xg = 0.155081
ohms per 1000 ft

ohms per 1000 ft
Theproperties,inorder,are:
bus1=
Nameofbusforterminal1.Nodeorderdefinitionsoptional.
bus2=
Nameofbusforterminal2.
Linecode= NameofanexistingLineCodeobjectcontainingimpedancedefinitions.
Length=
Lengthmultipliertobeappliedtotheimpedancedata.
Phases=
No.ofphases.Default=3.Alinehasthesamenumberofconductorsperterminal
asithasphases.Neutralsarenotexplicitlymodeledunlessdeclaredasaphase,
andtheimpedancematricesmustbeaugmentedaccordingly.Forexample,athree
phaselinehasa3x3Zmatrixwiththeneutralreduced,ora4x4Zmatrixwiththe
neutralretained.
SymmetricalComponentImpedanceDefinitionProperties
Page 114 of 180
OpenDSS Manual
June 2013
Ifanyofthefollowingpropertiesareused,theLineobjectprimitiveYmatrixis
computedusingthepresentvaluesoftheothersymmetricalcomponentline
properties.Thisisthedefaultmethod.Onelimitationtousingthesymmetrical
componentmethodisyoucantcorrectlyrepresentasymmetricalline
constructions.UsethematrixpropertiesortheGeometrypropertytoovercome
thislimitation.
R1=
positivesequenceresistance,ohmsperunitlength.
X1=
positivesequencereactance,ohmsperunitlength.
R0=
zerosequenceresistance,ohmsperunitlength.
X0=
zerosequencereactance,ohmsperunitlength.
C1=
positivesequencecapacitance,nanofaradsperunitlength.SettinganyofR1,R0,
X1,X0,C1,C0forcestheprogramtousethesymmetricalcomponentlinedefinition.
SeealsoCmatrixandB1
C0=
zerosequencecapacitance,nanofaradsperunitlength.
B1=
AlternatewaytoenterC1,microSperunitlength.
B0=
AlternatewaytoenterC0,microSperunitlength.
Normamps=Normalampacity,amps.
Emergamps=Emergencyampacity,amps.Usuallytheonehourrating.
Faultrate= Numberoffaultsperyearperunitlength.Thisisthedefaultforthisgeneralline
construction.
Pctperm= Percentofthefaultsthatbecomepermanent(requiringalinecrewtorepairanda
sustainedinterruption).
Repair=
Hourstorepair.
BaseFreq=BaseFrequencyatwhichtheimpedancevaluesarespecified.Default=60.0Hz.
MatrixImpedanceDefinitionProperties
YoumaydefinelineimpedancesinaLineobjectdefinitionusingmatrices.Ifyouuse
anyofthefollowingpropertiesanddonotsupercedeitwithasymmetrical
componentpropertyoreitheraLineCodeorGeometryproperty,theprimitiveY
matrixiscomputedassumingyouwishtousethequantitiesdefinedthroughthe
matrixpropertiesbelow.Thedefaultmatrixvaluescorrespondtothesymmetrical
componentdefaultsdescribedabove.Theremainatthosevaluesuntilyouchange
them.Matrixpropertiesallowyougreatflexibilityinmodelingallsortsofline
asymmetries.Ifyouwillbesolvingatsomefrequencyotherthanthebase
frequency,besuretodefineRgandXg(seeLineCodeobjectdescription).
Rmatrix=
Seriesresistancematrix,ohmsperunitlength.SeeCommandLanguageforsyntax.
Lowertriangleformisacceptable.
Xmatrix=
Seriesreactancematrix,ohmsperunitlength.
Cmatrix=
Shuntnodalcapacitancematrix,nanofaradsperunitlength.
Switch=
{y/n|T/F}Default=no/false.Designatesthislineasaswitchforgraphicsand
algorithmicpurposes.SIDEEFFECT:SetsR1=0.001X1=0.0.Youmustresetifyou
wantsomethingdifferent.
Rg=
Carsonearthreturnresistanceperunitlengthusedtocomputeimpedancevalues
Page 115 of 180
OpenDSS Manual
June 2013
atbasefrequency.Formakingbetterfrequencyadjustments.Appliestoline
impedancesdefinedusingtheLineobjectpropertiesdescribedhereorto
impedancesdefinedbyLineCodeobjects.Doesnotapplytoimpedancesdefinedby
Geometry.SeeexplanationinLineCodeobject.Defaultvaluesaresameasfor
defaultLineCodeobject,whichcorrespondstothedefaultLineobjectimpedances.
SetbothRgandXg=0ifyoudonotwishforearthreturncorrectiontobeadjusted
whenthefrequencyofthesolutionisdifferentthanthebasefrequency.
Xg=
Carsonearthreturnreactanceperunitlengthusedtocomputeimpedancevaluesat
basefrequency.Formakingbetterfrequencyadjustments.Appliestoline
impedancesdefinedusingtheLineobjectpropertiesdescribedhereorto
impedancesdefinedbyLineCodeobjects.Doesnotapplytoimpedancesdefinedby
Geometry.SeeexplanationinLineCodeobject.Defaultvaluesaresameasfor
defaultLineCodeobject,whichcorrespondstothedefaultLineobjectimpedances.
SetbothRgandXg=0ifyoudonotwishforearthreturncorrectiontobeadjusted
whenthefrequencyofthesolutionisdifferentthanthebasefrequency.
Rho=
Earthresistivityusedtocomputeearthcorrectionfactor.OverridesLinegeometry
definitionifspecified.Default=100meterohms.
Geometry= GeometrycodeforLineGeometryObject.Supercedesanypreviousdefinitionofline
impedance.Lineconstantsarecomputedforeachfrequencychangeorrhochange.
CAUTION:maycausethenumberofphasestoberedefined.
EarthModel Oneof{Carson|FullCarson|Deri}.Defaultistheglobalvalueestablishedwiththe
SetEarthModeloption.SeetheOptionsHelponEarthModeloption.Thisisusedto
overridetheglobalvalueforthisline.Thisoptionappliesonlywhenthe"geometry"
propertyisused.
Units=
LengthUnits={none|mi|kft|km|m|Ft|in|cm}DefaultisNoneassumes
lengthunitsmatchimpedanceunits.
Like=
NameofanexistingLineobjecttobuildthislike.
Page 116 of 180
OpenDSS Manual
June 2013
R EACTOR O BJECT
TheReactorelementisimplementedwithbasicallythesamephilosophyasaCapacitor(anda
Fault object). It is a constant impedance element that may be configured into a variety of
connections.LiketheCapacitor,thesecondterminaldefaultstoaWyeconnectiontogroundif
notspecified.Inthatcase,itisflaggedasaShuntelement.Itisaconstantimpedanceelement
entirelyrepresentedbyitsprimitiveYmatrix.
ThereactormaybeconceivedasaseriesRLoraparallelRLconnection(seeParallelproperty).
By default it is an inductance with series resistance. You may also specify a resistor, Rp, in
parallel with the entire branch. These options allow the Reactor impedance characteristic to
havedifferentfrequencyresponsecharacteristics,whichareoftenusefulforsomeHarmonics
modesimulations,particularlyforfilters.Inthecaseofashuntreactor,theRpvalueisusedfor
noloadlosses.
Zeroimpedance devices cannot exist in OpenDSS. However, either R or X can be zero in this
model. A Reactor element can be used for source equivalent or other equivalent impedances
wherethecapacitanceofaLineelementisunnecessary.Usea1phasereactortomodelneutral
reactors in transformers, generators, or loads. See the Tech Notes on the OpenDSS Wiki for
furtherdetails.
Bydefault,theReactorhasnocouplingbetweenthephases.Shuntreactorswouldtypicallybe
defined by kV and kvar properties, similar to a capacitor. Series reactors without mutual
coupling would be defined by the R and X properties. Of course, either could be used in all
circumstances.
Note that if the connection is specified as delta only the first terminal matters; there is no
secondterminal.Thisappliesonlytoshuntreactors.ByleavingtheConnpropertyaswyeand
specifying both terminal connections explicitly, nearly any reactor configuration can be
achieved.MutualcouplingbetweenphasescanbeachievedbyspecifyingRmatrixandXmatrix
properties. Note that the matrix specification is mutually exclusive with the other means of
specifyingthereactancevalues.Ofcourse,theRmatrixandXmatrixpropertiesmaybedefined
with zero mutual coupling. The Parallel property applies to the Rmatrix and Xmatrix
specification.
phases
Numberofphases.
bus1
Nameoffirstbus.Examples:
bus1=busname
bus1=busname.1.2.3
bus2
Nameof2ndbus.Defaultstoallphasesconnectedtofirstbus,node0.(ShuntWye
Connection)
Notnecessarytospecifyfordelta(LL)connection
kv
For2,3phase,kVphasephase.Otherwisespecifyactualcoilrating.
kvar
Totalkvar,allphases.Evenlydividedamongphases.OnlydeterminesX.SpecifyR
separately
conn
={wye|delta|LN|LL}Defaultiswye,whichisequivalenttoLN.IfDelta,thenonly
oneterminal.
Page 117 of 180
OpenDSS Manual
June 2013
Parallel
{Yes|No}Default=No.IndicateswhetherRmatrixandXmatrixaretobeconsidered
tobeinparallel.Thismakesasignificantdifferenceinharmonicstudies.Defaultis
series.Forothermodels,specifyRandRp.
Resistance(inserieswithreactance),eachphase,ohms.
Rmatrix
Resistancematrix,lowertriangle,ohmsatbasefrequency.Orderofthematrixis
thenumberofphases.MutuallyexclusivetospecifyingparametersbykvarorR.
Rp
ResistanceinparallelwithRandX(theentirebranch).Assumedinfiniteifnot
specified.
Reactance,eachphase,ohmsatbasefrequency.
Xmatrix
Reactancematrix,lowertriangle,ohmsatbasefrequency.Orderofthematrixisthe
numberofphases.MutuallyexclusivetospecifyingparametersbykvarorX.
AlternativewayofdefiningRandXproperties.Entera2elementarray
representingR+jXinohms.Example:
Z=[510]!equivalenttoR=5X=10
Z1
Positivesequenceimpedance,ohms,asa2elementarrayrepresentingacomplex
number.Example:
Ifdefined,Z1,Z2,andZ0areusedtodefinetheimpedancematrixoftheREACTOR.
Z1MUSTBEDEFINEDTOUSETHISOPTIONFORDEFININGTHEMATRIX.
SideEffect:SetsZ2andZ0tosamevaluesunlesstheywerepreviouslydefined.
Z2
Negativesequenceimpedance,ohms,asa2elementarrayrepresentingacomplex
number.Example:
Note:Z2defaultstoZ1ifitisnotspecificallydefined.IfZ2isnotequaltoZ1,the
impedancematrixisasymmetrical.
Z0
Zerosequenceimpedance,ohms,asa2elementarrayrepresentingacomplex
number.Example:
Note:Z0defaultstoZ1ifitisnotspecificallydefined.
Propertiesinheritedfromthecircuitelementclass:
normamps Normalratedcurrent.
emergamps Maximumcurrent.
repair
Hourstorepair.
faultrate
No.offailuresperyear.
pctperm
Percentoffailuresthatbecomepermanent.
basefreq
enabled
Page 118 of 180

like
OpenDSS Manual
June 2013
NewReactor.R2like=R1...
Page 119 of 180
OpenDSS Manual
June 2013
T RANSFORMER O BJECT
TheTransfomerisimplementedasamultiterminal(twoormore)powerdeliveryelement.
AtransfomerconsistsoftwoormoreWindings,connectedinsomewhatarbitraryfashion(with
adefaultWyeDeltaconnection).Youcanspecifytheparametersonewindingatatimeoruse
arraystosetallthewindingvaluesatonce.Usethe"wdg="parametertoselectawindingfor
editing.
Transformershaveoneormorephases.Thenumberofconductorsperterminalisalwaysone
morethanthenumberofphases.Forwyeorstarconnectedwindings,theextraconductoris
the neutral point. For deltaconnected windings, the extra terminal is open internally (you
normallyleavethisconnectedtonode0).
Properties,inorder,are:
Phases=Numberofphases.Defaultis3.
Windings=Numberofwindings.Defaultis2.
For defining the winding values one winding at a time, use the following parameters. Always
start the winding definition with "wdg = " when using this method of defining transformer
parameters.Theremainderofthetagsareoptionalasusualifyoukeeptheminorder.
Wdg=Integerrepresentingthewindingwhichwillbecometheactivewindingforsubsequent
data.
Bus=Definitionfortheconnectionofthiswinding(eachwindingisconnectedtooneterminalof
thetransformerand,hence,toonebus).
Conn=Connectionofthiswinding.Oneof{wye|ln}forwyeconnectedbanksor{delta|ll}for
delta(lineline)connectedbanks.Defaultiswye.
Kv=Ratedvoltageofthiswinding,kV.Fortransformersdesignated2or3phase,enterphase
tophasekV.Forallotherdesignations,enteractualwindingkVrating.Twophase
transfomersareassumedtobeemployedina3phasesystem.Defaultis12.47kV.
Kva=BasekVArating(OArating)ofthiswinding.
Tap=Perunittaponwhichthiswindingisset.
%R=PercentresistanceofthiswindingontheratedkVAbase.(Reactanceisbetweentwo
windingsandisspecifiedseparatelyseebelow.)
rneut=Neutralresistancetogroundinohmsforthiswinding.Ignoredifdeltawinding.Foropen
ungroundedneutral,settoanegativenumber.Defaultis1(capableofbeing
ungrounded).TheDSSdefaultstoconnectingtheneutraltonode0atabus,soit
willstillbegroundwhenthesystemYisbuilt.Tomaketheneutralfloating,
explicitlyconnectittoanunusednodeatthebus,e.g.,Bus=Busname.1.2.3.4,when
node4willbetheexplicitneutralnode.
xneut=Neutralreactanceinohmsforthiswinding.Ignoredifdeltawinding.Assumedtobein
serieswithneutralresistance.Defaultis0.
Use the following properties to set the winding values using arrays (setting of wdg= is
Page 120 of 180
OpenDSS Manual
June 2013
ignored).Thenamesofthesepropertiesaresimplythepluralformofthepropertynameabove.
Buses=Arrayofbusdefinitionsforwindings[1,2.].
Conns=Arrayofwindingconnectionsforwindings[1,2.].
KVs=ArrayofkVratingsfollowingrulesstatedaboveforthekVfieldforwindings[1,2,].
KVAs=ArrayofbasekVAratingsforwindings[1,2,].
Taps=Arrayofperunittapsforwindings[1,2,].
%Rs=Arrayofpercentresistancesforwindings[1,2.]
Usethefollowingpropertistodefinethereactancesofthetransformer.For2and3winding
transformers,youmayusetheconventionalXHL,XLT,andXHTparameters.Youmayalsoput
thevaluesinanarray(xscarray),whichisrequiredforhigherphaseordertransformers.There
are always n*(n1)/2 different short circuit reactances, where n is the number of windings.
Always use the kVA base of the first winding for entering impedances. Impedance values are
enteredinpercent.
XHL=Percentreactancehightolow(winding1towinding2).
XLT=Percentreactancelowtotertiary(winding2towinding3).
XHT=Percentreactancehightotertiary(winding1towinding3).
XscArray=Arrayofn*(n1)/2shortcircuitreactancesinpercentonthefirstwinding'skVAbase.
"n"isnumberofwindings.Orderis(12,13,14,1n,23,24,34,)
Generaltransformerratingdata:
Thermal=Thermaltimeconstant,hrs.Defaultis2.
n=Thermalexponent,n,fromIEEE/ANSIC57.Defaultis0.8.
m=Thermalexponent,m,fromIEEE/ANSIC57.Defaultis0.8.
flrise=Fullloadtemperaturerise,degreescentigrade.Defaultis65.
hsrise=Hotspottemperatirerise,degreescentigrade.Defaultis15.
%Loadloss=PercentLossesatratedload..Causesthe%rvaluestobesetforwindings1and2.
%Noloadloss=PercentNoloadlossesatnominalvoltage.Defaultis0.Causesaresistivebranch
tobeaddedinparallelwiththemagnetizinginductance.
%imag=Percentmagnetizingcurrent.Defaultis0.Aninductanceisusedtorepresentthe
magnetizingcurrent.Thisisembeddedwithinthetransformermodelasthe
primitiveYmatrixisbeingcomputed.
Ppm_Antifloat=Partspermillionforantifloatingreactancetobeconnectedfromeachterminal
toground.Defaultis1.Thatis,thediagonaloftheprimitiveYmatrixisincreasedby
afactorof1.000001.Preventssingularmatrixifdeltawindingleftfloating.Setthis
tozeroifyoudontneeditandtheresultingimpedancetogroundisaffectingthe
results.Isinconsequentialformostcases.
NormHKVA=NormalmaximumkVAratingforHwinding(1).Usually100110%ofmaximum
nameplaterating.
Page 121 of 180
OpenDSS Manual
June 2013
EmergHKVA=EmergencymaximumkVAratingforHwinding(1).Usually140150%of
maximumnameplaterating.Thisistheamountofloadingthatwillcause1%lossof
lifeinoneday.
Faultrate=Failureratefortransformer.Defaultsto0.007peryear.Allareconsidered
permanent.
Basefreq=Basefrequency,Hz.Defaultis60.0
Like=NameofanotherTransformerobjectonwhichtobasethisone.
Sub=Yes/No.Designateswhetherthistransformeristobetreatedasasubstation.Defaultis
No.
GICT RANSFORMER O BJECT

TheGICTransformermodelisusedincombinationwiththeGICLinemodelforthecalculationof
geomagneticallyinducedcurrent(GIC).TheGICLinemodelcontainsthesourcerepresentingthe
induced voltage. Transformers with a connection to ground provide a return path for the
resultingcurrent.
Power transformers are represented by their dc equivalent circuits, and only windings with
connection to ground are included in the analysis. The model is a resistor network for the
purposesofcomputingGICintransformers.Onlyfrequencydomainmodelsarenecessary.
Generator StepUp Banks

A common transformer connection in large networked power systems is the groundedwye
deltaconnectedgeneratorstepuptransformer(GSU).AthreephasemodelofaGSUusedin
GICcalculationsisshowninFigure19.
Figure 19. Three-phase Model of a Generator Step-Up Transformer
Notethatthedeltawindingdoesnothaveanyconnectiontotheexternalnetworksinceitisnot
physicallyconnectedtogroundandisopentothezerosequence.Thus,itisnotincludedinthe
OpenDSSmodel.TheHOterminalreferstotheneutralpoint,andismodeledexplicitly.Rw1and
Page 122 of 180
OpenDSS Manual
June 2013
Rw2aredefinedasthedcwindingresistancevaluesofthehighvoltageorextrahighvoltageand
mediumvoltagewindings,respectively.
TransformerwindingsaremodeledwithresistivebranchcircuitsasshowninFigure20.
Figure 20. GSU Model in OpenDSS
The winding terminals designated as NH.1, NH.2, and NH.3 in Fig. 23 must be connected
togethertoconstructthewyewinding.Thebusnumberisarbitrary,buttypicallythenameof
thehighsidebusisusedwiththenextavailableterminalnumber.AnexampleOpenDSSscript
withhighvoltagebusnamedBus1anddcwindingresistanceof0.1/phaseisasfollows:
New GICTransformer.T1 busH=Bus1.1.2.3 busNH=Bus1.4.4.4 R1=0.1 type=GSU
Toillustratethepreviouscommentofutilizingthenextavailableterminalvaluefortheneutral
bus,twoidenticalGSUsinparallelcanbedescribedbythefollowing:
Namingtheneutralbusesinthismannerallowsforthecreationofindividualneutralbusesfor
eachGSUwhichisnecessarywhenmodelingGICblockingdevices.
ThreeWinding Transformers
AthreephasemodelofathreewindingtransformerusedinthecalculationofGICisshownin
Figure 21. Note that the delta tertiary winding is not included in the model since it does not
have any physical connection to ground. Thus, the same model can be used for both two
windingandthreewindingtransformers.Theneutralnodesofbothofthewyewindings(i.e.X0
andH0)aremodeledexplicitly.Insomecases,eithertheX0orH0bushingmaybeungrounded.
IntheGICmodel,thenodecanbegroundedthroughalargeresistance,e.g.1Mtorepresent
suchconnections.
Page 123 of 180
OpenDSS Manual
June 2013
Figure 21. Three-phase Model of a Three-Winding Transformer (Grounded-Wye,

Grounded-Wye, Delta)
Rw1 and Rw2 are defined as the dc winding resistance values of the high voltage or extrahigh
voltageandmediumvoltagewindings,respectively.Rw3isdefinedasthedcwindingresistance
valuesofthelowvoltagetertiarywinding;however,itisnotincludedintheDSSmodelsinceit
hasnophysicalconnectiontoground.
TransformerwindingsaremodeledinDSSwithresistivebranchcircuitsasshowninFigure22.
Figure 22. Two-winding and Three-winding Transformer model in DSS
ThewindingterminalsdesignatedasNH.1,NH.2,NH.3andNX.1,NX.2,NX.3inFigure22must
beconnectedtogethertoconstructeachofthewyewindings.Thebusnumbersarearbitrary,
buttypicallythenameofthehighsidebusisusedwiththenextavailableterminalnumber.An
exampleOpenDSSscriptwithhighvoltagebusnamedBus1,lowvoltagebusnamedBus2,dc
winding resistance of 0.2 /phase for the H winding and 0.1 /phase for the X winding is as
Page 124 of 180
OpenDSS Manual
June 2013

follows:
New GICTransformer.T1 busH=Bus1.1.2.3 busNH=Bus1.4.4.4 busX=Bus2.1.2.3

busNX=Bus1.5.5.5 R1=0.2 R2=0.1 type=YY
Autotransformers
AthreephasemodelofanautotransformerusedindeterminingGICflowisshowninFigure23.
Notethatthedeltatertiarywinding(ifapplicable)isnotincludedintheDSSmodelsinceitdoes
nothaveanyphysicalconnectiontoground.Thecommonautotransformerneutral(H0/X0)is
modeledexplicitly.
Figure 23 Three-phase Model of a Three-Winding Autotransformer
Rw1 and Rw2 are defined as the dc resistance values of the series and common windings,
respectively.TransformerwindingsaremodeledinDSSwithresistivebranchcircuitsasshown
inFigure24.
Page 125 of 180
OpenDSS Manual
June 2013
Figure 24. Two-winding and Three-winding Autotransformer model in DSS
The winding terminals designated as NX.1, NX.2, and NX.3 in Figure 24 must be connected
togethertoconstructtheneutralconnection.Thebusnumbersarearbitrary,buttypicallythe
name of the high side bus with the next available terminal number is used to designate the
neutralbus.AnexampleOpenDSSscriptwithhighvoltagebusnamedBus1,lowvoltagebus
namedBus2,dcwindingresistanceof0.1/phasefortheserieswindingand0.2/phasefor
thecommonwindingisasfollows:
New GICTransformer.T1 busH=Bus1.1.2.3 busX=Bus2.1.2.3 busNX=Bus1.4.4.4 R1=0.1
R2=0.2 type=auto
ThepropertiesoftheGICTransformermodel,inorder,are:
Basefreq=InheritedPropertyforallPCElements.Basefrequencyforspecificationofreactance
value.
busH= NameofbusHighside(H)bus.Nodeorderdefinitionsoptional.
busNH=
NameofNeutralbusforH,orfirst,winding.Defaultstoallphasesconnectedto
Hside bus, node 0, if not specified and transformer type is either GSU or YY. (Shunt Wye
Connectiontogroundreference)ForAuto,thisisautomaticallysettotheXbus.
busNX=
NameofNeutralbusforX,orSecond,winding.Defaultstoallphasesconnected
toXsidebus,node0,ifnotspecified.(ShuntWyeConnectiontogroundreference).
busX= NameofbusLowside(X)bus.Nodeorderdefinitionsoptional.
emergamps=Maximumcurrent.TypicallynotspecifiedinGICcalculations.
enabled= {Yes|No or True|False} Indicates whether this element is enabled. Default is
Yes/True.
phases=Numberofphases.Defaultis3.
R1=Resistance,eachphase,ohmsforHwinding,(Serieswinding,ifAuto).Defaultis0.0001.
Page 126 of 180
OpenDSS Manual
June 2013
R2=Resistance,eachphase,ohmsforXwinding,(Commonwinding,ifAuto).Defaultis0.0001.
Type=Typeoftransformer:{GSU*|Auto|YY}.DefaultisGSU.
MVA=
Optional.MVARatingassumedTransformer.Defaultis100.Usedforcomputing
varsduetoGICandwindingresistancesifkVandMVAratingsarespecified.
KVLL1=
Optional.kVLLratingforHwinding(winding1).Defaultis500.Requiredifyou
aregoingtoexportvarsforpowerflowanalysisorenterwindingresistancesin
percent.
KVLL2=
Optional.kVLLratingforXwinding(winding2).Defaultis138.Requiredifyou
aregoingtoexportvarsforpowerflowanalysisorenterwindingresistancesin
percent..
%R1=
Optional.PercentResistance,each phase,forHwinding (1), (Serieswinding,if

Auto). Default is 0.2. Alternative way to enter R1 value. It is the actual
resistancesinohmnsthatmatter.MVAandkVshouldbespecified.
%R2=
Optional.PercentResistance,eachphase,forXwinding(2),(Commonwinding,
if Auto). Default is 0.2. Alternative way to enter R2 value. It is the actual
resistancesinohmsthatmatter.MVAandkVshouldbespecified.
K=
Mvar K factor. Default way to convert GIC Amps in H winding (winding 1) to

Mvar. Default is 2.2. Commonlyused simple multiplier for estimating Mvar
lossesforpowerflowanalysis.
Mvar=K*kvLL*GICperphase/1000
Mutually exclusive with using the VarCurve property and pu curves.If you
specifythis(default),VarCurveisignored.
VarCurve=
Optional. XYCurve object name. Curve is expected as TOTAL pu vars vs pu GIC

amps/phase. Vars are in pu of the MVA property. No Default value. Required
onlyifyouaregoingtoexportvarsforpowerflowanalysisusingcurves.SeeK
property.
like=Makelikeanotherobject,e.g.NewGICTransformer.T2like=T1...
ThefollowingpropertiesareinheritedfromthePowerDeliveryelementclass,butareignored
forGICcalculations
normamps=
Normalratedcurrent.TypicallynotspecifiedinGICcalculations.
emergamps= Maximumcurrent.TypicallynotspecifiedinGICcalculations.
pctperm=
Percent of failures that become permanent. Typically not specified in GIC

calculations.
Page 127 of 180

repair=
OpenDSS Manual
June 2013
Hourstorepair.TypicallynotspecifiedinGICcalculations.
Page 128 of 180
OpenDSS Manual
June 2013
Power Conversion Elements (PCelement)

GICL INE O BJECT
The GICLine model is used in the calculation of geomagnetically induced current (GIC).
Normally, one would think of a Line element as a power delivery device, but in GIC analysisa
Line is actually a source. Each phase of the transmission line is represented by a quasidc
induced voltage (0.1 Hz) in series with the dc resistance of the line. The resulting model is
depictedinFigure25.
Rdc
Rdc
Rdc
V
V

Figure 25. GICLine Model
TheinducedvoltageshowninFigure17canbecomputedinternallybytheprogramorsupplied
viatheVoltspropertyoftheGICLinemodel.Thefollowingdescribestheprocedureutilizedby
OpenDSStocomputetheinducedvoltage.
TheinducedvoltageshowninFigure17isdeterminedbyanapplicationofFaradaysLaw:

V E dl
where E is the electric field vector at the location of the transmission line, and dl is the
incrementallinesegmentlengthincludingdirection.Becausethedistancebetweenthesource
oftheinducedgeoelectricfield(electrojet)andtheearthssurfaceisgenerallyontheorderof
100200km,theelectricfieldattheheightofthetransmissionlinecanassumedtobethesame
as that of the earths surface. If the geoelectric field is assumed constant in the geographical
areaofatransmissionline,thenonlythecoordinatesoftheendpointofthelineareimportant,
regardlessofroutingtwistsandturns.Theresultingincrementallengthvector dl ,becomes L .
Theinducedvoltagecanthereforebecomputedasfollows:

E dl E L
Page 129 of 180
OpenDSS Manual
June 2013
The vector L , representing the length and direction of the line between end points can be
constructed using an arbitrary reference; however, such methods can introduce error. An
improvedmethodistoconstructthevector L ,bycomputingthedistanceintheNorthwardand
EastwarddirectionsindependentlyasdepictedinFigure26.
LN
LE
Figure 26. Substation Location Coordinates
RecallthatthedotproductoftwovectorsAandBcanbecomputedusing:

A B Ax B x A y B y
Thus,thedotproductoftheinducedelectricfieldandthelengthvectorcanbeapproximated
by:

E L E N L N E E LE
whereENisthenorthwardelectricfield(V/km),EEistheeastwardelectricfield(V/km),LNisthe
northwarddistance(km),andLEistheeastwarddistance(km).
Thefollowingprocedurecanbeusedtocomputenorthwardandeastwarddistances.Considera
transmissionlinebetweensubstationsAandBasshowninFig.18.Thenorthwarddistancecan
becomputedusing:
L N 111.2 lat
where lat is the difference in latitude (degrees) between the two substations A and B. The
eastwarddistancecanbecomputedusing:
L E 111.2 long sin 90
Page 130 of 180
OpenDSS Manual
June 2013
wherelongisthedifferenceinlongitude(degrees)betweenthetwosubstationsAandB,and
isdefinedastheaverageofthetwolatitudes:
LatA LatB
ThepropertiesoftheGICLinemodel,inorder,are:
Angle=
Phaseangleindegreesoffirstphase.Default=0.0.SeeVoltageproperty
bus1=
Nameofbusforterminal1.Nodeorderdefinitionsoptional.
bus2=
Nameofbusforterminal2.
C=
Valueoflineblockingcapacitanceinmicrofarads.Default=0.0,implyingthatthere
isnolineblockingcapacitor.
EE=
EastwardElectricfield.Ifspecified,VoltageandAnglearecomputedfromEN,EE,
latandlonvalues.
EN=
NorthwardElectricfield.Ifspecified,VoltageandAnglearecomputedfromEN,EE,
latandlonvalues.
frequency= Sourcefrequency.Defaultsto0.1Hz.
Lat1=
LatitudeofBus1(degrees)
Lat2=
LatitudeofBus2(degrees)
Lon1=
LongitudeofBus1(degrees)
Lon2=
LongitudeofBus2(degrees)
Phases=
No.ofphases.Default=3.Alinehasthesamenumberofconductorsperterminal
asithasphases.Neutralsarenotexplicitlymodeledunlessdeclaredasaphase,
andtheimpedancematricesmustbeaugmentedaccordingly.Forexample,athree
phaselinehasa3x3Zmatrixwiththeneutralreduced,ora4x4Zmatrixwiththe
neutralretained.
R=
Resistanceofline,ohmsofimpedanceinserieswithGICvoltagesource.
Volts=
Voltagemagnitude,involts,oftheGICvoltageinducedacrossthisline.When
spedified,voltagesourceisassumeddefinedbyVoltageandAngleproperties.
SpecifythisvalueOREN,EE,lat1,lon1,lat2,lon2.Notboth!!Lastoneenteredwill
takeprecedence.AssumedidenticalineachphaseoftheLineobject.
X=
Reactanceatbasefrequency,ohms.Default=0.0.Thisvalueisgenerallynot
importantforGICstudiesbutmaybeusedifdesired.
The following properties are common to all Power Conversion elements and inherited by
GICLine.
like=
MakelikeanotherGICLineobject
Basefreq=
Inherited Property for all PCElements. Base frequency for specification of the
reactancevalue,X,ifdefined.
enabled=
{Yes|No or True|False} Indicates whether this element is enabled. Inherited

PropertyforallPCElements.
Page 131 of 180

Spectrum=
OpenDSS Manual
June 2013
Inherited Property for all PCElements. Name of harmonic spectrum for this
source.Defaultis"defaultvsource",whichisdefinedwhentheDSSstarts.Not
usedforGICanalysis.
L OAD O BJECT
ALoadisacomplicatedPowerConversionelementthatisattheheartofmanyanalyses.Itis
basicallydefined byitsnominal kWandPForitskWand kvar. Thenit maybe modifiedbya
numberofmultipliers,includingtheglobalcircuitloadmultiplier,yearlyloadshape,dailyload
shape,andadutycycleloadshape.
Thedefaultisfortheloadtobeacurrentinjectionsource.Thus,itsprimitiveYmatrixcontains
only the impedance that might exist from the neutral of a wyeconnected load to ground.
However, if the load model is switched to Admittance from PowerFlow (see Set LoadModel
command), the load is converted to an admittance and included in the system Y matrix. This
wouldbethemodelusedforfaultstudieswhereconvergencemightnotbeachievedbecauseof
lowvoltages.
Loadsareassumedbalancedforthenumberofphasesspecified.Ifyouwouldlikeunbalanced
loads,enterseparatesinglephaseloads.
Therearethreelegalwaystospecifythebaseload:
1. kW,PF
2. kw,kvar
3. kVA,PF
Ifyousentthesepropertiesintheordershown,thedefinitionshouldwork.Ifyoudeviatefrom
these procedures, the result may or may not be what you want. (To determine if it has
accomplished the desired effect, execute the Dump command for the desired load(s) and
observethesettings.)
bus1=
Nameofbustowhichtheloadisconnected.Includenodedefinitionsifthe
terminalconductorsareconnectedabnormally.3phaseWyeconnectedloads
have4conductors;Deltaconnectedhave3.Wyeconnectedloads,ingeneral,have
onemoreconductorthanphases.1phaseDeltahas2conductors;2phasehas3.
TheremainingDelta,orlineline,connectionshavethesamenumberofconductors
asphases.
Phases=
No.ofphasesthisload.
Kv=
Basevoltageforload.For2or3phaseloads,specifiedinphasetophasekV.For
allotherloads,theactualkVacrosstheloadbranch.Ifwye(star)connected,then
specifyphasetoneutral(LN).Ifdeltaorphasetophaseconnected,specifythe
phasetophase(LL)kV.
Page 132 of 180
OpenDSS Manual
June 2013
Kw=
nominalkWforload.Totalofallphases.SeekVA.
Pf=
nominalPowerFactorforload.NegativePFisleading.SpecifyeitherPForkvar
(seebelow).Ifbotharespecified,thelastonespecifiedtakesprecedence.
Model=
Integerdefininghowtheloadwillvarywithvoltage.Presentlydefinedmodelsare:
1:Normalloadflowtypeload:constantPandQ.
2:Constantimpedanceload
3:ConstantP,QuadraticQ(somewhatlikeamotor)
4:LinearP,QuadraticQ(Mixedresistive,motor)
5:Rectifierload(ConstantP,constantcurrent)
6:ConstantP;Qisfixedatnominalvalue
7:ConstantP;Qisfixedimpedanceatnominalvalue
8:ZIPmodel
"Constant"valuesmaybemodifiedbyloadshapemultipliers."Fixed"valuesare
alwaysthesameatnominal,orbase,value.
Yearly=
NameofYearlyloadshape.
Daily=
NameofDailyloadshape.
Duty=
nameofDutycycleloadshape.DefaultstoDailyloadshapeifnotdefined.
Growth=
NameofGrowthShapeGrowthfactordefaultstothecircuit'sdefaultgrowthrateif
notdefined.(seeSet%Growthcommand)
Conn=
{wye|y|LN}forWye(LineNeutral)connection;{delta|LL}forDelta(LineLine)
connection.Default=wye.
Kvar=
Basekvar.Ifthisisspecified,supercedesPF.(seePF)
Rneut=
Neutralresistance,ohms.Ifenteredasnegative,nonzeronumber,neutralis
assumedopen,orungrounded.Ignoredfordeltaorlinelineconnectedloads.
Xneut=
Neutralreactance,ohms.Ignoredfordeltaorlinelineconnectedloads.Assumed
tobeinserieswithRneutvalue.
Status=
{fixed|variable}.Defaultisvariable.Iffixed,thentheloadisnotmodifiedby
multipliers;itisfixedatitsdefinedbasevalue.
Class=
Integernumbersegregatingtheloadaccordingtoaparticularclass.
Vminpu= Default=0.95.MinimumperunitvoltageforwhichtheMODELisassumedto
apply.Belowthisvalue,theloadmodelrevertstoaconstantimpedancemodel.
Vmaxpu= Default=1.05.MaximumperunitvoltageforwhichtheMODELisassumedto
apply.Abovethisvalue,theloadmodelrevertstoaconstantimpedancemodel.
VminNorm=MinimumperunitvoltageforloadEENevaluations,Normallimit.Default=0,
whichdefaultstosystem"vminnorm"property(seeSetCommandunder
Executive).Ifthispropertyisspecified,itALWAYSoverridesthesystem
specification.Thisallowsyoutohavedifferentcriteriafordifferentloads.Setto
zerotoreverttothedefaultsystemvalue.
VminEmerg=MinimumperunitvoltageforloadUEevaluations,Emergencylimit.Default=0,
whichdefaultstosystem"vminemerg"property(seeSetCommandunder
Page 133 of 180
OpenDSS Manual
June 2013
Executive).Ifthispropertyisspecified,itALWAYSoverridesthesystem
specification.Thisallowsyoutohavedifferentcriteriafordifferentloads.Setto
zerotoreverttothedefaultsystemvalue.
XfkVA=
Default=0.0.RatedkVAofservicetransformerforallocatingloadsbasedon
connectedkVAatabus.Sideeffect:kW,PF,andkvararemodified.See
PeakCurrentpropertyofEnergyMeter.SeealsoAllocateLoadsCommand.SeekVA
propertybelow.
AllocationFactor=Default=0.5.AllocationfactorforallocatingloadsbasedonconnectedkVA
atabus.Sideeffect:kW,PF,andkvararemodifiedbymultiplyingthisfactortimes
theXFKVA(if>0).SeealsoAllocateLoadsCommand.
kVA=
DefinitionoftheBaseloadinkVA,totalallphases.Thisisintendedtobeusedin
combinationwiththepowerfactor(PF)todeterminetheactualload.Legalwaysto
definebaseload(kWandkvar):
kW,PF
kW,kvar
kVA,PF
XFKVA*Allocationfactor,PF
kWh/(kWhdays*24)*Cfactor,PF
%mean=
Percentmeanvalueforloadtouseformontecarlostudiesifnoloadshapeis
assignedtothisload.Defaultis50.
%stddev= PercentStddeviationvalueforloadtouseformontecarlostudiesifnoloadshape
isassignedtothisload.Defaultis10.
CVRwatts=Percentreductioninactivepower(watts)per1%reductioninvoltagefrom100%
rated.Default=1.Typicalvaluesrangefrom0.4to0.8.AppliestoModel=4only.
Intendedtorepresentconservationvoltagereductionorvoltageoptimization
measures.
CVRvars= Percentreductioninreactivepower(vars)per1%reductioninvoltagefrom100%
rated.Default=2.Typicalvaluesrangefrom2to3.AppliestoModel=4only.
Intendedtorepresentconservationvoltagereductionorvoltageoptimization
measures.
kWh=
kWhbilledforthisperiod.Defaultis0.SeehelponkVAandCfactorandkWhDays.
kWhDays=LengthofkWhbillingperiodindays(24hrdays).Defaultis30.Averagedemandis
computedusingthisvalue.
CFactor=
FactorrelatingaveragekWtopeakkW.Defaultis4.0.SeekWhandkWhdays.See
kVA.
CVRCurve=DefaultisNONE.Curvedescribingbothwattandvarfactorsasafunctionoftime.
ReferstoaLoadShapeobjectwithbothMultandQmultdefined.Definea
Loadshapetoagreewithyearlyordailycurveaccordingtothetypeofanalysis
beingdone.IfNONE,theCVRwattsandCVRvarsfactorsareusedandassumed
constantforthesimulationperiod.
NumCust=Numberofcustomers,thisload.Defaultis1.
spectrum=Nameofharmoniccurrentspectrumforthisload.Defaultis"defaultload",whichis
definedwhentheDSSstarts.
Page 134 of 180
OpenDSS Manual
June 2013

ZIPV=Arrayof7coefficients:
1.
First3areZIPweightingfactorsforactivepower(shouldsumto1)
2.
Next3areZIPweightingfactorsforreactivepower(shouldsumto1)
3.
Last1iscutoffvoltageinp.u.ofbasekV;loadis0belowthiscutoff
Nodefaults;allcoefficientsmustbespecifiedifusingmodel=8.
%SeriesRL= PercentofloadthatisseriesRLforHarmonicstudies.Defaultis50.Remainderis
assumedtobeparallelRandL.Thishasasignificantimpactontheamountof
dampingobservedinHarmonicssolutions.
Basefreq=Basefrequencyforwhichthisloadisdefined.Defaultis60.0.
Like=
NameofanotherLoadobjectonwhichtobasethisone.
Page 135 of 180
OpenDSS Manual
June 2013
G ENERATOR O BJECT
A Generator is a Power Conversion element similar to a Load object. Its rating is basically
definedbyitsnominalkWandPForitskWandkvar.Thenitmaybemodifiedbyanumberof
multipliers,includingtheglobalcircuitloadmultiplier,yearlyloadshape,dailyloadshape,anda
dutycycleloadshape.
Forpowerflowstudies,thegeneratorisessentiallyanegativeloadthatcanbedispatched.For
Harmonicsmode,thegeneratorisconvertedtoavoltagesourcebehindthevaluespecifiedfor
Xdthatapproximatelymatchesthepowerflowsolution.Fordynamicsmode,thegeneratoris
converted to a voltage source behind an impedance with the impedance dependent on the
modelchosen.
If the dispatch value (DispValue property) is 0, the generator always follows the appropriate
dispatch curve, which is simply a Loadshape object. If DispValue>0 then the generator only
comesonwhentheglobalcircuitloadmultiplierexceedsDispValue.Whenthegeneratorison,
italwaysfollowsthedispatchcurveappropriateforthetypeofsolutionbeingperformed.
Ifyouwanttomodelageneratorthatisfullyonwheneveritisdispatchedon,simplydesignate
"Status=Fixed".Thedefaultis"Status=Variable"(i.e.,itfollowsadispatchcurve.Youcouldalso
defineadispatchcurvethatisalways1.0.
Generatorshavetheirownenergymetersthatrecord:
1.Totalkwh
2.Totalkvarh
3.MaxkW
4.MaxkVA
5.Hoursinoperation
6.$(Pricesignal*energygenerated)
Generatormetersresetwiththecircuitenergymetersandtakeasamplewiththecircuitenergy
metersaswell.TheEnergymetersalsousedtrapezoidalintegrationsothattheyarecompatible
withLoadDurationsimulations.
Generatorpowermodelsforpowerflowsimulationsare:
1. ConstantP,Q(*dispatchcurve,ifappropriate).
2. ConstantZ(Forsimple,approximatesolution)
3. Constant P, |V| somewhat like a standard power flow with voltage magnitudes and
anglesasthevariablesinsteadofPandQ.
Page 136 of 180
OpenDSS Manual
June 2013
4. ConstantP,fixedQ.Pfollowsdispatch;Qisalwaysthesame.
5. Constant P, fixed reactance. P follows dispatch, Q is computed as if it were a fixed
reactance.
6. Userwrittenmodel
7. CurrentlimitedconstantP,Qmodel(likesomeinverters).
Mostofthetimeyouwilluse#1forplanningstudies,assumingyouwanttospecifyaspecific
power. All load models can follow Loadshapes. Some follow only the P component while the
Type1canfollowbothaPandQcharacteristic.
Thedefaultisforthegeneratortobeacurrentinjectionsource(Nortonequivalent).Thus,its
primitive Y matrix is similar to a Load object with a nominal equivalent admittance at rated
voltage included in the primitive Y matrix and the injection current representing the amount
required to compensate the Norton equivalent to achieve the desired terminal current.
However, if the generator model is switched to Admittance from PowerFlow (see Set Mode
command),thegeneratorterminalcurrentiscomputedsimplyfromequivalentadmittancethat
isincludedinthesystemYmatrix.
Generatorpowersareassumedbalancedoverthenumberofphasesspecified.Ifyouwouldlike
unbalancedgenerators,enterseparatesinglephasegenerators.
Theproperties,innumericalorder,are:
bus1=
Nameofbustowhichthegeneratorisconnected.Includenodedefinitionsifthe
terminalconductorsareconnectedunusually.3phaseWyeconnectedgenerators
have4conductors;Deltaconnectedhave3.Wyeconnectedgenerators,ingeneral,
haveonemoreconductorthanphases.1phaseDeltahas2conductors;2phase
has3.TheremainingDelta,orlineline,connectionshavethesamenumberof
conductorsasphases.
Phases=
No.ofphasesthisgenerator.
Kv=
Basevoltageforgenerator.For2or3phasegenerators,specifiedinphaseto
phasekV.Forallothergenerators,theactualkVacrossthegeneratorbranch.If
wye(star)connected,specifythephasetoneutral(LN)kV.Ifdeltaorphaseto
phaseconnected,specifythephasetophase(LL)kV.
Kw=
nominalkWforgenerator.Totalofallphases.
Pf=
nominalPowerFactorforgenerator.NegativePFisleading(absorbingvars).
SpecifyeitherPForkvar(seebelow).Ifbotharespecified,thelastonespecified
takesprecedence.
Model=
Integerdefininghowthegeneratorwillvarywithvoltage.Presentlydefinedmodels
are:
1:GeneratorinjectsaconstantkWatspecifiedpowerfactor.
2:Generatorismodeledasaconstantadmittance.
3:ConstkW,constantkV.Somewhatlikeaconventionaltransmissionpowerflow
PVgenerator.
4:ConstkW,FixedQ(Qnevervaries)
Page 137 of 180
OpenDSS Manual
June 2013
5:ConstkW,FixedQ(asaconstantreactance)
6:ComputeloadinjectionfromUserwrittenModel.(seeusageofXd,Xdp)
7:ConstantkW,kvar,butcurrentislimitedwhenvoltageisbelowVminpu
Yearly=
NameofYearlyloadshape.
Daily=
NameofDailyloadshape.
Duty=
nameofDutycycleloadshape.DefaultstoDailyloadshapeifnotdefined.
Dispvalue=Dispatchvalue.If=0.0thenGeneratorfollowsdispatchcurves.If>0then
GeneratorisONonlywhenthegloballoadmultiplierexceedsthisvalue.Thenthe
generatorfollowsdispatchcurves(seealsoStatus)
Conn=
{wye|y|LN}forWye(LineNeutral)connection;{delta|LL}forDelta(LineLine)
connection.Default=wye.
Kvar=
Basekvar.Ifthisisspecified,willsupercedePF.(seePF)
Rneut=
Neutralresistanceohms.Ifenteredasnegative,nonzeronumber,neutralis
assumedopen,orungrounded.Ignoredfordeltaorlinelineconnectedgenerators.
Defaultis0.
Xneut=
Neutralreactance,ohms.Ignoredfordeltaorlinelineconnectedgenerators.
AssumedtobeinserieswithRneutvalue.
Status=
{fixed|variable}.IfFixed,thendispatchmultipliersdonotapply.Thegeneratoris
alwaysatfullpowerwhenitisON.DefaultisVariable(followscurves).
Class=
Integernumbersegregatingthegeneratoraccordingtoaparticularclass.
Maxkvar= MaximumkvarlimitforModel=3.Defaultstotwicethespecifiedloadkvar.
AlwaysresetthisifyouchangePForkvarproperties.
Minkvar= MinimumkvarlimitforModel=3.Enteranegativenumberifgeneratorcanabsorb
vars.DefaultstonegativeofMaxkvar.AlwaysresetthisifyouchangePForkvar
properties.
Pvfactor= ConvergencedecelerationfactorforPVgeneratormodel(Model=3).Defaultis0.1.
Ifthecircuitconvergeseasily,youmaywanttouseahighernumbersuchas1.0.
Usealowernumberifsolutiondiverges.UseDebugtrace=yestocreateafilethat
willtracetheconvergenceofageneratormodel.
Debugtrace={Yes|No}Defaultisno.Turnthisontocapturetheprogressofthegenerator
modelforeachiteration.Createsaseparatefileforeachgeneratornamed
"GEN_name.CSV".
Vminpu= Default=0.95.MinimumperunitvoltageforwhichtheModelisassumedtoapply.
Belowthisvalue,thegeneratormodelrevertstoaconstantimpedancemodel.For
Model7,thisisusedtodeterminetheuppercurrentlimit.Forexample,ifVminpuis
0.90thenthecurrentlimitis(1/0.90)=111%.
Vmaxpu= Default=1.05.MaximumperunitvoltageforwhichtheModelisassumedtoapply.
Abovethisvalue,thegeneratormodelrevertstoaconstantimpedancemodel.
ForceON={Yes|No}ForcesgeneratorONdespiterequirementsofotherdispatchmodes.Stays
ONuntilthispropertyissettoNO,oraninternalalgorithmcancelstheforcedON
state.
Page 138 of 180
OpenDSS Manual
June 2013
kVA=
kVAratingofelectricalmachine.Defaultsto1.2*kWifnotspecified.Appliedto
machineorinverterdefinitionforDynamicsmodesolutions.
MVA=
MVAratingofelectricalmachine.AlternativetousingkVA=.
Xd=
Perunitsynchronousreactanceofmachine.PresentlyusedonlyforThevinen
impedanceforpowerflowcalcsofusermodels(model=6).Typicallyuseavalue
from0.4to1.0.Defaultis1.0
Xdp=
Perunittransientreactanceofthemachine.UsedforDynamicsmodeandFault
studies.Defaultis0.27.Forusermodels,thisvalueisusedfortheThevinen/Norton
impedanceforDynamicsMode.
Xdpp=
Perunitsubtransientreactanceofthemachine.UsedforHarmonics.Defaultis
0.20.
H=
Perunitmassconstantofthemachine.MWsec/MVA.Defaultis1.0.
D=
Dampingconstant.Usualrangeis0to4.Defaultis1.0.Adjusttogetdamping
UserModel=NameofDLLcontaininguserwrittenmodel,whichcomputestheterminalcurrents
forDynamicsstudies,overridingthedefaultmodel.Setto"none"tonegate
previoussetting.
UserData=String(inquotesorparentheses)thatgetspassedtouserwrittenmodelfordefining
thedatarequiredforthatmodel.
ShaftModel=NameofuserwrittenDLLcontainingaShaftmodel,whichmodelstheprime
moveranddeterminesthepowerontheshaftforDynamicsstudies.Models
additionalmasselementsotherthanthesinglemassmodelintheDSSdefault
model.Setto"none"tonegateprevioussetting.
ShaftData=String(inquotesorparentheses)thatgetspassedtouserwrittenshaftdynamic
modelfordefiningthedataforthatmodel.
spectrum=Nameofharmonicvoltageorcurrentspectrumforthisgenerator.Voltagebehind
Xd"formachinedefault.Currentinjectionforinverter.Defaultvalueis"default",
whichisdefinedwhentheDSSstarts.
Basefreq=
Basefrequencyforwhichthisgeneratorisdefined.Defaultis60.0.
Like=
NameofanotherGeneratorobjectonwhichtobasethisone.
Generator Dynamics Model

The Generator object automatically converts into a form of Thevenin equivalent model when
theprogramswitchestoDynamicsmode.Thiswouldoccuronasetmode=dynamicsorsolve
mode=dynamicsstatementaswellaFaultstudymode.Figure27showsthenominalformof
the model for a deltaconnected generator (no zero sequence modeled in the Generator). It
consists of a voltage source behind subtransient reactance, Xd (Xdp property), in the positive
sequence network while the negative sequence is modeled as an impedance using the value
specified for Xd (Xdpp property). The voltage, E1, is computed to approximately match the
positivesequencepowerflowcomputedjustpriortoenteringDynamicsmode.
Themachinedynamicsaregovernedbythetraditionalswingequationsforasinglemass.This
simple model works reasonably well for such analyses as generator infeed to faults, open
conductor simulations, and short DG islanding simulations. The different reactance value for
negativesequenceyieldsamoreaccurateresultforunbalancedcircuitconditionsthanasimple
Page 139 of 180
OpenDSS Manual
June 2013
voltage source behind three singlephase reactances. There are no builtin models for exciter
and governor controls, which would obviously be needed for extended dynamics studies and
microgridsimulations.Nevertheless,thismodelsatisfiesmanyneedsofdistributionplannersfor
evaluatingDGinterconnections.
Xd
Phases
A
Phase
to
Symmetrical
Component
Transformation
Positive
Sequence
EE11

C
Negative
Sequence
Xd
Figure 27. Nominal Generator Model in Dynamics Mode
Whenthezerosequencemustbeincluded,suchasforgroundedwyeconnectedalternators,it
hasbeenfoundthattheOpenDSSperformsbetterbyinsertingaYg/Deltatransformerwiththe
samekVAratinginfrontofthemodelshowninFigure27.Theimpedanceofthetransformeris
settothezerosequenceimpedanceofthemachine,whichistypicallyabout5%orso.Thenthe
Xdp and Xdpp properties are decreased by that amount. The impedance of the transformer
provides a little linear system isolation from the nonlinear machine that assists in the
convergenceofthesolutionalgorithm.
ForGeneratormodel=7,whichistoapproximatethenominalbehaviorofsomeinverterbased
systems,thevaluesspecifiedfortheXdpandXdpppropertiesareactuallyplacedintherealpart
ofthecompleximpedance.Thisyieldsacurrentcontributionfromthegeneratorthatismorein
phase with E1 up to the max current for the model (see Vminpu property above). This
approximates inverters that tend to produce a current in phase with the voltage, and is often
goodenoughforplanningpurposes.
STORAGE O BJECT
Property
Description
%Charge
Chargingrate(inputpower)inPercentofratedkW.Default=100.
%Discharge
Dischargerate(outputpower)inPercentofratedkW.Default=100.
Page 140 of 180
OpenDSS Manual
June 2013

%EffCharge
PercentefficiencyforCHARGINGthestorageelement.Default=90.
%EffDischarge
Percent efficiency for DISCHARGING the storage element. Default =

90.Idlinglossesarehandledby%IdlingkWpropertyandareinaddition
to the charging and discharging efficiency losses in the power
conversionprocessinsidetheunit.
%Idlingkvar
Percent of rated kW consumed as reactive power (kvar) while idling.

Default=0.
%IdlingkW
PercentofratedkWconsumedwhileidling.Default=1.
%R
Equivalent percent internal resistance, ohms. Default is 0. Placed in

serieswithinternalvoltagesourceforharmonicsanddynamicsmodes.
Use a combination of %IdlekW and %EffCharge and %EffDischarge to
accountforlossesinpowerflowmodes.
%reserve
PercentofratedkWhstoragecapacitytobeheldinreservefornormal
operation.
Default=20.
Thisistreatedastheminimumenergydischargelevelunlessthereisan
emergency. For emergency operation set this property lower. Cannot
belessthanzero.
%stored
Presentamountofenergystored,%ofratedkWh.Defaultis100%.
%X
Equivalent percent internal reactance, ohms. Default is 50%. Placed in

serieswithinternalvoltagesourceforharmonicsanddynamicsmodes.
(Limits fault current to 2 pu.) Use %Idlekvar and kvar properties to
accountforanyreactivepowerduringpowerflowsolutions.
basefreq
bus1
Bus to which the Storage element is connected. May include specific

nodespecification.
ChargeTrigger
Dispatchtriggervalueforchargingthestorage.
If=0.0theStorageelementstateischangedbytheStatecommandor
StorageControllerobject.
If<>0theStorageelementstateissettoCHARGINGwhenthistrigger
levelisGREATERthaneitherthespecifiedLoadshapecurvevalueorthe
pricesignalorglobalLoadlevelvalue,dependingondispatchmode.See
Stateproperty.
Page 141 of 180
OpenDSS Manual
June 2013

class
AnarbitraryintegernumberrepresentingtheclassofStorageelement
sothatStoragevaluesmaybesegregatedbyclass.
conn
={wye|LN|delta|LL}.Defaultiswye.
daily
Dispatchshapetousefordailysimulations.Mustbepreviouslydefined
asaLoadshapeobjectof24hrs,typically.Inthedefaultdispatchmode,
theStorageelementusesthisloadshapetotriggerStatechanges.
debugtrace
{Yes|No}Defaultisno.Turnthisontocapturetheprogressofthe
Storage model for each iteration. Creates a separate file for each
Storageelementnamed"STORAGE_name.CSV".
DischargeTrigger
Dispatchtriggervaluefordischargingthestorage.
If=0.0theStorageelementstateischangedbytheStatecommandor
byaStorageControllerobject.
If <> 0 the Storage element state is set to DISCHARGING when this
triggerlevelisEXCEEDEDbyeitherthespecifiedLoadshapecurvevalue
or the price signal or global Loadlevel value, depending on dispatch
mode.SeeStateproperty.
DispMode
{DEFAULT | FOLLOW | EXTERNAL | LOADLEVEL | PRICE } Default =

"DEFAULT".Dispatchmode.
In DEFAULT mode, Storage element state is triggered to discharge or
charge at the specified rate by the loadshape curve corresponding to
thesolutionmode.
In FOLLOW mode the kW and kvar output of the STORAGE element
follows the active loadshape multipliers until storage is either
exhausted or full. The element discharges for positive values and
chargesfornegativevalues.TheloadshapesarebasedonthekWand
kvarvaluesinthemostrecentdefinitionofkWandPForkWandkvar
properties.
InEXTERNALmode,Storageelementstateiscontrolledbyanexternal
Storage controller. This mode is automatically set if this Storage
elementisincludedintheelementlistofaStorageControllerelement.
For the other two dispatch modes, the Storage element state is
controlledbyeithertheglobaldefaultLoadlevelvalueorthepricelevel.
duty
Loadshapetousefordutycycledispatchsimulationssuchasforsolar
ramp rate studies. Must be previously defined as a Loadshape object.
Typically would have time intervals of 15 seconds. Designate the
number of points to solve using the Set Number=xxxx command. If
there are fewer points in the actual shape, the shape is assumed to
Page 142 of 180
OpenDSS Manual
June 2013

repeat.
DynaData
String (in quotes or parentheses if necessary) that gets passed to the

userwritten dynamics model Edit function for defining the data
requiredforthatmodel.
DynaDLL
NameofDLLcontaininguserwrittendynamicsmodel,whichcomputes
the terminal currents for Dynamicsmode simulations, overriding the
defaultmodel.Setto"none"tonegateprevioussetting.ThisDLLhasa
simplerinterfacethantheUserModelDLLandisonlyusedforDynamics
mode.
enabled
kv
Nominalrated(1.0perunit)voltage,kV,forStorageelement.For2and
3phase Storage elements, specify phasephase kV. Otherwise, specify
actual kV across each branch of the Storage element. If wye (star),
specify phaseneutral kV. If delta or phasephase connected, specify
phasephasekV.
kVA
kVAratingofpoweroutput.DefaultstoratedkW.Usedasthebasefor
DynamicsmodeandHarmonicsmodevalues.
kvar
Get/set the present kvar value. Alternative to specifying the power

factor.Sideeffect:thepowerfactorvalueisalteredtoagreebasedon
presentvalueofkW.
kW
Get/setthepresentkWvalue.Apositivevaluedenotespowercoming
OUT of the element, which is the opposite of a Load element. A
negative value indicates the Storage element is in Charging state. This
valueismodifiedinternallydependingonthedispatchmode.
kWhrated
RatedstoragecapacityinkWh.Defaultis50.
kWhstored
Presentamountofenergystored,kWh.DefaultissameaskWhrated.
kWrated
kW rating of power output. Base for Loadshapes when

DispMode=Follow.Sideeffect:SetsKVAproperty.
like
NewStorage.S2like=S1...
model
Integer code (default=1) for the model to use for powet output
variationwithvoltage.Validvaluesare:
1:StorageelementinjectsaCONSTANTkWatspecifiedpowerfactor.
Page 143 of 180
OpenDSS Manual
June 2013
2:StorageelementismodeledasaCONSTANTADMITTANCE.
3:ComputeloadinjectionfromUserwrittenModel.
pf
Nominally, the power factor for discharging (acting as a generator).

Defaultis1.0.
Setting this property will also set the kvar property.Enter negative for
leadingpowerfactor(whenkWandkvarhaveoppositesigns.)
A positive power factor for a generator signifies that the Storage
elementproducesvarsasistypicalforagenerator.
phases
Number of Phases, this Storage element. Power is evenly divided

amongphases.
spectrum
Name of harmonic voltage or current spectrum for this Storage

element. Current injection is assumed for inverter. Default value is
"default",whichisdefinedwhentheDSSstarts.
State
{IDLING | CHARGING | DISCHARGING} Get/Set present operational

state.InDISCHARGINGmode,theStorageelementactsasagenerator
andthe kW propertyispositive.Theelementcontinuesdischargingat
thescheduledoutputpowerleveluntilthestoragereachesthereserve
value. Then the state reverts to IDLING. In the CHARGING state, the
StorageelementbehaveslikeaLoadandthekWpropertyisnegative.
TheelementcontinuestochargeuntilthemaxstoragekWhisreached
and Then switches to IDLING state. In IDLING state, the kW property
showszero.However,theresistiveandreactivelosselementsremainin
thecircuitandthepowerflowreportwillshowpowerbeingconsumed.
TimeChargeTrig
Time of day in fractional hours (0230 = 2.5) at which storage element

willautomaticallygointochargestate.Defaultis2.0.Enteranegative
timevaluetodisablethisfeature.
UserData
String(inquotesorparentheses)thatgetspassedtouserwrittenmodel
fordefiningthedatarequiredforthatmodel.
UserModel
Name of DLL containing userwritten model, which computes the

terminal currents for both power flow and dynamics, overriding the
defaultmodel.Setto"none"tonegateprevioussetting.
Vmaxpu
Default = 1.10. Maximum per unit voltage for which the Model is
assumed to apply. Above this value, the load model reverts to a
constantimpedancemodel.
Vminpu
Default = 0.90. Minimum per unit voltage for which the Model is
assumed to apply. Below this value, the load model reverts to a
Page 144 of 180
OpenDSS Manual
June 2013

constantimpedancemodel.
yearly
Dispatch shape to use for yearly simulations. Must be previously

definedasaLoadshapeobject.Ifthisisnotspecified,theDailydispatch
shape, if any, is repeated during Yearly solution modes. In the default
dispatchmode,theStorageelementusesthisloadshapetotriggerState
changes.
Examples
New storage.JO0235 phases=1 bus1=X_637.1 yearly=Phasealoadshape

~ kV=0.24 kwrated=25 pf=1.0 kwhrated=25
~ state=IDLING DischargeTrigger=0.8 ChargeTrigger=0.6
// 3-phase version
New Storage.Store1 phases=3 Bus1=LVBus kV=0.400 conn=Delta kVA=60
~ kWrated=60 kWHrated=
0.20833 %reserve=50
~ state=discharge
~ kW=50 PF=1
// 1-phase L-L connected version with dynamics DLL
New Storage.Store1 phases=1 Bus1=LVBus.1.2 kV=0.400 conn=delta kVA=60
~ kWrated=60 kWHrated=
0.20833 %reserve=50
~ state=discharge
~ kW=50 PF=1
// connect to user-written dynamics model
~ DynaDLL="C:\Users\prdu001\OpenDSS\Source\DESS1\Dess1.DLL"
~ DynaData=(file=DESSModel_Test.Txt)
Page 145 of 180
OpenDSS Manual
June 2013
Control Elements
One of the distinctive capabilities of the OpenDSS is that control elements are modeled
separatelyfromthepowercarryingelements.Thisprovidessignificantflexibilitytocreatenew
models. Initially, control objects reflected only standard utility distribution system control
devices.Morerecently,new,innovativemodelshavebeendeveloped.Currently,therearenine
controls provided with the program with more planned soon. This section gives some idea of
howthecontrolobjectsworkandhowyoumightexploitthem.
Controlelementsarepolledafterapowerflowsolutionhasbeenobtained.Ifanycontrolneeds
to operate, it places a message on the Control Queue. When it comes time for the control to
operate,themessageispoppedoffthequeueandthecommandexecuted.Thisallowsforthe
simulationofcontrolsthathavetimedelaysintheiroperation.
ThetypicalexecutionoftheSolvecommandforasinglesnapshotpowerflowsolutionis:
1. InitializeSnapshot(_InitSnap)
2. Repeatuntilconverged:
a. SolveCircuit(_SolveNoControl)
b. Samplecontroldevices(_SampleControls)
c. Docontrolactions,ifany(_DoControlActions)
The names in parentheses after the step is the corresponding command (see command
referenceabove)thatyouwoulduseifyouwantedtorollyourownsolutionmethod.
ControlelementstypicallyhaveaSamplefunctionthatsamplesthevoltageandcurrentatthe
terminal that the control is monitoring. Each element of the Control element class also has a
DoPendingAction function that is called from the control queue at the appropriated time. The
Control element then takes the prescribed action or decides that it doesnt need to (as is the
caseformanydistributionsystemcontrols).
RefertotheDocfolderontheOpenDSSwebsiteforadditionalinformation.
C AP C ONTROL O BJECT
The capacitor control monitors the voltage and current at a terminal of a PDelement or a
PCelement and sends switching messages to a Capacitor object. The CapControl contains
essentialfeaturesofmanytypicalutilitycapacitorcontrols.
Example:
New CapControl.C1ctrl element=Line.L1 Capacitor=C1
~ Type=Current ON=400 OFF=300 Delay=30
This control monitors the current in Line.L1 and switches Capacitor.C1 based on current
magnitude.Thisisoneofthesimplercontrolstoimplement.ThecapacitorwillswitchONwhen
the current in the monitored phase (defaults to 1) after a delay of 30 s. If the current drops
below400Abefore30shaselapsed,thecontrolresets(ignoresthemessagefromthecontrol
Page 146 of 180
OpenDSS Manual
June 2013
queue). After energization, the capacitor switches off when the current drops below 300with
thedefaultDelayOFF.
Element
Fullobjectnameofthecircuitelement,typicallyalineortransformer,towhichthe
capacitorcontrol'sPTand/orCTareconnected.Thereisnodefault;mustbe
specified.
Capacitor
NameofCapacitorelementwhichtheCapControlcontrols.NoDefault;Mustbe
specified.Donotspecifythefullobjectname;"Capacitor"isassumedfortheobject
class.Example:
Capacitor=cap1
Type
{Current|voltage|kvar|PF|time}Controltype.SpecifytheONsettingand
OFFsettingappropriatelywiththetypeofcontrol.(SeehelpforONsetting)
CTPhase
NumberofthephasebeingmonitoredforCURRENTcontroloroneof{AVG|MAX|
MIN}forallphases.Default=1.IfdeltaorLLconnection,enterthefirstorthetwo
phasesbeingmonitored[12,23,31].Mustbelessthanthenumberofphases.
Doesnotapplytokvarcontrolwhichusesallphasesbydefault.
CTratio
RatiooftheCTfromlineampstocontrolamperesettingforcurrentandkvar
controltypes.
DeadTime DeadtimeaftercapacitoristurnedOFFbeforeitcanbeturnedbackON.Defaultis
300sec.
Delay
Timedelay,inseconds,fromwhenthecontrolisarmedbeforeitsendsoutthe
switchingcommandtoturnON.Thecontrolmayresetbeforetheactionactually
occurs.Thisisusedtodeterminewhichcapacitycontrolwillactfirst.Defaultis15.
Youmayspecifyanyfloatingpointnumbertoachieveamodelofwhatever
conditionisnecessary.
DelayOFF
Timedelay,inseconds,forcontroltoturnOFFwhenpresentstateisON.Defaultis
15.
EventLog
{Yes/True*|No/False}DefaultisYESforCapControl.Logcontrolactionsto
Eventlog.
OFFsetting ValueatwhichthecontrolarmstoswitchthecapacitorOFF.(Seehelpfor
ONsetting)ForTimecontrol,isOKtohaveOfftimethenextday(<Ontime)
ONsetting ValueatwhichthecontrolarmstoswitchthecapacitorON(orratchetupastep).
TypeofControl:
Current:LineAmps/CTratio
Voltage:LineNeutral(orLineLinefordelta)Volts/PTratio
kvar:Totalkvar,allphases(3phaseforposseqmodel).Thisisdirectional.
PF:PowerFactor,Totalpowerinmonitoredterminal.NegativeforLeading.
Time:HrsfromMidnightasafloatingpointnumber(decimal).7:30amwouldbe
enteredas7.5.
PTPhase
NumberofthephasebeingmonitoredforVOLTAGEcontroloroneof{AVG|MAX|
MIN}forallphases.Default=1.IfdeltaorLLconnection,enterthefirstorthetwo
phasesbeingmonitored[12,23,31].Mustbelessthanthenumberofphases.
Doesnotapplytokvarcontrolwhichusesallphasesbydefault.
Page 147 of 180
OpenDSS Manual
June 2013
PTratio
RatioofthePTthatconvertsthemonitoredvoltagetothecontrolvoltage.Default
is60.IfthecapacitorisWye,the1stphaselinetoneutralvoltageismonitored.
Else,thelinetolinevoltage(1st2ndphase)ismonitored.
terminal
NumberoftheterminalofthecircuitelementtowhichtheCapControlis
connected.1or2,typically.Defaultis1.
VBus
Nameofbustouseforvoltageoverridefunction.Defaultisbusatmonitored
terminal.Sometimesitisusefultomonitorabusinanotherlocationtoemulate
variousDMScontrolalgorithms.
Vmax
Maximumvoltage,involts.Ifthevoltageacrossthecapacitordividedbythe
PTRATIOisgreaterthanthisvoltage,thecapacitorwillswitchOFFregardlessof
othercontrolsettings.Defaultis126(goeswithaPTratioof60for12.47kV
system).
Vmin
Minimumvoltage,involts.Ifthevoltageacrossthecapacitordividedbythe
PTRATIOislessthanthisvoltage,thecapacitorwillswitchONregardlessofother
controlsettings.Defaultis115(goeswithaPTratioof60for12.47kVsystem).
VoltOverride{Yes|No}DefaultisNo.SwitchtoindicatewhetherVOLTAGEOVERRIDEistobe
considered.VmaxandVminmustbesettoreasonablevaluesifthispropertyisYes.
Page 148 of 180
OpenDSS Manual
June 2013
R EG C ONTROL O BJECT
This control is designed to emulate a standard utility voltage regulator or LTC control. It is
attached to a particular winding of a transformer as the winding to monitor. It generally also
adjusts the taps in that winding but could also be directed to control the taps in another
winding.
The control has line drop compensator modeling by setting the R, X, CTprim, and ptratio
properties.ThecontrolcanalsomonitorthevoltageataremotebustoemulatevariousSmart
Griddevices.Thisisausefulfunctionforperformingvolt/varoptimization.
To understand how regulator controls work, refer to W. H. Kerstings book on Distribution
SystemModeling.Asimpleexampleofaregulatorona12.47kVsystem:
New RegControl.Reg1 Transformer=T1 Winding=2 Vreg=122 band=3 ptratio=60
Withalinedropcompensator,thedefinitionmightlooklike
New RegControl.Reg1 Transformer=T1 Winding=2 Vreg=122 band=3
~ ptratio=60 CTprim=300 R=2 X=0
Controllingabusattheendofthefeederto118V:
New RegControl.Reg1 Transformer=T1 Winding=2 Vreg=118 band=2 bus=MyEndBus
transformer NameofTransformerelementtowhichtheRegControlisconnected.Donotspecify
thefullobjectname;"Transformer"isassumedfortheobjectclass.Example:
Transformer=Xfmr1
winding
NumberofthewindingofthetransformerelementthattheRegControlis
monitoring.1or2,typically.SideEffect:SetsTAPWINDINGpropertytothesame
winding.
vreg
Voltageregulatorsetting,inVOLTS,forthewindingbeingcontrolled.Multiplying
thisvaluetimestheptratioshouldyieldthevoltageacrosstheWINDINGofthe
controlledtransformer.Defaultis120.0
band
BandwidthinVOLTSforthecontrolledbus(seehelpforptratioproperty).Default
is3.0
delay
Timedelay,inseconds,fromwhenthevoltagegoesoutofbandtowhenthetap
changingbegins.Thisisusedtodeterminewhichregulatorcontrolwillactfirst.
Defaultis15.Youmayspecifyanyfloatingpointnumbertoachieveamodelof
whateverconditionisnecessary.
ptratio
RatioofthePTthatconvertsthecontrolledwindingvoltagetotheregulator
voltage.Defaultis60.IfthewindingisWye,thelinetoneutralvoltageisused.
Else,thelinetolinevoltageisused.
CTprim
Rating,inAmperes,oftheprimaryCTratingforconvertingthelineampstocontrol
amps.Thetypicaldefaultsecondaryampereratingis0.2Amps(checkwith
manufacturerspecs).
Rsettingonthelinedropcompensatorintheregulator,expressedinVOLTS.
Xsettingonthelinedropcompensatorintheregulator,expressedinVOLTS.
Page 149 of 180

PTphase
OpenDSS Manual
June 2013
Formultiphasetransformers,thenumberofthephasebeingmonitoredoroneof{
MAX|MIN}forallphases.Default=1.Mustbelessthanorequaltothenumberof
phases.Ignoredforregulatedbus.
tapwinding Windingcontainingtheactualtaps,ifdifferentthantheWINDINGproperty.
DefaultstothesamewindingasspecifiedbytheWINDINGproperty.
bus
Nameofabus(busname.nodename)inthesystemtouseasthecontrolledbus
insteadofthebustowhichthetransformerwindingisconnectedortheRandX
linedropcompensatorsettings.Donotspecifythisvalueifyouwishtousetheline
dropcompensatorsettings.Defaultisnullstring.Assumesthebasevoltageforthis
busisthesameasthetransformerwindingbasespecifiedabove.Note:Thisbus(1
phase)WILLBECREATEDbytheregulatorcontroluponSOLVEifnotdefinedby
someotherdevice.Youcanspecifythenodeofthebusyouwishtosample
(defaultsto1).Ifspecified,theRegControlisredefinedasa1phasedevicesince
onlyonevoltageisused.
debugtrace {Yes|No*}Defaultisno.Turnthisontocapturetheprogressoftheregulator
modelforeachcontroliteration.CreatesaseparatefileforeachRegControlnamed
"REG_name.CSV".
EventLog
{Yes/True*|No/False}DefaultisYESforregulatorcontrol.Logcontrolactionsto
Eventlog.
inversetime {Yes|No*}Defaultisno.Thetimedelayisadjustedinverselyproportionaltothe
amountthevoltageisoutsidethebanddownto10%.
maxtapchange
MaximumallowabletapchangepercontroliterationinSTATICcontrol
mode.Defaultis16.
Setthisto1tobetterapproximateactualcontrolaction.
Setthisto0tofixthetapinthecurrentposition.
revband
Bandwidthforoperatinginthereversedirection.
revDelay
TimeDelayinseconds(s)forexecutingthereversingactiononcethethresholdfor
reversinghasbeenexceeded.Defaultis60s.
reversible
{Yes|No*}Indicateswhetherornottheregulatorcanbeswitchedtoregulatein
thereversedirection.DefaultisNo.Typicallyappliesonlytolineregulatorsandnot
toLTConasubstationtransformer.
revNeutral {Yes|No*}Defaultisno.SetthistoYesifyouwanttheregulatortogotoneutralin
thereversedirection.
revR
Rlinedropcompensatorsettingforreversedirection.
revThreshold
kWreversepowerthresholdforreversingthedirectionofthe
regulator.Defaultis100.0kw.
revvreg
Voltagesettinginvoltsforoperationinthereversedirection.
revX
Xlinedropcompensatorsettingforreversedirection.
tapdelay
Delayinsecbetweentapchanges.Defaultis2.Thisishowlongittakesbetween
changesafterthefirstchange.
TapNum
Anintegernumberindicatingthetappositionthatthecontrolledtransformer
windingtappositioniscurrentlyat,orisbeingsetto.Ifbeingset,andthevalueis
outsidetherangeofthetransformerminormaxtap,thensettotheminormaxtap
Page 150 of 180
OpenDSS Manual
June 2013
positionasappropriate.Defaultis0,whichistheneutraltap.Aconventional32
stepregulatorhasarangefrom16(Lower)to16(Raise).Withtap0,thereare
actually33taps.Youcanquerythetappositionasfollows:
?RegControl.MyRegulator.TapNum
TheresultwillgointotheResultwindoworinterface.
vlimit
VoltageLimitforbustowhichregulatedwindingisconnected(e.g.firstcustomer).
Defaultis0.0.Settoavaluegreaterthenzerotoactivatethisfunction.
Page 151 of 180
OpenDSS Manual
June 2013
Meter Elements
E NERGY M ETER O BJECT
AnEnergyMeterobjectisanintelligentmeterconnectedtoaterminalofacircuitelement.It
simulatesthebehaviorofanactualenergymeter.However,ithasmorecapabilitybecauseit
canaccessvaluesatotherplacesinthecircuitratherthansimplyatthelocationatwhichitis
installed.Itmeasuresnotonlypowerandenergyvaluesatitslocation,butlossesandoverload
valueswithinadefinedregionofthecircuit.
Theoperationoftheobjectissimple.Ithasseveralregistersthataccumulatecertainvalues.At
the beginning of a study, the registers are cleared (reset) to zero. At the end of each
subsequent solution, the meter is instructed to take a sample. Energy values are then
integratedusingtheintervaloftimethathaspassedsincetheprevioussolution.
Registers
Therearetwotypesofregisters:
1. EnergyAccumulators(forenergyvalues)
2. Maximumpowervalues("draghand"registers).
The energy registers may use trapezoidal integration (system option), which allows for
somewhat arbitrary time step sizes between solutions with less integration error. This is
importantforusingloaddurationcurvesapproximatedwithstraightlines,forexample.
Thepresentdefinitionsoftheregistersare,forexamplefora22kVsystem:
Hour
"kWh"
"kvarh"
"MaxkW"
"MaxkVA"
"ZonekWh"
"Zonekvarh"
"ZoneMaxkW"
"ZoneMaxkVA"
"OverloadkWhNormal"
"OverloadkWhEmerg"
"LoadEEN"
"LoadUE"
"ZoneLosseskWh"
"ZoneLosseskvarh"
"ZoneMaxkWLosses"
"ZoneMaxkvarLosses"
"LoadLosseskWh"
"LoadLosseskvarh"
"NoLoadLosseskWh"
"NoLoadLosseskvarh"
"MaxkWLoadLosses"
"MaxkWNoLoadLosses"
"LineLosses"
"TransformerLosses"
"LineModeLineLosses"
"ZeroModeLineLosses"
Page 152 of 180
OpenDSS Manual
June 2013
"3-phaseLineLosses"
"1-and2-phaseLineLosses"
"GenkWh"
"Genkvarh"
"GenMaxkW"
"GenMaxkVA"
"22kVLosses"
"Aux1"
"Aux6"
"Aux11"
"Aux16"
"Aux21"
"Aux26"
"22kVLineLoss"
"Aux2"
"Aux7"
"Aux12"
"Aux17"
"Aux22"
"Aux27"
"22kVLoadLoss"
"Aux3"
"Aux8"
"Aux13"
"Aux18"
"Aux23"
"Aux28"
"22kVNoLoadLoss"
"Aux4"
"Aux9"
"Aux14"
"Aux19"
"Aux24"
"Aux29"
"22kVLoadEnergy"
"Aux5"
"Aux10"
"Aux15"
"Aux20"
"Aux25"
"Aux30"
Registersarefrequentlyaddedforvariouspurposes.Youcanviewthepresentmeterssimplyby
solvingandtakingasample.ThenexecuteaShowMeterscommand.TheAuxregisterslistedin
the example above are used for keep track of losses at up to 7 different voltage levels in the
meterzone.
Meter Zones
TheEnergyMeterobjectusestheconceptofazone.Thisisanareaofthecircuitforwhichthe
meter is responsible. It can compute energies, losses, etc for any power delivery object and
Loadobjectinitszone(Generatorobjectshavetheirownintrinsicmeters).
Azoneisacollectionofcircuitelements"downline"fromthemeter.Thisconceptisnominally
applicable to radial circuits, but also has some applicability to meshed circuits. The zones are
automaticallydeterminedaccordingtothefollowingrules:
Startwiththecircuitelementinwhichthemeterislocated.Ignoretheterminalonwhichthe
Page 153 of 180
OpenDSS Manual
June 2013
meter is connected. This terminal is the start of the zone. Begin tracing with the other
terminal(s).
(Note:Theserulesimplythatthemetershouldusuallybeplacedatthesourceendofthecircuit
elementitismonitoring.)
Trace out the circuit, finding all other circuit elements (loads and power delivery elements)
connectedtothezone.Continuetracingouteverybranchofthecircuit.Stoptracingabranch
when:
Theendofthecircuitbranchisreached
AcircuitelementcontaininganotherEnergyMeterobjectisencountered
AnOPENterminalisencountered.(allphasesintheterminalareopen.)
Adisableddeviceisencountered.
Acircuitelementalreadyincludedinanotherzoneisencountered.
Therearenomorecircuitelementstoconsider.
ZonesareautomaticallyupdatedafterachangeinthecircuitunlesstheZONELOCKoption(Set
command)issettotrue(Yes).Thenzonesremainfixedafterinitialdetermination.
InordertoapplytheReconductorcommand,bothlinesmustbeinthesamemeterzone.The
upline/downline orientation of the line segments is established when the zones are built.
Otherwise,theDSShasnoconceptofradiality.
TheParentpropertyavailableintheLinesinterfaceintheCOMinterfaceissetwhenthezoneis
established. This allows users to programmatically trace back up the circuit toward the
Energymeter. The total number of customers served downline is determined during the
establishmentofthemeterzone.
Zones on Meshed Networks

While the concept of zones nominally applies to radial circuits, judicious placement of energy
meterscanmaketheconceptusefulformeshednetworksaswell.Keepinmindthattherecan
bemanyEnergyMeterobjectsdefinedinthecircuit.Theirplacementdoesnotnecessarilyhave
torepresentreality;theyareforthereportingofpowerandenergyquantitiesthroughoutthe
system.
The automatic algorithm for determining zones will determine zones consistently for meshed
networks,althoughthezonesthemselvesmaynotberadial.Ifthereareseveralmetersonthe
networkthatcouldbemonitoringthesamezone,thefirstonedefinedwillhaveaccesstoallthe
elementsexcepttheonescontainingtheothermeters.Theotherswillhaveonlyoneelement
intheirzone,asinFigure14.
Page 154 of 180
OpenDSS Manual
June 2013
METER ZONE 2
METER ZONE 1
METER ZONE 3
Figure 28. Default Meter Zones for a Simple Network
Don't put any load at tie point or take care in processing meter information so that it isn't
counted more than once. All three of the meters added would see the centermost bus in
Figure15.
METER ZONE 2
METER ZONE 1
METER ZONE 3
Figure 29. Using Additional Meters to Control the Definition of Meter Zones
Sampling
Thesamplingalgorithmsareasfollows:
Local Energy and Power Values: Simply compute the power into the terminal on which the
meter is installed and integrate using the interval between the present solution and the
previous solution. This operation uses the voltage and current computed from the present
solution.
Page 155 of 180
OpenDSS Manual
June 2013
LossesinZone:AccumulatethekWlossesineachpowerdeliveryelementinthezone.
LoadinZone:Whilesamplingthelossesineachpowerdeliveryelement,accumulatethepower
inallloadsconnectedtothedownlinebus(es)oftheelement.
OverloadEnergyinZone:Foreachpowerdeliveryelementinthezone,computetheamountof
powerexceedingtheratingoftheelementcomparedtobothnormalandemergencyratings.
EEN and UE in Zone: For each load in the zone marked as exceeding normal or unserved,
computethepresentpower.Integratetogetenergies.
EEN and UE Definitions

EENreferstoloadenergyconsideredunservedbecausethecurrentorvoltageexceedsNormal
ratings.UEreferstoloadenergyconsideredunservedbecausethepower(actuallythecurrent)
exceedsEmergency,ormaximum,ratings.
On radial systems (default), a load is marked as unserved with respect to either normal or
emergencyratingsifeither:
Thevoltageattheloadbusisbelowminimumratings
Thecurrentinanypowerdeliveryelementsupplyingtheloadexceedsthecurrentratings.
Eithertheentireloadorjusttheportionaboveratingatthebusthatisconsideredunservedis
counted as unserved, depending on whether the Excess option or the Total option have been
specified.
EnergyMeter EEN and UE Registers

Register9through12ontheEnergyMeterareconfusingtobothnewandexperiencedOpenDSS
users.Hopefully,thisexplanationwillhelpshedsomelightonthecontentsoftheseregisters.
EEN = Energy Exceeding Normal: The energy served over a selected period of time above the
Normalratingofpowerdeliverydevices(lines,transformers,switches,etc.).Itisassumedthat
there is sufficient engineering margin in the power system to continue to operate, but that a
failure (1st contingency) will require curtailment of load. This is the primary quantity used for
measureofrisk.
UE = Unserved Energy: The energy over a selected period of time projected to be above the
Emergency,orMaximum,ratingofpowerdeliveryequipment.Itisassumedthatsomeloadwill
havetobecurtailedtobringthepowerdowntoamanageablelevel.
Theseconceptshaveevolvedsince1994aswebegantolookforsomemeanstomeasureriskin
planning,particularlyasitappliestodistributedgeneration.Wequicklylearnedthatdistribution
plannerswerenotcomfortablewithpureprobabilisticplanning.Theyprefermethodsbasedon
concretelimits.Therefore,weadaptedsometraditionalplanningconceptstoachieveameasure
of risk. Many traditional methods used two limits for power delivery equipment: Normal and
Emergency. Planning studies are triggered when the peak demand exceeds the Normal limits.
Exceeding the Emergency limit requires immediate curtailment. The usual intent was to get
something built before the Emergency limit was projected to be exceeded. By using power
Page 156 of 180
OpenDSS Manual
June 2013
demand alone, new construction is frequently very conservative. Distributed generation

muddies the waters for planning with demand alone because it is often unclear how much
capacityisactuallyachievedbyDG.
Ourextensionoftheconceptwastouseenergyinadditiontosimplypowertodeterminethe
risk.Onewoulddeferinvestinginnewinfrastructureuntiltheenergyexceedingthelimitswas
sufficienttojustifyit.
Formoreonthissubject,seethefollowingpapersforreferenceonthissubject:
R. C. Dugan, Computing Incremental Capacity Provided By Distributed Resources For
DistributionPlanning,IEEEPESGeneralMeeting,2007.
RogerDuganandMarekWaclawiak,UsingEnergyasaMeasureofRiskinDistribution
Planning,Paper0822,CIRED2007,Vienna.
Registers 9 and 10: Overload EEN and UE

As the Energymeter element sweeps through its zone, it queries each series power delivery
element encountered for the kW above Normal and Emergency limits. The value recorded in
these two registers is the largest kW amount encountered. In other words, the value is the
maximumoverloadintermsofactualkW.
Mostofthetime,thisiswhatyouwant.However,therearecaseswheredataerrorscanskew
theresults.Forexample,ifthedatashowa15kVAtransformerservinganapartmentbuilding
withover150kVAload,thiswillconsistentlyshowupasa135kVAoverload,whichmightbethe
largestoverloadintheproblem.However,youwouldnotbuildanewfeederbecauseasmall
transformer is overloaded. You would change out the transformer (or correct the data error).
Such errors are common in distribution data where it may take a while for transformer
changeoutstogetproperlyentered.
Excess or Total: There are two ways these registers can record the results. They can simply
recordtheexcesskWoverthelimits.Thisisthedefaultbehavior.However,theycanalsorecord
thetotalkWflowingthroughtheelement.Thelattermethodisforcaseswhereitisassumed
thatthefeederbranchinquestionmustbeswitchedoffcompletelyifanoverloadoccurs.This
reflectsamoreconservativeplanningapproach.
Registers11and12:LoadEENandUE
ThesetworegistersrecordadifferentapproachtocomputeEENandUEvalues:Theyaskeach
Loadelementinthezoneifitisunserved.Thenominalcriterionisundervoltage.
IfyousetOption=VoltageforanEnergymeterobject,onlythevoltageisused.Theglobaloptions
NormVminpuandEmergVminpuareusedforthisvalue.IfthevoltageisbetweenNormVminpu
and EmergVminpu, the EEN is proportioned to how far below the NormVminpu it is. If the
voltageislessthanEmergVminpu,theUEvaluefortheloadiscomputedinproportiontothe
degeeitisbelowEmergVminpu,continuingonthesameslopeastheEENcalculation.Inmulti
phaseelements,thelowestphasevoltageisused.
Thedefaultbehavior(Option=Combined)istoconsiderbothlineoverloadandundervoltage.Ifa
Page 157 of 180
OpenDSS Manual
June 2013
line, or other power delivery element, serving the load is overloaded, the load is considered
unserved in the same percentage that the line is overloaded. This actually takes precedence
over the voltage criteria, which assumes that any undervoltage is due to the line overload. A
line is considered to serve the load if it is between the EnergyMeter and the load. Note that
someinaccuraciescanoccurifthemeterzoneisnotproperlydefined,suchasifloopsexist.
Properties
Element=
Nameofanexistingcircuitelementtowhichthemonitoristobeconnected.Note
thattheremaybemorethanonecircuitelementwiththesamename(notwise,
butitisallowed).Themonitorwillbeplacedatthefirstonefoundinthelist.
Terminal= No.oftheterminaltowhichthemonitorwillbeconnected,normallythesource
end.
Action=
Optionalactiontoexecute.Oneof
Clear=resetallregisterstozero
Save=Saves(appends)thepresentregistervaluestoafile.FilenameisMTR_metername.CSV,
wheremeternameisthenameoftheenergymeter.
Take=Takesasampleatthepresentsolution.
Option=
Options:EnterastringARRAYofanycombinationofthefollowing.Options
processedlefttoright:
(E)xcess:(default)UE/EENisestimateofonlyenergyexceedingcapacity
(T)otal:UE/EENistotalenergyaftercapacityexceeded.
(R)adial:(default)Treatszoneasaradialcircuit
(M)esh:Treatszoneasmeshednetwork(notradial).
(C)ombined:(default)LoadUEorEENarecomputedfrombothoverloadandundervoltage
criteria.
(V)oltage:LoadUE/EENarecomputedonlyfromtheundervoltagecriteria.
Example:option=(E,R,C)
Inameshednetwork,theoverloadregistersrepresentthetotalofthepowerdeliveryelement
overloads and the load UE/EEN registers will contain only those loads that are "unserved",
which are those with low voltages. In a radial circuit, the overload registers record the max
overload (absolute magnitude, not percent) in the zone. Loads become unserved either with
lowvoltageorifanylineintheirpathtothesourceisoverloaded.
KWNorm=UpperlimitonkWloadinthezone,Normalconfiguration.Defaultis0.0(ignored).If
specified,overrideslimitsonindividuallinesforoverloadEEN.KWabovethislimit
fortheentirezoneisconsideredEEN.
KWEmerg=UpperlimitonkWloadinthezone,Emergencyconfiguration.Defaultis0.0
(ignored).Ifspecified,overrideslimitsonindividuallinesforoverloadUE.KWabove
thislimitfortheentirezoneisconsideredUE.
Peakcurrent=ARRAYofcurrentmagnitudesrepresentingthepeakcurrentsmeasuredatthis
locationfortheloadallocationfunction(forloadsdefinedwithxfkva=).Defaultis
Page 158 of 180
OpenDSS Manual
June 2013
(400,400,400).Enteronecurrentforeachphase.
Zonelist= ARRAYoffullelementnamesforthismeter'szone.Defaultisformetertofindit's
ownzone.Ifspecified,DSSusesthislistinstead.Itcanaccessthenamesinasingle
columntextfile.Examples:
zonelist=[line.L1,transformer.T1,Line.L3]
zonelist=(file=branchlist.txt)
LocalOnly={Yes|No}DefaultisNO.IfYes,meterconsidersonlythemonitoredelementfor
EENandUEcalcs.Useswholezoneforlosses.
Mask=
Maskforaddingregisterswheneverallmetersaretotalized.Arrayoffloatingpoint
numbersrepresentingthemultipliertobeusedforsummingeachregisterfromthis
meter.Default=(1,1,1,1,...).Youonlyhavetoenterasmanyasarechanged
(positional).Usefulwhentwometersmonitorsameenergy,etc.
Losses=
{Yes|No}DefaultisYES.ComputeZonelosses.IfNO,thennolossesatallare
computed.
LineLosses={Yes|No}DefaultisYES.ComputeLinelosses.IfNO,thennoneofthelinelosses
arecomputed.
XfmrLosses={Yes|No}DefaultisYES.ComputeTransformerlosses.IfNO,transformersare
ignoredinlosscalculations.
SeqLosses={Yes|No}DefaultisYES.ComputeSequencelossesinlinesandsegregatebyline
modelossesandzeromodelosses.
3PhaseLosses={Yes|No}DefaultisYES.ComputeLinelossesandsegregateby3phaseand
other(1and2phase)linelosses.
VbaseLosses={Yes|No}DefaultisYES.Computelossesandsegregatebyvoltagebase.IfNO,
thenvoltagebasedtabulationisnotreported.Makesurethevoltagebasesofthe
busesareassignedBEFOREdefiningtheEnergyMetertoensurethatitwill
automaticallypickupthevoltagebases.Or,issuetheCalcVoltageBasescommand
afterdefiningtheEnergyMeter.Eachvoltagebasehasfour(4)lossregisters:total,
line,load,andnoload,respectively.Therearesufficientregisterstoreportlossesin
five(5)differentvoltagelevels.
BaseFreq=Basefrequencyforratings.
Enabled= {Yes|NoorTrue|False}Indicateswhethertheelementisenabled.
Like=
NameofanotherEnergyMeterobjectonwhichtobasethisone.
Page 159 of 180
OpenDSS Manual
June 2013
M ONITOR O BJECT
Amonitorisabenigncircuitelementthatisconnectedtoaterminalofanothercircuitelement.
It takes a sample when instructed, recording the time and the complex values of voltage and
current,orpower,atallphases.Otherquantitiesmaybesaveddependingonthesettingofthe
Mode property. The data are saved in a file stream (a separate one for each monitor) at the
conclusion of each step of a multistep solution (e.g., daily or yearly, or harmonics) or each
solutioninaMonteCarlocalculation.Inessence,itworkslikearealpowermonitor.Thedata
in the file may be converted to CSV form and, for example, brought into Excel. You may
accomplishthisbyeithertheShowMonitorcommandortheExportMonitorcommand.
ForMonteCarloruns,thehourissettothenumberofthesolutionandsecondsissettozero.
ForHarmonicsolutions,thefirsttwofieldsarechangedtoFrequencyandHarmonic.
Monitorsmaybeconnectedtobothpowerdeliveryelementsandpowerconversionelements.
Parameters,inorder,are:
Element=
Nameofanexistingcircuitelementtowhichthemonitoristobeconnected.Note
thattheremaybemorethanonecircuitelementwiththesamename(notwise,
butitisallowed).Themonitorwillbeplacedatthefirstonefoundinthelist.
Terminal= No.oftheterminaltowhichthemonitorwillbeconnected.
Mode=
Integerbitmaskcodetodescribewhatitisthatthemonitorwillsave.Monitorscan
savetwobasictypesofquantities:1)Voltageandcurrent;2)Power.TheMode
codesaredefinedasfollows:
0:StandardmodeVandI,eachphase,complex
1:Powereachphase,complex(kwandkvars)
2:Transformertaps(connectMonitortoatransformerwinding)
3:Statevariables(connectMontortoaPCElement)
+16:Sequencecomponents:V012,I012
+32:Magnitudeonly
+64:PosSeqonlyorAverageofphases,ifnot3phases
Forexample,Mode=33willsavethemagnitudeofthepower(kVA)onlyineach
phase.Mode=112savesPositivesequencevoltagesandcurrents,magnitudesonly.
Action=
{clear|save}parsingofthispropertyforcesclearingofthemonitor'sbuffer,or
savingtodisk.
ThenameofthefilecreatedappearsintheResultwindow.
Page 160 of 180
OpenDSS Manual
June 2013
Page 161 of 180
OpenDSS Manual
June 2013
Default Circuit
When a new circuit is instantiated, it is created as a 3phase voltage source named "Source"
connectedtoabusnamed"SourceBus"withareasonableshortcircuitstrengthfortransmission
systemsfeedingdistributionsubstations.
Source
SourceBus
Figure 30. Default Circuit
Thedefaultvaluesforthesourceare(seeVsourceobjectdefinition):
115kV
3000MVAshortcircuit
Thus,thecircuitcanbeimmediatelysolved,albeitwithatrivialresult.
Thecircuitisalsoimmediatelyavailableforaddingasubstationand/orlinesforaquickmanual
circuitmodelingtask.
Thedefaultcircuitmodeldoesnotincludeasubstationtransformerbecausetheusermaywish
tostudymorethanonesubstationconnectedbyanontrivialtransmissionorsubtransmission
network.
Page 162 of 180
OpenDSS Manual
June 2013
Examples
E XAMPLE C IRCUIT 1
Subbus
LoadBus1
10 000 ft
115 kV
12.47 kV
LoadBus2
LoadBus3
10 000 ft
1000 kW
Monitor
Locations
Regbus
20 000 ft
Regulator
500 kW
600 kvar
336 MCM ACSR
(Untransposed)
Wind Gen
8 MW
DSS Circuit Description Script

new object=circuit.DSSLLibtestckt
~ basekv=115 1.00 0.0 60.0 3 20000 21000 4.0 3.0
new
~
.94
new
~
.94
new
~
!edit the voltage source
loadshape.day 24 1.0
mult=(.3 .3 .3 .35 .36 .39 .41 .48 .52 .59 .62 .94 .87 .91 .95 .95 1.0 .98
.92 .61 .60 .51 .44)
loadshape.year 24 1.0 ! same as day for now
mult=".3 .3 .3 .35 .36 .39 .41 .48 .52 .59 .62 .94 .87 .91 .95 .95 1.0 .98
.92 .61 .60 .51 .44"
loadshape.wind 2400 0.00027777
! unit must be hours 1.0/3600.0 = .0002777
csvfile=zavwind.csv action=normalize ! wind turbine characteristi
! define a linecode for the lines - unbalanced 336 MCM ACSR connection
new linecode.336matrix nphases=3
! horizontal flat construction
~ rmatrix=(0.0868455 | 0.0298305 0.0887966 | 0.0288883 0.0298305 0.0868455)
! ohms per 1000 ft
~ xmatrix=(0.2025449 | 0.0847210 0.1961452 | 0.0719161 0.0847210 0.2025449)
~ cmatrix=(2.74 | -0.70 2.96| -0.34 -0.71 2.74) !nf per 1000 ft
~ Normamps = 400 Emergamps=600
! Substation transformer
new transformer.sub phases=3 windings=2 buses=(SourceBus subbus) conns='delta
wye' kvs="115 12.47 " kvas="20000 20000" XHL=7
! define the lines
new line.line1 subbus
loadbus1 linecode=336matrix length=10
new line.line2 loadbus1 loadbus2 336matrix 10
new line.line3 Loadbus2 loadbus3 336matrix 20
! define a couple of loads
new load.load1 bus1=loadbus1 phases=3 kv=12.47 kw=1000.0 pf=0.88 model=1
class=1 yearly=year daily=day status=fixed
new load.load2 bus1=loadbus2 phases=3 kv=12.47 kw=500.0 pf=0.88 model=1 class=1
yearly=year daily=day conn=delta status=fixed
Page 163 of 180
OpenDSS Manual
June 2013
! Capacitor with control

new capacitor.C1 bus1=loadbus2 phases=3 kvar=600 kv=12.47
new capcontrol.C1 element=line.line3 1 capacitor=C1 type=current ctratio=1
ONsetting=60 OFFsetting=55 delay=2
! regulated transformer to DG bus
new transformer.reg1 phases=3 windings=2
~
buses=(loadbus3 regbus)
~
conns='wye wye'
~
kvs="12.47 12.47"
~
kvas="8000 8000"
~
XHL=1
!tiny reactance for a regulator
! Regulator Control definitions
new regcontrol.sub transformer=sub winding=2 vreg=125 band=3 ptratio=60
delay=10
new regcontrol.reg1 transformer=reg1 winding=2 vreg=122 band=3 ptratio=60
delay=15
! define a wind generator of 8MW
New generator.gen1
bus1=regbus kV=12.47 kW=8000 pf=1 conn=delta duty=wind
Model=1
! Define some monitors so's we can see what's happenin'

New Monitor.gen1a element=generator.gen1 1
mode=48
New Monitor.line3 element=line.line3 1
mode=48
New Monitor.gen1 element=generator.gen1 1 mode=32
! Define voltage bases so voltage reports come out in per unit
Set voltagebases="115 12.47 .48"
Calcv
Set controlmode=time
Set mode=duty number=2400
hour=0
h=1.0 sec=0
! Mode resets the monitors
Page 164 of 180
OpenDSS Manual
June 2013
E XAMPLE C IRCUIT 2
Subbus
F1-1
15 000 ft
115 kV
FAULT
(all types)
15 000 ft
15 000 ft
480 V
Y-Y
1000 kW
F2-1
12.47 kV
F1-3
F1-2
F2-2
F2-3
Delta-Y
Monitor
Locations
1000 kW
F3-1
F3-3
F3-2
Delta-Delta
1000 kW
DSS Circuit Description Script

new object=circuit.DSSLLibtestckt
~ basekv=115 1.00 0.0 60.0 3 20000 21000 4.0 3.0
!edit the voltage source
! define a linecode for the lines - unbalanced 336 MCM ACSR connection
new linecode.336matrix nphases=3
! horizontal flat construction
~ rmatrix=(0.0868455 | 0.0298305 0.0887966 | 0.0288883 0.0298305 0.0868455)
! ohms per 1000 ft
~ xmatrix=(0.2025449 | 0.0847210 0.1961452 | 0.0719161 0.0847210 0.2025449)
~ cmatrix=(2.74 | -0.70 2.96| -0.34 -0.71 2.74) !nf per 1000 ft
~ Normamps = 400 Emergamps=600
! Substation transformer
new transformer.sub phases=3 windings=2 buses=(SourceBus subbus) conns='delta
wye' kvs="115 12.47 " kvas="20000 20000" XHL=7
! define the lines
(Make sure they have unique names!)
! Feeder 1
new line.line1-1 subbus
new line.line1-2 F1-1
F1-1 336matrix 15
F1-2 336matrix 15
F1-3 336matrix 15
! Feeder 2
F2-1 336matrix 15
F2-2 336matrix 15
F2-3 336matrix 15
! Feeder 3
F3-1 336matrix 15
F3-2 336matrix 15
Page 165 of 180
OpenDSS Manual
June 2013

F3-3 336matrix 15
! Define 3 transformer of different connections on each feeder midpoint

new transformer.TR1 phases=3 windings=2
~
buses=(F1-2 Genbus1)
~
conns='wye wye'
~
kvs="12.47 0.48"
~
kvas="5000 5000"
~
XHL=6
~
~
conns='delta wye'
~
kvs="12.47 0.48"
~
kvas="5000 5000"
~
XHL=6
~
~
conns='delta delta'
~
kvs="12.47 0.48"
~
kvas="5000 5000"
~
XHL=6
! put some loads on the transformers
new load.load1 bus1=Genbus1 phases=3 kv=0.48 kw=1000.0 pf=0.88 model=1
conn=delta
! Define monitors at the secondary buses to pick up voltage magnitudes

New Monitor.TR1 element=Transformer.TR1 2
mode=32
mode=32
mode=32
! Define voltage bases so voltage reports come out in per unit

Set voltagebases="115 12.47 .48"
Calcv
! define all kinds of faults at one bus (will be moved later)
! in Monte Carlo Fault mode, only one will be chosen at a time
New Fault.F1
bus1=F1-1.1 phases=1 r=2
New Fault.F2
New Fault.F3
New Fault.FALL bus1=F1-1
phases=3 r=2
New Fault.F12 bus1=F1-1.1 bus2=F1-1.2 phases=1 r=2
New Fault.F23 bus1=F1-1.2 Bus2=F1-1.3 phases=1 r=2
Set loadmodel=a
Set Toler=0.001 Random=uniform
Page 166 of 180
OpenDSS Manual
June 2013
COM Interface Reference

Whilealotcanbedonewiththestandardtextscriptinginterface,knowledgableuserscanopen
up an entirely new world of applications by learning to effectively use the COM interface.
AlgorithmscanbeimplementedinanothercomputerprogramandusedtodrivetheOpenDSS
to do something that is not currently implemented within it. An example would be a specific
optimizationalgorithm.OnlyafewsimpleonesarecurrentlyimplementedinsideOpenDSS,but
externalonesofgreatcomplexitycanbewritten.ThealgorithmswouldrelyontheOpenDSSto
representthebehaviourofthedistributionsystemwhileadjustingwhatevervariablesarebeing
optimized.
OnegooduseoftheCOMinterfaceistocreateloopingscripts.Thereisnoloopingcapabilitiesin
the OpenDSS scripting language. The closest thing is the Next command, which can simplify
scriptsthatincrementtime.Eveniftherewerealoopingcapability,itwouldexecuterelatively
slowly because it would be interpreted. Looping scripts are relatively easy to write in other
languagesandtheygenerallyrunquickly.
DocumentationoftheOpenDSSCOMinterfaceshavelaggedbehindtheimplementations.This
isonereasontheprogramhasbeenmadeopensource.Iftheuseofaninterfaceisnotobvious
fromitsnameorwithexperimentation,theusercanviewthesourcecodeanddeterminewhat
theinterfacefunctionorpropertywilldowheninvoked.Thecodebehindtheimplementationof
theinterfacesmaybefoundinfilesnamedImplxxxx.pasintheSource\DLLfolder,wherexxxxis
thenameoftheinterface.SomeinterfacedocumentationmaybefoundintheDOCfolder,with
thecaveatthateventhesemightbeoutofdatesincefunctions(methods)andpropertiesmay
beaddedatanytime.TheWikihasadditionalinformation.
Thereareseveralchoicesfortoolsthatcanprovidedocumentationofthetypelibrary(TLB)for
theCOMinterface.MostuserswillhaveatleastoneoftheMicrosoftOfficeprogramsontheir
computer.SinceCOMisaMicrosoftinvention,theVBAdevelopersupportfortheseprogramsis
prettygoodforexposingtheclasses,properties,andmethodsintheTLBtotheuser.Theyhave
code completion, which is useful for developing code that must access the OpenDSS COM
interfaces.SoftwarelikeMATLABisnotgenerallyashelpful.Someuserswilllayouttheircodein
VBA first and then paste it into the MATLAB editor. Another strategy is to obtain one of a
numberofTLBdocumentersandexecuteitontheOpenDSSEngine.DLLfile.
WewilldocumenttheDSSinterfacehereandthenprovidesomeexamplesofwritingcodefor
driving the OpenDSS program. The DSS interface is the only one that you must instantiate to
starttheprogram.Thereareseveralotherinterfaces,allcreatedwhentheStartfunctionofthe
DSSinterfaceisexecuted.
The most important of the other interfaces is probably the Circuit class interface. This is
documentedinthefilenamedOpenDSSCircuitInterface.Bothadocfileandapdffileareonthe
OpenDSSwebsite.
BesidessettingvariablesfortheDSSobjectitself,itiscommontoalsodefinespecificvariables
fortheTextinterfaceandtheCircuitinterface.Forexample,inVBA:
Option Explicit
Page 167 of 180
OpenDSS Manual
June 2013
Declare variables
Public DSSobj As OpenDSSengine.DSS
Public DSSText As OpenDSSengine.Text
Public DSSCircuit As OpenDSSengine.Circuit
' Create a new instance of the DSS

Set DSSobj = New OpenDSSengine.DSS
DSSObj.Start(0)
' Assign a variable to the Text interface for easier access
Set DSSText = DSSobj.Text
' Assign a variable to the Circuit interface for easier access
Set DSSCircuit = DSSobj.ActiveCircuit
DSS I NTERFACE
Assume DSSObj is an object defined as type OpenDSSEngine.DSS. Then the methods and
propertiesoftheDSSinterfaceareasdescribedbelow:
bOK = DSSObj.Start(0)
Start is a function that returns a Boolean value indicating success in starting the
OpenDSS.
(InsertDSSObj.infrontofeachpropertynamebelow.)
ActiveCircuit
ReturnsatypeCircuitinterfacethatpointstotheactivecircuit.Thisisoneofthemost
used interface and a variable in the users program is often set to this interface to
simplifyprogramming.Forexample,inVBA:
Set DSSCircuit = DSSObj.ActiveCircuit
ActiveClass
Returns a type ActiveClass interface to the class of the active element in the present
problem.Thisinterfaceisbasicallyforreportingthenamesoftheclassesinthepresent
versionoftheprogram.
AllowForms
Thispropertyisusedtosuppressmessageformsfrompoppingupduringtheexecution
oftheusersprogram.SetthistoFalsetosuppressforms.CannotbesetbacktoTrue.
Circuits
Thisinterfaceisprovidedforfutureusewhentheprogramcansupportmorethanone
circuitobjectinmemoryatatime.Currently,thisisnotallowed.
Classes
VariantarraycontainingalistofintrinsicOpenDSSclassnames.
ClearAll
Executingthisfunctionclearsallcircuitparametersfrommemory.
Page 168 of 180
OpenDSS Manual
June 2013
DataPath
Read/writestringdescribingthepathnameforOpenDSSdata.
DefaultEditor
ReadonlypropertyreturningthepathnameoftheEditorbeingusedbyOpenDSS.
DSSProgress
ReturnsinterfacetotheProgressBar,
Error
ReturnstheErrorinterface,whichcangivetheerrornumberanderrordescription
Events
ReturnsinterfacetoDSSEvents,whichisusedtomanageWindowseventsraisedwithin
OpenDSS.
Executive
Returns DSS_Executive interface, which gives access to the names of all OpenDSS
commands, options, and related help strings. This is the same information that is
displayedinthestandardOpenDSSHelpformfromtheHelpcommand.
NewCircuit
ThisfunctionmakesanewcircuitobjectandreturnstheCircuitinterfacetotheactive
Circuit.
NumCircuits
Returnsthenumberofcircuitdefined.Atpresent,either0or1.
Reset
ThisfunctionexecutestheResetcommand.
SetActiveClass(Classname as String)
This function sets the active class to the class specified by Classname. Same as
SetActiveClassfunctioninCircuitinterface.
ShowPanel
ShowsaversionofthemaincontrolpanelforOpenDSS.
Text
ReturnstheTextinterfacethroughwhichstandardOpenDSStextcommandmaybesent
and results messages retrieved. This is generally a commonlyused interface and most
userwritten programs should have a variable assigned to this interface to aid coding.
Seeexamplesthatfollowthissection.TheTextinterfacehastwoproperties:Command
andResult.
UserClasses
Variantarrayofstringswithalistofnamesofuserwrittenclasses.
Page 169 of 180
OpenDSS Manual
June 2013
Version
Readonly property returning a string describing the present version of the program.
Thisisusefulformakingsuretheversionbeingaccessediscompatiblewiththeversion
theuserwrittenprogramexpects.
Page 170 of 180
OpenDSS Manual
June 2013
E XAMPLE MS E XCEL VBA C ODE FOR D RIVING THE COM I NTERFACE

ThecodebelowwasextractedfromasimpleMicrosoftExcelexamplefordrivingtheOpenDSS
forcompilinganarbitrarycircuitscriptfile.
Declarations
This section of the code declares some public variable for accessing the OpenDSS object and
directlyaccessingtwooftheinterfacesoncetheOpenDSSisinstantiated.TheDSSobjvariableis
required. DSSText and DSSCircuit are optional but allow for shorthand access to the Text
interfaceandtheactivecircuitinterface.
Option Explicit
Public DSSobj As OpenDSSengine.DSS
Public DSSCircuit As OpenDSSengine.Circuit
Startup
This subroutine first instantiates the OpenDSS object, setting it to the DSSobj variable. The
DSSTextvariablecanbesetatthistime,sothatisdone.NotethattheDSSCircuitvariablecannot
besetbecausenocircuitexistsyet.ThentheOpenDSSisstartedbyinvokingtheStartmethod.
Theargumentisignoredinthisversion.ThisinitializestheOpenDSSandgetsitreadyfordoing
itswork.
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
' Start the DSS
If Not DSSobj.Start(0) Then MsgBox "DSS Failed to Start"
End Sub
Compiling the Circuit

This subroutine illustrates using the Text interface Command property to compile the circuit
script file the user has specified. The filename is specified in a cell in the workbook labelled
fname.
WhentheCompilehascompleted,therewillbeanactivecircuitandthecurrentdirectorywill
havebeenswitched tothescriptfile directory.Unlesschangedinthescript,thisiswherethe
results files will reside. Now that there is an active circuit, the DSSCircuit variable can be
assignedtoit.
Public Sub LoadCircuit(fname As String)
' Always a good idea to clear the DSS when loading a new circuit
DSSText.Command = "clear"
Page 171 of 180
OpenDSS Manual
June 2013
' 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
Solving the Circuit

SolvingcanbeaccomplishedbysendingsolvetotheDSSText.Commandinterface.However,
thisexampleillustratesdirectlyaccessingtheSolvemethodintheSolutionobjectoftheactive
circuit. This shows the expanded code. Since the DSSCircuit interface has been set, one could
alsoinvoketheSolvemethodbyDSSCircuit.Solution.Solvewhichisabitshorter.
Public Sub Solve()
' Execute the Solve method in the Solution interface of the active circuit
DSSobj.ActiveCircuit.Solution.Solve
End Sub
Bringing Results into the Spreadsheet

ThereareanumberofwaystobringresultsfrominsidetheOpenDSSintoaspreadsheet.One
obviousmethodistoexportaCSVfileandopenthefileinMSExcel.Thetwosubroutinesbelow
illustratehowtodoacoupleofthingsprogrammatically.Thefirstfunctionloadsthesequence
voltages for all buses into a worksheet. The second loads the complex per unit voltages into
anotherworksheet.
TheseroutinestakeadvantageoftheabilitytotransfervariantarraysacrosstheCOMinterface
thatisinherentinVBAandsupportedinOpenDSS.Withonesimplelineofcode,suchas:
V = DSSBus.SeqVoltages
Awholearrayofvaluesarebroughtintotheprogramtobeexploitedhowevertheuserdesires.
The SeqVoltages property is associated with the Bus interface. When invoked, it causes the
sequencevoltagestobecomputedforthebusforthemostrecentsolutionandmarshalledinto
avariantarrayofdoubles.(TheOpenDSSdoesnotworkinsymmetricalcomponents,sothese
valuesmustbecomputedpostsolution.)
Intheseexamples,thevaluesaresimplydepositedintocertaincellsalongwiththebusname.
ThebusnameisextractedfromtheDSSCircuit.ActiveBusinterface.
Public Sub LoadSeqVoltages()
' This Sub loads the sequence voltages onto Sheet1 starting in Row 2
Dim
Dim
Dim
Dim
DSSBus As OpenDSSengine.Bus
iRow As Long, iCol As Long, i As Long, j As Long
V As Variant
WorkingSheet As Worksheet
Page 172 of 180
OpenDSS Manual
June 2013

Set WorkingSheet = Sheet1
'set to Sheet1 (target sheet)
iRow = 2
For i = 1 To DSSCircuit.NumBuses
' Cycle through all buses
Set DSSBus = DSSCircuit.Buses(i)
' Set ith bus active
' 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
' 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
End Sub
Public Sub LoadVoltageMags()

' This Sub loads the per unit complex voltages onto Sheet3 starting in Row 2
Dim
Dim
Dim
Dim
DSSBus As OpenDSSengine.Bus
iRow As Long, iCol As Long, i As Long, j As Long
V As Variant
WorkingSheet As Worksheet
Set WorkingSheet = Sheet3
'For Example
iRow = 2
For i = 1 To DSSCircuit.NumBuses
' Cycle through all buses
Set DSSBus = DSSCircuit.Buses(i)
' Set i-th bus active
' Bus name goes into Column 1

WorkingSheet.Cells(iRow, 1).Value = DSSCircuit.ActiveBus.Name
' Loads pu voltages (complex) at active bus as variant array of doubles
V = DSSBus.puVoltages
' Put values in Variant array into cells in sequence provided by DSS
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
End Sub
Page 173 of 180
OpenDSS Manual
June 2013
InMSExcelVBA,youmayeasilyviewtheotherpropertiesandmethodsavailablethroughthe
various interfaces in the OpenDSSEngine by including the OpenDSSEngine on the Tools |
ReferenceslistanddisplayingtheObjectBrowser(seeFigure31andFigure32).Asimpleone
linehelpstringisavailableforeachitem.
Figure 31. OpenDSSEngine COM interface as seen with MS Excel VBA
Page 174 of 180
OpenDSS Manual
June 2013
Figure 32. VBA Object Browser listing of the OpenDSS Circuit Interface
Page 175 of 180
OpenDSS Manual
June 2013
E XAMPLE : O BTAINING ALL C APACITOR N AMES AND L OCATIONS IN

M ICROSOFT E XCEL VBA
ThisExcelsubroutinewillcyclethroughalltheCapacitorobjectsinthecircuitandputthenames
andbusconnectionsinanExcelspreadsheet.ItusesCtk24fromtheEPRITestCircuits(onthe
OpenDSSsite).
Attribute VB_Name = "Module1"
Option Explicit
Public DSSObj As OpenDSSengine.DSS
Public Sub LoadInCapLocations()
Set DSSObj = New OpenDSSengine.DSS
Set DSSText = DSSObj.Text
If DSSObj.Start(0) Then
DSSText.Command = "Compile
[C:\Users\prdu001\OpenDSS\EPRITestCircuits\ckt24\master_ckt24.dss]"
DSSObj.ActiveCircuit.Solution.Solve
DSSObj.ActiveCircuit.SetActiveClass "Capacitor"
Dim MyCap As Integer, iRow As Integer
Dim BusNameArray As Variant
ActiveSheet.Cells(1, 1).Value = DSSObj.ActiveClass.ActiveClassName
ActiveSheet.Cells(1, 2).Value = "Bus1"
ActiveSheet.Cells(1, 3).Value = "Bus2"
iRow = 2
MyCap = DSSObj.ActiveClass.First
Do While MyCap > 0
ActiveSheet.Cells(iRow, 1).Value = DSSObj.ActiveClass.Name
BusNameArray = DSSObj.ActiveCircuit.ActiveCktElement.BusNames
gets all bus names for this device
ActiveSheet.Cells(iRow, 2).Value = BusNameArray(0)
' Bus1
ActiveSheet.Cells(iRow, 3).Value = BusNameArray(1)
' Bus2
iRow = iRow + 1
MyCap = DSSObj.ActiveClass.Next
Loop
'
End If
Set DSSObj = Nothing
' Be a good citizen
End Sub
Page 176 of 180
OpenDSS Manual
June 2013
E XAMPLE : GIC C ALCULATION

Theexamplesystemrepresentsahypothetical20busEHVnetworkconsistingof500kVand345
kVlinesandtransformers3.Figure33showsasinglelinediagramofthenetwork.Thenetwork
includessingletransmissionlinesaswellassomethatoccupythesametransmissioncorridor.
The substations feature both conventional transformers and autotransformers. Also included
areseries(seriescapacitors)andneutralconnectedGICblockingdevices.
SUB 2
18
16
17
SUB 3
15
T3
T15
SUB 6
7
T6
19
T5
T4
500 kV
345 kV
G
20
T8
T7
G
SUB 8
SUB 5
11
T9
3
SUB 1
1
SUB 4
13
12
T10
T2
Sw.Sta 7
T1
T11
14
G
GIC BD
T12
T13
T14
Figure 33. One Line Diagram of Example GIC System
DataforthesystemdescribedinFigure33areprovidedinTables13.
R.Horton,D.H.Boteler,T.J.Overbye,R.J.Pirjola,R.Dugan,ATestCasefortheCalculationof
GeomagneticallyInducedCurrents,IEEETransactionsonPower
Systems,October2012.
Page 177 of 180
OpenDSS Manual
June 2013
Table 1.
GIC Example Substation Location and Grid Resistance
Name
Latitude
Longitude
Sub 1
Sub 2
Sub 3
Sub 4
Sub 5
Sub 6
Sub 7
Sub 8
33.613499
34.310437
33.955058
33.547885
32.705087
33.377327
34.252248
34.195574
-87.373673
-86.365765
-84.679354
-86.074605
-84.663397
-82.618777
-82.836301
-81.098002
Grounding
Resistance
(Ohm)
0.2
0.2
0.2
1.0
0.1
0.1
N/A
0.1
Table 2.
GIC Example Transmission Line Data
Line
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
From
Bus
2
2
15
17
4
4
5
5
6
4
15
15
11
16
17
To
Bus
3
17
4
16
5
5
6
11
11
6
6
6
12
20
20
Voltage
(kV-LL)
345
345
500
345
500
500
500
500
500
500
500
500
500
345
345
Length
(miles)
77.18
77.47
87.51
102.54
103.31
103.31
131.05
154.57
63.59
205.57
128.81
128.81
102.39
88.98
152.53
Resistance
(ohm/phase)
3.512
3.525
1.986
4.665
2.345
2.345
2.975
3.509
1.444
4.666
2.924
2.924
2.324
4.049
6.940
Page 178 of 180
OpenDSS Manual
June 2013
Table 3.
GIC Example Transformer Data
Name
T1
T2
T3
T4
T5
T6
T7
T8
T9
T10
T11
T12
T13
T14
T15
Resistance W1
Resistance W2
Bus No.
Bus No.
(Ohms/phase)
(Ohms/phase)
GSU w/ GIC BD
0.1
2
N/A
1
GY-GY-D
0.2
4
0.1
3
GSU
0.1
17
N/A
18
GSU
0.1
17
N/A
19
Auto
0.04
16
0.06
15
GSU
0.15
6
N/A
7
GSU
0.15
6
N/A
8
GY-GY
0.04
5
0.06
20
GY-GY
0.04
5
0.06
20
GSU
0.1
12
N/A
13
GSU
0.1
12
N/A
14
Auto
0.04
4
0.06
3
GY-GY-D
0.2
4
0.1
3
Auto
0.04
4
0.06
3
Auto
0.04
15
0.06
16
Type
OpenDSS Script for Example System

ThefollowingscriptscanbeusedtomodeltheexamplesysteminOpenDSSwithanEastward
electricfieldof1V/km.SeeExamples\GICExampleontheOpenDSSWebsite.
TransmissionLines
Note:LinesappearwrappedinthisdocumentduetoWordlimitations,butarealloneOpenDSS
statementintheactualDSSscriptfile.
!GIC Line Data
New GICLine.1-Bus2-Bus3 bus1=2 bus2=3 R=3.512 Lat1=33.613499 Lon1=-87.373673
Lat2=33.547885 Lon2=-86.074605 EE=1.00 EN=0.00
Lat2=34.310437 Lon2=-86.365765 EE=1.00 EN=0.00
Lat2=33.547885 Lon2=-86.074605 EE=1.00 EN=0.00
New GICLine.4-Bus17-Bus16 bus1=17 bus2=16 R=4.665 Lat1=34.310437 Lon1=86.365765 Lat2=33.955058 Lon2=-84.679354 EE=1.00 EN=0.00
Lat2=32.705087 Lon2=-84.663397 EE=1.00 EN=0.00
Lat2=32.705087 Lon2=-84.663397 EE=1.00 EN=0.00
Lat2=33.377327 Lon2=-82.618777 EE=1.00 EN=0.00
New GICLine.8-Bus5-Bus11 bus1=5 bus2=11 C=32.0 R=3.509 Lat1=32.705087 Lon1=84.663397 Lat2=34.252248 Lon2=-82.836301 EE=1.00 EN=0.00
Page 179 of 180
OpenDSS Manual
June 2013
Lat2=34.252248 Lon2=-82.836301 EE=1.00 EN=0.00

Lat2=33.377327 Lon2=-82.618777 EE=1.00 EN=0.00
Lat2=33.377327 Lon2=-82.618777 EE=1.00 EN=0.00
Lat2=33.377327 Lon2=-82.618777 EE=1.00 EN=0.00
Transformers
Note:LinesappearwrappedinthisdocumentduetoWordlimitations,butarealloneOpenDSS
statementintheactualDSSscriptfile.
New GICTransformer.T1 busH=2 busNH=2.4.4.4 R1=0.1 type=GSU_
New GICTransformer.T2 busH=4 busNH=4.4.4.4 busX=3 busNX=4.4.4.4 R1=0.2 R2=0.1
type=YY
New GICTransformer.T3 busH=17 busNH=17.4.4.4 R1=0.1 type=GSU
New GICTransformer.T5 busH=15 busX=16 busNX=15.4.4.4 R1=0.04 R2=0.06 type=Auto
New GICTransformer.T8 busH=5 busNH=5.4.4.4 busX=20 busNX=5.4.4.4 R1=0.04
R2=0.06 type=YY
New GICTransformer.T9 busH=5 busNH=5.4.4.4 busX=20 busNX=5.4.4.4 R1=0.04
R2=0.06 type=YY
New GICTransformer.T13 busH=4 busNH=4.4.4.4 busX=3 busNX=4.4.4.4 R1=0.2 R2=0.1
type=YY
New Capacitor.T1 bus1=2.4 bus2=2.5 phases=1 cuf=10
Page 180 of 180

The Open Distribution System Simulator

Uploaded by

Document Information

Original Title

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

The Open Distribution System Simulator

Uploaded by

Copyright:

Available Formats

OpenDSS Manual

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Redistribution and use in source and binary forms, with or without

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Figure 1. OpenDSS Structure

Program Revision: 7.6

Brief History and Objectives of OpenDSS

Program Revision: 7.6

Program Revision: 7.6

represented by a primitive nodal admittance (Y) matrix. This is generally straightforward,

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Figure 2. OpenDSSEngine in the Windows Registry

Figure 3. GUID points to the In-Process Server File (OpenDSSEngine.DLL)

Thekeyshownisforthe64bitversionCLSIDon Windows7pointing totheserverinthex64

Program Revision: 7.6

O THER R EGISTRY E NTRIES

Figure 4. OpenDSS Values in Registry

Examples, Docs, and Test Cases

Program Revision: 7.6

LoadShapes: Several typical annual distribution system loadshapes. Also, solar PV

Program Revision: 7.6

Summary of Simulation Capabilities

Program Revision: 7.6

Program Revision: 7.6

H ARMONIC F LOW A NALYSIS

Program Revision: 7.6

L OAD P ARAMETRIC V ARIATION

G EOMAGNETICALLY I NDUCED C URRENT (GIC) A NALYSIS

Program Revision: 7.6

Program Revision: 7.6

Program Revision: 7.6

Figure 5. Example of the Control panel window for the DSS

Figure 6. Do command and speed buttons

Program Revision: 7.6

E XPORT M ENU C OMMANDS

Program Revision: 7.6

Default File Name

Export Powers [MVA]

Export Monitors monitorname

file name is assigned

Program Revision: 7.6

P LOT M ENU C OMMANDS

Program Revision: 7.6

Program Revision: 7.6

plot General quantity=1 Max=.003 dots=n labels=n subs=y object=filename.csv

Figure 8: Color-shaded heat plot of harmonic resonance

Program Revision: 7.6