src/base/cs_coupling.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_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-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 * 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
48 BEGIN_C_DECLS
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 for Fortran API
64 *============================================================================*/
65
66 /*----------------------------------------------------------------------------
67 * Synchronize with applications in the same PLE coupling group.
68 *
69 * This function should be called before starting a new time step. The
70 * current time step id is that of the last finished time step, or 0 at
71 * initialization.
72 *
73 * Fortran Interface:
74 *
75 * subroutine cplsyn (ntcmabs, ntcabs, dtref)
76 * *****************
77 *
78 * integer ntmabs : <-> : maximum iteration number
79 * integer ntcabs : <-- : current iteration number
80 * double precision dtref : <-> : reference time step value
81 *----------------------------------------------------------------------------*/
82
83 void CS_PROCF(cplsyn, CPLSYN)
84 (
85 cs_int_t *ntmabs,
86 const cs_int_t *ntcabs,
87 cs_real_t *dtref
88 );
89
90 /*----------------------------------------------------------------------------
91 * Indicate if there are synchronized applications in the same
92 * PLE coupling group.
93 *
94 * Fortran Interface:
95 *
96 * subroutine cplact (isync)
97 * *****************
98 *
99 * integer isync : <-- : 1 if synchronized, 0 otherwise
100 *----------------------------------------------------------------------------*/
101
102 void CS_PROCF(cplact, CPLACT)
103 (
104 cs_int_t *isync
105 );
106
107 /*============================================================================
108 * Public function prototypes
109 *============================================================================*/
110
111 #if defined(HAVE_MPI)
112
113 /*----------------------------------------------------------------------------
114 * Discover other applications in the same MPI root communicator.
115 *
116 * parameters:
117 * app_name <-- name of this instance of Code_Saturne.
118 *----------------------------------------------------------------------------*/
119
120 void
121 cs_coupling_discover_mpi_apps(const char *app_name);
122
123 /*----------------------------------------------------------------------------
124 * Finalize MPI coupling helper structures.
125 *----------------------------------------------------------------------------*/
126
127 void
128 cs_coupling_finalize(void);
129
130 /*----------------------------------------------------------------------------
131 * Return info on other applications in the same MPI root communicator.
132 *
133 * returns:
134 * info on other applications structure.
135 *----------------------------------------------------------------------------*/
136
137 const ple_coupling_mpi_set_t *
138 cs_coupling_get_mpi_apps(void);
139
140 #endif /* HAVE_MPI */
141
142 /*----------------------------------------------------------------------------
143 * Return the optional synchronization flag for external couplings.
144 *
145 * See cs_coupling_set_sync_flag() for details.
146 *
147 * returns:
148 * synchronization flag to apply to couplings
149 *----------------------------------------------------------------------------*/
150
151 int
152 cs_coupling_get_sync_flag(void);
153
154 /*----------------------------------------------------------------------------
155 * Define an optional synchronization flag for external couplings.
156 *
157 * This flag is used by all couplings based on the PLE (Parallel Location
158 * and Exchange) group synchronization mechanism, which include couplings
159 * with SYRTHES 4, Code_Saturne, and NEPTUNE_CFD.
160 *
161 * It is defined by a mask, so for example flags f1, f2, and f3 may be
162 * combined using the "f1 | f2 | f2" syntax.
163 *
164 * Note also that for Code_Saturne, in the case of a variable time step,
165 * the reference time step is synchronized at the beginning of each
166 * iteration, but the actual time step is recomputed later.
167 *
168 * Possible flags are:
169 * PLE_COUPLING_TS_MIN Use smallest time step
170 * PLE_COUPLING_TS_LEADER Prescribe time step for the group
171 * (only one member may set this flag)
172 * PLE_COUPLING_UNSTEADY Inform others that this instance is
173 * using an unsteady solution approach
174 * PLE_COUPLING_STEADY Inform others that this instance is
175 * using a teady solution approach
176 * PLE_COUPLING_USER_1 User definable flag
177 * PLE_COUPLING_USER_2 User definable flag
178 * PLE_COUPLING_USER_3 User definable flag
179 * PLE_COUPLING_USER_4 User definable flag
180 *
181 * To force stopping, PLE_COUPLING_STOP may be set. In this case,
182 * the calculation will stop at the first synchronization, even if
183 * this function is called again with another flag.
184 *
185 * parameters:
186 * flag <-- synchronization flag to apply to couplings
187 *----------------------------------------------------------------------------*/
188
189 void
190 cs_coupling_set_sync_flag(int flag);
191
192 /*----------------------------------------------------------------------------
193 * Return the time step multiplier for external couplings.
194 *
195 * See cs_coupling_get_ts_multiplier() for details.
196 *
197 * returns:
198 * time step multiplier for external couplings
199 *----------------------------------------------------------------------------*/
200
201 double
202 cs_coupling_get_ts_multiplier(void);
203
204 /*----------------------------------------------------------------------------
205 * Define a time step multiplier for external couplings.
206 *
207 * The apparent time step for the current instance times (as viewed by
208 * coupled codes) is equal to the true time step times this multiplier.
209 *
210 * If the synchronization flag contains "time step min" (PLE_COUPLING_TS_MIN),
211 * the apparent time step is used to determine which code has the smallest
212 * time step.
213 *
214 * parameters:
215 * m <-- time step multipier to aply to couplings
216 *----------------------------------------------------------------------------*/
217
218 void
219 cs_coupling_set_ts_multiplier(double m);
220
221 /*----------------------------------------------------------------------------
222 * Synchronize with applications in the same PLE coupling group.
223 *
224 * This function should be called before starting a new time step. The
225 * current time step id is that of the last finished time step, or 0 at
226 * initialization.
227 *
228 * Default synchronization flags indicating a new iteration or end of
229 * calculation are set automatically, but the user may set additional flags
230 * to this function if necessary.
231 *
232 * parameters:
233 * flags <-- optional additional synchronization flags
234 * current_ts_id <-- current time step id
235 * max_ts_id <-> maximum time step id
236 * ts <-> suggested time step value
237 *----------------------------------------------------------------------------*/
238
239 void
240 cs_coupling_sync_apps(int flags,
241 int current_ts_id,
242 int *max_ts_id,
243 double *ts);
244
245 /*----------------------------------------------------------------------------
246 * Indicate is synchronization with applications in the same
247 * PLE group is active.
248 *
249 * return:
250 * true if synchronization is required, false otherwise
251 *----------------------------------------------------------------------------*/
252
253 bool
254 cs_coupling_is_sync_active(void);
255
256 /*----------------------------------------------------------------------------
257 * Compute extents of a mesh representation
258 *
259 * parameters:
260 * mesh <-- pointer to mesh representation structure
261 * n_max_extents <-- maximum number of sub-extents (such as element extents)
262 * to compute, or -1 to query
263 * tolerance <-- addition to local extents of each element:
264 * extent = base_extent * (1 + tolerance)
265 * extents <-> extents associated with mesh:
266 * x_min, y_min, ..., x_max, y_max, ... (size: 2*dim)
267 *
268 * returns:
269 * the number of extents computed
270 *----------------------------------------------------------------------------*/
271
272 ple_lnum_t
273 cs_coupling_mesh_extents(const void *mesh,
274 ple_lnum_t n_max_extents,
275 double tolerance,
276 double extents[]);
277
278 /*----------------------------------------------------------------------------
279 * Find elements in a given mesh containing points: updates the
280 * location[] and distance[] arrays associated with a set of points
281 * for points that are in an element of this mesh, or closer to one
282 * than to previously encountered elements.
283 *
284 * Location is relative to the id of a given element + 1 in
285 * concatenated sections of same element dimension.
286 *
287 * parameters:
288 * mesh <-- pointer to mesh representation structure
289 * tolerance <-- associated tolerance
290 * n_points <-- number of points to locate
291 * point_coords <-- point coordinates
292 * location <-> number of element containing or closest to each
293 * point (size: n_points)
294 * distance <-> distance from point to element indicated by
295 * location[]: < 0 if unlocated, 0 - 1 if inside,
296 * and > 1 if outside a volume element, or absolute
297 * distance to a surface element (size: n_points)
298 *----------------------------------------------------------------------------*/
299
300 void
301 cs_coupling_point_in_mesh(const void *mesh,
302 double tolerance,
303 ple_lnum_t n_points,
304 const ple_coord_t point_coords[],
305 ple_lnum_t location[],
306 float distance[]);
307
308 /*----------------------------------------------------------------------------
309 * Find elements in a given mesh containing points: updates the
310 * location[] and distance[] arrays associated with a set of points
311 * for points that are in an element of this mesh, or closer to one
312 * than to previously encountered elements.
313 *
314 * Location is relative to parent element numbers.
315 *
316 * parameters:
317 * mesh <-- pointer to mesh representation structure
318 * tolerance <-- associated tolerance
319 * n_points <-- number of points to locate
320 * point_coords <-- point coordinates
321 * location <-> number of element containing or closest to each
322 * point (size: n_points)
323 * distance <-> distance from point to element indicated by
324 * location[]: < 0 if unlocated, 0 - 1 if inside,
325 * and > 1 if outside a volume element, or absolute
326 * distance to a surface element (size: n_points)
327 *----------------------------------------------------------------------------*/
328
329 void
330 cs_coupling_point_in_mesh_p(const void *mesh,
331 double tolerance,
332 ple_lnum_t n_points,
333 const ple_coord_t point_coords[],
334 ple_lnum_t location[],
335 float distance[]);
336
337 /*----------------------------------------------------------------------------
338 * Find elements in a given mesh closest to points: updates the
339 * location[] and distance[] arrays associated with a set of points
340 * for points that are closer to an element of this mesh than to previously
341 * encountered elements.
342 *
343 * This function currently only handles elements of lower dimension than
344 * the spatial dimension.
345 *
346 * Location is relative to the id of a given element + 1 in
347 * concatenated sections of same element dimension.
348 *
349 * parameters:
350 * mesh <-- pointer to mesh representation structure
351 * n_points <-- number of points to locate
352 * point_coords <-- point coordinates
353 * location <-> number of element containing or closest to each
354 * point (size: n_points)
355 * distance <-> distance from point to element indicated by
356 * location[]: < 0 if unlocated, or absolute
357 * distance to a surface element (size: n_points)
358 *----------------------------------------------------------------------------*/
359
360 void
361 cs_coupling_point_closest_mesh(const void *mesh,
362 ple_lnum_t n_points,
363 const ple_coord_t point_coords[],
364 ple_lnum_t location[],
365 float distance[]);
366
367 /*----------------------------------------------------------------------------
368 * Find elements in a given mesh closest to points: updates the
369 * location[] and distance[] arrays associated with a set of points
370 * for points that are closer to an element of this mesh than to previously
371 * encountered elements.
372 *
373 * This function currently only handles elements of lower dimension than
374 * the spatial dimension.
375 *
376 * Location is relative to parent element numbers.
377 *
378 * parameters:
379 * mesh <-- pointer to mesh representation structure
380 * n_points <-- number of points to locate
381 * point_coords <-- point coordinates
382 * location <-> number of element containing or closest to each
383 * point (size: n_points)
384 * distance <-> distance from point to element indicated by
385 * location[]: < 0 if unlocated, or absolute
386 * distance to a surface element (size: n_points)
387 *----------------------------------------------------------------------------*/
388
389 void
390 cs_coupling_point_closest_mesh_p(const void *mesh,
391 ple_lnum_t n_points,
392 const ple_coord_t point_coords[],
393 ple_lnum_t location[],
394 float distance[]);
395
396 /*----------------------------------------------------------------------------*/
397
398 END_C_DECLS
399
400 #endif /* __CS_COUPLING_H__ */