Main API (module DSS)

The dss function is the main function for passing commands to OpenDSS. You can pass multi-line commands with dss. You can also splice in Julia values with string interpolation. Here is an example of using dss:

using OpenDSSDirect
filename = "C:/OpenDSS/electricdss/IEEETestCases/8500-Node/Master.dss"
dss("""
    clear
    compile $filename
""")

Several functions are available for setting OpenDSS variables, getting values, and initiating commands. Each of these is in one of several modules. Here is an example to set the kW of the active load element:

Loads.kW(50.)

Here is an example setting some loads:

using OpenDSSDirect
filename = "C:/OpenDSS/electricdss/IEEETestCases/8500-Node/Master.dss"
dss("""
    clear
    compile $filename
""")
loadnumber = Loads.First()
while loadnumber > 0
    Loads.kW(50.)
    Loads.kvar(20.)
    loadnumber = Loads.Next()
end
println(Loads.Count())

To use this API, you can either use import OpenDSSDirect and prepend all calls with OpenDSSDirect, or you can run using OpenDSSDirect and use the functions within each module directly. The following two are equivalent:

import OpenDSSDirect
OpenDSSDirect.Circuit.TotalPower()

Importing the DSS module:

using OpenDSSDirect
Circuit.TotalPower()

Many of the functions that return arrays convert to complex numbers where appropriate. Here is an example session:

julia> using OpenDSSDirect

julia> filename = joinpath(Pkg.dir(), "OpenDSSDirect", "examples", "8500-Node", "Master.dss");

julia> dss("""
           clear
           compile $filename
       """)

julia> Solution.Solve();

julia> Circuit.Losses()
1.218242333223247e6 + 2.798391857088721e6im

julia> Circuit.TotalPower()
-12004.740450109337 - 1471.1749507157301im

julia> Circuit.SetActiveElement("Capacitor.CAPBank3")
6075

julia> CktElement.Voltages()
6-element Array{Complex{Float64},1}:
  5390.82-4652.32im
 -6856.89-2274.93im
  1284.62+7285.18im
      0.0+0.0im
      0.0+0.0im
      0.0+0.0im

To find the functions available in each module, use Julia's help for each module (initiated by hitting ?). See below for an example.

julia> using OpenDSSDirect

help?> Circuit
search: Circuit

  module Circuit – Functions for interfacing with the active OpenDSS circuit.

  Circuit.NumCktElements() – Number of CktElements in the circuit

  Circuit.NumBuses() – Total number of Buses in the circuit

  Circuit.NumNodes() – Total number of Nodes in the circuit

  Circuit.FirstPCElement() – Sets the first enabled Power Conversion (PC) element in the circuit to be active; if not successful returns a 0

  Circuit.NextPCElement() – Sets the next enabled Power Conversion (PC) element in the circuit to be active; if not successful returns a 0

  Circuit.FirstPDElement() – Sets the first enabled Power Delivery (PD) element in the circuit to be active; if not successful returns a 0

  Circuit.NextPDElement() – Sets the next enabled Power Delivery (PD) element in the circuit to be active; if not successful returns a 0

  {truncated...}

Here is a list of modules supported by this API. Each module has several functions.

dss

OpenDSSDirect.dssFunction
Command() -> String

Input command string for the DSS. (Getter)

source
Command(Value::String) -> String

Input command string for the DSS. (Setter)

source

ActiveClass

OpenDSSDirect.ActiveClass.FirstMethod
First() -> Int64

Sets first element in the active class to be the active DSS object. If object is a CktElement, ActiveCktELment also points to this element. Returns 0 if none.

source
OpenDSSDirect.ActiveClass.NextMethod
Next() -> Int64

Sets next element in active class to be the active DSS object. If object is a CktElement, ActiveCktElement also points to this element. Returns 0 if no more.

source

Basic

OpenDSSDirect.Basic.LegacyModelsMethod
LegacyModels(Value::Bool)

Gets/sets the state of the Legacy Models mechanism (Setter)

If enabled, the legacy/deprecated models for PVSystem, InvControl, Storage and StorageControl are used. WARNING: Changing the active value runs a "Clear" command, discarding the current circuit.

Defaults to false (disabled state).

