Update ports from DSS-Python 0.13, integrating our base library, DSS C-API 0.13.

- add missing file
- DSS.AdvancedTypes mode: when enabled, can return complex numbers and matrices
- DSS.CompatFlags: some toggles for compatibility with the official OpenDSS on some specific points.
- DSS.AllowDOScmd: toggle running system commands from DSS scripts
- DSS.COMErrorResults: toggle returning empty "[]" vs "[0]" etc.
- fix many docstring typos
- fix some arrays of strings: some functions were broken during the DSSContext migration.
- use enums for some properties: easier to read, more maintainable.

Author: PMeira

+DSS_MATLAB/APIUtil.m

@@ -9,6 +9,7 @@
         libname
         dssctx
         is_prime
+        allow_complex
     end
     methods
         function obj = APIUtil(varargin)
@@ -19,11 +20,14 @@
             else
                 obj.libname = 'dss_capi';
             end
-
             MfilePath = fileparts(mfilename('fullpath'));
             DLLfilePath = fullfile(MfilePath, obj.libname);
             PropertiesMOfilePath = fullfile(MfilePath, 'messages', 'properties-en-US.mo');
             DSS_MATLAB.librefcount(1);
+            obj.allow_complex = false;
+            if (nargin > 1) && (varargin{2})
+                obj.allow_complex = true;
+            end
             if libisloaded(obj.libname)
                 if (nargin > 0) && (varargin{1} ~= 0)
                     obj.dssctx = calllib(obj.libname, 'ctx_New');
@@ -95,44 +99,111 @@ function delete(obj)
             % setdatatype(obj.DataPtr_PInteger, 'int32PtrPtr', 1);
             % setdatatype(obj.DataPtr_PByte, 'int8PtrPtr', 1);
 
-            setdatatype(obj.CountPtr_PDouble, 'int32Ptr', 2);
-            setdatatype(obj.CountPtr_PInteger, 'int32Ptr', 2);
-            setdatatype(obj.CountPtr_PByte, 'int32Ptr', 2);
+            setdatatype(obj.CountPtr_PDouble, 'int32Ptr', 4);
+            setdatatype(obj.CountPtr_PInteger, 'int32Ptr', 4);
+            setdatatype(obj.CountPtr_PByte, 'int32Ptr', 4);
         end
 
 
         function result = get_float64_gr_array(obj)
             data = calllib(obj.libname, 'ctx_DSS_GR_DataPtr_PDouble', obj.dssctx);
-            setdatatype(data, 'doublePtr', 1, obj.CountPtr_PDouble.Value(1));
+            cnt = obj.CountPtr_PDouble.Value;
+            setdatatype(data, 'doublePtr', 1, cnt(1));
             result = data.Value;
+            if obj.allow_complex && (cnt(4) ~= 0)
+                % If the last element is filled, we have a matrix.  Otherwise, the 
+                % matrix feature is disabled or the result is indeed a vector
+                result = reshape(result, [cnt(3), cnt(4)]);
+            end
         end
 
+        function result = get_complex128_gr_array(obj)
+            if ~obj.allow_complex
+                result = obj.get_float64_gr_array();
+                return
+            end
+
+            % Currently we use the same as API as get_float64_array, may change later
+            data = calllib(obj.libname, 'ctx_DSS_GR_DataPtr_PDouble', obj.dssctx);
+            cnt = obj.CountPtr_PDouble.Value;
+            setdatatype(data, 'doublePtr', 1, cnt(1));
+            result = data.Value(1:2:end) + 1j * data.Value(2:2:end);
+            if obj.allow_complex && (cnt(4) ~= 0)
+                % If the last element is filled, we have a matrix.  Otherwise, the 
+                % matrix feature is disabled or the result is indeed a vector
+                result = reshape(result, [cnt(3), cnt(4)]);
+            end
+        end
+
+        function result = get_complex128_gr_simple(obj)
+            if ~obj.allow_complex
+                result = obj.get_float64_gr_array();
+                return
+            end
+
+            % Currently we use the same as API as get_float64_array, may change later
+            data = calllib(obj.libname, 'ctx_DSS_GR_DataPtr_PDouble', obj.dssctx);
+            cnt = obj.CountPtr_PDouble.Value;
+            assert(cnt(1) == 2, 'Unexpected number of elements returned by API');
+            setdatatype(data, 'doublePtr', 1, 2);
+            result = data.Value(1) + 1j * data.Value(2);
+        end
+
         function result = get_int32_gr_array(obj)
             data = calllib(obj.libname, 'ctx_DSS_GR_DataPtr_PInteger', obj.dssctx);
