Release 3.0

CHANGES.md

@@ -2,8 +2,11 @@ Change history for MP-Opt-Model
 ===============================
 
 
-since last release
-------------------
+Version 3.0 - *Oct 8, 2020*
+---------------------------
+
+#### 10/8/20
+  - Release 3.0.
 
 #### 9/23/20
   - Move `have_feature()` to [MP-Test][8] and respective feature detection
@@ -83,7 +86,7 @@ since last release
 
 
 Version 2.1 - *Aug 25, 2020*
----------------------------
+----------------------------
 
 #### 8/25/20
   - Release 2.1.

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 2.1, use:
+appropriate. For version 3.0, use:
 
-  R. D. Zimmerman. MP-Opt-Model User's Manual, Version 2.1. 2020.
-  [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-2.1.pdf
-  doi: 10.5281/zenodo.4001106
+  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
 
 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

@@ -48,20 +48,20 @@ of MATLAB or Octave, including setting up your MATLAB path.
     [MIPS][6]) The result should resemble the following:
 ```
   >> test_mp_opt_model
-  t_nested_struct_copy....ok
   t_have_fcn..............ok
+  t_nested_struct_copy....ok
   t_nleqs_master..........ok (30 of 150 skipped)
-  t_qps_master............ok (100 of 396 skipped)
+  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 170 skipped)
-  t_om_solve_qps..........ok (79 of 319 skipped)
-  t_om_solve_miqps........ok (12 of 72 skipped)
+  t_om_solve_nleqs........ok (36 of 194 skipped)
+  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 (2713 passed, 325 skipped of 3038)
-  Elapsed time 3.37 seconds.
+  All tests successful (3032 passed, 329 skipped of 3361)
+  Elapsed time 3.11 seconds.
 ```
 
 Sample Usage
@@ -199,11 +199,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 2.1, use:
+For version 3.0, use:
 
