libSim - VisIt's in-situ library

libSim Integration

Initialization

• tell libsim whether the simulation is parallel
  • VisItSetMPICommunicator
  • VisItSetParallel
  • VisItSetParallelRank

• dump trace of visit function calls for better debugging
  • VisItOpenTraceFile

• set visits binary directory
  • VisItSetDirectory

• parse command line arguments to visit
  • VisItSetOptions

• prepare visit enviroment for loading plugins
  • VisItSetupEnv

• initialize libsim library and write .sim2 file to visit_simpath
  • VisItInitializeSim (only rank 0)

Check Status and Process Commands

• update time and plots if nessessary
  • VisItTimestepChanged
  • VisItUpdatePlots

• detect input from proc 0 and broadcast that input to all others
  • status = VisItDetectInputWithTimeout
    • status < 0: error -> cleanup/disconnect
    • status == 0: no new input -> nothing to do
    • status == 1: trying to connect -> open connection
      • conn = VisItAttemptConnection
        • conn == VISIT_OKAY: connected and listening
        • conn == VISIT_ERROR: connecting failed
    • status == 2: new commands for VisIt engine -> process commands

Process Commands

• get commands from visit client and broadcast them
  • if rank==0:
    • VisItProcessEngineCommand (calls visitSlaveProcessCallback)
    • MPI_BCAST
  • if rank != 0
    • MPI_BCAST
    • VisItProcessEngineCommand

VisItSetBroadcastIntFunction

This function installs a callback function that allows libsim to broadcast an integer from the root process to slave processes.

Prototype

void  VisItSetBroadcastIntFunction(int (*)(int *, int));

Arguments

A pointer to a callback function with prototype: int func(int *, int);

Returns

None

Note

All processors must call this function and install a callback function after initializing MPI. The callback function must be installed prior to VisItDetectInput.
Sample callback function:

static int visit_broadcast_int_callback(int *value, int sender)
{
    return MPI_Bcast(value, 1, MPI_INT, sender, MPI_COMM_WORLD);
}

Source

​doxygen

VisItSetBroadcastStringFunction

This function installs a callback function that allows libsim to broadcast a character string from the root process to slave processes.

Prototype

void  VisItSetBroadcastStringFunction(int (*)(char *, int, int));

Arguments

A pointer to a callback function with prototype: int func(char *, int, int);

Returns

None

Note

All processors must call this function and install a callback function after initializing MPI. The callback function must be installed prior to VisItDetectInput.
Sample callback function:

static int visit_broadcast_string_callback(char *str, int len, int sender)
{
    return MPI_Bcast(str, len, MPI_CHAR, sender, MPI_COMM_WORLD);
}

Source

​doxygen

VisItSetParallel

Set whether or not libsim will be operating in parallel.

Prototype

void  VisItSetParallel(int);

Arguments

flag : Pass a non-zero value to indicate parallel; 0 for serial operation.

Returns

None

Note

All processors must call this function. Only parallel simulations need to call this function.

Source

​doxygen

VisItSetParallelRank

Set the rank of the current process within its MPI communicator.

Prototype

void  VisItSetParallelRank(int);

Arguments

rank : The MPI rank of the process.

Returns

None

Note

All processors must call this function. Only parallel simulations need to call this function.

Source

​doxygen

VisItSetDirectory

Set the path to the top level directory where VisIt is installed. This lets libsim load runtime libraries from a specific version of VisIt. If you never call this function, libsim will obtain VisIt runtime information using the visit script in your path. If that is the case, the latest runtime libraries will be used but it may not match the version of the client that is trying to connect to VisIt. Version mismatches are avoided (but not eliminated) by only using installed versions of VisIt to connect to a simulation.

Prototype

void  VisItSetDirectory(char *);

Arguments

path : The path to the top level VisIt directory. This does not include the "bin/visit" part of the path; just "/path/to/visitdir".

Returns

None

Note

All processors must call this function. This function must be called before VisItSetupEnvironment.

Source

​doxygen

VisItSetOptions

Pass command line arguments that will be used when calling out to VisIt to determine the runtime libraries that libsim will need to load when VisIt connects. You can use this function to pass arguments such as "-forceversion 1.12.0" to force a specific version of VisIt.

Prototype

void  VisItSetOptions(char *);

Arguments

args : A null-terminated string containing additional arguments will be passed to VisIt when determining the runtime libraries that need to be loaded when VisIt connects to the simulation.

Returns

None

Note

All processors must call this function. This function must be called before VisItSetupEnvironment.

Source

​doxygen

VisItGetEnvironment

Try to determine the environment variables that the VisIt Engine needs to run and return a string containing those values. The VisIt script can tell us this.

Prototype

char *VisItGetEnvironment(void)

Arguments

None

Returns

environment variables required to run VisIt Engine

Note

Source

​doxygen

VisItSetupEnvironment