This can also be set through the environment variable DSSCAPILEGACY_MODELS. Setting it to 1 enables the legacy components, using the old models from the start.

(API Extension)

source
OpenDSSDirect.Basic.LegacyModelsLegacyModelsMethod
LegacyModelsLegacyModels() -> Bool

Gets/sets the state of the Legacy Models mechanism (Getter)

If enabled, the legacy/deprecated models for PVSystem, InvControl, Storage and StorageControl are used. WARNING: Changing the active value runs a "Clear" command, discarding the current circuit.

Defaults to false (disabled state).

This can also be set through the environment variable DSSCAPILEGACY_MODELS. Setting it to 1 enables the legacy components, using the old models from the start.

(API Extension)

source

Bus

OpenDSSDirect.Bus.NodesMethod
Nodes() -> Array{Int64,1}

Integer Array of Node Numbers defined at the bus in same order as the voltages.

source
OpenDSSDirect.Bus.VLLMethod
VLL() -> Array{Complex{Float64},1}

For 2- and 3-phase buses, returns array of complex numbers representing L-L voltages in volts. Returns -1.0 for 1-phase bus. If more than 3 phases, returns only first 3.

source
OpenDSSDirect.Bus.puVLLMethod
puVLL() -> Array{Complex{Float64},1}

Returns Complex array of pu L-L voltages for 2- and 3-phase buses. Returns -1.0 for 1-phase bus. If more than 3 phases, returns only 3 phases.

source

Capacitors

OpenDSSDirect.Capacitors.StatesMethod
States() -> Array{Int64,1}

Array of integer [0..numsteps-1] indicating state of each step. If value is -1 an error has occurred. (Getter)

source

CapControls

Circuit

CktElement

OpenDSSDirect.CktElement.ControllerMethod
Controller(idx::Int64) -> String

Full name of the i-th controller attached to this element. Ex: str = Controller(2). See NumControls to determine valid index range

source
OpenDSSDirect.CktElement.VariableMethod
Variable(MyVarName::String, Code::Int64) -> Float64

For PCElement, get the value of a variable by name. If Code>0 Then no variable by this name or not a PCElement.

source

CtrlQueue

Element

Error

OpenDSSDirect.Error.ExtendedErrorsMethod
ExtendedErrors(Value::Bool)

Get/set the state of the Legacy Models mechanism (Setter)

If enabled, the legacy/deprecated models for PVSystem, InvControl, Storage and StorageControl are used. WARNING: Changing the active value runs a "Clear" command, discarding the current circuit.

Defaults to false (disabled state).

This can also be set through the environment variable DSSCAPILEGACY_MODELS. Setting it to 1 enables the legacy components, using the old models from the start.

(API Extension)

source
OpenDSSDirect.Error.ExtendedErrorsMethod
ExtendedErrors() -> Bool

Get/set the state of the Legacy Models mechanism (Getter)

If enabled, the legacy/deprecated models for PVSystem, InvControl, Storage and StorageControl are used. WARNING: Changing the active value runs a "Clear" command, discarding the current circuit.

Defaults to false (disabled state).

This can also be set through the environment variable DSSCAPILEGACY_MODELS. Setting it to 1 enables the legacy components, using the old models from the start.

(API Extension)

source

Executive

Fuses

OpenDSSDirect.Fuses.DelayMethod
Delay(Value::Float64)

A fixed delay time in seconds added to the fuse blowing time determined by the TCC curve. Default is 0. (Setter)

source
OpenDSSDirect.Fuses.DelayMethod
Delay() -> Float64

A fixed delay time in seconds added to the fuse blowing time determined by the TCC curve. Default is 0. (Getter)

source
OpenDSSDirect.Fuses.RatedCurrentMethod
RatedCurrent(Value::Float64)

Multiplier or actual amps for the TCCcurve object. Defaults to 1.0. Multipliy current values of TCC curve by this to get actual amps. Has to correspond to the Current axis of TCCcurve object. (Setter)

source
OpenDSSDirect.Fuses.RatedCurrentMethod
RatedCurrent() -> Float64

Multiplier or actual amps for the TCCcurve object. Defaults to 1.0. Multipliy current values of TCC curve by this to get actual amps. Has to correspond to the Current axis of TCCcurve object. (Getter)

source