->   R. D. Zimmerman. *MP-Opt-Model User's Manual, Version 2.1*. 2020.
-    [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-2.1.pdf  
-    doi: [10.5281/zenodo.4001106](https://doi.org/10.5281/zenodo.4001106)
+>   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)
 
 For a version non-specific citation, use the following citation and DOI,
 with *\<YEAR\>* replaced by the year of the most recent release:

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

@@ -0,0 +1,61 @@
+What's New in MP-Opt-Model 3.0
+------------------------------
+
+#### Released October 8, 2020
+
+Below is a summary of the changes since version 2.1 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 [OSQP][3] solver for LP and QP problems (https://osqp.org).
+  - Support for modifying parameters of an existing MP-Opt-Model object.
+  - Support for extracting specific named/indexed variables, costs, constraint
+    values and shadow prices, etc. from a solved  MP-Opt-Model object.
+  - Results of the `solve()` method saved to the `soln` field of the
+    MP-Opt-Model object.
+  - Allow `v0`, `vl`, and `vu` inputs to `opt_model/add_var()` method, and
+    `l` and `u` inputs to `opt_model/add_lin_constraint()` to be scalars
+    that get expanded automatically to the appropriate vector dimension.
+  - New functions:
+    - `opt_model/set_params()` method modifies parameters for a given named
+      set of existing variables, costs, or constraints of an MP-Opt-Model
+      object.
+    - `opt_model/get_soln()` method extracts solved results for a given
+      named set of variables, constraints or costs.
+    - `opt_model/parse_soln()` method returns a complete set of solution
+      vector and shadow price values for a solved model.
+    - `opt_model/eval_lin_constraint()` method computes the constraint values
+      for the full set or an individual named subset of linear constraints.
+    - `qps_osqp()` provides standardized interface for using [OSQP][3] to
+      solve LP/QP problems
+    - `osqp_options()` initializes options for [OSQP][3] solver
+    - `osqpver()` returns/displays version information for [OSQP][3]
+    - ... plus 29 individual feature detection functions for
+      `have_feature()`, see Table A-7 in the [MP-Opt-Model User's Manual][2]
+      for details.
+
+#### Bugs Fixed:
+  - Starting point supplied to `solve()` via `opt.x0` is no longer ignored
+    for nonlinear equations.
+  - Calling `params_var()` method with empty `idx` no longer results in
+    fatal error.
+  - For `opt_model`, incorrect evaluation of constant term has been fixed for
+    vector valued quadratic costs with constant term supplied as a vector.
+
+#### Other Changes
+  - Simplified logic to determine whether a quadratic cost for an
+    MP-Opt-Model object is vector vs. scalar valued. If the quadratic
+    coefficient is supplied as a matrix, the cost is scalar varied,
+    otherwise it is vector valued.
+  - Deprecated `have_fcn()` and make it a simple wrapper around the new
+    modular and extensible `have_feature()`, which has now been moved to
+    [MP-Test][4] (https://github.com/MATPOWER/mptest).
+
+
+[1]: ../../CHANGES.md
+[2]: ../MP-Opt-Model-manual.pdf
+[3]: https://osqp.org
+[4]: https://github.com/MATPOWER/mptest

docs/src/MP-Opt-Model-manual/MIPS-manual.aux

@@ -65,21 +65,21 @@
 \newlabel{tab:mips_input}{{3\unhbox \voidb@x \hbox {-}1}{11}{Input Arguments for \code {mips}\tnote {\dag }\relax }{table.caption.4}{}}
 \@writefile{lot}{\contentsline {table}{\numberline {3\unhbox \voidb@x \hbox {-}2}{\ignorespaces Output Arguments for {\relsize  {-0.5}{\tt  {{mips}}}}\relax }}{12}{table.caption.6}\protected@file@percent }
 \newlabel{tab:mips_output}{{3\unhbox \voidb@x \hbox {-}2}{12}{Output Arguments for \code {mips}\relax }{table.caption.6}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {3.1}Example 1}{12}{subsection.3.1}\protected@file@percent }
-\newlabel{sec:ex1}{{3.1}{12}{Example 1}{subsection.3.1}{}}
-\@writefile{lot}{\contentsline {table}{\numberline {3\unhbox \voidb@x \hbox {-}3}{\ignorespaces Options for {\relsize  {-0.5}{\tt  {{mips}}}}\TPToverlap {\textsuperscript  {\dag  }}\relax }}{13}{table.caption.8}\protected@file@percent }
-\newlabel{tab:mips_options}{{3\unhbox \voidb@x \hbox {-}3}{13}{Options for \code {mips}\tnote {\dag }\relax }{table.caption.8}{}}
+\@writefile{lot}{\contentsline {table}{\numberline {3\unhbox \voidb@x \hbox {-}3}{\ignorespaces Options for {\relsize  {-0.5}{\tt  {{mips}}}}\relax }}{13}{table.caption.8}\protected@file@percent }
+\newlabel{tab:mips_options}{{3\unhbox \voidb@x \hbox {-}3}{13}{Options for \code {mips}\relax }{table.caption.8}{}}
 \@writefile{brf}{\backcite{wang2007a}{{13}{3\unhbox \voidb@x \hbox {-}3}{table.caption.8}}}
 \@writefile{brf}{\backcite{wang2007a}{{13}{3\unhbox \voidb@x \hbox {-}3}{table.caption.8}}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {3.2}Example 2}{14}{subsection.3.2}\protected@file@percent }
-\newlabel{sec:ex2}{{3.2}{14}{Example 2}{subsection.3.2}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.1}Example 1}{14}{subsection.3.1}\protected@file@percent }
+\newlabel{sec:ex1}{{3.1}{14}{Example 1}{subsection.3.1}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.2}Example 2}{15}{subsection.3.2}\protected@file@percent }
+\newlabel{sec:ex2}{{3.2}{15}{Example 2}{subsection.3.2}{}}
 \citation{wang2007a,wang2007}
