altdss.Relay

Module Contents

Classes

IRelay
Relay
RelayBatch
RelayBatchProperties	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)
RelayProperties	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

API

class altdss.Relay.IRelay(iobj)

Bases: altdss.DSSObj.IDSSObj, altdss.Relay.RelayBatch

Action: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

DEPRECATED. See “State” property

DSS property name: Action, DSS property index: 29.

Action_str: List[str]

‘property(…)’

DEPRECATED. See “State” property

DSS property name: Action, DSS property index: 29.

BaseFreq: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Base Frequency for ratings.

DSS property name: BaseFreq, DSS property index: 51.

BreakerTime: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Fixed delay time (sec) added to relay time. Default is 0.0. Designed to represent breaker time or some other delay after a trip decision is made.Use Delay property for setting a fixed trip time delay.Added to trip time of current and voltage relays. Could use in combination with inst trip value to obtain a definite time overcurrent relay.

DSS property name: BreakerTime, DSS property index: 28.

ComplexSeqCurrents() → altdss.types.ComplexArray

Complex double array of Sequence Currents for all conductors of all terminals of active circuit element.

Original COM help: https://opendss.epri.com/CplxSeqCurrents.html

ComplexSeqVoltages() → altdss.types.ComplexArray

Complex double array of Sequence Voltage for all terminals of active circuit element.

Original COM help: https://opendss.epri.com/CplxSeqVoltages1.html

Currents() → altdss.types.ComplexArray

Complex array of currents into each conductor of each terminal

Original COM help: https://opendss.epri.com/Currents1.html

CurrentsMagAng() → altdss.types.Float64Array

Currents in magnitude, angle (degrees) format as a array of doubles.

Original COM help: https://opendss.epri.com/CurrentsMagAng.html

DOC_DelayInner: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip time delay (sec) for operation in inner region for DOC relay, defined when “DOC_TripSettingMag” or “DOC_TripSettingHigh” are activate. Default is -1.0 (deactivated), meaning that the relay characteristic is insensitive in the inner region (no trip). Set to 0 for instantaneous trip and >0 for a definite time delay. If “DOC_PhaseCurveInner” is specified, time delay from curve is utilized instead.

DSS property name: DOC_DelayInner, DSS property index: 46.

DOC_P1Blocking: List[bool]

‘property(…)’

{Yes/True* | No/False} Blocking element that impedes relay from tripping if balanced net three-phase active power is in the forward direction (i.e., flowing into the monitored terminal). For a delayed trip, if at any given time the reverse power flow condition stops, the tripping is reset. Default=True.

DSS property name: DOC_P1Blocking, DSS property index: 50.

DOC_PhaseCurveInner: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

Name of the TCC Curve object that determines the phase trip for operation in inner region for DOC relay. Must have been previously defined as a TCC_Curve object. Default is none (ignored). Multiplying the current values in the curve by the “DOC_PhaseTripInner” value gives the actual current.

DSS property name: DOC_PhaseCurveInner, DSS property index: 47.

DOC_PhaseCurveInner_str: List[str]

‘property(…)’

Name of the TCC Curve object that determines the phase trip for operation in inner region for DOC relay. Must have been previously defined as a TCC_Curve object. Default is none (ignored). Multiplying the current values in the curve by the “DOC_PhaseTripInner” value gives the actual current.

DSS property name: DOC_PhaseCurveInner, DSS property index: 47.

DOC_PhaseTripInner: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Multiplier for the “DOC_PhaseCurveInner” TCC curve. Defaults to 1.0.

DSS property name: DOC_PhaseTripInner, DSS property index: 48.

DOC_TDPhaseInner: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Time dial for “DOC_PhaseCurveInner” TCC curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: DOC_TDPhaseInner, DSS property index: 49.

DOC_TiltAngleHigh: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Tilt angle for high-current trip line. Default is 90.

DSS property name: DOC_TiltAngleHigh, DSS property index: 42.

DOC_TiltAngleLow: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Tilt angle for low-current trip line. Default is 90.

DSS property name: DOC_TiltAngleLow, DSS property index: 41.

DOC_TripSettingHigh: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Resistive trip setting for high-current line. Default is -1 (deactivated). To activate, set a positive value. Must be greater than “DOC_TripSettingLow”.

DSS property name: DOC_TripSettingHigh, DSS property index: 44.

DOC_TripSettingLow: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Resistive trip setting for low-current line. Default is 0.

DSS property name: DOC_TripSettingLow, DSS property index: 43.

DOC_TripSettingMag: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip setting for current magnitude (defines a circle in the relay characteristics). Default is -1 (deactivated). To activate, set a positive value.

DSS property name: DOC_TripSettingMag, DSS property index: 45.

DebugTrace: List[bool]

‘property(…)’

{Yes/True* | No/False* } Default is No for Relay. Write extra details to Eventlog.

DSS property name: DebugTrace, DSS property index: 37.

Delay: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip time delay (sec) for DEFINITE TIME relays. Default is 0.0 for current, voltage and DOC relays. If >0 then this value is used instead of curves. Used by Generic, RevPower, 46 and 47 relays. Defaults to 0.1 s for these relays.

DSS property name: Delay, DSS property index: 17.

DistReverse: List[bool]

‘property(…)’

{Yes/True* | No/False} Default is No; reverse direction for distance and td21 types.

DSS property name: DistReverse, DSS property index: 38.

Enabled: List[bool]

‘property(…)’

{Yes|No or True|False} Indicates whether this element is enabled.

DSS property name: Enabled, DSS property index: 52.

EventLog: List[bool]

‘property(…)’

{Yes/True | No/False* } Default is No for Relay. Write trips, reclose and reset events to EventLog.

DSS property name: EventLog, DSS property index: 36.

F46BaseAmps: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Base current, Amps, for 46 relay (neg seq current). Used for establishing pickup and per unit I-squared-t.

DSS property name: 46BaseAmps, DSS property index: 22.

F46isqt: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Negative Sequence I-squared-t trip value for 46 relay (neg seq current). Default is 1 (trips in 1 sec for 1 per unit neg seq current). Should be 1 to 99.

DSS property name: 46isqt, DSS property index: 24.

F46pctPickup: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Percent pickup current for 46 relay (neg seq current). Default is 20.0. When current exceeds this value * BaseAmps, I-squared-t calc starts.

DSS property name: 46%Pickup, DSS property index: 23.

F47pctPickup: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Percent voltage pickup for 47 relay (Neg seq voltage). Default is 2. Specify also base voltage (kvbase) and delay time value.

DSS property name: 47%Pickup, DSS property index: 21.

FullName() → List[str]

Returns the full name (including object type) for all objects in this batch

GUID() → List[str]

GUID/UUID for each object. Currently used only in the CIM-related methods.

Original COM help: https://opendss.epri.com/GUID.html

GroundCurve: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

Name of the TCC Curve object that determines the ground trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored).For overcurrent relay, multiplying the current values in the curve by the “groundtrip” valuw gives the actual current.

DSS property name: GroundCurve, DSS property index: 7.

GroundCurve_str: List[str]

‘property(…)’

Name of the TCC Curve object that determines the ground trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored).For overcurrent relay, multiplying the current values in the curve by the “groundtrip” valuw gives the actual current.

DSS property name: GroundCurve, DSS property index: 7.

GroundInst: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Actual amps for instantaneous ground trip which is assumed to happen in 0.01 sec + Delay Time.Default is 0.0, which signifies no inst trip.

DSS property name: GroundInst, DSS property index: 13.

GroundTrip: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Multiplier or actual ground amps (3I0) for the ground TCC curve. Defaults to 1.0.

DSS property name: GroundTrip, DSS property index: 9.

Handle() → altdss.types.Int32Array

Index of each element into the circuit’s element list.

Original COM help: https://opendss.epri.com/Handle.html

HasOCPDevice() → altdss.types.BoolArray

For each element in the batch: returns true if a recloser, relay, or fuse controlling the circuit element.

OCP = Overcurrent Protection

Original COM help: https://opendss.epri.com/HasOCPDevice.html

HasSwitchControl() → altdss.types.BoolArray

For each element in the batch: returns true if the element has a SwtControl attached.

Original COM help: https://opendss.epri.com/HasSwitchControl.html

HasVoltControl() → altdss.types.BoolArray

For each element in the batch: returns true if the element has a CapControl or RegControl attached.

Original COM help: https://opendss.epri.com/HasVoltControl.html

IsIsolated() → altdss.types.BoolArray

For each element in the batch: returns true if the element is isolated. Note that this only fetches the current value. See also the Topology interface.

Like(value: AnyStr, flags: altdss.enums.SetterFlags = 0)

Make like another object, e.g.:

New Capacitor.C2 like=c1 …

DSS property name: Like, DSS property index: 53.

Losses() → altdss.types.ComplexArray

For each element in the batch: total losses in the element, in VA (watts, vars).

Original COM help: https://opendss.epri.com/Losses1.html

MGround: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Ground reach multiplier in per-unit for Distance and TD21 functions. Default=0.7

DSS property name: MGround, DSS property index: 35.

MPhase: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Phase reach multiplier in per-unit for Distance and TD21 functions. Default=0.7

DSS property name: MPhase, DSS property index: 34.

MaxCurrent(terminal: int) → altdss.types.Float64Array

Returns the maximum current (magnitude) at the specified terminal for each element in this batch. Use -1 as terminal to get the value across all terminals.

MonitoredObj: List[altdss.DSSObj.DSSObj]

‘property(…)’

Full object name of the circuit element, typically a line, transformer, load, or generator, to which the relay’s PT and/or CT are connected. This is the “monitored” element. There is no default; must be specified.

DSS property name: MonitoredObj, DSS property index: 1.

MonitoredObj_str: List[str]

‘property(…)’

Full object name of the circuit element, typically a line, transformer, load, or generator, to which the relay’s PT and/or CT are connected. This is the “monitored” element. There is no default; must be specified.

