Add documentation of main data table structure to all DME classes.

MATPOWER · Dec 9, 2023 · 0b32809 · 0b32809
1 parent 5277103
commit 0b32809
Show file tree

Hide file tree

Showing 17 changed files with 370 additions and 12 deletions.
diff --git a/lib/+mp/dm_element.m b/lib/+mp/dm_element.m
@@ -7,6 +7,19 @@
 % A given data model element object contains the data for all instances of
 % that element type, stored in one or more table data structures.
 %
+% Defines the following columns in the main data table, which are inherited
+% by all subclasses:
+%
+%   ==============  ============  ==========================================
+%   Name            Type          Description
+%   ==============  ============  ==========================================
+%   ``uid``         *integer*     unique ID
+%   ``name``        *char array*  element name
+%   ``status``      *boolean*     true = online, false = offline
+%   ``source_uid``  *undefined*   intended for any info required to link
+%                                 back to element instance in source data
+%   ==============  ============  ==========================================
+%
 % By convention, data model element variables are named ``dme`` and data model
 % element class names begin with ``dme``.
 %

diff --git a/lib/+mp/dme_branch.m b/lib/+mp/dme_branch.m
@@ -1,5 +1,37 @@
 classdef dme_branch < mp.dm_element
 % mp.dme_branch - Data model element for branch.
+%
+% Adds the following columns in the main data table:
+%
+%   ===========  =========  ========================================
+%   Name         Type       Description
+%   ===========  =========  ========================================
+%   ``bus_fr``   *integer*  bus ID (``uid``) of "from" bus
+%   ``bus_to``   *integer*  bus ID (``uid``) of "to" bus
+%   ``r``        *double*   per unit series resistance
+%   ``x``        *double*   per unit series reactance
+%   ``g_fr``     *double*   per unit shunt conductance at "from" end
+%   ``b_fr``     *double*   per unit shunt susceptance at "from" end
+%   ``g_to``     *double*   per unit shunt conductance at "to" end
+%   ``b_to``     *double*   per unit shunt susceptance at "to" end
+%   ``sm_ub_a``  *double*   long term apparent power rating (MVA)
+%   ``sm_ub_b``  *double*   short term apparent power rating (MVA)
+%   ``sm_ub_c``  *double*   emergency apparent power rating (MVA)
+%   ``cm_ub_a``  *double*   long term current magnitude rating (MVA
+%                           equivalent at 1 p.u. voltage)
+%   ``cm_ub_b``  *double*   short term current magnitude rating (MVA
+%                           equivalent at 1 p.u. voltage)
+%   ``cm_ub_c``  *double*   emergency current magnitude rating (MVA
+%                           equivalent at 1 p.u. voltage)
+%   ``vad_lb``   *double*   voltage angle difference lower bound
+%   ``vad_ub``   *double*   voltage angle difference upper bound
+%   ``tm``       *double*   transformer off-nominal turns ratio
+%   ``ta``       *double*   transformer phase-shift angle (degrees)
+%   ``pl_fr``    *double*   active power injection at "from" end
+%   ``ql_fr``    *double*   reactive power injection at "from" end
+%   ``pl_to``    *double*   active power injection at "to" end
+%   ``ql_to``    *double*   reactive power injection at "to" end
+%   ===========  =========  ========================================
 
 %   MATPOWER
 %   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_branch_opf.m b/lib/+mp/dme_branch_opf.m
@@ -1,5 +1,24 @@
 classdef dme_branch_opf < mp.dme_branch & mp.dme_shared_opf
 % mp.dme_branch_opf - Data model element for branch for OPF.
