8.3
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-2024 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
56typedef enum {
57
60
62
63/* Moment restart behavior */
64
65typedef 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
89typedef 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
99extern const char *cs_time_moment_type_name[];
100
101/*============================================================================
102 * Public function prototypes
103 *============================================================================*/
104
105/*----------------------------------------------------------------------------
106 * Destroy all moments management metadata.
107 *----------------------------------------------------------------------------*/
108
109void
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
119void
121
122/*----------------------------------------------------------------------------
123 * Update all moment accumulators.
124 *----------------------------------------------------------------------------*/
125
126void
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
139int
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 non-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
167int
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 non-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
205int
206cs_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
227int
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
237int
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
254void
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
270const char *
271cs_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 order
277 * moments, which do not have an associated field, a null pointer 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
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
299int
301
302/*----------------------------------------------------------------------------*/
311/*----------------------------------------------------------------------------*/
312
313void
315
316/*----------------------------------------------------------------------------
317 * Update all moment accumulators.
318 ----------------------------------------------------------------------------*/
319
320void
322
323/*----------------------------------------------------------------------------
324 * Log moment definition setup information.
325 *----------------------------------------------------------------------------*/
326
327void
329
330/*----------------------------------------------------------------------------
331 * Log moment definition information for a given iteration.
332 *----------------------------------------------------------------------------*/
333
334void
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
344void
346
347/*----------------------------------------------------------------------------
348 * Read restart moment data
349 *
350 * parameters:
351 * <-> restart associated restart file pointer
352 *----------------------------------------------------------------------------*/
353
354void
356
357/*----------------------------------------------------------------------------
358 * Checkpoint moment data
359 *
360 * parameters:
361 * <-> restart associated restart file pointer
362 *----------------------------------------------------------------------------*/
363
364void
366
367/*----------------------------------------------------------------------------*/
368
370
371#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_restart_use_main(int use_main)
Indicate if restart API should use "main" instead of "auxiliary" file.
Definition: cs_time_moment.cpp:2586
void cs_time_moment_destroy_all(void)
Destroy all moments management metadata.
Definition: cs_time_moment.cpp:1498
void cs_time_moment_restart_read(cs_restart_t *restart)
Read restart moment data.
Definition: cs_time_moment.cpp:2603
void cs_time_moment_log_setup(void)
Log moment definition setup information.
Definition: cs_time_moment.cpp: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.cpp:1804
int cs_time_moment_n_moments(void)
Return the number of defined time moments.
Definition: cs_time_moment.cpp: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.cpp:2393
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:1863
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:1775
const char * cs_time_moment_type_name[]
Definition: cs_time_moment.cpp: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.cpp: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.cpp: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.cpp:1887
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:1834
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: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.cpp: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.cpp:1594
void cs_time_moment_update_all(void)
Update all moment accumulators.
Definition: cs_time_moment.cpp:1997
int moment_id
Definition: keywords.h:91
Field descriptor.
Definition: cs_field.h:131