dynamic_visualization_store_api.h File Reference

Function pointer for logging methods.

void* param is for data to be sent back to logging method, might be NULL

Definition at line 143 of file dynamic_visualization_store_api.h.

Add metadata for the current dataset.

Errors:

• DVS_NONE: Success
• DVS_PARAM_NULL: Method called with NULL params or num_metadata_pairs == 0
• DVS_CLIENT_INVALID_TRANSPORT: Internal error, should not happen
• DVS_TRANSPORT_NULL_INVALID_SERVER: Internal error, should not happen
• DVS_VERSION_MISMATCH: Client version out of date with server version, update server and client to match
• DVS_VERSION_UNKNOWN: Unable to determine server version, update the server to match the client
• DVS_TRANSPORT_SERVICE_FAILURE: Normally caused by server call retry time out or invalid secret key

Parameters

session_id	id for session created by dvs_connect()
metadata_keys	string array of UTF-8 Compatible string keys, each string should be null terminated
metadata_vals	string array of UTF-8 Compatible string values, each string should be null terminated
num_metadata_pairs	number of key/value pairs in the arrays

Returns

dvs_ret DVS_NONE on success, otherwise see method description

Add part info for simulation.

Note: These cannot be changed once dvs_end_init() is called

Parameters

	session_id	id for session created by dvs_connect()
[in]	parts	this solver handles
	num_parts	size of parts array, maximum number of parts (2^30)

Returns

dvs_ret TODO

Add plot info for simulation.

NOTE: These cannot be changed once end_init() is called.

Parameters

	session_id	id for session created by dvs_connect()
[in]	plots	plots this solver handles
	num_plots	size of plots array

Returns

dvs_ret TODO

Add var info for simulation.

Note: These cannot be changed once dvs_end_init() is called

Parameters

	session_id	id for session created by dvs_connect()
[in]	vars	variables definitions which will be sent from this compute node
	num_vars	size of var array

Returns

dvs_ret TODO

begin setup of rank

Parameters

session_id	id for session created by dvs_connect()
dataset_name	name for dataset
current_rank	Rank this solver is processing (zero based)
total_ranks	Total number of ranks across solver nodes
num_chunks	Number of chunks for this rank (usually 1)

Returns

dvs_ret TODO

Method to begin an update.

Parameters

session_id	id for session created by dvs_connect()
update_num	update number of this update, must be monotonically increasing
rank	the rank we are sending an update for (zero based)
chunk	the chunk number this update is for (zero based)
time	time in seconds this update is for

Returns

dvs_ret TODO

Connect to dvs server.

This call will connect to a server that has been created using dvs_server_create() If server is being created locally dvs_server_start() must be called before connecting.

Parameters

	server_id	id of server created by dvs_server_create()
	flags	flags for client setup see dvs_client_flags (dynamic_visualization_store_enums.h)
[in]	secret	shared secret to use for client, can be NULL
[out]	session_id	dynamic id created for connection, used for client dvs calls

Returns

0 on success, otherwise -1

Delete an item.

This call must be called by every rank similarly to how begin_update happens.

Currently this will only allow for timesteps to be deleted. In the future it can be expanded to all objects via the filter mechanism (see Query Stanzas). Currently this supports the operands of eq, gt, gte, lt, lte. Example: To delete all timesteps >= time 1.1 the filter would be "/timestep.time/gte/1.1//" .

It also currently only supports one statement so /timestep.time/gt/1.1//and/timestep.time/lt/2.1// is not valid as of version 1.1.0.

Note: The update number should be monotonically increasing with the begin_update calls

Parameters

session_id	id for session created by dvs_connect()
update_num	update number of this update, must be monotonically increasing
rank	rank making this call
filter	filter for the item(s) to delete see detailed description for more info

Returns

dvs_ret TODO

end the initialization of the rank

This must be called to let server know initialization for this rank is complete

Parameters

session_id

id for session created by dvs_connect()

Returns

dvs_ret TODO

Call to end the update for this timestep/rank/chunk.

Parameters

session_id

id for session created by dvs_connect()

Returns

dvs_ret TODO

Get the number of dvs_part_info objects for this client session.

Note: This checks the local client session information, does not contact server