-\@writefile{toc}{\contentsline {subsection}{\numberline {3.3}Primal-Dual Interior Point Algorithm}{16}{subsection.3.3}\protected@file@percent }
-\@writefile{brf}{\backcite{wang2007a, wang2007}{{16}{3.3}{subsection.3.3}}}
-\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.3.1}Notation}{16}{subsubsection.3.3.1}\protected@file@percent }
-\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.3.2}Problem Formulation and Lagrangian}{17}{subsubsection.3.3.2}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.3}Primal-Dual Interior Point Algorithm}{17}{subsection.3.3}\protected@file@percent }
+\@writefile{brf}{\backcite{wang2007a, wang2007}{{17}{3.3}{subsection.3.3}}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.3.1}Notation}{17}{subsubsection.3.3.1}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.3.2}Problem Formulation and Lagrangian}{18}{subsubsection.3.3.2}\protected@file@percent }
 \newlabel{eq:L}{{3.23}{18}{Problem Formulation and Lagrangian}{equation.3.23}{}}
-\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.3.3}First Order Optimality Conditions}{18}{subsubsection.3.3.3}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.3.3}First Order Optimality Conditions}{19}{subsubsection.3.3.3}\protected@file@percent }
 \@writefile{toc}{\contentsline {subsubsection}{\numberline {3.3.4}Newton Step}{19}{subsubsection.3.3.4}\protected@file@percent }
 \newlabel{eq:newton_step}{{3.34}{19}{Newton Step}{equation.3.34}{}}
 \newlabel{eq:2nd_row}{{3.35}{19}{Newton Step}{equation.3.35}{}}
@@ -94,36 +94,47 @@
 \newlabel{sec:mplinsolve}{{4.1}{22}{Linear System Solver - {\tt mplinsolve}}{subsection.4.1}{}}
 \@writefile{toc}{\contentsline {subsection}{\numberline {4.2}Quadratic Programming Solver - {\tt  qps\_mips}}{22}{subsection.4.2}\protected@file@percent }
 \newlabel{sec:qps_mips}{{4.2}{22}{Quadratic Programming Solver - {\tt qps\_mips}}{subsection.4.2}{}}
-\@writefile{toc}{\contentsline {section}{Appendix \numberline {A}{MIPS}{} Files and Functions}{24}{Appendix.1.A}\protected@file@percent }
-\newlabel{app:functions}{{A}{24}{\mips {} Files and Functions}{Appendix.1.A}{}}
-\@writefile{lot}{\contentsline {table}{\numberline {A\unhbox \voidb@x \hbox {-}1}{\ignorespaces {MIPS}{} Files and Functions\relax }}{24}{table.caption.10}\protected@file@percent }
-\newlabel{tab:files}{{A\unhbox \voidb@x \hbox {-}1}{24}{\mips {} Files and Functions\relax }{table.caption.10}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {4.3}Private Feature Detection Functions}{23}{subsection.4.3}\protected@file@percent }
+\newlabel{sec:featuredetection}{{4.3}{23}{Private Feature Detection Functions}{subsection.4.3}{}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {4.3.1}\tt  have\_feature\_lu\_vec}{23}{subsubsection.4.3.1}\protected@file@percent }
+\newlabel{sec:have_feature_lu_vec}{{4.3.1}{23}{\tt have\_feature\_lu\_vec}{subsubsection.4.3.1}{}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {4.3.2}\tt  have\_feature\_pardiso\_legacy}{23}{subsubsection.4.3.2}\protected@file@percent }
+\newlabel{sec:have_feature_pardiso_legacy}{{4.3.2}{23}{\tt have\_feature\_pardiso\_legacy}{subsubsection.4.3.2}{}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {4.3.3}\tt  have\_feature\_pardiso\_object}{23}{subsubsection.4.3.3}\protected@file@percent }
+\newlabel{sec:have_feature_pardiso_object}{{4.3.3}{23}{\tt have\_feature\_pardiso\_object}{subsubsection.4.3.3}{}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {4.3.4}\tt  have\_feature\_pardiso}{24}{subsubsection.4.3.4}\protected@file@percent }
+\newlabel{sec:have_feature_pardiso}{{4.3.4}{24}{\tt have\_feature\_pardiso}{subsubsection.4.3.4}{}}
+\@writefile{toc}{\contentsline {section}{\numberline {5}Acknowledgments}{25}{section.5}\protected@file@percent }
+\@writefile{toc}{\contentsline {section}{Appendix \numberline {A}{MIPS}{} Files and Functions}{26}{Appendix.1.A}\protected@file@percent }
+\newlabel{app:functions}{{A}{26}{\mips {} Files and Functions}{Appendix.1.A}{}}
+\@writefile{lot}{\contentsline {table}{\numberline {A\unhbox \voidb@x \hbox {-}1}{\ignorespaces {MIPS}{} Files and Functions\relax }}{26}{table.caption.10}\protected@file@percent }
+\newlabel{tab:files}{{A\unhbox \voidb@x \hbox {-}1}{26}{\mips {} Files and Functions\relax }{table.caption.10}{}}
 \citation{pardiso,pardiso2}