DSS property name: MonitoredObj, DSS property index: 1.

MonitoredTerm: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

Number of the terminal of the circuit element to which the Relay is connected. 1 or 2, typically. Default is 1.

DSS property name: MonitoredTerm, DSS property index: 2.

property Name: List[str]

Normal: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

{Open | Closed} Normal state of the relay. The relay reverts to this state for reset, change of mode, etc. Defaults to “State” if not specifically declared.

DSS property name: Normal, DSS property index: 39.

Normal_str: List[str]

‘property(…)’

{Open | Closed} Normal state of the relay. The relay reverts to this state for reset, change of mode, etc. Defaults to “State” if not specifically declared.

DSS property name: Normal, DSS property index: 39.

NumConductors() → altdss.types.Int32Array

Number of conductors per terminal for each element in the batch.

Original COM help: https://opendss.epri.com/NumConductors.html

NumControllers() → altdss.types.Int32Array

Number of controllers connected to each device in the batch.

Original COM help: https://opendss.epri.com/NumControls.html

NumPhases() → altdss.types.Int32Array

Number of Phases for each element in this batch.

Original COM help: https://opendss.epri.com/NumPhases.html

NumTerminals() → altdss.types.Int32Array

Number of terminals for each Circuit Element in the batch.

Original COM help: https://opendss.epri.com/NumTerminals.html

OCPDevice() → List[Union[altdss.DSSObj.DSSObj, None]]

Returns (as a list of Python objects) the OCP device controlling each element.

OCPDeviceIndex() → altdss.types.Int32Array

For each element in the batch: index into each controller list of the OCP Device controlling each circuit element

Original COM help: https://opendss.epri.com/OCPDevIndex.html

OCPDeviceType() → List[dss.enums.OCPDevType]

For each element in the batch: type of OCP controller device

Original COM help: https://opendss.epri.com/OCPDevType.html

Overtrip: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip setting (high value) for Generic relay variable. Relay trips in definite time if value of variable exceeds this value.

DSS property name: Overtrip, DSS property index: 26.

OvervoltCurve: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

TCC Curve object to use for overvoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: OvervoltCurve, DSS property index: 18.

OvervoltCurve_str: List[str]

‘property(…)’

TCC Curve object to use for overvoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: OvervoltCurve, DSS property index: 18.

PhaseCurve: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

Name of the TCC Curve object that determines the phase trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored). For overcurrent relay, multiplying the current values in the curve by the “phasetrip” value gives the actual current.

DSS property name: PhaseCurve, DSS property index: 6.

PhaseCurve_str: List[str]

‘property(…)’

Name of the TCC Curve object that determines the phase trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored). For overcurrent relay, multiplying the current values in the curve by the “phasetrip” value gives the actual current.

DSS property name: PhaseCurve, DSS property index: 6.

PhaseInst: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Actual amps (Current relay) or kW (reverse power relay) for instantaneous phase trip which is assumed to happen in 0.01 sec + Delay Time. Default is 0.0, which signifies no inst trip. Use this value for specifying the Reverse Power threshold (kW) for reverse power relays.

DSS property name: PhaseInst, DSS property index: 12.

PhaseLosses() → altdss.types.ComplexArray

Complex array of losses (kVA) by phase

Original COM help: https://opendss.epri.com/PhaseLosses.html

PhaseTrip: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Multiplier or actual phase amps for the phase TCC curve. Defaults to 1.0.

DSS property name: PhaseTrip, DSS property index: 8.

Powers() → altdss.types.ComplexArray

Complex array of powers (kVA) into each conductor of each terminal, of each element in the batch.

Original COM help: https://opendss.epri.com/Powers.html

RecloseIntervals: List[altdss.types.Float64Array]

‘property(…)’

Array of reclose intervals. If none, specify “NONE”. Default for overcurrent relay is (0.5, 2.0, 2.0) seconds. Default for a voltage relay is (5.0). In a voltage relay, this is seconds after restoration of voltage that the reclose occurs. Reverse power relay is one shot to lockout, so this is ignored. A locked out relay must be closed manually (set action=close).

DSS property name: RecloseIntervals, DSS property index: 16.

Reset: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Reset time in sec for relay. Default is 15. If this much time passes between the last pickup event, and the relay has not locked out, the operation counter resets.

DSS property name: Reset, DSS property index: 14.

SeqCurrents() → altdss.types.Float64Array

Array of symmetrical component currents (magnitudes only) into each 3-phase terminal of each element

Original COM help: https://opendss.epri.com/SeqCurrents.html

SeqPowers() → altdss.types.ComplexArray

Complex array of sequence powers (kW, kvar) into each 3-phase terminal of each element

Original COM help: https://opendss.epri.com/SeqPowers.html

SeqVoltages() → altdss.types.Float64Array

Double array of symmetrical component voltages (magnitudes only) at each 3-phase terminal

Original COM help: https://opendss.epri.com/SeqVoltages1.html

Shots: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

Number of shots to lockout. Default is 4. This is one more than the number of reclose intervals.

DSS property name: Shots, DSS property index: 15.

State: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

{Open | Closed} Actual state of the relay. Upon setting, immediately forces state of the relay, overriding the Relay control. Simulates manual control on relay. Defaults to Closed. “Open” causes the controlled element to open and lock out. “Closed” causes the controlled element to close and the relay to reset to its first operation.

DSS property name: State, DSS property index: 40.

State_str: List[str]

‘property(…)’

{Open | Closed} Actual state of the relay. Upon setting, immediately forces state of the relay, overriding the Relay control. Simulates manual control on relay. Defaults to Closed. “Open” causes the controlled element to open and lock out. “Closed” causes the controlled element to close and the relay to reset to its first operation.

DSS property name: State, DSS property index: 40.

SwitchedObj: List[altdss.DSSObj.DSSObj]

‘property(…)’

Name of circuit element switch that the Relay controls. Specify the full object name.Defaults to the same as the Monitored element. This is the “controlled” element.

DSS property name: SwitchedObj, DSS property index: 3.

SwitchedObj_str: List[str]

‘property(…)’

Name of circuit element switch that the Relay controls. Specify the full object name.Defaults to the same as the Monitored element. This is the “controlled” element.

DSS property name: SwitchedObj, DSS property index: 3.

SwitchedTerm: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

Number of the terminal of the controlled element in which the switch is controlled by the Relay. 1 or 2, typically. Default is 1.

DSS property name: SwitchedTerm, DSS property index: 4.

TDGround: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Time dial for Ground trip curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: TDGround, DSS property index: 11.

TDPhase: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Time dial for Phase trip curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: TDPhase, DSS property index: 10.

TotalPowers() → altdss.types.ComplexArray

Returns an array with the total powers (complex, kVA) at all terminals of the circuit elements in this batch.

The resulting array is equivalent to concatenating the TotalPowers for each element.

Type: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

One of a legal relay type: Current Voltage Reversepower 46 (neg seq current) 47 (neg seq voltage) Generic (generic over/under relay) Distance TD21 DOC (directional overcurrent)

Default is overcurrent relay (Current) Specify the curve and pickup settings appropriate for each type. Generic relays monitor PC Element Control variables and trip on out of over/under range in definite time.

DSS property name: Type, DSS property index: 5.

Type_str: List[str]

‘property(…)’

One of a legal relay type: Current Voltage Reversepower 46 (neg seq current) 47 (neg seq voltage) Generic (generic over/under relay) Distance TD21 DOC (directional overcurrent)

Default is overcurrent relay (Current) Specify the curve and pickup settings appropriate for each type. Generic relays monitor PC Element Control variables and trip on out of over/under range in definite time.

DSS property name: Type, DSS property index: 5.

Undertrip: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip setting (low value) for Generic relay variable. Relay trips in definite time if value of variable is less than this value.

DSS property name: Undertrip, DSS property index: 27.

UndervoltCurve: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

TCC Curve object to use for undervoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: UndervoltCurve, DSS property index: 19.

UndervoltCurve_str: List[str]

‘property(…)’

TCC Curve object to use for undervoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: UndervoltCurve, DSS property index: 19.

Variable: List[str]

‘property(…)’

Name of variable in PC Elements being monitored. Only applies to Generic relay.

DSS property name: Variable, DSS property index: 25.

Voltages() → altdss.types.ComplexArray

Complex array of voltages at terminals

Original COM help: https://opendss.epri.com/Voltages1.html

VoltagesMagAng() → altdss.types.Float64Array

Voltages at each conductor in magnitude, angle form as array of doubles.

Original COM help: https://opendss.epri.com/VoltagesMagAng.html

Z0Ang: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Zero sequence reach impedance angle in degrees for Distance and TD21 functions. Default=68.0

DSS property name: Z0Ang, DSS property index: 33.

Z0Mag: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Zero sequence reach impedance in primary ohms for Distance and TD21 functions. Default=2.1

DSS property name: Z0Mag, DSS property index: 32.

Z1Ang: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Positive sequence reach impedance angle in degrees for Distance and TD21 functions. Default=64.0

DSS property name: Z1Ang, DSS property index: 31.

Z1Mag: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Positive sequence reach impedance in primary ohms for Distance and TD21 functions. Default=0.7

DSS property name: Z1Mag, DSS property index: 30.

__call__()

__contains__(name: str) → bool

__getitem__(name_or_idx)

__init__(iobj)

__iter__()

__len__() → int

batch(**kwargs)

Creates a new batch handler of (existing) objects

batch_new(names: Optional[List[AnyStr]] = None, *, df=None, count: Optional[int] = None, begin_edit: Optional[bool] = None, **kwargs: typing_extensions.Unpack[altdss.Relay.RelayBatchProperties]) → altdss.Relay.RelayBatch

Creates a new batch of Relay objects

Either names, count or df is required.

Parameters:

• begin_edit – The argument begin_edit indicates if the user want to leave the elements in the edit state, and requires a call to end_edit() or equivalent. The default begin_edit is set to None. With None, the behavior will be adjusted according the default of how the batch is created.

