programmer's documentation
 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 
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
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 <-- 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
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
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
391  ple_lnum_t n_points,
392  const ple_coord_t point_coords[],
393  ple_lnum_t location[],
394  float distance[]);
395 
396 /*----------------------------------------------------------------------------*/
397 
399 
400 #endif /* __CS_COUPLING_H__ */