From fdb00109bbb249ee1adf7be225dd61cc8c1cb013 Mon Sep 17 00:00:00 2001 From: Ray Zimmerman Date: Tue, 11 Jun 2024 15:16:31 -0600 Subject: [PATCH] Add mp.load_dm function to load the data model. --- CHANGES.md | 1 + .../matlab-source/matpower/+mp/load_dm.m | 1 + .../source/ref-manual/functions/index.rst | 2 +- .../ref-manual/functions/mp/load_dm.rst | 8 ++ docs/src/MATPOWER-manual/MATPOWER-manual.tex | 2 +- lib/+mp/load_dm.m | 94 +++++++++++++++++++ lib/mpver.m | 2 +- lib/t/generate_matpower_autodoc.m | 4 +- 8 files changed, 110 insertions(+), 4 deletions(-) create mode 120000 docs/sphinx/source/matlab-source/matpower/+mp/load_dm.m create mode 100644 docs/sphinx/source/ref-manual/functions/mp/load_dm.rst create mode 100644 lib/+mp/load_dm.m diff --git a/CHANGES.md b/CHANGES.md index 7beead39..edce724b 100644 --- a/CHANGES.md +++ b/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 diff --git a/docs/sphinx/source/matlab-source/matpower/+mp/load_dm.m b/docs/sphinx/source/matlab-source/matpower/+mp/load_dm.m new file mode 120000 index 00000000..bc1ae532 --- /dev/null +++ b/docs/sphinx/source/matlab-source/matpower/+mp/load_dm.m @@ -0,0 +1 @@ +../../../../../../lib/+mp/load_dm.m \ No newline at end of file diff --git a/docs/sphinx/source/ref-manual/functions/index.rst b/docs/sphinx/source/ref-manual/functions/index.rst index 0f717b8d..2620c67a 100644 --- a/docs/sphinx/source/ref-manual/functions/index.rst +++ b/docs/sphinx/source/ref-manual/functions/index.rst @@ -33,5 +33,5 @@ Other Functions --------------- .. toctree:: - + mp/load_dm mp_table_class diff --git a/docs/sphinx/source/ref-manual/functions/mp/load_dm.rst b/docs/sphinx/source/ref-manual/functions/mp/load_dm.rst new file mode 100644 index 00000000..f0ce4374 --- /dev/null +++ b/docs/sphinx/source/ref-manual/functions/mp/load_dm.rst @@ -0,0 +1,8 @@ +.. currentmodule:: matpower.+mp + +:raw-html:`
` + +mp.load_dm +---------- + +.. autofunction:: load_dm diff --git a/docs/src/MATPOWER-manual/MATPOWER-manual.tex b/docs/src/MATPOWER-manual/MATPOWER-manual.tex index be3afd42..f0beb6cb 100644 --- a/docs/src/MATPOWER-manual/MATPOWER-manual.tex +++ b/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} diff --git a/lib/+mp/load_dm.m b/lib/+mp/load_dm.m new file mode 100644 index 00000000..37544c60 --- /dev/null +++ b/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() ` 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 *, * 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 diff --git a/lib/mpver.m b/lib/mpver.m index 2efd6a5c..c853d9bb 100644 --- a/lib/mpver.m +++ b/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}; diff --git a/lib/t/generate_matpower_autodoc.m b/lib/t/generate_matpower_autodoc.m index 3a521e4b..8487d0fd 100644 --- a/lib/t/generate_matpower_autodoc.m +++ b/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', ...