Enumerations

Contents

Enumerations#

The enumeration classes from DSS-Python-Backend are reexported as dss.enums, and the enums are also imported to the main module dss (so you can use from dss import SolveModes, for example). 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

IncludeDSSClass#

64

Add “DSSClass” property to the output objects

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.

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#

1073741824

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