1
#ifndef __FVM_NEIGHBORHOOD_H__
2
#define __FVM_NEIGHBORHOOD_H__
4
/*============================================================================
5
* Search octrees and quadtrees of boxes.
6
*============================================================================*/
9
This file is part of Code_Saturne, a general-purpose CFD tool.
11
Copyright (C) 1998-2011 EDF S.A.
13
This program is free software; you can redistribute it and/or modify it under
14
the terms of the GNU General Public License as published by the Free Software
15
Foundation; either version 2 of the License, or (at your option) any later
18
This program is distributed in the hope that it will be useful, but WITHOUT
19
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
23
You should have received a copy of the GNU General Public License along with
24
this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25
Street, Fifth Floor, Boston, MA 02110-1301, USA.
28
/*----------------------------------------------------------------------------*/
34
/*----------------------------------------------------------------------------
36
*----------------------------------------------------------------------------*/
40
/*----------------------------------------------------------------------------*/
47
#endif /* __cplusplus */
49
/*============================================================================
51
*============================================================================*/
53
/*============================================================================
55
*============================================================================*/
57
typedef struct _fvm_neighborhood_t fvm_neighborhood_t;
59
/*============================================================================
60
* Public function definitions
61
*============================================================================*/
63
/*----------------------------------------------------------------------------
64
* Create a neighborhood_t structure and initialize it.
67
* comm <-- associated MPI communicator
70
* pointer to an empty fvm_box_tree_t structure.
71
*----------------------------------------------------------------------------*/
76
fvm_neighborhood_create(MPI_Comm comm);
81
fvm_neighborhood_create(void);
85
/*----------------------------------------------------------------------------
86
* Destroy a neighborhood_t structure.
89
* n <-> pointer to pointer to fvm_neighborhood_t structure to destroy.
90
*----------------------------------------------------------------------------*/
93
fvm_neighborhood_destroy(fvm_neighborhood_t **n);
95
/*----------------------------------------------------------------------------
96
* Set non-default algorithm parameters for neighborhood management structure.
99
* n <-> pointer to neighborhood management structure
100
* max_tree_depth <-- maximum search tree depth
101
* leaf_threshold <-- maximum number of boxes which can be related to
102
* a leaf of the tree if level < max_tree_depth
103
* max_box_ratio <-- stop adding levels to tree when
104
* (n_linked_boxes > max_box_ratio*n_init_boxes)
105
* max_box_ratio_distrib <-- maximum box ratio when computing coarse
106
* tree prior to parallel distribution
107
*---------------------------------------------------------------------------*/
110
fvm_neighborhood_set_options(fvm_neighborhood_t *n,
114
float max_box_ratio_distrib);
116
/*----------------------------------------------------------------------------
117
* Retrieve pointers to of arrays from a neighborhood_t structure.
119
* Arrays remain the property of the neighborhood_t structure, and must not
120
* be modified by the caller.
123
* n <-> pointer to fvm_neighborhood_t structure.
124
* n_elts --> number of elements with neighbors in block
125
* associated with local rank
126
* elt_num --> global element numbers in local block (size: n_elts)
127
* neighbor_index --> start index of neighbors (size: n_elts + 1)
128
* neighbor_num --> global element neighbor numbers
129
* (size: neighbor_index[n_elts])
130
*----------------------------------------------------------------------------*/
133
fvm_neighborhood_get_data(const fvm_neighborhood_t *n,
135
fvm_gnum_t **const elt_num,
136
fvm_lnum_t **const neighbor_index,
137
fvm_gnum_t **const neighbor_num);
139
/*----------------------------------------------------------------------------
140
* Transfer ownership of arrays from a neighborhood_t structure to the
143
* Arrays that are transferred are removed from the structure, so its
144
* use after calling this function is limited to querying timing information
145
* until a new neighborhood is computed.
148
* n <-> pointer to fvm_neighborhood_t structure.
149
* n_elts --> number of elements with neighbors in block
150
* associated with local rank
151
* elt_num --> global element numbers in local block (size: n_elts)
152
* neighbor_index --> start index of neighbors (size: n_elts + 1)
153
* neighbor_num --> global element neighbor numbers
154
* (size: neighbor_index[n_elts])
155
*----------------------------------------------------------------------------*/
158
fvm_neighborhood_transfer_data(fvm_neighborhood_t *n,
160
fvm_gnum_t **elt_num,
161
fvm_lnum_t **neighbor_index,
162
fvm_gnum_t **neighbor_num);
164
/*----------------------------------------------------------------------------
165
* Determine intersecting boxes.
167
* Box global numbers and extents may be either copied for the structure's
168
* internal use from the caller, or tranferred to the neighborhood management
169
* structure: both the box_gnum and extents arguments have an "assigned"
170
* variant, in which cas a pointer to a pointer is provided, and the
171
* argument's property is transferred to the neighborhod management structure.
172
* The unused variant of an argument should be set to NULL.
174
* Boxes may be distributed among processors, so their intersections are
175
* determined using a block distribution, and defined using their
178
* All global numbers appearing in box_gnum[] will have a matching entry in
179
* the neighborhod structure. To remove global numbers entries with no
180
* neighbors from the structure, the fvm_neighborhood_prune() function
184
* n <-> pointer to neighborhood management structure
185
* dim <-- spatial dimension
186
* n_boxes <-- local number of boxes
187
* box_gnum <-- global numbering of boxes
188
* extents <-- coordinate extents (size: n_boxes*dim*2, as
189
* xmin1, ymin1, .. xmax1, ymax1, ..., xmin2, ...)
190
* box_gnum_transfer <-> as box_gnum, ownership transferred (NULL on return)
191
* extents_transfer <-> as extents, ownership transferred (NULL on return)
192
* comm <-- associated MPI communicator
193
*---------------------------------------------------------------------------*/
196
fvm_neighborhood_by_boxes(fvm_neighborhood_t *n,
199
const fvm_gnum_t *box_gnum,
200
const fvm_coord_t *extents,
201
fvm_gnum_t **box_gnum_assigned,
202
fvm_coord_t **extents_assigned);
204
/*----------------------------------------------------------------------------
205
* Prune a neighborhood (remove entries with no neighbors).
208
* n <-> pointer to neighborhood management structure
209
*----------------------------------------------------------------------------*/
212
fvm_neighborhood_prune(fvm_neighborhood_t *n);
214
/*----------------------------------------------------------------------------
215
* Get global statistics relative to the search structures used
216
* by fvm_neighborhood_by_boxes().
218
* All fields returned are optional: if their argument is set to NULL,
219
* the corresponding information will not be returned.
221
* For each field not set to NULL, 3 values are always returned:
222
* the mean on all ranks (rounded to the closest integer), the minimum,
223
* and the maximum value respectively.
225
* In serial mode, the mean, minimum, and maximum will be identical for most
226
* fields, but all 3 values are returned nonetheless.
228
* Note that the final memory use is only relative to the final search
229
* structure, and the comparison of the total (or average) with the minima
230
* and maxima may give an indication on load balancing.
232
* The mem_required field only takes into account the theoretical maximum
233
* memory footprint of the main search structure during its construction phase,
234
* and of that of temporary structures before load balancing in parallel mode,
235
* but does not include minor work arrays or buffers used during the algorithm.
237
* Neither of the 2 memory fields include the footprint of the arrays
238
* containing the query results.
241
* n <-- pointer to neighborhood management structure
242
* dim --> layout dimension (3, 2, or 1)
243
* depth --> tree depth (max level used)
244
* n_leaves --> number of leaves in the tree
245
* n_boxes --> number of boxes in the tree
246
* n_threshold_leaves --> number of leaves where n_boxes > threshold
247
* n_leaf_boxes --> number of boxes for a leaf
248
* mem_final --> theoretical memory for final search structure
249
* mem_required --> theoretical maximum memory for main structures
250
* used during the algorithm
253
* the spatial dimension associated with the box tree layout (3, 2, or 1)
254
*----------------------------------------------------------------------------*/
257
fvm_neighborhood_get_box_stats(const fvm_neighborhood_t *n,
259
fvm_lnum_t n_leaves[3],
260
fvm_lnum_t n_boxes[3],
261
fvm_lnum_t n_threshold_leaves[3],
262
fvm_lnum_t n_leaf_boxes[3],
264
size_t mem_required[3]);
266
/*----------------------------------------------------------------------------
267
* Return timing information.
270
* n <-- pointer to neighborhood management structure
271
* build_wtime --> initialization Wall-clock time (or NULL)
272
* build_cpu_time --> initialization CPU time (or NULL)
273
* query_wtime --> query Wall-clock time (or NULL)
274
* query_cpu_time --> query CPU time (or NULL)
275
*----------------------------------------------------------------------------*/
278
fvm_neighborhood_get_times(const fvm_neighborhood_t *n,
280
double *build_cpu_time,
282
double *query_cpu_time);
284
/*----------------------------------------------------------------------------
285
* Dump a neighborhood management structure.
288
* n <-- pointer to neighborhood management structure
289
*----------------------------------------------------------------------------*/
292
fvm_neighborhood_dump(const fvm_neighborhood_t *n);
294
/*----------------------------------------------------------------------------*/
298
#endif /* __cplusplus */
300
#endif /* __FVM_NEIGHBORHOOD_H__ */
added
removed
src/fvm/fvm_neighborhood.h
