programmer's documentation
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
src
fvm
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-2013 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
#include "
cs_defs.h
"
31
32
/*----------------------------------------------------------------------------
33
* Local headers
34
*----------------------------------------------------------------------------*/
35
36
#include "
fvm_defs.h
"
37
38
/*----------------------------------------------------------------------------*/
39
40
BEGIN_C_DECLS
41
42
/*============================================================================
43
* Macro definitions
44
*============================================================================*/
45
46
/*============================================================================
47
* Type definitions
48
*============================================================================*/
49
50
typedef
struct
_fvm_neighborhood_t fvm_neighborhood_t;
51
52
/*============================================================================
53
* Public function definitions
54
*============================================================================*/
55
56
/*----------------------------------------------------------------------------
57
* Create a neighborhood_t structure and initialize it.
58
*
59
* parameters:
60
* comm <-- associated MPI communicator
61
*
62
* returns:
63
* pointer to an empty fvm_box_tree_t structure.
64
*----------------------------------------------------------------------------*/
65
66
#if defined(HAVE_MPI)
67
68
fvm_neighborhood_t *
69
fvm_neighborhood_create
(MPI_Comm comm);
70
71
#else
72
73
fvm_neighborhood_t *
74
fvm_neighborhood_create
(
void
);
75
76
#endif
77
78
/*----------------------------------------------------------------------------
79
* Destroy a neighborhood_t structure.
80
*
81
* parameters:
82
* n <-> pointer to pointer to fvm_neighborhood_t structure to destroy.
83
*----------------------------------------------------------------------------*/
84
85
void
86
fvm_neighborhood_destroy
(fvm_neighborhood_t **n);
87
88
/*----------------------------------------------------------------------------
89
* Set non-default algorithm parameters for neighborhood management structure.
90
*
91
* parameters:
92
* n <-> pointer to neighborhood management structure
93
* max_tree_depth <-- maximum search tree depth
94
* leaf_threshold <-- maximum number of boxes which can be related to
95
* a leaf of the tree if level < max_tree_depth
96
* max_box_ratio <-- stop adding levels to tree when
97
* (n_linked_boxes > max_box_ratio*n_init_boxes)
98
* max_box_ratio_distrib <-- maximum box ratio when computing coarse
99
* tree prior to parallel distribution
100
*---------------------------------------------------------------------------*/
101
102
void
103
fvm_neighborhood_set_options
(fvm_neighborhood_t *n,
104
int
max_tree_depth,
105
int
leaf_threshold,
106
float
max_box_ratio,
107
float
max_box_ratio_distrib);
108
109
/*----------------------------------------------------------------------------
110
* Retrieve pointers to of arrays from a neighborhood_t structure.
111
*
112
* Arrays remain the property of the neighborhood_t structure, and must not
113
* be modified by the caller.
114
*
115
* parameters:
116
* n <-> pointer to fvm_neighborhood_t structure.
117
* n_elts --> number of elements with neighbors in block
118
* associated with local rank
119
* elt_num --> global element numbers in local block (size: n_elts)
120
* neighbor_index --> start index of neighbors (size: n_elts + 1)
121
* neighbor_num --> global element neighbor numbers
122
* (size: neighbor_index[n_elts])
123
*----------------------------------------------------------------------------*/
124
125
void
126
fvm_neighborhood_get_data
(
const
fvm_neighborhood_t *n,
127
cs_lnum_t
*n_elts,
128
cs_gnum_t
**
const
elt_num,
129
cs_lnum_t
**
const
neighbor_index,
130
cs_gnum_t
**
const
neighbor_num);
131
132
/*----------------------------------------------------------------------------
133
* Transfer ownership of arrays from a neighborhood_t structure to the
134
* calling program.
135
*
136
* Arrays that are transferred are removed from the structure, so its
137
* use after calling this function is limited to querying timing information
138
* until a new neighborhood is computed.
139
*
140
* parameters:
141
* n <-> pointer to fvm_neighborhood_t structure.
142
* n_elts --> number of elements with neighbors in block
143
* associated with local rank
144
* elt_num --> global element numbers in local block (size: n_elts)
145
* neighbor_index --> start index of neighbors (size: n_elts + 1)
146
* neighbor_num --> global element neighbor numbers
147
* (size: neighbor_index[n_elts])
148
*----------------------------------------------------------------------------*/
149
150
void
151
fvm_neighborhood_transfer_data
(fvm_neighborhood_t *n,
152
cs_lnum_t
*n_elts,
153
cs_gnum_t
**elt_num,
154
cs_lnum_t
**neighbor_index,
155
cs_gnum_t
**neighbor_num);
156
157
/*----------------------------------------------------------------------------
158
* Determine intersecting boxes.
159
*
160
* Box global numbers and extents may be either copied for the structure's
161
* internal use from the caller, or tranferred to the neighborhood management
162
* structure: both the box_gnum and extents arguments have an "assigned"
163
* variant, in which cas a pointer to a pointer is provided, and the
164
* argument's property is transferred to the neighborhod management structure.
165
* The unused variant of an argument should be set to NULL.
166
*
167
* Boxes may be distributed among processors, so their intersections are
168
* determined using a block distribution, and defined using their
169
* global numbers.
170
*
171
* All global numbers appearing in box_gnum[] will have a matching entry in
172
* the neighborhod structure. To remove global numbers entries with no
173
* neighbors from the structure, the fvm_neighborhood_prune() function
174
* may be used.
175
*
176
* parameters:
177
* n <-> pointer to neighborhood management structure
178
* dim <-- spatial dimension
179
* n_boxes <-- local number of boxes
180
* box_gnum <-- global numbering of boxes
181
* extents <-- coordinate extents (size: n_boxes*dim*2, as
182
* xmin1, ymin1, .. xmax1, ymax1, ..., xmin2, ...)
183
* box_gnum_transfer <-> as box_gnum, ownership transferred (NULL on return)
184
* extents_transfer <-> as extents, ownership transferred (NULL on return)
185
* comm <-- associated MPI communicator
186
*---------------------------------------------------------------------------*/
187
188
void
189
fvm_neighborhood_by_boxes
(fvm_neighborhood_t *n,
190
int
dim,
191
cs_lnum_t
n_boxes,
192
const
cs_gnum_t
*box_gnum,
193
const
cs_coord_t
*extents,
194
cs_gnum_t
**box_gnum_assigned,
195
cs_coord_t
**extents_assigned);
196
197
/*----------------------------------------------------------------------------
198
* Prune a neighborhood (remove entries with no neighbors).
199
*
200
* parameters:
201
* n <-> pointer to neighborhood management structure
202
*----------------------------------------------------------------------------*/
203
204
void
205
fvm_neighborhood_prune
(fvm_neighborhood_t *n);
206
207
/*----------------------------------------------------------------------------
208
* Get global statistics relative to the search structures used
209
* by fvm_neighborhood_by_boxes().
210
*
211
* All fields returned are optional: if their argument is set to NULL,
212
* the corresponding information will not be returned.
213
*
214
* For each field not set to NULL, 3 values are always returned:
215
* the mean on all ranks (rounded to the closest integer), the minimum,
216
* and the maximum value respectively.
217
*
218
* In serial mode, the mean, minimum, and maximum will be identical for most
219
* fields, but all 3 values are returned nonetheless.
220
*
221
* Note that the final memory use is only relative to the final search
222
* structure, and the comparison of the total (or average) with the minima
223
* and maxima may give an indication on load balancing.
224
225
* The mem_required field only takes into account the theoretical maximum
226
* memory footprint of the main search structure during its construction phase,
227
* and of that of temporary structures before load balancing in parallel mode,
228
* but does not include minor work arrays or buffers used during the algorithm.
229
*
230
* Neither of the 2 memory fields include the footprint of the arrays
231
* containing the query results.
232
*
233
* parameters:
234
* n <-- pointer to neighborhood management structure
235
* dim --> layout dimension (3, 2, or 1)
236
* depth --> tree depth (max level used)
237
* n_leaves --> number of leaves in the tree
238
* n_boxes --> number of boxes in the tree
239
* n_threshold_leaves --> number of leaves where n_boxes > threshold
240
* n_leaf_boxes --> number of boxes for a leaf
241
* mem_final --> theoretical memory for final search structure
242
* mem_required --> theoretical maximum memory for main structures
243
* used during the algorithm
244
*
245
* returns:
246
* the spatial dimension associated with the box tree layout (3, 2, or 1)
247
*----------------------------------------------------------------------------*/
248
249
int
250
fvm_neighborhood_get_box_stats
(
const
fvm_neighborhood_t *n,
251
int
depth[3],
252
cs_lnum_t
n_leaves[3],
253
cs_lnum_t
n_boxes[3],
254
cs_lnum_t
n_threshold_leaves[3],
255
cs_lnum_t
n_leaf_boxes[3],
256
size_t
mem_final[3],
257
size_t
mem_required[3]);
258
259
/*----------------------------------------------------------------------------
260
* Return timing information.
261
*
262
* parameters:
263
* n <-- pointer to neighborhood management structure
264
* build_wtime --> initialization Wall-clock time (or NULL)
265
* build_cpu_time --> initialization CPU time (or NULL)
266
* query_wtime --> query Wall-clock time (or NULL)
267
* query_cpu_time --> query CPU time (or NULL)
268
*----------------------------------------------------------------------------*/
269
270
void
271
fvm_neighborhood_get_times
(
const
fvm_neighborhood_t *n,
272
double
*build_wtime,
273
double
*build_cpu_time,
274
double
*query_wtime,
275
double
*query_cpu_time);
276
277
/*----------------------------------------------------------------------------
278
* Dump a neighborhood management structure.
279
*
280
* parameters:
281
* n <-- pointer to neighborhood management structure
282
*----------------------------------------------------------------------------*/
283
284
void
285
fvm_neighborhood_dump
(
const
fvm_neighborhood_t *n);
286
287
/*----------------------------------------------------------------------------*/
288
289
END_C_DECLS
290
291
#endif
/* __FVM_NEIGHBORHOOD_H__ */
Generated on Thu Feb 27 2014 19:21:34 by
1.8.3.1