Difference between revisions of "Libsim High Level API"

(Libsim High Level API)
 
Line 11: Line 11:
 
int VisItLibsimFinalize(libsim_state *ss);
 
int VisItLibsimFinalize(libsim_state *ss);
 
</source>
 
</source>
The Initialize function loads the VisIt runtime and installs data and control callbacks that update and get data from the simulation. The first argument is a point to an MPI_Comm structure for VisIt to use for internal communications, or NULL if this is a serial run. The second and thirds arguments are the command line. This allows Libsim to handle the runtime configuration common to all simulations such as selecting the runtime mode, and the parallel loading Python scripts and session files for visualization. The third argument is a callback structure that holds user provided data API callbacks that VisIt uses to access simulation data. The fourth argument is an optional structure containing a collection of VisIt Python scripts. The function returns a state object that is passed into subsequent Libsim HL API calls.
+
The '''''VisItLibsimInitialize''''' function loads the VisIt runtime and installs data and control callbacks that update and get data from the simulation. The first argument, ''pcomm'',  is a pointer to an MPI_Comm structure that Libsim and VisIt will subsequently duplicate and use for internal communications, or ''NULL'' if this is a serial run. The second and thirds arguments, ''argc'' and ''argv'', are the command line length and arguments. By processing thye command line Libsim handles the runtime configuration common to all simulations such as selecting the mode, the parallel loading Python scripts, VisIt engine configuration, and debug logging. The third argument, ''callbacks'',  is a callback structure that holds user provided data API callbacks that VisIt uses to access simulation data. The fourth argument, ''scripts'', is an optional structure containing a collection of VisIt Python scripts that can be used for visualization during the run. The function returns a state object that is passed into subsequent Libsim HL API calls. If there is an error, or --help was passed on the command line, a ''NULL'' is returned.
 +
 
 +
The '''''VisItLibsimExecute''''' function starts the run. Libsim will invoke the callbacks to request data from the simulation and to pass control to the simulation during each iteration.
 +
 
 +
The '''''VisItLibsimFinalize''''' function frees up resources used by libsim, including the state object returned by ''VisItLibsimInitialize''.
  
 
== Callbacks ==
 
== Callbacks ==
Line 32: Line 36:
 
| row 2, cell 3
 
| row 2, cell 3
 
|}
 
|}
 
 
 
  
 
= Original V2 API =
 
= Original V2 API =

Latest revision as of 17:38, 21 November 2016

Libsim High Level API

The high level API was added to handle the most common scenarios, reducing code duplication, and easing integration into user's simulations. Libsim HL supports batch and interactive mode. In batch mode either VisIt session file and/or VisIt Python scripts run to produce visualizations. In interactive mode the GUI connects and is used to control both simulation and visualization.

Instrumenting a simulation via Libsim HL API requires 3 functions that need to be added to the user's code:

libsim_state *VisItLibsimInitialize(void *pcomm, int argc, char **argv,                                                                       
     libsim_callbacks *callbacks, libsim_script_library *scripts);

int VisItLibsimExecute(libsim_state *ss);

int VisItLibsimFinalize(libsim_state *ss);

The VisItLibsimInitialize function loads the VisIt runtime and installs data and control callbacks that update and get data from the simulation. The first argument, pcomm, is a pointer to an MPI_Comm structure that Libsim and VisIt will subsequently duplicate and use for internal communications, or NULL if this is a serial run. The second and thirds arguments, argc and argv, are the command line length and arguments. By processing thye command line Libsim handles the runtime configuration common to all simulations such as selecting the mode, the parallel loading Python scripts, VisIt engine configuration, and debug logging. The third argument, callbacks, is a callback structure that holds user provided data API callbacks that VisIt uses to access simulation data. The fourth argument, scripts, is an optional structure containing a collection of VisIt Python scripts that can be used for visualization during the run. The function returns a state object that is passed into subsequent Libsim HL API calls. If there is an error, or --help was passed on the command line, a NULL is returned.

The VisItLibsimExecute function starts the run. Libsim will invoke the callbacks to request data from the simulation and to pass control to the simulation during each iteration.

The VisItLibsimFinalize function frees up resources used by libsim, including the state object returned by VisItLibsimInitialize.

Callbacks

Libsim interfaces to a simulation code via a set of callbacks. The callbacks are broken into two categories, control and data. The control callbacks let libsim pass control to the simulation, and let the simulation signal that it's finished running.

Control Callbacks

Header 1 Header 2 Header 3
row 1, cell 1 row 1, cell 2 row 1, cell 3
row 2, cell 1 row 2, cell 2 row 2, cell 3

Original V2 API