programmer's 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-2015 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 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 (
86  const cs_int_t *ntcabs,
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
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 *
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
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
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
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
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_base <-- associated base tolerance (used for bounding
290  * box check only, not for location test)
291  * tolerance_fraction <-- associated fraction of element bounding boxes
292  * added to tolerance
293  * n_points <-- number of points to locate
294  * point_coords <-- point coordinates
295  * point_tag <-- optional point tag (size: n_points)
296  * location <-> number of element containing or closest to each
297  * point (size: n_points)
298  * distance <-> distance from point to element indicated by
299  * location[]: < 0 if unlocated, 0 - 1 if inside,
300  * and > 1 if outside a volume element, or absolute
301  * distance to a surface element (size: n_points)
302  *----------------------------------------------------------------------------*/
303 
304 void
305 cs_coupling_point_in_mesh(const void *mesh,
306  float tolerance_base,
307  float tolerance_fraction,
308  ple_lnum_t n_points,
309  const ple_coord_t point_coords[],
310  const int point_tag[],
311  ple_lnum_t location[],
312  float distance[]);
313 
314 /*----------------------------------------------------------------------------
315  * Find elements in a given mesh containing points: updates the
316  * location[] and distance[] arrays associated with a set of points
317  * for points that are in an element of this mesh, or closer to one
318  * than to previously encountered elements.
319  *
320  * Location is relative to parent element numbers.
321  *
322  * parameters:
323  * mesh <-- pointer to mesh representation structure
324  * tolerance_base <-- associated base tolerance (used for bounding
325  * box check only, not for location test)
326  * tolerance_fraction <-- associated fraction of element bounding boxes
327  * added to tolerance
328  * n_points <-- number of points to locate
329  * point_coords <-- point coordinates
330  * point_tag <-- optional point tag (size: n_points)
331  * location <-> number of element containing or closest to each
332  * point (size: n_points)
333  * distance <-> distance from point to element indicated by
334  * location[]: < 0 if unlocated, 0 - 1 if inside,
335  * and > 1 if outside a volume element, or absolute
336  * distance to a surface element (size: n_points)
337  *----------------------------------------------------------------------------*/
338 
339 void
341  float tolerance_base,
342  float tolerance_fraction,
343  ple_lnum_t n_points,
344  const ple_coord_t point_coords[],
345  const int point_tag[],
346  ple_lnum_t location[],
347  float distance[]);
348 
349 /*----------------------------------------------------------------------------*/
350 
352 
353 #endif /* __CS_COUPLING_H__ */
int cs_coupling_get_sync_flag(void)
Return the optional synchronization flag for external couplings.
Definition: cs_coupling.c:296
void cs_coupling_discover_mpi_apps(const char *app_name)
Discover other applications in the same MPI root communicator.
Definition: cs_coupling.c:178
real(c_double), pointer, save dtref
reference time step
Definition: optcal.f90:430
integer(c_int), pointer, save ntmabs
Maximum absolute time step number.
Definition: optcal.f90:391
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.c:631
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.c:278
#define BEGIN_C_DECLS
Definition: cs_defs.h:429
int cs_int_t
Fortran-compatible integer.
Definition: cs_defs.h:295
void cplact(cs_int_t *isync)
Definition: cs_coupling.c:153
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.c:402
void cs_coupling_set_sync_flag(int flag)
Define an optional synchronization flag for external couplings.
Definition: cs_coupling.c:338
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.c:687
bool cs_coupling_is_sync_active(void)
Indicate is synchronization with applications in the same PLE group is active.
Definition: cs_coupling.c:568
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.c:735
void cs_coupling_set_ts_multiplier(double m)
Define a time step multiplier for external couplings.
Definition: cs_coupling.c:377
void cplsyn(cs_int_t *ntmabs, const cs_int_t *ntcabs, cs_real_t *dtref)
Definition: cs_coupling.c:121
#define END_C_DECLS
Definition: cs_defs.h:430
double cs_real_t
Definition: cs_defs.h:296
integer(c_int), pointer, save ntcabs
Current absolute time step number. In case of restart, this is equal to ntpabs + number of new iterat...
Definition: optcal.f90:388
void cs_coupling_finalize(void)
Finalize MPI coupling helper structures.
Definition: cs_coupling.c:263
#define CS_PROCF(x, y)
Definition: cs_defs.h:453
double cs_coupling_get_ts_multiplier(void)
Return the time step multiplier for external couplings.
Definition: cs_coupling.c:356
Definition: mesh.f90:26