• **kwargs – Pass keyword arguments equivalent to the DSS properties of the object.

• names – When using a list of names, each new object will match the names from this list. begin_edit defaults to True if no arguments for properties were passed, False otherwise.

• count – When using count, new objects will be created with based on a random prefix, with an increasing integer up to count. begin_edit defaults to True if no arguments for properties were passed, False otherwise.

• df – Currently EXPERIMENTAL AND LIMITED, tries to get the columns from a dataframe to populate the names and the DSS properties. begin_edit defaults to False.

Returns:

Returns the new batch of DSS objects, wrapped in Python.

Note that, to make it easier for new users where the edit context might not be too relevant, AltDSS automatically opens/closes edit contexts for single properties if the object is not in the edit state already.

begin_edit() → None

Marks for editing all DSS objects in the batch

In the editing mode, some final side-effects of changing properties are postponed until end_edit is called. This side-effects can be somewhat costly, like updating the model parameters or internal matrices.

If you don’t have any performance constraint, you may edit each property individually without worrying about using begin_edit and end_edit. For convenience, those are emitted automatically when editing single properties outside an edit block.

edit(**kwargs: typing_extensions.Unpack[altdss.Relay.RelayBatchProperties]) → altdss.Relay.RelayBatch

Edit this Relay batch.

This method will try to open a new edit context (if not already open), edit the properties, and finalize the edit context for objects in the batch. It can be seen as a shortcut to manually setting each property, or a Pythonic analogous (but extended) to the DSS BatchEdit command.

Parameters:

**kwargs – Pass keyword arguments equivalent to the DSS properties of the objects.

Returns:

Returns itself to allow call chaining.

end_edit(num_changes: int = 1) → None

Leaves the editing states of all DSS objects in the batch

num_changes is required for a few classes to correctly match the official OpenDSS behavior and must be the number of properties modified in the current editing block. As of DSS C-API v0.13, this is only required for the Monitor class, when the Action property is used with the Process value.

find(name_or_idx: Union[AnyStr, int]) → altdss.DSSObj.DSSObj

Returns an object from the collection by name or index; the index must be zero-based.

kVBase: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Voltage base (kV) for the relay. Specify line-line for 3 phase devices); line-neutral for 1-phase devices. Relay assumes the number of phases of the monitored element. Default is 0.0, which results in assuming the voltage values in the “TCC” curve are specified in actual line-to-neutral volts.

DSS property name: kVBase, DSS property index: 20.

new(name: AnyStr, *, begin_edit: Optional[bool] = None, activate=False, **kwargs: typing_extensions.Unpack[altdss.Relay.RelayProperties]) → altdss.Relay.Relay

Creates a new Relay.

Parameters:

• name – The object’s name is a required positional argument.

• activate – Activation (setting activate to true) is useful for integration with the classic API, and some internal OpenDSS commands. If you interact with this object only via the Alt API, no need to activate it (due to performance costs).

• begin_edit – This controls how the edit context is left after the object creation:

• True: The object will be left in the edit state, requiring an end_edit call or equivalent.

• False: No edit context is started.

• None: If no properties are passed as keyword arguments, the object will be left in the edit state (assumes the user will fill the properties from Python attributes). Otherwise, the internal edit context will be finalized.

Parameters:

**kwargs – Pass keyword arguments equivalent to the DSS properties of the object.

Returns:

Returns the new DSS object, wrapped in Python.

Note that, to make it easier for new users where the edit context might not be too relevant, AltDSS automatically opens/closes edit contexts for single properties if the object is not in the edit state already.

to_json(options: Union[int, dss.enums.DSSJSONFlags] = 0)

Returns the data (as a list) of the elements in a batch as a JSON-encoded string.

The options parameter contains bit-flags to toggle specific features. See Obj_ToJSON (C-API) for more, or DSSObj.to_json in Python.

Additionally, the ExcludeDisabled flag can be used to excluded disabled elements from the output.

to_list()

class altdss.Relay.Relay(api_util, ptr)

Bases: altdss.DSSObj.DSSObj, altdss.CircuitElement.CircuitElementMixin

Action: altdss.enums.RelayAction

‘property(…)’

DEPRECATED. See “State” property

DSS property name: Action, DSS property index: 29.

Action_str: str

‘property(…)’

DEPRECATED. See “State” property

DSS property name: Action, DSS property index: 29.

BaseFreq: float

‘property(…)’

Base Frequency for ratings.

DSS property name: BaseFreq, DSS property index: 51.

BreakerTime: float

‘property(…)’

Fixed delay time (sec) added to relay time. Default is 0.0. Designed to represent breaker time or some other delay after a trip decision is made.Use Delay property for setting a fixed trip time delay.Added to trip time of current and voltage relays. Could use in combination with inst trip value to obtain a definite time overcurrent relay.

DSS property name: BreakerTime, DSS property index: 28.

Close(terminal: int, phase: int) → None

Close the specified terminal and phase, if non-zero, or all conductors at the terminal.

Original COM help: https://opendss.epri.com/Close1.html

ComplexSeqCurrents() → altdss.types.ComplexArray

Complex double array of Sequence Currents for all conductors of all terminals of active circuit element.

Original COM help: https://opendss.epri.com/CplxSeqCurrents.html

ComplexSeqVoltages() → altdss.types.ComplexArray

Complex double array of Sequence Voltage for all terminals of active circuit element.

Original COM help: https://opendss.epri.com/CplxSeqVoltages1.html

Currents() → altdss.types.ComplexArray

Complex array of currents into each conductor of each terminal

Original COM help: https://opendss.epri.com/Currents1.html

DOC_DelayInner: float

‘property(…)’

Trip time delay (sec) for operation in inner region for DOC relay, defined when “DOC_TripSettingMag” or “DOC_TripSettingHigh” are activate. Default is -1.0 (deactivated), meaning that the relay characteristic is insensitive in the inner region (no trip). Set to 0 for instantaneous trip and >0 for a definite time delay. If “DOC_PhaseCurveInner” is specified, time delay from curve is utilized instead.

DSS property name: DOC_DelayInner, DSS property index: 46.

DOC_P1Blocking: bool

‘property(…)’

{Yes/True* | No/False} Blocking element that impedes relay from tripping if balanced net three-phase active power is in the forward direction (i.e., flowing into the monitored terminal). For a delayed trip, if at any given time the reverse power flow condition stops, the tripping is reset. Default=True.

DSS property name: DOC_P1Blocking, DSS property index: 50.

DOC_PhaseCurveInner: altdss.TCC_Curve.TCC_Curve

‘property(…)’

Name of the TCC Curve object that determines the phase trip for operation in inner region for DOC relay. Must have been previously defined as a TCC_Curve object. Default is none (ignored). Multiplying the current values in the curve by the “DOC_PhaseTripInner” value gives the actual current.

DSS property name: DOC_PhaseCurveInner, DSS property index: 47.

DOC_PhaseCurveInner_str: str

‘property(…)’

Name of the TCC Curve object that determines the phase trip for operation in inner region for DOC relay. Must have been previously defined as a TCC_Curve object. Default is none (ignored). Multiplying the current values in the curve by the “DOC_PhaseTripInner” value gives the actual current.

DSS property name: DOC_PhaseCurveInner, DSS property index: 47.

DOC_PhaseTripInner: float

‘property(…)’

Multiplier for the “DOC_PhaseCurveInner” TCC curve. Defaults to 1.0.

DSS property name: DOC_PhaseTripInner, DSS property index: 48.

DOC_TDPhaseInner: float

‘property(…)’

Time dial for “DOC_PhaseCurveInner” TCC curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: DOC_TDPhaseInner, DSS property index: 49.

DOC_TiltAngleHigh: float

‘property(…)’

Tilt angle for high-current trip line. Default is 90.

DSS property name: DOC_TiltAngleHigh, DSS property index: 42.

DOC_TiltAngleLow: float

‘property(…)’

Tilt angle for low-current trip line. Default is 90.

DSS property name: DOC_TiltAngleLow, DSS property index: 41.

DOC_TripSettingHigh: float

‘property(…)’

Resistive trip setting for high-current line. Default is -1 (deactivated). To activate, set a positive value. Must be greater than “DOC_TripSettingLow”.

DSS property name: DOC_TripSettingHigh, DSS property index: 44.

DOC_TripSettingLow: float

‘property(…)’

Resistive trip setting for low-current line. Default is 0.

DSS property name: DOC_TripSettingLow, DSS property index: 43.

DOC_TripSettingMag: float

‘property(…)’

Trip setting for current magnitude (defines a circle in the relay characteristics). Default is -1 (deactivated). To activate, set a positive value.

DSS property name: DOC_TripSettingMag, DSS property index: 45.

DebugTrace: bool

‘property(…)’

{Yes/True* | No/False* } Default is No for Relay. Write extra details to Eventlog.

DSS property name: DebugTrace, DSS property index: 37.

Delay: float

‘property(…)’

Trip time delay (sec) for DEFINITE TIME relays. Default is 0.0 for current, voltage and DOC relays. If >0 then this value is used instead of curves. Used by Generic, RevPower, 46 and 47 relays. Defaults to 0.1 s for these relays.

DSS property name: Delay, DSS property index: 17.

DisplayName: str

‘property(…)’

Display name of the object (not necessarily unique)

Original COM help: https://opendss.epri.com/DisplayName.html

DistReverse: bool

‘property(…)’

{Yes/True* | No/False} Default is No; reverse direction for distance and td21 types.

DSS property name: DistReverse, DSS property index: 38.

Enabled: bool

‘property(…)’

{Yes|No or True|False} Indicates whether this element is enabled.

DSS property name: Enabled, DSS property index: 52.

EventLog: bool

‘property(…)’

{Yes/True | No/False* } Default is No for Relay. Write trips, reclose and reset events to EventLog.

DSS property name: EventLog, DSS property index: 36.

F46BaseAmps: float

