9.0
general documentation
Loading...
Searching...
No Matches
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-2025 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 "base/cs_base.h"
39#include "base/cs_field.h"
40#include "base/cs_restart.h"
41#include "base/cs_function.h"
42
43/*----------------------------------------------------------------------------*/
44
46
47/*============================================================================
48 * Macro definitions
49 *============================================================================*/
50
51/*============================================================================
52 * Type definitions
53 *============================================================================*/
54
55/* Moment type */
56
63
64/* Moment restart behavior */
65
73
74/*----------------------------------------------------------------------------
75 * Function pointer for computation of data values for moments computation.
76 *
77 * If the matching values are multidimensional, they must be interleaved.
78 *
79 * Note: if the input pointer is non-null, it must point to valid data
80 * when the selection function is called, so either:
81 * - that value or structure should not be temporary (i.e. local);
82 * - when a single integer identifier is needed, the input pointer can be
83 * set to that value instead of an actual address;
84 *
85 * parameters:
86 * input <-- pointer to optional (untyped) value or structure.
87 * vals --> pointer to values (size: n_local elements*dimension)
88 *----------------------------------------------------------------------------*/
89
90typedef void
91(cs_time_moment_data_t) (const void *input,
92 cs_real_t *vals);
93
94/*=============================================================================
95 * Global variables
96 *============================================================================*/
97
98/* Names associated with moment types */
99
100extern const char *cs_time_moment_type_name[];
101
102/*============================================================================
103 * Public function prototypes
104 *============================================================================*/
105
106/*----------------------------------------------------------------------------
107 * Destroy all moments management metadata.
108 *----------------------------------------------------------------------------*/
109
110void
112
113/*----------------------------------------------------------------------------
114 * Map time step values array for temporal moments.
115 *
116 * If this function is not called, the field referenced by field pointer
117 * CS_F_(dt) will be used instead.
118 *----------------------------------------------------------------------------*/
119
120void
122
123/*----------------------------------------------------------------------------
124 * Update all moment accumulators.
125 *----------------------------------------------------------------------------*/
126
127void
129
130/*----------------------------------------------------------------------------
131 * Return 1 if a moment is active, 0 if it is not active yet.
132 *
133 * parameters:
134 * moment_id <-- id of associated moment
135 *
136 * returns:
137 * 0 in case of success, 1 if moment accumulation has not started yet
138 *----------------------------------------------------------------------------*/
139
140int
142
143/*----------------------------------------------------------------------------
144 * Define a moment of a product of existing field components
145 *
146 * Moments will involve the tensor products of their component fields,
147 * and only scalar, vector, or rank-2 tensors are handled (for
148 * post-processing output reasons), so a moment may not involve more than
149 * 2 vectors or 1 tensor, unless single components are specified.
150 *
151 * If of dimension > 1, the moment array is always interleaved.
152 *
153 * parameters:
154 * name <-- name of associated moment
155 * n_fields <-- number of associated fields
156 * field_id <-- ids of associated fields
157 * component_id <-- ids of matching field components (-1 for all)
158 * type <-- moment type
159 * nt_start <-- starting time step (or -1 to use t_start)
160 * t_start <-- starting time
161 * restart_mode <-- behavior in case of restart (reset, auto, or strict)
162 * restart_name <-- if non-null, previous name in case of restart
163 *
164 * returns:
165 * id of new moment in case of success, -1 in case of error.
166 *----------------------------------------------------------------------------*/
167
168int
170 int n_fields,
171 const int field_id[],
172 const int component_id[],
174 int nt_start,
175 double t_start,
176 cs_time_moment_restart_t restart_mode,
177 const char *restart_name);
178
179/*----------------------------------------------------------------------------
180 * Define a time moment of an existing field.
181 *
182 * Moments will involve the tensor products of their component fields,
183 * and only scalar, vector, or rank-2 tensors are handled (for
184 * post-processing output reasons), so a 1st-order moment (i.e. mean) may
185 * involve a scalar, vector, or tensor, while a second-order moment
186 * (i.e. variance) may only involve a scalar or vector.
187 *
188 * parameters:
189 * name <-- name of associated moment
190 * f <-- pointer to associated field
191 * type <-- moment type
192 * nt_start <-- starting time step (or -1 to use t_start)
193 * t_start <-- starting time
194 * restart_mode <-- behavior in case of restart (reset, auto, or strict)
195 * restart_name <-- if non-null, previous name in case of restart
196 *
197 * returns:
198 * id of new moment in case of success, -1 in case of error.
199 *----------------------------------------------------------------------------*/
200
201int
202cs_time_moment_define_by_field(const char *name,
203 const cs_field_t *f,
205 int nt_start,
206 double t_start,
207 cs_time_moment_restart_t restart_mode,
208 const char *restart_name);
209
210/*----------------------------------------------------------------------------
211 * Define a time moment based on an evaluation function.
212 *
213 * Moments will involve the tensor products of their component fields,
214 * and only scalar, vector, or rank-2 tensors are handled (for
215 * post-processing output reasons), so a 1st-order moment (i.e. mean) may
216 * involve a scalar, vector, or tensor, while a second-order moment
217 * (i.e. variance) may only involve a scalar or vector.
218 *
219 * parameters:
220 * name <-- name of associated moment
221 * f <-- pointer to function object
222 * type <-- moment type
223 * nt_start <-- starting time step (or -1 to use t_start)
224 * t_start <-- starting time
225 * restart_mode <-- behavior in case of restart (reset, auto, or strict)
226 * restart_name <-- if non-null, previous name in case of restart
227 *
228 * returns:
229 * id of new moment in case of success, -1 in case of error.
230 *----------------------------------------------------------------------------*/
231
232int
233cs_time_moment_define_by_function(const char *name,
234 cs_function_t *f,
236 int nt_start,
237 double t_start,
238 cs_time_moment_restart_t restart_mode,
239 const char *restart_name);
240
241/*----------------------------------------------------------------------------
242 * Define a moment whose data values will be computed using a
243 * specified function.
244 *
245 * If of dimension > 1, the moment array is always interleaved.
246 *
247 * parameters:
248 * name <-- name of associated moment
249 * location_id <-- id of associated mesh location
250 * dim <-- dimension associated with element data
251 * is_intensive <-- is the time moment intensive?
252 * data_func <-- function used to define data values
253 * data_input <-- pointer to optional (untyped) value or structure
254 * to be used by data_func
255 * weight_func <-- function used to define weight values
256 * weight_input <-- pointer to optional (untyped) value or structure
257 * to be used by weight_func
258 * type <-- moment type
259 * nt_start <-- starting time step (or -1 to use t_start)
260 * t_start <-- starting time
261 * restart_mode <-- behavior in case of restart (reset, auto, or strict)
262 * restart_name <-- if non-null, previous name in case of restart
263 *
264 * returns:
265 * id of new moment in case of success, -1 in case of error.
266 *----------------------------------------------------------------------------*/
267
268int
269cs_time_moment_define_by_func(const char *name,
270 int location_id,
271 int dim,
272 bool is_intensive,
273 cs_time_moment_data_t *data_func,
274 const void *data_input,
275 cs_time_moment_data_t *w_data_func,
276 void *w_data_input,
278 int nt_start,
279 double t_start,
280 cs_time_moment_restart_t restart_mode,
281 const char *restart_name);
282
283/*----------------------------------------------------------------------------
284 * Return the number of defined time moments.
285 *
286 * returns:
287 * number of defined time moments
288 *----------------------------------------------------------------------------*/
289
290int
292
293/*----------------------------------------------------------------------------
294 * Return the number of time moments in the restart file, if any
295 *
296 * returns:
297 * number of defined moments in restart file, or 0
298 *----------------------------------------------------------------------------*/
299
300int
302
303/*----------------------------------------------------------------------------
304 * Define a moment restart mode and name by an id.
305 *
306 * This is a utility function, to allow simplification of automatic setups.
307 * It must be called just before defining a moment to work properly if
308 * restart_id < -1 (automatic mode).
309 *
310 * parameters:
311 * restart_id <-- -2: automatic, -1: reset, >= 0: id of
312 * matching moment in restart data
313 * restart_mode --> matching restart mode
314 * restart_name --> matching restart name
315 *----------------------------------------------------------------------------*/
316
317void
319 cs_time_moment_restart_t *restart_mode,
320 const char **restart_name);
321
322/*----------------------------------------------------------------------------
323 * Return name of a given time moments in the restart file, if any
324 * (check also \ref cs_time_moment_n_moments_restart).
325 *
326 * parameters:
327 * restart_id <-- id of time moment in restart data
328 *
329 * returns:
330 * name of defined moment in restart file, or null
331 *----------------------------------------------------------------------------*/
332
333const char *
334cs_time_moment_restart_name(int restart_id);
335
336/*----------------------------------------------------------------------------
337 * Return pointer to field associated with a given moment.
338 *
339 * For moments defined automatically to assist computation of higher order
340 * moments, which do not have an associated field, a null pointer is returned.
341 *
342 * parameters:
343 * moment_id <-- id of associated moment
344 *
345 * returns:
346 * pointer to field associated with given moment, or null
347 *----------------------------------------------------------------------------*/
348
351
352/*----------------------------------------------------------------------------
353 * Return 1 if moment is active, 0 if it is not active yet.
354 *
355 * parameters:
356 * moment_id <-- id of associated moment
357 *
358 * returns:
359 * 1 if moment is active, 0 if it is not active yet
360 *----------------------------------------------------------------------------*/
361
362int
364
366
367#ifdef __cplusplus
368
369/*----------------------------------------------------------------------------*/
370/*
371 * \brief Reset selected time step for starting time step of selected moment.
372 *
373 * All other time moments sharing the same start time will also start
374 * at the same time step.
375 *
376 * \param[in] moment_id id of associated moment, or -1 for all
377 * \param[in] nt_start starting time step
378 */
379/*----------------------------------------------------------------------------*/
380
381void
383 int nt_start);
384
385/*----------------------------------------------------------------------------*/
386/*
387 * \brief Reset selected time step for starting time step of selected moment.
388 *
389 * All other time moments sharing the same start time will also start
390 * at the same time step.
391 *
392 * \param[in] moment_id id of associated moment, or -1 for all
393 * \param[in] nt_start starting time value
394 */
395/*----------------------------------------------------------------------------*/
396
397void
399 double t_start);
400
401#endif //ifdef __cplusplus
402
404
405/*----------------------------------------------------------------------------*/
406/*
407 * \brief Set current iteration as starting time step of selected moment.
408 *
409 * All other time moments sharing the same start time should also be reset.
410 *
411 * \param[in] moment_id id of associated moment, or -1 for all.
412 */
413/*----------------------------------------------------------------------------*/
414
415void
417
418/*----------------------------------------------------------------------------
419 * Update all moment accumulators.
420 ----------------------------------------------------------------------------*/
421
422void
424
425/*----------------------------------------------------------------------------
426 * Log moment definition setup information.
427 *----------------------------------------------------------------------------*/
428
429void
431
432/*----------------------------------------------------------------------------
433 * Log moment definition information for a given iteration.
434 *----------------------------------------------------------------------------*/
435
436void
438
439/*----------------------------------------------------------------------------
440 * Indicate if restart API should use "main" instead of "auxiliary" file.
441 *
442 * parameters:
443 * use_main <-- use "main" restart if nonzero, "auxiliary" otherwise
444 *----------------------------------------------------------------------------*/
445
446void
448
449/*----------------------------------------------------------------------------
450 * Read restart moment data
451 *
452 * parameters:
453 * <-> restart associated restart file pointer
454 *----------------------------------------------------------------------------*/
455
456void
458
459/*----------------------------------------------------------------------------
460 * Checkpoint moment data
461 *
462 * parameters:
463 * <-> restart associated restart file pointer
464 *----------------------------------------------------------------------------*/
465
466void
468
469/*----------------------------------------------------------------------------*/
470
472
473#endif /* __CS_TIME_MOMENT_H__ */
#define BEGIN_C_DECLS
Definition cs_defs.h:542
double cs_real_t
Floating-point value.
Definition cs_defs.h:342
#define END_C_DECLS
Definition cs_defs.h:543
@ dt
Definition cs_field_pointer.h:65
struct _cs_restart_t cs_restart_t
Definition cs_restart.h:95
void cs_time_moment_set_start_time(int moment_id, int nt_start)
Reset selected time step for starting time step of selected moment.
Definition cs_time_moment.cpp:2150
const char * cs_time_moment_type_name[]
Definition cs_time_moment.cpp:247
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.cpp:2910
int cs_time_moment_define_by_function(const char *name, cs_function_t *f, 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 time moment based on an evaluation function.
Definition cs_time_moment.cpp:1924
void cs_time_moment_destroy_all(void)
Destroy all moments management metadata.
Definition cs_time_moment.cpp:1771
void cs_time_moment_restart_read(cs_restart_t *restart)
Read restart moment data.
Definition cs_time_moment.cpp:2927
void cs_time_moment_log_setup(void)
Log moment definition setup information.
Definition cs_time_moment.cpp:2545
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.cpp:2063
int cs_time_moment_n_moments(void)
Return the number of defined time moments.
Definition cs_time_moment.cpp:2020
int cs_time_moment_define_by_field(const char *name, const cs_field_t *f, 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 time moment of an existing field.
Definition cs_time_moment.cpp:1865
void cs_time_moment_log_iteration(void)
Log moment definition information for a given iteration.
Definition cs_time_moment.cpp:2717
cs_field_t * cs_time_moment_get_field(int moment_id)
Return pointer to field associated with a given moment.
Definition cs_time_moment.cpp:2122
int cs_time_moment_n_moments_restart(void)
Return the number of time moments in the restart file, if any.
Definition cs_time_moment.cpp:2034
cs_time_moment_restart_t
Definition cs_time_moment.h:66
@ CS_TIME_MOMENT_RESTART_AUTO
Definition cs_time_moment.h:69
@ CS_TIME_MOMENT_RESTART_RESET
Definition cs_time_moment.h:68
@ CS_TIME_MOMENT_RESTART_EXACT
Definition cs_time_moment.h:70
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.cpp:1806
cs_time_moment_type_t
Definition cs_time_moment.h:57
@ CS_TIME_MOMENT_VARIANCE
Definition cs_time_moment.h:60
@ CS_TIME_MOMENT_MEAN
Definition cs_time_moment.h:59
void cs_time_moment_data_t(const void *input, cs_real_t *vals)
Definition cs_time_moment.h:91
void cs_time_moment_restart_write(cs_restart_t *restart)
Checkpoint moment data.
Definition cs_time_moment.cpp:2998
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.cpp:2188
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.cpp:2093
void cs_time_moment_map_cell_dt(const cs_real_t *dt)
Map time step values array for temporal moments.
Definition cs_time_moment.cpp:2295
void cs_time_moment_reset(int moment_id)
Set current iteration as starting time step of selected moment.
Definition cs_time_moment.cpp:2215
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.cpp:1979
void cs_time_moment_update_all(void)
Update all moment accumulators.
Definition cs_time_moment.cpp:2307
int moment_id
Definition keywords.h:91
Field descriptor.
Definition cs_field.h:158
Definition cs_function.h:121