Add mp.load_dm function to load the data model.

CHANGES.md

@@ -25,6 +25,7 @@ since 8.0
   - Make optional the `mpopt` argument to `mp.task.run()`.
   - Refactor part of `mp.task.run()` method into new `mp.task.load_dm()`
     method used to load the data model object.
+  - Add `mp.load_dm()` function to load the data model object.
 
 #### 6/4/24
   - Add shunt loss columns (`psh_fr`, `qsh_fr`, `psh_to`, `qsh_to`) to

docs/sphinx/source/matlab-source/matpower/+mp/load_dm.m

@@ -0,0 +1 @@
+../../../../../../lib/+mp/load_dm.m

docs/sphinx/source/ref-manual/functions/index.rst

@@ -33,5 +33,5 @@ Other Functions
 ---------------
 
 .. toctree::
-
+   mp/load_dm
    mp_table_class

docs/sphinx/source/ref-manual/functions/mp/load_dm.rst

@@ -0,0 +1,8 @@
+.. currentmodule:: matpower.+mp
+
+:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/matpower/blob/master/lib/+mp/load_dm.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.load_dm
+----------
+
+.. autofunction:: load_dm

docs/src/MATPOWER-manual/MATPOWER-manual.tex

@@ -8662,7 +8662,7 @@ \subsubsection*{New Features}
 \end{itemize}
 \item New functions/methods:
     \begin{itemize}
-        \item \code{foo} 
+        \item \code{mp.load\_dm} -- Loads a data model object.
     \end{itemize}
 \end{itemize}
 

lib/+mp/load_dm.m

@@ -0,0 +1,94 @@
+function [dm, task_rv] = load_dm(d, task_class, mpopt, varargin)
+% mp.load_dm - Load a |MATPOWER| data model.
+% ::
+%
+%   dm = mp.load_dm(d)
+%   dm = mp.load_dm(d, task_class)
+%   dm = mp.load_dm(d, task_class, mpopt)
+%   dm = mp.load_dm(d, task_class, mpopt, ...)
+%   [dm, task] = mp.load_dm(...)
+%
+% Uses a task object to load a |MATPOWER| data model object, optionally
+% returning the task object as well.
+%
+% The resulting data model object can later be passed to run_pf, run_cpf,
+% run_opf, or directly to the :meth:`run() <mp.task.run>` method of the
+% task object.
+%
+% Inputs:
+%   d : data source specification, currently assumed to be a |MATPOWER|
+%       case name or case struct (``mpc``)
+%   task_class (function handle) : *(optional)* handle to constructor of
+%       task class, *(default is mp.task_opf)*
+%   mpopt (struct) : *(optional)* |MATPOWER| options struct
+%
+%       Additional optional inputs can be provided as *<name>, <val>* pairs,
+%       with the following options:
+%
+%       - ``'mpx'`` - |MATPOWER| extension or cell array of |MATPOWER|
+%         extensions to apply
+%
+% Outputs:
+%   dm (mp.data_model) : data model object
+%   task (mp.task) : task object containing the solved run including the
+%       data, network, and mathematical model objects.
+%
+% See also run_pf, run_cpf, run_opf, mp.task.
+
+%   MATPOWER
+%   Copyright (c) 2021-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.
+
+%% assign default inputs
+if nargin < 3
+    mpopt = mpoption;
+    if nargin < 2
+        task_class = @mp.task_opf;
+    end
+end
+mpx = {};
+if rem(length(varargin), 2)
+    error('mp.load_dm: arguments following MPOPT must appear in name/value pairs');
+end
+
+%% assign overridden inputs
+for k = 1:2:length(varargin)
+    val  = varargin{k+1};
+    switch varargin{k}      %% arg name
+        case 'mpx'
+            if iscell(val)
+                mpx = val;
+            else
+                mpx = { val };
+            end
+    end
+end
+
+%% extract extensions from mpopt, if specified
+if isfield(mpopt.exp, 'mpx') && ~isempty(mpopt.exp.mpx)
+    if iscell(mpopt.exp.mpx)
+        mpx = [mpx mpopt.exp.mpx];
+    else
+        mpx = { mpx{:}, mpopt.exp.mpx };
+    end
+end
+
+%% apply extensions
+for k = 1:length(mpx)
+    task_class = mpx{k}.task_class(task_class, mpopt);
+end
+
+%% create task object
+task = task_class();
+
+%% load data model
+task.load_dm(d, mpopt, mpx);
+
+dm = task.dm;
+if nargout > 1
+    task_rv = task;
+end

lib/mpver.m

@@ -36,7 +36,7 @@
 v{1} = struct(  'Name',     'MATPOWER', ... 
                 'Version',  '8.0.1-dev', ...
                 'Release',  '', ...
-                'Date',     '04-Jun-2024' );
+                'Date',     '11-Jun-2024' );
 if nargout > 0
     if nargin > 0
         rv = v{1};

lib/t/generate_matpower_autodoc.m

@@ -256,7 +256,9 @@ function generate_matpower_autodoc(install_dir)
     'run_cpf', ...
     'run_opf', ...
 };
-lib_mp_fcns = {};
+lib_mp_fcns = {
+    'load_dm', ...
+};
 lib_t_fcns = {
     'test_matpower', ...
     't_mp_mapped_array', ...