Expose GICSources and other DSS C-API features

- Bus: ZSC012Matrix
- Circuit: ElementLosses
- DSS: AllowDOScmd, COMErrorResults, `__call__`
- Fuses: State, NormalState
- LineGeometries: Nconds
- Loads: Sensor
- LoadShapes: UseFloat32, UseFloat64
- PVSystems: Sensor
- Reclosers: State, NormalState
- Relays: State, NormalState
- Sensors: AllocationFactor
- Text: Commands
- WireData: CapRadius
- YMatrix: SetGeneratordQdV, Iteration

Author: PMeira

dss/dss_capi_gr/IBus.py

@@ -206,6 +206,12 @@ def puVoltages(self):
         self.CheckForError(self._lib.Bus_Get_puVoltages_GR())
         return self._get_float64_gr_array()
 
+    @property
+    def ZSC012Matrix(self):
+        '''Array of doubles (complex) containing the complete 012 Zsc matrix'''
+        self.CheckForError(self._lib.Bus_Get_ZSC012Matrix_GR())
+        return self._get_float64_gr_array()
+
     @property
     def x(self):
         '''X Coordinate for bus (double)'''

dss/dss_capi_gr/ICircuit.py

@@ -46,6 +46,7 @@
 from .IParallel import IParallel
 from .IReduceCkt import IReduceCkt
 from .IStorages import IStorages
+from .IGICSources import IGICSources
 
 class ICircuit(Base):
     __slots__ = [
@@ -91,7 +92,8 @@ class ICircuit(Base):
         'Reactors',
         'Parallel',
         'ReduceCkt',
-        'Storages'
+        'Storages',
+        'GICSources',
     ]
 
     _columns = [
@@ -165,6 +167,7 @@ def __init__(self, api_util):
         self.Reactors = IReactors(api_util)
         self.ReduceCkt = IReduceCkt(api_util) #: Circuit Reduction Interface
         self.Storages = IStorages(api_util)
+        self.GICSources = IGICSources(api_util)
 
         if hasattr(api_util.lib, 'Parallel_CreateActor'):
             self.Parallel = IParallel(api_util)
@@ -384,3 +387,14 @@ def YNodeVarray(self):
         '''(read-only) Complex array of actual node voltages in same order as SystemY matrix.'''
         self.CheckForError(self._lib.Circuit_Get_YNodeVarray_GR())
         return self._get_float64_gr_array()
+
+    def ElementLosses(self, Value):
+        '''
+        Array of total losses (complex) in a selection of elements.
+        Use the element indices (starting at 1) as parameter.
+
+        (API Extension)
+        '''
+        Value, ValuePtr, ValueCount = self._prepare_int32_array(Value)
+        self.CheckForError(self._lib.Circuit_Get_ElementLosses_GR(ValuePtr, ValueCount))        
+        return self._get_float64_gr_array()

dss/dss_capi_gr/ICktElement.py

@@ -130,7 +130,7 @@ def AllVariableValues(self):
     @property
     def BusNames(self):
         '''
-        Array of strings. Get  Bus definitions to which each terminal is connected. 0-based array.
+        Array of strings. Get  Bus definitions to which each terminal is connected.
         '''
         return self.CheckForError(self._get_string_array(self._lib.CktElement_Get_BusNames))
 

dss/dss_capi_gr/IDSS.py

@@ -5,7 +5,7 @@
 Copyright (c) 2018-2022 DSS Extensions contributors
 '''
 import warnings
-from .._cffi_api_util import Base, CffiApiUtil
+from .._cffi_api_util import Base, CffiApiUtil, DSSException
 from .ICircuit import ICircuit
 from .IError import IError
 from .IText import IText
@@ -216,6 +216,48 @@ def AllowChangeDir(self):
     def AllowChangeDir(self, Value):
         self.CheckForError(self._lib.DSS_Set_AllowChangeDir(Value))
 
+    @property
+    def AllowDOScmd(self):
+        '''
+        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)
+        '''
+        return self.CheckForError(self._lib.DSS_Get_AllowDOScmd()) != 0
+
+    @AllowDOScmd.setter
+    def AllowDOScmd(self, Value):
+        self.CheckForError(self._lib.DSS_Set_AllowDOScmd(Value))
+
+    @property
+    def COMErrorResults(self):
+        '''
+        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)
+        '''
+        return self.CheckForError(self._lib.DSS_Get_COMErrorResults()) != 0
+
+    @COMErrorResults.setter
+    def COMErrorResults(self, Value):
+        self.CheckForError(self._lib.DSS_Set_COMErrorResults(Value))
+
     def NewContext(self):
         '''
         Creates a new DSS engine context.
@@ -230,3 +272,43 @@ def NewContext(self):
         new_ctx = lib.ctx_New()
         new_api_util = CffiApiUtil(ffi, lib, new_ctx)
         return IDSS(new_api_util)