‘property(…)’

Base current, Amps, for 46 relay (neg seq current). Used for establishing pickup and per unit I-squared-t.

DSS property name: 46BaseAmps, DSS property index: 22.

F46isqt: float

‘property(…)’

Negative Sequence I-squared-t trip value for 46 relay (neg seq current). Default is 1 (trips in 1 sec for 1 per unit neg seq current). Should be 1 to 99.

DSS property name: 46isqt, DSS property index: 24.

F46pctPickup: float

‘property(…)’

Percent pickup current for 46 relay (neg seq current). Default is 20.0. When current exceeds this value * BaseAmps, I-squared-t calc starts.

DSS property name: 46%Pickup, DSS property index: 23.

F47pctPickup: float

‘property(…)’

Percent voltage pickup for 47 relay (Neg seq voltage). Default is 2. Specify also base voltage (kvbase) and delay time value.

DSS property name: 47%Pickup, DSS property index: 21.

FullName() → str

GUID() → str

Object’s GUID/UUID. Currently used only in the CIM-related methods.

Original COM help: https://opendss.epri.com/GUID.html

GroundCurve: altdss.TCC_Curve.TCC_Curve

‘property(…)’

Name of the TCC Curve object that determines the ground trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored).For overcurrent relay, multiplying the current values in the curve by the “groundtrip” valuw gives the actual current.

DSS property name: GroundCurve, DSS property index: 7.

GroundCurve_str: str

‘property(…)’

Name of the TCC Curve object that determines the ground trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored).For overcurrent relay, multiplying the current values in the curve by the “groundtrip” valuw gives the actual current.

DSS property name: GroundCurve, DSS property index: 7.

GroundInst: float

‘property(…)’

Actual amps for instantaneous ground trip which is assumed to happen in 0.01 sec + Delay Time.Default is 0.0, which signifies no inst trip.

DSS property name: GroundInst, DSS property index: 13.

GroundTrip: float

‘property(…)’

Multiplier or actual ground amps (3I0) for the ground TCC curve. Defaults to 1.0.

DSS property name: GroundTrip, DSS property index: 9.

Handle() → int

Index of this element into the circuit’s element list.

Original COM help: https://opendss.epri.com/Handle.html

HasOCPDevice() → bool

Returns true if a recloser, relay, or fuse controlling the circuit element.

OCP = Overcurrent Protection

Original COM help: https://opendss.epri.com/HasOCPDevice.html

HasSwitchControl() → bool

Returns true if the element has a SwtControl attached.

Original COM help: https://opendss.epri.com/HasSwitchControl.html

HasVoltControl() → bool

Returns true if the element has a CapControl or RegControl attached.

Original COM help: https://opendss.epri.com/HasVoltControl.html

IsIsolated() → bool

Returns true if the element is isolated. Note that this only fetches the current value. See also the Topology interface.

IsOpen(terminal: int, phase: int) → bool

Returns true if the specified terminal and phase are open.

If the phase parameter is zero, returns if any conductor at the terminal is open.

Like(value: AnyStr)

Make like another object, e.g.:

New Capacitor.C2 like=c1 …

DSS property name: Like, DSS property index: 53.

Losses() → complex

Total (complex) losses in the element, in VA (watts, vars)

Original COM help: https://opendss.epri.com/Losses1.html

MGround: float

‘property(…)’

Ground reach multiplier in per-unit for Distance and TD21 functions. Default=0.7

DSS property name: MGround, DSS property index: 35.

MPhase: float

‘property(…)’

Phase reach multiplier in per-unit for Distance and TD21 functions. Default=0.7

DSS property name: MPhase, DSS property index: 34.

MaxCurrent(terminal: int) → float

Returns the maximum current (magnitude) at the specified terminal. Use -1 as terminal to get the value across all terminals.

MonitoredObj: altdss.DSSObj.DSSObj

‘property(…)’

Full object name of the circuit element, typically a line, transformer, load, or generator, to which the relay’s PT and/or CT are connected. This is the “monitored” element. There is no default; must be specified.

DSS property name: MonitoredObj, DSS property index: 1.

MonitoredObj_str: str

‘property(…)’

Full object name of the circuit element, typically a line, transformer, load, or generator, to which the relay’s PT and/or CT are connected. This is the “monitored” element. There is no default; must be specified.

DSS property name: MonitoredObj, DSS property index: 1.

MonitoredTerm: int

‘property(…)’

Number of the terminal of the circuit element to which the Relay is connected. 1 or 2, typically. Default is 1.

DSS property name: MonitoredTerm, DSS property index: 2.

property Name: str

NodeOrder() → altdss.types.Int32Array

Array of integer containing the node numbers (representing phases, for example) for each conductor of each terminal.

Be sure to run a solution to initialize the values after the circuit is created or modified.

NodeRef() → altdss.types.Int32Array

Array of integers, a copy of the internal NodeRef of the CktElement.

Be sure to run a solution to initialize the values after the circuit is created or modified.

Normal: altdss.enums.RelayState

‘property(…)’

{Open | Closed} Normal state of the relay. The relay reverts to this state for reset, change of mode, etc. Defaults to “State” if not specifically declared.

DSS property name: Normal, DSS property index: 39.

Normal_str: str

‘property(…)’

{Open | Closed} Normal state of the relay. The relay reverts to this state for reset, change of mode, etc. Defaults to “State” if not specifically declared.

DSS property name: Normal, DSS property index: 39.

NumConductors() → int

Number of conductors per terminal

Original COM help: https://opendss.epri.com/NumConductors.html

NumControllers() → int

Number of controllers connected to this device.

Original COM help: https://opendss.epri.com/NumControls.html

NumPhases() → int

Number of phases

Original COM help: https://opendss.epri.com/NumPhases.html

NumTerminals() → int

Number of terminals in this circuit element

Original COM help: https://opendss.epri.com/NumTerminals.html

OCPDevice() → Union[altdss.DSSObj.DSSObj, None]

Returns (as a Python object) the OCP device controlling this element, if any.

OCPDeviceIndex() → int

Index into controller list of OCP Device controlling this circuit element

Original COM help: https://opendss.epri.com/OCPDevIndex.html

OCPDeviceType() → dss.enums.OCPDevType

Type of OCP controller device

Original COM help: https://opendss.epri.com/OCPDevType.html

Open(terminal: int, phase: int) → None

Open the specified terminal and phase, if non-zero, or all conductors at the terminal.

Original COM help: https://opendss.epri.com/Open1.html

Overtrip: float

‘property(…)’

Trip setting (high value) for Generic relay variable. Relay trips in definite time if value of variable exceeds this value.

DSS property name: Overtrip, DSS property index: 26.

OvervoltCurve: altdss.TCC_Curve.TCC_Curve

‘property(…)’

TCC Curve object to use for overvoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: OvervoltCurve, DSS property index: 18.

OvervoltCurve_str: str

‘property(…)’

TCC Curve object to use for overvoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: OvervoltCurve, DSS property index: 18.

PhaseCurve: altdss.TCC_Curve.TCC_Curve

‘property(…)’

Name of the TCC Curve object that determines the phase trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored). For overcurrent relay, multiplying the current values in the curve by the “phasetrip” value gives the actual current.

DSS property name: PhaseCurve, DSS property index: 6.

PhaseCurve_str: str

‘property(…)’

Name of the TCC Curve object that determines the phase trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored). For overcurrent relay, multiplying the current values in the curve by the “phasetrip” value gives the actual current.

DSS property name: PhaseCurve, DSS property index: 6.

PhaseInst: float

‘property(…)’

Actual amps (Current relay) or kW (reverse power relay) for instantaneous phase trip which is assumed to happen in 0.01 sec + Delay Time. Default is 0.0, which signifies no inst trip. Use this value for specifying the Reverse Power threshold (kW) for reverse power relays.

DSS property name: PhaseInst, DSS property index: 12.

PhaseLosses() → altdss.types.ComplexArray

Complex array of losses (kVA) by phase

Original COM help: https://opendss.epri.com/PhaseLosses.html

PhaseTrip: float

‘property(…)’

Multiplier or actual phase amps for the phase TCC curve. Defaults to 1.0.

DSS property name: PhaseTrip, DSS property index: 8.

Powers() → altdss.types.ComplexArray

Complex array of powers (kVA) into each conductor of each terminal

Original COM help: https://opendss.epri.com/Powers.html

RecloseIntervals: altdss.types.Float64Array

‘property(…)’

Array of reclose intervals. If none, specify “NONE”. Default for overcurrent relay is (0.5, 2.0, 2.0) seconds. Default for a voltage relay is (5.0). In a voltage relay, this is seconds after restoration of voltage that the reclose occurs. Reverse power relay is one shot to lockout, so this is ignored. A locked out relay must be closed manually (set action=close).

DSS property name: RecloseIntervals, DSS property index: 16.

Reset: float

‘property(…)’

Reset time in sec for relay. Default is 15. If this much time passes between the last pickup event, and the relay has not locked out, the operation counter resets.

DSS property name: Reset, DSS property index: 14.

Residuals() → altdss.types.Float64Array

Residual currents for each terminal: (magnitude, angle in degrees)

Original COM help: https://opendss.epri.com/Residuals.html

SeqCurrents() → altdss.types.Float64Array

Array of symmetrical component currents (magnitudes only) into each 3-phase terminal

Original COM help: https://opendss.epri.com/SeqCurrents.html

SeqPowers() → altdss.types.ComplexArray

Complex array of sequence powers (kW, kvar) into each 3-phase terminal

Original COM help: https://opendss.epri.com/SeqPowers.html

SeqVoltages() → altdss.types.Float64Array

Double array of symmetrical component voltages (magnitudes only) at each 3-phase terminal

Original COM help: https://opendss.epri.com/SeqVoltages1.html

Shots: int

‘property(…)’

Number of shots to lockout. Default is 4. This is one more than the number of reclose intervals.

DSS property name: Shots, DSS property index: 15.

