Warning

This is the documentation for the development version of DTK. There may be significant differences from the latest stable release. Please follow this link if you are looking for DTK 2.0

DataTransferKit API¶

C++ API¶

User Function Registry¶

template <class Scalar>

class DataTransferKit::UserFunctionRegistry¶

Registry for user functions.

The registry is the mechanism by which user functions and the data to be called with those user functions are registered with DTK.

Template Parameters

Scalar: Scalar type of the fields this user function implementation will provide.

Unnamed Group

void setNodeListSizeFunction(NodeListSizeFunction &&func, std::shared_ptr<void> user_data = nullptr)¶: Set geometry.

void setNodeListDataFunction(NodeListDataFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setBoundingVolumeListSizeFunction(BoundingVolumeListSizeFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setBoundingVolumeListDataFunction(BoundingVolumeListDataFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setPolyhedronListSizeFunction(PolyhedronListSizeFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setPolyhedronListDataFunction(PolyhedronListDataFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setCellListSizeFunction(CellListSizeFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setCellListDataFunction(CellListDataFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setMixedTopologyCellListSizeFunction(MixedTopologyCellListSizeFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setMixedTopologyCellListDataFunction(MixedTopologyCellListDataFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setBoundarySizeFunction(BoundarySizeFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setBoundaryDataFunction(BoundaryDataFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

Unnamed Group

void setDOFMapSizeFunction(DOFMapSizeFunction &&func, std::shared_ptr<void> user_data = nullptr)¶: Set degree-of-freedom maps.

void setDOFMapDataFunction(DOFMapDataFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setMixedTopologyDOFMapSizeFunction(MixedTopologyDOFMapSizeFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

void setMixedTopologyDOFMapDataFunction(MixedTopologyDOFMapDataFunction &&func, std::shared_ptr<void> user_data = nullptr)¶

Unnamed Group

void setFieldSizeFunction(FieldSizeFunction<Scalar> &&func, std::shared_ptr<void> user_data = nullptr)¶: Set fields.

void setPullFieldDataFunction(PullFieldDataFunction<Scalar> &&func, std::shared_ptr<void> user_data = nullptr)¶

void setPushFieldDataFunction(PushFieldDataFunction<Scalar> &&func, std::shared_ptr<void> user_data = nullptr)¶

void setEvaluateFieldFunction(EvaluateFieldFunction<Scalar> &&func, std::shared_ptr<void> user_data = nullptr)¶

Public Types

template<>
using UserImpl = std::pair<CallableObject, std::shared_ptr<void>>¶: User implementation.

User Application¶

template <class Scalar, class ParallelModel>

class DataTransferKit::UserApplication¶

High-level interface to user applications.

The user application provides a high-level interface to compose DTK input data structures and push and pull field data to and from the application through sequences of user function calls.

Template Parameters

Scalar: Scalar type of the fields this user application will provide.
ParallelModel: The DTK parallel model indicating the on-node parallelism of the user application. Indicates where data will be allocated.

Unnamed Group

template<>
using ExecutionSpace = typename ParallelTraits::ExecutionSpace¶: Type aliases.

Public Functions

UserApplication(const std::shared_ptr<UserFunctionRegistry<Scalar>> &user_functions)¶: Constructor.

auto getNodeList()¶

auto getBoundingVolumeList()¶

auto getPolyhedronList()¶

auto getCellList(std::vector<std::string> &cell_topologies)¶

template <class ListType>
void getBoundary(const std::string &boundary_name, ListType &list)¶

auto getDOFMap(std::string &discretization_type)¶

auto getField(const std::string &field_name)¶

void pullField(const std::string &field_name, Field<Scalar, Kokkos::LayoutLeft, ExecutionSpace> field)¶

void pushField(const std::string &field_name, const Field<Scalar, Kokkos::LayoutLeft, ExecutionSpace> field)¶

void evaluateField(const std::string &field_name, const EvaluationSet<Kokkos::LayoutLeft, ExecutionSpace> eval_set, Field<Scalar, Kokkos::LayoutLeft, ExecutionSpace> field)¶

C API¶

C interface header.

Typedefs

typedef struct _DTK_UserApplicationHandle *DTK_UserApplicationHandle¶

DTK user application handle.

Must be created using DTK_create() to be a valid handle.

The handle essentially hides C++ implementation details from the user.

typedef void( * DTK_NodeListSizeFunction) (void *user_data, unsigned *space_dim, size_t *local_num_nodes, bool *has_ghosts)

Prototype function to get the size parameters for building a node list.

Register with a user application using DTK_set_function() by passing DTK_NODE_LIST_SIZE_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
space_dim: Spatial dimension.
local_num_nodes: Number of nodes DTK will allocate memory for.
has_ghosts: Whether some of the nodes that will be passed are ghosted (i.e. belong to another process)

typedef void( * DTK_NodeListDataFunction) (void *user_data, Coordinate *coordinates, bool *is_ghost_node)

Prototype function to get the data for a node list.

Register with a user application using DTK_set_function() by passing DTK_NODE_LIST_DATA_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
coordinates: Node coordinates.
is_ghost_node: Indicates whether a given node is ghosted.

typedef void( * DTK_BoundingVolumeListSizeFunction) (void *user_data, unsigned *space_dim, size_t *local_num_volumes, bool *has_ghosts)

Prototype function to get the size parameters for building a bounding volume list.

Register with a user application using DTK_set_function() by passing DTK_BOUNDING_VOLUME_LIST_SIZE_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
space_dim: Spatial dimension.
local_num_volumes: Number of volumes DTK will allocate memory for.
has_ghosts: Whether some of the bounding volumes that will be passed are ghosted (i.e. belong to another process)

typedef void( * DTK_BoundingVolumeListDataFunction) (void *user_data, Coordinate *bounding_volumes, bool *is_ghost_volume)

Prototype function to get the data for a bounding volume list.

Register with a user application using DTK_set_function() by passing DTK_BOUNDING_VOLUME_LIST_DATA_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
bounding_volumes: Bounding volumes.
is_ghost_node: Indicates whether a given volume is ghosted.

typedef void( * DTK_PolyhedronListSizeFunction) (void *user_data, unsigned *space_dim, size_t *local_num_nodes, size_t *local_num_faces, size_t *total_nodes_per_face, size_t *local_num_cells, size_t *total_faces_per_cell, bool *has_ghosts)

Prototype function to get the size parameters for building a polyhedron list.

Register with a user application using DTK_set_function() by passing DTK_POLYHEDRON_LIST_SIZE_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
space_dim: Spatial dimension.
local_num_nodes: Number of nodes DTK will allocate memory for.
local_num_faces: Number of faces DTK will allocate memory for.
total_nodes_per_face: Total degrees of freedom per face.
local_num_cells: Number of cells DTK will allocate memory for.
total_faces_per_cell: Total number of faces per cell.
has_ghosts: Whether some of the cells that will be passed are ghosted (i.e. belong to another process)

typedef void( * DTK_PolyhedronListDataFunction) (void *user_data, Coordinate *coordinates, LocalOrdinal *faces, unsigned *nodes_per_face, LocalOrdinal *cells, unsigned *faces_per_cell, int *face_orientation, bool *is_ghost_cell)

Prototype function to get the data for a polyhedron list.

Register with a user application using DTK_set_function() by passing DTK_POLYHEDRON_LIST_DATA_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
coordinates: Node coordinates.
faces: Connectivity list of faces.
nodes_per_face: Number of nodes per face.
cells: Connectivity list of polyhedrons.
faces_per_cell: Number of faces per cell.
face_orientation: Orientation of the faces.
is_ghost_cell: Indicates whether a given cell is ghosted.

typedef void( * DTK_CellListSizeFunction) (void *user_data, unsigned *space_dim, size_t *local_num_nodes, size_t *local_num_cells, unsigned *nodes_per_cell, bool *has_ghosts)

Prototype function to get the size parameters for building a cell list with a single topology.

Register with a user application using DTK_set_function() by passing DTK_CELL_LIST_SIZE_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
space_dim: Spatial dimension.
local_num_nodes: Number of nodes DTK will allocate memory for.
local_num_cells: Number of cells DTK will allocate memory for.
nodes_per_cell: Number of nodes per cell.
has_ghosts: Whether some of the cells that will be passed are ghosted (i.e. belong to another process)

typedef void( * DTK_CellListDataFunction) (void *user_data, Coordinate *coordinates, LocalOrdinal *cells, bool *is_ghost_cell, char *cell_topology)

Prototype function to get the data for a single topology cell list.

Register with a user application using DTK_set_function() by passing DTK_CELL_LIST_DATA_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
coordinates: Node coordinates.
cells: List of cells.
is_ghost_cell: Indicates whether a given cell is ghosted.
cell_topology: Topology of the cells.

typedef void( * DTK_MixedTopologyCellListSizeFunction) (void *user_data, unsigned *space_dim, size_t *local_num_nodes, size_t *local_num_cells, size_t *total_nodes_per_cell, bool *has_ghosts)

Prototype function to get the size parameters for building a cell list with a mixed topology.

Register with a user application using DTK_set_function() by passing DTK_MIXED_TOPOLOGY_CELL_LIST_SIZE_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
space_dim: Spatial dimension.
local_num_nodes: Number of nodes DTK will allocate memory for.
local_num_cells: Number of cells DTK will allocate memory for.
total_nodes_per_cell: Total number of nodes per cell.
has_ghosts: Whether some of the cells that will be passed are ghosted (i.e. belong to another process)

typedef void( * DTK_MixedTopologyCellListDataFunction) (void *user_data, Coordinate *coordinates, LocalOrdinal *cells, unsigned *cell_topology_ids, bool *is_ghost_cell, char **cell_topologies)

Prototype function to get the data for a mixed topology cell list.

Register with a user application using DTK_set_function() by passing DTK_MIXED_TOPOLOGY_CELL_LIST_DATA_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
coordinates: Node coordinates.
cells: List of cells.
cell_topology_ids: Topology id for each cell.
is_ghost_cell: Indicates whether a given cell is ghosted.
cell_topologies: Topologies of the cells.

typedef void( * DTK_BoundarySizeFunction) (void *user_data, const char *boundary_name, size_t *local_num_faces)

Prototype function to get the size parameters for a boundary.

Register with a user application using DTK_set_function() by passing DTK_BOUNDARY_SIZE_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
boundary_name: Name of the boundary.
local_num_faces: Number of faces owned by this process.

typedef void( * DTK_BoundaryDataFunction) (void *user_data, const char *boundary_name, LocalOrdinal *boundary_cells, unsigned *cell_faces_on_boundary)

Prototype function to get the data for a boundary.

Register with a user application using DTK_set_function() by passing DTK_BOUNDARY_DATA_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
boundary_name: Name of the boundary.
boundary_cells: Indices of the cells on the boundary.
cell_faces_on_boundary: Indices of the faces within a given cell that is on the boundary.

typedef void( * DTK_DOFMapSizeFunction) (void *user_data, size_t *local_num_dofs, size_t *local_num_objects, unsigned *dofs_per_object)

Prototype function to get the size parameters for a degree-of-freedom id map with a single number of dofs per object.

Register with a user application using DTK_set_function() by passing DTK_DOF_MAP_SIZE_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
local_num_dofs: Number of degrees of freedom owned by this process.
local_num_objects: Number of objects on this process.
dofs_per_objects: Degrees of freedom per object.

typedef void( * DTK_DOFMapDataFunction) (void *user_data, GlobalOrdinal *global_dof_ids, LocalOrdinal *object_dof_ids, char *discretization_type)

Prototype function to get the size data for a degree-of-freedom id map with a single number of dofs per object.

Register with a user application using DTK_set_function() by passing DTK_DOF_MAP_DATA_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
global_dof_ids: Globally unique ids for DOFs on this process.
object_dof_ids: For every object of the given type in the object list give the local dof ids for that object. The local dof ids correspond to the index of the entry in the global dof id view.
discretization_type: Type of discretization.

typedef void( * DTK_MixedTopologyDofMapSizeFunction) (void *user_data, size_t *local_num_dofs, size_t *local_num_objects, size_t *total_dofs_per_object)

Prototype function to get the size parameters for a degree-of-freedom id map with each object having a potentially different number of dofs (e.g. mixed topology cell lists or polyhedron lists).

Register with a user application using DTK_set_function() by passing DTK_MIXED_TOPOLOGY_DOF_MAP_SIZE_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
local_num_dofs: Number of degrees of freedom owned by this process.
local_num_objects: Number of objects on this process.
total_dofs_per_objects: Total degrees of freedom per objects.

typedef void( * DTK_MixedTopologyDofMapDataFunction) (void *user_data, GlobalOrdinal *global_dof_ids, LocalOrdinal *object_dof_ids, unsigned *dofs_per_object, char *discretization_type)

Prototype function to get the data for a multiple object degree-of-freedom id map (e.g. mixed topology cell lists or polyhedron lists).

Register with a user application using DTK_set_function() by passing DTK_MIXED_TOPOLOGY_DOF_MAP_DATA_FUNCTION as the type argument.

Parameters

user_data: Pointer to custom user data.
global_dof_ids: Globally unique ids for DOFs on this process.
object_dof_ids: Local object IDs.
dofs_per_object: Degrees of freedom per object.
discretization_type: Type of discretization.

typedef void( * DTK_FieldSizeFunction) (void *user_data, const char *field_name, unsigned *field_dimension, size_t *local_num_dofs)

Prototype function to get the size parameters for a field.

Register with a user application using DTK_set_function() by passing DTK_FIELD_SIZE_FUNCTION as the type argument.

Field must be of size local_num_dofs in the associated dof_id_map.

Parameters

user_data: Custom user data.
field_name: Name of the field.
field_dimension: Dimension of the field (i.e. 1 for the pressure, or 3 for the velocity in 3-D)
local_num_dofs: Number of degrees of freedom owned by this process.

typedef void( * DTK_PullFieldDataFunction) (void *user_data, const char *field_name, double *field_dofs)

Prototype function to pull data from the application into a field.

Register with a user application using DTK_set_function() by passing DTK_PULL_FIELD_DATA_FUNCTION as the type argument.

Parameters

user_data: Custom user data.
field_name: Name of the field to pull.
field_dofs: Degrees of freedom for that field.

typedef void( * DTK_PushFieldDataFunction) (void *user_data, const char *field_name, const double *field_dofs)

Prototype function to push data from a field into the application.

Register with a user application using DTK_set_function() by passing DTK_PUSH_FIELD_DATA_FUNCTION as the type argument.

Parameters

user_data: Custom user data.
field_name: Name of the field to push.
field_dofs: Degrees of freedom for that field.

typedef void( * DTK_EvaluateFieldFunction) (void *user_data, const char *field_name, const Coordinate *evaluation_points, const LocalOrdinal *object_ids, double *values)

Prototype function to evaluate a field at a given set of points in a given set of objects.

Register with a user application using DTK_set_function() by passing DTK_EVALUATE_FIELD_FUNCTION as the type argument.

Parameters

user_data: Custom user data.
field_name: Name of the field to evaluate.
evaluate_points: Coordinates of the points at which to evaluate the field.
objects_ids: ID of the cell/face with repect of which the coordinates are expressed.
values: Field values.

Enums

enum DTK_ExecutionSpace¶

Execution space (where functions execute)

Values:

DTK_SERIAL¶

DTK_OPENMP¶

DTK_CUDA¶

enum DTK_FunctionType¶

Passed as the type argument to DTK_set_function() in order to indicate what callback function is being registered with the user application.

Note: Callback functions are passed as pointers to functions that take no arguments and return nothing (void(*)()) so the value of the DTK_FunctionType enum is necessary to indicate what is being registered with the user application and how to cast the function pointer back to the appropriate signature.

Values:

DTK_NODE_LIST_SIZE_FUNCTION¶: See DTK_NodeListSizeFunction()

DTK_NODE_LIST_DATA_FUNCTION¶: See DTK_NodeListDataFunction()

DTK_BOUNDING_VOLUME_LIST_SIZE_FUNCTION¶: See DTK_BoundingVolumeListSizeFunction()

DTK_BOUNDING_VOLUME_LIST_DATA_FUNCTION¶: See DTK_BoundingVolumeListDataFunction()

DTK_POLYHEDRON_LIST_SIZE_FUNCTION¶: See DTK_PolyhedronListSizeFunction()

DTK_POLYHEDRON_LIST_DATA_FUNCTION¶: See DTK_PolyhedronListDataFunction()

DTK_CELL_LIST_SIZE_FUNCTION¶: See DTK_CellListSizeFunction()

DTK_CELL_LIST_DATA_FUNCTION¶: See DTK_CellListDataFunction()

DTK_MIXED_TOPOLOGY_CELL_LIST_SIZE_FUNCTION¶: See DTK_MixedTopologyCellListSizeFunction()

DTK_MIXED_TOPOLOGY_CELL_LIST_DATA_FUNCTION¶: See DTK_MixedTopologyCellListDataFunction()

DTK_BOUNDARY_SIZE_FUNCTION¶: See DTK_BoundarySizeFunction()

DTK_BOUNDARY_DATA_FUNCTION¶: See DTK_BoundaryDataFunction()

DTK_DOF_MAP_SIZE_FUNCTION¶: See DTK_DOFMapSizeFunction()

DTK_DOF_MAP_DATA_FUNCTION¶: See DTK_DOFMapDataFunction()

DTK_MIXED_TOPOLOGY_DOF_MAP_SIZE_FUNCTION¶: See DTK_MixedTopologyDofMapSizeFunction()

DTK_MIXED_TOPOLOGY_DOF_MAP_DATA_FUNCTION¶: See DTK_MixedTopologyDofMapDataFunction()

DTK_FIELD_SIZE_FUNCTION¶: See DTK_FieldSizeFunction()

DTK_PULL_FIELD_DATA_FUNCTION¶: See DTK_PullFieldDataFunction()

DTK_PUSH_FIELD_DATA_FUNCTION¶: See DTK_PushFieldDataFunction()

DTK_EVALUATE_FIELD_FUNCTION¶: See DTK_EvaluateFieldFunction()

Functions

const char *DTK_version()¶

Get the current version of DTK.

Return: Returns a string containing the version number for DTK.

const char *DTK_git_commit_hash()¶

Get the current repository hash.

Note: If the source code is not under revision control (e.g. downloaded as a tarball), this functions returns an error string indicating that it is not a GIT repository.
Return: Returns a string containing the revision number.

DTK_UserApplicationHandle DTK_create(DTK_ExecutionSpace space)¶

Create a DTK handle.

Return

DTK_create returns a handle for the user application.

Parameters

space: Execution space for the callback functions that are to be registered using DTK_set_function().

bool DTK_is_valid(DTK_UserApplicationHandle handle)¶

Indicates whether a DTK handle is valid.

A handle is valid if it was created by DTK_create() and has not yet been deleted by DTK_destroy().

Return

true if the given user application handle is valid; false otherwise.

Parameters

handle: The DTK user application handle to check.

void DTK_destroy(DTK_UserApplicationHandle handle)¶

Destroy a DTK handle.

Parameters

handle: User application handle.

void DTK_initialize()¶

Initializes the DTK execution environment.

This initializes Kokkos if it has not already been initialized.

void DTK_initialize_cmd(int *argc, char ***argv)¶

Initialize DTK.

This initializes Kokkos if it has not already been initialized.

This version of initialize() effectively calls Kokkos::initialize( *argc, *argv ). Pointers to argc and argv arguments are passed in order to match MPI_Init’s interface. This function name was suffixed with _cmd because, unlike C++, C does not allow to overload functions.

Parameters

argc: Pointer to the number of argument.
argv: Pointer to the argument vector.

bool DTK_is_initialized()¶

Indicates whether DTK has been initialized.

This function may be used to determine whether DTK has been initialized.

void DTK_finalize()¶

Finalizes DTK.

This function terminates the DTK execution environment. If DTK initialized Kokkos, finalize Kokkos. However, if Kokkos was initialized before DTK, then this function does NOT finalize Kokkos.

void DTK_set_function(DTK_UserApplicationHandle handle, DTK_FunctionType type, void (*f)()void *user_data, )¶

Register a function as a callback.

This registers a custom function as a callback for DTK to communicate with the user application.

Parameters

handle: User application handle.
type: Type of callback function.
f: Pointer to user defined callback function.
user_data: Pointer to the user data that will be passed to the callback function when executing it.