Lots of class description additions to Ref Manual.

docs/sphinx/source/ref-manual/introduction.rst

@@ -7,4 +7,4 @@ This documentation is automatically generated from the corresponding help text i
 
 The GitHub icon in the upper right of each reference page links to the corresponding source file in the master branch on GitHub.
 
-Currently, this manual includes *only* classes and functions that make up the new **MP-Core** and the **flexible** |MATPOWER| framework, but not the **legacy** |MATPOWER| framework or the other packages such as |MPOM>|, |MIPS>|, |MPTEST>|, or |MOST>|.
+Currently, this manual includes *only* classes and functions that make up the new **MP-Core** and the **flexible** and **legacy** |MATPOWER| frameworks, but not the other legacy |MATPOWER| functions or the included packages |MPOM>|, |MIPS>|, |MPTEST>|, or |MOST>|.

lib/+mp/data_model_cpf.m

@@ -1,13 +1,18 @@
 classdef data_model_cpf < mp.data_model
 % mp.data_model_cpf - |MATPOWER| **data model** for CPF tasks.
 %
+% The purpose of this class is to include CPF-specific subclasses for the
+% load and shunt elements, which need to be able to provide versions of
+% their model parameters that are parameterized by the continuation
+% parameter :math:`\lambda`.
+%
 % data_model_cpf Methods:
 %   * data_model_cpf - constructor, assign default data model element classes
 %
 % See also mp.data_model.
 
 %   MATPOWER
-%   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2020-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/data_model_opf.m

@@ -1,6 +1,9 @@
 classdef data_model_opf < mp.data_model
 % mp.data_model_opf - |MATPOWER| **data model** for OPF tasks.
 %
+% The purpose of this class is to include OPF-specific subclasses for its
+% elements and to handle pretty-printing output for **lim** sections.
+%
 % mp.data_model_opf Methods:
 %   * data_model_opf - constructor, assign default data model element classes
 %   * pp_flags - add flags for **lim** sections
@@ -10,7 +13,7 @@
 % See also mp.data_model.
 
 %   MATPOWER
-%   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2020-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_branch.m

@@ -1,7 +1,11 @@
 classdef dme_branch < mp.dm_element
 % mp.dme_branch - Data model element for branch.
 %
-% Adds the following columns in the main data table:
+% Implements the data element model for branch elements, including
+% transmission lines and transformers.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ===========  =========  ========================================
 %   Name         Type       Description

lib/+mp/dme_branch_opf.m

@@ -1,7 +1,11 @@
 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:
+% To parent class :class:`mp.dme_branch`, adds shadow prices on flow and
+% angle difference limits, and pretty-printing for **lim** sections.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   =================  ========  ===================================
 %   Name               Type      Description

lib/+mp/dme_bus.m

@@ -1,7 +1,10 @@
 classdef dme_bus < mp.dm_element
 % mp.dme_bus - Data model element for bus.
 %
-% Adds the following columns in the main data table:
+% Implements the data element model for bus elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ===========  =========  ========================================
 %   Name         Type       Description

lib/+mp/dme_bus3p.m

@@ -1,7 +1,10 @@
 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:
+% Implements the data element model for 3-phase bus elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ===========  =========  ========================================
 %   Name         Type       Description

lib/+mp/dme_bus3p_opf.m

@@ -1,8 +1,11 @@
 classdef dme_bus3p_opf < mp.dme_bus3p & mp.dme_shared_opf
 % mp.dme_bus3p_opf - Data model element for 3-phase bus for OPF.
+%
+% To parent class :class:`mp.dme_bus3p`, adds pretty-printing for **lim**
+% sections.
 
 %   MATPOWER
-%   Copyright (c) 2022-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2022-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_bus_opf.m

@@ -1,7 +1,11 @@
 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:
+% To parent class :class:`mp.dme_bus`, adds shadow prices on power balance
+% and voltage magnitude limits, and pretty-printing for **lim** sections.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ============  ========  ==============================================
 %   Name          Type      Description

