• Simulation Library
  • Usage models
  • Basic structure
  • Language bindings
  • Simulation Server Commands
  • Simulation Client Commands
  • Handling data on parallel machines

Simulation Library

Usage models

Interactive simulation

The primary focus of the Simulation Library is to allow an easy implementation of interactive simulations. An interactive simulation is a simulation code which is started directly from COVISE, immediately visualizes its results and allows parameter changes during ongoing simulation. It is assumed, that the simulation code is not directly integrated as subroutine into a COVISE module but a client-server coupling to a remote machine is used.

Control Visualization

Another application of simulation coupling is checking simulations with long execution times. In this case, the simulation start-up is not done by COVISE, but COVISE can connect to the running simulation and display the intermediate results. This allows an engineer to check them and terminate erroneous simulations early, avoiding unnecessary computing costs. Control visualization commands with repeated attachment to and detachment from the simulation is not yet implemented.

Basic structure

The simulation library is split into two parts:

• The simulation server is the COVISE-sided part of the simulation coupling. It is integrated into a module and takes care of the flow control, receives the parameters from the Map-Editor and puts the data from the simulation into the COVISE administered shared memory.
• The simulation client is the simulation-sided part of the coupling. It connects the COVISE module to the simulation code, exchanges messages with the module to request parameter values and sends results to the server for visualization.

Language bindings

The simulation client is written in ANSI C and calls only functions of the standard C library, which is automatically linked to every code on UNIX operating systems. This is important, because some simulation codes do not allow additional libraries to be added to the linker line but only object files.

The implementation language of COVISE is C++, which also applies to the COVISE-sided part of CoSimLib used by the simulation server. Thus it is possible to use all features of the development system.

The simulation library is accessible from multiple languages via appropriate language bindings. At the moment, 4 languages are supported:

1. C as the internally-used `natural' language binding for the client
2. FORTRAN77 as the most common language used for simulations
3. Fortran 90 by using backward-compatibility with FORTRAN77
4. C++ by using header-definitions to map C++ language calls to C language calls

Additional language bindings will be supplied if necessary.

Simulation Server Commands

The Simulation Server is the COVISE-sided part of the simulation coupling. When using interactive simulations, the module has to start the simulation code, for control visualization the module has to connect and authenticate to a running simulation. In both cases a network connection has to be created for control and data flow between the simulation and COVISE.

Simulation start-up

The simulation start-up is highly dependent on the circumstances in which the simulation takes place. To ensure sufficient flexibility for the module programmer as well as for the module user, the start-up procedure can be configured in the covise.config file. The following lines show an excerpt from covise.config.

MiniSim
{
   STARTUP SGI    CO_SIMLIB_CONN=%e ; export CO_SIMLIB_CONN; cd %0; ./miniSim
   STARTUP MANUAL echo "set CO_SIMLIB_CONN=%e and start MiniSim"
   PORTS    31000-31999
   SERVER   Module
   TIMEOUT  90
   VERBOSE  1
}

For each simulation coupling module, a section with the name of the module executable is searched. This section must include at least one STARTUP line, since no default start-up can be defined. The first word after STARTUP defines a label, the rest is executed by a shell in the active directory where COVISE was started in. If the module is started on a remote host, it is executed in the directory the user enters on login, usually the home directory. It has to define an (exported) environment variable CO_SIMLIB_CONN in the shell and then start the simulation job itself. The following variables can be used in the STARTUP string:

%%        the % character itself
%e        the value CO_SIMLIB_CONN has to be set to
%h        The host IP of the simulation host in "1.2.3.4" fashion (user-defined)
%0 ... %9 User-definable strings

Every SimLib module automatically creates a choice parameter for selecting the startup line from the possibilities given in the config file.

Examples:

STARTUP LOCAL  CO_SIMLIB_CONN=%e ; export CO_SIMLIB_CONN; cd %0; ./miniSim

If the user chooses "LOCAL" on the startup method choice, the environment variable is set, then changes to the module-defined directory (possibly from a string parameter of the module) and starts the program `miniSim'.

STARTUP REMOTE xterm -geometry 135x35 -e rsh -l %0 %h 'cd %1;
                        export CO_SIMLIB_CONN=%s; echo y | star' &

All other parameters in the file are optional:

   PORTS    <minPort>-<maxPort>

   SERVER   Module|Client

   TIMEOUT  90

   VERBOSE  1

   LOCAL  <local machine name>

The start-up is triggered by the startupSim() command:

If the user arguments (%0 ... %9) are used in the covise.config START line, they have to be set before the startupSim() command is called.

Status request

All coSimLib commands check for errors, which are usually reported by returning (-1) as result. For further checking, the internal status variable can be accessed:

Setting start-up parameters

Both the local and target host IP addresses can be set explicitly. As a default, the local interface to be used is set to the value of the LOCAL variable if given, otherwise the host's default interface is used.

Both functions call the nameserver if the host is not given in dot notation and check whether the requested host name exists. If the name is given in dot notation, no nameserver lookup or host existence testing is performed.

The user arguments %0 ... %9 must be set explicitly before starting the simulation. This allows simulation specific parameters, e.g. starting directory or startup parameters, to be set.

Starting the Server mode

Whenever this command is called, the module waits for the simulation to send client commands until a `finish' command is sent. This may only be done from the compute callback.

Parameter requests are also handled outside of the server mode, but data creation is only allowed when the simulation server module is in the compute() callback and in server mode.

Requesting and setting verbose mode

The verbose level can be set and requested by the user. It is recommended to request the verbose mode when creating own debug output in simulation coupling modules.

Simulation Client Commands

Start-up the connection with COVISE

This command checks the environment for the variable CO_SIMLIB_CONN, analyses it and tries to open a connection with the COVISE module. Depending on the setting in the covise.config file, this can be either a client or a server connection on any port in the specified direction. The command tries to open the connection for the period specified in the configuration file and returns with an error message if the connection was not established.

Check whether COVISE is connected

This call checks whether the connection to COVISE is still active. It does not check, whether the module is able to handle data now or whether it is busy.

Retrieving parameter values

All parameter calls can be submitted both in the compute and main-loop state of the COVISE coupling module. One should be aware that only immediate mode parameters are updated at the module immediately while non-immediate parameters are only updated before entering the compute() callback.

All parameter requests have the parameter name as input and the requested parameter(s) as output. Returned is an error code: 0 for proper function, -1, if the parameter is not yet available, -2 for an unknown parameter name.

Not all parameter types are currently implemented in the simulation library.

Creating data objects

Currently only the creation of unstructured scalar and vector data fields (coDoFloat and coDoFloat) is supported.

Other types will be implemented in the future, especially for sending unstructured grids and structured data sets.

Handling data on parallel machines

Parallelization of simulations is usually done by domain decomposition: parts of the grid are decomposed to several processors. For these kinds of simulations, only one node is connected to COVISE and has to perform the data and parameter propagation.

Initialisation

The simulation library supports distributed data by supplying a set of additional calls, which prepare and perform the gathering operations. Therefore, two different index mappings can be defined for both cell indices and vertex indices. To set these tables, all nodes send their local-to-global mapping field (array size of local data size, containing global data indices).

There can be two different tables for mapping local fields into global fields: a cell map and a vertex map. For every node, the cell map gives for each local cell the cell numbers in the global field. Accordingly, the vertex table gives the global coordinate index for every local coordinate.

Data creation

Data is created by telling the COVISE server, which node sends, and then using the standard data object creation calls, which automatically gather the data according to the mapping set during the initialization.

Previous

Next