# Introduction to the GMP Library

Introduction

With every `MathematicalProgram`

declared as part of your model, the
GMP library allows you to associate

one or more

**G**enerated**M**ath**P**rogram instances (GMPs),

and with each GMP

a conceptual matrix of coefficients that can be manipulated,

a repository of initial, intermediate or final solutions, and

a pool of local or remote solver sessions.

Fig. 2 illustrates the interrelationship between symbolic mathematical programs and the concepts of the GMP library, as well as the main properties that can be associated with each of them.

Generated mathematical program instances

For every `MathematicalProgram`

declaration in your model,
modifications in the index sets and input data referenced in constraints
and variable definitions may give rise to completely different instances
of the coefficient matrix when the mathematical program at hand is being
generated.

An example: indexed instances

An illustrative example of such differing instances occurs when the
constraints and variables of a symbolic mathematical program are indexed
over a subset of some other superset. If you let the subset contain a
single element of the superset, the generated instances will be
completely different for each element of the superset. The effect of
changing the contents of the subset in this manner, would almost compare
to having an indexed `MathematicalProgram`

*declaration* (which AIMMS
does not support). In the worked example of
Indexed Mathematical Program Instances you will see, however, how you can
obtain an indexed collection of generated mathematical program
*instances* using the GMP library.

Need for multiple instances

With the standard `SOLVE`

statement (see The SOLVE Statement) you only
have access to a single generated mathematical program instance for
every symbolic mathematical program, namely the instance associated with
the last call to the `SOLVE`

statement for that particular
mathematical program. This effectively eliminates the capability to
efficiently implement an algorithm which requires the interaction
between two or more generated instances of the same symbolic
mathematical program. For this reason, the GMP library allows you to
maintain and work with a collection of generated mathematical program
instances simultaneously.

Matrix manipulation

The GMP library also allows you to manipulate the rows, columns and
coefficients of the matrix of a mathematical program instance once it
has been generated. If the number of modifications is relatively small,
manipulating the matrix directly will save a considerable amount of time
compared to letting AIMMS completely regenerate the matrix again through
the standard `SOLVE`

statement. You can use matrix manipulation, for
instance

to quickly add columns, and adapt the existing rows of the matrix accordingly, in a column generation scheme, or

to dynamically add cuts to a mixed integer linear program.

Keeping multiple solutions

With the standard `SOLVE`

statement, you only have access to a single
solution of a mathematical program, namely the one stored in the
symbolic variables and constraints that make up the mathematical
program. There are, however, many situations where it would be
convenient to have access to a repository of solutions. A solution
repository can be used, for instance

to store a collection of starting solutions for a NLP or MINLP problem. Solving the problem, in either a serial or parallel manner, with each of these starting solutions may help you find a better solution than by simply solving the problem with only a single starting solution.

during the solution process of a mixed integer program, if you are interested in other integer solutions than the final solution returned by the solver. You can use the solution repository to store a fixed size collection of the best incumbent solutions returned by the solver during the solution process.

Solution repository

The GMP library comes with a solution repository for each generated mathematical program instance, and offers a number of functions to easily transfer a solution from and to either

the data of the variables and constraints that make up the associated mathematical program in your model, or

any solver session (explained below) associated with the generated mathematical program instance.

In fact, in the GMP library there is no direct solution/starting point transfer between a solver and the model, but such transfer always takes place through the solution repository.

Solver session pool

The final concept that is part of the GMP library is that of solver sessions. In principle, the GMP library is prepared to allow a generated mathematical program instance to keep a pool of associated solver sessions, each possibly set up with a different solver, or with different solver settings, and to be run either locally or remotely.

When useful

Using multiple solver session it becomes possible, for example, to let the same (or another) solver with different solver settings solve a mixed integer program instance in parallel, and pass tighter bound information found by one solver session to the other sessions by means of a callback implemented in your model.

`GMP`

namespace

To prevent naming conflicts, all functions and procedure in the GMP
library are member of the predefined `GMP`

namespace. The `GMP`

namespace is further partitioned into the namespaces

`GMP::Instance`

,`GMP::Row`

,`GMP::Column`

,`GMP::Coefficient`

,`GMP::Event`

,`GMP::QuadraticCoefficient`

,`GMP::Solution`

,`GMP::SolverSession`

,`GMP::Stochastic`

,`GMP::Robust`

,`GMP::Benders`

,`GMP::Linearization`

, and`GMP::ProgressWindow`

.

In the following sections we will discuss the procedures and functions contained in each of these namespaces.

Return values

When using the GMP library, it may be particularly important to check
for any kind of error conditions that can occur. To help you catch such
errors, the procedures and functions in the `GMP`

namespace either
return

a 1 when successful, or 0 otherwise (for procedures), or

a non-empty element in one of the GMP-related predefined sets when successful, or the empty element otherwise (for functions).

Note that, for the sake of brevity, most of the examples in this chapter do not perform error checking of any kind.