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