Sets up the environment so VisIt can be loaded into libsim when the VisIt client wants to connect.

Prototype

int   VisItSetupEnvironment(void);

Arguments

None

Returns

None

Note

All processors must call this function and they must call it before VisItInitializeSocketAndDumpSimFile and VisItDetectInput.
Calls !VisItSetupEnvironment2(null).

Source

​doxygen

!VisItSetupEnvironment2

Sets up the environment so VisIt can be loaded into libsim when the VisIt client wants to connect.

Prototype

int   VisItSetupEnvironment2(char *env);

Arguments

environment variables

Returns

None

Note

Same as VisItSetupEnvironment, but without possibility to set new environment variables.

Source

​doxygen

VisItInitializeSocketAndDumpSimFile

This function makes the simulation start listening for inbound VisIt socket connections and it writes a .sim2 file that tells VisIt how to connect to the simulation.

Prototype

int   VisItInitializeSocketAndDumpSimFile(const char *name,
                                          const char *comment,
                                          const char *path,
                                          const char *inputfile,
                                          const char *guifile,
                                          const char *absoluteFilename);

Arguments

name : The name of the simulation, which will be used in the created filename.
comment : A comment describing the simulation.
path : The path where the simulation was started.
inputfile : reserved, pass NULL
guifile : reserved, pass NULL
absoluteFilename : reserved, pass NULL

Returns

1 on success, 0 on failure

Note

Only the root processor should call this function. This function should be called early on and before the calls to VisItDetectInput.

Source

​doxygen

VisItDetectInput

Simulations call this function to detect input from the listen socket, client socket, or console. Call this function in a loop to form the main event loop for a simulation.

Prototype

int   VisItDetectInput(int blocking, int consoledesc);

Arguments

blocking : Pass a non-zero value to tell the function to wait until there is input before returning. If you want to run the simulation without waiting for input, you will want to pass 0 so the function times out and returns whether or not there is input to be handled.
consoledesc : If you want to handle input from another file in addition to the VisIt sockets, pass a file descriptor for the file that you want to monitor. If you want to monitor the console for typed commands, pass fileno(stdin). If you do not want to monitor other files, pass -1 for the descriptor.

Returns

-5 Logic error (fell through all cases)
-4 Logic error (no descriptors but blocking)
-3 Logic error (a socket was selected but not one we set)
-2 Unknown error in select
-1 Interrupted by EINTR in select
0 Okay - Timed out
1 Listen socket input
2 Engine socket input
3 Console socket input

Note

This function should only be called by the root process in parallel. The results of this function should be broadcast to other processors so that all may follow the same general call pattern.

What to do with a return value:
0 The function timed out; execute a time step.
1 An inbound VisIt connection is being made. Call the VisItAttemptToCompleteConnection function.
2 The VisIt viewer sent instructions to the simulation so call the VisItProcessEngineCommand function.
3 Console input was detected so read stdin and handle it.
other error out, stop calling VisItDetectInput.

Source

​doxygen

VisItAttemptToCompleteConnection

Accept the inbound VisIt connection socket, verify security keys, get the connection parameters from the client, load the VisIt engine library, create the Engine and connect back to the VisIt viewer.

Prototype

int   VisItAttemptToCompleteConnection(void);

Arguments

None

Returns

1 on success; 0 on failure

Note

This function should be called when VisItDetectInput returns 1.

Source

​doxygen

VisItSetSlaveProcessCallback

Set the callback function used to inform slave processes that they should call VisItProcessEngineCommand. The provided callback function is used internally in libsim.

Prototype

void  VisItSetSlaveProcessCallback(void(*)(void));

Arguments

A pointer to a function with prototype: void func(void);

Returns

None

Note

The slave process callback is required for a parallel simulation. This function should be called when VisItAttemptToCompleteConnection returns successfully.

MPI simulations may define the callback like this:

void slave_process_callback()
{
    int command = 0;
    MPI_BCast(&command, 1, MPI_INT, 0, MPI_COMM_WORLD);
}

Source

​doxygen

VisItSetCommandCallback

