| PLE
    Parallel Location and Exchange | 
Go to the source code of this file.
| Typedefs | |
| typedef ple_lnum_t() | ple_mesh_extents_t(const void *mesh, ple_lnum_t n_max_extents, double tolerance, double extents[]) | 
| typedef void() | ple_mesh_elements_locate_t(const void *mesh, float tolerance_base, float tolerance_fraction, ple_lnum_t n_points, const ple_coord_t point_coords[], const int point_tag[], ple_lnum_t location[], float distance[]) | 
| typedef int() | ple_locator_log_t(int event, int data, const char *string) | 
| Enumerations | |
| enum | ple_locator_option_t { PLE_LOCATOR_NUMBERING , PLE_LOCATOR_N_OPTIONS } | 
| Functions | |
| ple_locator_t * | ple_locator_create (MPI_Comm comm, int n_ranks, int start_rank) | 
| Creation of a locator structure.  More... | |
| ple_locator_t * | ple_locator_destroy (ple_locator_t *this_locator) | 
| Destruction of a locator structure.  More... | |
| void | ple_locator_set_mesh (ple_locator_t *this_locator, const void *mesh, const int *options, float tolerance_base, float tolerance_fraction, int dim, ple_lnum_t n_points, const ple_lnum_t point_list[], const int point_tag[], const ple_coord_t point_coords[], float distance[], ple_mesh_extents_t *mesh_extents_f, ple_mesh_elements_locate_t *mesh_elements_locate_f) | 
| Prepare locator for use with a given mesh representation.  More... | |
| void | ple_locator_extend_search (ple_locator_t *this_locator, const void *mesh, const int *options, float tolerance_base, float tolerance_fraction, ple_lnum_t n_points, const ple_lnum_t point_list[], const int point_tag[], const ple_coord_t point_coords[], float distance[], ple_mesh_extents_t *mesh_extents_f, ple_mesh_elements_locate_t *mesh_locate_f) | 
| Extend search for a locator for which set_mesh has already been called.  More... | |
| void | ple_locator_shift_locations (ple_locator_t *this_locator, ple_lnum_t location_shift) | 
| Shift location ids for located points after locator initialization.  More... | |
| ple_lnum_t | ple_locator_get_n_dist_points (const ple_locator_t *this_locator) | 
| Return number of distant points after locator initialization.  More... | |
| const ple_lnum_t * | ple_locator_get_dist_locations (const ple_locator_t *this_locator) | 
| Return an array of local element numbers containing (or nearest to) each distant point after locator initialization.  More... | |
| const ple_coord_t * | ple_locator_get_dist_coords (const ple_locator_t *this_locator) | 
| Return an array of coordinates of each distant point after locator initialization.  More... | |
| ple_lnum_t | ple_locator_get_n_interior (const ple_locator_t *this_locator) | 
| Return number of points located after locator initialization.  More... | |
| const ple_lnum_t * | ple_locator_get_interior_list (const ple_locator_t *this_locator) | 
| Return list of points located after locator initialization. This list defines a subset of the point set used at initialization.  More... | |
| ple_lnum_t | ple_locator_get_n_exterior (const ple_locator_t *this_locator) | 
| Return number of points not located after locator initialization.  More... | |
| const ple_lnum_t * | ple_locator_get_exterior_list (const ple_locator_t *this_locator) | 
| Return list of points not located after locator initialization. This list defines a subset of the point set used at initialization.  More... | |
| void | ple_locator_discard_exterior (ple_locator_t *this_locator) | 
| Discard list of points not located after locator initialization. This list defines a subset of the point set used at initialization.  More... | |
| void | ple_locator_exchange_point_var (ple_locator_t *this_locator, void *distant_var, void *local_var, const ple_lnum_t *local_list, size_t type_size, size_t stride, int reverse) | 
| Distribute variable defined on distant points to processes owning the original points (i.e. distant processes).  More... | |
| void | ple_locator_exchange_point_var_all (ple_locator_t *this_locator, void *distant_var, void *local_var, const ple_lnum_t *local_list, size_t type_size, size_t stride, int reverse) | 
| Distribute variable defined on distant points to processes owning the original points (i.e. distant processes).  More... | |
| void | ple_locator_get_times (const ple_locator_t *this_locator, double *location_wtime, double *location_cpu_time, double *exchange_wtime, double *exchange_cpu_time) | 
| Return timing information.  More... | |
| void | ple_locator_get_comm_times (const ple_locator_t *this_locator, double *location_wtime, double *location_cpu_time, double *exchange_wtime, double *exchange_cpu_time) | 
| Return communication timing information.  More... | |
| void | ple_locator_dump (const ple_locator_t *this_locator) | 
| Dump printout of a locator structure.  More... | |
| int | ple_locator_get_async_threshold (void) | 
| Get the maximum number of exchanging ranks for which we use asynchronous MPI sends and receives instead of MPI_SendRecv.  More... | |
| void | ple_locator_set_async_threshold (int threshold) | 
| Set the maximum number of exchanging ranks for which we use asynchronous MPI sends and receives instead of MPI_SendRecv.  More... | |
| void | ple_locator_set_default_option (const char *key, const char *value) | 
| Set default locator options.  More... | |
| void | ple_locator_set_options (ple_locator_t *this_locator, const char *key, const char *value) | 
| Set options for a given locator.  More... | |
| void | ple_locator_set_comm_log (ple_locator_log_t *log_function, int start_p_comm, int end_p_comm, int start_g_comm, int end_g_comm) | 
| Register communication logging functions for locator instrumentation.  More... | |
| typedef int() ple_locator_log_t(int event, int data, const char *string) | 
| typedef void() ple_mesh_elements_locate_t(const void *mesh, float tolerance_base, float tolerance_fraction, ple_lnum_t n_points, const ple_coord_t point_coords[], const int point_tag[], ple_lnum_t location[], float distance[]) | 
| typedef ple_lnum_t() ple_mesh_extents_t(const void *mesh, ple_lnum_t n_max_extents, double tolerance, double extents[]) | 
| enum ple_locator_option_t | 
| ple_locator_t* ple_locator_create | ( | MPI_Comm | comm, | 
| int | n_ranks, | ||
| int | start_rank | ||
| ) | 
Creation of a locator structure.
Note that depending on the choice of ranks of the associated communicator, distant ranks may in fact be truly distant or not. If n_ranks = 1 and start_rank is equal to the current rank in the communicator, the locator will work only locally.
| [in] | comm | associated MPI communicator | 
| [in] | n_ranks | number of MPI ranks associated with distant location | 
| [in] | start_rank | first MPI rank associated with distant location | 
| ple_locator_t* ple_locator_destroy | ( | ple_locator_t * | this_locator | ) | 
Destruction of a locator structure.
| [in,out] | this_locator | locator to destroy | 
| void ple_locator_discard_exterior | ( | ple_locator_t * | this_locator | ) | 
Discard list of points not located after locator initialization. This list defines a subset of the point set used at initialization.
| [in] | this_locator | pointer to locator structure | 
| void ple_locator_dump | ( | const ple_locator_t * | this_locator | ) | 
Dump printout of a locator structure.
| this_locator | pointer to structure that should be dumped | 
| void ple_locator_exchange_point_var | ( | ple_locator_t * | this_locator, | 
| void * | distant_var, | ||
| void * | local_var, | ||
| const ple_lnum_t * | local_list, | ||
| size_t | type_size, | ||
| size_t | stride, | ||
| int | reverse | ||
| ) | 
Distribute variable defined on distant points to processes owning the original points (i.e. distant processes).
The exchange is symmetric if both variables are defined, receive only if distant_var is NULL, or send only if local_var is NULL.
The caller should have defined the values of distant_var[] for the distant points, whose coordinates are given by ple_locator_get_dist_coords(), and which are located in the elements whose numbers are given by ple_locator_get_dist_locations().
The local_var[] is defined at the located points (those whose numbers are returned by ple_locator_get_interior_list().
If the optional local_list indirection is used, it is assumed to use the same base numbering as that defined by the options for the previous call to ple_locator_set_mesh() or ple_locator_extend_search().
| [in] | this_locator | pointer to locator structure | 
| [in,out] | distant_var | variable defined on distant points (ready to send); size: n_dist_points*stride | 
| [in,out] | local_var | variable defined on located local points (received); size: n_interior*stride | 
| [in] | local_list | optional indirection list for local_var | 
| [in] | type_size | sizeof (float or double) variable type | 
| [in] | stride | dimension (1 for scalar, 3 for interleaved vector) | 
| [in] | reverse | if nonzero, exchange is reversed (receive values associated with distant points from the processes owning the original points) | 
| void ple_locator_exchange_point_var_all | ( | ple_locator_t * | this_locator, | 
| void * | distant_var, | ||
| void * | local_var, | ||
| const ple_lnum_t * | local_list, | ||
| size_t | type_size, | ||
| size_t | stride, | ||
| int | reverse | ||
| ) | 
Distribute variable defined on distant points to processes owning the original points (i.e. distant processes).
The exchange is symmetric if both variables are defined, receive only if distant_var is NULL, or send only if local_var is NULL.
The caller should have defined the values of distant_var[] for the distant points, whose coordinates are given by ple_locator_get_dist_coords(), and which are located in the elements whose numbers are given by ple_locator_get_dist_locations().
The local_var[] is defined at the local points (whether located or not) provided when calling ple_locator_set_mesh() or ple_locator_extend_search().
If the optional local_list indirection is used, it is assumed to use the same base numbering as that defined by the options for the previous call to ple_locator_set_mesh() or ple_locator_extend_search().
| [in] | this_locator | pointer to locator structure | 
| [in,out] | distant_var | variable defined on distant points (ready to send); size: n_dist_points*stride | 
| [in,out] | local_var | variable defined on local points (received); size: n_points*stride | 
| [in] | local_list | optional indirection list for local_var | 
| [in] | type_size | sizeof (float or double) variable type | 
| [in] | stride | dimension (1 for scalar, 3 for interleaved vector) | 
| [in] | reverse | if nonzero, exchange is reversed (receive values associated with distant points from the processes owning the original points) | 
| void ple_locator_extend_search | ( | ple_locator_t * | this_locator, | 
| const void * | mesh, | ||
| const int * | options, | ||
| float | tolerance_base, | ||
| float | tolerance_fraction, | ||
| ple_lnum_t | n_points, | ||
| const ple_lnum_t | point_list[], | ||
| const int | point_tag[], | ||
| const ple_coord_t | point_coords[], | ||
| float | distance[], | ||
| ple_mesh_extents_t * | mesh_extents_f, | ||
| ple_mesh_elements_locate_t * | mesh_locate_f | ||
| ) | 
Extend search for a locator for which set_mesh has already been called.
| [in,out] | this_locator | pointer to locator structure | 
| [in] | mesh | pointer to mesh representation structure | 
| [in] | options | options array (size PLE_LOCATOR_N_OPTIONS), or NULL | 
| [in] | tolerance_base | associated fixed tolerance | 
| [in] | tolerance_fraction | associated fraction of element bounding boxes added to tolerance | 
| [in] | n_points | number of points to locate | 
| [in] | point_list | optional indirection array to point_coords | 
| [in] | point_tag | optional point tag (size: n_points) | 
| [in] | point_coords | coordinates of points to locate (dimension: dim * n_points) | 
| [out] | distance | optional distance from point to matching element: < 0 if unlocated; 0 - 1 if inside and > 1 if outside a volume element, or absolute distance to a surface element (size: n_points) | 
| [in] | mesh_extents_f | pointer to function computing mesh or mesh subset or element extents | 
| [in] | mesh_locate_f | pointer to function wich updates the location[] and distance[] arrays associated with a set of points for points that are in an element of this mesh, or closer to one than to previously encountered elements. | 
| int ple_locator_get_async_threshold | ( | void | ) | 
Get the maximum number of exchanging ranks for which we use asynchronous MPI sends and receives instead of MPI_SendRecv.
| void ple_locator_get_comm_times | ( | const ple_locator_t * | this_locator, | 
| double * | location_wtime, | ||
| double * | location_cpu_time, | ||
| double * | exchange_wtime, | ||
| double * | exchange_cpu_time | ||
| ) | 
Return communication timing information.
In serial mode, return times are always zero.
When location on closest elements to force location of all points is active, location times include a total value, followed by the value associated with the location of closest elements stage.
parameters:
| [in] | this_locator | pointer to locator structure | 
| [out] | location_wtime | Location Wall-clock time (or NULL) | 
| [out] | location_cpu_time | Location CPU time (or NULL) | 
| [out] | exchange_wtime | Variable exchange Wall-clock time (or NULL) | 
| [out] | exchange_cpu_time | Variable exchange CPU time (or NULL) | 
| const ple_coord_t* ple_locator_get_dist_coords | ( | const ple_locator_t * | this_locator | ) | 
Return an array of coordinates of each distant point after locator initialization.
| [in] | this_locator | pointer to locator structure | 
| const ple_lnum_t* ple_locator_get_dist_locations | ( | const ple_locator_t * | this_locator | ) | 
Return an array of local element numbers containing (or nearest to) each distant point after locator initialization.
| [in] | this_locator | pointer to locator structure | 
| const ple_lnum_t* ple_locator_get_exterior_list | ( | const ple_locator_t * | this_locator | ) | 
Return list of points not located after locator initialization. This list defines a subset of the point set used at initialization.
| [in] | this_locator | pointer to locator structure | 
| const ple_lnum_t* ple_locator_get_interior_list | ( | const ple_locator_t * | this_locator | ) | 
Return list of points located after locator initialization. This list defines a subset of the point set used at initialization.
| [in] | this_locator | pointer to locator structure | 
| ple_lnum_t ple_locator_get_n_dist_points | ( | const ple_locator_t * | this_locator | ) | 
Return number of distant points after locator initialization.
| [in] | this_locator | pointer to locator structure | 
| ple_lnum_t ple_locator_get_n_exterior | ( | const ple_locator_t * | this_locator | ) | 
Return number of points not located after locator initialization.
| [in] | this_locator | pointer to locator structure | 
| ple_lnum_t ple_locator_get_n_interior | ( | const ple_locator_t * | this_locator | ) | 
Return number of points located after locator initialization.
| [in] | this_locator | pointer to locator structure | 
| void ple_locator_get_times | ( | const ple_locator_t * | this_locator, | 
| double * | location_wtime, | ||
| double * | location_cpu_time, | ||
| double * | exchange_wtime, | ||
| double * | exchange_cpu_time | ||
| ) | 
Return timing information.
In parallel mode, this includes communication time.
When location on closest elements to force location of all points is active, location times include a total value, followed by the value associated with the location of closest elements stage.
| [in] | this_locator | pointer to locator structure | 
| [out] | location_wtime | Location Wall-clock time (or NULL) | 
| [out] | location_cpu_time | Location CPU time (or NULL) | 
| [out] | exchange_wtime | Variable exchange Wall-clock time (size: 1 or NULL) | 
| [out] | exchange_cpu_time | Variable exchange CPU time (size: 2 or NULL) | 
| void ple_locator_set_async_threshold | ( | int | threshold | ) | 
Set the maximum number of exchanging ranks for which we use asynchronous MPI sends and receives instead of MPI_SendRecv.
| threshold | maximum number of ranks allowing asynchronous exchanges | 
| void ple_locator_set_comm_log | ( | ple_locator_log_t * | log_function, | 
| int | start_p_comm, | ||
| int | end_p_comm, | ||
| int | start_g_comm, | ||
| int | end_g_comm | ||
| ) | 
Register communication logging functions for locator instrumentation.
By default, locators are not instrumented.
Functions using MPE may be defined and used, but other similar systems may be used.
| [in] | log_function | pointer to logging function | 
| [in] | start_p_comm | point to point communication start event number | 
| [in] | end_p_comm | point to point communication end event number | 
| [in] | start_g_comm | global communication start event number | 
| [in] | end_g_comm | global communication end event number | 
| void ple_locator_set_default_option | ( | const char * | key, | 
| const char * | value | ||
| ) | 
Set default locator options.
| [in] | key | option name | 
| [in] | value | associated value | 
| void ple_locator_set_mesh | ( | ple_locator_t * | this_locator, | 
| const void * | mesh, | ||
| const int * | options, | ||
| float | tolerance_base, | ||
| float | tolerance_fraction, | ||
| int | dim, | ||
| ple_lnum_t | n_points, | ||
| const ple_lnum_t | point_list[], | ||
| const int | point_tag[], | ||
| const ple_coord_t | point_coords[], | ||
| float | distance[], | ||
| ple_mesh_extents_t * | mesh_extents_f, | ||
| ple_mesh_elements_locate_t * | mesh_locate_f | ||
| ) | 
Prepare locator for use with a given mesh representation.
| [in,out] | this_locator | pointer to locator structure | 
| [in] | mesh | pointer to mesh representation structure | 
| [in] | options | options array (size PLE_LOCATOR_N_OPTIONS), or NULL | 
| [in] | tolerance_base | associated fixed tolerance | 
| [in] | tolerance_fraction | associated fraction of element bounding boxes added to tolerance | 
| [in] | dim | spatial dimension of mesh and points to locate | 
| [in] | n_points | number of points to locate | 
| [in] | point_list | optional indirection array to point_coords | 
| [in] | point_tag | optional point tag (size: n_points) | 
| [in] | point_coords | coordinates of points to locate (dimension: dim * n_points) | 
| [out] | distance | optional distance from point to matching element: < 0 if unlocated; 0 - 1 if inside and > 1 if outside a volume element, or absolute distance to a surface element (size: n_points) | 
| [in] | mesh_extents_f | pointer to function computing mesh or mesh subset or element extents | 
| [in] | mesh_locate_f | pointer to function wich updates the location[] and distance[] arrays associated with a set of points for points that are in an element of this mesh, or closer to one than to previously encountered elements. | 
| void ple_locator_set_options | ( | ple_locator_t * | this_locator, | 
| const char * | key, | ||
| const char * | value | ||
| ) | 
Set options for a given locator.
| [in,out] | this_locator | pointer to locator structure | 
| [in] | key | option name | 
| [in] | value | associated value | 
| void ple_locator_shift_locations | ( | ple_locator_t * | this_locator, | 
| ple_lnum_t | location_shift | ||
| ) | 
Shift location ids for located points after locator initialization.
This is useful mainly to switch between 0-based to 1-based numberings.
| [in,out] | this_locator | pointer to locator structure | 
| [in] | location_shift | shift value |