src/mesh/cs_partition.h Source File

| 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
cs_partition.h
Go to the documentation of this file.
1 #ifndef __CS_PARTITION_H__
2 #define __CS_PARTITION_H__
3
4 /*============================================================================
5 * Define cs_mesh_t fields from cs_mesh_builder_t fields.
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 /*----------------------------------------------------------------------------
31 * Local headers
32 *----------------------------------------------------------------------------*/
33
34 #include "cs_defs.h"
35
36 #include "cs_base.h"
37
38 #include "cs_mesh.h"
39 #include "cs_mesh_builder.h"
40
41 /*----------------------------------------------------------------------------*/
42
43 BEGIN_C_DECLS
44
45 /*=============================================================================
46 * Macro definitions
47 *============================================================================*/
48
49 /*============================================================================
50 * Type definitions
51 *============================================================================*/
52
53 /* Partitioning stage
54 *
55 * Partitioning is always done just after reading the mesh, unless a
56 * partitioning input file is available, in which case the partitioning
57 * read replaces this stage.
58 *
59 * When a mesh modification implying a change of cell connectivity graph
60 * is expected, the mesh may be re-partitioned after the pre-processing
61 * stage, prior to calculation. By default, re-partitioning is only done
62 * if the partitioning algorithm chosen for that stage is expected to
63 * produce different results due to the connectivity change. This is
64 * the case for graph-based algorithms such as those of METIS or SCOTCH,
65 * when mesh joining is defined, or additional periodic matching is defined
66 * (and the algorithm is not configured to ignore periodicity information).
67 *
68 * There are thus two possible partitioning stages:
69 *
70 * - CS_PARTITION_FOR_PREPROCESS, which is optional, and occurs
71 * just after reading the mesh.
72 * - CS_PARTITION_MAIN, which occurs just after reading the mesh if
73 * it is the only stage,, or after mesh preprocessing (and before
74 * computation), if the partitioning for preprocessing stage is
75 * activated.
76 *
77 * The number of partitioning stages is determined automatically based on
78 * information provided through cs_partition_set_preprocess_hints(),
79 * but re-partitioning may also be forced or inhibited using the
80 * cs_partition_set_preprocess() function.
81 */
82
83 typedef enum {
84
85 CS_PARTITION_FOR_PREPROCESS, /* Partitioning for preprocessing stage */
86 CS_PARTITION_MAIN /* Partitioning for computation stage */
87
88 } cs_partition_stage_t;
89
90
91 /* Partitioning algorithm type
92 *
93 * If the default algorithm is selected, the choice will be based on the
94 * following priority, depending on available libraries:
95 * - Pt-Scotch (or Scotch if partitioning on one rank);
96 * - ParMETIS (or METIS if partitioning on one rank);
97 * - Morton space-filling curve (in bounding box)
98 *
99 * If both partitioning stages are active, the default for the preprocessing
100 * stage will be based on the Morton space-filling curve (in bounding box),
101 * as this should be cheaper, and the initial cell connectivity graph
102 * is usually expected to be modified during preprocessing.
103 */
104
105 typedef enum {
106
107 CS_PARTITION_DEFAULT, /* Default partitioning (based on stage) */
108 CS_PARTITION_SFC_MORTON_BOX, /* Morton (Z) curve in bounding box */
109 CS_PARTITION_SFC_MORTON_CUBE, /* Morton (Z) curve in bounding cube */
110 CS_PARTITION_SFC_HILBERT_BOX, /* Peano-Hilbert curve in bounding box */
111 CS_PARTITION_SFC_HILBERT_CUBE, /* Peano-Hilbert curve in bounding cube */
112 CS_PARTITION_SCOTCH, /* PT-SCOTCH or SCOTCH */
113 CS_PARTITION_METIS, /* ParMETIS or METIS */
114 CS_PARTITION_BLOCK /* Unoptimized (naive) block partitioning */
115
116 } cs_partition_algorithm_t;
117
118 /*============================================================================
119 * Static global variables
120 *============================================================================*/
121
122 /*=============================================================================
123 * Public function prototypes
124 *============================================================================*/
125
126 /*----------------------------------------------------------------------------
127 * Print information on external libraries
128 *----------------------------------------------------------------------------*/
129
130 void
131 cs_partition_external_library_info(void);
132
133 /*----------------------------------------------------------------------------
134 * Set algorithm for domain partitioning for a given partitioning stage.
135 *
136 * parameters:
137 * stage <-- associated partitioning stage
138 * algorithm <-- partitioning algorithm choice
139 * rank_step <-- if > 1, partitioning done on at most
140 * n_ranks / rank_step processes
141 * (for graph-based partitioning only)
142 * ignore_perio <-- if true, ignore periodicity information when present
143 * when present (for graph-based
144 * (for graph-based partitioning only)
145 *----------------------------------------------------------------------------*/
146
147 void
148 cs_partition_set_algorithm(cs_partition_stage_t stage,
149 cs_partition_algorithm_t algorithm,
150 int rank_step,
151 bool ignore_perio);
152
153 /*----------------------------------------------------------------------------
154 * Set partitioning write to file option.
155 *
156 * Partitioning information for subsequent calculations is written to file
157 * after the last partitioning stage depending on the output level.
158 *
159 * Note that partitioning information for additional partitionings is
160 * always written to file, regardless of this option.
161 *
162 * parameters:
163 * write_flag <-- option to save partitioning information:
164 * 0: never
165 * 1: for graph-based partitioning only (default)
166 * 2: always
167 *----------------------------------------------------------------------------*/
168
169 void
170 cs_partition_set_write_level(int write_flag);
171
172 /*----------------------------------------------------------------------------
173 * Define hints indicating if initial partitioning fo a preprocessing
174 * stage is required.
175 *
176 * parameters:
177 * join <-- true if a mesh joining operation is planned
178 * join_periodic <-- true if a mesh periodic matching operation is planned
179 *----------------------------------------------------------------------------*/
180
181 void
182 cs_partition_set_preprocess_hints(bool join,
183 bool join_periodic);
184
185 /*----------------------------------------------------------------------------
186 * Activate or deactivate initial partitioning for preprocessing.
187 *
188 * parameters:
189 * active <-- true to activate pre-partitiong for the preprocessing
190 * stage, false to de-activate it
191 *----------------------------------------------------------------------------*/
192
193 void
194 cs_partition_set_preprocess(bool active);
195
196 /*----------------------------------------------------------------------------
197 * Indicate if initial partitioning for preprocessing is required.
198 *
199 * returns:
200 * true if initial partitioning for preprocessing is active,
201 * false otherwise
202 *----------------------------------------------------------------------------*/
203
204 bool
205 cs_partition_get_preprocess(void);
206
207 /*----------------------------------------------------------------------------
208 * Define list of extra partitionings to build.
209 *
210 * Partitionings in this list will be output to file, and may be used for
211 * subsequent calculations.
212 *
213 * When partitioning for both preprocessing and calculation stages, output to
214 * file of partioning data or generation of additional partitionings
215 * (see \ref cs_partition_add_partitions) will only be done for the
216 * second stage.
217 *
218 * parameters:
219 * n_extra_partitions <-- number of extra partitionings to compute
220 * extra_partitions_list <-- list of extra partitions to compute
221 *----------------------------------------------------------------------------*/
222
223 void
224 cs_partition_add_partitions(int n_extra_partitions,
225 int extra_partitions_list[]);
226
227 /*----------------------------------------------------------------------------
228 * Compute partitioning for a given mesh.
229 *
230 * parameters:
231 * mesh <-- pointer to mesh structure
232 * mesh_builder <-> pointer to mesh builder structure
233 * stage <-- associated partitioning stage
234 *----------------------------------------------------------------------------*/
235
236 void
237 cs_partition(cs_mesh_t *mesh,
238 cs_mesh_builder_t *mesh_builder,
239 cs_partition_stage_t stage);
240
241 /*----------------------------------------------------------------------------*/
242
243 END_C_DECLS
244
245 #endif /* __CS_PARTITION_H__ */