#include "ple_config.h"
#include <mpi.h>
#include "ple_defs.h"

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

Typedef Documentation

◆ ple_locator_log_t

typedef int() ple_locator_log_t(int event, int data, const char *string)

◆ ple_mesh_elements_locate_t

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[])

◆ ple_mesh_extents_t

typedef ple_lnum_t() ple_mesh_extents_t(const void *mesh, ple_lnum_t n_max_extents, double tolerance, double extents[])

Enumeration Type Documentation

◆ ple_locator_option_t

enum ple_locator_option_t

Enumerator
PLE_LOCATOR_NUMBERING
PLE_LOCATOR_N_OPTIONS

Function Documentation

◆ ple_locator_create()

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]	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

Returns: pointer to locator

◆ ple_locator_destroy()

ple_locator_t* ple_locator_destroy ( ple_locator_t * this_locator )

Destruction of a locator structure.

Parameters

[in,out] this_locator locator to destroy

Returns: NULL pointer

◆ ple_locator_discard_exterior()

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_locator pointer to locator structure

◆ ple_locator_dump()

void ple_locator_dump ( const ple_locator_t * this_locator )

Dump printout of a locator structure.

Parameters

this_locator pointer to structure that should be dumped

◆ ple_locator_exchange_point_var()

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_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)

◆ ple_locator_extend_search()

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.

Parameters

[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.

◆ ple_locator_get_async_threshold()

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

◆ ple_locator_get_comm_times()

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_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)

◆ ple_locator_get_dist_coords()

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_locator pointer to locator structure

Returns: coordinate array associated with distant points (interlaced).

◆ ple_locator_get_dist_locations()

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_locator pointer to locator structure

Returns: local element numbers associated with distant points.

◆ ple_locator_get_exterior_list()

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_locator pointer to locator structure

Returns: list of points not located.

◆ ple_locator_get_interior_list()

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_locator pointer to locator structure

Returns: list of points located.

◆ ple_locator_get_n_dist_points()

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_locator pointer to locator structure

Returns: number of distant points.

◆ ple_locator_get_n_exterior()

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_locator pointer to locator structure

Returns: number of points not located.

◆ ple_locator_get_n_interior()

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_locator pointer to locator structure

Returns: number of points located.

◆ ple_locator_get_times()

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_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)

◆ ple_locator_set_async_threshold()

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

threshold maximum number of ranks allowing asynchronous exchanges

◆ ple_locator_set_comm_log()

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

◆ ple_locator_set_mesh()

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.

Parameters

[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.

◆ ple_locator_shift_locations()

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_locator	pointer to locator structure
[in]	location_shift	shift value

Typedefs

Enumerations

Functions

Typedef Documentation

◆ ple_locator_log_t

◆ ple_mesh_elements_locate_t

◆ ple_mesh_extents_t

Enumeration Type Documentation

◆ ple_locator_option_t

Function Documentation

◆ ple_locator_create()

◆ ple_locator_destroy()

◆ ple_locator_discard_exterior()

◆ ple_locator_dump()

◆ ple_locator_exchange_point_var()

◆ ple_locator_extend_search()

◆ ple_locator_get_async_threshold()

◆ ple_locator_get_comm_times()

◆ ple_locator_get_dist_coords()

◆ ple_locator_get_dist_locations()

◆ ple_locator_get_exterior_list()

◆ ple_locator_get_interior_list()

◆ ple_locator_get_n_dist_points()

◆ ple_locator_get_n_exterior()

◆ ple_locator_get_n_interior()

◆ ple_locator_get_times()

◆ ple_locator_set_async_threshold()

◆ ple_locator_set_comm_log()

◆ ple_locator_set_mesh()

◆ ple_locator_shift_locations()