Add reference documentation for legacy task classes.

MATPOWER · Feb 15, 2024 · 0dd290c · 0dd290c
1 parent db70d88
commit 0dd290c
Show file tree

Hide file tree

Showing 17 changed files with 303 additions and 49 deletions.
diff --git a/docs/sphinx/source/matlab-source/matpower/+mp/task_cpf_legacy.m b/docs/sphinx/source/matlab-source/matpower/+mp/task_cpf_legacy.m
@@ -0,0 +1 @@
+../../../../../../lib/+mp/task_cpf_legacy.m
diff --git a/docs/sphinx/source/matlab-source/matpower/+mp/task_opf_legacy.m b/docs/sphinx/source/matlab-source/matpower/+mp/task_opf_legacy.m
@@ -0,0 +1 @@
+../../../../../../lib/+mp/task_opf_legacy.m
diff --git a/docs/sphinx/source/matlab-source/matpower/+mp/task_pf_legacy.m b/docs/sphinx/source/matlab-source/matpower/+mp/task_pf_legacy.m
@@ -0,0 +1 @@
+../../../../../../lib/+mp/task_pf_legacy.m
diff --git a/docs/sphinx/source/matlab-source/matpower/+mp/task_shared_legacy.m b/docs/sphinx/source/matlab-source/matpower/+mp/task_shared_legacy.m
@@ -0,0 +1 @@
+../../../../../../lib/+mp/task_shared_legacy.m
diff --git a/docs/sphinx/source/ref-manual/classes/index.rst b/docs/sphinx/source/ref-manual/classes/index.rst
@@ -4,6 +4,9 @@ Classes
 Task Classes
 ------------
 
+Core Task Classes
++++++++++++++++++
+
 .. toctree::
    :name: sec_task_classes
 
@@ -12,6 +15,19 @@ Task Classes
    mp/task_cpf
    mp/task_opf
 
+Legacy Task Classes
++++++++++++++++++++
+
+Used by MP-Core when called by the *legacy* |/MATPOWER/| *framework*.
+
+.. toctree::
+   :name: sec_legacy_task_classes
+
+   mp/task_pf_legacy
+   mp/task_cpf_legacy
+   mp/task_opf_legacy
+   mp/task_shared_legacy
+
 
 Data Model Classes
 ------------------

