Release 4.2

CHANGES.md

@@ -2,8 +2,11 @@ Change history for MP-Opt-Model
 ===============================
 
 
-Since version 4.1
------------------
+ Version 4.2 - *May 10, 2024*
+----------------------------
+
+#### 5/10/24
+  - Release 4.2.
 
 #### 4/23/24
   - Fix bug in test `t_opt_model()` for MATLAB R2011b and earlier.
@@ -20,6 +23,9 @@ Since version 4.1
     `opt_model.set_params()`.
   - Add caching of aggregate output parameters in `opt_model.params_var()`.
 
+#### 3/26/24
+  - Add Sphinx-based [Reference documentation][13].
+
 #### 3/21/24
   - Add to the `parse_soln()` method of `opt_model` an optional `stash`
     input argument that, if present and true, causes the parsed solution
@@ -34,7 +40,7 @@ Since version 4.1
     been renamed to architecture-specific names along with an `ipopt.m`
     wrapper function to call the appropriate one.
     *Thanks to Carlos Murillo-Sánchez.*  
-    _**Note:** While MATPOWER no longer requires this, my recommendation
+    _**Note:** While MP-Opt-Model no longer requires this, my recommendation
      is still to simply rename the MEX file to `ipopt.<mexext>`, with the
      appropriate architecture-specific extension, and delete the
      unnecessary `ipopt.m` entirely._
@@ -503,3 +509,4 @@ Version 0.7.0 - *Jun 20, 2019*
 [10]: https://savannah.gnu.org/bugs/?52614
 [11]: https://github.com/MATPOWER/most
 [12]: https://github.com/ebertolazzi/mexIPOPT
+[13]: https://matpower.org/doc/mpom/

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 4.1, use:
+appropriate. For version 4.2, use:
 
