[Next chapter]

Introduction


What is Mosel?

Mosel is an environment for modeling and solving problems. To this aim, it provides a language that is both a modeling and a programming language. The originality of the Mosel language is that there is no separation between a modeling statement (e.g. declaring a decision variable or expressing a constraint) and a procedure that actually solves the problem (e.g. call to an optimizing command). Thanks to this synergy, one can program a complex solution algorithm by combining modeling and solving statements.

Each category of problem comes with its own particular types of variables and constraints and a single kind of solver cannot be efficient in all cases. To take this into account, the Mosel system does not integrate any solver by default but offers a dynamic interface to external solvers provided as modules. Each solver module comes with its own set of procedures and functions that directly extends the vocabulary and capabilities of the Mosel language. The link between Mosel and a solving module is achieved at the memory level and does not require any modification of the core system.

This open architecture can also be used as a means to connect Mosel to other software. For instance, a module could define the functionality required to communicate with a specific database.

The modeling and solving tasks are usually not the only operations performed by a software application. This is why the Mosel environment is provided either in the form of libraries or as a standalone program.

General organization

As input, Mosel expects a text file containing the source of the model/program to execute (henceforth we use just the term 'model' for 'model/program' except where there might be an ambiguity). This source file is first compiled by the Mosel compiler. During this operation, the syntax of the model is checked but no operation is executed. The result of the compilation is a BInary Model (BIM) that is saved in a second file. In this form, the model is ready to be executed and the source file is not required any more. To actually 'run' the model, the BIM file must be read in again by Mosel and then executed. These different phases are handled by different modules that comprise the Mosel environment:

The runtime library: This library contains the VIrtual MAchine (VIMA) interpreter. It knows how to load a model in its binary format and how to execute it. It also implements a model manager (for handling several models at a time) and a Dynamic Shared Objects manager (for loading and unloading modules required by a given model). All the features of this library can be accessed from a user application.

The compiler library: The role of this module is to translate a source file into a binary format suitable for being executed by the VIMA Interpreter.

The standalone application: The 'mosel' application, also known as 'Mosel Console', is a command line interpreter linked to the two previous modules. It provides a single program to compile and execute models.

Various modules: These modules complete the Mosel set of functionalities by providing, for instance, optimization procedures. As an example, the mmxprs module extends the Mosel language with the procedure maximize that optimizes the current problem using the Xpress-Optimizer.

This modularized structure offers various advantages:

Running Mosel

The Mosel environment may be accessed either through its libraries or by means of two applications, perhaps the simplest of which is the Xpress-MP integrated visual environment, Xpress-IVE. Using a popular graphical interface, models can be developed and solved, providing simple access to all aspects of Mosel's post-processing capabilities. Xpress-IVE is available under the Windows operating system only.

In its standalone version, Mosel offers a simple interface to execute certain generic commands either in batch mode or by means of a command line interpreter. The user may compile source models or programs (.mos files), load binary models (.bim files), execute them, display or save a matrix as well as the value of a given symbol. Several binary models can be loaded at a time and used alternatively. An interractive debugger as well as a profiler are also included: the debugger allows to execute the model step by step, specify breakpoints from where status of the model can be examined. Running a model with the profiler provides detailed information on what part of the code is actually executed and how much time each statement requires. This information may be helpful for optimizing the model (by locating hot spots where the code is using a great deal of computer time) and for building testsuites for instance (by chekcing whether the data sets used in the test set exercise all statements of a given model).

Command line interpreter: main commands

The mosel executable accepts the following command line options:

-h
Display a short help message and terminate.
-V
Display the version number and terminate.
-s
Silent mode (valid only when running in batch mode)
-c commands
Run Mosel in batch mode. The parameter commands must be a list of commands (see below) separated by semicolons (this list may have to be quoted with single or double quote depending on the operating system and shell being used). The commands are executed in sequence until the end of the list or until an error occurs, then Mosel terminates. For example, 
mosel -c "cload -sg mymodel; run"

If no command line option is specified, Mosel starts in interactive mode. At the command prompt, the following commands may be executed (the arguments enclosed in square brackets [] are optional). The command line interpreter is case-insensitive, although we display commands in upper case for clarity:

