8.3
general documentation
fvm_writer.h
Go to the documentation of this file.
1#ifndef __FVM_WRITER_H__
2#define __FVM_WRITER_H__
3
4/*============================================================================
5 * Handle export of mesh and fields.
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#include "cs_defs.h"
31
32/*----------------------------------------------------------------------------
33 * Local headers
34 *----------------------------------------------------------------------------*/
35
36#include "cs_timer.h"
37
38#include "fvm_defs.h"
39#include "fvm_nodal.h"
40
41/*----------------------------------------------------------------------------*/
42
44
45/*=============================================================================
46 * Macro definitions
47 *============================================================================*/
48
49/*============================================================================
50 * Type definitions
51 *============================================================================*/
52
53/*----------------------------------------------------------------------------
54 * Element types
55 *----------------------------------------------------------------------------*/
56
57typedef enum {
58
59 FVM_WRITER_FIXED_MESH, /* Mesh definitions do not change with time */
60 FVM_WRITER_TRANSIENT_COORDS, /* Vertex coordinates may change with time */
61 FVM_WRITER_TRANSIENT_CONNECT /* Mesh connectivity may change with time */
62
64
65/*----------------------------------------------------------------------------
66 * Variable definition type
67 *----------------------------------------------------------------------------*/
68
69typedef enum {
70
71 FVM_WRITER_PER_NODE, /* Variable values per node */
72 FVM_WRITER_PER_ELEMENT, /* Variable values per element */
73 FVM_WRITER_PER_PARTICLE /* Variable values per particle */
74
76
77/*----------------------------------------------------------------------------
78 * Opaque structure defining a writer definition
79 *----------------------------------------------------------------------------*/
80
81typedef struct _fvm_writer_t fvm_writer_t;
82
83/*=============================================================================
84 * Static global variables
85 *============================================================================*/
86
87/* Names of time dependency enumeration values */
88
89extern const char *fvm_writer_time_dep_name[];
90
91/*=============================================================================
92 * Public function prototypes
93 *============================================================================*/
94
95/*----------------------------------------------------------------------------
96 * Find the format matching a name,
97 *
98 * parameters:
99 * format_name <-- name of desired format
100 *
101 * returns:
102 * index of the format matching the given name, or -1 if none matches.
103 *----------------------------------------------------------------------------*/
104
105int
106fvm_writer_get_format_id(const char *format_name);
107
108/*----------------------------------------------------------------------------
109 * Returns number of known formats.
110 *----------------------------------------------------------------------------*/
111
112int
114
115/*----------------------------------------------------------------------------
116 * Returns name of a known format.
117 *
118 * parameters:
119 * format_index <-- index of format in known format list (0 to n-1)
120 *
121 * returns:
122 * pointer to constant string containing the format's name
123 *----------------------------------------------------------------------------*/
124
125const char *
126fvm_writer_format_name(int format_index);
127
128/*----------------------------------------------------------------------------
129 * Returns availability of a known format.
130 *
131 * parameters:
132 * format_index <-- index of format in known format list (0 to n-1)
133 *
134 * returns:
135 * 1 if the format is available, 0 otherwise.
136 *----------------------------------------------------------------------------*/
137
138int
139fvm_writer_format_available(int format_index);
140
141/*----------------------------------------------------------------------------
142 * Returns number of library version strings associated with a given format.
143 *
144 * For writers requiring an external library, the first associated
145 * version string should correspond to that library, with possible
146 * additional version strings for its dependencies.
147 *
148 * For writers only requiring standard libraries (libc, MPI, MPI-IO),
149 * this function should return 0.
150 *
151 * parameters:
152 * format_index <-- index of format in known format list (0 to n-1)
153 *
154 * returns:
155 * number of library version strings associated with a given format.
156 *----------------------------------------------------------------------------*/
157
158int
159fvm_writer_n_version_strings(int format_index);
160
161/*----------------------------------------------------------------------------
162 * Returns a library version string associated with a given format.
163 *
164 * We must have string_index < fvm_writer_n_version_strings(format_index).
165 *
166 * In certain cases, when using dynamic libraries, fvm may be compiled
167 * with one library version, and linked with another. If both run-time
168 * and compile-time version information is available, this function
169 * will return the run-time version string by default.
170 *
171 * Setting the compile_time flag to 1, the compile-time version string
172 * will be returned if this is different from the run-time version.
173 * If the version is the same, or only one of the 2 version strings are
174 * available, a NULL character string will be returned with this flag set.
175 *
176 * parameters:
177 * format_index <-- index of format in known format list (0 to n-1)
178 * string_index <-- index in format's version string list (0 to n-1)
179 * compile_time <-- 0 by default, 1 if we want the compile-time version
180 * string, if different from the run-time version.
181 *
182 * returns:
183 * pointer to constant string containing the library's version.
184 *----------------------------------------------------------------------------*/
185
186const char *
187fvm_writer_version_string(int format_index,
188 int string_index,
189 int compile_time_version);
190
191/*----------------------------------------------------------------------------
192 * Remove a given option from a format options list if present.
193 *
194 * The possible separators are also transformed to whitespace and merged.
195 *
196 * parameters:
197 * format_options <-> options for the selected format (case-independent,
198 * whitespace or comma separated list)
199 * exclude_option <-- option to be excluded
200 *----------------------------------------------------------------------------*/
201
202void
203fvm_writer_filter_option(char *format_options,
204 const char *exclude_option);
205
206/*----------------------------------------------------------------------------
207 * Initialize FVM mesh and field output writer.
208 *
209 * Allowed options depend on what is applicable to a given format. Those
210 * not relevant to a given writer are ignored. Possible options include:
211 * text output text files (EnSight)
212 * binary output binary files (EnSight, default)
213 * big_endian force binary files to big-endian (EnSight)
214 * adf use ADF file type (CGNS)
215 * hdf5 use HDF5 file type (CGNS, default if available)
216 * discard_polygons do not output polygons or related values
217 * discard_polyhedra do not output polyhedra or related values
218 * divide_polygons tesselate polygons with triangles
219 * divide_polyhedra tesselate polyhedra with tetrahedra and pyramids
220 * (adding a vertex near each polyhedron's center)
221 * separate_meshes use a different writer for each mesh
222 *
223 * parameters:
224 * name <-- base name of output
225 * path <-- optional directory name for output
226 * (directory automatically created if necessary)
227 * format_name <-- name of selected format (case-independent)
228 * format_options <-- options for the selected format (case-independent,
229 * whitespace or comma separated list)
230 * time_dependency <-- indicates if and how meshes will change with time
231 *
232 * returns:
233 * pointer to mesh and field output writer
234 *----------------------------------------------------------------------------*/
235
236fvm_writer_t *
237fvm_writer_init(const char *name,
238 const char *path,
239 const char *format_name,
240 const char *format_options,
241 fvm_writer_time_dep_t time_dependency);
242
243/*----------------------------------------------------------------------------
244 * Finalize FVM mesh and field output writer.
245 *
246 * parameters:
247 * this_writer <-- pointer to mesh and field output writer
248 *
249 * returns:
250 * null pointer
251 *----------------------------------------------------------------------------*/
252
253fvm_writer_t *
254fvm_writer_finalize(fvm_writer_t *this_writer);
255
256/*----------------------------------------------------------------------------
257 * Return a writer's name.
258 *
259 * parameters:
260 * this_writer <-- pointer to mesh and field output writer
261 *
262 * returns:
263 * pointer to base name of output associated with the writer
264 *----------------------------------------------------------------------------*/
265
266const char *
267fvm_writer_get_name(const fvm_writer_t *this_writer);
268
269/*----------------------------------------------------------------------------
270 * Return a writer's associated format name.
271 *
272 * parameters:
273 * this_writer <-- pointer to mesh and field output writer
274 *
275 * returns:
276 * pointer to output format name associated with the writer
277 *----------------------------------------------------------------------------*/
278
279const char *
280fvm_writer_get_format(const fvm_writer_t *this_writer);
281
282/*----------------------------------------------------------------------------
283 * Return a writer's associated format options.
284 *
285 * parameters:
286 * this_writer <-- pointer to mesh and field output writer
287 *
288 * returns:
289 * pointer to output format options associated with the writer
290 *----------------------------------------------------------------------------*/
291
292const char *
293fvm_writer_get_options(const fvm_writer_t *this_writer);
294
295/*----------------------------------------------------------------------------
296 * Return a writer's associated output directory.
297 *
298 * parameters:
299 * this_writer <-- pointer to mesh and field output writer
300 *
301 * returns:
302 * pointer to output format options associated with the writer
303 *----------------------------------------------------------------------------*/
304
305const char *
306fvm_writer_get_path(const fvm_writer_t *this_writer);
307
308/*----------------------------------------------------------------------------
309 * Return geometry time dependency status of a writer.
310 *
311 * parameters:
312 * this_writer <-- pointer to mesh and field output writer
313 *
314 * returns:
315 * time dependency status
316 *----------------------------------------------------------------------------*/
317
319fvm_writer_get_time_dep(const fvm_writer_t *this_writer);
320
321/*----------------------------------------------------------------------------
322 * Associate new time step with a mesh.
323 *
324 * parameters:
325 * this_writer_p <-- pointer to associated writer
326 * time_step <-- time step number
327 * time_value <-- time_value number
328 *----------------------------------------------------------------------------*/
329
330void
331fvm_writer_set_mesh_time(fvm_writer_t *this_writer,
332 int time_step,
333 double time_value);
334
335/*----------------------------------------------------------------------------
336 * Query if elements of a given type will need to be tesselated
337 * for use of a nodal mesh with an output writer.
338 *
339 * This function should be called before any fvm_writer_export_...()
340 *
341 * parameters:
342 * this_writer <-- pointer to mesh and field output writer
343 * mesh <-- pointer to nodal mesh
344 * element_type <-- type of element
345 *
346 * returns:
347 * 0 if no tesselation is necessary, 1 if tesselation is necessary.
348 *----------------------------------------------------------------------------*/
349
350int
351fvm_writer_needs_tesselation(fvm_writer_t *this_writer,
352 const fvm_nodal_t *mesh,
353 fvm_element_t element_type);
354
355/*----------------------------------------------------------------------------
356 * Export FVM nodal mesh.
357 *
358 * parameters:
359 * this_writer <-- pointer to mesh and field output writer
360 * mesh <-- pointer to nodal mesh
361 *----------------------------------------------------------------------------*/
362
363void
364fvm_writer_export_nodal(fvm_writer_t *this_writer,
365 const fvm_nodal_t *mesh);
366
367/*----------------------------------------------------------------------------
368 * Export field associated with a nodal mesh.
369 *
370 * Assigning a negative value to the time step indicates a time-independent
371 * field (in which case the time_value argument is unused).
372 *
373 * parameters:
374 * this_writer <-- pointer to mesh and field output writer
375 * mesh <-- pointer to associated nodal mesh structure
376 * name <-- variable name
377 * location <-- variable definition location (nodes or elements)
378 * dimension <-- variable dimension (0: constant, 1: scalar,
379 * 3: vector, 6: sym. tensor, 9: asym. tensor)
380 * interlace <-- indicates if variable in memory is interlaced
381 * n_parent_lists <-- indicates if variable values are to be obtained
382 * directly through the local entity index (when 0) or
383 * through the parent entity numbers (when 1 or more)
384 * parent_num_shift <-- parent number to value array index shifts;
385 * size: n_parent_lists
386 * datatype <-- indicates the data type of (source) field values
387 * time_step <-- number of the current time step
388 * time_value <-- associated time value
389 * field_values <-- array of associated field value arrays
390 *----------------------------------------------------------------------------*/
391
392void
393fvm_writer_export_field(fvm_writer_t *this_writer,
394 const fvm_nodal_t *mesh,
395 const char *name,
396 fvm_writer_var_loc_t location,
397 int dimension,
398 cs_interlace_t interlace,
399 int n_parent_lists,
400 const cs_lnum_t parent_num_shift[],
401 cs_datatype_t datatype,
402 int time_step,
403 double time_value,
404 const void *const field_values[]);
405
406/*----------------------------------------------------------------------------
407 * Flush files associated with a given writer.
408 *
409 * parameters:
410 * this_writer <-- pointer to mesh and field output writer
411 *----------------------------------------------------------------------------*/
412
413void
414fvm_writer_flush(fvm_writer_t *this_writer);
415
416/*----------------------------------------------------------------------------
417 * Return accumulated times associated with output for a given writer.
418 *
419 * parameters:
420 * this_writer <-- pointer to mesh and field output writer
421 * mesh_time --> Meshes output time (or NULL)
422 * field_time --> Fields output time (or NULL)
423 * flush_time --> remaining (applying output) time (or NULL)
424 *----------------------------------------------------------------------------*/
425
426void
427fvm_writer_get_times(fvm_writer_t *this_writer,
431
432/*----------------------------------------------------------------------------*/
433
435
436#endif /* __FVM_WRITER_H__ */
cs_datatype_t
Definition: cs_defs.h:300
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
cs_interlace_t
Definition: cs_defs.h:514
#define END_C_DECLS
Definition: cs_defs.h:543
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:335
fvm_element_t
Definition: fvm_defs.h:48
const char * fvm_writer_format_name(int format_index)
Definition: fvm_writer.cpp:919
void fvm_writer_get_times(fvm_writer_t *this_writer, cs_timer_counter_t *mesh_time, cs_timer_counter_t *field_time, cs_timer_counter_t *flush_time)
Definition: fvm_writer.cpp:1626
void fvm_writer_set_mesh_time(fvm_writer_t *this_writer, int time_step, double time_value)
Definition: fvm_writer.cpp:1412
void fvm_writer_export_field(fvm_writer_t *this_writer, const fvm_nodal_t *mesh, const char *name, fvm_writer_var_loc_t location, int dimension, cs_interlace_t interlace, int n_parent_lists, const cs_lnum_t parent_num_shift[], cs_datatype_t datatype, int time_step, double time_value, const void *const field_values[])
Definition: fvm_writer.cpp:1528
fvm_writer_time_dep_t
Definition: fvm_writer.h:57
@ FVM_WRITER_TRANSIENT_COORDS
Definition: fvm_writer.h:60
@ FVM_WRITER_TRANSIENT_CONNECT
Definition: fvm_writer.h:61
@ FVM_WRITER_FIXED_MESH
Definition: fvm_writer.h:59
void fvm_writer_filter_option(char *format_options, const char *exclude_option)
Definition: fvm_writer.cpp:1044
const char * fvm_writer_get_options(const fvm_writer_t *this_writer)
Definition: fvm_writer.cpp:1359
const char * fvm_writer_get_path(const fvm_writer_t *this_writer)
Definition: fvm_writer.cpp:1378
const char * fvm_writer_get_format(const fvm_writer_t *this_writer)
Definition: fvm_writer.cpp:1343
fvm_writer_t * fvm_writer_init(const char *name, const char *path, const char *format_name, const char *format_options, fvm_writer_time_dep_t time_dependency)
Definition: fvm_writer.cpp:1127
fvm_writer_time_dep_t fvm_writer_get_time_dep(const fvm_writer_t *this_writer)
Definition: fvm_writer.cpp:1397
void fvm_writer_flush(fvm_writer_t *this_writer)
Definition: fvm_writer.cpp:1585
fvm_writer_var_loc_t
Definition: fvm_writer.h:69
@ FVM_WRITER_PER_NODE
Definition: fvm_writer.h:71
@ FVM_WRITER_PER_PARTICLE
Definition: fvm_writer.h:73
@ FVM_WRITER_PER_ELEMENT
Definition: fvm_writer.h:72
const char * fvm_writer_get_name(const fvm_writer_t *this_writer)
Definition: fvm_writer.cpp:1327
int fvm_writer_n_version_strings(int format_index)
Definition: fvm_writer.cpp:975
int fvm_writer_n_formats(void)
Definition: fvm_writer.cpp:903
int fvm_writer_format_available(int format_index)
Definition: fvm_writer.cpp:939
const char * fvm_writer_version_string(int format_index, int string_index, int compile_time_version)
Definition: fvm_writer.cpp:1015
int fvm_writer_needs_tesselation(fvm_writer_t *this_writer, const fvm_nodal_t *mesh, fvm_element_t element_type)
Definition: fvm_writer.cpp:1449
const char * fvm_writer_time_dep_name[]
Definition: fvm_writer.cpp:462
void fvm_writer_export_nodal(fvm_writer_t *this_writer, const fvm_nodal_t *mesh)
Definition: fvm_writer.cpp:1475
int fvm_writer_get_format_id(const char *format_name)
Definition: fvm_writer.cpp:850
fvm_writer_t * fvm_writer_finalize(fvm_writer_t *this_writer)
Definition: fvm_writer.cpp:1275
Definition: mesh.f90:26
Definition: fvm_writer_priv.h:174
char * path
Definition: fvm_writer_priv.h:179
char * name
Definition: fvm_writer_priv.h:176
cs_timer_counter_t field_time
Definition: fvm_writer_priv.h:187
cs_timer_counter_t mesh_time
Definition: fvm_writer_priv.h:186
cs_timer_counter_t flush_time
Definition: fvm_writer_priv.h:188
Definition: cs_timer.h:55