Module Contents#




class dss.ICircuit.ICircuit(api_util)#

Bases: dss._cffi_api_util.Base

ActiveBus: dss.IBus.IBus#


ActiveCktElement: dss.ICktElement.ICktElement#


ActiveClass: dss.IActiveClass.IActiveClass#


ActiveDSSElement: dss.IDSSElement.IDSSElement#


ActiveElement: dss.ICktElement.ICktElement#


property AllBusDistances: dss._types.Float64Array#

Returns distance from each bus to parent EnergyMeter. Corresponds to sequence in AllBusNames.

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

property AllBusNames: List[str]#

Array of strings containing names of all buses in circuit (see AllNodeNames).

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

property AllBusVmag: dss._types.Float64Array#

Array of magnitudes (doubles) of voltages at all buses

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

property AllBusVmagPu: dss._types.Float64Array#

Double Array of all bus voltages (each node) magnitudes in Per unit

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

property AllBusVolts: dss._types.Float64ArrayOrComplexArray#

Complex array of all bus, node voltages from most recent solution

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

property AllElementLosses: dss._types.Float64ArrayOrComplexArray#

Array of total losses (complex) in each circuit element

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

property AllElementNames: List[str]#

Array of strings containing Full Name of all elements.

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

property AllNodeDistances: dss._types.Float64Array#

Returns an array of distances from parent EnergyMeter for each Node. Corresponds to AllBusVMag sequence.

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

AllNodeDistancesByPhase(Phase: int) dss._types.Float64Array#

Returns an array of doubles representing the distances to parent EnergyMeter. Sequence of array corresponds to other node ByPhase properties.

property AllNodeNames: List[str]#

Array of strings containing full name of each node in system in same order as returned by AllBusVolts, etc.

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

AllNodeNamesByPhase(Phase: int) List[str]#

Return array of strings of the node names for the By Phase criteria. Sequence corresponds to other ByPhase properties.

AllNodeVmagByPhase(Phase: int) dss._types.Float64Array#

Returns Array of doubles represent voltage magnitudes for nodes on the specified phase.

AllNodeVmagPUByPhase(Phase: int) dss._types.Float64Array#

Returns array of per unit voltage magnitudes for each node by phase

Buses: dss.IBus.IBus#


CNData: dss.ICNData.ICNData#


CapControls: dss.ICapControls.ICapControls#


Capacitors: dss.ICapacitors.ICapacitors#


Capacity(Start: float, Increment: float) float#

Compute the maximum load the active circuit can serve in the PRESENT YEAR.

This method uses the EnergyMeter objects with the registers set with the SET UEREGS= (...) command for the AutoAdd functions.

Returns the metered kW (load + losses - generation) and per unit load multiplier for the loading level at which something in the system reports an overload or undervoltage. If no violations, then it returns the metered kW for peak load for the year (1.0 multiplier).

Aborts and returns 0 if no EnergyMeters.

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

CktElements: dss.ICktElement.ICktElement#


CtrlQueue: dss.ICtrlQueue.ICtrlQueue#


DSSim_Coms: dss.IDSSimComs.IDSSimComs#


Disable(Name: AnyStr)#

Disable a circuit element by name (removes from circuit but leave in database).

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

ElementLosses(Value: dss._types.Int32Array) dss._types.Float64ArrayOrComplexArray#

Array of total losses (complex) in a selection of elements. Use the element indices (starting at 1) as parameter.

(API Extension)

Enable(Name: AnyStr)#

Enable a circuit element by name

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


Call EndOfTimeStepCleanup in SolutionAlgs (Do cleanup, sample monitors, and increment time).

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

FirstElement() int#

Set the first element of active class to be the Active element in the active circuit.

Returns 0 if none.

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

FirstPCElement() int#

Set the first Power Conversion (PC) element to be the active element.

Returns 0 if none.

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

FirstPDElement() int#

Set the first Power Delivery (PD) element to be the active element.

Returns 0 if none.

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

FromJSON(data: Union[AnyStr, dict], options: dss.enums.DSSJSONFlags = 0)#

Replaces the circuit, if any, with the one provided from a JSON-encoded string. If a Python dict is provided, json.dumps(data) is applied first.

The expected layout is defined from the JSON schema proposed at dss-extensions/AltDSS-Schema

The options parameter contains bit-flags to toggle specific features. See the enum DSSJSONFlags.

(API Extension)

Fuses: dss.IFuses.IFuses#


GICSources: dss.IGICSources.IGICSources#


Generators: dss.IGenerators.IGenerators#


ISources: dss.IISources.IISources#


Isources: dss.IISources.IISources#


LineCodes: dss.ILineCodes.ILineCodes#


LineGeometries: dss.ILineGeometries.ILineGeometries#


property LineLosses: dss._types.Float64ArrayOrSimpleComplex#

Complex total line losses in the circuit

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

LineSpacings: dss.ILineSpacings.ILineSpacings#


Lines: dss.ILines.ILines#


LoadShapes: dss.ILoadShapes.ILoadShapes#