INFO [symbol]
Without a parameter, this command displays information about the program being executed (this may be useful for problem reporting). Any parameter is interpreted as a symbol from the current model. If the requested symbol actually exists, this command displays some information about its type and structure.
SYSTEM command
Execute an operating system command.
Examples: 
>system ls
>system vi mywork.mos
Execute the command ls to display the current directory content and launch the VI editor to edit the file mywork.mos. Note that if the command contains blanks (usually the case if it requires parameters), quotes have to be used.
SETSTREAM [-i|o|e] filename [file_out file_err]:
Set one (or all) of the default streams: without option, three filenames are required (input, output and error stream). Note that if one of these file names is '*', the corresponding stream is not modified. A single stream may be updated using one of the option flags ('-i' for input, '-o' for output and '-e' for error). If no model is loaded, the setting becomes the default for models loaded later and the system switches to the given error stream (for error messages during compilation for instance). Otherwise the change applies to the current model.
QUIT
Terminate the current Mosel session.
COMPILE [-sgGp] filename [comment [dst_file]]
Compile the model filename and generate the corresponding Binary Model (BIM) file if the compilation succeeds. The extension .mos is appended to filename if no extension is provided. If option dst_file (filename to use for saving BIM file) is not given, the extension .bim is used to form the name of the binary file. If the flag '-s' is selected, the private object names (e.g. variables, constraints) are not saved into the BIM file. The flag '-g' adds debugging information: it is required to locate a runtime error. The flag '-G' adds both debugging and tracing information: it is required to run the model with the debugger. When this flag is used, the compiler adds instructions in the generated code that may slow down execution speed of the model. The optional comment parameter may be used to add a commentary to the BIM file (cf. command LIST). Note that the source file name may contain environment variable expansions using the notation ${varname} (e.g. '${MOSEL}/source/model'). When this facility is used, an output file name must be provided. If the flag '-p' is selected, only the syntax of the source file is checked, the compilation is not performed and no output file is generated.
Examples: 
>compile mywork "This is an example"
>compile thismodel.mos
Compile the files mywork.mos and thismodel.mos, creating the BIM files mywork.bim and thismodel.bim after successful completion of the compilation.
LOAD filename
Load the BIM file filename into memory and open all modules it requires for later execution. The extension .bim is appended to filename if no extension is provided. If a model bearing the same name is already loaded in core memory it is replaced by the new one (the name of the model is specified by the statement model in the source file — it is not necessarily the file name).
Example: 
>load mywork
Load mywork.bim into memory (provided the source file begins with the statement model mymodel, the name of this problem is 'mymodel').
CLOAD [-sgG] filename [comment]
Compile filename then load the resulting file (if the compilation has succeeded). This command is equivalent to the consecutive execution of compile filename and load filename. For an explanation of the options see command COMPILE.
LIST
Display the list of all models loaded using either CLOAD or LOAD. The information displayed for each model is:
  • name: the model name and version number (given by the model and version statements in the source file);
  • number: the model number is automatically assigned when the model is loaded;
  • size: the amount of memory used by the model (in bytes);
  • system comment: a text string generated by the compiler indicating the source filename and if the model contains debugging information and/or symbols;
  • user comment: the comment defined by the user at compile time (cf. COMPILE, CLOAD);
  • modules: the name and version number of each module required by the model;
  • pkg. req.: if the model is a package, the name and version number of each package required by a model using this package;
  • pkg. imp.: the name and version number of each package included by this model.
The active model is marked by an asterisk ('*') in front of its name (the commands UNLOAD, RUN, and RESET are applied to the active model). By default the last model that has been loaded is active.
SELECT [number | name]
Activate a model. The model can be selected using either its name or its order number. If no model reference is provided, information about the current active model is displayed.
UNLOAD [number | name]
Unload a model from memory (the BIM file is not affected by this command). If no model name or sequence number is given, the active model is unloaded. If the active model is removed, the model loaded most recently (if any) becomes the new active model.
RUN [parameters]
Execute the active model. Optionally, a list of parameter values may be provided in order to initialize the parameters of the model and/or the control parameters of the modules used. The syntax of such an initialization is param_name = value for a model parameter and dsoname.ctrpar_name = value, where dsoname is the name of a module and ctrpar_name the control parameter to set. Pressing ctrl-C causes the execution to be canceled. Note that if a critical operation is being processed, the interruption is delayed until the operation completes. For instance, the Optimizer cannot be interrupted during an iteration of its algorithm. that
Examples: 
>run A=33,B="word",C=true,D=5.3e-5
>run Z="aa",mmxprs.XPRS_verbose=true
>run T=1
DEBUG [parameters]
Execute the active model with the debugger (cf. Section Command line interpreter: debugger). Optionally, a list of parameter values may be provided in order to initialize the parameters of the model and/or the control parameters of the modules used. This command requires that the model has been compiled with options -g or -G.
PROFILE [-sp] [parameters]
Execute the active model with the profiler. Optionally, a list of parameter values may be provided in order to initialize the parameters of the model and/or the control parameters of the modules used. This command requires that the model has been compiled with options -G. After execution, the total execution time and some source coverage information is displayed. Moreover, if options -s has not been specified, a file sourcefile.prof is generated based on the original source file. Each line of this file consists in:
  • the number of times the corresponding statement has been executed;
  • the total amount of time (in seconds) or the percentage of the total execution time (if option -s is used) spent on this particular line (this measure is not valid if the statement is a recursive call);
  • the elapsed time (in seconds) between the beginning of the execution and the last time the line was executed;
  • the text of the model source