Generators

Isource

LineCodes

Lines

OpenDSSDirect.Lines.FirstMethod
First() -> Int64

Invoking this property sets the first element active. Returns 0 if no lines. Otherwise, index of the line element.

source
OpenDSSDirect.Lines.NextMethod
Next() -> Int64

Invoking this property advances to the next Line element active. Returns 0 if no more lines. Otherwise, index of the line element.

source
OpenDSSDirect.Lines.RgMethod
Rg(Value::Float64)

Earth return resistance value used to compute line impedances at power frequency (Setter)

source
OpenDSSDirect.Lines.RgMethod
Rg() -> Float64

Earth return resistance value used to compute line impedances at power frequency (Getter)

source
OpenDSSDirect.Lines.XgMethod
Xg(Value::Float64)

Earth return reactance value used to compute line impedances at power frequency (Setter)

source
OpenDSSDirect.Lines.XgMethod
Xg() -> Float64

Earth return reactance value used to compute line impedances at power frequency (Getter)

source

Loads

OpenDSSDirect.Loads.ModelMethod
Model(Value::Union{Int64, OpenDSSDirect.Lib.LoadModels})

The Load Model defines variation of P and Q with voltage. (Setter)

source
OpenDSSDirect.Loads.PFMethod
PF(Value::Float64)

Power Factor for Active Load. Specify leading PF as negative. Updates kvar based on present value of kW value (Setter)

source
OpenDSSDirect.Loads.PFMethod
PF() -> Float64

Power Factor for Active Load. Specify leading PF as negative. Updates kvar based on present value of kW value (Getter)

source
OpenDSSDirect.Loads.PctMeanMethod
PctMean(Value::Float64)

Average percent of nominal load in Monte Carlo studies; only if no loadshape defined for this load. (Setter)

source
OpenDSSDirect.Loads.PctMeanMethod
PctMean() -> Float64

Average percent of nominal load in Monte Carlo studies; only if no loadshape defined for this load. (Getter)

source
OpenDSSDirect.Loads.PctStdDevMethod
PctStdDev(Value::Float64)

Percent standard deviation for Monte Carlo load studies; if there is no loadshape assigned to this load. (Setter)

source
OpenDSSDirect.Loads.PctStdDevMethod
PctStdDev() -> Float64

Percent standard deviation for Monte Carlo load studies; if there is no loadshape assigned to this load. (Getter)

source
OpenDSSDirect.Loads.StatusMethod
Status(Value::Union{Int64, OpenDSSDirect.Lib.LoadStatus})

Response to load multipliers: Fixed (growth only), Exempt (no LD curve), Variable (all). (Setter)

source
OpenDSSDirect.Loads.StatusMethod
Status() -> OpenDSSDirect.Lib.LoadStatus

Response to load multipliers: Fixed (growth only), Exempt (no LD curve), Variable (all). (Getter)

source
OpenDSSDirect.Loads.XfkVAMethod
XfkVA(Value::Float64)

Rated service transformer kVA for load allocation, using AllocationFactor. Affects kW, kvar, and pf. (Setter)

source
OpenDSSDirect.Loads.XfkVAMethod
XfkVA() -> Float64

Rated service transformer kVA for load allocation, using AllocationFactor. Affects kW, kvar, and pf. (Getter)

source
OpenDSSDirect.Loads.kVMethod
kV(Value::Float64)

Set kV rating for active Load. For 2 or more phases set Line-Line kV. Else actual kV across terminals. (Setter)

source
OpenDSSDirect.Loads.kVMethod
kV() -> Float64

Set kV rating for active Load. For 2 or more phases set Line-Line kV. Else actual kV across terminals. (Getter)

source
OpenDSSDirect.Loads.kVABaseMethod
kVABase(Value::Float64)

Base load kva. Also defined kw and kvar or pf input, or load allocation by kwh or xfkva. (Setter)

source

LoadShape

Meters

OpenDSSDirect.Meters.CalcCurrentMethod
CalcCurrent(Value::Array{Float64,1})

Set the magnitude of the real part of the Calculated Current (normally determined by solution) for the Meter to force some behavior on Load Allocation

source
OpenDSSDirect.Meters.CalcCurrentMethod
CalcCurrent() -> Array{Float64,1}