State: altdss.enums.RelayState

‘property(…)’

{Open | Closed} Actual state of the relay. Upon setting, immediately forces state of the relay, overriding the Relay control. Simulates manual control on relay. Defaults to Closed. “Open” causes the controlled element to open and lock out. “Closed” causes the controlled element to close and the relay to reset to its first operation.

DSS property name: State, DSS property index: 40.

State_str: str

‘property(…)’

{Open | Closed} Actual state of the relay. Upon setting, immediately forces state of the relay, overriding the Relay control. Simulates manual control on relay. Defaults to Closed. “Open” causes the controlled element to open and lock out. “Closed” causes the controlled element to close and the relay to reset to its first operation.

DSS property name: State, DSS property index: 40.

SwitchedObj: altdss.DSSObj.DSSObj

‘property(…)’

Name of circuit element switch that the Relay controls. Specify the full object name.Defaults to the same as the Monitored element. This is the “controlled” element.

DSS property name: SwitchedObj, DSS property index: 3.

SwitchedObj_str: str

‘property(…)’

Name of circuit element switch that the Relay controls. Specify the full object name.Defaults to the same as the Monitored element. This is the “controlled” element.

DSS property name: SwitchedObj, DSS property index: 3.

SwitchedTerm: int

‘property(…)’

Number of the terminal of the controlled element in which the switch is controlled by the Relay. 1 or 2, typically. Default is 1.

DSS property name: SwitchedTerm, DSS property index: 4.

TDGround: float

‘property(…)’

Time dial for Ground trip curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: TDGround, DSS property index: 11.

TDPhase: float

‘property(…)’

Time dial for Phase trip curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: TDPhase, DSS property index: 10.

TotalPowers() → altdss.types.ComplexArray

Returns an array with the total powers (complex, kVA) at ALL terminals of the active circuit element.

Original COM help: https://opendss.epri.com/TotalPowers.html

Type: altdss.enums.RelayType

‘property(…)’

One of a legal relay type: Current Voltage Reversepower 46 (neg seq current) 47 (neg seq voltage) Generic (generic over/under relay) Distance TD21 DOC (directional overcurrent)

Default is overcurrent relay (Current) Specify the curve and pickup settings appropriate for each type. Generic relays monitor PC Element Control variables and trip on out of over/under range in definite time.

DSS property name: Type, DSS property index: 5.

Type_str: str

‘property(…)’

One of a legal relay type: Current Voltage Reversepower 46 (neg seq current) 47 (neg seq voltage) Generic (generic over/under relay) Distance TD21 DOC (directional overcurrent)

Default is overcurrent relay (Current) Specify the curve and pickup settings appropriate for each type. Generic relays monitor PC Element Control variables and trip on out of over/under range in definite time.

DSS property name: Type, DSS property index: 5.

Undertrip: float

‘property(…)’

Trip setting (low value) for Generic relay variable. Relay trips in definite time if value of variable is less than this value.

DSS property name: Undertrip, DSS property index: 27.

UndervoltCurve: altdss.TCC_Curve.TCC_Curve

‘property(…)’

TCC Curve object to use for undervoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: UndervoltCurve, DSS property index: 19.

UndervoltCurve_str: str

‘property(…)’

TCC Curve object to use for undervoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: UndervoltCurve, DSS property index: 19.

Variable: str

‘property(…)’

Name of variable in PC Elements being monitored. Only applies to Generic relay.

DSS property name: Variable, DSS property index: 25.

Voltages() → altdss.types.ComplexArray

Complex array of voltages at terminals

Original COM help: https://opendss.epri.com/Voltages1.html

VoltagesMagAng() → altdss.types.Float64Array

Voltages at each conductor in magnitude, angle form as array of doubles.

Original COM help: https://opendss.epri.com/VoltagesMagAng.html

YPrim() → altdss.types.ComplexArray

YPrim matrix, column order, complex numbers

Original COM help: https://opendss.epri.com/Yprim.html

Z0Ang: float

‘property(…)’

Zero sequence reach impedance angle in degrees for Distance and TD21 functions. Default=68.0

DSS property name: Z0Ang, DSS property index: 33.

Z0Mag: float

‘property(…)’

Zero sequence reach impedance in primary ohms for Distance and TD21 functions. Default=2.1

DSS property name: Z0Mag, DSS property index: 32.

Z1Ang: float

‘property(…)’

Positive sequence reach impedance angle in degrees for Distance and TD21 functions. Default=64.0

DSS property name: Z1Ang, DSS property index: 31.

Z1Mag: float

‘property(…)’

Positive sequence reach impedance in primary ohms for Distance and TD21 functions. Default=0.7

DSS property name: Z1Mag, DSS property index: 30.

__hash__()

Return hash(self).

__init__(api_util, ptr)

__ne__(other)

Return self!=value.

__repr__()

Return repr(self).

begin_edit() → None

Marks a DSS object for editing

In the editing mode, some final side-effects of changing properties are postponed until end_edit is called. This side-effects can be somewhat costly, like updating the model parameters or internal matrices.

If you don’t have any performance constraint, you may edit each property individually without worrying about using begin_edit and end_edit. For convenience, those are emitted automatically when editing single properties outside an edit block.

edit(**kwargs: typing_extensions.Unpack[altdss.Relay.RelayProperties]) → altdss.Relay.Relay

Edit this Relay.

This method will try to open a new edit context (if not already open), edit the properties, and finalize the edit context. It can be seen as a shortcut to manually setting each property, or a Pythonic analogous (but extended) to the DSS Edit command.

Parameters:

**kwargs – Pass keyword arguments equivalent to the DSS properties of the object.

Returns:

Returns itself to allow call chaining.

end_edit(num_changes: int = 1) → None

Leaves the editing state of a DSS object

num_changes is required for a few classes to correctly match the official OpenDSS behavior and must be the number of properties modified in the current editing block. As of DSS C-API v0.13, this is only required for the Monitor class, when the Action property is used with the Process value.

kVBase: float

‘property(…)’

Voltage base (kV) for the relay. Specify line-line for 3 phase devices); line-neutral for 1-phase devices. Relay assumes the number of phases of the monitored element. Default is 0.0, which results in assuming the voltage values in the “TCC” curve are specified in actual line-to-neutral volts.

DSS property name: kVBase, DSS property index: 20.

to_json(options: Union[int, dss.enums.DSSJSONFlags] = 0)

Returns an element’s data as a JSON-encoded string.

The options parameter contains bit-flags to toggle specific features.

By default (options = 0), only the properties explicitly set. The properties are returned in the order they are set in the input. As a reminder, OpenDSS is sensitive to the order of the properties.

The options bit-flags are available in the DSSJSONFlags enum. Values used by this function are:

• Full: if set, all properties are returned, ordered by property index instead.

• SkipRedundant: if used with Full, all properties except redundant and unused ones are returned.

• EnumAsInt: enumerated properties are returned as integer values instead of strings.

• FullNames: any element reference will use the full name ({class name}.{element name}) even if not required.

• Pretty: more whitespace is used in the output for a “prettier” format.

• SkipDSSClass: do not add the “DSSClass” property to the JSON objects.

NOT IMPLEMENTED YET:

• State: include run-time state information

• Debug: include debug information

Other bit-flags are reserved for future uses. Please use DSSJSONFlags enum to avoid potential conflicts.

(API Extension)

class altdss.Relay.RelayBatch(api_util, **kwargs)

Bases: altdss.Batch.DSSBatch, altdss.CircuitElement.CircuitElementBatchMixin

Action: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

DEPRECATED. See “State” property

DSS property name: Action, DSS property index: 29.

Action_str: List[str]

‘property(…)’

DEPRECATED. See “State” property

DSS property name: Action, DSS property index: 29.

BaseFreq: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Base Frequency for ratings.

DSS property name: BaseFreq, DSS property index: 51.

BreakerTime: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Fixed delay time (sec) added to relay time. Default is 0.0. Designed to represent breaker time or some other delay after a trip decision is made.Use Delay property for setting a fixed trip time delay.Added to trip time of current and voltage relays. Could use in combination with inst trip value to obtain a definite time overcurrent relay.

DSS property name: BreakerTime, DSS property index: 28.

ComplexSeqCurrents() → altdss.types.ComplexArray

Complex double array of Sequence Currents for all conductors of all terminals of active circuit element.

Original COM help: https://opendss.epri.com/CplxSeqCurrents.html

ComplexSeqVoltages() → altdss.types.ComplexArray

Complex double array of Sequence Voltage for all terminals of active circuit element.

Original COM help: https://opendss.epri.com/CplxSeqVoltages1.html

Currents() → altdss.types.ComplexArray

Complex array of currents into each conductor of each terminal

Original COM help: https://opendss.epri.com/Currents1.html

CurrentsMagAng() → altdss.types.Float64Array

Currents in magnitude, angle (degrees) format as a array of doubles.

Original COM help: https://opendss.epri.com/CurrentsMagAng.html

DOC_DelayInner: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip time delay (sec) for operation in inner region for DOC relay, defined when “DOC_TripSettingMag” or “DOC_TripSettingHigh” are activate. Default is -1.0 (deactivated), meaning that the relay characteristic is insensitive in the inner region (no trip). Set to 0 for instantaneous trip and >0 for a definite time delay. If “DOC_PhaseCurveInner” is specified, time delay from curve is utilized instead.

DSS property name: DOC_DelayInner, DSS property index: 46.

DOC_P1Blocking: List[bool]

‘property(…)’

{Yes/True* | No/False} Blocking element that impedes relay from tripping if balanced net three-phase active power is in the forward direction (i.e., flowing into the monitored terminal). For a delayed trip, if at any given time the reverse power flow condition stops, the tripping is reset. Default=True.

DSS property name: DOC_P1Blocking, DSS property index: 50.

DOC_PhaseCurveInner: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

