MP-Opt-Model

MP-Opt-Model is a package of MATLAB/Octave M-files for constructing 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 simply by changing an input option.

It is based on code that was originally developed by Ray D. Zimmerman of Cornell University as part of MATPOWER.

System Requirements

• MATLAB version 7.9 (R2009b) or later, or
• GNU Octave version 6.2 or later [^1]
• MP-Test
• MATPOWER Interior Point Solver (MIPS)

[^1]: All functionality except object copy constructors work on GNU Octave 4.4 and later.

Installation

Note to MATPOWER users: MP-Opt-Model and its prerequisites, MIPS and MP-Test, are included when you install MATPOWER. There is generally no need to install MP-Opt-Model separately. You can skip directly to step 3 to verify.

Installation and use of MP-Opt-Model requires familiarity with the basic operation of MATLAB or Octave, including setting up your MATLAB/Octave path.

1. Clone the repository or download and extract the zip file of the MP-Opt-Model distribution from the MP-Opt-Model project page to the location of your choice. The files in the resulting mp-opt-model or mp-opt-modelXXX directory, where XXX depends on the version of MP-Opt-Model, should not need to be modified, so it is recommended that they be kept separate from your own code. We will use <MPOM> to denote the path to this directory.

2. Add the following directories to your MATLAB or Octave path:

   • <MPOM>/lib
   • <MPOM>/lib/t
   • <MPOM>/examples

3. At the MATLAB/Octave prompt, type test_mp_opt_model to run the test suite and verify that MP-Opt-Model is properly installed and functioning. (Note: The tests require functioning installations of both MP-Test and MIPS) The result should resemble the following: ```

   testmpoptmodel thavefcn..............ok tnestedstructcopy....ok tnleqsmaster..........ok (30 of 150 skipped) tpnesmaster...........ok tqpsmaster............ok (144 of 504 skipped) tqcqpsmaster..........ok (94 of 651 skipped) tmiqpsmaster..........ok (128 of 371 skipped) tnlpsmaster...........ok (16 of 540 skipped) tmpoptmodel..........ok tmmsolveleqs.........ok tmmsolvenleqs........ok (36 of 196 skipped) tmmsolvepne..........ok tmmsolveqcqps........ok (6 of 214 skipped) tmmsolveqps..........ok (120 of 449 skipped) tmmsolvemiqps........ok (106 of 261 skipped) tmmsolvenlps.........ok (9 of 506 skipped) toptmodel.............ok tomsolveleqs.........ok tomsolvenleqs........ok (36 of 196 skipped) tomsolvepne..........ok tomsolveqcqps........ok (6 of 214 skipped) tomsolveqps..........ok (120 of 449 skipped) tomsolvemiqps........ok (106 of 261 skipped) tomsolve_nlps.........ok (9 of 506 skipped) All tests successful (6814 passed, 966 skipped of 7780) Elapsed time 18.02 seconds. ```

Sample Usage

Suppose we have the following constrained 4-dimensional quadratic programming (QP) problem with two 2-dimensional variables, y and z, and two constraints, one equality and the other inequality, along with lower bounds on all of the variables.

``` min 1/2 [y; z]' * H * [y; z] y,z

subject to: A1 * [y; z] = b1 A2 * y <= u2 y >= ymin z <= zmax ```

And suppose the data for the problem is provided as follows.

```matlab %% variable initial values y0 = [1; 0]; z0 = [0; 1];

%% variable lower bounds ymin = [0; 0]; zmax = [0; 2];

%% constraint data A1 = [ 6 1 5 -4 ]; b1 = 4; A2 = [ 4 9 ]; u2 = 2;

%% quadratic cost coefficients H = [ 8 1 -3 -4; 1 4 -2 -1; -3 -2 5 4; -4 -1 4 12 ]; ```

Below, we will show two approaches to construct and solve the problem. The first method, based on the the Optimization Model class mp.opt_model, allows you to add variables, constraints and costs to the model individually. Then mp.opt_model automatically assembles and solves the full model automatically.

```matlab %%----- METHOD 1 ----- %% build model mm = mp.opt_model; mm.var.add('y', 2, y0, ymin); mm.var.add('z', 2, z0, [], zmax); mm.lin.add(mm.var, 'lincon1', A1, b1, b1); mm.lin.add(mm.var, 'lincon2', A2, [], u2, {'y'}); mm.qdc.add(mm.var, 'cost', H, []);

%% solve model [x, f, exitflag, output, lambda] = mm.solve(); ```

The second method requires you to construct the parameters for the full problem manually, then call the solver function directly.

```matlab %%----- METHOD 2 ----- %% assemble model parameters manually xmin = [ymin; -Inf(2,1)]; xmax = [ Inf(2,1); zmax]; x0 = [y0; z0]; A = [ A1; A2 0 0]; l = [ b1; -Inf ]; u = [ b1; u2 ];

%% solve model [x, f, exitflag, output, lambda] = qps_master(H, [], A, l, u, xmin, xmax, x0); ```

The above examples are included in <MPOM>/examples/qp_ex1.m along with some commands to print the results, yielding the output below for each approach:

``` f = 1.875 exitflag = 1

         var bound shadow prices
 x     lambda.lower  lambda.upper

0.5000 0.0000 0.0000 0.0000 5.1250 0.0000 -0.0000 0.0000 8.7500 -0.2500 0.0000 0.0000

constraint shadow prices lambda.mul lambda.muu 1.2500 0.0000 0.0000 0.6250 ```

An options struct can be passed to the solve method or the qps_master function to select a specific solver, control the level of progress output, or modify a solver's default parameters.

Both approaches can be applied to each of the types of problems that MP-Opt-Model handles, namely, LP, QP, MILP, MIQP, NLP and nonlinear equations.

There are other examples in <MPOM>/examples, in the test files in <MPOM>/lib/t, as well as in the opf_setup() and opf_execute() functions in MATPOWER.

Documentation

There are two primary sources of documentation for MP-Opt-Model.

The first is the MP-Opt-Model User's Manual. It can be found in your MP-Opt-Model distribution at <MPOM>/docs/MP-Opt-Model-manual.pdf and the latest version is always available at: https://github.com/MATPOWER/mp-opt-model/blob/master/docs/MP-Opt-Model-manual.pdf.

And second is the built-in help command. As with the built-in functions and toolbox routines in MATLAB and Octave, you can type help followed by the name of a command or M-file to get help on that particular function. Many of the M-files in MP-Opt-Model have such documentation and this should be considered the main reference for the calling options for each function, e.g.: qps_master, miqps_master, and nlps_master.

Citing MP-Opt-Model

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 5.0, use:

R. D. Zimmerman. MP-Opt-Model User's Manual, Version 5.0. 2025. [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual-5.0.pdf
doi: 10.5281/zenodo.15871431

For a version non-specific citation, use the following citation and DOI, with <YEAR> replaced by the year of the most recent release:

R. D. Zimmerman. MP-Opt-Model User's Manual. <YEAR>. [Online]. Available: https://matpower.org/docs/MP-Opt-Model-manual.pdf
doi: 10.5281/zenodo.3818002

A list of versions of the User's Manual with release dates and version-specific DOI's can be found via the general DOI at https://doi.org/10.5281/zenodo.3818002.

Contributing

Please see our contributing guidelines for details on how to contribute to the project or report issues.

License

MP-Opt-Model is distributed under the 3-clause BSD license.