Enumerations

The enumeration classes from DSS-Python-Backend are reexported as opendssdirect.enums. Many functions allow using these for better code quality, and some are required to correctly use the extended API. Note that AltDSS-Python includes a lot more enumerations derived from the internal DSS schema.

class ActionCodes

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Close

2

Close a switch

Lock

4

Lock a switch, preventing both manual and automatic operation

Open

1

Open a switch

Reset

3

Reset to the shelf state (unlocked, closed for a switch)

TapDown

7

Move a regulator tap down

TapUp

6

Move a regulator tap up

Unlock

5

Unlock a switch, permitting both manual and automatic operation

none

0

No action

class AltDSSEvent

Bases: enum.IntEnum

Event codes used by the event callback system

Legacy events are the events present the classic OpenDSS COM implementation, while the rest are extensions added here.

BuildSystemY

5

Clear

3

Legacy_CheckControls

1

Legacy_InitControls

0

Legacy_StepControls

2

ReprocessBuses

4

class AutoAddTypes

Bases: enum.IntEnum

Enum where members are also (and must be) ints

AddCap

2

Add capacitors in AutoAdd mode

AddGen

1

Add generators in AutoAdd mode

class CapControlModes

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Current

0

Current control, ON and OFF settings on CT secondary

KVAR

2

kVAR control, ON and OFF settings on PT / CT base

PF

4

ON and OFF settings are power factor, negative for leading

Time

3

Time control, ON and OFF settings are seconds from midnight

Voltage

1

Voltage control, ON and OFF settings on the PT secondary base

class CktModels

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Multiphase

0

Circuit model is multiphase (default)

PositiveSeq

1

Circuit model is positive sequence model only

class ControlModes

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Event

1

Control Mode Option - Event driven solution mode

Multirate

3

Control mode option - Multirate mode

Off

None

Control Mode OFF

Static

0

Control Mode option - Static

Time

2

Control mode option - Time driven mode

class CoreType

Bases: enum.IntEnum

Transformer Core Type

core_1_phase

9

five_leg

5

four_leg

4

one_phase

1

shell

0

three_leg

3

class DSSCompatFlags

Bases: enum.IntFlag

Support for integer-based Flags

ActiveLine

16

In the official OpenDSS implementation, the Lines API use the active circuit element instead of the active line. This can lead to unexpected behavior if the user is not aware of this detail. For example, if the user accidentally enables any other circuit element, the next time they use the Lines API, the line object that was previously enabled is overwritten with another unrelated object. This flag enables this behavior above if compatibility at this level is required. On DSS-Extensions, we changed the behavior to follow what most of the other APIs do: use the active object in the internal list. This change was done for DSS C-API v0.13.5, as well as the introduction of this flag.

BadPrecision

2

If enabled, toggle worse precision for certain aspects of the engine. For example, the sequence-to-phase (As2p) and sequence-to-phase (Ap2s) transform matrices. On DSS C-API, we fill the matrix explicitly using higher precision, while numerical inversion of an initially worse precision matrix is used in the official OpenDSS. We will introduce better precision for other aspects of the engine in the future, so this flag can be used to toggle the old/bad values where feasible.

InvControl9611

4

Toggle some InvControl behavior introduced in OpenDSS 9.6.1.1. It could be a regression but needs further investigation, so we added this flag in the time being.

NoPropertyTracking

32

On DSS-Extensions/AltDSS, when setting a property invalidates a previous input value, the engine will try to mark the invalidated data as unset. This allows for better exports and tracking of the current state of DSS objects. Set this flag to disable this behavior, following the original OpenDSS implementation for potential compatibility with older software that may require the original behavior; note that may lead to errorneous interpretation of the data in the DSS properties. This was introduced in DSS C-API v0.14.0 and will be further developed for future versions.

NoSolverFloatChecks

1

If enabled, don’t check for NaNs in the inner solution loop. This can lead to various errors. This flag is useful for legacy applications that don’t handle OpenDSS API errors properly. Through the development of DSS-Extensions, we noticed this is actually a quite common issue.

SaveCalcVoltageBases

8

When using “save circuit”, the official OpenDSS always includes the “CalcVoltageBases” command in the saved script. We found that it is not always a good idea, so we removed the command (leaving it commented). Use this flag to enable the command in the saved script.

SkipSideEffects

64

Some specific functions on the official OpenDSS APIs skip important side-effects. By default, on DSS-Extensions/AltDSS, those side-effects are enabled. Use this flag to try to follow the behavior of the official APIs. Beware that some side-effects are important and skipping them may result in incorrect results. This flag only affects some of the classic API functions, especially Loads and Generators.

class DSSJSONFlags

Bases: enum.IntFlag

Support for integer-based Flags

