PLE
Parallel Location and Exchange
 All Files Functions Pages
ple_locator.h
1 #ifndef __PLE_LOCATOR_H__
2 #define __PLE_LOCATOR_H__
3 
4 /*============================================================================
5  * Locate points in a nodal representation associated with a mesh
6  *============================================================================*/
7 
8 /*
9  This file is part of the "Parallel Location and Exchange" library,
10  intended to provide mesh or particle-based code coupling services.
11 
12  Copyright (C) 2005-2015 EDF
13 
14  This library is free software; you can redistribute it and/or
15  modify it under the terms of the GNU Lesser General Public
16  License as published by the Free Software Foundation; either
17  version 2.1 of the License, or (at your option) any later version.
18 
19  This library is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22  Lesser General Public License for more details.
23 
24  You should have received a copy of the GNU Lesser General Public
25  License along with this library; if not, write to the Free Software
26  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
27 */
28 
29 /*----------------------------------------------------------------------------*/
30 
31 #include "ple_config.h"
32 
33 #if defined(PLE_HAVE_MPI)
34 #include <mpi.h>
35 #endif
36 
37 /*----------------------------------------------------------------------------
38  * Local headers
39  *----------------------------------------------------------------------------*/
40 
41 #include "ple_defs.h"
42 
43 /*----------------------------------------------------------------------------*/
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #if 0
48 } /* Fake brace to force back Emacs auto-indentation back to column 0 */
49 #endif
50 #endif /* __cplusplus */
51 
52 /*=============================================================================
53  * Macro definitions
54  *============================================================================*/
55 
56 /*============================================================================
57  * Type definitions
58  *============================================================================*/
59 
60 /*============================================================================
61  * Type definitions
62  *============================================================================*/
63 
64 /* PLE option types */
65 
66 typedef enum {
67 
68  PLE_LOCATOR_NUMBERING,
69  PLE_LOCATOR_N_OPTIONS
70 
71 } ple_locator_option_t;
72 
73 /*----------------------------------------------------------------------------
74  * Query number of extents and compute extents of a mesh representation.
75  *
76  * For future optimizations, computation of extents should not be limited
77  * to mesh extents, but to 1 to n extents, allowing different extent
78  * refinements, from global mesh to individual element extents.
79  *
80  * The minimum required functionality for this function is to compute
81  * whole mesh extents, but it could also return extents of individual
82  * elements, or intermediate extents of mesh subdivisions or coarsened
83  * elements. As such, it takes an argument indicating the maximum
84  * local number of extents it should compute (based on the size of
85  * the extents array argument), but returns the number of extents
86  * really computed, which may be lower (usually 1 for mesh extents,
87  * possibly even 0 if the local mesh is empty). If n_max_extents = 1,
88  * the whole mesh extents should be computed.
89  *
90  * If n_max_extents is set to a negative value (-1), no extents are computed,
91  * but the function returns the maximum number of extents it may compute.
92  * This query mode allows for the caller to allocate the correct amount
93  * of memory for a subsequent call.
94  *
95  * parameters:
96  * mesh <-- pointer to mesh representation structure
97  * n_max_extents <-- maximum number of sub-extents (such as element extents)
98  * to compute, or -1 to query
99  * tolerance <-- addition to local extents of each element:
100  * extent = base_extent * (1 + tolerance)
101  * extents <-> extents associated with the mesh or elements (or even
102  * aggregated elements in case of coarser representation):
103  * x_min_0, y_min_0, ..., x_max_i, y_max_i, ...
104  * (size: 2*dim*n_max_extents), ignored in query mode
105  * returns:
106  * the number of extents computed
107  *----------------------------------------------------------------------------*/
108 
109 typedef ple_lnum_t
110 (ple_mesh_extents_t) (const void *mesh,
111  ple_lnum_t n_max_extents,
112  double tolerance,
113  double extents[]);
114 
115 /*----------------------------------------------------------------------------
116  * Find elements in a given local mesh containing points: updates the
117  * location[] and distance[] arrays associated with a set of points
118  * for points that are in an element of this mesh, or closer to one
119  * than to previously encountered elements.
120  *
121  * parameters:
122  * this_nodal <-- pointer to nodal mesh representation structure
123  * tolerance_base <-- associated base tolerance (used for bounding
124  * box check only, not for location test)
125  * tolerance_fraction <-- associated fraction of element bounding boxes
126  * added to tolerance
127  * n_points <-- number of points to locate
128  * point_coords <-- point coordinates (interleaved)
129  * point_tag <-- optional point tag (size: n_points)
130  * location <-> number of element containing or closest to each
131  * point (size: n_points)
132  * distance <-> distance from point to element indicated by
133  * location[]: < 0 if unlocated, 0 - 1 if inside,
134  * and > 1 if outside a volume element, or absolute
135  * distance to a surface element (size: n_points)
136  *----------------------------------------------------------------------------*/
137 
138 typedef void
139 (ple_mesh_elements_locate_t) (const void *mesh,
140  float tolerance_base,
141  float tolerance_fraction,
142  ple_lnum_t n_points,
143  const ple_coord_t point_coords[],
144  const int point_tag[],
145  ple_lnum_t location[],
146  float distance[]);
147 
148 /*----------------------------------------------------------------------------
149  * Function pointer type for user definable logging/profiling type functions
150  *----------------------------------------------------------------------------*/
151 
152 typedef int
153 (ple_locator_log_t) (int event,
154  int data,
155  const char *string);
156 
157 /*----------------------------------------------------------------------------
158  * Structure defining a locator
159  *----------------------------------------------------------------------------*/
160 
161 typedef struct _ple_locator_t ple_locator_t;
162 
163 /*=============================================================================
164  * Static global variables
165  *============================================================================*/
166 
167 /*=============================================================================
168  * Public function prototypes
169  *============================================================================*/
170 
171 /*----------------------------------------------------------------------------
172  * Creation of a locator structure.
173  *
174  * Note that depending on the choice of ranks of the associated communicator,
175  * distant ranks may in fact be truly distant or not. If n_ranks = 1 and
176  * start_rank is equal to the current rank in the communicator, the locator
177  * will work only locally.
178  *
179  * parameters:
180  * comm <-- associated MPI communicator
181  * n_ranks <-- number of MPI ranks associated with distant location
182  * start_rank <-- first MPI rank associated with distant location
183  *
184  * returns:
185  * pointer to locator
186  *----------------------------------------------------------------------------*/
187 
188 #if defined(PLE_HAVE_MPI)
189 
190 ple_locator_t *
191 ple_locator_create(MPI_Comm comm,
192  int n_ranks,
193  int start_rank);
194 
195 #else
196 
197 ple_locator_t *
198 ple_locator_create(void);
199 
200 #endif
201 
202 /*----------------------------------------------------------------------------
203  * Destruction of a locator structure.
204  *
205  * parameters:
206  * this_locator <-> locator to destroy
207  *
208  * returns:
209  * NULL pointer
210  *----------------------------------------------------------------------------*/
211 
212 ple_locator_t *
213 ple_locator_destroy(ple_locator_t * this_locator);
214 
215 /*----------------------------------------------------------------------------
216  * Prepare locator for use with a given mesh representation.
217  *
218  * parameters:
219  * this_locator <-> pointer to locator structure
220  * mesh <-- pointer to mesh representation structure
221  * options <-- options array (size PLE_LOCATOR_N_OPTIONS),
222  * or NULL
223  * tolerance_base <-- associated base tolerance (used for bounding
224  * box check only, not for location test)
225  * tolerance_fraction <-- associated fraction of element bounding boxes
226  * added to tolerance
227  * dim <-- spatial dimension of mesh and points to locate
228  * n_points <-- number of points to locate
229  * point_list <-- optional indirection array to point_coords
230  * point_tag <-- optional point tag (size: n_points)
231  * point_coords <-- coordinates of points to locate
232  * (dimension: dim * n_points)
233  * distance --> optional distance from point to matching element:
234  * < 0 if unlocated; 0 - 1 if inside and > 1 if
235  * outside a volume element, or absolute distance
236  * to a surface element (size: n_points)
237  * mesh_extents_f <-- pointer to function computing mesh extents
238  * locate_f <-- pointer to function wich updates the location[]
239  * and distance[] arrays associated with a set of
240  * points for points that are in an element of this
241  * mesh, or closer to one than to previously
242  * encountered elements.
243  *----------------------------------------------------------------------------*/
244 
245 void
246 ple_locator_set_mesh(ple_locator_t *this_locator,
247  const void *mesh,
248  const int *options,
249  float tolerance_base,
250  float tolerance_fraction,
251  int dim,
252  ple_lnum_t n_points,
253  const ple_lnum_t point_list[],
254  const int point_tag[],
255  const ple_coord_t point_coords[],
256  float distance[],
257  ple_mesh_extents_t *mesh_extents_f,
258  ple_mesh_elements_locate_t *mesh_elements_locate_f);
259 
260 /*----------------------------------------------------------------------------
261  * Extend search for a locator for which set_mesh has already been called.
262  *
263  * parameters:
264  * this_locator <-> pointer to locator structure
265  * mesh <-- pointer to mesh representation structure
266  * options <-- options array (size PLE_LOCATOR_N_OPTIONS),
267  * or NULL
268  * tolerance_base <-- associated base tolerance (used for bounding
269  * box check only, not for location test)
270  * tolerance_fraction <-- associated fraction of element bounding boxes
271  * added to tolerance
272  * n_points <-- number of points to locate
273  * point_list <-- optional indirection array to point_coords
274  * point_tag <-- optional point tag (size: n_points)
275  * point_coords <-- coordinates of points to locate
276  * (dimension: dim * n_points)
277  * distance --> optional distance from point to matching element:
278  * < 0 if unlocated; 0 - 1 if inside and > 1 if
279  * outside a volume element, or absolute distance
280  * to a surface element (size: n_points)
281  * mesh_extents_f <-- pointer to function computing mesh extents
282  * locate_f <-- pointer to function wich updates the location[]
283  * and distance[] arrays associated with a set of
284  * points for points that are in an element of this
285  * mesh, or closer to one than to previously
286  * encountered elements.
287  */
288 /*----------------------------------------------------------------------------*/
289 
290 void
291 ple_locator_extend_search(ple_locator_t *this_locator,
292  const void *mesh,
293  const int *options,
294  float tolerance_base,
295  float tolerance_fraction,
296  ple_lnum_t n_points,
297  const ple_lnum_t point_list[],
298  const ple_lnum_t point_tag[],
299  const ple_coord_t point_coords[],
300  float distance[],
301  ple_mesh_extents_t *mesh_extents_f,
302  ple_mesh_elements_locate_t *mesh_locate_f);
303 
304 /*----------------------------------------------------------------------------
305  * Shift location ids for located points after locator initialization.
306  *
307  * This is useful mainly to switch between 0-based to 1-based numberings.
308  *
309  * parameters:
310  * this_locator <-> pointer to locator structure
311  *----------------------------------------------------------------------------*/
312 
313 void
314 ple_locator_shift_locations(ple_locator_t *this_locator,
315  ple_lnum_t location_shift);
316 
317 /*----------------------------------------------------------------------------
318  * Return number of distant points after locator initialization.
319  *
320  * parameters:
321  * this_locator <-- pointer to locator structure
322  *
323  * returns:
324  * number of distant points.
325  *----------------------------------------------------------------------------*/
326 
327 ple_lnum_t
328 ple_locator_get_n_dist_points(const ple_locator_t *this_locator);
329 
330 /*----------------------------------------------------------------------------
331  * Return an array of local element numbers containing (or nearest to)
332  * each distant point after locator initialization.
333  *
334  * parameters:
335  * this_locator <-- pointer to locator structure
336  *
337  * returns:
338  * local element numbers associated with distant points.
339  *----------------------------------------------------------------------------*/
340 
341 const ple_lnum_t *
342 ple_locator_get_dist_locations(const ple_locator_t *this_locator);
343 
344 /*----------------------------------------------------------------------------
345  * Return an array of coordinates of each distant point after
346  * locator initialization.
347  *
348  * parameters:
349  * this_locator <-- pointer to locator structure
350  *
351  * returns:
352  * coordinate array associated with distant points (interlaced).
353  *----------------------------------------------------------------------------*/
354 
355 const ple_coord_t *
356 ple_locator_get_dist_coords(const ple_locator_t *this_locator);
357 
358 /*----------------------------------------------------------------------------
359  * Return number of points located after locator initialization.
360  *
361  * parameters:
362  * this_locator <-- pointer to locator structure
363  *
364  * returns:
365  * number of points located.
366  *----------------------------------------------------------------------------*/
367 
368 ple_lnum_t
369 ple_locator_get_n_interior(const ple_locator_t *this_locator);
370 
371 /*----------------------------------------------------------------------------
372  * Return list of points located after locator initialization.
373  * This list defines a subset of the point set used at initialization.
374  *
375  * parameters:
376  * this_locator <-- pointer to locator structure
377  *
378  * returns:
379  * list of points located.
380  *----------------------------------------------------------------------------*/
381 
382 const ple_lnum_t *
383 ple_locator_get_interior_list(const ple_locator_t *this_locator);
384 
385 /*----------------------------------------------------------------------------
386  * Return number of points not located after locator initialization.
387  *
388  * parameters:
389  * this_locator <-- pointer to locator structure
390  *
391  * returns:
392  * number of points not located.
393  *----------------------------------------------------------------------------*/
394 
395 ple_lnum_t
396 ple_locator_get_n_exterior(const ple_locator_t *this_locator);
397 
398 /*----------------------------------------------------------------------------
399  * Return list of points not located after locator initialization.
400  * This list defines a subset of the point set used at initialization.
401  *
402  * parameters:
403  * this_locator <-- pointer to locator structure
404  *
405  * returns:
406  * list of points not located.
407  *----------------------------------------------------------------------------*/
408 
409 const ple_lnum_t *
410 ple_locator_get_exterior_list(const ple_locator_t *this_locator);
411 
412 /*----------------------------------------------------------------------------
413  * Discard list of points not located after locator initialization.
414  * This list defines a subset of the point set used at initialization.
415  *
416  * parameters:
417  * this_locator <-- pointer to locator structure
418  *----------------------------------------------------------------------------*/
419 
420 void
421 ple_locator_discard_exterior(ple_locator_t *this_locator);
422 
423 /*----------------------------------------------------------------------------
424  * Distribute variable defined on distant points to processes owning
425  * the original points (i.e. distant processes).
426  *
427  * The exchange is symmetric if both variables are defined, receive
428  * only if distant_var is NULL, or send only if local_var is NULL.
429  *
430  * The caller should have defined the values of distant_var[] for the
431  * distant points, whose coordinates are given by
432  * ple_locator_get_dist_coords(), and which are located in the elements
433  * whose numbers are given by ple_locator_get_dist_locations().
434  *
435  * The local_var[] is defined at the located points (those whose
436  * numbers are returned by ple_locator_get_interior_list().
437  *
438  * If the optional local_list indirection is used, it is assumed to use
439  * the same base numbering as that defined by the options for the previous
440  * call to ple_locator_set_mesh() or ple_locator_extend_search().
441  *
442  * parameters:
443  * this_locator <-- pointer to locator structure
444  * distant_var <-> variable defined on distant points (ready to send)
445  * size: n_dist_points*stride
446  * local_var <-> variable defined on located local points (received)
447  * size: n_interior*stride
448  * local_list <-- optional indirection list for local_var
449  * type_size <-- sizeof (float or double) variable type
450  * stride <-- dimension (1 for scalar, 3 for interlaced vector)
451  * reverse <-- if nonzero, exchange is reversed
452  * (receive values associated with distant points
453  * from the processes owning the original points)
454  *----------------------------------------------------------------------------*/
455 
456 void
457 ple_locator_exchange_point_var(ple_locator_t *this_locator,
458  void *distant_var,
459  void *local_var,
460  const ple_lnum_t *local_list,
461  size_t type_size,
462  size_t stride,
463  int reverse);
464 
465 /*----------------------------------------------------------------------------
466  * Return timing information.
467  *
468  * In parallel mode, this includes communication time.
469  *
470  * parameters:
471  * this_locator <-- pointer to locator structure
472  * location_wtime --> Location Wall-clock time (or NULL)
473  * location_cpu_time --> Location CPU time (or NULL)
474  * exchange_wtime --> Variable exchange Wall-clock time (or NULL)
475  * exchange_cpu_time --> Variable exchange CPU time (or NULL)
476  *----------------------------------------------------------------------------*/
477 
478 void
479 ple_locator_get_times(const ple_locator_t *this_locator,
480  double *location_wtime,
481  double *location_cpu_time,
482  double *exchange_wtime,
483  double *exchange_cpu_time);
484 
485 /*----------------------------------------------------------------------------
486  * Return communication timing information.
487  *
488  * In serial mode, returned times are always zero..
489  *
490  * parameters:
491  * this_locator <-- pointer to locator structure
492  * location_wtime --> Location Wall-clock time (or NULL)
493  * location_cpu_time --> Location CPU time (or NULL)
494  * exchange_wtime --> Variable exchange Wall-clock time (or NULL)
495  * exchange_cpu_time --> Variable exchange CPU time (or NULL)
496  *----------------------------------------------------------------------------*/
497 
498 void
499 ple_locator_get_comm_times(const ple_locator_t *this_locator,
500  double *location_wtime,
501  double *location_cpu_time,
502  double *exchange_wtime,
503  double *exchange_cpu_time);
504 
505 /*----------------------------------------------------------------------------
506  * Dump printout of a locator structure.
507  *
508  * parameters:
509  * this_locator <-- pointer to structure that should be dumped
510  *----------------------------------------------------------------------------*/
511 
512 void
513 ple_locator_dump(const ple_locator_t *this_locator);
514 
515 /*----------------------------------------------------------------------------
516  * Get the maximum number of exchanging ranks for which we use asynchronous
517  * MPI sends and receives instead of MPI_SendRecv.
518  *
519  * returns:
520  * the maximum number of ranks allowing asynchronous exchanges
521  *----------------------------------------------------------------------------*/
522 
523 #if defined(PLE_HAVE_MPI)
524 
525 int
527 
528 #endif /* defined(PLE_HAVE_MPI) */
529 
530 /*----------------------------------------------------------------------------
531  * Set the maximum number of exchanging ranks for which we use asynchronous
532  * MPI sends and receives instead of MPI_SendRecv.
533  *
534  * parameters:
535  * threshold <-- maximum number of ranks allowing asynchronous exchanges
536  *----------------------------------------------------------------------------*/
537 
538 #if defined(PLE_HAVE_MPI)
539 
540 void
541 ple_locator_set_async_threshold(int threshold);
542 
543 #endif /* defined(PLE_HAVE_MPI) */
544 
545 /*----------------------------------------------------------------------------
546  * Register communication logging functions for locator instrumentation.
547  *
548  * By default, locators are not instrumented.
549  *
550  * Functions using MPE may be defined and used, but other similar systems
551  * may be used.
552  *
553  * parameters:
554  * fct <-- pointer to logging function
555  * start_p_comm <-- point to point communication start event number
556  * end_p_comm <-- point to point communication end event number
557  * start_g_comm <-- global communication start event number
558  * end_g_comm <-- global communication end event number
559  *----------------------------------------------------------------------------*/
560 
561 #if defined(PLE_HAVE_MPI)
562 
563 void
564 ple_locator_set_comm_log(ple_locator_log_t *log_function,
565  int start_p_comm,
566  int end_p_comm,
567  int start_g_comm,
568  int end_g_comm);
569 
570 #endif /* defined(PLE_HAVE_MPI) */
571 
572 /*----------------------------------------------------------------------------*/
573 
574 #ifdef __cplusplus
575 }
576 #endif /* __cplusplus */
577 
578 #endif /* __PLE_LOCATOR_H__ */
ple_locator_t * ple_locator_create(MPI_Comm comm, int n_ranks, int start_rank)
Creation of a locator structure.
Definition: ple_locator.c:2508
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 poi...
Definition: ple_locator.c:3117
ple_lnum_t ple_locator_get_n_dist_points(const ple_locator_t *this_locator)
Return number of distant points after locator initialization.
Definition: ple_locator.c:2991
void ple_locator_set_async_threshold(int threshold)
Set the maximum number of exchanging ranks for which we use asynchronous MPI sends and receives inste...
Definition: ple_locator.c:3507
void ple_locator_dump(const ple_locator_t *this_locator)
Dump printout of a locator structure.
Definition: ple_locator.c:3328
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.
Definition: ple_locator.c:2728
int ple_locator_get_async_threshold(void)
Get the maximum number of exchanging ranks for which we use asynchronous MPI sends and receives inste...
Definition: ple_locator.c:3492
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.
Definition: ple_locator.c:3039
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.
Definition: ple_locator.c:2638
ple_lnum_t ple_locator_get_n_exterior(const ple_locator_t *this_locator)
Return number of points not located after locator initialization.
Definition: ple_locator.c:3100
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...
Definition: ple_locator.c:3174
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.
Definition: ple_locator.c:3530
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.
Definition: ple_locator.c:3274
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 s...
Definition: ple_locator.c:3084
ple_locator_t * ple_locator_destroy(ple_locator_t *this_locator)
Destruction of a locator structure.
Definition: ple_locator.c:2579
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 ...
Definition: ple_locator.c:3015
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 po...
Definition: ple_locator.c:3132
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.
Definition: ple_locator.c:3307
void ple_locator_shift_locations(ple_locator_t *this_locator, ple_lnum_t location_shift)
Shift location ids for located points after locator initialization.
Definition: ple_locator.c:2968
ple_lnum_t ple_locator_get_n_interior(const ple_locator_t *this_locator)
Return number of points located after locator initialization.
Definition: ple_locator.c:3062