-            setdatatype(data, 'int32Ptr', 1, obj.CountPtr_PInteger.Value(1));
+            cnt = obj.CountPtr_PInteger.Value;
+            setdatatype(data, 'int32Ptr', 1, cnt);
             result = data.Value;
+            if obj.allow_complex && (cnt(4) ~= 0)
+                % If the last element is filled, we have a matrix.  Otherwise, the 
+                % matrix feature is disabled or the result is indeed a vector
+                result = reshape(result, [cnt(3), cnt(4)]);
+            end
         end
 
         function result = get_int8_gr_array(obj)
             data = calllib(obj.libname, 'ctx_DSS_GR_DataPtr_PByte', obj.dssctx);
-            setdatatype(data, 'int8Ptr', 1, obj.CountPtr_PByte.Value(1));
+            cnt = obj.CountPtr_PByte.Value;
+            setdatatype(data, 'int8Ptr', 1, cnt(1));
             result = data.Value;
+            if obj.allow_complex && (cnt(4) ~= 0)
+                % If the last element is filled, we have a matrix.  Otherwise, the 
+                % matrix feature is disabled or the result is indeed a vector
+                result = reshape(result, [cnt(3), cnt(4)]);
+            end
         end
 
         function result = get_string_array(obj, funcname, varargin)
             dataPointer = libpointer('voidPtr', 0);
-            countPointer = libpointer('int32Ptr', [0, 0]);
+            countPointer = libpointer('int32Ptr', [0, 0, 0, 0]);
             calllib(obj.libname, funcname, obj.dssctx, dataPointer, countPointer, varargin{:});
             result = cell(countPointer.Value(1), 1);
             for i=1:countPointer.Value(1)
                 result(i) = cellstr(calllib(obj.libname, 'DSS_Get_PAnsiChar', dataPointer, i - 1));
             end
             calllib(obj.libname, 'DSS_Dispose_PPAnsiChar', dataPointer, countPointer.Value(2));
         end
-   
+
+        function obj = set_string_array(obj, funcname, Value)
+            calllib(obj.libname, funcname, obj.dssctx, Value, numel(Value));
+        end
+
+        function obj = set_complex128_simple(obj, funcname, value)
+            if ~isreal(value)
+                assert(length(value) ~= 1, 'A single complex number or a pair of reals was expected');
+                calllib(obj.libname, funcname, obj.dssctx, value, 2);
+                return
+            end
+            assert((length(value) == 1) || (length(value) == 2), 'A single complex number or a pair of reals was expected');
+            if (length(value) ~= 2)
+                value = [value; 0];
+            end
+            calllib(obj.libname, funcname, obj.dssctx, value, 2);
+        end
+
         % function result = get_int8_array(obj, funcname, varargin)
         %     dataPointer = libpointer('int8PtrPtr');
-        %     countPointer = libpointer('int32Ptr', [0, 0]);
+        %     countPointer = libpointer('int32Ptr', [0, 0, 0, 0]);
         %     calllib(obj.libname, funcname, dataPointer, countPointer, varargin{:});
         %     dataPointer.Value
         %     setdatatype(dataPointer.Value, 'int8Ptr', 1, countPointer.Value(1));
@@ -143,7 +214,7 @@ function delete(obj)
 
         % function result = get_int32_array(obj, funcname, varargin)
         %     dataPointer = libpointer('int32PtrPtr');
-        %     countPointer = libpointer('int32Ptr', [0, 0]);
+        %     countPointer = libpointer('int32Ptr', [0, 0, 0, 0]);
         %     calllib(obj.libname, funcname, dataPointer, countPointer, varargin{:});
         %     setdatatype(dataPointer.Value, 'int32Ptr', 1, countPointer.Value(1));
         %     result = dataPointer.Value;
@@ -152,7 +223,7 @@ function delete(obj)
 
         % function result = get_float64_array(obj, funcname, varargin)
         %     dataPointer = libpointer('doublePtrPtr');
-        %     countPointer = libpointer('int32Ptr', [0, 0]);
+        %     countPointer = libpointer('int32Ptr', [0, 0, 0, 0]);
         %     calllib(obj.libname, funcname, dataPointer, countPointer, varargin{:});
         %     setdatatype(dataPointer.Value, 'doublePtr', 1, countPointer.Value(1));
         %     result = dataPointer.Value;

+DSS_MATLAB/ControlModes.m

@@ -0,0 +1,18 @@
+classdef(Enumeration) ControlModes < int32
+    % ControlModes: enumerated values for DSS.Solution.ControlMode
+    % 
+    % Values:
+    %   Static(0): Control Mode option - Static
+    %   Event(1): Control Mode Option - Event driven solution mode
+    %   Time(2): Control mode option - Time driven mode
+    %   Multirate(3): Control mode option - Multirate mode
+    %   Off(-1): Control Mode OFF
+
+    enumeration
+        Static(0) % Control Mode option - Static
+        Event(1) % Control Mode Option - Event driven solution mode
+        Time(2) % Control mode option - Time driven mode
+        Multirate(3) % Control mode option - Multirate mode
+        Off(-1) % Control Mode OFF
+    end
+end

