Code_Saturne
CFD tool
fvm_neighborhood.h
Go to the documentation of this file.
1 #ifndef __FVM_NEIGHBORHOOD_H__
2 #define __FVM_NEIGHBORHOOD_H__
3 
4 /*============================================================================
5  * Search octrees and quadtrees of boxes.
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2012 EDF S.A.
12 
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
16  version.
17 
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
21  details.
22 
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.
26 */
27 
28 /*----------------------------------------------------------------------------*/
29 
30 #if defined(HAVE_MPI)
31 #include <mpi.h>
32 #endif
33 
34 /*----------------------------------------------------------------------------
35  * Local headers
36  *----------------------------------------------------------------------------*/
37 
38 #include "fvm_defs.h"
39 
40 /*----------------------------------------------------------------------------*/
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #if 0
45 } /* Fake brace to */
46 #endif
47 #endif /* __cplusplus */
48 
49 /*============================================================================
50  * Macro definitions
51  *============================================================================*/
52 
53 /*============================================================================
54  * Type definitions
55  *============================================================================*/
56 
58 
59 /*============================================================================
60  * Public function definitions
61  *============================================================================*/
62 
63 /*----------------------------------------------------------------------------
64  * Create a neighborhood_t structure and initialize it.
65  *
66  * parameters:
67  * comm <-- associated MPI communicator
68  *
69  * returns:
70  * pointer to an empty fvm_box_tree_t structure.
71  *----------------------------------------------------------------------------*/
72 
73 #if defined(HAVE_MPI)
74 
76 fvm_neighborhood_create(MPI_Comm comm);
77 
78 #else
79 
82 
83 #endif
84 
85 /*----------------------------------------------------------------------------
86  * Destroy a neighborhood_t structure.
87  *
88  * parameters:
89  * n <-> pointer to pointer to fvm_neighborhood_t structure to destroy.
90  *----------------------------------------------------------------------------*/
91 
92 void
94 
95 /*----------------------------------------------------------------------------
96  * Set non-default algorithm parameters for neighborhood management structure.
97  *
98  * parameters:
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  *---------------------------------------------------------------------------*/
108 
109 void
111  int max_tree_depth,
112  int leaf_threshold,
113  float max_box_ratio,
114  float max_box_ratio_distrib);
115 
116 /*----------------------------------------------------------------------------
117  * Retrieve pointers to of arrays from a neighborhood_t structure.
118  *
119  * Arrays remain the property of the neighborhood_t structure, and must not
120  * be modified by the caller.
121  *
122  * parameters:
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  *----------------------------------------------------------------------------*/
131 
132 void
134  cs_lnum_t *n_elts,
135  cs_gnum_t **const elt_num,
136  cs_lnum_t **const neighbor_index,
137  cs_gnum_t **const neighbor_num);
138 
139 /*----------------------------------------------------------------------------
140  * Transfer ownership of arrays from a neighborhood_t structure to the
141  * calling program.
142  *
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.
146  *
147  * parameters:
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  *----------------------------------------------------------------------------*/
156 
157 void
159  cs_lnum_t *n_elts,
160  cs_gnum_t **elt_num,
163 
164 /*----------------------------------------------------------------------------
165  * Determine intersecting boxes.
166  *
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.
173  *
174  * Boxes may be distributed among processors, so their intersections are
175  * determined using a block distribution, and defined using their
176  * global numbers.
177  *
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
181  * may be used.
182  *
183  * parameters:
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  *---------------------------------------------------------------------------*/
194 
195 void
197  int dim,
198  cs_lnum_t n_boxes,
199  const cs_gnum_t *box_gnum,
200  const cs_coord_t *extents,
201  cs_gnum_t **box_gnum_assigned,
202  cs_coord_t **extents_assigned);
203 
204 /*----------------------------------------------------------------------------
205  * Prune a neighborhood (remove entries with no neighbors).
206  *
207  * parameters:
208  * n <-> pointer to neighborhood management structure
209  *----------------------------------------------------------------------------*/
210 
211 void
213 
214 /*----------------------------------------------------------------------------
215  * Get global statistics relative to the search structures used
216  * by fvm_neighborhood_by_boxes().
217  *
218  * All fields returned are optional: if their argument is set to NULL,
219  * the corresponding information will not be returned.
220  *
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.
224  *
225  * In serial mode, the mean, minimum, and maximum will be identical for most
226  * fields, but all 3 values are returned nonetheless.
227  *
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.
231 
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.
236  *
237  * Neither of the 2 memory fields include the footprint of the arrays
238  * containing the query results.
239  *
240  * parameters:
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
251  *
252  * returns:
253  * the spatial dimension associated with the box tree layout (3, 2, or 1)
254  *----------------------------------------------------------------------------*/
255 
256 int
258  int depth[3],
259  cs_lnum_t n_leaves[3],
260  cs_lnum_t n_boxes[3],
261  cs_lnum_t n_threshold_leaves[3],
262  cs_lnum_t n_leaf_boxes[3],
263  size_t mem_final[3],
264  size_t mem_required[3]);
265 
266 /*----------------------------------------------------------------------------
267  * Return timing information.
268  *
269  * parameters:
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  *----------------------------------------------------------------------------*/
276 
277 void
279  double *build_wtime,
280  double *build_cpu_time,
281  double *query_wtime,
282  double *query_cpu_time);
283 
284 /*----------------------------------------------------------------------------
285  * Dump a neighborhood management structure.
286  *
287  * parameters:
288  * n <-- pointer to neighborhood management structure
289  *----------------------------------------------------------------------------*/
290 
291 void
293 
294 /*----------------------------------------------------------------------------*/
295 
296 #ifdef __cplusplus
297 }
298 #endif /* __cplusplus */
299 
300 #endif /* __FVM_NEIGHBORHOOD_H__ */
float max_box_ratio
Definition: fvm_neighborhood.c:116
void fvm_neighborhood_get_data(const fvm_neighborhood_t *n, cs_lnum_t *n_elts, cs_gnum_t **const elt_num, cs_lnum_t **const neighbor_index, cs_gnum_t **const neighbor_num)
Definition: fvm_neighborhood.c:766
int fvm_neighborhood_get_box_stats(const fvm_neighborhood_t *n, int depth[3], cs_lnum_t n_leaves[3], cs_lnum_t n_boxes[3], cs_lnum_t n_threshold_leaves[3], cs_lnum_t n_leaf_boxes[3], size_t mem_final[3], size_t mem_required[3])
Definition: fvm_neighborhood.c:1116
void fvm_neighborhood_set_options(fvm_neighborhood_t *n, int max_tree_depth, int leaf_threshold, float max_box_ratio, float max_box_ratio_distrib)
Definition: fvm_neighborhood.c:734
fvm_neighborhood_t * fvm_neighborhood_create(void)
Definition: fvm_neighborhood.c:646
void fvm_neighborhood_destroy(fvm_neighborhood_t **n)
Definition: fvm_neighborhood.c:703
void fvm_neighborhood_prune(fvm_neighborhood_t *n)
Definition: fvm_neighborhood.c:1031
int max_tree_depth
Definition: fvm_neighborhood.c:112
cs_lnum_t n_elts
Definition: fvm_neighborhood.c:96
void fvm_neighborhood_get_times(const fvm_neighborhood_t *n, double *build_wtime, double *build_cpu_time, double *query_wtime, double *query_cpu_time)
Definition: fvm_neighborhood.c:1168
float max_box_ratio_distrib
Definition: fvm_neighborhood.c:119
double cs_coord_t
Definition: cs_defs.h:261
cs_gnum_t * neighbor_num
Definition: fvm_neighborhood.c:103
int cs_lnum_t
Definition: cs_defs.h:260
cs_lnum_t * neighbor_index
Definition: fvm_neighborhood.c:101
cs_gnum_t * elt_num
Definition: fvm_neighborhood.c:98
unsigned cs_gnum_t
Definition: cs_defs.h:255
int leaf_threshold
Definition: fvm_neighborhood.c:113
void fvm_neighborhood_transfer_data(fvm_neighborhood_t *n, cs_lnum_t *n_elts, cs_gnum_t **elt_num, cs_lnum_t **neighbor_index, cs_gnum_t **neighbor_num)
Definition: fvm_neighborhood.c:807
void fvm_neighborhood_dump(const fvm_neighborhood_t *n)
Definition: fvm_neighborhood.c:1196
Definition: fvm_neighborhood.c:94
void fvm_neighborhood_by_boxes(fvm_neighborhood_t *n, int dim, cs_lnum_t n_boxes, const cs_gnum_t *box_gnum, const cs_coord_t *extents, cs_gnum_t **box_gnum_assigned, cs_coord_t **extents_assigned)
Definition: fvm_neighborhood.c:865