Parameters

session_id

which client session id to check

Returns

uint32_t number of dvs_part_info objects, or 0 on error

Get the number of dvs_plot_info objects for this client session.

Note: This checks the local client session information, does not contact server

Parameters

session_id

which client session id to check

Returns

uint32_t number of dvs_plot_info objects, or 0 on error

Get the number of dvs_var_info objects for this client session.

Note: This checks the local client session information, does not contact server

Parameters

session_id

which client session id to check

Returns

uint32_t number of dvs_var_info objects, or 0 on error

Get the ID being used by the client for the named part.

Errors: DVS_NONE: Success DVS_INVALID_NAME: No object with name found DVS_ID_NO_VALID_SESSION: No session found matching session_id DVS_ID_INVALID_TYPE: Session id is of wrong type (possibly server) DVS_PARAM_NULL: Null param passed in

Parameters

[in]	session_id	which client session id to check
[in]	name	the name of the part to search for
[out]	id	UINT32_MAX on failure, otherwise the id of the part for this client

Returns

DVS_NONE on success, else see method description

Get the dvs_part_info object for this index.

Note: This checks the local client session information, does not contact server

Parameters

session_id	which client session id to check
index	index of the dvs_part_info object to retrieve

Returns

const dvs_part_info* object found or NULL on not found or error

Get the ID being used by the client for the named plot.

Errors: DVS_NONE: Success DVS_INVALID_NAME: No object with name found DVS_ID_NO_VALID_SESSION: No session found matching session_id DVS_ID_INVALID_TYPE: Session id is of wrong type (possibly server) DVS_PARAM_NULL: Null param passed in

Parameters

[in]	session_id	which client session id to check
[in]	name	the name of the plot to search for
[out]	id	UINT32_MAX on failure, otherwise the id of the plot for this client

Returns

DVS_NONE on success, else see method description

Get the dvs_plot_info object for this index.

Note: This checks the local client session information, does not contact server

Parameters

session_id	which client session id to check
index	index of the dvs_plot_info object to retrieve

Returns

const dvs_plot_info* object found or NULL on not found or error

Get the ID being used by the client for the named var.

Errors: DVS_NONE: Success DVS_INVALID_NAME: No object with name found DVS_ID_NO_VALID_SESSION: No session found matching session_id DVS_ID_INVALID_TYPE: Session id is of wrong type (possibly server) DVS_PARAM_NULL: Null param passed in

Parameters

[in]	session_id	which client session id to check
[in]	name	the name of the var to search for
[out]	id	UINT32_MAX on failure, otherwise the id of the var for this client

Returns

DVS_NONE on success, else see method description

Get the dvs_var_info object for this index.

Note: This checks the local client session information, does not contact server

Parameters

session_id	which client session id to check
index	index of the dvs_var_info object to retrieve

Returns

const dvs_var_info* object found or NULL on not found or error

Get the current version of the built library.

This gets the current semantic version of the DVS library. Can be checked against DVS_CURRENT_API_VERSION in dynamic_visualization_store_version.h

This version follows semantic versioning of MAJOR.MINOR.PATCH. Any change to MAJOR or MINOR should be considered incompatible and the library should be updated.

Returns

const* the current version of the built library

This will be deprecated, just placeholder for printing out stats that the client is collecting for prototyping.

Parameters

session_id

id for session created by dvs_connect()

Register logging function for client to call (optional but recommended)

Will not see any logging messages if not registered

Parameters

session_id	id for session created by dvs_connect()
user_data	user data that will be passed into dvs_log_func calls
func	function pointer for logging (see dvs_log_func)
flags	which items to be logged, see dvs_log_flags (dynamic_visualization_store_enums.h)

Returns

dvs_ret TODO

Create a Dynamic Visualization Store server instance for the client to connect.

Parameters

	server_uri	URI of server to create of the format protocol://hostname:port, i.e. grpc://localhost:50055 or null:// see Server URIs for more info.
[out]	server_id	unique id dynamically created for this server, -1 if failure

Returns

0 on success, else TODO

Add an option to the server.

These options are used on server startup. Setting an option after a server is started will do nothing until the server is restarted (not common). See Server Options.

