8.3
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-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/*----------------------------------------------------------------------------
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
84typedef 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
106typedef 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
134void
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
151void
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
173void
174cs_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
185void
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
197void
198cs_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
208bool
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
227void
228cs_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
240void
242 cs_mesh_builder_t *mesh_builder,
244
245/*----------------------------------------------------------------------------*/
246
248
249#endif /* __CS_PARTITION_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
#define END_C_DECLS
Definition: cs_defs.h:543
cs_log_t
Definition: cs_log.h:48
void cs_partition_set_write_level(int write_flag)
Set partitioning write to file option.
Definition: cs_partition.cpp:2989
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.cpp:3006
bool cs_partition_get_preprocess(void)
Indicate if re-partitiong for the computation stage is required.
Definition: cs_partition.cpp:3041
cs_partition_algorithm_t
Definition: cs_partition.h:106
@ CS_PARTITION_METIS
Definition: cs_partition.h:114
@ CS_PARTITION_SFC_HILBERT_CUBE
Definition: cs_partition.h:112
@ CS_PARTITION_SFC_MORTON_CUBE
Definition: cs_partition.h:110
@ CS_PARTITION_BLOCK
Definition: cs_partition.h:115
@ CS_PARTITION_SFC_MORTON_BOX
Definition: cs_partition.h:109
@ CS_PARTITION_DEFAULT
Definition: cs_partition.h:108
@ CS_PARTITION_SCOTCH
Definition: cs_partition.h:113
@ CS_PARTITION_SFC_HILBERT_BOX
Definition: cs_partition.h:111
void cs_partition_external_library_info(cs_log_t log_type)
Print information on external libraries.
Definition: cs_partition.cpp:2851
void cs_partition_add_partitions(int n_extra_partitions, int extra_partitions_list[])
Define list of extra partitionings to build.
Definition: cs_partition.cpp:3086
void cs_partition_set_preprocess(bool active)
Activate or deactivate initial partitioning for preprocessing.
Definition: cs_partition.cpp:3023
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.cpp:2914
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.cpp:3110
cs_partition_stage_t
Definition: cs_partition.h:84
@ CS_PARTITION_FOR_PREPROCESS
Definition: cs_partition.h:86
@ CS_PARTITION_MAIN
Definition: cs_partition.h:87
Definition: mesh.f90:26
Definition: cs_mesh_builder.h:57
Definition: cs_mesh.h:85