Name of the TCC Curve object that determines the phase trip for operation in inner region for DOC relay. Must have been previously defined as a TCC_Curve object. Default is none (ignored). Multiplying the current values in the curve by the “DOC_PhaseTripInner” value gives the actual current.

DSS property name: DOC_PhaseCurveInner, DSS property index: 47.

DOC_PhaseCurveInner_str: List[str]

‘property(…)’

Name of the TCC Curve object that determines the phase trip for operation in inner region for DOC relay. Must have been previously defined as a TCC_Curve object. Default is none (ignored). Multiplying the current values in the curve by the “DOC_PhaseTripInner” value gives the actual current.

DSS property name: DOC_PhaseCurveInner, DSS property index: 47.

DOC_PhaseTripInner: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Multiplier for the “DOC_PhaseCurveInner” TCC curve. Defaults to 1.0.

DSS property name: DOC_PhaseTripInner, DSS property index: 48.

DOC_TDPhaseInner: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Time dial for “DOC_PhaseCurveInner” TCC curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: DOC_TDPhaseInner, DSS property index: 49.

DOC_TiltAngleHigh: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Tilt angle for high-current trip line. Default is 90.

DSS property name: DOC_TiltAngleHigh, DSS property index: 42.

DOC_TiltAngleLow: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Tilt angle for low-current trip line. Default is 90.

DSS property name: DOC_TiltAngleLow, DSS property index: 41.

DOC_TripSettingHigh: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Resistive trip setting for high-current line. Default is -1 (deactivated). To activate, set a positive value. Must be greater than “DOC_TripSettingLow”.

DSS property name: DOC_TripSettingHigh, DSS property index: 44.

DOC_TripSettingLow: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Resistive trip setting for low-current line. Default is 0.

DSS property name: DOC_TripSettingLow, DSS property index: 43.

DOC_TripSettingMag: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip setting for current magnitude (defines a circle in the relay characteristics). Default is -1 (deactivated). To activate, set a positive value.

DSS property name: DOC_TripSettingMag, DSS property index: 45.

DebugTrace: List[bool]

‘property(…)’

{Yes/True* | No/False* } Default is No for Relay. Write extra details to Eventlog.

DSS property name: DebugTrace, DSS property index: 37.

Delay: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip time delay (sec) for DEFINITE TIME relays. Default is 0.0 for current, voltage and DOC relays. If >0 then this value is used instead of curves. Used by Generic, RevPower, 46 and 47 relays. Defaults to 0.1 s for these relays.

DSS property name: Delay, DSS property index: 17.

DistReverse: List[bool]

‘property(…)’

{Yes/True* | No/False} Default is No; reverse direction for distance and td21 types.

DSS property name: DistReverse, DSS property index: 38.

Enabled: List[bool]

‘property(…)’

{Yes|No or True|False} Indicates whether this element is enabled.

DSS property name: Enabled, DSS property index: 52.

EventLog: List[bool]

‘property(…)’

{Yes/True | No/False* } Default is No for Relay. Write trips, reclose and reset events to EventLog.

DSS property name: EventLog, DSS property index: 36.

F46BaseAmps: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Base current, Amps, for 46 relay (neg seq current). Used for establishing pickup and per unit I-squared-t.

DSS property name: 46BaseAmps, DSS property index: 22.

F46isqt: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Negative Sequence I-squared-t trip value for 46 relay (neg seq current). Default is 1 (trips in 1 sec for 1 per unit neg seq current). Should be 1 to 99.

DSS property name: 46isqt, DSS property index: 24.

F46pctPickup: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Percent pickup current for 46 relay (neg seq current). Default is 20.0. When current exceeds this value * BaseAmps, I-squared-t calc starts.

DSS property name: 46%Pickup, DSS property index: 23.

F47pctPickup: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Percent voltage pickup for 47 relay (Neg seq voltage). Default is 2. Specify also base voltage (kvbase) and delay time value.

DSS property name: 47%Pickup, DSS property index: 21.

FullName() → List[str]

Returns the full name (including object type) for all objects in this batch

GUID() → List[str]

GUID/UUID for each object. Currently used only in the CIM-related methods.

Original COM help: https://opendss.epri.com/GUID.html

GroundCurve: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

Name of the TCC Curve object that determines the ground trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored).For overcurrent relay, multiplying the current values in the curve by the “groundtrip” valuw gives the actual current.

DSS property name: GroundCurve, DSS property index: 7.

GroundCurve_str: List[str]

‘property(…)’

Name of the TCC Curve object that determines the ground trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored).For overcurrent relay, multiplying the current values in the curve by the “groundtrip” valuw gives the actual current.

DSS property name: GroundCurve, DSS property index: 7.

GroundInst: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Actual amps for instantaneous ground trip which is assumed to happen in 0.01 sec + Delay Time.Default is 0.0, which signifies no inst trip.

DSS property name: GroundInst, DSS property index: 13.

GroundTrip: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Multiplier or actual ground amps (3I0) for the ground TCC curve. Defaults to 1.0.

DSS property name: GroundTrip, DSS property index: 9.

Handle() → altdss.types.Int32Array

Index of each element into the circuit’s element list.

Original COM help: https://opendss.epri.com/Handle.html

HasOCPDevice() → altdss.types.BoolArray

For each element in the batch: returns true if a recloser, relay, or fuse controlling the circuit element.

OCP = Overcurrent Protection

Original COM help: https://opendss.epri.com/HasOCPDevice.html

HasSwitchControl() → altdss.types.BoolArray

For each element in the batch: returns true if the element has a SwtControl attached.

Original COM help: https://opendss.epri.com/HasSwitchControl.html

HasVoltControl() → altdss.types.BoolArray

For each element in the batch: returns true if the element has a CapControl or RegControl attached.

Original COM help: https://opendss.epri.com/HasVoltControl.html

IsIsolated() → altdss.types.BoolArray

For each element in the batch: returns true if the element is isolated. Note that this only fetches the current value. See also the Topology interface.

Like(value: AnyStr, flags: altdss.enums.SetterFlags = 0)

Make like another object, e.g.:

New Capacitor.C2 like=c1 …

DSS property name: Like, DSS property index: 53.

Losses() → altdss.types.ComplexArray

For each element in the batch: total losses in the element, in VA (watts, vars).

Original COM help: https://opendss.epri.com/Losses1.html

MGround: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Ground reach multiplier in per-unit for Distance and TD21 functions. Default=0.7

DSS property name: MGround, DSS property index: 35.

MPhase: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Phase reach multiplier in per-unit for Distance and TD21 functions. Default=0.7

DSS property name: MPhase, DSS property index: 34.

MaxCurrent(terminal: int) → altdss.types.Float64Array

Returns the maximum current (magnitude) at the specified terminal for each element in this batch. Use -1 as terminal to get the value across all terminals.

MonitoredObj: List[altdss.DSSObj.DSSObj]

‘property(…)’

Full object name of the circuit element, typically a line, transformer, load, or generator, to which the relay’s PT and/or CT are connected. This is the “monitored” element. There is no default; must be specified.

DSS property name: MonitoredObj, DSS property index: 1.

MonitoredObj_str: List[str]

‘property(…)’

Full object name of the circuit element, typically a line, transformer, load, or generator, to which the relay’s PT and/or CT are connected. This is the “monitored” element. There is no default; must be specified.

DSS property name: MonitoredObj, DSS property index: 1.

MonitoredTerm: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

Number of the terminal of the circuit element to which the Relay is connected. 1 or 2, typically. Default is 1.

DSS property name: MonitoredTerm, DSS property index: 2.

property Name: List[str]

Normal: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

{Open | Closed} Normal state of the relay. The relay reverts to this state for reset, change of mode, etc. Defaults to “State” if not specifically declared.

DSS property name: Normal, DSS property index: 39.

Normal_str: List[str]

‘property(…)’

{Open | Closed} Normal state of the relay. The relay reverts to this state for reset, change of mode, etc. Defaults to “State” if not specifically declared.

DSS property name: Normal, DSS property index: 39.

NumConductors() → altdss.types.Int32Array

Number of conductors per terminal for each element in the batch.

Original COM help: https://opendss.epri.com/NumConductors.html

NumControllers() → altdss.types.Int32Array

Number of controllers connected to each device in the batch.

Original COM help: https://opendss.epri.com/NumControls.html

NumPhases() → altdss.types.Int32Array

Number of Phases for each element in this batch.

Original COM help: https://opendss.epri.com/NumPhases.html

NumTerminals() → altdss.types.Int32Array

Number of terminals for each Circuit Element in the batch.

Original COM help: https://opendss.epri.com/NumTerminals.html

OCPDevice() → List[Union[altdss.DSSObj.DSSObj, None]]

Returns (as a list of Python objects) the OCP device controlling each element.

OCPDeviceIndex() → altdss.types.Int32Array

For each element in the batch: index into each controller list of the OCP Device controlling each circuit element

Original COM help: https://opendss.epri.com/OCPDevIndex.html

OCPDeviceType() → List[dss.enums.OCPDevType]

For each element in the batch: type of OCP controller device

Original COM help: https://opendss.epri.com/OCPDevType.html

Overtrip: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip setting (high value) for Generic relay variable. Relay trips in definite time if value of variable exceeds this value.

DSS property name: Overtrip, DSS property index: 26.

OvervoltCurve: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

TCC Curve object to use for overvoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: OvervoltCurve, DSS property index: 18.

OvervoltCurve_str: List[str]

‘property(…)’

TCC Curve object to use for overvoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: OvervoltCurve, DSS property index: 18.

PhaseCurve: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

Name of the TCC Curve object that determines the phase trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored). For overcurrent relay, multiplying the current values in the curve by the “phasetrip” value gives the actual current.

DSS property name: PhaseCurve, DSS property index: 6.

PhaseCurve_str: List[str]

‘property(…)’

Name of the TCC Curve object that determines the phase trip. Must have been previously defined as a TCC_Curve object. Default is none (ignored). For overcurrent relay, multiplying the current values in the curve by the “phasetrip” value gives the actual current.