Parameters

	server_id	id of server from dvs_server_create()
[in]	key	Key for option to add, MAX LENGTH 2048
[in]	value	Value for option, MAX LENGTH 2048

Returns

0 on success, else TODO

Shutdown this server thread.

Parameters

server_id

id of server from dvs_server_create()

Returns

0 on success, else TODO

Start a Dynamic Visualization Store server in a separate thread to receive data from solver node.

server_number is used by the DVS server, for each group of servers this number should be unique and monotonically increasing with no gaps (valid: 0, 1, 2 invalid: 0, 2)

local_ranks is used to determine how many clients will be connecting to this server

Parameters

server_id	id of server from dvs_server_create()
server_number	The server number (zero based) for this server, should be unique for each server in this server group.
local_ranks	Number of local ranks this server will handle.

Returns

0 if server started, else TODO

Check to see if a server was started with this server_num.

Parameters

	server_id	id of server from dvs_server_create()
[out]	running	1 if running, else 0

Returns

0 on success, else TODO

Query a Dynamic Visualization Store server as to the number of timesteps it contains.

Parameters

	server_id	id of server from dvs_server_create()
[out]	num_pending	The number of incomplete timesteps currently in the server
[out]	num_complete	The number of complete timesteps currently in the server

Returns

0 on success, else TODO

Shutdown session.

Parameters

session_id

id for session created by dvs_connect()

Returns

dvs_ret TODO

Shutdown all connected sessions.

All previously returned session_id's from dvs_connect will be invalid once this call is made.

Set a unit system (optional but recommended)

Note: This cannot be changed once dvs_end_init() is called

Parameters

session_id	id for session created by dvs_connect()
system	UTF-8 compatible unit system see: https://nexusdemo.ensight.com/docs/python/html/ENS_UNITSSchema.html

Returns

dvs_ret TODO

Update elements for a specific part and element type.

This will update the elements for a part. The number of indices needed will vary depending on the type and the num_elements. I.E. if updating triangles with 3 elements the indices array should be of size 9 (3 triangles with 3 indices)

Parameters

session_id	id for session created by dvs_connect()
part_id	unique id of part to update elements for (must match parts added with dvs_add_part_info)
type	element type of elements to update (points, triangles, quads, etc.)
indices	node indices for each element, for ordering info per element type see EnSight's User Manual, section 9.2.3 Supported EnSight Gold Elements
num_indices	the size of the indices array

Returns

ret_val TODO

Update N-SIDED elements.

This method will send over a list of arbitrarily sized polygons. The nodes_per_polygon param is an array containing the size of each polygon. I.E. if sending a quadrangle, and a 25 sided element the nodes_per_polygon array might look like [4, 25]. The size of the indices array would be 4+25=29 in this example where the first 4 items in the indices array would correspond to the first item in the nodes_per_polygon array, the next 25 items in the indices array would correspond to the second item in the nodes_per_polygon array

Parameters

session_id	id for session created by dvs_connect()
part_id	unique id of part to update elements for (must match parts added with dvs_add_part_info)
type	element type of elements to update (N_SIDED_POLYGON or N_SIDED_POLYGON_GHOST)
nodes_per_polygon	Array containing number of nodes in each element/polygon
nodes_per_polygon_size	size of nodes_per_polygon array
indices	Array of node indices for the polygons described in nodes_per_polygon
indices_size	Size of indices array

Returns

dvs_ret TODO

Update N-FACED Elements.

Parameters

session_id	id for session created by dvs_connect()
part_id	unique id of part to update elements for (must match parts added with dvs_add_part_info)
type	element type of elements to update (CONVEX_POLYHEDRON or CONVEX_POLYHEDRON_GHOST)
faces_per_element	Array of how many faces are in each element
faces_per_element_size	size of faces_per_element array
nodes_per_face	Array of how many nodes each face contains
nodes_per_face_size	size of nodes_per_face array
indices	Node indices for elements
indices_size	size of node indices

Returns

dvs_ret TODO

Update nodes for a specific part.

Parameters

	session_id	id for session created by dvs_connect()
	part_id	the id of part we are updating nodes for