Set the callback for processing control commands (these are set up in the simulation's metadata).

Prototype

void  VisItSetCommandCallback(void(*)(const char*,int,float,const char*));

Arguments

A pointer to a function with prototype: void func(const char*,int,float,const char*);
The callback arguments are:
cmd The name of the command being called.
idata int data (reserved)
fdata float data (reserved)
sdata string argument (reserved)

Returns

None

Note

This function must be called on all processors to install the callback function. This function should be called when VisItAttemptToCompleteConnection returns successfully.

Source

​doxygen

VisItProcessEngineCommand

This function reads input from VisIt's viewer and executes the requests. The VisItProcessEngineCommand function needs to be called from the simulation's event loop when VisItDetectInput return 2, indicating that there is input to be processed.

Prototype

int   VisItProcessEngineCommand(void);

Arguments

None

Returns

1 on success
0 on failure.

Note

All processors must call this function.

Source

​doxygen

VisItTimeStepChanged

The simulation can use this function to tell VisIt that it has changed to a new time step. This causes the simulation to send new metadata to VisIt.

Prototype

void  VisItTimeStepChanged(void);

Arguments

None

Returns

None

Note

All processors must call this function.

Source

​doxygen

VisItUpdatePlots

The simulation can use this function to tell VisIt to update its plots using new data from the simulation. Calling this function only serves as a trigger to VisIt that it needs to update its plots. The simulation should take care to pause until VisIt has made all of its requests from the simulation or multiple plots may contain data from different time steps if the simulation has kept running.

Prototype

void  VisItUpdatePlots(void);

Arguments

None

Returns

None

Note

All processors must call this function.

Source

​doxygen

VisItExecuteCommand

This simulation can use this function to tell VisIt to execute VisIt CLI Python commands. The commands are sent to VisIt in a non-blocking fashion and VisIt later translates the commands into requests to the simulation.

Prototype

void  VisItExecuteCommand(const char *);

Arguments

A null-terminated character string containing the commands to be executed.

Returns

None

Note

Only the root processor should call this function.
And example call to this function could look like:

VisItExecuteCommand("AddPlot(\"Pseudocolor\", \"zonal\")\n");

Source

​doxygen

VisItDisconnect

This function disconnects the simulation from VisIt. It should be called from the simulation's event loop when VisItProcessEngineCommand returns failure.

Prototype

void  VisItDisconnect(void);

Arguments

None

Returns

None

Note

All processors must call this function.

Source

​doxygen

VisItConnected

Returns whether VisIt is connected.

Prototype

int VisItIsConnected(void)

Arguments

None

Returns

Note

Source

​doxygen

VisItSaveWindow

Tell VisIt to save the active network as an image.

Prototype

int VisItSaveWindow(const char *filename, int w, int h, int format)

Arguments

filename output file name
w windowid
h handler
format file format

Returns

Note

Source

​doxygen

VisItGetLastError

This function returns a pointer to a character string that contains the last error that libsim encountered.

Prototype

char *VisItGetLastError(void);

Arguments

None

Returns

A null-terminated character string that contains the last error.

Note

Source

​doxygen

VisItOpenTraceFile

Opens the trace file that libsim will use.

Prototype

void VisItOpenTraceFile(const char *filename)

Arguments

filename trace file

Returns

None

Note

Source

​doxygen

VisItCloseTraceFile

Closes the trace file that libsim will use.

Prototype

void VisItOpenTraceFile(void)

Arguments

None

Returns

None

Note

Source

​doxygen

VisItSynchronize

Sends a synchronize message to VisIt if we're connected to VisIt and spawns a sub-eventloop to wait for the sync message to be returned from VisIt. This permits us to write code in the sim that blocks until it's done and still processes events from VisIt needed to get us to the point where the message gets read.

Prototype

     int VisItSynchronize(void);

Arguments

None

Returns

Note

This function has not been tried for sims that use polling.

Source

​doxygen

VisItEnableSynchronize

This method lets us turn off automatic synchronization for functions that communicate with VisIt's viewer.

Prototype

    void VisItEnableSynchronize(int mode);

Arguments

enable == 1; disable == 0

Returns

None

Note

Source

​doxygen

VisItDebug[1-5]

Function to write to the VisIt debug logs.

Prototype

    void VisItDebug1(const char *format, ...);
    void VisItDebug2(const char *format, ...);
    void VisItDebug3(const char *format, ...);
    void VisItDebug4(const char *format, ...);
    void VisItDebug5(const char *format, ...);

Arguments

Returns

Note

Source

​doxygen

VisItSetMPICommunicator

Let the user set the MPI communicator that VisIt will use.

Prototype

    int VisItSetMPICommunicator(void *comm);

Arguments

MPI communicator

Returns

1 on success, 0 on failure

Note

Source

​doxygen

VisItInitializeRuntime

Source

​doxygen

VisItGetMemory

Source

​doxygen

!VisItUI_clicked

Source

​doxygen

!VisItUI_stateChanged

Source

​doxygen

!VisItUI_valueChanged

Source

​doxygen

!VisItUI_setValueI

Source

​doxygen

!VisItUI_setValueS

Source

​doxygen

VisItAddPlot

Source

​doxygen

VisItAddOperator

Source

​doxygen

VisItDrawPlots

Source

​doxygen

VisItDeleteActivePlots

Source

​doxygen

VisItSetActivePlots

Source

​doxygen

VisItSetPlotOptions

Source

​doxygen

VisItSetOperatorOptions

Source

​doxygen

VisItExportDatabase

Source

​doxygen

VisItRestoreSession

Source

​doxygen

---

any feedback welcomed - h.zilken@…, j.goebbert@…