DSS property name: PhaseCurve, DSS property index: 6.

PhaseInst: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Actual amps (Current relay) or kW (reverse power relay) for instantaneous phase trip which is assumed to happen in 0.01 sec + Delay Time. Default is 0.0, which signifies no inst trip. Use this value for specifying the Reverse Power threshold (kW) for reverse power relays.

DSS property name: PhaseInst, DSS property index: 12.

PhaseLosses() → altdss.types.ComplexArray

Complex array of losses (kVA) by phase

Original COM help: https://opendss.epri.com/PhaseLosses.html

PhaseTrip: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Multiplier or actual phase amps for the phase TCC curve. Defaults to 1.0.

DSS property name: PhaseTrip, DSS property index: 8.

Powers() → altdss.types.ComplexArray

Complex array of powers (kVA) into each conductor of each terminal, of each element in the batch.

Original COM help: https://opendss.epri.com/Powers.html

RecloseIntervals: List[altdss.types.Float64Array]

‘property(…)’

Array of reclose intervals. If none, specify “NONE”. Default for overcurrent relay is (0.5, 2.0, 2.0) seconds. Default for a voltage relay is (5.0). In a voltage relay, this is seconds after restoration of voltage that the reclose occurs. Reverse power relay is one shot to lockout, so this is ignored. A locked out relay must be closed manually (set action=close).

DSS property name: RecloseIntervals, DSS property index: 16.

Reset: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Reset time in sec for relay. Default is 15. If this much time passes between the last pickup event, and the relay has not locked out, the operation counter resets.

DSS property name: Reset, DSS property index: 14.

SeqCurrents() → altdss.types.Float64Array

Array of symmetrical component currents (magnitudes only) into each 3-phase terminal of each element

Original COM help: https://opendss.epri.com/SeqCurrents.html

SeqPowers() → altdss.types.ComplexArray

Complex array of sequence powers (kW, kvar) into each 3-phase terminal of each element

Original COM help: https://opendss.epri.com/SeqPowers.html

SeqVoltages() → altdss.types.Float64Array

Double array of symmetrical component voltages (magnitudes only) at each 3-phase terminal

Original COM help: https://opendss.epri.com/SeqVoltages1.html

Shots: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

Number of shots to lockout. Default is 4. This is one more than the number of reclose intervals.

DSS property name: Shots, DSS property index: 15.

State: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

{Open | Closed} Actual state of the relay. Upon setting, immediately forces state of the relay, overriding the Relay control. Simulates manual control on relay. Defaults to Closed. “Open” causes the controlled element to open and lock out. “Closed” causes the controlled element to close and the relay to reset to its first operation.

DSS property name: State, DSS property index: 40.

State_str: List[str]

‘property(…)’

{Open | Closed} Actual state of the relay. Upon setting, immediately forces state of the relay, overriding the Relay control. Simulates manual control on relay. Defaults to Closed. “Open” causes the controlled element to open and lock out. “Closed” causes the controlled element to close and the relay to reset to its first operation.

DSS property name: State, DSS property index: 40.

SwitchedObj: List[altdss.DSSObj.DSSObj]

‘property(…)’

Name of circuit element switch that the Relay controls. Specify the full object name.Defaults to the same as the Monitored element. This is the “controlled” element.

DSS property name: SwitchedObj, DSS property index: 3.

SwitchedObj_str: List[str]

‘property(…)’

Name of circuit element switch that the Relay controls. Specify the full object name.Defaults to the same as the Monitored element. This is the “controlled” element.

DSS property name: SwitchedObj, DSS property index: 3.

SwitchedTerm: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

Number of the terminal of the controlled element in which the switch is controlled by the Relay. 1 or 2, typically. Default is 1.

DSS property name: SwitchedTerm, DSS property index: 4.

TDGround: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Time dial for Ground trip curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: TDGround, DSS property index: 11.

TDPhase: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Time dial for Phase trip curve. Multiplier on time axis of specified curve. Default=1.0.

DSS property name: TDPhase, DSS property index: 10.

TotalPowers() → altdss.types.ComplexArray

Returns an array with the total powers (complex, kVA) at all terminals of the circuit elements in this batch.

The resulting array is equivalent to concatenating the TotalPowers for each element.

Type: altdss.ArrayProxy.BatchInt32ArrayProxy

‘property(…)’

One of a legal relay type: Current Voltage Reversepower 46 (neg seq current) 47 (neg seq voltage) Generic (generic over/under relay) Distance TD21 DOC (directional overcurrent)

Default is overcurrent relay (Current) Specify the curve and pickup settings appropriate for each type. Generic relays monitor PC Element Control variables and trip on out of over/under range in definite time.

DSS property name: Type, DSS property index: 5.

Type_str: List[str]

‘property(…)’

One of a legal relay type: Current Voltage Reversepower 46 (neg seq current) 47 (neg seq voltage) Generic (generic over/under relay) Distance TD21 DOC (directional overcurrent)

Default is overcurrent relay (Current) Specify the curve and pickup settings appropriate for each type. Generic relays monitor PC Element Control variables and trip on out of over/under range in definite time.

DSS property name: Type, DSS property index: 5.

Undertrip: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Trip setting (low value) for Generic relay variable. Relay trips in definite time if value of variable is less than this value.

DSS property name: Undertrip, DSS property index: 27.

UndervoltCurve: List[altdss.TCC_Curve.TCC_Curve]

‘property(…)’

TCC Curve object to use for undervoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: UndervoltCurve, DSS property index: 19.

UndervoltCurve_str: List[str]

‘property(…)’

TCC Curve object to use for undervoltage relay. Curve is assumed to be defined with per unit voltage values. Voltage base should be defined for the relay. Default is none (ignored).

DSS property name: UndervoltCurve, DSS property index: 19.

Variable: List[str]

‘property(…)’

Name of variable in PC Elements being monitored. Only applies to Generic relay.

DSS property name: Variable, DSS property index: 25.

Voltages() → altdss.types.ComplexArray

Complex array of voltages at terminals

Original COM help: https://opendss.epri.com/Voltages1.html

VoltagesMagAng() → altdss.types.Float64Array

Voltages at each conductor in magnitude, angle form as array of doubles.

Original COM help: https://opendss.epri.com/VoltagesMagAng.html

Z0Ang: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Zero sequence reach impedance angle in degrees for Distance and TD21 functions. Default=68.0

DSS property name: Z0Ang, DSS property index: 33.

Z0Mag: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Zero sequence reach impedance in primary ohms for Distance and TD21 functions. Default=2.1

DSS property name: Z0Mag, DSS property index: 32.

Z1Ang: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Positive sequence reach impedance angle in degrees for Distance and TD21 functions. Default=64.0

DSS property name: Z1Ang, DSS property index: 31.

Z1Mag: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Positive sequence reach impedance in primary ohms for Distance and TD21 functions. Default=0.7

DSS property name: Z1Mag, DSS property index: 30.

__call__()

__getitem__(idx0) → altdss.DSSObj.DSSObj

Get element at 0-based index of the batch pointer array

__init__(api_util, **kwargs)

__iter__()

__len__() → int

batch(**kwargs) → altdss.Batch.DSSBatch

Filter a batch using integer or float DSS properties, returning a new batch.

For integers, provide a single value to match.

For floats, provide a range as a 2-valued tuple/list (min value, max value), or an exact value to value (not recommended).

Multiple properties can be listed to allow filtering various conditions.

Example for loads:

    # Create an initial batch using a regular expression
    abc_loads = altdss.Load.batch(re=r'^abc.*$') # a batch of all loads with names starting with "abc"
    abc_loads_filtered = abc_loads.batch(Class=1, Phases=1, kV=(0.1, 1.0))

    # Create an initial batch, already filtered
    abc_loads_filtered = altdss.Load.batch(re=r'^abc.*$', Class=1, Phases=1, kV=(0.1, 1.0))

begin_edit() → None

Marks for editing all DSS objects in the batch

In the editing mode, some final side-effects of changing properties are postponed until end_edit is called. This side-effects can be somewhat costly, like updating the model parameters or internal matrices.

If you don’t have any performance constraint, you may edit each property individually without worrying about using begin_edit and end_edit. For convenience, those are emitted automatically when editing single properties outside an edit block.

edit(**kwargs: typing_extensions.Unpack[altdss.Relay.RelayBatchProperties]) → altdss.Relay.RelayBatch

Edit this Relay batch.

This method will try to open a new edit context (if not already open), edit the properties, and finalize the edit context for objects in the batch. It can be seen as a shortcut to manually setting each property, or a Pythonic analogous (but extended) to the DSS BatchEdit command.

Parameters:

**kwargs – Pass keyword arguments equivalent to the DSS properties of the objects.

Returns:

Returns itself to allow call chaining.

end_edit(num_changes: int = 1) → None

Leaves the editing states of all DSS objects in the batch

num_changes is required for a few classes to correctly match the official OpenDSS behavior and must be the number of properties modified in the current editing block. As of DSS C-API v0.13, this is only required for the Monitor class, when the Action property is used with the Process value.

kVBase: altdss.ArrayProxy.BatchFloat64ArrayProxy

‘property(…)’

Voltage base (kV) for the relay. Specify line-line for 3 phase devices); line-neutral for 1-phase devices. Relay assumes the number of phases of the monitored element. Default is 0.0, which results in assuming the voltage values in the “TCC” curve are specified in actual line-to-neutral volts.

DSS property name: kVBase, DSS property index: 20.

to_json(options: Union[int, dss.enums.DSSJSONFlags] = 0)

Returns the data (as a list) of the elements in a batch as a JSON-encoded string.

The options parameter contains bit-flags to toggle specific features. See Obj_ToJSON (C-API) for more, or DSSObj.to_json in Python.

Additionally, the ExcludeDisabled flag can be used to excluded disabled elements from the output.

to_list()

class altdss.Relay.RelayBatchProperties

