From 30015adef7b521cb6529bde94cb2634077ff5df9 Mon Sep 17 00:00:00 2001 From: Paulo Meira <10246101+PMeira@users.noreply.github.com> Date: Sat, 14 Mar 2020 02:01:34 -0300 Subject: [PATCH] Prepare DSS_MATLAB version 0.10.5 - Sync docstrings with DSS C-API and DSS Python 0.10.5 - Update dss_capi_v7_no_thunk.m to add the 4 new functions from v0.10.5 - Expose the new functions --- +DSS_MATLAB/IActiveClass.m | 7 ++ +DSS_MATLAB/IBus.m | 4 +- +DSS_MATLAB/ICircuit.m | 7 +- +DSS_MATLAB/ICktElement.m | 9 ++ +DSS_MATLAB/IDSS.m | 6 +- +DSS_MATLAB/IFuses.m | 28 +++---- +DSS_MATLAB/ILineGeometries.m | 4 +- +DSS_MATLAB/ILines.m | 10 +++ +DSS_MATLAB/ILoadShapes.m | 9 +- +DSS_MATLAB/ILoads.m | 12 +-- +DSS_MATLAB/IPDElements.m | 4 +- +DSS_MATLAB/IPVSystems.m | 128 +++++++++++++++++++++++++---- +DSS_MATLAB/IParallel.m | 10 +-- +DSS_MATLAB/IReactors.m | 2 +- +DSS_MATLAB/IReclosers.m | 19 ++--- +DSS_MATLAB/ISolution.m | 5 +- +DSS_MATLAB/ISwtControls.m | 10 +-- +DSS_MATLAB/IVsources.m | 5 +- +DSS_MATLAB/IXYCurves.m | 18 ++-- +DSS_MATLAB/dss_capi_v7_no_thunk.m | 8 ++ +DSS_MATLAB/version.m | 2 +- .travis.yml | 4 +- LICENSE | 2 +- README.md | 8 +- 24 files changed, 222 insertions(+), 99 deletions(-) diff --git a/+DSS_MATLAB/IActiveClass.m b/+DSS_MATLAB/IActiveClass.m index 8213957..4463f6f 100644 --- a/+DSS_MATLAB/IActiveClass.m +++ b/+DSS_MATLAB/IActiveClass.m @@ -9,6 +9,7 @@ % Name - Name of the Active Element of the Active Class % Next - Sets next element in active class to be the active DSS object. If object is a CktElement, ActiveCktElement also points to this element. Returns 0 if no more. % NumElements - Number of elements in this class. Same as Count property. + % ActiveClassParent - Get the name of the parent class of the active class properties (Access = protected) apiutil @@ -22,6 +23,7 @@ Name Next NumElements + ActiveClassParent end methods (Access = public) @@ -70,5 +72,10 @@ % (read-only) Number of elements in this class. Same as Count property. result = calllib('dss_capi_v7', 'ActiveClass_Get_NumElements'); end + + function result = get.ActiveClassParent(obj) + % Get the name of the parent class of the active class + result = calllib('dss_capi_v7', 'ActiveClass_Get_ActiveClassParent'); + end end end \ No newline at end of file diff --git a/+DSS_MATLAB/IBus.m b/+DSS_MATLAB/IBus.m index 315fe4c..9099cbf 100644 --- a/+DSS_MATLAB/IBus.m +++ b/+DSS_MATLAB/IBus.m @@ -19,7 +19,7 @@ % SeqVoltages - Double Array of sequence voltages at this bus. % 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 - Variant Array of doubles containing voltages in Magnitude (VLN), angle (deg) + % VMagAngle - Array of doubles containing voltages in Magnitude (VLN), angle (deg) % 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. @@ -181,7 +181,7 @@ end function result = get.VMagAngle(obj) - % (read-only) Variant Array of doubles containing voltages in Magnitude (VLN), angle (deg) + % (read-only) Array of doubles containing voltages in Magnitude (VLN), angle (deg) calllib('dss_capi_v7', 'Bus_Get_VMagAngle_GR'); result = obj.apiutil.get_float64_gr_array(); end diff --git a/+DSS_MATLAB/ICircuit.m b/+DSS_MATLAB/ICircuit.m index 223fce8..b4c8aa7 100644 --- a/+DSS_MATLAB/ICircuit.m +++ b/+DSS_MATLAB/ICircuit.m @@ -416,8 +416,11 @@ end function result = get.SystemY(obj) - % (read-only) System Y matrix (after a solution has been performed) - result = DSS_MATLAB.get_float64_array('Circuit_Get_SystemY'); + % (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. + calllib('dss_capi_v7', 'Circuit_Get_SystemY_GR'); + result = obj.apiutil.get_float64_gr_array(); end function result = get.TotalPower(obj) diff --git a/+DSS_MATLAB/ICktElement.m b/+DSS_MATLAB/ICktElement.m index 780c0ac..ada0b4d 100644 --- a/+DSS_MATLAB/ICktElement.m +++ b/+DSS_MATLAB/ICktElement.m @@ -39,6 +39,7 @@ % Voltages - Complex array of voltages at terminals % VoltagesMagAng - Voltages at each conductor in magnitude, angle form as array of doubles. % Yprim - YPrim matrix, column order, complex numbers (paired) + % IsIsolated - Returns true if the current active element is isolated. Note that this only fetches the current value. See also the Topology interface. % % Methods: % Close - @@ -92,6 +93,7 @@ Voltages VoltagesMagAng Yprim + IsIsolated end methods (Access = public) @@ -273,6 +275,7 @@ function result = get.NodeOrder(obj) % (read-only) Array of integer containing the node numbers (representing phases, for example) for each conductor of each terminal. calllib('dss_capi_v7', 'CktElement_Get_NodeOrder_GR'); + obj.CheckForError(); result = obj.apiutil.get_int32_gr_array(); end @@ -373,5 +376,11 @@ calllib('dss_capi_v7', 'CktElement_Get_Yprim_GR'); result = obj.apiutil.get_float64_gr_array(); end + + function result = get.IsIsolated(obj) + % Returns true if the current active element is isolated. + % Note that this only fetches the current value. See also the Topology interface. + result = (calllib('dss_capi_v7', 'CktElement_Get_IsIsolated') ~= 0); + end end end \ No newline at end of file diff --git a/+DSS_MATLAB/IDSS.m b/+DSS_MATLAB/IDSS.m index 0c3d348..7fb4b20 100644 --- a/+DSS_MATLAB/IDSS.m +++ b/+DSS_MATLAB/IDSS.m @@ -168,9 +168,9 @@ function result = get.AllowEditor(obj) % 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. + % 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. result = (calllib('dss_capi_v7', 'DSS_Get_AllowEditor') ~= 0); end function obj = set.AllowEditor(obj, value) diff --git a/+DSS_MATLAB/IFuses.m b/+DSS_MATLAB/IFuses.m index bcabdd3..87485ee 100644 --- a/+DSS_MATLAB/IFuses.m +++ b/+DSS_MATLAB/IFuses.m @@ -8,13 +8,13 @@ % Name - Get/sets the name of the current active Fuse % Next - Sets next Fuse active; returns 0 if no more. % idx - Sets next Fuse active; returns 0 if no more. - % Delay - (read) A fixed delay time in seconds added to the fuse blowing time determined by the TCC curve. Default is 0. (write) Fixed delay time in seconds added to the fuse blowing time to represent fuse clear or other delay. + % Delay - A fixed delay time in seconds added to the fuse blowing time determined by the TCC curve. Default is 0. This represents a fuse clear or other delay. % MonitoredObj - Full name of the circuit element to which the fuse is connected. - % MonitoredTerm - (read) Terminal number to which the fuse is connected. (write) Number of the terminal to which the fuse is connected + % MonitoredTerm - Terminal number to which the fuse is connected. % NumPhases - Number of phases, this fuse. - % RatedCurrent - (read) Multiplier or actual amps for the TCCcurve object. Defaults to 1.0. Multipliy current values of TCC curve by this to get actual amps. (write) Multiplier or actual fuse amps for the TCC curve. Defaults to 1.0. Has to correspond to the Current axis of TCCcurve object. - % SwitchedObj - (read) Full name of the circuit element switch that the fuse controls. Defaults to the MonitoredObj. (write) Full name of the circuit element switch that the fuse controls. Defaults to MonitoredObj. - % SwitchedTerm - (read) Number of the terminal containing the switch controlled by the fuse. (write) Number of the terminal of the controlled element containing the switch controlled by the fuse. + % RatedCurrent - Multiplier or actual amps for the TCCcurve object. Defaults to 1.0. Multiply current values of TCC curve by this to get actual amps. + % SwitchedObj - Full name of the circuit element switch that the fuse controls. Defaults to the MonitoredObj. + % SwitchedTerm - Number of the terminal of the controlled element containing the switch controlled by the fuse. % TCCcurve - Name of the TCCcurve object that determines fuse blowing. % % Methods: @@ -103,8 +103,8 @@ function result = get.Delay(obj) - % (read) A fixed delay time in seconds added to the fuse blowing time determined by the TCC curve. Default is 0. - % (write) Fixed delay time in seconds added to the fuse blowing time to represent fuse clear or other delay. + % A fixed delay time in seconds added to the fuse blowing time determined by the TCC curve. Default is 0. + % This represents a fuse clear or other delay. result = calllib('dss_capi_v7', 'Fuses_Get_Delay'); end function obj = set.Delay(obj, Value) @@ -122,8 +122,7 @@ end function result = get.MonitoredTerm(obj) - % (read) Terminal number to which the fuse is connected. - % (write) Number of the terminal to which the fuse is connected + % Terminal number to which the fuse is connected. result = calllib('dss_capi_v7', 'Fuses_Get_MonitoredTerm'); end function obj = set.MonitoredTerm(obj, Value) @@ -137,8 +136,8 @@ end function result = get.RatedCurrent(obj) - % (read) Multiplier or actual amps for the TCCcurve object. Defaults to 1.0. Multipliy current values of TCC curve by this to get actual amps. - % (write) Multiplier or actual fuse amps for the TCC curve. Defaults to 1.0. Has to correspond to the Current axis of TCCcurve object. + % Multiplier or actual amps for the TCCcurve object. Defaults to 1.0. + % Multiply current values of TCC curve by this to get actual amps. result = calllib('dss_capi_v7', 'Fuses_Get_RatedCurrent'); end function obj = set.RatedCurrent(obj, Value) @@ -147,8 +146,8 @@ end function result = get.SwitchedObj(obj) - % (read) Full name of the circuit element switch that the fuse controls. Defaults to the MonitoredObj. - % (write) Full name of the circuit element switch that the fuse controls. Defaults to MonitoredObj. + % Full name of the circuit element switch that the fuse controls. + % Defaults to the MonitoredObj. result = calllib('dss_capi_v7', 'Fuses_Get_SwitchedObj'); end function obj = set.SwitchedObj(obj, Value) @@ -157,8 +156,7 @@ end function result = get.SwitchedTerm(obj) - % (read) Number of the terminal containing the switch controlled by the fuse. - % (write) Number of the terminal of the controlled element containing the switch controlled by the fuse. + % Number of the terminal of the controlled element containing the switch controlled by the fuse. result = calllib('dss_capi_v7', 'Fuses_Get_SwitchedTerm'); end function obj = set.SwitchedTerm(obj, Value) diff --git a/+DSS_MATLAB/ILineGeometries.m b/+DSS_MATLAB/ILineGeometries.m index 68e6c5d..31e174b 100644 --- a/+DSS_MATLAB/ILineGeometries.m +++ b/+DSS_MATLAB/ILineGeometries.m @@ -10,7 +10,7 @@ % idx - Sets next LineGeometrie active; returns 0 if no more. % Conductors - Array of strings with names of all conductors in the active LineGeometry object % EmergAmps - Emergency ampere rating - % NormAmps - Normal Ampere rating + % NormAmps - Normal ampere rating % RhoEarth - % Reduce - % Phases - Number of Phases @@ -132,7 +132,7 @@ end function result = get.NormAmps(obj) - % Normal Ampere rating + % Normal ampere rating result = calllib('dss_capi_v7', 'LineGeometries_Get_NormAmps'); end function obj = set.NormAmps(obj, Value) diff --git a/+DSS_MATLAB/ILines.m b/+DSS_MATLAB/ILines.m index 10f28d3..9bda091 100644 --- a/+DSS_MATLAB/ILines.m +++ b/+DSS_MATLAB/ILines.m @@ -35,6 +35,7 @@ % Xmatrix - % Yprim - Yprimitive: Does Nothing at present on Put; Dangerous % SeasonRating - Delivers the rating for the current season (in Amps) if the "SeasonalRatings" option is active + % IsSwitch - Sets/gets the Line element switch status. Setting it has side-effects to the line parameters. % % Methods: % New - @@ -77,6 +78,7 @@ Xmatrix Yprim SeasonRating + IsSwitch end methods (Access = public) @@ -357,5 +359,13 @@ % Delivers the rating for the current season (in Amps) if the "SeasonalRatings" option is active result = calllib('dss_capi_v7', 'Lines_Get_SeasonRating'); end + + function result = get.IsSwitch(obj) + % Sets/gets the Line element switch status. Setting it has side-effects to the line parameters. + result = (calllib('dss_capi_v7', 'Lines_Get_IsSwitch') ~= 0); + end + function obj = set.IsSwitch(obj, Value) + calllib('dss_capi_v7', 'Lines_Set_IsSwitch', Value); + end end end \ No newline at end of file diff --git a/+DSS_MATLAB/ILoadShapes.m b/+DSS_MATLAB/ILoadShapes.m index 0f014f5..aca81ef 100644 --- a/+DSS_MATLAB/ILoadShapes.m +++ b/+DSS_MATLAB/ILoadShapes.m @@ -10,13 +10,13 @@ % idx - Sets next LoadShape active; returns 0 if no more. % HrInterval - Fixed interval time value, hours. % MinInterval - Fixed Interval time value, in minutes - % Npts - (read) Get Number of points in active Loadshape. (write) Set number of points to allocate for active Loadshape. + % Npts - Get/set Number of points in active Loadshape. % PBase - % Pmult - Array of doubles for the P multiplier in the Loadshape. % QBase - Base for normalizing Q curve. If left at zero, the peak value is used. % Qmult - Array of doubles containing the Q multipliers. % TimeArray - Time array in hours correscponding to P and Q multipliers when the Interval=0. - % UseActual - T/F flag to let Loads know to use the actual value in the curve rather than use the value as a multiplier. + % UseActual - Boolean flag to let Loads know to use the actual value in the curve rather than use the value as a multiplier. % sInterval - % % Methods: @@ -120,8 +120,7 @@ end function result = get.Npts(obj) - % (read) Get Number of points in active Loadshape. - % (write) Set number of points to allocate for active Loadshape. + % Get/set Number of points in active Loadshape. result = calllib('dss_capi_v7', 'LoadShapes_Get_Npts'); end function obj = set.Npts(obj, Value) @@ -177,7 +176,7 @@ end function result = get.UseActual(obj) - % T/F flag to let Loads know to use the actual value in the curve rather than use the value as a multiplier. + % Boolean flag to let Loads know to use the actual value in the curve rather than use the value as a multiplier. result = (calllib('dss_capi_v7', 'LoadShapes_Get_UseActual') ~= 0); end function obj = set.UseActual(obj, Value) diff --git a/+DSS_MATLAB/ILoads.m b/+DSS_MATLAB/ILoads.m index 086052a..545aceb 100644 --- a/+DSS_MATLAB/ILoads.m +++ b/+DSS_MATLAB/ILoads.m @@ -12,7 +12,7 @@ % CVRcurve - Name of a loadshape with both Mult and Qmult, for CVR factors as a function of time. % CVRvars - Percent reduction in Q for percent reduction in V. Must be used with dssLoadModelCVR. % CVRwatts - Percent reduction in P for percent reduction in V. Must be used with dssLoadModelCVR. - % Cfactor - Factor relates average to peak kw. Used for allocation with kwh and kwhdays/ + % Cfactor - Factor relates average to peak kw. Used for allocation with kwh and kwhdays % Class - % Growth - Name of the growthshape curve for yearly load growth factors. % IsDelta - Delta loads are connected line-to-line. @@ -31,13 +31,13 @@ % Vminpu - Minimum voltage to apply the load model. Below this, constant Z is used. % Xneut - Neutral reactance for wye-connected loads. % Yearly - Name of yearly duration loadshape - % ZIPV - Array of 7 doubles with values for ZIPV property of the LOAD object + % ZIPV - Array of 7 doubles with values for ZIPV property of the load object % daily - Name of the loadshape for a daily load profile. % duty - Name of the loadshape for a duty cycle simulation. % kV - Set kV rating for active Load. For 2 or more phases set Line-Line kV. Else actual kV across terminals. % kW - Set kW for active Load. Updates kvar based on present PF. % kva - Base load kva. Also defined kw and kvar or pf input, or load allocation by kwh or xfkva. - % kvar - Set kvar for active Load. Updates PF based on present kW. + % kvar - Get/set kvar for active Load. If set, updates PF based on present kW. % kwh - kwh billed for this period. Can be used with Cfactor for load allocation. % kwhdays - Length of kwh billing period for average demand calculation. Default 30. % pctSeriesRL - Percent of Load that is modeled as series R-L for harmonics studies @@ -175,7 +175,7 @@ end function result = get.Cfactor(obj) - % Factor relates average to peak kw. Used for allocation with kwh and kwhdays/ + % Factor relates average to peak kw. Used for allocation with kwh and kwhdays result = calllib('dss_capi_v7', 'Loads_Get_Cfactor'); end function obj = set.Cfactor(obj, Value) @@ -345,7 +345,7 @@ end function result = get.ZIPV(obj) - % Array of 7 doubles with values for ZIPV property of the LOAD object + % Array of 7 doubles with values for ZIPV property of the load object calllib('dss_capi_v7', 'Loads_Get_ZIPV_GR'); result = obj.apiutil.get_float64_gr_array(); end @@ -400,7 +400,7 @@ end function result = get.kvar(obj) - % Set kvar for active Load. Updates PF based on present kW. + % Get/set kvar for active Load. If set, updates PF based on present kW. result = calllib('dss_capi_v7', 'Loads_Get_kvar'); end function obj = set.kvar(obj, Value) diff --git a/+DSS_MATLAB/IPDElements.m b/+DSS_MATLAB/IPDElements.m index 4667e54..2b3062b 100644 --- a/+DSS_MATLAB/IPDElements.m +++ b/+DSS_MATLAB/IPDElements.m @@ -7,7 +7,7 @@ % FaultRate - Get/Set Number of failures per year. For LINE elements: Number of failures per unit length per year. % First - Set the first enabled PD element to be the active element. Returns 0 if none found. % FromTerminal - Number of the terminal of active PD element that is on the "from" side. This is set after the meter zone is determined. - % IsShunt - Variant boolean indicating of PD element should be treated as a shunt element rather than a series element. Applies to Capacitor and Reactor elements in particular. + % IsShunt - Boolean indicating of PD element should be treated as a shunt element rather than a series element. Applies to Capacitor and Reactor elements in particular. % Lambda - Failure rate for this branch. Faults per year including length of line. % Name - Get/Set name of active PD Element. Returns null string if active element is not PDElement type. % Next - Advance to the next PD element in the circuit. Enabled elements only. Returns 0 when no more elements. @@ -80,7 +80,7 @@ end function result = get.IsShunt(obj) - % (read-only) Variant boolean indicating of PD element should be treated as a shunt element rather than a series element. Applies to Capacitor and Reactor elements in particular. + % (read-only) Boolean indicating of PD element should be treated as a shunt element rather than a series element. Applies to Capacitor and Reactor elements in particular. result = (calllib('dss_capi_v7', 'PDElements_Get_IsShunt') ~= 0); end diff --git a/+DSS_MATLAB/IPVSystems.m b/+DSS_MATLAB/IPVSystems.m index 4fa7326..8977b4b 100644 --- a/+DSS_MATLAB/IPVSystems.m +++ b/+DSS_MATLAB/IPVSystems.m @@ -8,13 +8,21 @@ % Name - Get/sets the name of the current active PVSystem % Next - Sets next PVSystem active; returns 0 if no more. % idx - Sets next PVSystem active; returns 0 if no more. - % Irradiance - (read) Get the present value of the Irradiance property in W/sq-m (write) Set the present Irradiance value in W/sq-m - % PF - (read) Get Power factor (write) Set PF - % RegisterNames - Variant Array of PVSYSTEM energy meter register names + % Irradiance - Get/set the present value of the Irradiance property in W/m² + % PF - Get/set the power factor for the active PVSystem + % RegisterNames - Array of PVSYSTEM energy meter register names % RegisterValues - Array of doubles containing values in PVSystem registers. - % kVArated - (read) Get Rated kVA of the PVSystem (write) Set kva rated + % kVArated - Get/set Rated kVA of the PVSystem % kW - get kW output - % kvar - (read) Get kvar value (write) Set kvar output value + % kvar - Get/set kvar output value + % daily - Name of the loadshape for a daily PVSystem profile. + % duty - Name of the load shape to use for duty cycle dispatch simulations such as for solar ramp rate studies. Must be previously defined as a Loadshape object. Typically would have time intervals of 1-5 seconds. + % yearly - Dispatch shape to use for yearly simulations. Must be previously defined as a Loadshape object. If this is not specified, the Daily dispatch shape, if any, is repeated during Yearly solution modes. In the default dispatch mode, the PVSystem element uses this loadshape to trigger State changes. + % Tdaily - Temperature shape to use for daily simulations. Must be previously defined as a TShape object of 24 hrs, typically. The PVSystem element uses this TShape to determine the Pmpp from the Pmpp vs T curve. Units must agree with the Pmpp vs T curve. + % Tduty - Temperature shape to use for duty cycle dispatch simulations such as for solar ramp rate studies. Must be previously defined as a TShape object. Typically would have time intervals of 1-5 seconds. Designate the number of points to solve using the Set Number=xxxx command. If there are fewer points in the actual shape, the shape is assumed to repeat. The PVSystem model uses this TShape to determine the Pmpp from the Pmpp vs T curve. Units must agree with the Pmpp vs T curve. + % Tyearly - Temperature shape to use for yearly simulations. Must be previously defined as a TShape object. If this is not specified, the Daily dispatch shape, if any, is repeated during Yearly solution modes. The PVSystem element uses this TShape to determine the Pmpp from the Pmpp vs T curve. Units must agree with the Pmpp vs T curve. + % IrradianceNow - Returns the current irradiance value for the active PVSystem. Use it to know what's the current irradiance value for the PV during a simulation. + % Pmpp - Gets/sets the rated max power of the PV array for 1.0 kW/sq-m irradiance and a user-selected array temperature of the active PVSystem. properties (Access = protected) apiutil @@ -34,6 +42,14 @@ kVArated kW kvar + daily + duty + yearly + Tdaily + Tduty + Tyearly + IrradianceNow + Pmpp end methods (Access = public) @@ -84,8 +100,7 @@ function result = get.Irradiance(obj) - % (read) Get the present value of the Irradiance property in W/sq-m - % (write) Set the present Irradiance value in W/sq-m + % Get/set the present value of the Irradiance property in W/m² result = calllib('dss_capi_v7', 'PVSystems_Get_Irradiance'); end function obj = set.Irradiance(obj, Value) @@ -94,8 +109,7 @@ end function result = get.PF(obj) - % (read) Get Power factor - % (write) Set PF + % Get/set the power factor for the active PVSystem result = calllib('dss_capi_v7', 'PVSystems_Get_PF'); end function obj = set.PF(obj, Value) @@ -104,7 +118,7 @@ end function result = get.RegisterNames(obj) - % (read-only) Variant Array of PVSYSTEM energy meter register names + % (read-only) Array of PVSYSTEM energy meter register names result = DSS_MATLAB.get_string_array('PVSystems_Get_RegisterNames'); end @@ -115,8 +129,7 @@ end function result = get.kVArated(obj) - % (read) Get Rated kVA of the PVSystem - % (write) Set kva rated + % Get/set Rated kVA of the PVSystem result = calllib('dss_capi_v7', 'PVSystems_Get_kVArated'); end function obj = set.kVArated(obj, Value) @@ -130,13 +143,100 @@ end function result = get.kvar(obj) - % (read) Get kvar value - % (write) Set kvar output value + % Get/set kvar output value result = calllib('dss_capi_v7', 'PVSystems_Get_kvar'); end function obj = set.kvar(obj, Value) calllib('dss_capi_v7', 'PVSystems_Set_kvar', Value); obj.CheckForError(); end + + function result = get.daily(obj) + % Name of the loadshape for a daily PVSystem profile. + result = calllib('dss_capi_v7', 'PVSystems_Get_daily'); + end + function obj = set.daily(obj, Value) + calllib('dss_capi_v7', 'PVSystems_Set_daily', Value); + obj.CheckForError(); + end + + function result = get.duty(obj) + % Name of the load shape to use for duty cycle dispatch simulations such as + % for solar ramp rate studies. Must be previously defined as a Loadshape + % object. Typically would have time intervals of 1-5 seconds. + result = calllib('dss_capi_v7', 'PVSystems_Get_duty'); + end + function obj = set.duty(obj, Value) + calllib('dss_capi_v7', 'PVSystems_Set_duty', Value); + obj.CheckForError(); + end + + function result = get.yearly(obj) + % Dispatch shape to use for yearly simulations. Must be previously defined + % as a Loadshape object. If this is not specified, the Daily dispatch shape, + % if any, is repeated during Yearly solution modes. In the default dispatch + % mode, the PVSystem element uses this loadshape to trigger State changes. + result = calllib('dss_capi_v7', 'PVSystems_Get_yearly'); + end + function obj = set.yearly(obj, Value) + calllib('dss_capi_v7', 'PVSystems_Set_yearly', Value); + obj.CheckForError(); + end + + function result = get.Tdaily(obj) + % Temperature shape to use for daily simulations. Must be previously defined + % as a TShape object of 24 hrs, typically. The PVSystem element uses this + % TShape to determine the Pmpp from the Pmpp vs T curve. Units must agree + % with the Pmpp vs T curve. + result = calllib('dss_capi_v7', 'PVSystems_Get_Tdaily'); + end + function obj = set.Tdaily(obj, Value) + calllib('dss_capi_v7', 'PVSystems_Set_Tdaily', Value); + obj.CheckForError(); + end + + function result = get.Tduty(obj) + % Temperature shape to use for duty cycle dispatch simulations such as for + % solar ramp rate studies. Must be previously defined as a TShape object. + % Typically would have time intervals of 1-5 seconds. Designate the number + % of points to solve using the Set Number=xxxx command. If there are fewer + % points in the actual shape, the shape is assumed to repeat. The PVSystem + % model uses this TShape to determine the Pmpp from the Pmpp vs T curve. + % Units must agree with the Pmpp vs T curve. + result = calllib('dss_capi_v7', 'PVSystems_Get_Tduty'); + end + function obj = set.Tduty(obj, Value) + calllib('dss_capi_v7', 'PVSystems_Set_Tduty', Value); + obj.CheckForError(); + end + + function result = get.Tyearly(obj) + % Temperature shape to use for yearly simulations. Must be previously defined + % as a TShape object. If this is not specified, the Daily dispatch shape, if + % any, is repeated during Yearly solution modes. The PVSystem element uses + % this TShape to determine the Pmpp from the Pmpp vs T curve. Units must + % agree with the Pmpp vs T curve. + result = calllib('dss_capi_v7', 'PVSystems_Get_Tyearly'); + end + function obj = set.Tyearly(obj, Value) + calllib('dss_capi_v7', 'PVSystems_Set_Tyearly', Value); + obj.CheckForError(); + end + + function result = get.IrradianceNow(obj) + % Returns the current irradiance value for the active PVSystem. Use it to + % know what's the current irradiance value for the PV during a simulation. + result = calllib('dss_capi_v7', 'PVSystems_Get_IrradianceNow'); + end + + function result = get.Pmpp(obj) + % Gets/sets the rated max power of the PV array for 1.0 kW/sq-m irradiance + % and a user-selected array temperature of the active PVSystem. + result = calllib('dss_capi_v7', 'PVSystems_Get_Pmpp'); + end + function obj = set.Pmpp(obj, Value) + calllib('dss_capi_v7', 'PVSystems_Set_Pmpp', Value); + obj.CheckForError(); + end end end \ No newline at end of file diff --git a/+DSS_MATLAB/IParallel.m b/+DSS_MATLAB/IParallel.m index 920dba1..faa74bf 100644 --- a/+DSS_MATLAB/IParallel.m +++ b/+DSS_MATLAB/IParallel.m @@ -2,9 +2,9 @@ % IParallel: DSS MATLAB interface class to DSS C-API % % Properties: - % ActiveActor - (read) Gets the ID of the Active Actor (write) Sets the Active Actor + % ActiveActor - Gets/sets the ID of the Active Actor % ActiveParallel - (read) Sets ON/OFF (1/0) Parallel features of the Engine (write) Delivers if the Parallel features of the Engine are Active - % ActorCPU - (read) Gets the CPU of the Active Actor (write) Sets the CPU for the Active Actor + % ActorCPU - Gets/sets the CPU of the Active Actor % ActorProgress - Gets the progress of all existing actors in pct % ActorStatus - Gets the status of each actor % ConcatenateReports - (read) Reads the values of the ConcatenateReports option (1=enabled, 0=disabled) (write) Enable/Disable (1/0) the ConcatenateReports option for extracting monitors data @@ -49,8 +49,7 @@ methods function result = get.ActiveActor(obj) - % (read) Gets the ID of the Active Actor - % (write) Sets the Active Actor + % Gets/sets the ID of the Active Actor result = calllib('dss_capi_v7', 'Parallel_Get_ActiveActor'); end function obj = set.ActiveActor(obj, Value) @@ -69,8 +68,7 @@ end function result = get.ActorCPU(obj) - % (read) Gets the CPU of the Active Actor - % (write) Sets the CPU for the Active Actor + % Gets/sets the CPU of the Active Actor result = calllib('dss_capi_v7', 'Parallel_Get_ActorCPU'); end function obj = set.ActorCPU(obj, Value) diff --git a/+DSS_MATLAB/IReactors.m b/+DSS_MATLAB/IReactors.m index e730613..9f8905e 100644 --- a/+DSS_MATLAB/IReactors.m +++ b/+DSS_MATLAB/IReactors.m @@ -40,7 +40,6 @@ Name Next idx - Conductors SpecType IsDelta Parallel @@ -109,6 +108,7 @@ obj.CheckForError(); end + function result = get.SpecType(obj) % How the reactor data was provided: 1=kvar, 2=R+jX, 3=R and X matrices, 4=sym components. % Depending on this value, only some properties are filled or make sense in the context. diff --git a/+DSS_MATLAB/IReclosers.m b/+DSS_MATLAB/IReclosers.m index 2764259..fcb95a4 100644 --- a/+DSS_MATLAB/IReclosers.m +++ b/+DSS_MATLAB/IReclosers.m @@ -8,14 +8,14 @@ % Name - Get/sets the name of the current active Recloser % Next - Sets next Recloser active; returns 0 if no more. % idx - Sets next Recloser active; returns 0 if no more. - % GroundInst - (read) Ground (3I0) instantaneous trip setting - curve multipler or actual amps. (write) Ground (3I0) trip instantaneous multiplier or actual amps + % GroundInst - Ground (3I0) instantaneous trip setting - curve multipler or actual amps. % GroundTrip - Ground (3I0) trip multiplier or actual amps - % MonitoredObj - (read) Full name of object this Recloser is monitoring. (write) Set monitored object by full name. + % MonitoredObj - Full name of object this Recloser to be monitored. % MonitoredTerm - Terminal number of Monitored object for the Recloser % NumFast - Number of fast shots % PhaseInst - Phase instantaneous curve multipler or actual amps - % PhaseTrip - (read) Phase trip curve multiplier or actual amps (write) Phase Trip multiplier or actual amps - % RecloseIntervals - Variant Array of Doubles: reclose intervals, s, between shots. + % PhaseTrip - Phase trip curve multiplier or actual amps + % RecloseIntervals - Array of Doubles: reclose intervals, s, between shots. % Shots - Number of shots to lockout (fast + delayed) % SwitchedObj - Full name of the circuit element that is being switched by the Recloser. % SwitchedTerm - Terminal number of the controlled device being switched by the Recloser @@ -104,8 +104,7 @@ function result = get.GroundInst(obj) - % (read) Ground (3I0) instantaneous trip setting - curve multipler or actual amps. - % (write) Ground (3I0) trip instantaneous multiplier or actual amps + % Ground (3I0) instantaneous trip setting - curve multipler or actual amps. result = calllib('dss_capi_v7', 'Reclosers_Get_GroundInst'); end function obj = set.GroundInst(obj, Value) @@ -123,8 +122,7 @@ end function result = get.MonitoredObj(obj) - % (read) Full name of object this Recloser is monitoring. - % (write) Set monitored object by full name. + % Full name of object this Recloser to be monitored. result = calllib('dss_capi_v7', 'Reclosers_Get_MonitoredObj'); end function obj = set.MonitoredObj(obj, Value) @@ -160,8 +158,7 @@ end function result = get.PhaseTrip(obj) - % (read) Phase trip curve multiplier or actual amps - % (write) Phase Trip multiplier or actual amps + % Phase trip curve multiplier or actual amps result = calllib('dss_capi_v7', 'Reclosers_Get_PhaseTrip'); end function obj = set.PhaseTrip(obj, Value) @@ -170,7 +167,7 @@ end function result = get.RecloseIntervals(obj) - % (read-only) Variant Array of Doubles: reclose intervals, s, between shots. + % (read-only) Array of Doubles: reclose intervals, s, between shots. calllib('dss_capi_v7', 'Reclosers_Get_RecloseIntervals_GR'); result = obj.apiutil.get_float64_gr_array(); end diff --git a/+DSS_MATLAB/ISolution.m b/+DSS_MATLAB/ISolution.m index 0f7704c..e7e31bc 100644 --- a/+DSS_MATLAB/ISolution.m +++ b/+DSS_MATLAB/ISolution.m @@ -24,7 +24,7 @@ % LoadMult - Default load multiplier applied to all non-fixed loads % MaxControlIterations - Maximum allowable control iterations % MaxIterations - Max allowable iterations. - % MinIterations - (read) Minimum number of iterations required for a power flow solution. (write) Mininum number of iterations required for a power flow solution. + % MinIterations - Minimum number of iterations required for a power flow solution. % Mode - Set present solution mode (by a text code - see DSS Help) % ModeID - ID (text) of the present solution mode % MostIterationsDone - Max number of iterations required to converge at any control iteration of the most recent solution. @@ -399,8 +399,7 @@ end function result = get.MinIterations(obj) - % (read) Minimum number of iterations required for a power flow solution. - % (write) Mininum number of iterations required for a power flow solution. + % Minimum number of iterations required for a power flow solution. result = calllib('dss_capi_v7', 'Solution_Get_MinIterations'); end function obj = set.MinIterations(obj, Value) diff --git a/+DSS_MATLAB/ISwtControls.m b/+DSS_MATLAB/ISwtControls.m index 030308b..20fb015 100644 --- a/+DSS_MATLAB/ISwtControls.m +++ b/+DSS_MATLAB/ISwtControls.m @@ -11,8 +11,8 @@ % Action - Open or Close the switch. No effect if switch is locked. However, Reset removes any lock and then closes the switch (shelf state). % Delay - Time delay [s] betwen arming and opening or closing the switch. Control may reset before actually operating the switch. % IsLocked - The lock prevents both manual and automatic switch operation. - % NormalState - (read) Get Normal state of switch (write) set Normal state of switch (see actioncodes) dssActionOpen or dssActionClose - % State - (read) Force switch to specified state (write) Get Present state of switch + % NormalState - Get/set Normal state of switch (see actioncodes) dssActionOpen or dssActionClose + % State - Set it to force the switch to a specified state, otherwise read its present state. % SwitchedObj - Full name of the switched element. % SwitchedTerm - Terminal number where the switch is located on the SwitchedObj % @@ -118,8 +118,7 @@ end function result = get.NormalState(obj) - % (read) Get Normal state of switch - % (write) set Normal state of switch (see actioncodes) dssActionOpen or dssActionClose + % Get/set Normal state of switch (see actioncodes) dssActionOpen or dssActionClose result = calllib('dss_capi_v7', 'SwtControls_Get_NormalState'); end function obj = set.NormalState(obj, Value) @@ -128,8 +127,7 @@ end function result = get.State(obj) - % (read) Force switch to specified state - % (write) Get Present state of switch + % Set it to force the switch to a specified state, otherwise read its present state. result = calllib('dss_capi_v7', 'SwtControls_Get_State'); end function obj = set.State(obj, Value) diff --git a/+DSS_MATLAB/IVsources.m b/+DSS_MATLAB/IVsources.m index 84e189a..21567fd 100644 --- a/+DSS_MATLAB/IVsources.m +++ b/+DSS_MATLAB/IVsources.m @@ -8,7 +8,7 @@ % Name - Get/sets the name of the current active Vsource % Next - Sets next Vsource active; returns 0 if no more. % idx - Sets next Vsource active; returns 0 if no more. - % AngleDeg - (read) Phase angle of first phase in degrees (write) phase angle in degrees + % AngleDeg - Phase angle of first phase in degrees % BasekV - Source voltage in kV % Frequency - Source frequency in Hz % Phases - Number of phases @@ -80,8 +80,7 @@ function result = get.AngleDeg(obj) - % (read) Phase angle of first phase in degrees - % (write) phase angle in degrees + % Phase angle of first phase in degrees result = calllib('dss_capi_v7', 'Vsources_Get_AngleDeg'); end function obj = set.AngleDeg(obj, Value) diff --git a/+DSS_MATLAB/IXYCurves.m b/+DSS_MATLAB/IXYCurves.m index 2440635..624538d 100644 --- a/+DSS_MATLAB/IXYCurves.m +++ b/+DSS_MATLAB/IXYCurves.m @@ -9,14 +9,14 @@ % Next - Sets next XYCurve active; returns 0 if no more. % idx - Sets next XYCurve active; returns 0 if no more. % Npts - Get/Set Number of points in X-Y curve - % Xarray - Get/Set X values as a Array of doubles. Set Npts to max number expected if setting + % Xarray - Get/set X values as a Array of doubles. Set Npts to max number expected if setting % Xscale - Factor to scale X values from original curve % Xshift - Amount to shift X value from original curve % Yarray - Get/Set Y values in curve; Set Npts to max number expected if setting - % Yscale - (read) Factor to scale Y values from original curve (write) Amount to scale Y values from original curve. Represents a curve shift. - % Yshift - amount to shift Y valiue from original curve + % Yscale - Factor to scale Y values from original curve + % Yshift - Amount to shift Y valiue from original curve % x - Set X value or get interpolated value after setting Y - % y - (read) Y value for present X or set this value then get corresponding X (write) Set Y value or get interpolated Y value after setting X + % y - Set Y value or get interpolated Y value after setting X properties (Access = protected) apiutil @@ -97,7 +97,7 @@ end function result = get.Xarray(obj) - % Get/Set X values as a Array of doubles. Set Npts to max number expected if setting + % Get/set X values as a Array of doubles. Set Npts to max number expected if setting calllib('dss_capi_v7', 'XYCurves_Get_Xarray_GR'); result = obj.apiutil.get_float64_gr_array(); end @@ -135,8 +135,7 @@ end function result = get.Yscale(obj) - % (read) Factor to scale Y values from original curve - % (write) Amount to scale Y values from original curve. Represents a curve shift. + % Factor to scale Y values from original curve result = calllib('dss_capi_v7', 'XYCurves_Get_Yscale'); end function obj = set.Yscale(obj, Value) @@ -145,7 +144,7 @@ end function result = get.Yshift(obj) - % amount to shift Y valiue from original curve + % Amount to shift Y valiue from original curve result = calllib('dss_capi_v7', 'XYCurves_Get_Yshift'); end function obj = set.Yshift(obj, Value) @@ -163,8 +162,7 @@ end function result = get.y(obj) - % (read) Y value for present X or set this value then get corresponding X - % (write) Set Y value or get interpolated Y value after setting X + % Set Y value or get interpolated Y value after setting X result = calllib('dss_capi_v7', 'XYCurves_Get_y'); end function obj = set.y(obj, Value) diff --git a/+DSS_MATLAB/dss_capi_v7_no_thunk.m b/+DSS_MATLAB/dss_capi_v7_no_thunk.m index 0306193..e8d0abc 100644 --- a/+DSS_MATLAB/dss_capi_v7_no_thunk.m +++ b/+DSS_MATLAB/dss_capi_v7_no_thunk.m @@ -52,6 +52,8 @@ fcns.thunkname{fcnNum}='int32voidThunk';fcns.name{fcnNum}='ActiveClass_Get_Next'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}='int32'; fcns.RHS{fcnNum}=[];fcnNum=fcnNum+1; % char * ActiveClass_Get_Name ( void ); fcns.thunkname{fcnNum}='cstringvoidThunk';fcns.name{fcnNum}='ActiveClass_Get_Name'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}='cstring'; fcns.RHS{fcnNum}=[];fcnNum=fcnNum+1; +% char * ActiveClass_Get_ActiveClassParent ( void ); +fcns.thunkname{fcnNum}='cstringvoidThunk';fcns.name{fcnNum}='ActiveClass_Get_ActiveClassParent'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}='cstring'; fcns.RHS{fcnNum}=[];fcnNum=fcnNum+1; % void ActiveClass_Set_Name ( char * Value ); fcns.thunkname{fcnNum}='voidcstringThunk';fcns.name{fcnNum}='ActiveClass_Set_Name'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}=[]; fcns.RHS{fcnNum}={'cstring'};fcnNum=fcnNum+1; % int32_t ActiveClass_Get_NumElements ( void ); @@ -1630,6 +1632,12 @@ fcns.thunkname{fcnNum}='voiddoubleThunk';fcns.name{fcnNum}='PVSystems_Set_PF'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}=[]; fcns.RHS{fcnNum}={'double'};fcnNum=fcnNum+1; % void PVSystems_Set_kvar ( double Value ); fcns.thunkname{fcnNum}='voiddoubleThunk';fcns.name{fcnNum}='PVSystems_Set_kvar'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}=[]; fcns.RHS{fcnNum}={'double'};fcnNum=fcnNum+1; +% double PVSystems_Get_Pmpp ( void ); +fcns.thunkname{fcnNum}='doublevoidThunk';fcns.name{fcnNum}='PVSystems_Get_Pmpp'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}='double'; fcns.RHS{fcnNum}=[];fcnNum=fcnNum+1; +% void PVSystems_Set_Pmpp ( double Value ); +fcns.thunkname{fcnNum}='voiddoubleThunk';fcns.name{fcnNum}='PVSystems_Set_Pmpp'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}=[]; fcns.RHS{fcnNum}={'double'};fcnNum=fcnNum+1; +% double PVSystems_Get_IrradianceNow ( void ); +fcns.thunkname{fcnNum}='doublevoidThunk';fcns.name{fcnNum}='PVSystems_Get_IrradianceNow'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}='double'; fcns.RHS{fcnNum}=[];fcnNum=fcnNum+1; % void Reclosers_Get_AllNames ( char *** ResultPtr , int32_t * ResultCount ); fcns.thunkname{fcnNum}='voidvoidPtrvoidPtrThunk';fcns.name{fcnNum}='Reclosers_Get_AllNames'; fcns.calltype{fcnNum}='cdecl'; fcns.LHS{fcnNum}=[]; fcns.RHS{fcnNum}={'voidPtr', 'int32Ptr'};fcnNum=fcnNum+1; % void Reclosers_Get_AllNames_GR ( void ); diff --git a/+DSS_MATLAB/version.m b/+DSS_MATLAB/version.m index 20923c9..19fa2a8 100644 --- a/+DSS_MATLAB/version.m +++ b/+DSS_MATLAB/version.m @@ -1,3 +1,3 @@ function result = version - result = '0.10.4'; + result = '0.10.5'; end \ No newline at end of file diff --git a/.travis.yml b/.travis.yml index 47adf76..15077e1 100644 --- a/.travis.yml +++ b/.travis.yml @@ -2,8 +2,8 @@ language: generic env: global: - - DSS_CAPI_VERSION=0.10.4 - - DSS_MATLAB_VERSION=0.10.4 + - DSS_CAPI_VERSION=0.10.5 + - DSS_MATLAB_VERSION=0.10.5 matrix: include: diff --git a/LICENSE b/LICENSE index 7631cba..a5b8c19 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2018-2019, Paulo Meira +Copyright (c) 2018-2020, Paulo Meira All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/README.md b/README.md index c3aa932..bdbd683 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ## **[📦 Downloads available here](https://github.com/dss-extensions/dss_matlab/releases/latest) for Linux, macOS and Windows** -*Note that the repository itself doesn't contain the binaries since this is a multi-platform project. If you download the git repository, you still need the binary files from DSS C-API.* +*Note that the repository itself doesn't contain the binaries since this is a multi-platform project. If you download the git repository, you still need the binary files from the DSS C-API library.* --- @@ -17,7 +17,7 @@ Related projects: - [`OpenDSSDirect.py`](http://github.com/dss-extensions/OpenDSSDirect.py): More pythonic bindings and useful tools. - [`DSS Sharp`](http://github.com/dss-extensions/dss_sharp/): .NET assembly to use the native DLL, mimics the COM object as used in .NET. -Version 0.10.4, released on 2019-11-23, covers most of the COM functions and classes, besides some extensions from DSS C-API. If you find a missing function or unexpected behavior, please open an issue on GitHub to both help us track and hopefully fix it, and also inform other users. +Version 0.10.5, released on 2020-03-14, covers most of the COM functions and classes, besides some extensions from DSS C-API. If you find a missing function or unexpected behavior, please open an issue on GitHub to both help us track and hopefully fix it, and also inform other users. This project uses the [DSS C-API library version 0.10.5](https://github.com/dss-extensions/dss_capi/blob/0.10.x/docs/changelog.md#version-0105), based on OpenDSS revision 2836 (which is slightly newer than OpenDSS v8.6.7.1). ## Usage @@ -59,7 +59,7 @@ If you want more code to play with, you can use the MATLAB examples from the off **As a general advice (valid for COM and DSS_MATLAB), avoid using the `get` function without parameters on OpenDSS classes. Some properties like `First` and `Next` used for iteration of elements change the current active element and can lead to misleading data!** -## Known differences and more +## Known differences and history We maintain a list of important differences between the official COM implementation and DSS C-API at: @@ -67,7 +67,7 @@ https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md Most of these apply indirectly to DSS_MATLAB. -The [list of important changes](https://github.com/dss-extensions/dss_capi/blob/0.10.x/docs/changelog.md#version-0104) through development is also useful. +The [list of important changes](https://github.com/dss-extensions/dss_capi/blob/0.10.x/docs/changelog.md#version-0105) through development is also useful. ## Credits / Acknowlegement