Set the magnitude of the real part of the Calculated Current (normally determined by solution) for the Meter to force some behavior on Load Allocation

source
OpenDSSDirect.Meters.SequenceListMethod
SequenceList(Value::Int64)

Get/set Index into Meter's SequenceList that contains branch pointers in lexical order. Earlier index guaranteed to be upline from later index. Sets PDelement active.

source
OpenDSSDirect.Meters.SequenceListMethod
SequenceList() -> Int64

Get/set Index into Meter's SequenceList that contains branch pointers in lexical order. Earlier index guaranteed to be upline from later index. Sets PDelement active.

source

Monitors

OpenDSSDirect.Monitors.ByteStreamMethod
ByteStream() -> Array{Int8,1}

(read-only) Byte Array containing monitor stream values. Make sure a "save" is done first (standard solution modes do this automatically)

source
OpenDSSDirect.Monitors.ChannelMethod
Channel(Index::Int64) -> Array{Float64,1}

Array of doubles for the specified channel (usage: MyArray = DSSMonitor.Channel(i)) A Save or SaveAll should be executed first. Done automatically by most standard solution modes.

source
OpenDSSDirect.Monitors.DblFreqMethod
DblFreq() -> Array{Float64,1}

(read-only) Array of doubles containing frequency values for harmonics mode solutions; Empty for time mode solutions (use dblHour)

source
OpenDSSDirect.Monitors.DblHourMethod
DblHour() -> Array{Float64,1}

(read-only) Array of doubles containgin time value in hours for time-sampled monitor values; Empty if frequency-sampled values for harmonics solution (see dblFreq)

source

Parser

OpenDSSDirect.Parser.AutoIncrementMethod
AutoIncrement(Value::Bool)

Default is FALSE. If TRUE parser automatically advances to next token after DblValue, IntValue, or StrValue. Simpler when you don't need to check for parameter names.

source
OpenDSSDirect.Parser.AutoIncrementMethod
AutoIncrement() -> Bool

Default is FALSE. If TRUE parser automatically advances to next token after DblValue, IntValue, or StrValue. Simpler when you don't need to check for parameter names.

source
OpenDSSDirect.Parser.BeginQuoteMethod
BeginQuote(Value::String)

String containing the the characters for Quoting in OpenDSS scripts. Matching pairs defined in EndQuote. Default is "'([{.

source
OpenDSSDirect.Parser.BeginQuoteMethod
BeginQuote() -> String

String containing the the characters for Quoting in OpenDSS scripts. Matching pairs defined in EndQuote. Default is "'([{.

source
OpenDSSDirect.Parser.CmdStringMethod
CmdString(Value::String)

String to be parsed. Loading this string resets the Parser to the beginning of the line. Then parse off the tokens in sequence.

source
OpenDSSDirect.Parser.CmdStringMethod
CmdString() -> String

String to be parsed. Loading this string resets the Parser to the beginning of the line. Then parse off the tokens in sequence.

source
OpenDSSDirect.Parser.DelimitersMethod
Delimiters(Value::String)

String defining hard delimiters used to separate token on the command string. Default is , and =. The = separates token name from token value. These override whitesspace to separate tokens.

source
OpenDSSDirect.Parser.DelimitersMethod
Delimiters() -> String

String defining hard delimiters used to separate token on the command string. Default is , and =. The = separates token name from token value. These override whitesspace to separate tokens.

source
OpenDSSDirect.Parser.EndQuoteMethod
EndQuote(Value::String)

String containing characters, in order, that match the beginning quote characters in BeginQuote. Default is "')]} (Setter)

source
OpenDSSDirect.Parser.EndQuoteMethod
EndQuote() -> String

String containing characters, in order, that match the beginning quote characters in BeginQuote. Default is "')]} (Getter)

source
OpenDSSDirect.Parser.MatrixMethod
Matrix(ExpectedOrder::Any)

Use this property to parse a Matrix token in OpenDSS format. Returns square matrix of order specified. Order same as default Fortran order: column by column.

source

PDElements

OpenDSSDirect.PDElements.AllMaxCurrentsFunction
AllMaxCurrents() -> Array{Float64,1}
AllMaxCurrents(AllNodes::Bool) -> Array{Float64,1}