lib/+mp/dme_buslink.m

@@ -1,7 +1,10 @@
 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:
+% Implements the data element model for 1-to-3-phase buslink elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ===========  =========  ========================================
 %   Name         Type       Description

lib/+mp/dme_buslink_opf.m

@@ -1,8 +1,11 @@
 classdef dme_buslink_opf < mp.dme_buslink & mp.dme_shared_opf
 % mp.dme_buslink_opf - Data model element for 1-to-3-phase buslink for OPF.
+%
+% To parent class :class:`mp.dme_buslink`, adds pretty-printing for **lim**
+% sections.
 
 %   MATPOWER
-%   Copyright (c) 2022-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2022-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_gen.m

@@ -1,7 +1,10 @@
 classdef dme_gen < mp.dm_element
 % mp.dme_gen - Data model element for generator.
 %
-% Adds the following columns in the main data table:
+% Implements the data element model for generator elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   =====================  =========  =====================================
 %   Name                   Type       Description

lib/+mp/dme_gen3p.m

@@ -1,7 +1,10 @@
 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:
+% Implements the data element model for 3-phase generator elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ================  =========  =====================================
 %   Name              Type       Description

lib/+mp/dme_gen3p_opf.m

@@ -1,8 +1,11 @@
 classdef dme_gen3p_opf < mp.dme_gen3p & mp.dme_shared_opf
 % mp.dme_gen3p_opf - Data model element for 3-phase generator for OPF.
+%
+% To parent class :class:`mp.dme_gen3p`, adds pretty-printing for **lim**
+% sections.
 
 %   MATPOWER
-%   Copyright (c) 2022-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2022-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_gen_opf.m

@@ -1,7 +1,11 @@
 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:
+% To parent class :class:`mp.dme_gen`, adds costs, shadow prices on active
+% and reactive generation limits, and pretty-printing for **lim** sections.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ============  ===============  =====================================
 %   Name          Type             Description

lib/+mp/dme_line3p.m

@@ -1,7 +1,10 @@
 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:
+% Implements the data element model for 3-phase distribution line elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ===========  =========  =============================================
 %   Name         Type       Description
@@ -24,7 +27,7 @@
 %   ``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
+% The line construction table in the :attr:`lc_tab` property is defined as a
 % table with the following columns:
 %
 %   ======  =========  ==================================================
@@ -52,7 +55,7 @@
         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
+        lc      % index into :attr:`lc_tab` for lines that are on
         len     % length for lines that are on
         lc_tab  % line construction table
         ys      % cell array of 3x3 series admittance matrices for lc rows

lib/+mp/dme_line3p_opf.m

@@ -1,8 +1,11 @@
 classdef dme_line3p_opf < mp.dme_line3p & mp.dme_shared_opf
 % mp.dme_line3p_opf - Data model element for 3-phase line for OPF.
+%
+% To parent class :class:`mp.dme_line3p`, adds pretty-printing for **lim**
+% sections.
 
 %   MATPOWER
-%   Copyright (c) 2022-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2022-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_load.m

@@ -1,7 +1,11 @@
 classdef dme_load < mp.dm_element
 % mp.dme_load - Data model element for load.
 %
-% Adds the following columns in the main data table:
+% Implements the data element model for load elements, using a ZIP load
+% model.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ========  =========  =====================================
 %   Name      Type       Description

lib/+mp/dme_load3p.m

@@ -1,7 +1,10 @@
 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:
+% Implements the data element model for 3-phase load elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ================  =========  =====================================
 %   Name              Type       Description

lib/+mp/dme_load3p_opf.m

@@ -1,8 +1,11 @@
 classdef dme_load3p_opf < mp.dme_load3p & mp.dme_shared_opf
 % mp.dme_load3p_opf - Data model element for 3-phase load for OPF.
