omc(1)

NAME
omc - OpenModelica Compiler/Interpreter a Modelica compiler based on free software

HINT
This man page of omc - OpenModelica Compiler/Interpreter is in most parts a copy of the man page from omc version 1.4.5. A description of new parameters aren't included in the man page of this release candidate. The maintainer will include the description of new parameters in the final version of omc.

SYNOPSIS
omc [omcOptions] [runtimeOptions - general commands] [runtimeOptions - tuning commands] [runtimeOptions - tracing commands] [runtimeOptions - debugging commands] [optionalFiles]

DESCRIPTION
omc is a compiler that translates source code written in Modelica language to C++. With a suitable C++ compiler omc creates a executable simulation file, runs the simulation file and presents the result in a graphical view.

The executable omc knows two running modes, the direct mode and the server mode.

In direct mode omc act upon the delivered model or script file. Model files Model.mo or Model.mof will be translated in flattened Modelica source code. The result will be send to the standard output. Using the omcOption +s followed by a Model.mo file will create a C++ source code file, a make file and several support files. These files will be stored in the current working directory.

Script files Script.mos includes OpenModelica control commands. These commands control the executable behavior of omc. With a script omc can load, translate, build, simulate a model and plot the result of a simulation. The plot of a simulation result ensues with the aid of the JAVA client Ptolemy or the Qt client graphWindow. Consequently omc can execute plot commands only in a X-Windows environment like GNOME or KDE. All from the script produced files, the C++ source code file, the support files, the simulation file and the plot file will be stored in the current working directory. Consequently omc shouldn't be started from the user's home directory or another sensitive directory.

In server mode omc runs in the background and waits for inputs from a client. The Debian package of the OpenModelica Project includes the clients OMNotebook, OMShell and OMShell-terminal. The clients OMNotebook and OMShell are Qt-Windows applications. The client OMShell-terminal is a console application and runs in a X-Windows based terminal emulation like gnome-terminal. The communication between the clients and the server can be based on MICO or on BSD-sockets. MICO is an open source implementation of CORBA 2.3.

More documentation will be found in the enclosed OpenModelica System Documentation or the OpenModelica Users Guide. The documentation OpenModelica System Documentation, Version 2009-11-09 for OpenModelica 1.5 shows in chapter 2 on page 15 how to run omc in stand alone mode. Section DOCUMENTATION of this manual page shows where the above mentioned documentations are stored on this computer system. The section USING OMC shows how to run the compiler omc.

OpenModelica Compiler/Interpreter omc is the work of the members from Programming Environment Laboratory (PELAB) of the Department of Computer and Information Science (IDA) in the Linkoeping University (LiU). The goal of The OpenModelica Project is the creation of a complete Modelica modeling, compilation and simulation environment based on free software. The OpenModelica Project is supported by The Open Source Modelica Consortium (OSMC).

Modelica is a formal computer language for object-oriented modeling and simulation of technical systems.

OPTIONS

  omcOptions:

++v, +version
    Will print the version and exit.

+s  Generate simulation code.

+s Model.mo
    Will generate code for the model “Model”:

    Model.cpp
        the model C++ code
    Model_functions.cpp
        the model functions C++ code
    Model.makefile
        the makefile to compile the model
    Model_init.txt
        the initial values for parameters

+d=interactive
    Will start omc as a server listening on the socket interface.

+d=interactiveCorba
    Will start omc as a server listening on the CORBA interface.

+c=corbaName
    Works together with +d=interactiveCorba. It will start omc with a different CORBA session name. This way multiple omc compilers can be started.

+annotationVersion=<value>
    What annotation version should we use. Accepted values are 1.x, 2.x or 3.x.

    Default annotation value:
        2.x

+noSimplify
    Do not simplify expressions.

    Default is to simplify.

+q  Run in quiet mode, output nothing.

+metaModelica
    Accept MetaModelica grammar and semantics.

+d=<flags>
    Set debug flags.
    NOTE:
        Read more about debug flags in the OpenModelica System Documentation, chapter 2, section 2.1.2 “Compiler Debug Flags” on page 16. See section DOCUMENTATIONS in this manual page, for more informations about the above mentioned document.

+d=bltdump
    Dump in the blt form.

+d=failtrace
    Print what function fail.

+d=parsedump
    Dump the parsing tree.

+d=parseonly
    Will only parse the given file and exit.

+d=dynload
    Display debug information about dynamic loading of compiled functions.

  runtimeOptions - general commands:

-help
    Prints the runtime options and exits.

  runtimeOptions - tuning commands:

-log
    Prints runtime log information at the program exit.

-gcgag
    Prints garbage collector log information at the program exit.