+
+    def __call__(self, single=None, block=None):
+        '''
+        Shortcut to pass text commands.
+
+        If `single` is set and is a string, a normal `DSS.Text.Command = single` is called.
+        Otherwise, the value is passed to `DSS.Text.Commands`.
+
+        Examples:
+
+            # single command
+            DSS("new Circuit.test") 
+            DSS(single="new Circuit.test")
+
+            # list of commands (either will work)
+            DSS(["new Circuit.test", "new Line.line1 bus1=a bus2=b"])
+            DSS(single=["new circuit.test", "new Line.line1 bus1=a bus2=b"])
+            DSS(block=["new circuit.test", "new Line.line1 bus1=a bus2=b"])
+
+            # block of commands in a big string
+            DSS(block="""
+                clear
+                new Circuit.test
+                new Line.line1 bus1=a bus2=b
+                new Load.load1 bus1=a bus2=b
+            """)
+
+        (API Extension)
+        '''
+        if (single is not None) and (block is not None):
+           raise DSSException("Only a single argument is accepted.")
+
+        if (single is None) and (block is None):
+           raise DSSException("A value is required.")
+
+        if single is not None:
+            self.Text.Command = single
+            return
+
+        self.Text.Commands(single or block)

dss/dss_capi_gr/IFuses.py

@@ -21,18 +21,27 @@ class IFuses(Iterable):
         'RatedCurrent',
         'SwitchedObj',
         'SwitchedTerm',
+        'State',
+        'NormalState',
     ]
 
 
     def Close(self):
+        '''Close all phases of the fuse.'''
         self.CheckForError(self._lib.Fuses_Close())
 
     def IsBlown(self):
+        '''Current state of the fuses. TRUE if any fuse on any phase is blown. Else FALSE.'''
         return self.CheckForError(self._lib.Fuses_IsBlown()) != 0
 
     def Open(self):
+        '''Manual opening of all phases of the fuse.'''
         self.CheckForError(self._lib.Fuses_Open())
 