Array of doubles with the maximum current across the conductors, for each PD element.

By default, only the first terminal is used for the maximum current, matching the behavior of the "export capacity" command. Pass AllNodes=True to force the analysis to all terminals.

See also: https://sourceforge.net/p/electricdss/discussion/beginners/thread/da5b93ca/

(API Extension)

source
OpenDSSDirect.PDElements.AllPctEmergFunction
AllPctEmerg() -> Array{Float64,1}
AllPctEmerg(AllNodes::Bool) -> Array{Float64,1}

Array of doubles with the maximum current across the conductors as a percentage of the Emergency Ampere Rating, for each PD element.

By default, only the first terminal is used for the maximum current, matching the behavior of the "export capacity" command. Pass AllNodes=True to force the analysis to all terminals.

See also: https://sourceforge.net/p/electricdss/discussion/beginners/thread/da5b93ca/

(API Extension)

source
OpenDSSDirect.PDElements.AllPctNormFunction
AllPctNorm() -> Array{Float64,1}
AllPctNorm(AllNodes::Bool) -> Array{Float64,1}

Array of doubles with the maximum current across the conductors as a percentage of the Normal Ampere Rating, for each PD element.

By default, only the first terminal is used for the maximum current, matching the behavior of the "export capacity" command. Pass AllNodes=True to force the analysis to all terminals.

See also: https://sourceforge.net/p/electricdss/discussion/beginners/thread/da5b93ca/

(API Extension)

source
OpenDSSDirect.PDElements.IsShuntMethod
IsShunt() -> Bool

Variant boolean indicating of PD element should be treated as a shunt element rather than a series element. Applies to Capacitor and Reactor elements in particular.

source

Progress

Properties

PVsystems

OpenDSSDirect.PVsystems.IrradianceNowMethod
IrradianceNow() -> Float64

Returns the current irradiance value for the active PVSystem. Use it to know what's the current irradiance value for the PV during a simulation.

source
OpenDSSDirect.PVsystems.TDutyMethod
TDuty(Value::String)

Name of the emperature shape to use for duty cycle dispatch simulations such as for solar ramp rate studies. (Setter)

source
OpenDSSDirect.PVsystems.TDutyMethod
TDuty() -> String

Name of the temperature shape to use for duty cycle dispatch simulations such as for solar ramp rate studies. (Getter)

source

Reclosers

RegControls

Relays

Sensors

OpenDSSDirect.Sensors.kVBaseMethod
kVBase(Value::Float64)

Voltage base for the sensor measurements. LL for 2 and 3-phase sensors, LN for 1-phase sensors. (Setter)

source
OpenDSSDirect.Sensors.kVSMethod
kVS(Value::Array{Float64,1})

Array of doubles for the LL or LN (depending on Delta connection) voltage measurements. (Setter)

source
OpenDSSDirect.Sensors.kVSMethod
kVS() -> Array{Float64,1}

Array of doubles for the LL or LN (depending on Delta connection) voltage measurements. (Getter)

source
OpenDSSDirect.Sensors.kWMethod
kW(Value::Array{Float64,1})

Array of doubles for P measurements. Overwrites Currents with a new estimate using kVAR. (Setter)

source
OpenDSSDirect.Sensors.kWMethod
kW() -> Array{Float64,1}

Array of doubles for P measurements. Overwrites Currents with a new estimate using kVAR. (Getter)

source
OpenDSSDirect.Sensors.kvarMethod
kvar(Value::Array{Float64,1})

Array of doubles for Q measurements. Overwrites Currents with a new estimate using kW. (Setter)

source
OpenDSSDirect.Sensors.kvarMethod
kvar() -> Array{Float64,1}

Array of doubles for Q measurements. Overwrites Currents with a new estimate using kW. (Getter)

source

Settings

OpenDSSDirect.Settings.CktModelMethod
CktModel(Value::Union{Int64, OpenDSSDirect.Lib.CktModels})

{dssMultiphase * | dssPositiveSeq} IIndicate if the circuit model is positive sequence. (Setter)

source
OpenDSSDirect.Settings.CktModelMethod
CktModel() -> OpenDSSDirect.Lib.CktModels

{dssMultiphase * | dssPositiveSeq} IIndicate if the circuit model is positive sequence. (Getter)

