8.3
general documentation
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-2024 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
41
42/*============================================================================
43 * Macro definitions
44 *============================================================================*/
45
46/*============================================================================
47 * Type definitions
48 *============================================================================*/
49
50typedef 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
69fvm_neighborhood_create(MPI_Comm comm);
70
71#else
72
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
85void
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
102void
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
125void
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
150void
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 transferred to the neighborhood management
162 * structure: both the box_gnum and extents arguments have an "assigned"
163 * variant, in which case 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_assigned <-> as box_gnum, ownership transferred (NULL on return)
184 * extents_assigned <-> as extents, ownership transferred (NULL on return)
185 *---------------------------------------------------------------------------*/
186
187void
189 int dim,
190 cs_lnum_t n_boxes,
191 const cs_gnum_t *box_gnum,
192 const cs_coord_t *extents,
193 cs_gnum_t **box_gnum_assigned,
194 cs_coord_t **extents_assigned);
195
196/*----------------------------------------------------------------------------
197 * Prune a neighborhood (remove entries with no neighbors).
198 *
199 * parameters:
200 * n <-> pointer to neighborhood management structure
201 *----------------------------------------------------------------------------*/
202
203void
205
206/*----------------------------------------------------------------------------
207 * Get global statistics relative to the search structures used
208 * by fvm_neighborhood_by_boxes().
209 *
210 * All fields returned are optional: if their argument is set to NULL,
211 * the corresponding information will not be returned.
212 *
213 * For each field not set to NULL, 3 values are always returned:
214 * the mean on all ranks (rounded to the closest integer), the minimum,
215 * and the maximum value respectively.
216 *
217 * In serial mode, the mean, minimum, and maximum will be identical for most
218 * fields, but all 3 values are returned nonetheless.
219 *
220 * Note that the final memory use is only relative to the final search
221 * structure, and the comparison of the total (or average) with the minima
222 * and maxima may give an indication on load balancing.
223
224 * The mem_required field only takes into account the theoretical maximum
225 * memory footprint of the main search structure during its construction phase,
226 * and of that of temporary structures before load balancing in parallel mode,
227 * but does not include minor work arrays or buffers used during the algorithm.
228 *
229 * Neither of the 2 memory fields include the footprint of the arrays
230 * containing the query results.
231 *
232 * parameters:
233 * n <-- pointer to neighborhood management structure
234 * depth --> tree depth (max level used)
235 * n_leaves --> number of leaves in the tree
236 * n_boxes --> number of boxes in the tree
237 * n_threshold_leaves --> number of leaves where n_boxes > threshold
238 * n_leaf_boxes --> number of boxes for a leaf
239 * mem_final --> theoretical memory for final search structure
240 * mem_required --> theoretical maximum memory for main structures
241 * used during the algorithm
242 *
243 * returns:
244 * the spatial dimension associated with the box tree layout (3, 2, or 1)
245 *----------------------------------------------------------------------------*/
246
247int
249 int depth[3],
250 cs_lnum_t n_leaves[3],
251 cs_lnum_t n_boxes[3],
252 cs_lnum_t n_threshold_leaves[3],
253 cs_lnum_t n_leaf_boxes[3],
254 size_t mem_final[3],
255 size_t mem_required[3]);
256
257/*----------------------------------------------------------------------------
258 * Return timing information.
259 *
260 * parameters:
261 * n <-- pointer to neighborhood management structure
262 * build_wtime --> initialization Wall-clock time (or NULL)
263 * build_cpu_time --> initialization CPU time (or NULL)
264 * query_wtime --> query Wall-clock time (or NULL)
265 * query_cpu_time --> query CPU time (or NULL)
266 *----------------------------------------------------------------------------*/
267
268void
270 double *build_wtime,
271 double *build_cpu_time,
272 double *query_wtime,
273 double *query_cpu_time);
274
275/*----------------------------------------------------------------------------
276 * Dump a neighborhood management structure.
277 *
278 * parameters:
279 * n <-- pointer to neighborhood management structure
280 *----------------------------------------------------------------------------*/
281
282void
284
285/*----------------------------------------------------------------------------*/
286
288
289#endif /* __FVM_NEIGHBORHOOD_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
double cs_coord_t
Definition: cs_defs.h:340
uint64_t cs_gnum_t
global mesh entity number
Definition: cs_defs.h:325
#define END_C_DECLS
Definition: cs_defs.h:543
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:335
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.cpp:830
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.cpp:1134
void fvm_neighborhood_prune(fvm_neighborhood_t *n)
Definition: fvm_neighborhood.cpp:997
void fvm_neighborhood_destroy(fvm_neighborhood_t **n)
Definition: fvm_neighborhood.cpp:669
fvm_neighborhood_t * fvm_neighborhood_create(void)
Definition: fvm_neighborhood.cpp:612
struct _fvm_neighborhood_t fvm_neighborhood_t
Definition: fvm_neighborhood.h:50
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.cpp:1082
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.cpp:773
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.cpp:732
void fvm_neighborhood_dump(const fvm_neighborhood_t *n)
Definition: fvm_neighborhood.cpp:1162
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.cpp:700