EnumAsInt

4

Return enums as integers instead of strings

ExcludeDisabled

32

Exclude disabled elements (only valid when exporting a collection)

Full

1

Return all properties, regardless of order or if the property was filled by the user

FullNames

8

Use full names for the elements, including the class name

IncludeDefaultObjs

256

Include default unchanged objects in the exports. Any default object that has been edited is always exported. Affects whole circuit and batch exports.

LowercaseKeys

128

Use lowercase representation for the property names (and other keys) instead of the internal variants.

Pretty

16

Try to “pretty” format the JSON output

SkipBuses

1024

Skip exporting buses. Affects whole circuit exports.

SkipDSSClass

64

Do not add the “DSSClass” property to the output

SkipRedundant

2

Skip redundant properties

SkipTimestamp

512

Skip timestamp/version comment, which is added a pre-command by default. Affects whole circuit exports.

class DSSPropertyNameStyle

Bases: enum.IntEnum

This enum is used in the PropertyNameStyle property to control the naming convention. Currently, this only affects capitalization, i.e., if you software already uses case insensitive string comparisons for the property names, this is not useful. Otherwise, you can use Legacy to use the older names.

Legacy

2

Use the previous capitalization of the property names.

Lowercase

1

Use all lowercase strings.

Modern

0

By default, the modern names are used. The names were reviewed to try to reach a convention across all components.

class DSSSaveFlags

Bases: enum.IntFlag

DSSSaveFlags are bit flags used in the Circuit_Save function to customize the saved circuit.

CalcVoltageBases

1

Include the command CalcVoltageBases.

ExcludeDefault

16

Exclude default DSS items if they are not modified by the user.

ExcludeMeterZones

128

Do not export meter zones (as “feeders”) separately. Has no effect when using a single file.

IncludeDisabled

8

Include disabled circuit elements (and LoadShapes).

IncludeOptions

4

Include most of the options (from the Set/Get DSS commands).

IsOpen

256

Export commands to open terminals of elements.

KeepOrder

64

Save the circuit elements in the order they were loaded in the active circuit. Guarantees better reproducibility, especially when the system is ill-conditioned. Requires “SingleFile” flag.

SetVoltageBases

2

Include commands to set the voltage bases individually.

SingleFile

32

Use a single file instead of a folder for output.

ToString

512

Export to the result string. Requires “SingleFile” flag.

class EnergyMeterRegisters

Bases: enum.IntEnum

Energy meter registers

This enumeration lists the basic energy meter registers. Extra registers start at VBaseStart. This is exposed to make it easier to access common registers without needing to check the register names every time, plus makes it safer to access the registers by index directly without introducing bugs we found in OpenDSS code (both user code and engine code) in the past due to direct use of magic numbers.

GenMaxkVA

31

GenMaxkW

30

GenkWh

28

Genkvarh

29

LineLosseskWh

22

LineModeLineLoss

24

LoadEEN

10

LoadLosseskWh

16

LoadLosseskvarh

17

LoadUE

11

LossesMaxkW

14

LossesMaxkvar

15

MaxLoadLosses

20

MaxNoLoadLosses

21

MaxkVA

3

MaxkW

2

NoLoadLosseskWh

18

NoLoadLosseskvarh

19

OnePhaseLineLoss

27

OverloadkWhEmerg

9

OverloadkWhNorm

8

ThreePhaseLineLoss

26

TransformerLosseskWh

23

VBaseStart

32

Anchor for the voltage base loss registers

ZeroModeLineLoss

25

ZoneLosseskWh

12

ZoneLosseskvarh

13

ZoneMaxkVA

7

ZoneMaxkW

6

ZonekWh

4

Zonekvarh

5

kWh

0

kvarh

1

class GeneratorRegisters

Bases: enum.IntEnum

Generator registers

Enumeration of the generator registers by index. Currently shared between the Generator, Storage and PVSystem models.

Hours

4

MaxkVA

3

MaxkW

2

Price

5

kWh

0

kvarh

1

class GeneratorStatus

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Fixed

1

Variable

0

class LineUnits

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Miles

1

Line length units in miles

cm

7

Line units are cm

ft

5

Line units in feet

inch

6

Line length units are inches

kFt

2

Line length units are in thousand feet

km

3

Line length units are km

meter

4

Line length units are meters

mm

8

Line length units are mm

none

0

No line length unit

class LoadModels

Bases: enum.IntEnum

Enum where members are also (and must be) ints

CVR

4

ConstI

5

ConstPFixedQ

6

ConstPFixedX

7

ConstPQ

1

ConstZ

2

Motor

3

ZIPV

8

class LoadStatus

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Exempt

2

Fixed

1

Variable

0

class MonitorModes

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Magnitude

32

