Release 4.0.

Author: rdzman

AUTHORS

@@ -1,2 +1,5 @@
 Ray Zimmerman <rz10@cornell.edu>
+
+Shrirang Abhyankar
+Alex Flueck
 Carlos E. Murillo-Sanchez <carlos_murillo@ieee.org>

CHANGES.md

@@ -2,8 +2,11 @@ Change history for MP-Opt-Model
 ===============================
 
 
-since last release
-------------------
+Version 4.0 - *Oct 18, 2021*
+----------------------------
+
+#### 10/18/21
+  - Release 4.0.
 
 #### 5/8/21
   - Add several enhancements to `mp_idx_manager/set_type_idx_map()`.

CITATION

@@ -1,11 +1,11 @@
 We request that publications derived from the use of MP-Opt-Model
 explicitly acknowledge that fact by citing the MP-Opt-Model User's
 Manual. The citation and DOI can be version-specific or general, as
-appropriate. For version 3.0, use:
+appropriate. For version 4.0, use:
 
-  R. D. Zimmerman. MP-Opt-Model User's Manual, Version 3.0. 2020.
-  [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-3.0.pdf
-  doi: 10.5281/zenodo.4073361
+  R. D. Zimmerman. MP-Opt-Model User's Manual, Version 4.0. 2021.
+  [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-4.0.pdf
+  doi: 10.5281/zenodo.5576755
 
 For a version non-specific citation, use the following citation and DOI,
 with *\<YEAR\>* replaced by the year of the most recent release:

README.md

@@ -52,17 +52,19 @@ of MATLAB or Octave, including setting up your MATLAB/Octave path.
   t_have_fcn..............ok
   t_nested_struct_copy....ok
   t_nleqs_master..........ok (30 of 150 skipped)
+  t_pnes_master...........ok
   t_qps_master............ok (100 of 432 skipped)
   t_miqps_master..........ok (68 of 288 skipped)
   t_nlps_master...........ok
   t_opt_model.............ok
   t_om_solve_leqs.........ok
   t_om_solve_nleqs........ok (36 of 194 skipped)
+  t_om_solve_pne..........ok
   t_om_solve_qps..........ok (81 of 387 skipped)
   t_om_solve_miqps........ok (14 of 118 skipped)
   t_om_solve_nlps.........ok
-  All tests successful (3032 passed, 329 skipped of 3361)
-  Elapsed time 3.11 seconds.
+  All tests successful (3430 passed, 329 skipped of 3759)
+  Elapsed time 7.75 seconds.
 ```
 
 Sample Usage
@@ -200,11 +202,11 @@ function, e.g.: `qps_master`, `miqps_master`, and `nlps_master`.
 We request that publications derived from the use of MP-Opt-Model
 explicitly acknowledge that fact by citing the [MP-Opt-Model User's Manual][7].
 The citation and DOI can be version-specific or general, as appropriate.
-For version 3.0, use:
+For version 4.0, use:
 
->   R. D. Zimmerman. *MP-Opt-Model User's Manual, Version 3.0*. 2020.
-    [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-3.0.pdf  
-    doi: [10.5281/zenodo.4073361](https://doi.org/10.5281/zenodo.4073361)
+>   R. D. Zimmerman. *MP-Opt-Model User's Manual, Version 4.0*. 2021.
+    [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-4.0.pdf  
+    doi: [10.5281/zenodo.5576755](https://doi.org/10.5281/zenodo.5576755)
 
 For a version non-specific citation, use the following citation and DOI,
 with *\<YEAR\>* replaced by the year of the most recent release:

docs/MP-Opt-Model-manual.pdf

@@ -0,0 +1,69 @@
+What's New in MP-Opt-Model 4.0
+------------------------------
+
+#### Released October 18, 2021
+
+Below is a summary of the changes since version 3.0 of MP-Opt-Model. See
+the [`CHANGES.md`][1] file for all the gory details. For release notes
+for previous versions, see Appendix C of the [MP-Opt-Model User's
+Manual][2].
+
+
+#### New Features
+  - Support for new class of problems -- parameterized nonlinear equations
+    (PNE). Either create a model with only equality constraints (no
+    inequalities or costs) and with number of variables equal to 1 more than
+    number of constraints, _or_ call `pnes_master()` directly. See Section 4.5
+    of User's Manual for details.
+    *Thanks to Shrirang Abhyankar and Alexander Flueck for contributions to this
+    feature, which is based on the continuation power flow code in MATPOWER 7.1.*
+    - Predictor/corrector numerical continuation method for tracing solution
+      curves for PNE problems.
+    - Plotting of solution curves.
+    - User-defined event functions and callback functions.
+    - Warm-start capabilities.
+  - Optional threshold for detecting failure of LEQ solve, by setting the
+    `leq_opt.thresh` option. If the absolute value of any element of the
+    solution vector exceeds the threshold, `exitflag` is set to 0, indicating
+    failure.
+  - New functions:
+      - `pnes_master()` provides unified interface for parameterized nonlinear
+         equation (PNE) solvers.
+      - `pne_callback_default()` collects PNE results and optionally plots
+         solution curve.
+      - `pne_callback_nose()` handles event signaling a nose point or limit
+         has been reached.
+      - `pne_callback_target_lam()` handles event signaling a target value
+         of parameter λ has been reached.
+      - `pne_detect_events()` detects events from event function values.
+      - `pne_detected_event()` returns detected event details for events
+        with a particular name.
+      - `pne_event_nose()` detects the limit or nose point.
+      - `pne_event_target_lam()` detects a target λ value.
+      - `pne_pfcn_arc_length()` implements arc length parameterization.
+      - `pne_pfcn_natural()` implements natural parameterization.
+      - `pne_pfcn_pseudo_arc_length()` implements pseudo arc length
+        parameterization.
+      - `pne_register_callbacks()` registers callback functions.
+      - `pne_register_events()` registers event functions.
+      - `mp_idx_manager/set_type_idx_map()` method returns information about
+        mapping of indices for a given set type back to the corresponding
+        named (and possibly indexed) sets.
+      - `mpopt2pneopt()` creates or modifies an options struct for
+        `pnes_master()` from a MATPOWER options struct.
+
+#### Bugs Fixed:
+  - Calling the `problem_type()` or `is_mixed_integer()` method on an empty
+    model no longer causes a fatal error.
+
+#### Other Changes
+  - Labels from the `set_types` property are now used as headers for
+    `opt_model/display()` to simplify things facilitate use by sub-classes.
+  - Refactored `describe_idx` into a new method, `set_type_idx_map`, that
+    returns in information in a programmatically usable form, and an updated
+    `describe_idx` that calls the new method, then formats the results in
+    the expected char array(s).
+
+
+[1]: ../../CHANGES.md
+[2]: ../MP-Opt-Model-manual.pdf

docs/relnotes/MP-Opt-Model-Release-Notes-4.0.md

@@ -151,7 +151,7 @@
 \newcommand{\mpomlink}[0]{\href{\mpomurl}{\mpom{}}}
 \newcommand{\mpomname}[0]{\mpom{}}
 % \newcommand{\mpomname}[0]{{{\bf M}{\sc at}{\bf P}{\sc ower} \textbf{Opt}imization \textbf{Model}}}
-\newcommand{\mpomver}[0]{4.0-dev}
+\newcommand{\mpomver}[0]{4.0}
 \newcommand{\most}[0]{{MOST}}
 \newcommand{\mostname}[0]{{{\bf M}{\sc atpower} \textbf{O}ptimal \textbf{S}cheduling \textbf{T}ool}}
 \newcommand{\mosturl}[0]{https://github.com/MATPOWER/most}
@@ -242,7 +242,7 @@
 %\title{\hl{--- DRAFT  ---}\\\hl{\em do not distribute}\\~\\{\huge \bfseries \mpomname{} User's Manual } \\ ~ \\ \LARGE Version \mpomver{}\\
 \title{{\huge \bfseries \mpomname{} User's Manual } \\ ~ \\ \LARGE Version \mpomver{}}
 \author{Ray~D.~Zimmerman}
-%\date{October 8, 2020} % comment this line to display the current date
+\date{October 18, 2021} % comment this line to display the current date
 %\date{May 8, 2020\thanks{Second revision. First revision was April 29, 2020}} % comment this line to display the current date
 
 %%% BEGIN DOCUMENT
@@ -253,7 +253,7 @@
 \vfill
 \begin{center}
 {\scriptsize
-\copyright~2020~\PSERC{}\\
+\copyright~2020, 2021~\PSERC{}\\
 All Rights Reserved}
 \end{center}
 
@@ -327,12 +327,12 @@ \subsection{License and Terms of Use}
 \subsection{Citing \mpom{}}
 
 We request that publications derived from the use of \mpom{} explicitly acknowledge that fact by citing the \mpomname{} User's Manual~\cite{mpom_manual}.
-The citation and DOI can be version-specific or general, as appropriate. For version 3.0, use:
+The citation and DOI can be version-specific or general, as appropriate. For version 4.0, use:
 
 \begin{quote}
 \footnotesize
-R.~D. Zimmerman. \mpomname{} User's Manual, Verision 3.0. 2020. [Online]. Available: \url{https://matpower.org/docs/MP-Opt-Model-manual-3.0.pdf}\\
-\doi{10.5281/zenodo.4073361}
+R.~D. Zimmerman. \mpomname{} User's Manual, Verision 4.0. 2021. [Online]. Available: \url{https://matpower.org/docs/MP-Opt-Model-manual-4.0.pdf}\\
+\doi{10.5281/zenodo.5576755}
 \end{quote}
 For a version non-specific citation, use the following citation and DOI,
 with \emph{\textless{}YEAR\textgreater{}} replaced by the year of the most recent release:
@@ -411,17 +411,19 @@ \subsection{Installation}
 t_have_fcn..............ok
 t_nested_struct_copy....ok
 t_nleqs_master..........ok (30 of 150 skipped)
+t_pnes_master...........ok
 t_qps_master............ok (100 of 432 skipped)
 t_miqps_master..........ok (68 of 288 skipped)
 t_nlps_master...........ok
 t_opt_model.............ok
 t_om_solve_leqs.........ok
 t_om_solve_nleqs........ok (36 of 194 skipped)
+t_om_solve_pne..........ok
 t_om_solve_qps..........ok (81 of 387 skipped)
 t_om_solve_miqps........ok (14 of 118 skipped)
 t_om_solve_nlps.........ok
-All tests successful (3032 passed, 329 skipped of 3361)
-Elapsed time 3.11 seconds.
+All tests successful (3430 passed, 329 skipped of 3759)
+Elapsed time 7.75 seconds.
 \end{Code}
 \end{enumerate}
 
@@ -2070,7 +2072,6 @@ \subsubsection{PNE Example}
 Then, call the \code{pnes\_master} function with a handle to that function, a starting value for $x$, and an option to make it trace the full continuation curve.
 \begin{Code}
 >> x = pnes_master(@f1p, [-1;0;0], struct('stop_at', 'FULL'))
->> pne_ex1
 
 x =
 
@@ -2108,7 +2109,7 @@ \subsubsection{PNE Example}
 \begin{Code}
 >> pne_ex1
 
-MP-Opt-Model Version 4.0, 03-May-2021 -- Predictor/Corrector Continuation Method
+MP-Opt-Model Version 4.0, 18-Oct-2021 -- Predictor/Corrector Continuation Method
 step   0  :                          lambda =  0.000,  6 corrector steps
 step   1  : PAL stepsize = 0.6       lambda =  0.081   2 corrector steps
 step   2  : PAL stepsize = 0.6       lambda =  0.162   2 corrector steps
@@ -2146,8 +2147,8 @@ \subsubsection{PNE Example}
    0
 
 f = 
-             0
-   -6.4837e-13
+            0
+  -6.4837e-13
 
 jac =
    1   1   6
@@ -4398,7 +4399,7 @@ \subsubsection*{Other Changes}
 \end{itemize}
 
 
-\subsection{Version 4.0 -- released Oct 19, 2021}
+\subsection{Version 4.0 -- released Oct 18, 2021}
 \label{app:v40}
 
 The \href{https://matpower.org/docs/MP-Opt-Model-manual-4.0.pdf}{\mpom{} 4.0 User's Manual} is available online.\footnote{\url{https://matpower.org/docs/MP-Opt-Model-manual-4.0.pdf}}
@@ -4495,7 +4496,7 @@ \subsubsection*{Other Changes}
 The BSD 3-Clause License. [Online]. Available: \url{https://opensource.org/licenses/BSD-3-Clause}.
 
 \bibitem{mpom_manual}
-R.~D. Zimmerman. \mpomname{} User's Manual. 2020.
+R.~D. Zimmerman. \mpomname{} User's Manual. 2021.
 [Online]. Available: \url{https://matpower.org/docs/MP-Opt-Model-manual.pdf}\\
 \doi{10.5281/zenodo.3818002}
 

docs/src/MP-Opt-Model-manual/MP-Opt-Model-manual.tex

@@ -1,12 +1,12 @@
 % MP-Opt-Model
-%   Version 3.0         08-Oct-2020
+%   Version 4.0         18-Oct-2021
 %
 %   MP-Opt-Model is a package of MATLAB/Octave M-files for constructing
-%   and solving mathematical optimization problems. It provides an
-%   easy-to-use, object-oriented interface for building and solving
-%   your optimization model. It also includes a unified interface for
-%   calling numerous LP, QP, mixed-integer and nonlinear solvers, with
-%   the ability to switch solvers by simply changing an input option.
+%   and solving mathematical programming and optimization problems. It
+%   provides an easy-to-use, object-oriented interface for building and
+%   solving your model. It also includes a unified interface for calling
+%   numerous LP, QP, mixed-integer and nonlinear solvers, with the ability
+%   to switch solvers by simply changing an input option.
 % 
 %   It is based on code that was originally developed by Ray D. Zimmerman
 %   of Cornell University as part of MATPOWER.
@@ -18,7 +18,7 @@
 %   MIPS is covered by the 3-clause BSD License (see LICENSE for details).
 
 %   MP-Opt-Model
-%   Copyright (c) 2020, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2020-2021, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MP-Opt-Model.

lib/Contents.m

@@ -9,17 +9,17 @@
 %   See also MPVER.
 
 %   MP-Opt-Model
-%   Copyright (c) 2010-2020, Power Systems Engineering Research Center (PSERC)
+%   Copyright (c) 2010-2021, Power Systems Engineering Research Center (PSERC)
 %   by Ray Zimmerman, PSERC Cornell
 %
 %   This file is part of MP-Opt-Model.
 %   Covered by the 3-clause BSD License (see LICENSE file for details).
 %   See https://github.com/MATPOWER/mp-opt-model for more info.
 
 v = struct( 'Name',     'MP-Opt-Model', ... 
-            'Version',  '4.0-dev', ...
+            'Version',  '4.0', ...
             'Release',  '', ...
-            'Date',     '11-Aug-2021' );
+            'Date',     '18-Oct-2021' );
 if nargout > 0
     if nargin > 0
         rv = v;