+DSS_MATLAB/DSSCompatFlags.m

@@ -0,0 +1,34 @@
+classdef(Enumeration) DSSCompatFlags < int32
+    % DSSCompatFlags: enumerated flags for DSS.CompatFlags
+    % 
+    % Values:
+    %    NoSolverFloatChecks(0x00000001)
+    %    BadPrecision(0x00000002)
+    %    InvControl9611(0x00000004)
+    %
+    % Descriptions:
+    %
+    %   NoSolverFloatChecks:
+    %       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.
+    %
+    %   BadPrecision:
+    %       If enabled, 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.
+    %
+    %   InvControl9611:
+    %       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.        
+
+
+    enumeration
+        NoSolverFloatChecks(0x00000001)
+        BadPrecision(0x00000002)
+        InvControl9611(0x00000004)
+    end
+end

+DSS_MATLAB/GeneratorStatus.m

@@ -0,0 +1,12 @@
+classdef(Enumeration) GeneratorStatus < int32
+    % GeneratorStatus: enumerated values for Loads.Status
+    % 
+    % Values:
+    %    Variable(0)
+    %    Fixed(1)
+
+    enumeration
+        Variable(0)
+        Fixed(1)
+    end
+end

+DSS_MATLAB/IActiveClass.m

@@ -12,7 +12,7 @@
     %    ActiveClassParent - Get the name of the parent class of the active class
     % 
     % Methods:
-    %    ToJSON - Returns the data (as a list) of all elements from the active class as a JSON-encoded string.    The `options` parameter contains bit-flags to toggle specific features.  See `Obj_ToJSON` (C-API) for more.    Additionally, the `ExcludeDisabled` flag can be used to excluded disabled elements from the output.    (API Extension)
+    %    ToJSON - Returns the data (as a list) of all elements from the active class as a JSON-encoded string.    The `options` parameter contains bit-flags to toggle specific features.  See `Obj_ToJSON` (C-API) for more.    Additionally, the `ExcludeDisabled` flag can be used to excluded disabled elements from the output. (API Extension)
 
     properties
         ActiveClassName

+DSS_MATLAB/IBus.m

@@ -16,20 +16,21 @@
     %    Nodes - Integer Array of Node Numbers defined at the bus in same order as the voltages.
     %    NumNodes - Number of Nodes this bus.
     %    SectionID - Integer ID of the feeder section in which this bus is located.
-    %    SeqVoltages - Double Array of sequence voltages at this bus.
+    %    SeqVoltages - Double Array of sequence voltages at this bus. Magnitudes only.
     %    TotalMiles - Total length of line downline from this bus, in miles. For recloser siting algorithm.
     %    VLL - For 2- and 3-phase buses, returns array of complex numbers represetin L-L voltages in volts. Returns -1.0 for 1-phase bus. If more than 3 phases, returns only first 3.
-    %    VMagAngle - Array of doubles containing voltages in Magnitude (VLN), angle (deg)
+    %    VMagAngle - Array of doubles containing voltages in Magnitude (VLN), angle (degrees)
     %    Voc - Open circuit voltage; Complex array.
     %    Voltages - Complex array of voltages at this bus.
     %    YscMatrix - Complex array of Ysc matrix at bus. Column by column.
     %    Zsc0 - Complex Zero-Sequence short circuit impedance at bus.
-    %    Zsc1 - Complex Positive-Sequence short circuit impedance at bus..
+    %    Zsc1 - Complex Positive-Sequence short circuit impedance at bus.
     %    ZscMatrix - Complex array of Zsc matrix at bus. Column by column.
     %    kVBase - Base voltage at bus in kV
     %    puVLL - Returns Complex array of pu L-L voltages for 2- and 3-phase buses. Returns -1.0 for 1-phase bus. If more than 3 phases, returns only 3 phases.
-    %    puVmagAngle - Array of doubles containig voltage magnitude, angle pairs in per unit
+    %    puVmagAngle - Array of doubles containing voltage magnitude, angle (degrees) pairs in per unit
     %    puVoltages - Complex Array of pu voltages at the bus.
+    %    ZSC012Matrix - Array of doubles (complex) containing the complete 012 Zsc matrix.   Only available after Zsc is computed, either through the "ZscRefresh" command, or running a "FaultStudy" solution.  Only available for buses with 3 nodes.
     %    x - X Coordinate for bus (double)
     %    y - Y coordinate for bus(double)
     %    LoadList - List of strings: Full Names of LOAD elements connected to the active bus.