diff --git a/docs/sphinx/source/ref-manual/classes/mp/task_cpf_legacy.rst b/docs/sphinx/source/ref-manual/classes/mp/task_cpf_legacy.rst
@@ -0,0 +1,10 @@
+.. automodule:: matpower.+mp
+
+:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/matpower/blob/master/lib/+mp/task_cpf_legacy.m" target=_blank><svg height="32" aria-hidden="true" viewBox="0 0 16 16" version="1.1" width="32" data-view-component="true" class="octicon octicon-mark-github v-align-middle color-fg-default"><path d="M8 0c4.42 0 8 3.58 8 8a8.013 8.013 0 0 1-5.45 7.59c-.4.08-.55-.17-.55-.38 0-.27.01-1.13.01-2.2 0-.75-.25-1.23-.54-1.48 1.78-.2 3.65-.88 3.65-3.95 0-.88-.31-1.59-.82-2.15.08-.2.36-1.02-.08-2.12 0 0-.67-.22-2.2.82-.64-.18-1.32-.27-2-.27-.68 0-1.36.09-2 .27-1.53-1.03-2.2-.82-2.2-.82-.44 1.1-.16 1.92-.08 2.12-.51.56-.82 1.28-.82 2.15 0 3.06 1.86 3.75 3.64 3.95-.23.2-.44.55-.51 1.07-.46.21-1.61.55-2.33-.66-.15-.24-.6-.83-1.23-.82-.67.01-.27.38.01.53.34.19.73.9.82 1.13.16.45.68 1.31 2.69.94 0 .67.01 1.3.01 1.49 0 .21-.15.45-.55.38A7.995 7.995 0 0 1 0 8c0-4.42 3.58-8 8-8Z"></path></svg></a></div>`
+
+mp.task_cpf_legacy
+------------------
+
+.. autoclass:: task_cpf_legacy
+    :show-inheritance:
+    :members:
diff --git a/docs/sphinx/source/ref-manual/classes/mp/task_opf_legacy.rst b/docs/sphinx/source/ref-manual/classes/mp/task_opf_legacy.rst
@@ -0,0 +1,10 @@
+.. automodule:: matpower.+mp
+
+:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/matpower/blob/master/lib/+mp/task_opf_legacy.m" target=_blank><svg height="32" aria-hidden="true" viewBox="0 0 16 16" version="1.1" width="32" data-view-component="true" class="octicon octicon-mark-github v-align-middle color-fg-default"><path d="M8 0c4.42 0 8 3.58 8 8a8.013 8.013 0 0 1-5.45 7.59c-.4.08-.55-.17-.55-.38 0-.27.01-1.13.01-2.2 0-.75-.25-1.23-.54-1.48 1.78-.2 3.65-.88 3.65-3.95 0-.88-.31-1.59-.82-2.15.08-.2.36-1.02-.08-2.12 0 0-.67-.22-2.2.82-.64-.18-1.32-.27-2-.27-.68 0-1.36.09-2 .27-1.53-1.03-2.2-.82-2.2-.82-.44 1.1-.16 1.92-.08 2.12-.51.56-.82 1.28-.82 2.15 0 3.06 1.86 3.75 3.64 3.95-.23.2-.44.55-.51 1.07-.46.21-1.61.55-2.33-.66-.15-.24-.6-.83-1.23-.82-.67.01-.27.38.01.53.34.19.73.9.82 1.13.16.45.68 1.31 2.69.94 0 .67.01 1.3.01 1.49 0 .21-.15.45-.55.38A7.995 7.995 0 0 1 0 8c0-4.42 3.58-8 8-8Z"></path></svg></a></div>`
+
+mp.task_opf_legacy
+------------------
+
+.. autoclass:: task_opf_legacy
+    :show-inheritance:
+    :members:
diff --git a/docs/sphinx/source/ref-manual/classes/mp/task_pf_legacy.rst b/docs/sphinx/source/ref-manual/classes/mp/task_pf_legacy.rst
@@ -0,0 +1,10 @@
+.. automodule:: matpower.+mp
+
+:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/matpower/blob/master/lib/+mp/task_pf_legacy.m" target=_blank><svg height="32" aria-hidden="true" viewBox="0 0 16 16" version="1.1" width="32" data-view-component="true" class="octicon octicon-mark-github v-align-middle color-fg-default"><path d="M8 0c4.42 0 8 3.58 8 8a8.013 8.013 0 0 1-5.45 7.59c-.4.08-.55-.17-.55-.38 0-.27.01-1.13.01-2.2 0-.75-.25-1.23-.54-1.48 1.78-.2 3.65-.88 3.65-3.95 0-.88-.31-1.59-.82-2.15.08-.2.36-1.02-.08-2.12 0 0-.67-.22-2.2.82-.64-.18-1.32-.27-2-.27-.68 0-1.36.09-2 .27-1.53-1.03-2.2-.82-2.2-.82-.44 1.1-.16 1.92-.08 2.12-.51.56-.82 1.28-.82 2.15 0 3.06 1.86 3.75 3.64 3.95-.23.2-.44.55-.51 1.07-.46.21-1.61.55-2.33-.66-.15-.24-.6-.83-1.23-.82-.67.01-.27.38.01.53.34.19.73.9.82 1.13.16.45.68 1.31 2.69.94 0 .67.01 1.3.01 1.49 0 .21-.15.45-.55.38A7.995 7.995 0 0 1 0 8c0-4.42 3.58-8 8-8Z"></path></svg></a></div>`
+
+mp.task_pf_legacy
+-----------------
+
+.. autoclass:: task_pf_legacy
+    :show-inheritance:
+    :members:
diff --git a/docs/sphinx/source/ref-manual/classes/mp/task_shared_legacy.rst b/docs/sphinx/source/ref-manual/classes/mp/task_shared_legacy.rst
@@ -0,0 +1,10 @@
+.. automodule:: matpower.+mp
+
+:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/matpower/blob/master/lib/+mp/task_shared_legacy.m" target=_blank><svg height="32" aria-hidden="true" viewBox="0 0 16 16" version="1.1" width="32" data-view-component="true" class="octicon octicon-mark-github v-align-middle color-fg-default"><path d="M8 0c4.42 0 8 3.58 8 8a8.013 8.013 0 0 1-5.45 7.59c-.4.08-.55-.17-.55-.38 0-.27.01-1.13.01-2.2 0-.75-.25-1.23-.54-1.48 1.78-.2 3.65-.88 3.65-3.95 0-.88-.31-1.59-.82-2.15.08-.2.36-1.02-.08-2.12 0 0-.67-.22-2.2.82-.64-.18-1.32-.27-2-.27-.68 0-1.36.09-2 .27-1.53-1.03-2.2-.82-2.2-.82-.44 1.1-.16 1.92-.08 2.12-.51.56-.82 1.28-.82 2.15 0 3.06 1.86 3.75 3.64 3.95-.23.2-.44.55-.51 1.07-.46.21-1.61.55-2.33-.66-.15-.24-.6-.83-1.23-.82-.67.01-.27.38.01.53.34.19.73.9.82 1.13.16.45.68 1.31 2.69.94 0 .67.01 1.3.01 1.49 0 .21-.15.45-.55.38A7.995 7.995 0 0 1 0 8c0-4.42 3.58-8 8-8Z"></path></svg></a></div>`
+
+mp.task_shared_legacy
+---------------------
+
+.. autoclass:: task_shared_legacy
+    :show-inheritance:
+    :members:
diff --git a/docs/sphinx/source/ref-manual/introduction.rst b/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** |MATPOWER| framework, but not the **legacy** |MATPOWER| framework or the other packages such as |MPOM>|, |MIPS>|, |MPTEST>|, or |MOST>|.
diff --git a/lib/+mp/dm_converter_mpc2_legacy.m b/lib/+mp/dm_converter_mpc2_legacy.m
@@ -1,5 +1,5 @@
 classdef dm_converter_mpc2_legacy < mp.dm_converter_mpc2