source
OpenDSSDirect.Settings.LoadsTerminalCheckMethod
LoadsTerminalCheck(Value::Bool)

Get/Set the state of terminal checking in all load elements. (Setter)

This controls whether the terminals are checked when updating the currents in Load component. Defaults to true. If the loads are guaranteed to have their terminals closed throughout the simulation, this can be set to false to save some time.

(API Extension)

source
OpenDSSDirect.Settings.LoadsTerminalCheckMethod
LoadsTerminalCheck() -> Bool

Get/Set the state of terminal checking in all load elements. (Getter)

This controls whether the terminals are checked when updating the currents in Load component. Defaults to true. If the loads are guaranteed to have their terminals closed throughout the simulation, this can be set to false to save some time.

(API Extension)

source

Solution

OpenDSSDirect.Solution.AddTypeMethod
AddType(Value::Union{Int64, OpenDSSDirect.Lib.AutoAddTypes})

Type of device to add in AutoAdd Mode: {dssGen (Default) | dssCap} (Setter)

source
OpenDSSDirect.Solution.MinIterationsMethod
MinIterations(Value::Int64)

(read) Minimum number of iterations required for a power flow solution. (write) Mininum number of iterations required for a power flow solution.

source
OpenDSSDirect.Solution.MinIterationsMethod
MinIterations() -> Int64

(read) Minimum number of iterations required for a power flow solution. (write) Mininum number of iterations required for a power flow solution.

source
OpenDSSDirect.Solution.RandomMethod
Random(Value::Union{Int64, OpenDSSDirect.Lib.RandomModes})

Randomization mode for random variables "Gaussian" or "Uniform" (Setter)

source

SwtControls

OpenDSSDirect.SwtControls.ActionMethod
Action(Value::Int64)

Open or Close the switch. No effect if switch is locked. However, Reset removes any lock and then closes the switch (shelf state). (Setter)

source
OpenDSSDirect.SwtControls.ActionMethod
Action() -> Int64

Open or Close the switch. No effect if switch is locked. However, Reset removes any lock and then closes the switch (shelf state). (Getter)

source
OpenDSSDirect.SwtControls.DelayMethod
Delay(Value::Float64)

Time delay [s] betwen arming and opening or closing the switch. Control may reset before actually operating the switch. (Setter)

source
OpenDSSDirect.SwtControls.DelayMethod
Delay() -> Float64

Time delay [s] betwen arming and opening or closing the switch. Control may reset before actually operating the switch. (Getter)

source

Text

Topology

Transformers

OpenDSSDirect.Transformers.WdgMethod
Wdg(Value::Float64)

Active Winding Number from 1..NumWindings. Update this before reading or setting a sequence of winding properties (R, Tap, kV, kVA, etc.) (Setter)

source
OpenDSSDirect.Transformers.WdgMethod
Wdg() -> Float64

Active Winding Number from 1..NumWindings. Update this before reading or setting a sequence of winding properties (R, Tap, kV, kVA, etc.) (Getter)

source
OpenDSSDirect.Transformers.XhlMethod
Xhl(Value::Float64)

Percent reactance between windings 1 and 2, on winding 1 kVA base. Use for 2-winding or 3-winding transformers. (Setter)

source
OpenDSSDirect.Transformers.XhlMethod
Xhl() -> Float64

Percent reactance between windings 1 and 2, on winding 1 kVA base. Use for 2-winding or 3-winding transformers. (Getter)

source
OpenDSSDirect.Transformers.kVAMethod
kVA(Value::Float64)

Active Winding kVA rating. On winding 1, this also determines normal and emergency current ratings for all windings. (Setter)

source
OpenDSSDirect.Transformers.kVAMethod
kVA() -> Float64

Active Winding kVA rating. On winding 1, this also determines normal and emergency current ratings for all windings. (Getter)

source

Vsources

XYCurves

YMatrix

OpenDSSDirect.YMatrix.getYsparseFunction
getYsparse() -> SparseArrays.SparseMatrixCSC{Complex{Float64},Int64}
getYsparse(factor::Bool) -> SparseArrays.SparseMatrixCSC{Complex{Float64},Int64}

Return SparseMatrixCSC of ComplexF64

source