Loads: dss.ILoads.ILoads#


property Losses: dss._types.Float64ArrayOrSimpleComplex#

Total losses in active circuit, complex number (two-element array of double).

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

Meters: dss.IMeters.IMeters#


Monitors: dss.IMonitors.IMonitors#


property Name: str#

Name of the active circuit.

NextElement() int#

Set the next element of the active class to be the active element in the active circuit. Returns 0 if no more elements..

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

NextPCElement() int#

Get the next Power Conversion (PC) element to be the active element.

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

NextPDElement() int#

Get the next Power Delivery (PD) element to be the active element.

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

property NumBuses: int#

Total number of Buses in the circuit.

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

property NumCktElements: int#

Number of CktElements in the circuit.

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

property NumNodes: int#

Total number of nodes in the circuit.

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

PDElements: dss.IPDElements.IPDElements#


PVSystems: dss.IPVSystems.IPVSystems#


Parallel: dss.IParallel.IParallel#


property ParentPDElement: int#

Sets Parent PD element, if any, to be the active circuit element and returns index>0; Returns 0 if it fails or not applicable.

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

Reactors: dss.IReactors.IReactors#


Reclosers: dss.IReclosers.IReclosers#


ReduceCkt: dss.IReduceCkt.IReduceCkt#


RegControls: dss.IRegControls.IRegControls#


Relays: dss.IRelays.IRelays#



Force all Meters and Monitors to take a sample.

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

Save(dirOrFilePath: AnyStr, options: dss.enums.DSSSaveFlags) str#

Equivalent of the “save circuit” DSS command, but allows customization through the saveFlags argument, which is a set of bit flags. See the “DSSSaveFlags” enumeration for available flags:

  • CalcVoltageBases: Include the command CalcVoltageBases.

  • SetVoltageBases: Include commands to set the voltage bases individually.

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

  • IncludeDisabled: Include disabled circuit elements (and LoadShapes).

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

  • SingleFile: Use a single file instead of a folder for output.

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

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

  • IsOpen: Export commands to open terminals of elements.

  • ToString: to the result string. Requires “SingleFile” flag.

If SingleFile is enabled, the first argument (dirOrFilePath) is the file path, otherwise it is the folder path. For string output, the argument is not used.

(API Extension)


Force all meters and monitors to save their current buffers.

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

Sensors: dss.ISensors.ISensors#


SetActiveBus(BusName: AnyStr) int#

Sets Active bus by name.

Ignores node list. Returns bus index (zero based) compatible with AllBusNames and Buses collection.

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

SetActiveBusi(BusIndex: int) int#

Set ActiveBus by an integer value.

0-based index compatible with SetActiveBus return value and AllBusNames indexing. Returns 0 if OK.

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

SetActiveClass(ClassName: AnyStr) int#

Set the active class by name.

Use FirstElement, NextElement to iterate through the class. Returns -1 if fails.

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

SetActiveElement(FullName: AnyStr) int#

Set the Active Circuit Element using the full object name (e.g. “generator.g1”).

Returns -1 if not found. Else index to be used in CktElements collection or AllElementNames.

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

Settings: dss.ISettings.ISettings#


Solution: dss.ISolution.ISolution#


Storages: dss.IStorages.IStorages#


property SubstationLosses: dss._types.Float64ArrayOrSimpleComplex#

Complex losses in all transformers designated to substations.

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

SwtControls: dss.ISwtControls.ISwtControls#


property SystemY: dss._types.Float64ArrayOrComplexArray#

(read-only) System Y matrix (after a solution has been performed). This is deprecated as it returns a dense matrix. Only use it for small systems. For large-scale systems, prefer YMatrix.GetCompressedYMatrix.

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

TSData: dss.ITSData.ITSData#


ToJSON(options: dss.enums.DSSJSONFlags = 0) str#

Returns data for all objects and basic circuit properties as a JSON-encoded string.

The JSON data is organized using the JSON schema proposed at dss-extensions/AltDSS-Schema

The options parameter contains bit-flags to toggle specific features. See the enum DSSJSONFlags or Obj_ToJSON (C-API) for more.

(API Extension)

Topology: dss.ITopology.ITopology#


property TotalPower: dss._types.Float64ArrayOrSimpleComplex#

Total power (complex), kVA delivered to the circuit

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

Transformers: dss.ITransformers.ITransformers#



Force an update to all storage classes.

Typically done after a solution. Done automatically in intrinsic solution modes.

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

Vsources: dss.IVsources.IVsources#


WireData: dss.IWireData.IWireData#


XYCurves: dss.IXYCurves.IXYCurves#


property YCurrents: dss._types.Float64ArrayOrComplexArray#

Array of doubles containing complex injection currents for the present solution. It is the “I” vector of I=YV

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

property YNodeOrder: List[str]#

Array of strings containing the names of the nodes in the same order as the Y matrix

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

property YNodeVarray: dss._types.Float64ArrayOrComplexArray#

Complex array of actual node voltages in same order as SystemY matrix.

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