-% mp.dm_converter_mpc2_legacy - |MATPOWER| **data model converter** for MATPOWER case v2.
+% mp.dm_converter_mpc2_legacy - Legacy |MATPOWER| **data model converter** for MATPOWER case v2.
 %
 % Adds to mp.dm_converter_mpc2 the ability to handle legacy user
 % customization.
@@ -11,7 +11,7 @@
 % See also mp.dm_converter, mp.dm_converter_mpc2, mp.task_opf_legacy.
 
 %   MATPOWER
-%   Copyright (c) 2021-2023, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2021-2024, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MATPOWER.

diff --git a/lib/+mp/task_cpf_legacy.m b/lib/+mp/task_cpf_legacy.m
@@ -1,42 +1,90 @@
 classdef task_cpf_legacy < mp.task_cpf & mp.task_shared_legacy
-%MP.TASK_CPF_LEGACY  MATPOWER task for legacy continuation power flow (CPF).
-%   MP.TASK_CPF_LEGACY provides implementation for continuation power flow problem.
+% mp.task_cpf - |MATPOWER| task for legacy continuation power flow (CPF).
 %
-%   Properties
-%       ?
+% Adds functionality needed by the *legacy* |/MATPOWER/| *framework* to the
+% task implementation for the continuation power flow problem.
 %
-%   Methods
-%       ?
+% mp.task_pf Methods:
+%   * run_pre - pre-process inputs that are for legacy framework only
+%   * run_post - export results back to data model source
+%   * legacy_post_run - post-process *legacy framework* outputs
 %
-%   See also MP.TASK_CPF
+% See also mp.task_cpf, mp.task, mp.task_shared_legacy.
 
 %   MATPOWER
-%   Copyright (c) 2020-2022, 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.
 %   Covered by the 3-clause BSD License (see LICENSE file for details).
 %   See https://matpower.org for more info.
 
-    properties
-    end
-
     methods
         %%-----  task methods  -----
         function [d, mpopt] = run_pre(obj, d, mpopt)
