8.0
general documentation
cs_time_moment.h
Go to the documentation of this file.
1 #ifndef __CS_TIME_MOMENT_H__
2 #define __CS_TIME_MOMENT_H__
3 
4 /*============================================================================
5  * Moments management
6  *============================================================================*/
7 
8 /*
9  This file is part of code_saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2023 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  * Local headers
36  *----------------------------------------------------------------------------*/
37 
38 #include "cs_base.h"
39 #include "cs_field.h"
40 #include "cs_restart.h"
41 
42 /*----------------------------------------------------------------------------*/
43 
45 
46 /*============================================================================
47  * Macro definitions
48  *============================================================================*/
49 
50 /*============================================================================
51  * Type definitions
52  *============================================================================*/
53 
54 /* Moment type */
55 
56 typedef enum {
57 
60 
62 
63 /* Moment restart behavior */
64 
65 typedef enum {
66 
70 
72 
73 /*----------------------------------------------------------------------------
74  * Function pointer for computation of data values for moments computation.
75  *
76  * If the matching values are multidimensional, they must be interleaved.
77  *
78  * Note: if the input pointer is non-NULL, it must point to valid data
79  * when the selection function is called, so either:
80  * - that value or structure should not be temporary (i.e. local);
81  * - when a single integer identifier is needed, the input pointer can be
82  * set to that value instead of an actual address;
83  *
84  * parameters:
85  * input <-- pointer to optional (untyped) value or structure.
86  * vals --> pointer to values (size: n_local elements*dimension)
87  *----------------------------------------------------------------------------*/
88 
89 typedef void
90 (cs_time_moment_data_t) (const void *input,
91  cs_real_t *vals);
92 
93 /*=============================================================================
94  * Global variables
95  *============================================================================*/
96 
97 /* Names associated with moment types */
98 
99 extern const char *cs_time_moment_type_name[];
100 
101 /*============================================================================
102  * Public function prototypes
103  *============================================================================*/
104 
105 /*----------------------------------------------------------------------------
106  * Destroy all moments management metadata.
107  *----------------------------------------------------------------------------*/
108 
109 void
111 
112 /*----------------------------------------------------------------------------
113  * Map time step values array for temporal moments.
114  *
115  * If this function is not called, the field referenced by field pointer
116  * CS_F_(dt) will be used instead.
117  *----------------------------------------------------------------------------*/
118 
119 void
121 
122 /*----------------------------------------------------------------------------
123  * Update all moment accumulators.
124  *----------------------------------------------------------------------------*/
125 
126 void
128 
129 /*----------------------------------------------------------------------------
130  * Return 1 if a moment is active, 0 if it is not active yet.
131  *
132  * parameters:
133  * moment_id <-- id of associated moment
134  *
135  * returns:
136  * 0 in case of success, 1 if moment accumulation has not started yet
137  *----------------------------------------------------------------------------*/
138 
139 int
141 
142 /*----------------------------------------------------------------------------
143  * Define a moment of a product of existing field components
144  *
145  * Moments will involve the tensor products of their component fields,
146  * and only scalar, vector, or rank-2 tensors are handled (for
147  * post-processing output reasons), so a moment may not involve more than
148  * 2 vectors or 1 tensor, unless single components are specified.
149  *
150  * If of dimension > 1, the moment array is always interleaved.
151  *
152  * parameters:
153  * name <-- name of associated moment
154  * n_fields <-- number of associated fields
155  * field_id <-- ids of associated fields
156  * component_id <-- ids of matching field components (-1 for all)
157  * type <-- moment type
158  * nt_start <-- starting time step (or -1 to use t_start)
159  * t_start <-- starting time
160  * restart_mode <-- behavior in case of restart (reset, auto, or strict)
161  * restart_name <-- if not NULL, previous name in case of restart
162  *
163  * returns:
164  * id of new moment in case of success, -1 in case of error.
165  *----------------------------------------------------------------------------*/
166 
167 int
168 cs_time_moment_define_by_field_ids(const char *name,
169  int n_fields,
170  const int field_id[],
171  const int component_id[],
173  int nt_start,
174  double t_start,
175  cs_time_moment_restart_t restart_mode,
176  const char *restart_name);
177 
178 /*----------------------------------------------------------------------------
179  * Define a moment whose data values will be computed using a
180  * specified function.
181  *
182  * If of dimension > 1, the moment array is always interleaved.
183  *
184  * parameters:
185  * name <-- name of associated moment
186  * location_id <-- id of associated mesh location
187  * dim <-- dimension associated with element data
188  * is_intensive <-- is the time moment intensive?
189  * data_func <-- function used to define data values
190  * data_input <-- pointer to optional (untyped) value or structure
191  * to be used by data_func
192  * weight_func <-- function used to define weight values
193  * weight_input <-- pointer to optional (untyped) value or structure
194  * to be used by weight_func
195  * type <-- moment type
196  * nt_start <-- starting time step (or -1 to use t_start)
197  * t_start <-- starting time
198  * restart_mode <-- behavior in case of restart (reset, auto, or strict)
199  * restart_name <-- if not NULL, previous name in case of restart
200  *
201  * returns:
202  * id of new moment in case of success, -1 in case of error.
203  *----------------------------------------------------------------------------*/
204 
205 int
206 cs_time_moment_define_by_func(const char *name,
207  int location_id,
208  int dim,
209  bool is_intensive,
210  cs_time_moment_data_t *data_func,
211  const void *data_input,
212  cs_time_moment_data_t *w_data_func,
213  void *w_data_input,
215  int nt_start,
216  double t_start,
217  cs_time_moment_restart_t restart_mode,
218  const char *restart_name);
219 
220 /*----------------------------------------------------------------------------
221  * Return the number of defined time moments.
222  *
223  * returns:
224  * number of defined time moments
225  *----------------------------------------------------------------------------*/
226 
227 int
229 
230 /*----------------------------------------------------------------------------
231  * Return the number of time moments in the restart file, if any
232  *
233  * returns:
234  * number of defined moments in restart file, or 0
235  *----------------------------------------------------------------------------*/
236 
237 int
239 
240 /*----------------------------------------------------------------------------
241  * Define a moment restart mode and name by an id.
242  *
243  * This is a utility function, to allow simplification of automatic setups.
244  * It must be called just before defining a moment to work properly if
245  * restart_id < -1 (automatic mode).
246  *
247  * parameters:
248  * restart_id <-- -2: automatic, -1: reset, >= 0: id of
249  * matching moment in restart data
250  * restart_mode --> matching restart mode
251  * restart_name --> matching restart name
252  *----------------------------------------------------------------------------*/
253 
254 void
256  cs_time_moment_restart_t *restart_mode,
257  const char **restart_name);
258 
259 /*----------------------------------------------------------------------------
260  * Return name of a given time moments in the restart file, if any
261  * (check also \ref cs_time_moment_n_moments_restart).
262  *
263  * parameters:
264  * restart_id <-- id of time moment in restart data
265  *
266  * returns:
267  * name of defined moment in restart file, or NULL
268  *----------------------------------------------------------------------------*/
269 
270 const char *
271 cs_time_moment_restart_name(int restart_id);
272 
273 /*----------------------------------------------------------------------------
274  * Return pointer to field associated with a given moment.
275  *
276  * For moments defined automatically to assist computation of higher
277  * order moments, which do not have an associated field, NULL is returned.
278  *
279  * parameters:
280  * moment_id <-- id of associated moment
281  *
282  * returns:
283  * pointer to field associated with given moment, or NULL
284  *----------------------------------------------------------------------------*/
285 
286 cs_field_t *
288 
289 /*----------------------------------------------------------------------------
290  * Return 1 if moment is active, 0 if it is not active yet.
291  *
292  * parameters:
293  * moment_id <-- id of associated moment
294  *
295  * returns:
296  * 1 if moment is active, 0 if it is not active yet
297  *----------------------------------------------------------------------------*/
298 
299 int
301 
302 /*----------------------------------------------------------------------------*/
311 /*----------------------------------------------------------------------------*/
312 
313 void
315 
316 /*----------------------------------------------------------------------------
317  * Update all moment accumulators.
318  ----------------------------------------------------------------------------*/
319 
320 void
322 
323 /*----------------------------------------------------------------------------
324  * Log moment definition setup information.
325  *----------------------------------------------------------------------------*/
326 
327 void
329 
330 /*----------------------------------------------------------------------------
331  * Log moment definition information for a given iteration.
332  *----------------------------------------------------------------------------*/
333 
334 void
336 
337 /*----------------------------------------------------------------------------
338  * Indicate if restart API should use "main" instead of "auxiliary" file.
339  *
340  * parameters:
341  * use_main <-- use "main" restart if nonzero, "auxiliary" otherwise
342  *----------------------------------------------------------------------------*/
343 
344 void
345 cs_time_moment_restart_use_main(int use_main);
346 
347 /*----------------------------------------------------------------------------
348  * Read restart moment data
349  *
350  * parameters:
351  * <-> restart associated restart file pointer
352  *----------------------------------------------------------------------------*/
353 
354 void
356 
357 /*----------------------------------------------------------------------------
358  * Checkpoint moment data
359  *
360  * parameters:
361  * <-> restart associated restart file pointer
362  *----------------------------------------------------------------------------*/
363 
364 void
366 
367 /*----------------------------------------------------------------------------*/
368 
370 
371 #endif /* __CS_TIME_MOMENT_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:509
double cs_real_t
Floating-point value.
Definition: cs_defs.h:319
#define END_C_DECLS
Definition: cs_defs.h:510
@ dt
Definition: cs_field_pointer.h:65
struct _cs_restart_t cs_restart_t
Definition: cs_restart.h:95
void cs_time_moment_restart_use_main(int use_main)
Indicate if restart API should use "main" instead of "auxiliary" file.
Definition: cs_time_moment.c:2586
void cs_time_moment_destroy_all(void)
Destroy all moments management metadata.
Definition: cs_time_moment.c:1498
void cs_time_moment_restart_read(cs_restart_t *restart)
Read restart moment data.
Definition: cs_time_moment.c:2603
void cs_time_moment_log_setup(void)
Log moment definition setup information.
Definition: cs_time_moment.c:2221
void cs_time_moment_restart_options_by_id(int restart_id, cs_time_moment_restart_t *restart_mode, const char **restart_name)
Define a moment restart mode and name by an id.
Definition: cs_time_moment.c:1804
const char * cs_time_moment_restart_name(int restart_id)
Return name of a given time moments in the restart file, if any (check also cs_time_moment_n_moments_...
Definition: cs_time_moment.c:1834
int cs_time_moment_n_moments(void)
Return the number of defined time moments.
Definition: cs_time_moment.c:1761
void() cs_time_moment_data_t(const void *input, cs_real_t *vals)
Definition: cs_time_moment.h:90
void cs_time_moment_log_iteration(void)
Log moment definition information for a given iteration.
Definition: cs_time_moment.c:2393
int cs_time_moment_n_moments_restart(void)
Return the number of time moments in the restart file, if any.
Definition: cs_time_moment.c:1775
const char * cs_time_moment_type_name[]
Definition: cs_time_moment.c:243
cs_time_moment_restart_t
Definition: cs_time_moment.h:65
@ CS_TIME_MOMENT_RESTART_AUTO
Definition: cs_time_moment.h:68
@ CS_TIME_MOMENT_RESTART_RESET
Definition: cs_time_moment.h:67
@ CS_TIME_MOMENT_RESTART_EXACT
Definition: cs_time_moment.h:69
int cs_time_moment_define_by_field_ids(const char *name, int n_fields, const int field_id[], const int component_id[], cs_time_moment_type_t type, int nt_start, double t_start, cs_time_moment_restart_t restart_mode, const char *restart_name)
Define a moment of a product of existing fields components.
Definition: cs_time_moment.c:1533
cs_time_moment_type_t
Definition: cs_time_moment.h:56
@ CS_TIME_MOMENT_VARIANCE
Definition: cs_time_moment.h:59
@ CS_TIME_MOMENT_MEAN
Definition: cs_time_moment.h:58
void cs_time_moment_restart_write(cs_restart_t *restart)
Checkpoint moment data.
Definition: cs_time_moment.c:2671
int cs_time_moment_is_active(int moment_id)
Return 1 if moment is active, 0 if it is not active yet.
Definition: cs_time_moment.c:1887
cs_field_t * cs_time_moment_get_field(int moment_id)
Return pointer to field associated with a given moment.
Definition: cs_time_moment.c:1863
void cs_time_moment_map_cell_dt(const cs_real_t *dt)
Map time step values array for temporal moments.
Definition: cs_time_moment.c:1985
void cs_time_moment_reset(int moment_id)
Reset a time moment. Current iteration is set as starting time step for current moment.
Definition: cs_time_moment.c:1915
int cs_time_moment_define_by_func(const char *name, int location_id, int dim, bool is_intensive, cs_time_moment_data_t *data_func, const void *data_input, cs_time_moment_data_t *w_data_func, void *w_data_input, cs_time_moment_type_t type, int nt_start, double t_start, cs_time_moment_restart_t restart_mode, const char *restart_name)
Define a moment whose data values will be computed using a specified function.
Definition: cs_time_moment.c:1594
void cs_time_moment_update_all(void)
Update all moment accumulators.
Definition: cs_time_moment.c:1997
int moment_id
Definition: keywords.h:91
Field descriptor.
Definition: cs_field.h:130