8.3
general documentation
cs_coupling.h
Go to the documentation of this file.
1#ifndef __CS_COUPLING_H__
2#define __CS_COUPLING_H__
3
4/*============================================================================
5 * Common functionnality for various coupling types.
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 * Standard C library headers
32 *----------------------------------------------------------------------------*/
33
34/*----------------------------------------------------------------------------
35 * PLE library headers
36 *----------------------------------------------------------------------------*/
37
38#include <ple_coupling.h>
39
40/*----------------------------------------------------------------------------
41 * Local headers
42 *----------------------------------------------------------------------------*/
43
44#include "cs_base.h"
45
46/*----------------------------------------------------------------------------*/
47
49
50/*=============================================================================
51 * Macro definitions
52 *============================================================================*/
53
54/*============================================================================
55 * Type definitions
56 *============================================================================*/
57
58/*=============================================================================
59 * Global variable definitions
60 *============================================================================*/
61
62/*============================================================================
63 * Public function prototypes
64 *============================================================================*/
65
66#if defined(HAVE_MPI)
67
68/*----------------------------------------------------------------------------
69 * Discover other applications in the same MPI root communicator.
70 *
71 * parameters:
72 * app_name <-- name of this instance of code_saturne.
73 * forced_app_type <-- name of app type, or NULL
74 *----------------------------------------------------------------------------*/
75
76void
77cs_coupling_discover_mpi_apps(const char *app_name,
78 const char *forced_app_type);
79
80/*----------------------------------------------------------------------------
81 * Finalize MPI coupling helper structures.
82 *----------------------------------------------------------------------------*/
83
84void
86
87/*----------------------------------------------------------------------------
88 * Return info on other applications in the same MPI root communicator.
89 *
90 * returns:
91 * info on other applications structure.
92 *----------------------------------------------------------------------------*/
93
94const ple_coupling_mpi_set_t *
96
97#endif /* HAVE_MPI */
98
99/*----------------------------------------------------------------------------
100 * Return the optional synchronization flag for external couplings.
101 *
102 * See cs_coupling_set_sync_flag() for details.
103 *
104 * returns:
105 * synchronization flag to apply to couplings
106 *----------------------------------------------------------------------------*/
107
108int
110
111/*----------------------------------------------------------------------------
112 * Define an optional synchronization flag for external couplings.
113 *
114 * This flag is used by all couplings based on the PLE (Parallel Location
115 * and Exchange) group synchronization mechanism, which include couplings
116 * with SYRTHES, code_saturne, and neptune_cfd.
117 *
118 * It is defined by a mask, so for example flags f1, f2, and f3 may be
119 * combined using the "f1 | f2 | f2" syntax.
120 *
121 * Note also that for code_saturne, in the case of a variable time step,
122 * the reference time step is synchronized at the beginning of each
123 * iteration, but the actual time step is recomputed later.
124 *
125 * Possible flags are:
126 * PLE_COUPLING_TS_MIN Use smallest time step
127 * PLE_COUPLING_TS_LEADER Prescribe time step for the group
128 * (only one member may set this flag)
129 * PLE_COUPLING_UNSTEADY Inform others that this instance is
130 * using an unsteady solution approach
131 * PLE_COUPLING_STEADY Inform others that this instance is
132 * using a steady solution approach
133 * PLE_COUPLING_USER_1 User definable flag
134 * PLE_COUPLING_USER_2 User definable flag
135 * PLE_COUPLING_USER_3 User definable flag
136 * PLE_COUPLING_USER_4 User definable flag
137 *
138 * To force stopping, PLE_COUPLING_STOP may be set. In this case,
139 * the calculation will stop at the first synchronization, even if
140 * this function is called again with another flag.
141 *
142 * parameters:
143 * flag <-- synchronization flag to apply to couplings
144 *----------------------------------------------------------------------------*/
145
146void
148
149/*----------------------------------------------------------------------------
150 * Return the time step multiplier for external couplings.
151 *
152 * See cs_coupling_set_ts_multiplier() for details.
153 *
154 * returns:
155 * time step multiplier for external couplings
156 *----------------------------------------------------------------------------*/
157
158double
160
161/*----------------------------------------------------------------------------
162 * Define a time step multiplier for external couplings.
163 *
164 * The apparent time step for the current instance times (as viewed by
165 * coupled codes) is equal to the true time step times this multiplier.
166 *
167 * If the synchronization flag contains "time step min" (PLE_COUPLING_TS_MIN),
168 * the apparent time step is used to determine which code has the smallest
169 * time step.
170 *
171 * parameters:
172 * m <-- time step multipier to aply to couplings
173 *----------------------------------------------------------------------------*/
174
175void
177
178/*----------------------------------------------------------------------------
179 * Synchronize with applications in the same PLE coupling group.
180 *
181 * This function should be called before starting a new time step. The
182 * current time step id is that of the last finished time step, or 0 at
183 * initialization.
184 *
185 * Default synchronization flags indicating a new iteration or end of
186 * calculation are set automatically, but the user may set additional flags
187 * to this function if necessary.
188 *
189 * parameters:
190 * flags <-- optional additional synchronization flags
191 * current_ts_id <-- current time step id
192 * max_ts_id <-> maximum time step id
193 * ts <-> suggested time step value
194 *----------------------------------------------------------------------------*/
195
196void
197cs_coupling_sync_apps(int flags,
198 int current_ts_id,
199 int *max_ts_id,
200 double *ts);
201
202/*----------------------------------------------------------------------------
203 * Indicate is synchronization with applications in the same
204 * PLE group is active.
205 *
206 * return:
207 * true if synchronization is required, false otherwise
208 *----------------------------------------------------------------------------*/
209
210bool
212
213/*----------------------------------------------------------------------------
214 * Compute extents of a mesh representation
215 *
216 * parameters:
217 * mesh <-- pointer to mesh representation structure
218 * n_max_extents <-- maximum number of sub-extents (such as element extents)
219 * to compute, or -1 to query
220 * tolerance <-- addition to local extents of each element:
221 * extent = base_extent * (1 + tolerance)
222 * extents <-> extents associated with mesh:
223 * x_min, y_min, ..., x_max, y_max, ... (size: 2*dim)
224 *
225 * returns:
226 * the number of extents computed
227 *----------------------------------------------------------------------------*/
228
231 ple_lnum_t n_max_extents,
232 double tolerance,
233 double extents[]);
234
235/*----------------------------------------------------------------------------
236 * Find elements in a given mesh containing points: updates the
237 * location[] and distance[] arrays associated with a set of points
238 * for points that are in an element of this mesh, or closer to one
239 * than to previously encountered elements.
240 *
241 * Location is relative to the id of a given element + 1 in
242 * concatenated sections of same element dimension.
243 *
244 * parameters:
245 * mesh <-- pointer to mesh representation structure
246 * tolerance_base <-- associated base tolerance (used for bounding
247 * box check only, not for location test)
248 * tolerance_fraction <-- associated fraction of element bounding boxes
249 * added to tolerance
250 * n_points <-- number of points to locate
251 * point_coords <-- point coordinates
252 * point_tag <-- optional point tag (size: n_points)
253 * location <-> number of element containing or closest to each
254 * point (size: n_points)
255 * distance <-> distance from point to element indicated by
256 * location[]: < 0 if unlocated, 0 - 1 if inside,
257 * and > 1 if outside a volume element, or absolute
258 * distance to a surface element (size: n_points)
259 *----------------------------------------------------------------------------*/
260
261void
263 float tolerance_base,
264 float tolerance_fraction,
265 ple_lnum_t n_points,
266 const ple_coord_t point_coords[],
267 const int point_tag[],
268 ple_lnum_t location[],
269 float distance[]);
270
271/*----------------------------------------------------------------------------
272 * Find elements in a given mesh containing points: updates the
273 * location[] and distance[] arrays associated with a set of points
274 * for points that are in an element of this mesh, or closer to one
275 * than to previously encountered elements.
276 *
277 * Location is relative to parent element numbers.
278 *
279 * parameters:
280 * mesh <-- pointer to mesh representation structure
281 * tolerance_base <-- associated base tolerance (used for bounding
282 * box check only, not for location test)
283 * tolerance_fraction <-- associated fraction of element bounding boxes
284 * added to tolerance
285 * n_points <-- number of points to locate
286 * point_coords <-- point coordinates
287 * point_tag <-- optional point tag (size: n_points)
288 * location <-> number of element containing or closest to each
289 * point (size: n_points)
290 * distance <-> distance from point to element indicated by
291 * location[]: < 0 if unlocated, 0 - 1 if inside,
292 * and > 1 if outside a volume element, or absolute
293 * distance to a surface element (size: n_points)
294 *----------------------------------------------------------------------------*/
295
296void
298 float tolerance_base,
299 float tolerance_fraction,
300 ple_lnum_t n_points,
301 const ple_coord_t point_coords[],
302 const int point_tag[],
303 ple_lnum_t location[],
304 float distance[]);
305
306/*----------------------------------------------------------------------------*/
307
309
310#endif /* __CS_COUPLING_H__ */
ple_lnum_t cs_coupling_mesh_extents(const void *mesh, ple_lnum_t n_max_extents, double tolerance, double extents[])
Compute extents of a mesh representation.
Definition: cs_coupling.cpp:544
void cs_coupling_point_in_mesh(const void *mesh, float tolerance_base, float tolerance_fraction, ple_lnum_t n_points, const ple_coord_t point_coords[], const int point_tag[], ple_lnum_t location[], float distance[])
Find elements in a given mesh containing points: updates the location[] and distance[] arrays associa...
Definition: cs_coupling.cpp:600
void cs_coupling_set_ts_multiplier(double m)
Define a time step multiplier for external couplings.
Definition: cs_coupling.cpp:326
void cs_coupling_set_sync_flag(int flag)
Define an optional synchronization flag for external couplings.
Definition: cs_coupling.cpp:287
void cs_coupling_sync_apps(int flags, int current_ts_id, int *max_ts_id, double *ts)
Synchronize with applications in the same PLE coupling group.
Definition: cs_coupling.cpp:351
const ple_coupling_mpi_set_t * cs_coupling_get_mpi_apps(void)
Return info on other applications in the same MPI root communicator.
Definition: cs_coupling.cpp:227
void cs_coupling_point_in_mesh_p(const void *mesh, float tolerance_base, float tolerance_fraction, ple_lnum_t n_points, const ple_coord_t point_coords[], const int point_tag[], ple_lnum_t location[], float distance[])
Find elements in a given mesh containing points: updates the location[] and distance[] arrays associa...
Definition: cs_coupling.cpp:648
int cs_coupling_get_sync_flag(void)
Return the optional synchronization flag for external couplings.
Definition: cs_coupling.cpp:245
void cs_coupling_discover_mpi_apps(const char *app_name, const char *forced_app_type)
Discover other applications in the same MPI root communicator.
Definition: cs_coupling.cpp:116
double cs_coupling_get_ts_multiplier(void)
Return the time step multiplier for external couplings.
Definition: cs_coupling.cpp:305
bool cs_coupling_is_sync_active(void)
Indicate is synchronization with applications in the same PLE group is active.
Definition: cs_coupling.cpp:486
void cs_coupling_finalize(void)
Finalize MPI coupling helper structures.
Definition: cs_coupling.cpp:212
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
#define END_C_DECLS
Definition: cs_defs.h:543
Definition: mesh.f90:26
int ple_lnum_t
double ple_coord_t