-\@writefile{toc}{\contentsline {section}{Appendix \numberline {B}{PARDISO}{} -- Parallel Sparse Direct and Multi-Recursive Iterative Linear Solvers}{25}{Appendix.1.B}\protected@file@percent }
-\newlabel{app:pardiso}{{B}{25}{\pardiso {} -- Parallel Sparse Direct and Multi-Recursive Iterative Linear Solvers}{Appendix.1.B}{}}
-\@writefile{brf}{\backcite{pardiso, pardiso2}{{25}{B}{Appendix.1.B}}}
-\@writefile{toc}{\contentsline {section}{Appendix \numberline {C}Release History}{26}{Appendix.1.C}\protected@file@percent }
-\newlabel{app:release_history}{{C}{26}{Release History}{Appendix.1.C}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.1}Version 1.0 -- released Feb 7, 2011}{26}{subsection.1.C.1}\protected@file@percent }
-\newlabel{app:v10}{{C.1}{26}{Version 1.0 -- released Feb 7, 2011}{subsection.1.C.1}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.2}Version 1.0.1 -- released Apr 30, 2012}{26}{subsection.1.C.2}\protected@file@percent }
-\newlabel{app:v101}{{C.2}{26}{Version 1.0.1 -- released Apr 30, 2012}{subsection.1.C.2}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.3}Version 1.0.2 -- released Nov 5, 2013}{26}{subsection.1.C.3}\protected@file@percent }
-\newlabel{app:v102}{{C.3}{26}{Version 1.0.2 -- released Nov 5, 2013}{subsection.1.C.3}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.4}Version 1.1 -- released Dec 17, 2014}{27}{subsection.1.C.4}\protected@file@percent }
-\newlabel{app:v11}{{C.4}{27}{Version 1.1 -- released Dec 17, 2014}{subsection.1.C.4}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.5}Version 1.2 -- released Mar 20, 2015}{27}{subsection.1.C.5}\protected@file@percent }
-\newlabel{app:v12}{{C.5}{27}{Version 1.2 -- released Mar 20, 2015}{subsection.1.C.5}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.6}Version 1.2.1 -- released Jun 1, 2016}{28}{subsection.1.C.6}\protected@file@percent }
-\newlabel{app:v121}{{C.6}{28}{Version 1.2.1 -- released Jun 1, 2016}{subsection.1.C.6}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.7}Version 1.2.2 -- released Dec 16, 2016}{28}{subsection.1.C.7}\protected@file@percent }
-\newlabel{app:v122}{{C.7}{28}{Version 1.2.2 -- released Dec 16, 2016}{subsection.1.C.7}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.8}Version 1.3 -- released Oct 30, 2018}{29}{subsection.1.C.8}\protected@file@percent }
-\newlabel{app:v13}{{C.8}{29}{Version 1.3 -- released Oct 30, 2018}{subsection.1.C.8}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.9}Version 1.3.1 -- released Jun 20, 2019}{30}{subsection.1.C.9}\protected@file@percent }
-\newlabel{app:v131}{{C.9}{30}{Version 1.3.1 -- released Jun 20, 2019}{subsection.1.C.9}{}}
-\@writefile{toc}{\contentsline {subsection}{\numberline {C.10}Version 1.3.2? -- released ??? ??, 202?}{30}{subsection.1.C.10}\protected@file@percent }
-\newlabel{app:v132}{{C.10}{30}{Version 1.3.2? -- released ??? ??, 202?}{subsection.1.C.10}{}}
+\@writefile{toc}{\contentsline {section}{Appendix \numberline {B}{PARDISO}{} -- Parallel Sparse Direct and Multi-Recursive Iterative Linear Solvers}{27}{Appendix.1.B}\protected@file@percent }
+\newlabel{app:pardiso}{{B}{27}{\pardiso {} -- Parallel Sparse Direct and Multi-Recursive Iterative Linear Solvers}{Appendix.1.B}{}}
+\@writefile{brf}{\backcite{pardiso, pardiso2}{{27}{B}{Appendix.1.B}}}
+\@writefile{toc}{\contentsline {section}{Appendix \numberline {C}Release History}{28}{Appendix.1.C}\protected@file@percent }
+\newlabel{app:release_history}{{C}{28}{Release History}{Appendix.1.C}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.1}Version 1.0 -- released Feb 7, 2011}{28}{subsection.1.C.1}\protected@file@percent }
+\newlabel{app:v10}{{C.1}{28}{Version 1.0 -- released Feb 7, 2011}{subsection.1.C.1}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.2}Version 1.0.1 -- released Apr 30, 2012}{28}{subsection.1.C.2}\protected@file@percent }
+\newlabel{app:v101}{{C.2}{28}{Version 1.0.1 -- released Apr 30, 2012}{subsection.1.C.2}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.3}Version 1.0.2 -- released Nov 5, 2013}{28}{subsection.1.C.3}\protected@file@percent }
+\newlabel{app:v102}{{C.3}{28}{Version 1.0.2 -- released Nov 5, 2013}{subsection.1.C.3}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.4}Version 1.1 -- released Dec 17, 2014}{29}{subsection.1.C.4}\protected@file@percent }
+\newlabel{app:v11}{{C.4}{29}{Version 1.1 -- released Dec 17, 2014}{subsection.1.C.4}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.5}Version 1.2 -- released Mar 20, 2015}{29}{subsection.1.C.5}\protected@file@percent }
+\newlabel{app:v12}{{C.5}{29}{Version 1.2 -- released Mar 20, 2015}{subsection.1.C.5}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.6}Version 1.2.1 -- released Jun 1, 2016}{30}{subsection.1.C.6}\protected@file@percent }
+\newlabel{app:v121}{{C.6}{30}{Version 1.2.1 -- released Jun 1, 2016}{subsection.1.C.6}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.7}Version 1.2.2 -- released Dec 16, 2016}{30}{subsection.1.C.7}\protected@file@percent }
+\newlabel{app:v122}{{C.7}{30}{Version 1.2.2 -- released Dec 16, 2016}{subsection.1.C.7}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.8}Version 1.3 -- released Oct 30, 2018}{31}{subsection.1.C.8}\protected@file@percent }
+\newlabel{app:v13}{{C.8}{31}{Version 1.3 -- released Oct 30, 2018}{subsection.1.C.8}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.9}Version 1.3.1 -- released Jun 20, 2019}{32}{subsection.1.C.9}\protected@file@percent }
+\newlabel{app:v131}{{C.9}{32}{Version 1.3.1 -- released Jun 20, 2019}{subsection.1.C.9}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.10}Version 1.4 -- released Oct 8, 2020}{32}{subsection.1.C.10}\protected@file@percent }
+\newlabel{app:v14}{{C.10}{32}{Version 1.4 -- released Oct 8, 2020}{subsection.1.C.10}{}}
 \bibcite{tspopf}{1}
 \bibcite{wang2007a}{2}
 \bibcite{wang2007}{3}
@@ -134,5 +145,5 @@
 \bibcite{bsd}{8}
 \bibcite{gpl}{9}
 \bibcite{pardiso}{10}
-\@writefile{toc}{\contentsline {section}{References}{31}{section*.29}\protected@file@percent }
+\@writefile{toc}{\contentsline {section}{References}{34}{section*.30}\protected@file@percent }
 \bibcite{pardiso2}{11}