Move examples from lib/t to their own examples directory.

Author: rdzman

.github/workflows/continuous-integration.yml

@@ -50,7 +50,7 @@ jobs:
         echo "MPTEST_PATH=$HOME/mptest/lib:$HOME/mptest/lib/t" >> $GITHUB_ENV
 
     - name: Set MIPS_PATH
-      run: echo "MIPS_PATH=${GITHUB_WORKSPACE}/lib:${GITHUB_WORKSPACE}/lib/t:${MPTEST_PATH}" >> $GITHUB_ENV
+      run: echo "MIPS_PATH=${GITHUB_WORKSPACE}/lib:${GITHUB_WORKSPACE}/lib/t:${GITHUB_WORKSPACE}/examples:${MPTEST_PATH}" >> $GITHUB_ENV
 
     - name: Test MP-Test
       run: env $ML_PATHVAR=$MPTEST_PATH $ML_CMD "mptestver; test_mptest(0,1)"

CHANGES.md

@@ -2,11 +2,15 @@ Change history for MIPS
 =======================
 
 
-Version 1.5.2 - *July 5, 2025*
-------------------------------
+Version 1.5.2 - *July 12, 2025*
+-------------------------------
 
-#### 5/10/24
+#### 5/12/24
   - Release 1.5.2.
+  - Move examples `mips_example1.m` and `mips_example2.m` from `lib/t`
+    to their own `examples` directory.
+
+#### 5/10/24
   - Add feature detection function `have_feature_mips()`, providing
     implementation of `'mips'` tag for `have_feature()`.
 

README.md

@@ -36,6 +36,7 @@ of MATLAB or Octave, including setting up your MATLAB/Octave path.
 2.  Add the following directories to your MATLAB or Octave path:
     *   `<MIPS>/lib`
     *   `<MIPS>/lib/t`
+    *   `<MIPS>/examples`
 
 3.  At the MATLAB/Octave prompt, type `test_mips` to run the test suite and
     verify that MIPS is properly installed and functioning. The result

docs/other/MIPS-Release-Checklist.md

@@ -40,7 +40,7 @@ Pre-release
   - Make updates for current version specific citations:
     - version number (3 places)
     - year
-    - latest version DOI, current is: 10.5281/zenodo.11176870
+    - latest version DOI, current is: 10.5281/zenodo.15815754
       - (update here each time)
     ... in the following places ...
     - CITATION file
@@ -53,6 +53,10 @@ Pre-release
       - search citations in all other projects being updated simultaneously
         - MATPOWER-manual.tex
         - MP-Opt-Model-manual.tex