+%
+% To parent class :class:`mp.dme_load3p`, adds pretty-printing for **lim**
+% sections.
 
 %   MATPOWER
-%   Copyright (c) 2022-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2022-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_load_cpf.m

@@ -1,8 +1,12 @@
 classdef dme_load_cpf < mp.dme_load
 % mp.dme_load_cpf - Data model element for load for CPF.
+%
+% To parent class :class:`mp.dme_load`, adds method for adjusting model
+% parameters based on value of continuation parameter :math:`\lambda`, and
+% overrides export_vars to export these updated parameter values.
 
 %   MATPOWER
-%   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2020-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_load_opf.m

@@ -1,8 +1,11 @@
 classdef dme_load_opf < mp.dme_load & mp.dme_shared_opf
 % mp.dme_load_opf - Data model element for load for OPF.
+%
+% To parent class :class:`mp.dme_load`, adds pretty-printing for **lim**
+% sections.
 
 %   MATPOWER
-%   Copyright (c) 2022-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2022-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_reserve_gen.m

@@ -1,7 +1,10 @@
 classdef dme_reserve_gen < mp.dm_element & mp.dme_shared_opf
 % mp.dme_reserve_gen - Data model element for reserve generator.
 %
-% Adds the following columns in the main data table:
+% Implements the data element model for reserve generator elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ==============  =========  =====================================
 %   Name            Type       Description

lib/+mp/dme_reserve_zone.m

@@ -1,7 +1,10 @@
 classdef dme_reserve_zone < mp.dm_element & mp.dme_shared_opf
 % mp.dme_reserve_zone - Data model element for reserve zone.
 %
-% Adds the following columns in the main data table:
+% Implements the data element model for reserve zone elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   =========  =========  ==================================================
 %   Name       Type       Description

lib/+mp/dme_shared_opf.m

@@ -1,10 +1,11 @@
 classdef (Abstract) dme_shared_opf < handle
 % mp.dme_shared_opf - Mixin class for OPF **data model element** objects.
 %
-% For all elements of mp.data_model_opf.
+% For all elements of mp.data_model_opf, adds shared functionality for
+% pretty-printing of **lim** sections.
 
 %   MATPOWER
-%   Copyright (c) 2022-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2022-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_shunt.m

@@ -1,7 +1,10 @@
 classdef dme_shunt < mp.dm_element
 % mp.dme_shunt - Data model element for shunt.
 %
-% Adds the following columns in the main data table:
+% Implements the data element model for shunt elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ========  =========  =====================================
 %   Name      Type       Description

lib/+mp/dme_shunt_cpf.m

@@ -1,8 +1,12 @@
 classdef dme_shunt_cpf < mp.dme_shunt
 % mp.dme_shunt_cpf - Data model element for shunt for CPF.
+%
+% To parent class :class:`mp.dme_shunt`, adds method for adjusting model
+% parameters based on value of continuation parameter :math:`\lambda`, and
+% overrides export_vars() to export these updated parameter values.
 
 %   MATPOWER
-%   Copyright (c) 2020-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2020-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_shunt_opf.m

@@ -1,8 +1,11 @@
 classdef dme_shunt_opf < mp.dme_shunt & mp.dme_shared_opf
 % mp.dme_shunt_opf - Data model element for shunt for OPF.
+%
+% To parent class :class:`mp.dme_shunt`, adds pretty-printing for **lim**
+% sections.
 
 %   MATPOWER
-%   Copyright (c) 2022-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2022-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

lib/+mp/dme_xfmr3p.m

@@ -1,7 +1,10 @@
 classdef dme_xfmr3p < mp.dm_element
 % mp.dme_xfmr3p - Data model element for 3-phase transformer.
 %
-% Adds the following columns in the main data table:
+% Implements the data element model for 3-phase transformer elements.
+%
+% Adds the following columns in the main data table, found in the
+% :attr:`tab` property:
 %
 %   ============  =========  =============================================
 %   Name          Type       Description