PLE
Parallel Location and Exchange
 All Files Functions Pages
Functions
ple_locator.c File Reference

Locate points in a representation associated with a mesh. More...

#include "ple_config.h"
#include <assert.h>
#include <math.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <mpi.h>
#include "ple_config_defs.h"
#include "ple_defs.h"
#include "ple_locator.h"

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 ple_lnum_t 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. 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 ple_lnum_t 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_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_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...
 

Detailed Description

Locate points in a representation associated with a mesh.

Function Documentation

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.

Parameters
[in]commassociated MPI communicator
[in]n_ranksnumber of MPI ranks associated with distant location
[in]start_rankfirst MPI rank associated with distant location
Returns
pointer to locator
ple_locator_t* ple_locator_destroy ( ple_locator_t *  this_locator)

Destruction of a locator structure.

Parameters
[in,out]this_locatorlocator to destroy
Returns
NULL pointer
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.

Parameters
[in]this_locatorpointer to locator structure
void ple_locator_dump ( const ple_locator_t *  this_locator)

Dump printout of a locator structure.

Parameters
this_locatorpointer 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().

Parameters
[in]this_locatorpointer to locator structure
[in,out]distant_varvariable defined on distant points (ready to send); size: n_dist_points*stride
[in,out]local_varvariable defined on located local points (received); size: n_interior*stride
[in]local_listoptional indirection list for local_var
[in]type_sizesizeof (float or double) variable type
[in]stridedimension (1 for scalar, 3 for interleaved vector)
[in]reverseif 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 ple_lnum_t  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.

Parameters
[in,out]this_locatorpointer to locator structure
[in]meshpointer to mesh representation structure
[in]optionsoptions array (size PLE_LOCATOR_N_OPTIONS), or NULL
[in]tolerance_baseassociated fixed tolerance
[in]tolerance_fractionassociated fraction of element bounding boxes added to tolerance
[in]n_pointsnumber of points to locate
[in]point_listoptional indirection array to point_coords
[in]point_tagoptional point tag
[in]point_coordscoordinates of points to locate (dimension: dim * n_points)
[out]distanceoptional 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_fpointer to function computing mesh or mesh subset or element extents
[in]mesh_locate_fpointer 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.

Returns
the maximum number of ranks allowing asynchronous exchanges
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:

Parameters
[in]this_locatorpointer to locator structure
[out]location_wtimeLocation Wall-clock time (size: 2 or NULL)
[out]location_cpu_timeLocation CPU time (size: 1 or NULL)
[out]exchange_wtimeVariable exchange Wall-clock time (size: 1 or NULL)
[out]exchange_cpu_timeVariable exchange CPU time (size: 2 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.

Parameters
[in]this_locatorpointer to locator structure
Returns
coordinate array associated with distant points (interlaced).
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.

Parameters
[in]this_locatorpointer to locator structure
Returns
local element numbers associated with distant points.
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.

Parameters
[in]this_locatorpointer to locator structure
Returns
list of points not located.
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.

Parameters
[in]this_locatorpointer to locator structure
Returns
list of points located.
ple_lnum_t ple_locator_get_n_dist_points ( const ple_locator_t *  this_locator)

Return number of distant points after locator initialization.

Parameters
[in]this_locatorpointer to locator structure
Returns
number of distant points.
ple_lnum_t ple_locator_get_n_exterior ( const ple_locator_t *  this_locator)

Return number of points not located after locator initialization.

Parameters
[in]this_locatorpointer to locator structure
Returns
number of points not located.
ple_lnum_t ple_locator_get_n_interior ( const ple_locator_t *  this_locator)

Return number of points located after locator initialization.

Parameters
[in]this_locatorpointer to locator structure
Returns
number of points located.
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.

Parameters
[in]this_locatorpointer to locator structure
[out]location_wtimeLocation Wall-clock time (size: 2 or NULL)
[out]location_cpu_timeLocation CPU time (size: 1 or NULL)
[out]exchange_wtimeVariable exchange Wall-clock time (size: 1 or NULL)
[out]exchange_cpu_timeVariable 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.

Parameters
thresholdmaximum 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.

Parameters
[in]log_functionpointer to logging function
[in]start_p_commpoint to point communication start event number
[in]end_p_commpoint to point communication end event number
[in]start_g_commglobal communication start event number
[in]end_g_commglobal communication end event number
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 ple_lnum_t  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.

Parameters
[in,out]this_locatorpointer to locator structure
[in]meshpointer to mesh representation structure
[in]optionsoptions array (size PLE_LOCATOR_N_OPTIONS), or NULL
[in]tolerance_baseassociated fixed tolerance
[in]tolerance_fractionassociated fraction of element bounding boxes added to tolerance
[in]dimspatial dimension of mesh and points to locate
[in]n_pointsnumber of points to locate
[in]point_listoptional indirection array to point_coords
[in]point_tagoptional point tag
[in]point_coordscoordinates of points to locate (dimension: dim * n_points)
[out]distanceoptional 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_fpointer to function computing mesh or mesh subset or element extents
[in]mesh_locate_fpointer 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_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.

Parameters
[in,out]this_locatorpointer to locator structure
[in]location_shiftshift value