[in]	x	array of x components for nodes
[in]	y	array of y components for nodes
[in]	z	array of z components for nodes
	num_values	number of values in individual x/y/z arrays (max nodes in part 2^31)

Returns

dvs_ret TODO

Update the nodes for a curvilinear structured part.

A curvilinear structured part is represented by the global IJK grid across ranks, the local sub-block's IJK rank, and the actual XYZ values for each IJK grid point in the local grid.

Local IJK Dimensions: The min/max represent a local sub-block from the overall global grid. This could be the entire range if not splitting the grid into multiple ranks or a specific slice. For example you could have a 2ix3jx4k grid where it was split across the I dimension. One rank would specify min/max IJK as min:[0,0,0], max:[0,2,3], the other rank would specify min/max IJK as min:[1,0,0], max:[1,2,3]. If sending the data all as one rank it would be the full range of: min:[0,0,0], max:[1,2,3]

IJK Vals: These specify the actual XYZ location for each IJK value in the grid. The order of these should be by the fastest changing dimension being I, the next being J, and the next being K. I.E. for a 2x2x2 grid the x_vals array would contain the X component for IJK values: [i0 j0 k0][i1 j0 k0][i0 j1 k0][i1 j1 k0][i0 j0 k1][i1 j0 k1][i0 j1 k1][i1 j1 k1].

Note: iblanking information is sent via dvs_update_var_node_scalar() using DVS_STRUCTURED_IBLANKED_NODES as the variable id

Note: Ghost element information is sent via dvs_update_var_element_scalar() using DVS_STRUCTURED_GHOST_ELEMENTS as the variable id

Parameters

[in]	session_id	id for session created by dvs_connect()
[in]	part_id	the id of part we are updating nodes for
[in]	global_ijk_max	The one based global ijk max of the mesh across all ranks
[in]	local_ijk_min	the zero based local sub-block ijk min for this rank
[in]	local_ijk_max	the zero based local sub-block ijk max for this rank
	x_vals	The actual X component for each IJK value for the local sub block (size (iMax-iMin+1)*(jMax-jMin+1)*(kMax-kMin+1))
	y_vals	The actual Y component for each IJK value for the local sub block (size (iMax-iMin+1)*(jMax-jMin+1)*(kMax-kMin+1))
	z_vals	The actual Z component for each IJK value for the local sub block (size (iMax-iMin+1)*(jMax-jMin+1)*(kMax-kMin+1))

Returns

dvs_ret TODO

Update the nodes for a parallelepiped structured part.

A parallelepiped structured part is represented by the global IJK grid across ranks, the local sub-block's IJK range, the ogigin of the IJK sub-block, the normalized direction (unit) vectors for each IJK dimension, and the absolute distances for each IJK index from the origin of this sub-block.

Global IJK Max: for a 2x3x4 grid would be: [2 3 4]

Local IJK Dimensions: The min/max represent a local sub-block from the overall global grid. This could be the entire range if not splitting the grid into multiple ranks or a specific slice. For example you could have a 2ix3jx4k grid where it was split across the I dimension. One rank would specify min/max IJK as min:[0,0,0], max:[0,2,3], the other rank would specify min/max IJK as min:[1,0,0], max:[1,2,3]. If sending the data all as one rank it would be the full range of: min:[0,0,0], max:[1,2,3]

Direction (Unit) Vectors: These represent the XYZ orientation of each IJK axis. I.E. if I==X J==Y K==Z the vectors would be dir_i: [1 0 0], dir_j: [0 1 0], dir_k: [0 0 1]

IJK Vals: These specify the absolute distance from the XYZ origin in each IJK direction(specified by the direction vectors). So if the distance was 1 between every I index, 2 between every J index, and 3 in between every K index the arrays would look like: i_vals: [0 1 2 3 4 5....] j_vals: [0 2 4 6 8 10....] k_vals: [0 3 6 9 12 15....]

Note: iblanking information is sent via dvs_update_var_node_scalar() using DVS_STRUCTURED_IBLANKED_NODES as the variable id

Note: Ghost element information is sent via dvs_update_var_element_scalar() using DVS_STRUCTURED_GHOST_ELEMENTS as the variable id

Parameters