+            % Pre-process inputs that are for *legacy framework* only.
+            % ::
+            %
+            %   [d, mpopt] = obj.run_pre(d, mpopt)
+            %
+            % Inputs:
+            %   d : data source specification, currently assumed to be a
+            %       |MATPOWER| case name or case struct (``mpc``)
+            %   mpopt (struct) : |MATPOWER| options struct
+            %
+            % Outputs:
+            %   d : updated value of corresponding input
+            %   mpopt (struct) : updated value of corresponding input
+            %
+            % Call :meth:`run_pre_legacy() <mp.task_shared_legacy.run_pre_legacy>`
+            % method for both input cases before calling parent.
+
             [d{1}, mpopt] = obj.run_pre_legacy(d{1}, mpopt);
             [d{2}, mpopt] = obj.run_pre_legacy(d{2}, mpopt);
             [d, mpopt] = [email protected]_cpf(obj, d, mpopt);
         end
 
         function obj = run_post(obj, mm, nm, dm, mpopt)
+            % Export results back to data model source.
+            % ::
+            %
+            %   obj.run_post(mm, nm, dm, mpopt)
+            %
+            % Inputs:
+            %   mm (mp.math_model) : mathmatical model object
+            %   nm (mp.net_model) : network model object
+            %   dm (mp.data_model) : data model object
+            %   mpopt (struct) : |MATPOWER| options struct
+            %
+            % Output:
+            %   obj (mp.task) : task object
+            %
+            % Calls mp.dm_converter.export and saves the result
+            % in the data model ``source`` property.
+
             if obj.nm.np ~= 0
                 obj.dm.source = obj.dmc.export(obj.dm, obj.dm.source);
             end
         end
 
         %%-----  other methods  -----
         function [results, success] = legacy_post_run(obj, mpopt)
+            % Post-process *legacy framework* outputs.
+            % ::
+            %
+            %   [results, success] = obj.legacy_post_run(mpopt)
+            %
+            % Input:
+            %   mpopt (struct) : |MATPOWER| options struct
+            %
+            % Outputs:
+            %   results (struct) : results struct for *legacy* |/MATPOWER/|
+            %       *framework*, see Table 5.1 in legacy |MUM|.
+            %   success (integer) : 1 - succeeded, 0 - failed
+            %
+            % Extract ``results`` and ``success`` and save the
+            % task object in ``results.task`` before returning.
+
             success = obj.success;
             results = obj.dm.source;
             results.task = obj;

diff --git a/lib/+mp/task_opf_legacy.m b/lib/+mp/task_opf_legacy.m
@@ -1,46 +1,90 @@
 classdef task_opf_legacy < mp.task_opf & mp.task_shared_legacy
-%MP.TASK_OPF_LEGACY  MATPOWER task for legacy optimal power flow (OPF).
-%   MP.TASK_OPF_LEGACY provides implementation for optimal power flow problem.
+% mp.task_opf - |MATPOWER| task for legacy optimal power flow (OPF).
 %
-%   Properties
-%       ?
+% Adds functionality needed by the *legacy* |/MATPOWER/| *framework* to the
+% task implementation for the optimal power flow problem.
 %
-%   Methods
-%       ?
+% mp.task_pf Methods:
+%   * run_pre - pre-process inputs that are for legacy framework only
+%   * run_post - export results back to data model source
+%   * dm_converter_class_mpc2_default - set to mp.dm_converter_mpc2_legacy
+%   * data_model_build_post - get data model converter to do more input pre-processing
+%   * math_model_class_default - use legacy math model subclasses
+%   * legacy_post_run - post-process *legacy framework* outputs
 %
-%   See also MP.TASK_OPF
+% See also mp.task_opf, mp.task, mp.task_shared_legacy.
 
 %   MATPOWER
-%   Copyright (c) 2020-2022, 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.
 %   Covered by the 3-clause BSD License (see LICENSE file for details).
 %   See https://matpower.org for more info.
 
-    properties
-    end
-
     methods
         %%-----  task methods  -----
         function [d, mpopt] = run_pre(obj, d, mpopt)
