Ctrl+K

dss.IDSS

dss.IDSS#

Module Contents#

Classes#

IDSS

Main OpenDSS interface. Organizes the subclasses trying to mimic the OpenDSSengine.DSS object as seen from win32com.client or comtypes.client.

API#

class dss.IDSS.IDSS(api_util)#

Bases: dss._cffi_api_util.Base

Main OpenDSS interface. Organizes the subclasses trying to mimic the OpenDSSengine.DSS object as seen from win32com.client or comtypes.client.

This main class also includes some global settings. See more settings in ActiveCircuit.Settings.

ActiveCircuit: dss.ICircuit.ICircuit#

None

ActiveClass: dss.IActiveClass.IActiveClass#

None

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 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 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 (DSS-Extensions) or general forms/windows are shown (official OpenDSS).

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

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)

Circuits: dss.ICircuit.ICircuit#

None

property Classes: List[str]#

List of DSS intrinsic classes (names of the classes)

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

ClearAll()#
property CompatFlags: int#

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

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

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.

See the enumeration DSSCompatFlags for available flags, including description.

(API Extension)

DSSProgress: dss.IDSSProgress.IDSSProgress#

None

DSSim_Coms: dss.IDSSimComs.IDSSimComs#

None

property DataPath: str#

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

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

property DefaultEditor: str#

Returns the path name for the default text editor.

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

Error: dss.IError.IError#

None

Events: dss.IDSSEvents.IDSSEvents#

None

Executive: dss.IDSS_Executive.IDSS_Executive#

None

property LegacyModels: bool#

LegacyModels was a flag used to toggle legacy (pre-2019) models for PVSystem, InvControl, Storage and StorageControl. In the official OpenDSS version 9.0, the old models were removed. They were temporarily present here but were also removed in DSS C-API v0.13.0.

NOTE: this property will be removed for v1.0. It is left to avoid breaking the current API too soon.

(API Extension)

NewCircuit(name) → dss.ICircuit.ICircuit#

Make a new circuit and returns the interface to the active circuit.

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

NewContext() → dss.IDSS.IDSS#

Creates a new DSS engine context.

A DSS Context encapsulates most of the global state of the original OpenDSS engine, allowing the user to create multiple instances in the same process. By creating contexts manually, the management of threads and potential issues should be handled by the user.

(API Extension)

property NumCircuits: int#

Number of Circuits currently defined

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

property NumClasses: int#

Number of DSS intrinsic classes

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

property NumUserClasses: int#

Number of user-defined classes

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

property Obj: altdss.AltDSS#

Deprecated: provides access to the AltDSS API; use DSS.to_altdss() instead

(API Extension)

Parser: dss.IParser.IParser#

None

property Plotting#

Shortcut for the plotting module. This property is equivalent to:

from dss import plot
return plot

Gives access to the enable() and disable() functions. Requires matplotlib and SciPy to be installed, hence it is an optional feature.

(API Extension)

Reset()#

This is a no-op function, does nothing. Left for compatibility.

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

SetActiveClass(ClassName: AnyStr) → int#
ShowPanel()#
Start(code: int) → bool#

This is a no-op function, does nothing. Left for compatibility.

Calling Start in AltDSS/DSS-Extensions is required but that is already handled automatically, so the users do not need to call it manually, unless using AltDSS/DSS C-API directly without further tools.

On the official OpenDSS, Start also does nothing at all in the current versions.

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

Text: dss.IText.IText#

None

property UserClasses: List[str]#

List of user-defined classes

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

property Version: str#

Get version string for the DSS.

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

YMatrix: dss.IYMatrix.IYMatrix#

None

ZIP: dss.IZIP.IZIP#

None

__call__(cmds: Union[AnyStr, List[AnyStr]])#

Shortcut to pass text commands.

Pass either a single string (with either one or multiples commands, separated by new lines), or a list of strings.

Examples:

# single command
DSS("new Circuit.test") 

# list of commands
DSS(["new Circuit.test", "new Line.line1 bus1=a bus2=b"])

# block of commands in a big string
DSS("""
    clear
    new Circuit.test
    new Line.line1 bus1=a bus2=b
    new Load.load1 bus1=a bus2=b
""")

(API Extension)

__init__(api_util)#

Wrap a new DSS context with the DSS-Python API. This is not typically used directly. Refer to IDSS.NewContext or IDSS._get_instance.

to_altdss() → altdss.AltDSS#

Returns an instance of AltDSS for the active DSS Context.

A compatible AltDSS (pip install altdss) is required.

to_opendssdirect() → opendssdirect.OpenDSSDirect.OpenDSSDirect#

Returns an instance of OpenDSSDirect.py for the active DSS Context.

A compatible OpenDSSDirect.py (pip install OpenDSSDirect.py) is required.

Contents