+%
+% Adds the following columns in the main data table:
+%
+%   =================  ========  ===================================
+%   Name               Type      Description
+%   =================  ========  ===================================
+%   ``mu_flow_fr_ub``  *double*  shadow price on flow constraint at
+%                                "from" end *(u/MVA)* [#]_
+%   ``mu_flow_to_ub``  *double*  shadow price on flow constraint at
+%                                "to" end *(u/MVA)* [1]_
+%   ``mu_vad_lb``      *double*  shadow price on lower bound of
+%                                voltage angle difference constraint
+%                                *(u/degree)* [1]_
+%   ``mu_vad_ub``      *double*  shadow price on upper bound of
+%                                voltage angle difference constraint
+%                                *(u/degree)* [1]_
+%   =================  ========  ===================================
+%
+% .. [#] Here *u* denotes the units of the objective function, e.g. USD.
 
 %   MATPOWER
 %   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_bus.m b/lib/+mp/dme_bus.m
@@ -1,5 +1,20 @@
 classdef dme_bus < mp.dm_element
 % mp.dme_bus - Data model element for bus.
+%
+% Adds the following columns in the main data table:
+%
+%   ===========  =========  ========================================
+%   Name         Type       Description
+%   ===========  =========  ========================================
+%   ``base_kv``  *double*   base voltage *(kV)*
+%   ``type``     *integer*  bus type (1 = PQ, 2 = PV, 3 = ref, 4 = isolated)
+%   ``area``     *integer*  area number
+%   ``zone``     *integer*  loss zone
+%   ``vm_lb``    *double*   voltage magnitude lower bound *(p.u.)*
+%   ``vm_ub``    *double*   voltage magnitude upper bound *(p.u.)*
+%   ``va``       *double*   voltage angle *(degrees)*
+%   ``vm``       *double*   voltage magnitude *(p.u.)*
+%   ===========  =========  ========================================
 
 %   MATPOWER
 %   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_bus3p.m b/lib/+mp/dme_bus3p.m
@@ -1,5 +1,20 @@
 classdef dme_bus3p < mp.dm_element
 % mp.dme_bus3p - Data model element for 3-phase bus.
+%
+% Adds the following columns in the main data table:
+%
+%   ===========  =========  ========================================
+%   Name         Type       Description
+%   ===========  =========  ========================================
+%   ``type``     *integer*  bus type (1 = PQ, 2 = PV, 3 = ref, 4 = isolated)
+%   ``base_kv``  *double*   base voltage *(kV)*
+%   ``vm1``      *double*   phase 1 voltage magnitude *(p.u.)*
+%   ``vm2``      *double*   phase 2 voltage magnitude *(p.u.)*
+%   ``vm3``      *double*   phase 3 voltage magnitude *(p.u.)*
+%   ``va1``      *double*   phase 1 voltage angle *(degrees)*
+%   ``va2``      *double*   phase 2 voltage angle *(degrees)*
+%   ``va3``      *double*   phase 3 voltage angle *(degrees)*
+%   ===========  =========  ========================================
 
 %   MATPOWER
 %   Copyright (c) 2021-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_bus_opf.m b/lib/+mp/dme_bus_opf.m
@@ -1,5 +1,22 @@
 classdef dme_bus_opf < mp.dme_bus & mp.dme_shared_opf
 % mp.dme_bus_opf - Data model element for bus for OPF.
+%
+% Adds the following columns in the main data table:
+%
+%   ============  ========  ==============================================
+%   Name          Type      Description
+%   ============  ========  ==============================================
+%   ``lam_p``     *double*  active power nodal price, i.e. shadow price on
+%                           active power balance constraint *(u/MW)* [#]_
+%   ``lam_q``     *double*  reactive power nodal price, i.e. shadow price on
+%                           reactive power balance constraint *(u/MVAr)* [1]_
+%   ``mu_vm_lb``  *double*  shadow price on voltage magnitude lower
+%                           bound *(u/p.u.)* [1]_
+%   ``mu_vm_ub``  *double*  shadow price on voltage magnitude upper
+%                           bound *(u/p.u.)* [1]_
+%   ============  ========  ==============================================
+%
+% .. [#] Here *u* denotes the units of the objective function, e.g. USD.
 
 %   MATPOWER
 %   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_buslink.m b/lib/+mp/dme_buslink.m
@@ -1,5 +1,14 @@
 classdef dme_buslink < mp.dm_element
 % mp.dme_buslink - Data model element for 1-to-3-phase buslink.
+%
+% Adds the following columns in the main data table:
+%
+%   ===========  =========  ========================================
+%   Name         Type       Description
+%   ===========  =========  ========================================
+%   ``bus``      *integer*  bus ID (``uid``) of single phase bus
+%   ``bus3p``    *integer*  bus ID (``uid``) of 3-phase bus
+%   ===========  =========  ========================================
 
 %   MATPOWER
 %   Copyright (c) 2021-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_gen.m b/lib/+mp/dme_gen.m
@@ -1,5 +1,33 @@
 classdef dme_gen < mp.dm_element
 % mp.dme_gen - Data model element for generator.
+%
+% Adds the following columns in the main data table:
+%
+%   =====================  =========  =====================================
+%   Name                   Type       Description
+%   =====================  =========  =====================================
+%   ``bus``                *integer*  bus ID (``uid``)
+%   ``vm_setpoint``        *double*   voltage magnitude setpoint *(p.u.)*
+%   ``pg_lb``              *double*   active power output lower bound *(MW)*
+%   ``pg_ub``              *double*   active power output upper bound *(MW)*
+%   ``qg_lb``              *double*   reactive power output lower bound *(MVAr)*
+%   ``qg_ub``              *double*   reactive power output upper bound *(MVAr)*
+%   ``pg``                 *double*   active power output *(MW)*
+%   ``qg``                 *double*   reactive power output *(MVAr)*
+%   ``startup_cost_cold``  *double*   cold startup cost *(USD)*
+%   ``pc1``                *double*   lower active power output of PQ
+%                                     capability curve *(MW)*
+%   ``pc2``                *double*   upper active power output of PQ
+%                                     capability curve *(MW)*
+%   ``qc1_lb``             *double*   lower bound on reactive power output
+%                                     at ``pc1`` *(MVAr)*
+%   ``qc1_ub``             *double*   upper bound on reactive power output
+%                                     at ``pc1`` *(MVAr)*
+%   ``qc2_lb``             *double*   lower bound on reactive power output
+%                                     at ``pc2`` *(MVAr)*
+%   ``qc2_ub``             *double*   upper bound on reactive power output
+%                                     at ``pc2`` *(MVAr)*
+%   =====================  =========  =====================================
 
 %   MATPOWER
 %   Copyright (c) 1996-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_gen3p.m b/lib/+mp/dme_gen3p.m
@@ -1,5 +1,22 @@
 classdef dme_gen3p < mp.dm_element
 % mp.dme_gen3p - Data model element for 3-phase generator.
+%
+% Adds the following columns in the main data table:
+%
+%   ================  =========  =====================================
+%   Name              Type       Description
+%   ================  =========  =====================================
+%   ``bus``           *integer*  bus ID (``uid``) of 3-phase bus
+%   ``vm1_setpoint``  *double*   phase 1 voltage magnitude setpoint *(p.u.)*
+%   ``vm2_setpoint``  *double*   phase 2 voltage magnitude setpoint *(p.u.)*
+%   ``vm3_setpoint``  *double*   phase 3 voltage magnitude setpoint *(p.u.)*
+%   ``pg1``           *double*   phase 1 active power output *(kW)*
+%   ``pg2``           *double*   phase 2 active power output *(kW)*
+%   ``pg3``           *double*   phase 3 active power output *(kW)*
+%   ``qg1``           *double*   phase 1 reactive power output *(kVAr)*
+%   ``qg2``           *double*   phase 2 reactive power output *(kVAr)*
+%   ``qg3``           *double*   phase 3 reactive power output *(kVAr)*
+%   ================  =========  =====================================
 
 %   MATPOWER
 %   Copyright (c) 2021-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_gen_opf.m b/lib/+mp/dme_gen_opf.m
@@ -1,5 +1,46 @@
 classdef dme_gen_opf < mp.dme_gen & mp.dme_shared_opf
 % mp.dme_gen_opf - Data model element for generator for OPF.
+%
+% Adds the following columns in the main data table:
+%
+%   ============  ========  =====================================
+%   Name          Type      Description
+%   ============  ========  =====================================
+%   ``cost_pg``   *table*   active power cost *(u/MW)* [#]_
+%   ``cost_qg``   *table*   reactive power cost *(u/MVAr)* [1]_
+%   ``mu_pg_lb``  *double*  shadow price on active power output lower bound *(u/MW)* [1]_
+%   ``mu_pg_ub``  *double*  shadow price on active power output upper bound *(u/MW)* [1]_
+%   ``mu_qg_lb``  *double*  shadow price on reactive power output lower bound *(u/MVAr)* [1]_
+%   ``mu_qg_ub``  *double*  shadow price on reactive power output upper bound *(u/MVAr)* [1]_
+%   ============  ========  =====================================
+%
+% .. [#] Here *u* denotes the units of the objective function, e.g. USD.
+%
+% The cost tables ``cost_pg`` and ``cost_qg`` are defined as tables with the
+% following columns:
+%
+%   =============  =========  =====================================
+%   Name           Type       Description
+%   =============  =========  =====================================
+%   ``poly_n``     *integer*  :math:`n_\mathrm{poly}`, number of coefficients
+%                             in polynomial cost curve,
+%                             :math:`f_\mathrm{poly}(x) = c_0 + c_1 x... + c_N x^N`,
+%                             where :math:`n_\mathrm{poly} = N + 1`
+%   ``poly_coef``  *double*   matrix of coefficients :math:`c_j`, of polynomial
+%                             cost :math:`f_\mathrm{poly}(x)`, where :math:`c_j`
+%                             is found in column :math:`j+1`
+%   ``pwl_n``      *double*   :math:`n_\mathrm{pwl}`, number of data points
+%                             :math:`(x_1, f_1), (x_2, f_2), ..., (x_N, f_N)`
+%                             defining a piecewise linear cost curve,
+%                             :math:`f_\mathrm{pwl}(x)` where
+%                             :math:`N = n_\mathrm{pwl}`
+%   ``pwl_qty``    *double*   matrix of *quantiy* coordinates :math:`x_j` for
+%                             piecwise linear cost :math:`f_\mathrm{pwl}(x)`,
+%                             where :math:`x_j` is found in column :math:`j`
+%   ``pwl_cost``   *double*   matrix of *cost* coordinates :math:`f_j` for
+%                             piecwise linear cost :math:`f_\mathrm{pwl}(x)`,
+%                             where :math:`f_j` is found in column :math:`j`
+%   =============  =========  =====================================
 
 %   MATPOWER
 %   Copyright (c) 1996-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_line3p.m b/lib/+mp/dme_line3p.m
@@ -1,5 +1,44 @@
 classdef dme_line3p < mp.dm_element
 % mp.dme_line3p - Data model element for 3-phase line.
+%
+% Adds the following columns in the main data table:
+%
+%   ===========  =========  =============================================
+%   Name         Type       Description
+%   ===========  =========  =============================================
+%   ``bus_fr``   *integer*  bus ID (``uid``) of "from" 3-phase bus
+%   ``bus_to``   *integer*  bus ID (``uid``) of "to" 3-phase bus
+%   ``lc``       *double*   index into line construction table
+%   ``len``      *double*   line length *(?)*
+%   ``pl1_fr``   *double*   phase 1 active power injection at "from" end *(kW)*
+%   ``ql1_fr``   *double*   phase 1 reactive power injection at "from" end *(kVAr)*
+%   ``pl2_fr``   *double*   phase 2 active power injection at "from" end *(kW)*
+%   ``ql2_fr``   *double*   phase 2 reactive power injection at "from" end *(kVAr)*
+%   ``pl3_fr``   *double*   phase 3 active power injection at "from" end *(kW)*
+%   ``ql3_fr``   *double*   phase 3 reactive power injection at "from" end *(kVAr)*
+%   ``pl1_to``   *double*   phase 1 active power injection at "to" end *(kW)*
+%   ``ql1_to``   *double*   phase 1 reactive power injection at "to" end *(kVAr)*
+%   ``pl2_to``   *double*   phase 2 active power injection at "to" end *(kW)*
+%   ``ql2_to``   *double*   phase 2 reactive power injection at "to" end *(kVAr)*
+%   ``pl3_to``   *double*   phase 3 active power injection at "to" end *(kW)*
+%   ``ql3_to``   *double*   phase 3 reactive power injection at "to" end *(kVAr)*
+%   ===========  =========  =============================================
+%
+% The line construction table in the :attr:`lc` property is defined as a
+% table with the following columns:
+%
+%   ======  =========  ==================================================
+%   Name    Type       Description
+%   ======  =========  ==================================================
+%   ``id``  *integer*  unique line construction ID, referenced from
+%                      ``lc`` column of main data table
+%   ``r``   *double*   6 resistence parameters for forming symmetric 3x3
+%                      series impedance matrix
+%   ``x``   *double*   6 reactance parameters for forming symmetric 3x3
+%                      series impedance matrix
+%   ``c``   *double*   6 susceptance parameters for forming symmetric 3x3
+%                      shunt susceptance matrix
+%   ======  =========  ==================================================
 
 %   MATPOWER
 %   Copyright (c) 2021-2023, Power Systems Engineering Research Center (PSERC)
@@ -10,8 +49,8 @@
 %   See https://matpower.org for more info.
 
     properties
-        fbus    % bus index vector for "from" port (port 1) (all lines)
-        tbus    % bus index vector for "to" port (port 2) (all lines)
+        fbus    % bus index vector for "from" bus (all lines)
+        tbus    % bus index vector for "to" bus (all lines)
         freq    % system frequency, in Hz
         lc      % index into lc_tab for lines that are on
         len     % length for lines that are on

diff --git a/lib/+mp/dme_load.m b/lib/+mp/dme_load.m
@@ -1,5 +1,30 @@
 classdef dme_load < mp.dm_element
 % mp.dme_load - Data model element for load.
+%
+% Adds the following columns in the main data table:
+%
+%   ========  =========  =====================================
+%   Name      Type       Description
+%   ========  =========  =====================================
+%   ``bus``   *integer*  bus ID (``uid``)
+%   ``pd``    *double*   :math:`p_p`, active constant power demand *(MW)*
+%   ``qd``    *double*   :math:`q_p`, reactive constant power demand *(MVAr)*
+%   ``pd_i``  *double*   :math:`p_i`, active nominal [#]_ constant current demand *(MW)*
+%   ``qd_i``  *double*   :math:`q_i`, reactive nominal [1]_ constant current demand *(MVAr)*
+%   ``pd_z``  *double*   :math:`p_z`, active nominal [1]_ constant impedance demand *(MW)*
+%   ``qd_z``  *double*   :math:`q_z`, reactive nominal [1]_ constant impedance demand *(MVAr)*
+%   ``p``     *double*   :math:`p`, total active demand *(MW)*
+%   ``q``     *double*   :math:`q`, total reactive demand *(MVAr)*
+%   ========  =========  =====================================
+%
+% .. [#] *Nominal* means for a voltage of 1 p.u.
+%
+% Implements a ZIP load model, where each load has three components, and
+% total demand for the load *i* is given by
+%
+% .. math::
+%       \cscal{s} &= \cscal{s}_p + \cscal{s}_i |\cscal{v}| + \cscal{s}_z |\cscal{v}|^2 \\
+%       p + j q &= (p_p + j q_p) + (p_i + j q_i) |\cscal{v}| + (p_z + j q_z) |\cscal{v}|^2
 
 %   MATPOWER
 %   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)

diff --git a/lib/+mp/dme_load3p.m b/lib/+mp/dme_load3p.m
@@ -1,5 +1,19 @@
 classdef dme_load3p < mp.dm_element
 % mp.dme_load3p - Data model element for 3-phase load.
+%
+% Adds the following columns in the main data table:
+%
+%   ================  =========  =====================================
+%   Name              Type       Description
+%   ================  =========  =====================================
+%   ``bus``           *integer*  bus ID (``uid``) of 3-phase bus
+%   ``pd1``           *double*   phase 1 active power demand *(kW)*
+%   ``pd2``           *double*   phase 2 active power demand *(kW)*
+%   ``pd3``           *double*   phase 3 active power demand *(kW)*
+%   ``pf1``           *double*   phase 1 power factor
+%   ``pf2``           *double*   phase 2 power factor
+%   ``pf3``           *double*   phase 3 power factor
+%   ================  =========  =====================================
 
 %   MATPOWER
 %   Copyright (c) 2021-2023, Power Systems Engineering Research Center (PSERC)