+    - search everywhere for 10.5281/zenodo.3236519 and update year (MATPOWER User's Manual)
+      - User's Manual
+    - search everywhere for 10.5281/zenodo.3236535 and update year (MATPOWER Software)
+      - User's Manual
 - Create `MIPS-manual.pdf` from `MIPS-manual.tex` and move to `docs`.
 - Add release notice with date and version in `CHANGES.md`.
 - Commit all changes to `prep-for-release`.
@@ -78,7 +82,7 @@ Pre-release
 Release
 -------
 - Merge latest `prep-for-release` into `master`.
-- Tag with version number, e.g. `1.5`.
+- Tag with version number, e.g. `1.5.2`.
 - Push `master` to GitHub.
 - Publish new release on GitHub: https://github.com/MATPOWER/mips/releases/new
   - use (possibly shortened) contents of `docs/relnotes/MIPS-Release-Notes-#.#.md`

docs/sphinx/source/functions/mips_example1.rst

@@ -1,6 +1,6 @@
 .. currentmodule:: mips
 
-:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/mips/blob/master/lib/t/mips_example1.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>`
+:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/mips/blob/master/examples/mips_example1.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>`
 
 mips_example1
 -------------

docs/sphinx/source/functions/mips_example2.rst

@@ -1,6 +1,6 @@
 .. currentmodule:: mips
 
-:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/mips/blob/master/lib/t/mips_example2.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>`
+:raw-html:`<div style="float: right"><a href="https://github.com/MATPOWER/mips/blob/master/examples/mips_example2.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>`
 
 mips_example2
 -------------

docs/sphinx/source/matlab-source/mips/mips_example1.m

@@ -1 +1 @@
-../../../../../lib/t/mips_example1.m
+../../../../../examples/mips_example1.m

docs/sphinx/source/matlab-source/mips/mips_example2.m

@@ -1 +1 @@
-../../../../../lib/t/mips_example2.m
+../../../../../examples/mips_example2.m

docs/src/MIPS-manual/MIPS-manual.tex

@@ -392,6 +392,7 @@ \subsection{Installation}
 \begin{itemize}
 \item \mipspath{/lib} -- core \mips{} functions
 \item \mipspath{/lib/t} -- test scripts for \mips{}
+\item \mipspath{/examples} -- \mips{} examples
 \end{itemize}
 \item At the \matlab{}/Octave prompt, type \code{test\_mips} to run the test suite and verify that \mips{} is properly installed and functioning.\footnote{The tests require a functioning installation of \mptestlink{}.} The result should resemble the following:
 %\clearpage
@@ -586,7 +587,7 @@ \section{\mips{} -- \mipsname{}}
 \subsection{Example 1}
 \label{sec:ex1}
 
-The following code, included as \code{mips\_example1.m} in \mipspath{lib/t}, shows a simple example of using \code{mips} to solve a 2-dimensional unconstrained optimization of Rosenbrock's ``banana'' function\footnote{\url{https://en.wikipedia.org/wiki/Rosenbrock_function}}
+The following code, included as \code{mips\_example1.m} in \mipspath{examples}, shows a simple example of using \code{mips} to solve a 2-dimensional unconstrained optimization of Rosenbrock's ``banana'' function\footnote{\url{https://en.wikipedia.org/wiki/Rosenbrock_function}}
 \begin{equation}
 f(x) = 100 (x_2-x_1^2)^2+(1-x_1)^2.
 \end{equation}
@@ -707,7 +708,7 @@ \subsection{Example 2}
    0
    0.707107
 \end{Code}
-This example can be found in \code{mips\_example2.m}. More example problems for \code{mips} can be found in \code{t\_mips.m}, both in \mipspath{lib/t}.
+This example can be found in \code{mips\_example2.m} in \mipspath{examples}. More example problems for \code{mips} can be found in \code{t\_mips.m} in \mipspath{lib/t}.
 
 \subsection{Primal-Dual Interior Point Algorithm}
 
@@ -1093,6 +1094,9 @@ \section{\mips{} Files and Functions}
 \code{~~MIPS-manual.pdf}	& \mipsman{}	\\
 \code{~~src/MIPS-manual/}	&	\\
 \code{~~~~MIPS-manual.tex}	& LaTeX source for \mips{} User's Manual	\\
+\code{examples/}	& 	\\
+\code{~~~~mips\_example1}	& implements example 1 from \mips{} User's Manual	\\
+\code{~~~~mips\_example2}	& implements example 2 from \mips{} User's Manual	\\
 \code{lib/}	& 	\\
 \code{~~have\_feature\_lu\_vec}\tnote{*}	& support for \code{lu(..., \textquotesingle{}vector\textquotesingle{})} syntax	\\
 \code{~~have\_feature\_pardiso\_legacy}\tnote{*}	& \pardiso{} v5, individual MEX files for factor, solve, etc.	\\
@@ -1103,8 +1107,6 @@ \section{\mips{} Files and Functions}
 \code{~~mplinsolve}	& common linear system solver interface, used by \mips{}	\\
 \code{~~qps\_mips}	& common QP/LP solver interface to \mips{}-based solver	\\
 \code{~~t/}	& 	\\
-\code{~~~~mips\_example1}	& implements example 1 from \mips{} User's Manual	\\
-\code{~~~~mips\_example2}	& implements example 2 from \mips{} User's Manual	\\
 \code{~~~~test\_mips}	& runs full \mips{} test suite	\\
 \code{~~~~t\_mips}	& runs tests for \mips{} NLP solver	\\
 \code{~~~~t\_mips\_pardiso}	& runs tests for \mips{} NLP solver, using PARDISO as linear solver\tnote{\dag}	\\
@@ -1413,7 +1415,7 @@ \subsubsection*{New Features}
 \doi{10.1109/TPWRS.2010.2051168}
 
 \bibitem{matpower}
-R.~D. Zimmerman, C.~E. Murillo-S{\'a}nchez (2024). \matpower{}\\~
+R.~D. Zimmerman, C.~E. Murillo-S{\'a}nchez (2025). \matpower{}\\~
 [Software]. Available: \url{https://matpower.org}\\
 \doi{10.5281/zenodo.3236535}