-bench
    Prints running time and other log information at the program exit.

-no-stack-check
    Instructs the runtime not to check for stack overflow.

-stack-size=<size>
    Instructs the runtime to allocate a stack of specified size.

-young-size=<size>
    Instructs the runtime to allocate a young size of specified size.

  runtimeOptions - tracing commands:

-trace
    Prints all the function names during execution - default to 'no'.
    NOTE:
        Compiled with -ftrace

-no-trace
    Disable printing of all the function names - default to 'yes'.
    NOTE:
        Compiled with -ftrace

  runtimeOptions - debugging commands:

    NOTE:
        If you don't specify one of the ports below, the executable will run without any debugging.

-dbgCmdPort=<port>
    Open the server localhost:CmdPort and listen for commands from the client.

-dbgReplyPort=<port>
    Open the server localhost:ReplyPort and send reply to commands from the client.

-dbgEventPort=<port>
    Open the server localhost:EventPort and send async events to the client.

-dbgSignalPort=<port>
    Open the server localhost:SignalPort and listen to async events from the client.

-dbgSocket
    Debug the socket communication.

-debugAll
    Dumps all the calls and the values of variables to standard output.
    NOTE:
        Can be extremely large

  optionalFiles:

Model.mo
    OpenModelica or Modelica model source code file

Model.mof
    OpenModelica or Modelica flattened model source code file

Script.mos
    OpenModelica script file

ENVIRONMENT

OPENMODELICAHOME
    This variable contains the absolute path towards the OpenModelica Compiler/Interpreter executable omc.

    Default directory:
        /usr/

OPENMODELICALIBRARY
    Absolute path towards the OpenModelica library Modelica.

    Default directory:
        /usr/share/omlibrary/modelicalib/

QTHOME
    Absolute path towards the directory with Qt libraries. The Compiler/Interpreter omc use these libraries to build the simulation executable. Setting the environment variable is only necessary, if omc is compiled with Qt support. The Compiler/Interpreter omc of the Debian package is compiled with Ot support by default.

    Default directory:
        ${OPENMODELICAHOME}/lib/

SENDDATALIBS
    This variable includes various libraries into the make control file Model.makefile. The variable SENDDATALIBS mustn't be set manual, only if the model will be compiled by hand. How to use the environment variable in the case of a manual compilation, is shown in the 2nd example of section USING OMC. Usually the environment variable will be set during the run of the compiler omc, if the environment variable QTHOME is set. Should the model be compiled by hand, then the environment variable SENDDATALIBS must get the following values:

    SENDDATALIBS="-lsendData -lQtCore -lQtGui -lQtNetwork"

MODELICAUSERCFLAGS
    Extend the compiler variable CFLAGS in the make control file Model.makefile by user supplied optimization flags. The variable must be set before the start of the compiler omc or before the execution of the make file Model.makefile via the command make -f Model.makefile.

FILES
The compiler omc needs some support files. These files are C++ include files, libraries, shell scripts and executables. The following subsections list the required files and there storage place.

  Executables:
The following executables supports the various OpenModelica plot commands. How to use these applications is shown in the 4th example in section USING OMC.

•   Ptolemy is a JAVA based application that plots a graphical view of the simulation results. The OpenModelica command plot2() and his variants use Ptolemy.

    File:
        ptplot-linux.jar
    Path:
        /usr/bin/

•   The Qt based graphWindow application is a advanced variant of Ptolemy. The OpenModelica command plot() and his variants use graphWindow.

    File:
        ext
    Path:
        /usr/bin/

  Shell-Scripts:
The script files supports omc during the build of the executable simulation file and the presentation of the simulation results via Ptolemy.

•   Compile execute the GNU make utility with a make control file $1.makefile as parameter. The shell variable $1 is the name of the simulation model. The OpenModelica command simulate() triggers via omc this script.

    File:
        Compile
    Path:
        /usr/bin/

•   The script doPlot's duty is the launch of Ptolemy, the JAVA based graphical viewer. The script uses the environment variable OPENMODELICAHOME to localize Ptolemy in the directory tree.

    File:
        doPlot
    Path:
        /usr/bin/

  Includes:
To compile a translated C++ model source code file, the C++ compiler needs suitable include files. These include files are stored in following directory.

    Path:
        /usr/include/

  Libraries:
This version of omc compiles with his companion C++ compiler simulation files with the support of Qt libraries. The required Qt libraries and other libraries are stored under the following directory.

    Path:
        /usr/lib/

NOTE:
    The Qt libraries libQtCore.so, libQtGui.so and libQtNetwork.so in the above directory are symlinks to the original Qt libraries in /usr/lib/. If this symlinks are broken, the C++ compiler can't compile a simulation file. This could happen, when a Debian package with new Qt libraries will be installed.

  JAVA interface:
The following files supports the bidirectional OpenModelica-Java CORBA interoperability.

    Files:
        antlr-3.1.3.jar, modelica_java.jar
    Path:
        /usr/share/java/

USING OMC
This section shows in some examples, how to invoke the compiler omc from the console.

NOTE:
    The examples shouldn't be launched in user's home directory or another sensitive directory. In some examples the compiler omc produce during his run C++ source code and some auxiliary files. This files will be stored in the current working directory. The best way to avoid the clutter in a used directory, is the creation of a fresh directory for the coming examples.

1.  This example will flattened Modelica source code. The result is delivered on the standard output. In this mode omc flattened only source code without references to external Modelica libraries. The following Modelica source code file Circle.mo has no references to a Modelica library. The example file dcmotor.mo includes code from the Modelica standard library. The path to above mentioned example files is shown in section EXAMPLES. How to flatten Modelica source code with included Modelica library code, will be shown in one of the following examples. Now follows the command to flatten the source code of the file Circle.mo:

    user@host$>
        omc Circle.mo

2.  The following command will throw out the translated Circle.mo file. The result is the C++ source code file Circle.cpp of Circle.mo. The C++ file is stored in the current working directory:

    user@host$>
        omc +s Circle.mo

    The above command produce among several other support files a make file. With a suitable C++ compiler the following commands will compile the C++ source code:

    user@host$>
        export SENDDATALIBS="-lsendData -lQtCore -lQtGui -lQtNetwork"
    user@host$>
        make -f Circle.makefile

    The result of the compilation is the executable file Circle, called simulation file. If started it will solve the model of Circle.mo and will spite out the numerical solution of its simulation:

    user@host$>
        ./Circle

    The numerical values of the simulation are stored in the plot file Circle_res.plt. The plot file includes all values of all variables that describe the model. A plot of all these values can be displayed with the JAVA based graphical viewer Ptolemy. The following commands will present the simulation data on the screen:

    user@host$>
        export OPENMODELICAHOME=/usr/
    user@host$>
        /usr/bin/doPlot Circle_res.plt

    During the execution Ptolemy prints a pixel image of the displayed graph. The image is stored under the file name omc_tmp_plot.png in the current working directory. This isn't the usual behavior of the original Ptolemy. This version of Ptolemy is adapted for the special requirements of the OpenModelica Project.

    The above command sequence isn't the usual way, how a simulation is realized. Usually a client like OMNotebook triggers the above sequence. The above example is a visualization of the work flow and should make the whole process a little more transparent.

3.  This example will demonstrate the scripting capabilities of omc. The following script flat_dcmotor.mos will instruct omc to load the standard Modelica library, load the Modelica source code of the dcmotor model and flatten the loaded source code. The source code of the dcmotor model is stored in the file dcmotor.mo. The result will be printed on the standard output. The following rows shows the contents of the script flat_dcmotor.mos:

    01  loadModel(Modelica);
    02  loadFile("dcmotor.mo");
    03  instantiateModel(dcmotor);

    The following command will do the job. The flattened Modelica source code will be printed on standard output:

    user@host$>
        omc flat_dcmotor.mos

    Or pipe the output to the pager less:

    user@host$>
        omc flat_dcmotor.mos | less -SM

4.  This example runs a complete simulation of a starting D.C. motor. The commands in the script sim_dcmotor.mos will translate the Modelica source code of the dcmotor model in the corresponding C++ code, will create a executable simulation file, will execute the simulation file and will plot the result. The plot can run via two different plot clients. The plot2() command uses Ptolemy a JAVA based graph plotting application. The newer plot() command presents the results in a Qt based window. The following rows shows the contents of the script sim_dcmotor.mos:

    01  loadModel(Modelica);
    02  loadFile("dcmotor.mo");
    03  simulate(dcmotor,startTime=0.0,stopTime=10.0);
    04  plot({load.w,load.phi});
    05  plot2({load.w,load.phi});

    The following command will present the result in Ptolemy and the Qt graphic window:

    user@host$>
        omc sim_dcmotor.mos