@@ -70,6 +71,7 @@
         puVLL
         puVmagAngle
         puVoltages
+        ZSC012Matrix
         x
         y
         LoadList
@@ -106,7 +108,7 @@
             % (read-only) Complex Double array of Sequence Voltages (0, 1, 2) at this Bus.
             calllib(obj.libname, 'ctx_Bus_Get_CplxSeqVoltages_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.Cust_Duration(obj)
@@ -137,7 +139,7 @@
             % (read-only) Short circuit currents at bus; Complex Array.
             calllib(obj.libname, 'ctx_Bus_Get_Isc_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.Lambda(obj)
@@ -184,7 +186,7 @@
         end
 
         function result = get.SeqVoltages(obj)
-            % (read-only) Double Array of sequence voltages at this bus.
+            % (read-only) Double Array of sequence voltages at this bus. Magnitudes only.
             calllib(obj.libname, 'ctx_Bus_Get_SeqVoltages_GR', obj.dssctx);
             obj.CheckForError();
             result = obj.apiutil.get_float64_gr_array();
@@ -200,11 +202,11 @@
             % (read-only) For 2- and 3-phase buses, returns array of complex numbers represetin L-L voltages in volts. Returns -1.0 for 1-phase bus. If more than 3 phases, returns only first 3.
             calllib(obj.libname, 'ctx_Bus_Get_VLL_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.VMagAngle(obj)
-            % (read-only) Array of doubles containing voltages in Magnitude (VLN), angle (deg)
+            % (read-only) Array of doubles containing voltages in Magnitude (VLN), angle (degrees)
             calllib(obj.libname, 'ctx_Bus_Get_VMagAngle_GR', obj.dssctx);
             obj.CheckForError();
             result = obj.apiutil.get_float64_gr_array();
@@ -214,42 +216,42 @@
             % (read-only) Open circuit voltage; Complex array.
             calllib(obj.libname, 'ctx_Bus_Get_Voc_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.Voltages(obj)
             % (read-only) Complex array of voltages at this bus.
             calllib(obj.libname, 'ctx_Bus_Get_Voltages_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.YscMatrix(obj)
             % (read-only) Complex array of Ysc matrix at bus. Column by column.
             calllib(obj.libname, 'ctx_Bus_Get_YscMatrix_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.Zsc0(obj)
             % (read-only) Complex Zero-Sequence short circuit impedance at bus.
             calllib(obj.libname, 'ctx_Bus_Get_Zsc0_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_simple();
         end
 
         function result = get.Zsc1(obj)
-            % (read-only) Complex Positive-Sequence short circuit impedance at bus..
+            % (read-only) Complex Positive-Sequence short circuit impedance at bus.
             calllib(obj.libname, 'ctx_Bus_Get_Zsc1_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_simple();
         end
 
         function result = get.ZscMatrix(obj)
             % (read-only) Complex array of Zsc matrix at bus. Column by column.
             calllib(obj.libname, 'ctx_Bus_Get_ZscMatrix_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.kVBase(obj)
@@ -262,11 +264,11 @@
             % (read-only) Returns Complex array of pu L-L voltages for 2- and 3-phase buses. Returns -1.0 for 1-phase bus. If more than 3 phases, returns only 3 phases.
             calllib(obj.libname, 'ctx_Bus_Get_puVLL_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.puVmagAngle(obj)
-            % (read-only) Array of doubles containig voltage magnitude, angle pairs in per unit
+            % (read-only) Array of doubles containing voltage magnitude, angle (degrees) pairs in per unit
             calllib(obj.libname, 'ctx_Bus_Get_puVmagAngle_GR', obj.dssctx);
             obj.CheckForError();
             result = obj.apiutil.get_float64_gr_array();
@@ -276,7 +278,16 @@
             % (read-only) Complex Array of pu voltages at the bus.
             calllib(obj.libname, 'ctx_Bus_Get_puVoltages_GR', obj.dssctx);
             obj.CheckForError();
-            result = obj.apiutil.get_float64_gr_array();
+            result = obj.apiutil.get_complex128_gr_array();
+        end
+
+        function result = get.ZSC012Matrix(obj)
+            % Array of doubles (complex) containing the complete 012 Zsc matrix. 
+            % Only available after Zsc is computed, either through the "ZscRefresh" command, or running a "FaultStudy" solution.
+            % Only available for buses with 3 nodes.
+            calllib(obj.libname, 'ctx_Bus_Get_ZSC012Matrix_GR', obj.dssctx);
+            obj.CheckForError();
+            result = obj.apiutil.get_complex128_gr_array();
         end
 
         function result = get.x(obj)