+            % Pre-process inputs that are for *legacy framework* only.
+            % ::
+            %
+            %   [d, mpopt] = obj.run_pre(d, mpopt)
+            %
+            % Inputs:
+            %   d : data source specification, currently assumed to be a
+            %       |MATPOWER| case name or case struct (``mpc``)
+            %   mpopt (struct) : |MATPOWER| options struct
+            %
+            % Outputs:
+            %   d : updated value of corresponding input
+            %   mpopt (struct) : updated value of corresponding input
+            %
+            % Call :meth:`run_pre_legacy() <mp.task_shared_legacy.run_pre_legacy>`
+            % method before calling parent.
+
             [d, mpopt] = obj.run_pre_legacy(d, mpopt);
             [d, mpopt] = [email protected]_opf(obj, d, mpopt);
         end
 
         function obj = run_post(obj, mm, nm, dm, mpopt)
+            % Export results back to data model source.
+            % ::
+            %
+            %   obj.run_post(mm, nm, dm, mpopt)
+            %
+            % Inputs:
+            %   mm (mp.math_model) : mathmatical model object
+            %   nm (mp.net_model) : network model object
+            %   dm (mp.data_model) : data model object
+            %   mpopt (struct) : |MATPOWER| options struct
+            %
+            % Output:
+            %   obj (mp.task) : task object
+            %
+            % Calls mp.dm_converter.export and saves the result
+            % in the data model ``source`` property.
+
             if obj.nm.np ~= 0
                 obj.dm.source = obj.dmc.export(obj.dm, obj.dm.source);
             end
         end
 
         %%-----  data model converter methods  -----
         function dmc_class = dm_converter_class_mpc2_default(obj)
+            % Set to mp.dm_converter_mpc2_legacy.
+            % ::
+            %
+            %   dmc_class = obj.dm_converter_class_mpc2_default()
+
             dmc_class = @mp.dm_converter_mpc2_legacy;
         end
 
         %%-----  data model methods  -----
         function dm = data_model_build_post(obj, dm, dmc, mpopt)
+            % Get data model converter to do more input pre-processing
+            % after calling superclass
+            % :meth:`data_model_build_post() <mp.task_opf.data_model_build_post>`.
+
             %% call parent
             dm = [email protected]_opf(obj, dm, dmc, mpopt);
 
@@ -50,9 +94,14 @@
 
         %%-----  mathematical model methods  -----
         function mm_class = math_model_class_default(obj, nm, dm, mpopt)
-            %% mp.mm_shared_opf_legacy (compatible with opf_model) is required
-            %% to support legacy cost functions and callback functions that
-            %% expect to find mpc in mm.mpc.
+            % Use legacy math model subclasses to support legacy costs and callbacks.
+            %
+            % Uses math model variations that inherit from
+            % mp.mm_shared_opf_legacy (compatible with the legacy
+            % :class:`opf_model`), in order to support legacy cost functions
+            % and callback functions that expect to find the |MATPOWER| case
+            % struct in ``mm.mpc``.
+
             switch upper(mpopt.model)
                 case 'AC'
                     if mpopt.opf.v_cartesian
@@ -74,7 +123,29 @@
         end
 
         function [results, success, raw] = legacy_post_run(obj, mpopt)
-            %% from opf_execute(), dcopf_solver(), nlpopf_solver()
+            % Post-process *legacy framework* outputs.
+            % ::
+            %
+            %   [results, success, raw] = obj.legacy_post_run(mpopt)
+            %
+            % Input:
+            %   mpopt (struct) : |MATPOWER| options struct
+            %
+            % Outputs:
+            %   results (struct) : results struct for *legacy* |/MATPOWER/|
+            %       *framework*, see Table 6.1 in legacy |MUM|.
+            %   success (integer) : 1 - succeeded, 0 - failed
+            %   raw (struct) : see ``raw`` field in Table 6.1 in legacy
+            %       |MUM|.
+            %
+            % Extract ``results`` and ``success`` and save the
+            % task object in ``results.task`` before returning. This
+            % method also creates and populates numerous other fields
+            % expected in the legacy OPF ``results`` struct, such as
+            % ``f``, ``x``, ``om``, ``mu``, ``g``, ``dg``, ``raw``, 
+            % ``var``, ``nle``, ``nli``, ``lin``, and ``cost``.
+            % Based on code from the legacy functions :func:`opf_execute`,
+            % :func:`dcopf_solver`, and :func:`nlpopf_solver`.
 
             %% unpack data
             mm = obj.mm;