Simulation Control Interface

VisIt provides a library called libsim that lets you instrument a simulation so VisIt can connect to it and plot data as the simulation runs. Libsim consists of 2 pieces: the control library and the data access callback functions. The control library is a small C library that provides functions for instrumenting the simulation so it listens to VisIt connections and plot requests. When VisIt connects to the simulation, libsim automatically imports VisIt libraries needed for the simulation to process VisIt's requests. The simulation provides data access callback functions that expose the simulation's data to VisIt. It is also possible to link the control library, runtime library and the rest of VisIt's compute libraries into your simulation statically.

This page describes the C-language control interface for libsim at the function level. The Fortran version of the control interface has slightly different function names and calling conventions but the usage is the same as in C.

V1 control functions

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); }

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); }

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.

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.

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.

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.

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.

VisItInitializeSocketAndDumpSimFile

This function makes the simulation start listening for inbound VisIt socket connections and it writes a .sim1 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.

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.

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.

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); }

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.

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
Returns	None 1 on success; 0 on failure.
Note	All processors must call this function.

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.

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.

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	And example call to this function could look like: VisItExecuteCommand("AddPlot(\"Pseudocolor\", \"zonal\")\n"); Only the root processor should call this function.

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.

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

V2 control functions

These new functions appear in SimV2.

• int VisItSynchronize(void);
• void VisItEnableSynchronize(int);
• void VisItDebug1(const char *format, ...); through void VisItDebug5(const char *format, ...);
• void VisItOpenTraceFile(const char *filename);
• void VisItCloseTraceFile(void);
• void VisItSaveWindow(const char *filename, int width, int height, int format);