== libSim - !VisIt's in-situ library [[PageOutline]] === libSim Integration ==== Initialization * tell libsim whether the simulation is parallel * [#VisItSetMPICommunicator VisItSetMPICommunicator] * [#VisItSetParallel VisItSetParallel] * [#VisItSetParallelRank VisItSetParallelRank] * dump trace of visit function calls for better debugging * [#VisItOpenTraceFile VisItOpenTraceFile] * set visits binary directory * [#VisItSetDirectory VisItSetDirectory] * parse command line arguments to visit * [#VisItSetOptions VisItSetOptions] * prepare visit enviroment for loading plugins * [#VisItSetupEnv VisItSetupEnv] * initialize libsim library and write .sim2 file to visit_simpath * [#VisItInitializeSim VisItInitializeSim] (only rank 0) ==== Check Status and Process Commands * update time and plots if nessessary * [#VisItTimestepChanged VisItTimestepChanged] * [#VisItUpdatePlots VisItUpdatePlots] * detect input from proc 0 and broadcast that input to all others * status = [#VisItDetectInputWithTimeout VisItDetectInputWithTimeout] * status < 0: error -> cleanup/disconnect * status == 0: no new input -> nothing to do * status == 1: trying to connect -> open connection * conn = [#VisItAttemptConnection 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 VisItProcessEngineCommand] (calls visitSlaveProcessCallback) * MPI_BCAST * if rank != 0 * MPI_BCAST * [#VisItProcessEngineCommand VisItProcessEngineCommand] \\ === !VisItSetBroadcastIntFunction This function installs a callback function that allows libsim to broadcast an integer from the root process to slave processes. Prototype:: {{{ #!C++ 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: {{{ #!C++ static int visit_broadcast_int_callback(int *value, int sender) { return MPI_Bcast(value, 1, MPI_INT, sender, MPI_COMM_WORLD); } }}} Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l01965 doxygen] \\ === !VisItSetBroadcastStringFunction This function installs a callback function that allows libsim to broadcast a character string from the root process to slave processes. Prototype:: {{{ #!C++ 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: {{{ #!C++ static int visit_broadcast_string_callback(char *str, int len, int sender) { return MPI_Bcast(str, len, MPI_CHAR, sender, MPI_COMM_WORLD); } }}} Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02003 doxygen] \\ === !VisItSetParallel Set whether or not libsim will be operating in parallel. Prototype:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02041 doxygen] \\ === !VisItSetParallelRank Set the rank of the current process within its MPI communicator. Prototype:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02073 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:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02081 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:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02118 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:: {{{ #!C++ char *VisItGetEnvironment(void) }}} Arguments:: None Returns:: environment variables required to run !VisIt Engine Note:: Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02151 doxygen] \\ === !VisItSetupEnvironment Sets up the environment so !VisIt can be loaded into libsim when the !VisIt client wants to connect. Prototype:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02213 doxygen] \\ === !VisItSetupEnvironment2 Sets up the environment so !VisIt can be loaded into libsim when the !VisIt client wants to connect. Prototype:: {{{ #!C++ int VisItSetupEnvironment2(char *env); }}} Arguments:: environment variables Returns:: None Note:: Same as VisItSetupEnvironment, but without possibility to set new environment variables. Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02247 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:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02370 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:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l02469 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:: {{{ #!C++ int VisItAttemptToCompleteConnection(void); }}} Arguments:: None Returns:: '''1''' on success; '''0''' on failure Note:: This function should be called when !VisItDetectInput returns 1. Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03071 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:: {{{ #!C++ 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: {{{ #!C++ void slave_process_callback() { int command = 0; MPI_BCast(&command, 1, MPI_INT, 0, MPI_COMM_WORLD); } }}} Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03179 doxygen] \\ === !VisItSetCommandCallback Set the callback for processing control commands (these are set up in the simulation's metadata). Prototype:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03246 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:: {{{ #!C++ int VisItProcessEngineCommand(void); }}} Arguments:: None Returns:: '''1''' on success \\ '''0''' on failure. Note:: All processors must call this function. Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03271 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:: {{{ #!C++ void VisItTimeStepChanged(void); }}} Arguments:: None Returns:: None Note:: All processors must call this function. Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03324 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:: {{{ #!C++ void VisItUpdatePlots(void); }}} Arguments:: None Returns:: None Note:: All processors must call this function. Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03349 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:: {{{ #!C++ 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: {{{ #!C++ VisItExecuteCommand("AddPlot(\"Pseudocolor\", \"zonal\")\n"); }}} Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03378 doxygen] \\ === !VisItDisconnect This function disconnects the simulation from !VisIt. It should be called from the simulation's event loop when !VisItProcessEngineCommand returns failure. Prototype:: {{{ #!C++ void VisItDisconnect(void); }}} Arguments:: None Returns:: None Note:: All processors must call this function. Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03417 doxygen] \\ === !VisItConnected Returns whether VisIt is connected. Prototype:: {{{ #!C++ int VisItIsConnected(void) }}} Arguments:: None Returns:: Note:: Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03459 doxygen] \\ === !VisItSaveWindow Tell VisIt to save the active network as an image. Prototype:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03477 doxygen] \\ === !VisItGetLastError This function returns a pointer to a character string that contains the last error that libsim encountered. Prototype:: {{{ #!C++ char *VisItGetLastError(void); }}} Arguments:: None Returns:: A null-terminated character string that contains the last error. Note:: Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03505 doxygen] \\ === !VisItOpenTraceFile Opens the trace file that libsim will use. Prototype:: {{{ #!C++ void VisItOpenTraceFile(const char *filename) }}} Arguments:: '''filename''' trace file Returns:: None Note:: Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03529 doxygen] \\ === !VisItCloseTraceFile Closes the trace file that libsim will use. Prototype:: {{{ #!C++ void VisItOpenTraceFile(void) }}} Arguments:: None Returns:: None Note:: Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03549 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:: {{{ #!C++ int VisItSynchronize(void); }}} Arguments:: None Returns:: Note:: This function has not been tried for sims that use polling. Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03601 doxygen] \\ === !VisItEnableSynchronize This method lets us turn off automatic synchronization for functions that communicate with VisIt's viewer. Prototype:: {{{ #!C++ void VisItEnableSynchronize(int mode); }}} Arguments:: enable == 1; disable == 0 Returns:: None Note:: Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03715 doxygen] \\ === !VisItDebug[1-5] Function to write to the VisIt debug logs. Prototype:: {{{ #!C++ 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:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03735 doxygen] === VisItSetMPICommunicator Let the user set the MPI communicator that !VisIt will use. Prototype:: {{{ #!C++ int VisItSetMPICommunicator(void *comm); }}} Arguments:: MPI communicator Returns:: 1 on success, 0 on failure Note:: Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03768 doxygen] === !VisItInitializeRuntime Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03793 doxygen] \\ === !VisItGetMemory Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03812 doxygen] \\ === !VisItUI_clicked Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03873 doxygen] \\ === !VisItUI_stateChanged Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03895 doxygen] \\ === !VisItUI_valueChanged Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03911 doxygen] \\ === !VisItUI_setValueI Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03928 doxygen] \\ === !VisItUI_setValueS Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03946 doxygen] \\ === !VisItAddPlot Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l03968 doxygen] \\ === !VisItAddOperator Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l04012 doxygen] \\ === !VisItDrawPlots Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l04048 doxygen] \\ === !VisItDeleteActivePlots Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l04076 doxygen] \\ === !VisItSetActivePlots Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l04104 doxygen] \\ === !VisItSetPlotOptions Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l04132 doxygen] \\ === !VisItSetOperatorOptions Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l04177 doxygen] \\ === !VisItExportDatabase Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l04221 doxygen] \\ === !VisItRestoreSession Source:: [https://fossies.org/dox/visit2.9.2/VisItControlInterface__V2_8c_source.html#l04252 doxygen] \\ ---- any feedback welcomed - [mailto:h.zilken@fz.juelich.de], [mailto:j.goebbert@fz-juelich.de]