Bases: typing_extensions.TypedDict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

Action: Union[AnyStr, int, altdss.enums.RelayAction, List[AnyStr], List[int], List[altdss.enums.RelayAction], altdss.types.Int32Array]

None

BaseFreq: Union[float, altdss.types.Float64Array]

None

BreakerTime: Union[float, altdss.types.Float64Array]

None

DOC_DelayInner: Union[float, altdss.types.Float64Array]

None

DOC_P1Blocking: bool

None

DOC_PhaseCurveInner: Union[AnyStr, altdss.TCC_Curve.TCC_Curve, List[AnyStr], List[altdss.TCC_Curve.TCC_Curve]]

None

DOC_PhaseTripInner: Union[float, altdss.types.Float64Array]

None

DOC_TDPhaseInner: Union[float, altdss.types.Float64Array]

None

DOC_TiltAngleHigh: Union[float, altdss.types.Float64Array]

None

DOC_TiltAngleLow: Union[float, altdss.types.Float64Array]

None

DOC_TripSettingHigh: Union[float, altdss.types.Float64Array]

None

DOC_TripSettingLow: Union[float, altdss.types.Float64Array]

None

DOC_TripSettingMag: Union[float, altdss.types.Float64Array]

None

DebugTrace: bool

None

Delay: Union[float, altdss.types.Float64Array]

None

DistReverse: bool

None

Enabled: bool

None

EventLog: bool

None

F46BaseAmps: Union[float, altdss.types.Float64Array]

None

F46isqt: Union[float, altdss.types.Float64Array]

None

F46pctPickup: Union[float, altdss.types.Float64Array]

None

F47pctPickup: Union[float, altdss.types.Float64Array]

None

GroundCurve: Union[AnyStr, altdss.TCC_Curve.TCC_Curve, List[AnyStr], List[altdss.TCC_Curve.TCC_Curve]]

None

GroundInst: Union[float, altdss.types.Float64Array]

None

GroundTrip: Union[float, altdss.types.Float64Array]

None

Like: AnyStr

None

MGround: Union[float, altdss.types.Float64Array]

None

MPhase: Union[float, altdss.types.Float64Array]

None

MonitoredObj: Union[AnyStr, altdss.DSSObj.DSSObj, List[AnyStr], List[altdss.DSSObj.DSSObj]]

None

MonitoredTerm: Union[int, altdss.types.Int32Array]

None

Normal: Union[AnyStr, int, altdss.enums.RelayState, List[AnyStr], List[int], List[altdss.enums.RelayState], altdss.types.Int32Array]

None

Overtrip: Union[float, altdss.types.Float64Array]

None

OvervoltCurve: Union[AnyStr, altdss.TCC_Curve.TCC_Curve, List[AnyStr], List[altdss.TCC_Curve.TCC_Curve]]

None

PhaseCurve: Union[AnyStr, altdss.TCC_Curve.TCC_Curve, List[AnyStr], List[altdss.TCC_Curve.TCC_Curve]]

None

PhaseInst: Union[float, altdss.types.Float64Array]

None

PhaseTrip: Union[float, altdss.types.Float64Array]

None

RecloseIntervals: altdss.types.Float64Array

None

Reset: Union[float, altdss.types.Float64Array]

None

Shots: Union[int, altdss.types.Int32Array]

None

State: Union[AnyStr, int, altdss.enums.RelayState, List[AnyStr], List[int], List[altdss.enums.RelayState], altdss.types.Int32Array]

None

SwitchedObj: Union[AnyStr, altdss.DSSObj.DSSObj, List[AnyStr], List[altdss.DSSObj.DSSObj]]

None

SwitchedTerm: Union[int, altdss.types.Int32Array]

None

TDGround: Union[float, altdss.types.Float64Array]

None

TDPhase: Union[float, altdss.types.Float64Array]

None

Type: Union[AnyStr, int, altdss.enums.RelayType, List[AnyStr], List[int], List[altdss.enums.RelayType], altdss.types.Int32Array]

None

Undertrip: Union[float, altdss.types.Float64Array]

None

UndervoltCurve: Union[AnyStr, altdss.TCC_Curve.TCC_Curve, List[AnyStr], List[altdss.TCC_Curve.TCC_Curve]]

None

Variable: Union[AnyStr, List[AnyStr]]

None

Z0Ang: Union[float, altdss.types.Float64Array]

None

Z0Mag: Union[float, altdss.types.Float64Array]

None

Z1Ang: Union[float, altdss.types.Float64Array]

None

Z1Mag: Union[float, altdss.types.Float64Array]

None

__contains__()

True if the dictionary has the specified key, else False.

__delattr__()

Implement delattr(self, name).

__delitem__()

Delete self[key].

__dir__()

Default dir() implementation.

__format__()

Default object formatter.

Return str(self) if format_spec is empty. Raise TypeError otherwise.

__ge__()

Return self>=value.

__getattribute__()

Return getattr(self, name).

__getitem__()

Return self[key].

__getstate__()

Helper for pickle.

__gt__()

Return self>value.

__init__()

Initialize self. See help(type(self)) for accurate signature.

__ior__()

Return self|=value.

__iter__()

Implement iter(self).

__le__()

Return self<=value.

__len__()

Return len(self).

__lt__()

Return self<value.

__ne__()

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__or__()

Return self|value.

__reduce__()

Helper for pickle.

__reduce_ex__()

Helper for pickle.

__repr__()

Return repr(self).

__reversed__()

Return a reverse iterator over the dict keys.

__ror__()

Return value|self.

__setitem__()

Set self[key] to value.

__sizeof__()

D.sizeof() -> size of D in memory, in bytes

__str__()

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.subclasscheck(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

clear()

D.clear() -> None. Remove all items from D.

copy()

D.copy() -> a shallow copy of D

get()

Return the value for key if key is in the dictionary, else default.

items()

D.items() -> a set-like object providing a view on D’s items

kVBase: Union[float, altdss.types.Float64Array]

None

keys()

D.keys() -> a set-like object providing a view on D’s keys

pop()

D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault()

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update()

D.update([E, ]**F) -> None. Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()

D.values() -> an object providing a view on D’s values

class altdss.Relay.RelayProperties

Bases: typing_extensions.TypedDict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

Action: Union[AnyStr, int, altdss.enums.RelayAction]

None

BaseFreq: float

None

BreakerTime: float

None

DOC_DelayInner: float

None

DOC_P1Blocking: bool

None

DOC_PhaseCurveInner: Union[AnyStr, altdss.TCC_Curve.TCC_Curve]

None

DOC_PhaseTripInner: float

None

DOC_TDPhaseInner: float

None

DOC_TiltAngleHigh: float

None

DOC_TiltAngleLow: float

None

DOC_TripSettingHigh: float

None

DOC_TripSettingLow: float

None

DOC_TripSettingMag: float

None

DebugTrace: bool

None

Delay: float

None

DistReverse: bool

None

Enabled: bool

None

EventLog: bool

None

F46BaseAmps: float

None

F46isqt: float

None

F46pctPickup: float

None

F47pctPickup: float

None

GroundCurve: Union[AnyStr, altdss.TCC_Curve.TCC_Curve]

None

GroundInst: float

None

GroundTrip: float

None

Like: AnyStr

None

MGround: float

None

MPhase: float

None

MonitoredObj: Union[AnyStr, altdss.DSSObj.DSSObj]

None

MonitoredTerm: int

None

Normal: Union[AnyStr, int, altdss.enums.RelayState]

None

Overtrip: float

None

OvervoltCurve: Union[AnyStr, altdss.TCC_Curve.TCC_Curve]

None

PhaseCurve: Union[AnyStr, altdss.TCC_Curve.TCC_Curve]

None

PhaseInst: float

None

PhaseTrip: float

None

RecloseIntervals: altdss.types.Float64Array

None

Reset: float

None

Shots: int

None

State: Union[AnyStr, int, altdss.enums.RelayState]

None

SwitchedObj: Union[AnyStr, altdss.DSSObj.DSSObj]

None

SwitchedTerm: int

None

TDGround: float

None

TDPhase: float

None

Type: Union[AnyStr, int, altdss.enums.RelayType]

None

Undertrip: float

None

UndervoltCurve: Union[AnyStr, altdss.TCC_Curve.TCC_Curve]

None

Variable: AnyStr

None

Z0Ang: float

None

Z0Mag: float

None

Z1Ang: float

None

Z1Mag: float

None

__contains__()

True if the dictionary has the specified key, else False.

__delattr__()

Implement delattr(self, name).

__delitem__()

Delete self[key].

__dir__()

Default dir() implementation.

__format__()

Default object formatter.

Return str(self) if format_spec is empty. Raise TypeError otherwise.

__ge__()

Return self>=value.

__getattribute__()

Return getattr(self, name).

__getitem__()

Return self[key].

__getstate__()

Helper for pickle.

__gt__()

Return self>value.

__init__()

Initialize self. See help(type(self)) for accurate signature.

__ior__()

Return self|=value.

__iter__()

Implement iter(self).

__le__()

Return self<=value.

__len__()

Return len(self).

__lt__()

Return self<value.

__ne__()

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__or__()

Return self|value.

__reduce__()

Helper for pickle.

__reduce_ex__()

Helper for pickle.

__repr__()

Return repr(self).

__reversed__()

Return a reverse iterator over the dict keys.

__ror__()

Return value|self.

__setitem__()

Set self[key] to value.

__sizeof__()

D.sizeof() -> size of D in memory, in bytes

__str__()

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.subclasscheck(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

clear()

D.clear() -> None. Remove all items from D.

copy()

D.copy() -> a shallow copy of D

get()

Return the value for key if key is in the dictionary, else default.

items()

D.items() -> a set-like object providing a view on D’s items

kVBase: float

None

keys()

D.keys() -> a set-like object providing a view on D’s keys

pop()

D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault()

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update()

D.update([E, ]**F) -> None. Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()

D.values() -> an object providing a view on D’s values