All lines of the original source file are transferred, lines not corresponding to the beginning of a statement are directly copied without further information.
EXEC [-sg] filename [params]
Compile filename, load, and then run the model. This command is equivalent to the consecutive execution of cload filename and run params except that the BIM file is not preserved. For an explanation of the options see command COMPILE.
RESET
Re-initialize the active model by releasing all the resources it uses.
EXPORTPROB [-pms] [filename [objective]]
Display or save to the given file (option filename) the matrix corresponding to the active problem. The matrix output uses the LP format or the MPS format (flag '-m'). A problem is available after the execution of a model. The flags may be used to select the direction of the optimization ('-p': maximize), the file format ('-m': MPS format) and whether real object names should be used ('-s': scrambled names — this is the default if the object names are not available). The objective may also be selected by specifying a constraint name.
PRINT expression [>> filename]
Evaluate then display the value of the given arithmetic or Boolean expression. For building the expression, the following functions can be used: getparam, ceil, floor, round, abs, getsol, getsize, getrcost, getdual, getslack, getact. get-functions may be called using the suffix notation (e.g. getact(c) is equivalent to c.act). Some functions can be applied to arrays: the result is the evaluation of the function for each cell of the array. Private symbols of packages may be accessed by prefixing the symbol name by the package name and the symbol ˜ (for instance the identifier aa declared in the package mypkg can be accessed using mypkg˜aa). Display format of this command is compatible with the data file format of Mosel. Use operator >>filename to append output of the command to file filename.
Examples: 
>print getsol(x) >> solfile.txt
>print getact(C(1,"tut"))+c.size
>print toto~a
>print abs(mytol)>1
OPTION name [[=] value]
View or change the value of a command line parameter. These parameters are used by the command line interpreter to display real values (especially in command PRINT):
  • realfmt: C-style format for printing floating point numbers (default value: "%g")
  • zerotol: zero tolerance to decide whether two values are equal (default value: 1e-13). It is also used when printing very small numbers: if a value is smaller than zerotol, "0" is displayed instead.
Although these parameters have same name and function than those used by Mosel when running a model, they are not synchronised with their internal counterpart.
SYMBOLS [-cspou]
Display the list of symbols published by the current model. The optional flags may be used to filter what kind of symbol to display: '-c' for constants, '-s' for subroutines, '-p' for parameters and '-o' for everything else. By default the list is sorted in alphabetical order, option '-u' disables sorting.
LSDRVS
Display the list of IO drivers currently available.
LSLIBS
Display the list of all loaded dynamic shared objects (DSO) together with, for each module, its version number and its number of references (i.e. number of loaded models using it).
EXAMINE [-csptdu] libname
Display the list of constants, procedures/functions, types, IO drivers and control parameters of the module libname. Optional flags may be used to select which information is displayed: '-c' for constants, '-s' for subroutines, '-t' for types, '-d' for IO drivers and '-p' for control parameters. By default listings are sorted in alphabetical order, option '-u' disable sorting.
FLUSHLIBS
Unload all unused dynamic shared objects.

If a command is not recognized, a list of possible keywords is displayed together with a short explanation. The command names can be shortened as long as there is no ambiguity (e.g. cl can be used in place of CLOAD but c is not sufficient because it could equally denote the COMPILE command). String arguments (the parameter 10 is a number, but "10" or '10' are text strings) may be quoted with either single or double quotes. Quoting is required if the text string starts with a digit or contains spaces and/or quotes.

The mosel command terminates with the following exit status:

0: Normal termination
1: Unrecoverable error
2: Execution interrupted (ctrl-C, compilation failed...)
3: License error
4: Memory error

Moreover, if run or exec is the last command executed by the interpreter, the value returned is the one provided via procedure exit in the model (by default this is 0).

Typically, a model will be loaded and executed with the following commands:

>cload mymodel
>run

If the BIM file is not required, the EXEC command may be preferred: 

>exec model

Command line interpreter: debugger

When a model executed through the debugger is interrupted (because the user has typed ctrl-C or an error occured for instance), the execution is suspended, the command line interpreter displays the text source of the statement being processed and enters debug mode. In this mode, the normal command prompt is replaced by '>dbg' and only commands EXPORTPROB, INFO, OPTION and PRINT are still available. In addition the following commands are enabled:

CONTINUE
Resume execution. If the interruption was not due to an error, execution of the model continues, otherwise the execution of the model is aborted and the command line interpreter returns to its normal mode.
STEP
Continue execution until the next statement stepping into procedures and functions. The execution continues but will be interrupted again after the current statement has been completed. If the current statement contains function or procedure calls, interruption will happen in these procedures or functions.
NEXT [line [file]]
Continue execution until the next statement. The execution continues but will be interrupted again after the current statement has been completed. If a location information is provided (by means of a line number and, if necessary, a file name), the next interruption will occur before the specified statement is executed.
QUIT
Terminate the debug session. Execution is aborted and the command line interpreter returns to its normal mode.
LIST [[start] nblines]
Display the source file corresponding to the model being executed. When used with no extra argument, this command lists 10 lines of the source model starting at the current statement; used with a single positive parameter nblines, it displays nblines lines instead of the default 10 lines. If the parameter nblines is negative, it is interpreted as a starting point for the listing relative to the current statement. When 2 parameters are used, the first one is understood as the first line to display (a negative value is relative to the current line) and the second one as the number of lines to display.
Examples (assuming current line is 5): 
>list        displays lines 5 to 14
>list 5      displays lines 5 to 9
>list -2     displays lines 3 to 14
>list -2 5   displays lines 3 to 7
DISPLAY [expression]
Record an expression to be displayed at each interruption. Used with no expression, this command gives a list of all recorded expressions.
UNDISPLAY [disp]
Remove an expression recorded with DISPLAY. If no parameter is provided, all recorded expressions are removed otherwise the parameter is understood as a record number.
BREAK [procname]|[line [file]]
Install a breakpoint. When a breakpoint has been set up, execution is interrupted whenever the statement corresponding to the specified location is reached. A procedure or function name may be used as the location: in this case a breakpoint is installed at the beginning of each procedure or function of the provided name. If used with no parameter, the breakpoint is defined at the current location.
BCONDITION bk [cond]
Define or remove a condition on a breakpoint. This command may be used to put a condition (Boolean expression) on the specified break point: the execution is suspended at the breakpoint only if the given condition is verified. To remove a condition previously set up, the command should be typed without specifiyng the condition.
DELETE [bk]
Delete a breakpoint.
BREAKPOINTS
List defined breakpoints.
WHERE [nblev]
Display the calling stack. The calling stack corresponds to the sequence of procedure and function calls being processed. For instance assume the model calls procedure A which calls procedure B and the execution is suspended in procedure B: the calling stack will contain 3 records (location where A is called, location where B is called and current statement).
UP [nblev]
Go up in the calling stack. If an argument is provided, it indicates how many levels up to go (default is 1). Note that expressions are evaluated according to the current stack frame. For instance is variable i is defined in procedure B and execution is suspended in procedure A called by B; it is necessary to go up in the stack in order to view the value of i because it does not exist in the current frame.
DOWN [nblev]
Go down in the calling stack. If an argument is provided, it indicates how many levels down to go (default is 1).

Execution step by step and breakpoints can be used only if the model has been compiled using option -G. In this case, before the execution starts, a breakpoint is automatically put at the first statement of the model. Otherwise (model has been compiled with option -g), the model will be interrupted only if an error occurs or keys ctrl-C are pressed.

References

Mosel could be described as an original combination of a couple of well known technologies. Here is a non-exhaustive list of the most important 'originators' of Mosel:

Structure of this manual

The main body of this manual is essentially organized into two parts. In Chapter The Mosel Language, the basic building blocks of Mosel's modeling and programming language are discussed.

Chapter Predefined functions and procedures begins the reference section of this manual, providing a full description of all the functions and procedures defined as part of the core Mosel language. The functionality of the Mosel language may be expanded by loading modules: the following chapters describe the modules currently provided with the standard Mosel distribution: mmetc, mmive, mmodbc, mmquad, mmsystem, and mmxprs.


[Next] [Index]
If you have any comments or suggestions about these pages, please send mail to docs@dashoptimization.com.