+    def Reset(self):
+        '''Reset fuse to normal state.'''
+        self.CheckForError(self._lib.Fuses_Reset())
+
     @property
     def Delay(self):
         '''
@@ -120,3 +129,23 @@ def TCCcurve(self, Value):
             Value = Value.encode(self._api_util.codec)
 
         self.CheckForError(self._lib.Fuses_Set_TCCcurve(Value))
+
+    @property
+    def State(self):
+        '''Array of strings indicating the state of each phase of the fuse.'''
+        return self.CheckForError(self._get_string_array(self._lib.Fuses_Get_State))
+
+    @State.setter
+    def State(self, Value):
+        Value, ValuePtr, ValueCount = self._prepare_string_array(Value)
+        self.CheckForError(self._lib.Fuses_Set_State(ValuePtr, ValueCount))
+
+    @property
+    def NormalState(self):
+        '''Array of strings indicating the normal state of each phase of the fuse.'''
+        return self.CheckForError(self._get_string_array(self._lib.Fuses_Get_NormalState))
+
+    @NormalState.setter
+    def NormalState(self, Value):
+        Value, ValuePtr, ValueCount = self._prepare_string_array(Value)
+        self.CheckForError(self._lib.Fuses_Set_NormalState(ValuePtr, ValueCount))

dss/dss_capi_gr/ILineGeometries.py

@@ -14,6 +14,7 @@ class ILineGeometries(Iterable):
     _columns = [
         'Name',
         'idx',
+        'Nconds',
         'Phases',
         'RhoEarth',
         'Reduce',
@@ -128,3 +129,11 @@ def Ycoords(self, Value):
         Value, ValuePtr, ValueCount = self._prepare_float64_array(Value)
         self.CheckForError(self._lib.LineGeometries_Set_Ycoords(ValuePtr, ValueCount))
 
+    @property
+    def Nconds(self):
+        '''Number of conductors in this geometry. Default is 3. Triggers memory allocations. Define first!'''
+        return self.CheckForError(self._lib.LineGeometries_Get_Nconds())
+
+    @Nconds.setter
+    def Nconds(self, Value):
+        self.CheckForError(self._lib.LineGeometries_Set_Nconds(Value))

dss/dss_capi_gr/ILoadShapes.py

@@ -133,3 +133,21 @@ def sInterval(self, Value):
 
     Sinterval = sInterval
     SInterval = sInterval
+
+    def UseFloat32(self):
+        '''
+        Converts the current LoadShape data to float32/single precision.
+        If there is no data or the data is already represented using float32, nothing is done.
+
+        (API Extension)
+        '''
+        self.CheckForError(self._lib.LoadShapes_UseFloat32())
+
+    def UseFloat64(self):
+        '''
+        Converts the current LoadShape data to float64/double precision.
+        If there is no data or the data is already represented using float64, nothing is done.
+        
+        (API Extension)
+        '''
+        self.CheckForError(self._lib.LoadShapes_UseFloat64())

dss/dss_capi_gr/ILoads.py

@@ -47,6 +47,7 @@ class ILoads(Iterable):
         'AllocationFactor',
         'xfkVA',
         'pctSeriesRL',
+        'Sensor',
     ]
 
     @property
@@ -374,6 +375,11 @@ def xfkVA(self):
     def xfkVA(self, Value):
         self.CheckForError(self._lib.Loads_Set_xfkVA(Value))
 
+    @property
+    def Sensor(self):
+        '''Name of the sensor monitoring this load.'''
+        return self._get_string(self.CheckForError(self._lib.Loads_Get_Sensor()))
+
     # API extensions
     @property
     def Phases(self):

dss/dss_capi_gr/IPVSystems.py

@@ -29,6 +29,7 @@ class IPVSystems(Iterable):
         'Tdaily',
         'Tduty',
         'Tyearly',
+        'Sensor',
     ]
 
     @property
@@ -202,3 +203,8 @@ def Pmpp(self):
     @Pmpp.setter
     def Pmpp(self, Value):
         self.CheckForError(self._lib.PVSystems_Set_Pmpp(Value))
+
+    @property
+    def Sensor(self):
+        '''Name of the sensor monitoring this element.'''
+        return self._get_string(self.CheckForError(self._lib.PVSystems_Get_Sensor()))

dss/dss_capi_gr/IReclosers.py

@@ -23,6 +23,8 @@ class IReclosers(Iterable):
         'PhaseTrip',
         'RecloseIntervals',
         'Shots',
+        'State',
+        'NormalState',
     ]
 
     def Close(self):
@@ -133,3 +135,33 @@ def SwitchedTerm(self):
     def SwitchedTerm(self, Value):
         self.CheckForError(self._lib.Reclosers_Set_SwitchedTerm(Value))
 
+
+    def Reset(self):
+        '''
+        Reset recloser to normal state. 
+        If open, lock out the recloser. 
+        If closed, resets recloser to first operation.
+        '''
+        self.CheckForError(self._lib.Reclosers_Reset())
+
+    @property
+    def State(self):
+        '''
+        Get/Set present state of recloser. 
+        If set to open (ActionCodes.Open=1), open recloser's controlled element and lock out the recloser. 
+        If set to close (ActionCodes.Close=2), close recloser's controlled element and resets recloser to first operation.
+        '''
+        return self.CheckForError(self._lib.Reclosers_Get_State())
+
+    @State.setter
+    def State(self, Value):
+        self.CheckForError(self._lib.Reclosers_Set_State(Value))
+
+    @property
+    def NormalState(self):
+        '''Get/set normal state (ActionCodes.Open=1, ActionCodes.Close=2) of the recloser.'''
+        return self.CheckForError(self._lib.Reclosers_Get_NormalState())
+
+    @NormalState.setter
+    def NormalState(self, Value):
+        self.CheckForError(self._lib.Reclosers_Set_NormalState(Value))

dss/dss_capi_gr/IRelays.py

@@ -16,6 +16,8 @@ class IRelays(Iterable):
         'MonitoredTerm',
         'SwitchedObj',
         'SwitchedTerm',
+        'State',
+        'NormalState'
     ]
 
     @property
@@ -59,3 +61,41 @@ def SwitchedTerm(self):
     @SwitchedTerm.setter
     def SwitchedTerm(self, Value):
         self.CheckForError(self._lib.Relays_Set_SwitchedTerm(Value))
+
+    def Open(self):
+        '''Open relay's controlled element and lock out the relay.'''
+        self.CheckForError(self._lib.Relays_Open())
+
+    def Close(self):
+        '''Close the switched object controlled by the relay. Resets relay to first operation.'''
+        self.CheckForError(self._lib.Relays_Close())
+
+    def Reset(self):
+        '''
+        Reset relay to normal state. 
+        If open, lock out the relay. 
+        If closed, resets relay to first operation.
+        '''
+        self.CheckForError(self._lib.Relays_Reset())
+
+    @property
+    def State(self):
+        '''
+        Get/Set present state of relay. 
+        If set to open, open relay's controlled element and lock out the relay. 
+        If set to close, close relay's controlled element and resets relay to first operation.
+        '''
+        return self.CheckForError(self._lib.Relays_Get_State())
+
+    @State.setter
+    def State(self, Value):
+        self.CheckForError(self._lib.Relays_Set_State(Value))
+
+    @property
+    def NormalState(self):
+        '''Normal state of relay.'''
+        return self.CheckForError(self._lib.Relays_Get_NormalState())
+
+    @NormalState.setter
+    def NormalState(self, Value):
+        self.CheckForError(self._lib.Relays_Set_NormalState(Value))