-  R. D. Zimmerman. MP-Opt-Model User's Manual, Version 4.1. 2022.
-  [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-4.1.pdf
-  doi: 10.5281/zenodo.7434250
+  R. D. Zimmerman. MP-Opt-Model User's Manual, Version 4.2. 2024.
+  [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-4.2.pdf
+  doi: 10.5281/zenodo.11177079
 
 For a version non-specific citation, use the following citation and DOI,
 with *\<YEAR\>* replaced by the year of the most recent release:

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2004-2022, Power Systems Engineering Research Center (PSERC)
+Copyright (c) 2004-2024, Power Systems Engineering Research Center (PSERC)
 and individual contributors (see AUTHORS file for details).
 All rights reserved.
 

README.md

@@ -54,17 +54,17 @@ of MATLAB or Octave, including setting up your MATLAB/Octave path.
   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_miqps_master..........ok (78 of 318 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_nleqs........ok (36 of 195 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_qps..........ok (81 of 388 skipped)
+  t_om_solve_miqps........ok (20 of 131 skipped)
   t_om_solve_nlps.........ok
-  All tests successful (3430 passed, 329 skipped of 3759)
-  Elapsed time 4.22 seconds.
+  All tests successful (3461 passed, 345 skipped of 3806)
+  Elapsed time 2.28 seconds.
 ```
 
 Sample Usage
@@ -202,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 4.1, use:
+For version 4.2, use:
 
->   R. D. Zimmerman. *MP-Opt-Model User's Manual, Version 4.1*. 2022.
-    [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-4.1.pdf  
-    doi: [10.5281/zenodo.7434250](https://doi.org/10.5281/zenodo.7434250)
+>   R. D. Zimmerman. *MP-Opt-Model User's Manual, Version 4.2*. 2024.
+    [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-4.2.pdf  
+    doi: [10.5281/zenodo.11177079](https://doi.org/10.5281/zenodo.11177079)
 
 For a version non-specific citation, use the following citation and DOI,
 with *\<YEAR\>* replaced by the year of the most recent release:

docs/other/MP-Opt-Model-Release-Checklist.md

@@ -37,7 +37,7 @@ Pre-release
   - Make updates for current version specific citations:
     - version number (3 places)
     - year
-    - latest version DOI, current is: 10.5281/zenodo.7434250
+    - latest version DOI, current is: 10.5281/zenodo.11177079
       - (update here each time)
     ... in the following places ...
     - CITATION file
@@ -51,27 +51,27 @@ Pre-release
         - MATPOWER User's Manual
 - Copy latest `MIPS-manual.aux` to `docs/src/MP-Opt-Model-manual` for
   `\externaldocument`
-- Create `MP-Opt-Model-manual.pdf` from `MP-Opt-Model-manual.tex`
-  - move to `docs`
-  - make copy named `MP-Opt-Model-manual-x.x.pdf`
-    - copy to `docs` directory of `matpower.org-static` git repo
-      - update `MP-Opt-Model-manual.pdf` symlink on `https://matpower.org/docs/` to point
-        to new `MP-Opt-Model-manual-x.x.pdf` (replaces existing current version)
-        - `cd dev/projects/matpower.org-static/docs`
-        - `rm MP-Opt-Model-manual.pdf`
-        - `ln -s ./MP-Opt-Model-manual-x.x.pdf MP-Opt-Model-manual.pdf`
-      - commit & push, then pull to matpower.org
-    - upload `MP-Opt-Model-manual-x.x.pdf` to Zenodo and finish entry for "New Version"
-      - update:
-        - Publication date
-        - Version
-        - Identifiers:
-          - version number in "identical to"
-  - add link on `https://matpower.org/doc/manuals/` page
+- Create `MP-Opt-Model-manual.pdf` from `MP-Opt-Model-manual.tex` and move
+  to `docs`.
 - Add release notice with date and version in `CHANGES.md`.
 - Commit all changes to `prep-for-release`.
 - Push `prep-for-release` to GitHub.
 - Make sure CI checks are ok.
+- Make copy of `docs/MP-Opt-Model-manual.pdf` named `MP-Opt-Model-manual-x.x.pdf`
+  - copy to `docs` directory of `matpower.org-static` git repo
+    - update `MP-Opt-Model-manual.pdf` symlink on `https://matpower.org/docs/` to point
+      to new `MP-Opt-Model-manual-x.x.pdf` (replaces existing current version)
+      - `cd dev/projects/matpower.org-static/docs`
+      - `rm MP-Opt-Model-manual.pdf`
+      - `ln -s ./MP-Opt-Model-manual-x.x.pdf MP-Opt-Model-manual.pdf`
+    - commit & push, then pull to matpower.org
+  - upload `MP-Opt-Model-manual-x.x.pdf` to Zenodo and finish entry for "New Version"
+    - update:
+      - Publication date
+      - Version
+      - Identifiers:
+        - version number in "identical to"
+- Add link on `https://matpower.org/doc/manuals/` page
 
 
 Release

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

@@ -0,0 +1,78 @@
+What's New in MP-Opt-Model 4.2
+------------------------------
+
+#### Released May 10, 2024
+
+Below is a summary of the changes since version 4.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:
+  - Option for `opt_model.add_lin_constraint()` to provide/store the
+    transpose of the _A_ matrix instead of the original. This can
+    potentially save significant memory for sparse matrices with many
+    more columns than rows. E.g. storage constraints in [MOST][3]
+    for 8760 hour planning horizon.
+  - Add support to `nlps_master()` for calling `nlps_<my_solver>()` by
+    setting `opt.alg` to `'<MY_SOLVER>'` to allow for handling custom
+    NLP solvers.
+  - Add support to `miqps_master()` for calling `miqps_<my_solver>()`
+    by setting `opt.alg` to `'<MY_SOLVER>'` to allow for handling custom
+    MILP/MIQP solvers.
+  - Add to the `parse_soln()` method of `opt_model` an optional `stash`
+    input argument that, if present and true, causes the parsed
+    solution to be stored back in the object, as the `solve()` method
+    was already doing when `opt.parse_soln` is true.
+  - New Sphinx-based [Reference documentation][4].
+  - New functions:
+    - `convert_lin_constraint()` converts linear constraints from a
+      single set of doubly-bounded inequality constraints to separate
+      sets of equality and upper-bounded inequality constraints.
+    - `convert_lin_constraint_multipliers()` converts multipliers on
+      linear constraints from separate sets for equality and
+      upper-bounded inequality constraints to those for doubly-bounded
+      inequality constraints.
+  - New `opt_model` methods:
+      - `is_solved()` indicates whether the model has been solved.
+      - `has_parsed_soln()` indicates whether a parsed solution is
+        available in the model.
+      - `display_soln()` display the results of a solved model,
+        including values, bounds and shadow prices for variables and
+        linear constraints, values and shadow prices for nonlinear
+        constraints, and individual cost components.
+
+#### Bugs Fixed:
+  - Clear cached parameters after updating linear constraints or
+    quadratic costs via `opt_model.set_params()`.
+  - In `miqps_mosek()` the lower and upper bounds of binary variables
+    got overwritten with 0 and 1, respectively, effectively relaxing
+    any potentially tighter bounds provided as input.
+  - Fix false positive in `have_feature_fsolve` in case where the file
+    is present, but without a valid license.
+
+#### Other Changes:
+  - Update for compatibility with MATLAB R2023a (Optimization Toolbox
+    9.5) and later, which removed `x0` as a valid input to `linprog`.
+  - Update `have_feature_ipopt()` to recognize IPOPT MEX installations
+    from Enrico Bertolazzi's [mexIPOPT][5], which include MEX files
+    that have been renamed to architecture-specific names along with an
+    `ipopt.m` wrapper function to call the appropriate one.
+    *Thanks to Carlos Murillo-Sánchez.*
+
+    _**Note:** While MP-Opt-Model no longer requires this, my
+    recommendation is still to simply rename the MEX file to
+    `ipopt.<mexext>`, with the appropriate architecture-specific
+    extension, and delete the unnecessary `ipopt.m` entirely._
+  - Always skip price computation stage in `miqps_<solver>()` functions
+    for pure (as opposed to mixed) integer problems.
+  - Add caching of aggregate output parameters in
+    `opt_model.params_var()`.
+
+
+[1]: ../../CHANGES.md
+[2]: ../MP-Opt-Model-manual.pdf
+[3]: https://github.com/MATPOWER/most
+[4]: https://matpower.org/doc/mpom/
+[5]: https://github.com/ebertolazzi/mexIPOPT

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

@@ -1,16 +1,5 @@
 \relax 
 \providecommand\hyper@newdestlabel[2]{}
-\providecommand\HyperFirstAtBeginDocument{\AtBeginDocument}
-\HyperFirstAtBeginDocument{\ifx\hyper@anchor\@undefined
-\global\let\oldnewlabel\newlabel
-\gdef\newlabel#1#2{\newlabelxx{#1}#2}
-\gdef\newlabelxx#1#2#3#4#5#6{\oldnewlabel{#1}{{#2}{#3}}}
-\AtEndDocument{\ifx\hyper@anchor\@undefined
-\let\newlabel\oldnewlabel
-\fi}
-\fi}
-\global\let\hyper@last\relax 
-\gdef\HyperFirstAtBeginDocument#1{#1}
 \providecommand\HyField@AuxAddToFields[1]{}
 \providecommand\HyField@AuxAddToCoFields[2]{}
 \citation{octave}
@@ -57,13 +46,13 @@
 \newlabel{eq:mips_h}{{3.3}{10}{\mips {} -- \mipsname {}}{equation.3.2}{}}
 \newlabel{eq:mips_linear_constraints}{{3.4}{10}{\mips {} -- \mipsname {}}{equation.3.2}{}}
 \newlabel{eq:mips_var_bounds}{{3.5}{10}{\mips {} -- \mipsname {}}{equation.3.2}{}}
-\@writefile{lot}{\contentsline {table}{\numberline {3\mbox  {-}1}{\ignorespaces Input Arguments for {\relsize  {-0.5}{\tt  {{mips}}}}\TPToverlap {\textsuperscript  {\dag  }}\relax }}{11}{table.caption.4}\protected@file@percent }
+\@writefile{lot}{\contentsline {table}{\numberline {3\mbox  {-}1}{\ignorespaces Input Arguments for {\relsize  {-0.5}{\tt  {{mips}}}}\TPToverlap {\textsuperscript  {\dag  }}}}{11}{table.caption.4}\protected@file@percent }
 \providecommand*\caption@xref[2]{\@setref\relax\@undefined{#1}}
-\newlabel{tab:mips_input}{{3\mbox  {-}1}{11}{Input Arguments for \code {mips}\tnote {\dag }\relax }{table.caption.4}{}}
-\@writefile{lot}{\contentsline {table}{\numberline {3\mbox  {-}2}{\ignorespaces Output Arguments for {\relsize  {-0.5}{\tt  {{mips}}}}\relax }}{12}{table.caption.6}\protected@file@percent }
-\newlabel{tab:mips_output}{{3\mbox  {-}2}{12}{Output Arguments for \code {mips}\relax }{table.caption.6}{}}
-\@writefile{lot}{\contentsline {table}{\numberline {3\mbox  {-}3}{\ignorespaces Options for {\relsize  {-0.5}{\tt  {{mips}}}}\relax }}{13}{table.caption.8}\protected@file@percent }
-\newlabel{tab:mips_options}{{3\mbox  {-}3}{13}{Options for \code {mips}\relax }{table.caption.8}{}}
+\newlabel{tab:mips_input}{{3\mbox  {-}1}{11}{Input Arguments for \code {mips}\tnote {\dag }}{table.caption.4}{}}
+\@writefile{lot}{\contentsline {table}{\numberline {3\mbox  {-}2}{\ignorespaces Output Arguments for {\relsize  {-0.5}{\tt  {{mips}}}}}}{12}{table.caption.6}\protected@file@percent }
+\newlabel{tab:mips_output}{{3\mbox  {-}2}{12}{Output Arguments for \code {mips}}{table.caption.6}{}}
+\@writefile{lot}{\contentsline {table}{\numberline {3\mbox  {-}3}{\ignorespaces Options for {\relsize  {-0.5}{\tt  {{mips}}}}}}{13}{table.caption.8}\protected@file@percent }
+\newlabel{tab:mips_options}{{3\mbox  {-}3}{13}{Options for \code {mips}}{table.caption.8}{}}
 \@writefile{brf}{\backcite{wang2007a}{{13}{3\mbox  {-}3}{table.caption.8}}}
 \@writefile{brf}{\backcite{wang2007a}{{13}{3\mbox  {-}3}{table.caption.8}}}
 \@writefile{toc}{\contentsline {subsection}{\numberline {3.1}Example 1}{14}{subsection.3.1}\protected@file@percent }
@@ -104,8 +93,8 @@
 \@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\mbox  {-}1}{\ignorespaces {MIPS}{} Files and Functions\relax }}{26}{table.caption.10}\protected@file@percent }
-\newlabel{tab:files}{{A\mbox  {-}1}{26}{\mips {} Files and Functions\relax }{table.caption.10}{}}
+\@writefile{lot}{\contentsline {table}{\numberline {A\mbox  {-}1}{\ignorespaces {MIPS}{} Files and Functions}}{26}{table.caption.10}\protected@file@percent }
+\newlabel{tab:files}{{A\mbox  {-}1}{26}{\mips {} Files and Functions}{table.caption.10}{}}
 \citation{pardiso,pardiso2}
 \@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}{}}
@@ -134,6 +123,8 @@
 \newlabel{app:v14}{{C.10}{32}{Version 1.4 -- released Oct 8, 2020}{subsection.1.C.10}{}}
 \@writefile{toc}{\contentsline {subsection}{\numberline {C.11}Version 1.5 -- released Dec 12, 2022}{33}{subsection.1.C.11}\protected@file@percent }
 \newlabel{app:v15}{{C.11}{33}{Version 1.5 -- released Dec 12, 2022}{subsection.1.C.11}{}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.12}Version 1.5.1 -- released May 10, 2024}{33}{subsection.1.C.12}\protected@file@percent }
+\newlabel{app:v151}{{C.12}{33}{Version 1.5.1 -- released May 10, 2024}{subsection.1.C.12}{}}
 \bibcite{tspopf}{1}
 \bibcite{wang2007a}{2}
 \bibcite{wang2007}{3}
@@ -144,6 +135,6 @@
 \bibcite{bsd}{8}
 \bibcite{gpl}{9}
 \bibcite{pardiso}{10}
-\@writefile{toc}{\contentsline {section}{References}{34}{section*.31}\protected@file@percent }
+\@writefile{toc}{\contentsline {section}{References}{35}{section*.32}\protected@file@percent }
 \bibcite{pardiso2}{11}
-\gdef \@abspage@last{35}
+\gdef \@abspage@last{36}