Reports the monitored quantities in Magnitude Only

PosOnly

64

Reports the Positive Seq only or avg of all phases

Power

1

Monitor records kW, kvar or kVA, angle values, etc. at the terminal to which it is connected.

Sequence

16

Reports the monitored quantities as sequence quantities

States

3

For monitoring State Variables (for PC Elements only)

Taps

2

For monitoring Regulator and Transformer taps

VI

0

Monitor records Voltage and Current at the terminal (Default)

class OCPDevType

Bases: enum.IntEnum

Overcurrent Protection Device Type

Fuse

1

Recloser

2

Relay

3

none

0

class Options

Bases: enum.IntEnum

Deprecated. Please use instead:

• AutoAddTypes

• CktModels

• ControlModes

• SolutionLoadModels

• SolutionAlgorithms

• RandomModes

AddCap

2

AddGen

1

Admittance

2

ControlOFF

None

Event

1

Gaussian

1

LogNormal

3

Multiphase

0

NewtonSolve

1

NormalSolve

0

PositiveSeq

1

PowerFlow

1

Static

0

Time

2

Uniform

2

class RandomModes

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Gaussian

1

LogNormal

3

Uniform

2

class SetterFlags

Bases: enum.IntFlag

Setter flags customize how the update of DSS properties are handled by the engine and parts of the API. Use especially in the Obj and Batch APIs

AllowAllConductors

2147483648

Used internally for the “Wires” property (“Conductors”). This was left public in case someone tries to implement some internal aspects in external functions.

AvoidFullRecalc

2

Some components like Loads don’t need to update YPrim for every change, e.g. setting “load.a_load.kW=1” if was “kW” previously 2 should not force a YPrim update, but it does force an update by default. Using this flag will reproduce what the classic OpenDSS API for Loads (DSS.ActiveCircuit.Loads) does, but removes a lot of duplicated code. Besides that, we can extend the feature for other components if we think it fits.

ImplicitSizes

1

Most array properties depend on sizes defined by other properties. Using this flag, many properties allow users to skip setting the other property directly, allowing the engine to use the size of the provided array to initialize the other property.

SkipNA

4

For batch operations with arrays, skip NA values

Currently, NA values are interpreted as:

• NaN for float64

• INT32_MAX (0x7fffffff) for int32

• Null pointers for strings (in this case, use a "\0" string for empty strings)

class SolutionAlgorithms

Bases: enum.IntEnum

Enum where members are also (and must be) ints

NewtonSolve

1

Solution algorithm option - Newton solution

NormalSolve

0

Solution algorithm option - Normal solution

class SolutionLoadModels

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Admittance

2

Admittance load model option

PowerFlow

1

Power Flow load model option

class SolveModes

Bases: enum.IntEnum

Enum where members are also (and must be) ints

AutoAdd

13

Auto add generators or capacitors

Daily

1

Solve following Daily load shapes

Direct

7

Solve direct (forced admittance model)

DutyCycle

6

Solve following Duty Cycle load shapes

Dynamic

14

Solve for dynamics

FaultStudy

9

Fault study at all buses

Harmonic

15

Harmonic solution mode

HarmonicT

17

LD1

4

Load-duration Mode 1

LD2

12

Load-Duration Mode 2

Monte1

3

Monte Carlo Mode 1

Monte2

10

Monte Carlo Mode 2

Monte3

11

Monte Carlo Mode 3

MonteFault

8

Monte carlo Fault Study

PeakDay

5

Solves for Peak Day using Daily load curve

SnapShot

0

Solve a single snapshot power flow

Time

16

Yearly

2

Solve following Yearly load shapes

class SparseSolverOptions

Bases: enum.IntEnum

Enum where members are also (and must be) ints

AlwaysResetYPrimInvalid

268435456

Bit flag, see CktElement.pas for details. Some components do not clear the dirty flag after their YPrim is updated, so YPrim is updated every time the system Y is changed, even if there are no changes to the component. This flag forces clearing the dirty flag, keeping the YPrim matrix constant when the component has not changed.

ReuseCompressedMatrix

1

Reuse only the prepared CSC matrix. This should be numerically exact, but may have some cost saving if the number of entries changed in the system Y matrix are a small fraction of the total entries.

ReuseNothing

0

Default behavior, following the official OpenDSS implementation.

ReuseNumericFactorization

3

Reuse the numeric factorization, implies ReuseSymbolicFactorization

ReuseSymbolicFactorization

2

Reuse the symbolic factorization, implies ReuseCompressedMatrix

class StorageStates

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Charging

None

Discharging

1

Idling

0

class YMatrixModes

Bases: enum.IntEnum

Enum where members are also (and must be) ints

SeriesOnly

1

WholeMatrix

2