altdss.Settings

Module Contents

Classes

ISettings

API

class altdss.Settings.ISettings(api_util, prefer_lists=False)

Bases: altdss.common.Base

property AdvancedTypes: bool

When enabled, there are two side-effects:

• Per DSS Context: Complex arrays and complex numbers can be returned and consumed by the Python API.

• Global effect: The low-level API provides matrix dimensions when available (EnableArrayDimensions is enabled).

As a result, for example, DSS.ActiveCircuit.ActiveCktElement.Yprim is returned as a complex matrix instead of a plain array.

When disabled, the legacy plain arrays are used and complex numbers cannot be consumed by the Python API.

Defaults to False for backwards compatibility.

(API Extension)

property AllocationFactors

(write-only) Sets all load allocation factors for all loads defined by XFKVA property to this value.

property AllowChangeDir: bool

If disabled, the engine will not change the active working directory during execution. E.g. a “compile” command will not “chdir” to the file path.

If you have issues with long paths, enabling this might help in some scenarios.

Defaults to True (allow changes, backwards compatible) in the 0.10.x versions of DSS C-API. This might change to False in future versions.

This can also be set through the environment variable DSS_CAPI_ALLOW_CHANGE_DIR. Set it to 0 to disallow changing the active working directory.

(API Extension)

property AllowDOScmd: bool

If enabled, the DOScmd command is allowed. Otherwise, an error is reported if the user tries to use it.

Defaults to False/0 (disabled state). Users should consider DOScmd deprecated on DSS-Extensions.

This can also be set through the environment variable DSS_CAPI_ALLOW_DOSCMD. Setting it to 1 enables the command.

(API Extension)

property AllowDuplicates: bool

Designates whether to allow duplicate names of objects

NOTE: for DSS-Extensions, we are considering removing this option in a future release since it has performance impacts even when not used.

property AllowEditor: bool

Gets/sets whether running the external editor for “Show” is allowed

AllowEditor controls whether the external editor is used in commands like “Show”. If you set to 0 (false), the editor is not executed. Note that other side effects, such as the creation of files, are not affected.

(API Extension)

property AllowForms: bool

Gets/sets whether text output is allowed

property AutoBusList: str

List of Buses or (File=xxxx) syntax for the AutoAdd solution mode.

property COMErrorResults: bool

If enabled, in case of errors or empty arrays, the API returns arrays with values compatible with the official OpenDSS COM interface.

For example, consider the function Loads_Get_ZIPV. If there is no active circuit or active load element:

• In the disabled state (COMErrorResults=False), the function will return “[]”, an array with 0 elements.

• In the enabled state (COMErrorResults=True), the function will return “[0.0]” instead. This should be compatible with the return value of the official COM interface.

Defaults to True/1 (enabled state) in the v0.12.x series. This will change to false in future series.

This can also be set through the environment variable DSS_CAPI_COM_DEFAULTS. Setting it to 0 disables the legacy/COM behavior. The value can be toggled through the API at any time.

(API Extension)

property CktModel: int

{dssMultiphase (0) * | dssPositiveSeq (1) } Indicate if the circuit model is positive sequence.

property CompatFlags: int

Controls some compatibility flags introduced to toggle some behavior from the official OpenDSS.

THESE FLAGS ARE GLOBAL, affecting all DSS engines in the process.

The current bit flags are:

• 0x1 (bit 0): 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.

• 0x2 (bit 1): 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.

• 0x4 (bit 2): 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.

These flags may change for each version of DSS C-API, but the same value will not be reused. That is, when we remove a compatibility flag, it will have no effect but will also not affect anything else besides raising an error if the user tries to toggle a flag that was available in a previous version.

We expect to keep a very limited number of flags. Since the flags are more transient than the other options/flags, it was preferred to add this generic function instead of a separate function per flag.

Related enumeration: DSSCompatFlags

(API Extension)

property ControlTrace: bool

{True | False*} Denotes whether to trace the control actions to a file.

property DataPath: str

DSS Data File Path. Default path for reports, etc. from DSS

property DefaultEditor: str

Returns the path name for the default text editor.

property EmergVmaxpu: float

Per Unit maximum voltage for Emergency conditions.

property EmergVminpu: float

Per Unit minimum voltage for Emergency conditions.

property IterateDisabled: int

Controls whether First/Next iteration includes or skips disabled circuit elements. The default behavior from OpenDSS is to skip those. The user can still activate the element by name or index.

The default value for IterateDisabled is 0, keeping the original behavior. Set it to 1 (or True) to include disabled elements. Other numeric values are reserved for other potential behaviors.

(API Extension)

property LoadsTerminalCheck: bool

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

(API Extension)

property LossRegs: altdss.types.Int32Array

Integer array defining which energy meter registers to use for computing losses

property LossWeight: float

Weighting factor applied to Loss register values.

property NormVmaxpu: float

Per Unit maximum voltage for Normal conditions.

property NormVminpu: float

Per Unit minimum voltage for Normal conditions.

property PriceCurve: str

Name of LoadShape object that serves as the source of price signal data for yearly simulations, etc.

property PriceSignal: float

Price Signal for the Circuit

SetPropertyNameStyle(value: dss.enums.DSSPropertyNameStyle)

Switch the property names according

property Trapezoidal: bool

Gets value of trapezoidal integration flag in energy meters. Defaults to False.

property UEregs: altdss.types.Int32Array

Array of Integers defining energy meter registers to use for computing UE

property UEweight: float

Weighting factor applied to UE register values.

property VoltageBases: altdss.types.Float64Array

Array of doubles defining the legal voltage bases in kV L-L

property ZoneLock: bool

{True | False*} Locks Zones on energy meters to prevent rebuilding if a circuit change occurs.

__init__(api_util, prefer_lists=False)