« Previous « Start » Next »
4 Defining Problems in TOMLAB
TOMLAB is based on the principle of creating a problem structure
that defines the problem and includes all relevant information
needed for the solution of the user problem. One unified format is
defined, the TOMLAB format (TQ format). The TQ format gives the
user a fast way to setup a problem structure and solve the problem
from the Matlab command line using any suitable TOMLAB solver.
The definition of an advanced general graphical user interface (GUI) and
a similar menu system demanded a more complicated format.
The solution is the IF format, where groups of problems are collected into
sets, each set having an initialization file.
Besides defining the problem, a list of all problems in the set is also
generated by the initialization file.
In this section follows a more detailed description of the TOMLAB
format and the Init Files.
4.1 The TOMLAB (TQ) Format
The TQ format is a quick way to setup a problem and easily solve
it using any of the TOMLAB solvers. The principle is to put all
information in a Matlab structure, which then is passed to the
solver, which extracts the relevant information. The structure is
passed to the user function routines for nonlinear problems,
making it a convenient way to pass other types of information
The solution process for the TQ format has four steps:
-
Define the problem structure, often called Prob.
- Call the solver or the universal driver routine tomRun .
- Postprocessing, e.g. print the result of the optimization.
Step 1 could be done in several ways in TOMLAB. Recommended is to call one
of the following routines dependent on the type of optimization problem,
see Table
10.
Table 10: Routines to create a problem structure in the TQ format.
|
| Matlab call |
probTypes |
Type of
optimization problem |
|
| Prob = bmiAssign( ... ) |
14 |
Semi-definite programming with bilinear matrix inequalities. |
| Prob = clsAssign( ... ) |
4,5,6 |
Unconstrained and constrained nonlinear least squares. |
| Prob = conAssign( ... ) |
1,3 |
Unconstrained and constrained nonlinear optimization. |
| Prob = expAssign( ... ) |
17 |
Exponential fitting problems. |
| Prob = glcAssign( ... ) |
9,10,15 |
Box-bounded or mixed-integer constrained global programming. |
| Prob = lcpAssign( ... ) |
22 |
Linear mixed-complimentary problems. |
| Prob = llsAssign( ... ) |
5 |
Linear least-square problems. |
| Prob = lpAssign( ... ) |
8 |
Linear programming. |
| Prob = lpconAssign( ... ) |
3 |
Linear programming with nonlinear constraints. |
| Prob = mcpAssign( ... ) |
23 |
Nonlinear mixed-complimentary problems. |
| Prob = minlpAssign( ... ) |
12 |
Mixed-Integer nonlinear programming. |
| Prob = mipAssign( ... ) |
7 |
Mixed-Integer programming. |
| Prob = miqpAssign( ... ) |
11 |
Mixed-Integer quadratic programming. |
| Prob = miqqAssign( ... ) |
18 |
Mixed-Integer quadratic programming with quadratic constraints. |
| Prob = qcpAssign( ... ) |
23 |
Quadratic mixed-complimentary problems. |
| Prob = qpblockAssign( ... ) |
2 |
Quadratic programming (factorized). |
| Prob = qpAssign( ... ) |
2 |
Quadratic programming. |
| Prob = qpconAssign( ... ) |
3 |
Quadratic programming with nonlinear constraints. |
| Prob = sdpAssign( ... ) |
13 |
Semi-definite programming with linear matrix inequalities. |
|
|
| Prob = amplAssign( ... ) |
1-3,7,8,11,12 |
For AMPL problems defined as nl-files. |
| Prob = probAssign( ... ) |
1,3-6,9-10 |
General routine, but does not include all possible options. |
| Prob = simAssign( ... ) |
1,3-6,9-10 |
General routine, functions and constraints calculated at the same time . |
|
Step 2, the solver call, is either a direct call, e.g. conSolve:
Result = conSolve(Prob);
or a call to the multi-solver driver routine
tomRun ,
e.g. for constrained optimization:
Result = tomRun('conSolve', Prob);
Note that
tomRun handles several input formats, also the
TOMLAB Init File format described in Section
4.2.
It may also print the names of the available solvers.
Step 3 could be a call to PrintResult.m:
PrintResult(Result);
The 3rd step could be included in Step 2 by increasing the print
level to 1, 2 or 3 in the call to the driver routine
Result = tomRun('conSolve',Prob, 3);
See the different demo files that gives examples of how to apply
the TQ format:
conDemo.m ,
ucDemo.m ,
qpDemo.m ,
lsDemo.m ,
lpDemo.m ,
mipDemo.m ,
glbDemo.m and
glcDemo.m .
4.2 The TOMLAB Init Files (IF)
In the IF one initialization file is defined for each set of user
problems. The set could consist of only one problem.
The initialization file should perform two tasks:
-
If the input problem number is empty, return a string matrix with the
i:th row defining the
name of the i:th problem defined in the file.
- If the input problem number is nonempty, return the TOMLAB problem
structure defining the corresponding problem number.
To write such a basic routine is very simple.
The user could write such a routine and it will function well.
However, some thoughts make it clear that additional functionality
is nice to have in such a routine. Adding an integer
ask, to
tell if the initialization routine should ask questions, makes the
routine either silent, or optionally asking for problem dependent
parameters. TOMLAB has a query routine predefined, that is
suitable to use:
askparam.m . Examples of the use of
askparam is implemented in several of the predefined Init
Files in the
testprob directory:
uc_prob.m ,
qp_prob.m ,
mgh_prob.m ,
ls_prob.m ,
cls_prob.m and
glb_prob.m . Most often a problem
dimension is asked for, or a certain data series. Sometimes a
parameter value.
Adding the problem structure as input makes it possible to override
the default parameters, setting some fields beforehand.
The syntax of the initialization file (Init File) is the following
(assuming the name of the function is
new_prob.m ):
[probList, Prob] = new_prob(P, ask, Prob)
where
| P |
The problem number, either empty, or an integer. |
| ask |
An integer defining if questions should be asked in the Init File.
If ask >= 1 ask questions in the Init File. If ask = 0
use default values.
If ask < 0 use values defined in Prob.uP if defined or
otherwise use defaults. The last options makes it possible to change
values before the call.
If isempty(ask), then if length(Prob.uP) > 0,
ask=−1, else ask=0. |
| Prob |
As input, the problem structure is either empty,
or some or all of the fields are defined, and overrides the default
values in the Init File. |
| probList |
A string matrix, always returned. |
| Prob |
As output, a full definition of the problem structure is returned
if a valid problem number P is given as input. |
If a group of problems have been defined in the TOMLAB Init File it is easy to
retrieve a problem structure similar to the TOMLAB format for any of these
problems. The general call is
Prob = probInit(probFile, probNumber, ask, Prob)
where
| probFile |
Name of the Init File, without file extension. |
| probNumber |
The problem number, an integer. |
| ask |
An integer, defined exactly as in the call to new_prob.m above. |
| Prob |
As input, the problem structure is either empty,
or some or all of the fields are defined, and overrides the default
values in the Init File. |
When a problem is available as one of the problems defined in the
TOMLAB Init File, i.e. as one problem in an Init File, there are four ways
to proceed to solve the problem
-
Solve the problem using the TOMLAB GUI, tomGUI .
tomGUI;
or
global ResultGUI
tomGUI; % After the run results are available in ResultGUI
... % Postprocess ResultGUI
Only the last problem solved is available in ResultGUI. All solver
parameters and other parameters influencing the optimization are
possible to change before the call to a suitable solver. Note the
code generation facility in tomGUI , which creates a m-file and
mat-file that solves identically the same problem from the command
line. This m-file may, for example, be further extended to solve
sequences of problem. This concept is further explained
in § 10.2.
- Solve the problem using the TOMLAB menu program, tomMenu .
Some, but not all,
solver parameters and other parameters influencing the optimization
are possible to change before the call to a suitable solver.
tomMenu;
or
Result = tomRemote; % After the run results are available in Result
... % Postprocess Result.
If more than one problem is solved Result(1) gives the
results for the first problem, Result(2) gives the results
for the second problem, and so on. - Pick up the problem
structure using probInit and make any changes to the
problem structure, e.g.
probFile = 'con_prob';
probNumber = 10;
ask = [];
Prob = [];
Prob = probInit(probFile, probNumber, ask, Prob)
... % Make changes in the Prob structure
The fields in the structure are described in the tables in
Appendix A. Then either directly call a solver
Result = conSolve(Prob);
or call the multi-solver
driver routine tomRun
Result = tomRun('conSolve', Prob);
If increasing the print level
to 1, 2 or 3 in the call to the driver routine the call is
Result = tomRun('conSolve', Prob, 3);
- Define a Prob structure with only the fields you want to
change, e.g
Prob.optParam.MaxIter = 1000; % Increase maximal numbers of iterations
Prob.x_0 = [0 1 3]'; % Change initial value of x
% Tell tomRun to use conSolve to solve problem 10 from con_prob.
% Print Level 3 in the call to PrintResult
Result = tomRun('conSolve', 'con_prob', 10, Prob, 3);
It is very easy to try another solver in TOMLAB , e.g. to see what
nlpSolve does on this problem just add one line
Result = tomRun('nlpSolve', 'con_prob', 10, Prob, 3);
Note that when solving a sequence of similar problems, the best
way is to pick up the problem structure once using
probInit ,
and then make a loop, do the changes in the structure, and solve
the problem for each change.
An example
solving problem 10 in
con_prob.m one hundred times for
different starting values in the interval [100,100]
probFile = 'con_prob';
probNumber = 10;
ask = [];
Prob = [];
Prob = probInit(probFile, probNumber, ask, Prob)
for i=1:100
Prob.x_0 = -100 + 200*rand(3,1);
Result = tomRun('conSolve', Prob, 1);
end
For each type of the optimization problem there is at least one Init File.
All the predefined Init Files with test problems are
available in the
testprob directory.
See also the different demonstration files
in the
examples directory
that also includes a few examples of how to apply
the IF format.
In Appendix
D detailed descriptions are
given on
how
to copy
an Init File into a new Init File,
and also adding new problems.
4.3 Creating an Init File from TQ
If dropping the wish to ask user questions, then a simpler type of
initialization file may be created.
Using the routines
newInitFile ,
addProb
and
makeInitFile ,
it is easy to collect a group of problem structures Prob into a
set and put them into the TOMLAB Init File.
The Prob structures are saved in a Matlab mat-file having the same
name as the Init File.
Having defined a proper file in the TOMLAB Init File,
it is added to the GUI calling the routine
AddProblemFile .
See the file
makeInitFileDemo for an example on how to
create a new Init File and get it into the GUI.
It is recommended that the problems added into the Init File are
of the same problem type (
probType ).
If only up to five problem structures are collected to the Init File,
then only one call is needed
% Assume four structures P1,P3,P3 and P4 are created in TQ format
...
makeInitFile('new_prob',P1,P2,P3,P4);
If doing this type of call several times during a session global
arrays used by
makeInitFile must be cleared, and a
call to
newInitFile is needed
newInitFile;
% Assume four structures P1,P3,P3 and P4 are created in TQ format
...
makeInitFile('new_prob',P1,P2,P3,P4);
It might be easier to collect the problems in a loop. Then
addProb is usable.
Assuming that
conAssign is used to create the basic problem,
the following example shows the principles of making the new Init File:
% Make the assignments and calls for the first problem
Prob = conAssign ( .....)
...
newInitFile(Prob);
for i=2:10 % Define problem 2, 3, up to 10
% Make the assignments necessary for this particular problem i
Prob.P = i;
...
% Then add the structure when it is complete
addProb(Prob);
end
makeInitFile('new_prob'); % Create the Init File and save problems
Note that for LP, QP and MIP problems there is another alternative to
create a file in the Init File format. The routines
lpAssign ,
qpAssign and
mipAssign
have an option to create Init Files with an arbitrarily number of
problems.
See the help for the input arguments
setupFile and
nProblem in these routines.
With this strategy the problems are saved more efficiently with regards
to space. One binary mat-file is created for each problem in the Init File.
If the number of problems are large, this alternative
may be preferable.
The Init File creation is more complicated, and described in detail
with examples in Section
5.
4.4 Adding an Init File to the GUI Data Base
In order to get a file created in the TOMLAB Init File accessible to the
GUI and menu system, it must be added to the GUI init file data base.
The database is stored in the file
TomlabProblem.mat .
The command
AddProblemFile adds a new Init File to the data
base. The name of the file, a menu text shortly describing the
content of the Init File, the problem type, and one additional
number
mexType must be given.
mexType is always zero
for Matlab files. The following example adds the user file
new_prob :
% Assume the name of the problem to add is 'new_prob', of type 'con'
AddProblemFile('new_prob','New user created problems','con',0);
Note that in order to run the GUI and the menu system with the newly
added problems, they must reside in the current directory, or
somewhere in the Matlab PATH. The added Init File is always put
first, as the default file, among the files having the same problem
type.
If the GUI can not find the files it will crash. Then you must
either put the problems in the Matlab PATH, or delete the problems
from the GUI data base. A problem is deleted by a call to
DeleteProblemFile. You must also know the problem type of the file.
% Assume the name of the problem to delete is 'new_prob', of type 'con'
DeleteProblemFile('new_prob','con');
If there are many problems to be deleted from the GUI data base, or if
other problems occur, there is a command to restore everything back to
the original distribution of TOMLAB :
CreateTomProb;
The user must press ENTER when a question
Overwrite??? (ctrl-c to break)
appears.
Another way to get an Init File into the GUI, and deleted from the
GUI, is to use the GUI itself. By filling in the file name in the
field
New Init File for GUI, and a menu text in
New Init
File Text, and after that pressing the button
Add Init File to
GUI, the problem will be added to the GUI problem data base.
Another RED button
Delete selected Init File, will delete the
currently selected Init File, if is not part of the original TOMLAB
distribution.
4.5 Modifying existing problems
It is possible to modify an existing
Prob structure by editing
elements directly, however this is not recommended since there are
dependencies for memory allocation and problem sizes that the user
may not be aware of.
There are a set of routines developed specifically for modifying
linear constraints (do not modify directly,
Prob.mLin need to
be set to a proper value if so). All the static information can be
set with the following routines.
Purpose
Adds linear constraints to an existing problem.
Calling Syntax
Prob = add_A(Prob, A, b_L, b_U)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| A |
The additional linear constraints. |
| b_L |
The lower bounds for the new linear constraints. |
| b_U |
The upper bounds for the new linear constraints. |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
Purpose
Keeps the linear constraints specified by idx.
Calling Syntax
Prob = keep_A(Prob, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| idx |
The row indices to keep in the linear constraints. |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
Purpose
Removes the linear constraints specified by idx.
Calling Syntax
Prob = remove_A(Prob, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| idx |
The row indices to remove in the linear constraints. |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
Purpose
Replaces the linear constraints.
Calling Syntax
Prob = replace_A(Prob, A, b_L, b_U)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| A |
New linear constraints. |
| b_L |
Lower bounds for linear constraints. |
| b_U |
Upper bounds for linear constraints. |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
4.5.5 modify_b_L
Purpose
Modify lower bounds for linear constraints. If idx is not given b_L
will be replaced.
Calling Syntax
Prob = modify_b_L(Prob, b_L, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| b_L |
New lower bounds for the linear constraints. |
| idx |
Indices for the modified constraint bounds (optional). |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
4.5.6 modify_b_U
Purpose
Modify upper bounds for linear constraints. If idx is not given b_U
will be replaced.
Calling Syntax
Prob = modify_b_U(Prob, b_U, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| b_U |
New upper bounds for the linear constraints. |
| idx |
Indices for the modified constraint bounds (optional). |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
Purpose
Modify linear objective (LP/QP only).
Calling Syntax
Prob = modify_c(Prob, c, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| c |
New linear coefficients. |
| idx |
Indices for the modified linear coefficients (optional). |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
4.5.8 modify_c_L
Purpose
Modify lower bounds for nonlinear constraints. If idx is not given
c_L will be replaced.
Calling Syntax
Prob = modify_c_L(Prob, c_L, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| c_L |
New lower bounds for the nonlinear constraints. |
| idx |
Indices for the modified constraint bounds (optional). |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
4.5.9 modify_c_U
Purpose
Modify upper bounds for nonlinear constraints. If idx is not given
c_U will be replaced.
Calling Syntax
Prob = modify_c_U(Prob, c_U, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| c_U |
New upper bounds for the nonlinear constraints. |
| idx |
Indices for the modified constraint bounds (optional). |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
Purpose
Modify starting point. If x_0 is outside the bounds an error will
be returned. If idx is not given x_0 will be replaced.
Calling Syntax
Prob = modify_x_0(Prob, x_0, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| x_0 |
New starting points. |
| idx |
Indices for the modified starting points (optional). |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
Purpose
Modify lower bounds for decision variables. If idx is not given x_L
will be replaced. x_0 will be shifted if needed.
Calling Syntax
Prob = modify_x_L(Prob, x_L, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| x_L |
New lower bounds for the decision variables. |
| idx |
Indices for the modified lower bounds (optional). |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
Purpose
Modify upper bounds for decision variables. If idx is not given x_U
will be replaced. x_0 will be shifted if needed.
Calling Syntax
Prob = modify_x_U(Prob, x_U, idx)
Description of Inputs
| Prob |
Existing TOMLAB problem. |
| x_U |
New upper bounds for the decision variables. |
| idx |
Indices for the modified upper bounds (optional). |
Description of Outputs
| Prob |
Modified TOMLAB problem. |
« Previous « Start » Next »
TOMLAB