[in]	session_id	id for session created by dvs_connect()
[in]	part_id	the id of part we are updating nodes for
[in]	global_ijk_max	The one based global ijk max of the mesh across all ranks
[in]	local_ijk_min	the zero based local sub-block ijk min for this rank
[in]	local_ijk_max	the zero based local sub-block ijk max for this rank
[in]	origin	the XYZ origin of this local ijk block
[in]	dir_i	The normalized XYZ direction vector for the i dimension
[in]	dir_j	The normalized XYZ direction vector for the j dimension
[in]	dir_k	The normalized XYZ direction vector for the k dimension
[in]	i_vals	The absolute distance vector for each i index from the local sub block's origin of size iMax-iMin+1
[in]	j_vals	The absolute distance vector for each j index from the local sub block's origin of size jMax-jMin+1
[in]	k_vals	The absolute distance vector for each k index from the local sub block's origin of size kMax-kMin+1

Returns

dvs_ret TODO

Update the data for a plot.

Update the data for a plot, the size of the x_values and y_values should match and be the same as num_values

Parameters

	session_id	id for session created by dvs_connect()
	plot_id	id of plot to update matching plot_infos sent with dvs_add_plot_info
[in]	x_values	array of x axis values
[in]	y_values	array of y axis values
	num_values	size of arrays

Returns

dvs_ret TODO

Update value of case scalar.

Parameters

session_id	id for session created by dvs_connect()
var_id	unique id of variable to update (must match var added with dvs_add_var_info)
scalar	value to update

Returns

dvs_ret TODO

Update value of case vector.

Parameters

	session_id	id for session created by dvs_connect()
	var_id	unique id of variable to update (must match var added with dvs_add_var_info)
[in]	vec	array of x,y,z values (size 3)

Returns

dvs_ret TODO

Update a field of scalars on elements.

Parameters

	session_id	id for session created by dvs_connect()
	var_id	unique id for variable to update (must match var added with dvs_add_var_info)
	part_id	unique id for part element is associated with (must match parts added with dvs_add_part_info)
	type	element type to update
[in]	scalars	array of scalars
	num_vals	number of values in scalar array

Returns

dvs_ret TODO

Update a field of vectors on elements.

Updates a field of vectors on elements, the size of all coordinate arrays must be the same.

Parameters

	session_id	id for session created by dvs_connect()
	var_id	unique id for variable to update (must match var added with dvs_add_var_info)
	part_id	unique id for part to update (must match parts added with dvs_add_part_info)
	type	element type to update
[in]	values	array of values to udpate, should be the size of number of elements * 3, values are XYZ XYZ XYZ.......... XYZ
	num_values	size of values array

Returns

dvs_ret TODO

Update a field of scalars on nodes.

Parameters

	session_id	id for session created by dvs_connect()
	var_id	unique id for variable to update (must match var added with dvs_add_var_info)
	part_id	unique id for part nodes are associated with (must match parts added with dvs_add_part_info)
[in]	scalars	array of scalars to set on variable
	num_vals	number of values in scalar array

Returns

dvs_ret TODO

Update a field of vectors on nodes.

Updates a field of vectors on nodes, the size of all coordinate arrays must be the same.

Parameters

	session_id	id for session created by dvs_connect()
	var_id	unique id for variable to update (must match var added with dvs_add_var_info)
	part_id	unique id for part to update (must match parts added with dvs_add_part_info)
[in]	values	array of values to udpate, should be the size of number of nodes * 3, values are XYZ XYZ XYZ.......... XYZ
	num_values	size of values array

Returns

dvs_ret TODO

Update value of part scalar.

Parameters

session_id	id for session created by dvs_connect()
var_id	unique id of variable to update (must match var added with dvs_add_var_info)
part_id	unique id of part associated with (must match parts added with dvs_add_part_info)
scalar	value to update

Returns

dvs_ret TODO

Update value of part scalar.

Parameters

	session_id	id for session created by dvs_connect()
	var_id	unique id of variable to update (must match var added with dvs_add_var_info)
	part_id	unique id of part associated with (must match parts added with dvs_add_part_info)
[in]	vec	array of x,y,z values (size 3)

Returns

dvs_ret TODO