Version 4 (modified by 9 years ago) ( diff ) | ,
---|
libSim - VisIt's in-situ library
-
-
libSim - VisIt's in-situ library
- Functions
- VisItSetBroadcastIntFunction
- VisItSetBroadcastStringFunction
- VisItSetParallel
- VisItSetParallelRank
- VisItSetDirectory
- VisItSetOptions
- VisItSetupEnvironment
- VisItInitializeSocketAndDumpSimFile
- VisItDetectInput
- VisItAttemptToCompleteConnection
- VisItSetSlaveProcessCallback
- VisItSetCommandCallback
- VisItProcessEngineCommand
- VisItTimeStepChanged
- VisItUpdatePlots
- VisItExecuteCommand
- VisItDisconnect
- VisItGetLastError
- VisItSynchronize
- VisItEnableSynchronize
- !VisItDebug1
- VisItOpenTraceFile
- VisItCloseTraceFile
- VisItSaveWindow
-
libSim - VisIt's in-situ library
Functions
C-Interface: https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c.html
Fortran-Interface: https://fossies.org/dox/visit2.9.2/visitfortransimV2interface_8c.html
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); }
- Source
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
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
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
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
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.
- Source
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.
- Source
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
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); }
- Source
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
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.
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
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
- Only the root processor should call this function.
And example call to this function could look like:VisItExecuteCommand("AddPlot(\"Pseudocolor\", \"zonal\")\n");
- Source
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
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
VisItSynchronize
- Prototype
-
int VisItSynchronize(void);
- Arguments
- Returns
- Note
VisItEnableSynchronize
- Prototype
-
void VisItEnableSynchronize(int);
- Arguments
- Returns
- Note
- Source
!VisItDebug1
- Prototype
-
void VisItDebug1(const char *format, ...); through void VisItDebug5(const char *format, ...);
- Arguments
- Returns
- Note
- Source
VisItOpenTraceFile
- Prototype
-
void VisItOpenTraceFile(const char *filename);
- Arguments
- Returns
- Note
- Source
VisItCloseTraceFile
- Prototype
-
void VisItCloseTraceFile(void);
- Arguments
- Returns
- Note
- Source
VisItSaveWindow
- Prototype
-
void VisItSaveWindow(const char *filename, int width, int height, int format);
- Arguments
- Returns
- Note
- Source
any feedback welcomed - h.zilken@…, goebbert@…