5.  The next examples will show how to start omc in the server mode. In the server mode omc runs as independent process and will act upon inquiries from a client. The communication between omc and the client can use two different communication interfaces. One is based on the BSD socket interface, the other use CORBA. The following examples shows how to run the server omc with the client OMShell-terminal. In the first example omc will be launched in server mode with the BSD socket interface:

    First console
    user@host$>
        omc +d=interactive

    In a second console run the following command:

    Second console
    user@host$>
        OMShell-terminal -noserv

    The option -noserv is required. Without the option -noserv the client OMShell-terminal will create his own instance of the compiler omc.

    The second example does the same, but the communication between the server and the client will use the CORBA interface:

    First console
    user@host$>
        omc +d=interactiveCorba

    In a second console run the following command:

    Second console
    user@host$>
        OMShell-terminal -noserv -corba

    NOTE:
        In the above and in the following examples the compiler omc can't be put in the background. A command like “omc +d=interactive &” will not do the expected job. Only in a script the compiler can run in the background. The script OMShell-terminal shows how the compiler omc can be put in background. The script is stored in the directory /usr/bin/.

    The clients OMShell and OMNotebook needs some special treatment. These clients don't know the options -noserv and -corba. The default communication interface is CORBA and it can't be changed. Consequently the compiler omc can only be put in the independent server mode “interactiveCorba”.

    The compiler omc needs a special treatment to. Running omc in an independent server mode and with one of the above clients OMShell or OMNotebook, the current working directory shouldn't be the user's home directory. The start of omc should be happened in a sub directory. The next examples uses the directory /home/${USER}/OMWorkspace/ as start and working directory.

    The following examples will run the compiler omc in the independent server mode and with the communication interface CORBA. The clients will be called in a separate console. The clients will switched automatically to the interface of the server omc. In these cases the option -noserv is not needed:

    First console
    user@host$>
        cd /home/${USER}/OMWorkspace/
    user@host$>
        omc +d=interactiveCorba

    Second console
    user@host$>
        cd /home/${USER}/OMWorkspace/
    user@host$>
        OMShell

    The next example does the same but now OMNotebook runs as client:

    First console
    user@host$>
        cd /home/${USER}/OMWorkspace/
    user@host$>
        omc +d=interactiveCorba

    Second console
    user@host$>
        cd /home/${USER}/OMWorkspace/
    user@host$>
        OMNotebook

EXAMPLES
Modelica source code examples, Modelica scripts and OMNotebook files are stored under the following directory.

Path:
    /usr/share/omc/doc/testmodels/

Files with the extention .mo are Modelica source code files. Scripts are extended with the short .mos and the .onb extention is used for OMNotebook files.

DOCUMENTATIONS
This section lists all available documents of The OpenModelica Project. The most of the following documents are from the collaborator of the Programming Environment Laboratory (PELAB).

Title:
    OpenModelica Users Guide
Issue:
    Version 2009-11-09 for OpenModelica 1.5
Author(s):
    Peter Fritzon, Adrian Pop, Peter Aronsson and other
File:
    OpenModelicaUsersGuide.pdf
Path:
    /usr/share/omc/doc/

Title:
    OpenModelica System Documentation
Issue:
    Version 2009-11-09 for OpenModelica 1.5
Author(s):
    Peter Fritzon, Adrian Pop, Peter Aronsson and other
File:
    OpenModelicaSystem.pdf
Path:
    /usr/share/omc/doc/

Title:
    TUTORIAL - Introduction to Object-Oriented Modeling and Simulation with OpenModelica
Issue:
    Version 2006
Author(s):
    Peter Fritzon
File:
    ModelicaTutorialFritzson.pdf
Path:
    /usr/share/omc/doc/

Title:
    Modelica Meta-Programming and Symbolic Transformations - MetaModelica Programming Guide
Issue:
    Preliminary Incomplete Draft, 2007-06-20
Author(s):
    Peter Fritzon
File:
    OpenModelicaMetaProgramming.pdf
Path:
    /usr/share/omc/doc/

Title:
    OpenModelicaAPI-Howto
Issue:
    unknown
Author(s):
    unknown
File:
    OMC_API-HowTo.pdf
Path:
    /usr/share/omc/doc/

DIAGNOSTICS
The following subsections give some hints, how to cure simple failures.

  Libraries:
The Qt libraries libQtCore.so, libQtGui.so and libQtNetwork.so under the directory /usr/lib/ are symlinks to the original Qt libraries in /usr/lib/. If this symlinks are broken, the C++ compiler can't compile a simulation file. This could happen, when a Debian package with new Qt libraries will be installed. If this happens, the symlinks must be corrected.

SEE ALSO
omc(1), OMNotebook(1), OMShell(1), OMShell-terminal(1)

AUTHOR
The original author was William Spinelli. Changes and improvements were made by Robert Wotzlaw <Robert.Wotzlaw at web.de>.

The current author isn't a member of the Open Source Modelica Consortium (OSMC) nor a collaborator at the Programming Environment Laboratory (PELAB), Department of Computer and Information Science (IDA) of the Linkoeping University (LiU). He supports the OpenModelica Project as volunteer.