programmer's 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-2015 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 
57 typedef 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 
69 typedef 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 
81 typedef struct _fvm_writer_t fvm_writer_t;
82 
83 /*=============================================================================
84  * Static global variables
85  *============================================================================*/
86 
87 /* Names of time dependency enumeration values */
88 
89 extern 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 
105 int
106 fvm_writer_get_format_id(const char *format_name);
107 
108 /*----------------------------------------------------------------------------
109  * Returns number of known formats.
110  *----------------------------------------------------------------------------*/
111 
112 int
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 
125 const char *
126 fvm_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 
138 int
139 fvm_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 
158 int
159 fvm_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 
186 const char *
187 fvm_writer_version_string(int format_index,
188  int string_index,
189  int compile_time_version);
190 
191 /*----------------------------------------------------------------------------
192  * Initialize FVM mesh and field output writer.
193  *
194  * Allowed options depend on what is applicable to a given format. Those
195  * not relevant to a given writer are ignored. Possible options include:
196  * text output text files (EnSight)
197  * binary output binary files (EnSight, default)
198  * big_endian force binary files to big-endian (EnSight)
199  * adf use ADF file type (CGNS)
200  * hdf5 use HDF5 file type (CGNS, default if available)
201  * discard_polygons do not output polygons or related values
202  * discard_polyhedra do not output polyhedra or related values
203  * divide_polygons tesselate polygons with triangles
204  * divide_polyhedra tesselate polyhedra with tetrahedra and pyramids
205  * (adding a vertex near each polyhedron's center)
206  * split_tensors write tensor values as separate scalars
207  *
208  * parameters:
209  * name <-- base name of output
210  * path <-- optional directory name for output
211  * (directory automatically created if necessary)
212  * format_name <-- name of selected format (case-independent)
213  * format_options <-- options for the selected format (case-independent,
214  * whitespace or comma separated list)
215  * time_dependency <-- indicates if and how meshes will change with time
216  *
217  * returns:
218  * pointer to mesh and field output writer
219  *----------------------------------------------------------------------------*/
220 
221 fvm_writer_t *
222 fvm_writer_init(const char *name,
223  const char *path,
224  const char *format_name,
225  const char *format_options,
226  fvm_writer_time_dep_t time_dependency);
227 
228 /*----------------------------------------------------------------------------
229  * Finalize FVM mesh and field output writer.
230  *
231  * parameters:
232  * this_writer <-- pointer to mesh and field output writer
233  *
234  * returns:
235  * NULL pointer
236  *----------------------------------------------------------------------------*/
237 
238 fvm_writer_t *
239 fvm_writer_finalize(fvm_writer_t *this_writer);
240 
241 /*----------------------------------------------------------------------------
242  * Return a writer's name.
243  *
244  * parameters:
245  * this_writer <-- pointer to mesh and field output writer
246  *
247  * returns:
248  * pointer to base name of output associated with the writer
249  *----------------------------------------------------------------------------*/
250 
251 const char *
252 fvm_writer_get_name(const fvm_writer_t *this_writer);
253 
254 /*----------------------------------------------------------------------------
255  * Return a writer's associated format name.
256  *
257  * parameters:
258  * this_writer <-- pointer to mesh and field output writer
259  *
260  * returns:
261  * pointer to output format name associated with the writer
262  *----------------------------------------------------------------------------*/
263 
264 const char *
265 fvm_writer_get_format(const fvm_writer_t *this_writer);
266 
267 /*----------------------------------------------------------------------------
268  * Return a writer's associated format options.
269  *
270  * parameters:
271  * this_writer <-- pointer to mesh and field output writer
272  *
273  * returns:
274  * pointer to output format options associated with the writer
275  *----------------------------------------------------------------------------*/
276 
277 const char *
278 fvm_writer_get_options(const fvm_writer_t *this_writer);
279 
280 /*----------------------------------------------------------------------------
281  * Return a writer's associated output directory.
282  *
283  * parameters:
284  * this_writer <-- pointer to mesh and field output writer
285  *
286  * returns:
287  * pointer to output format options associated with the writer
288  *----------------------------------------------------------------------------*/
289 
290 const char *
291 fvm_writer_get_path(const fvm_writer_t *this_writer);
292 
293 /*----------------------------------------------------------------------------
294  * Return geometry time dependency status of a writer.
295  *
296  * parameters:
297  * this_writer <-- pointer to mesh and field output writer
298  *
299  * returns:
300  * time dependency status
301  *----------------------------------------------------------------------------*/
302 
304 fvm_writer_get_time_dep(const fvm_writer_t *this_writer);
305 
306 /*----------------------------------------------------------------------------
307  * Associate new time step with a mesh.
308  *
309  * parameters:
310  * this_writer_p <-- pointer to associated writer
311  * time_step <-- time step number
312  * time_value <-- time_value number
313  *----------------------------------------------------------------------------*/
314 
315 void
316 fvm_writer_set_mesh_time(fvm_writer_t *this_writer,
317  int time_step,
318  double time_value);
319 
320 /*----------------------------------------------------------------------------
321  * Query if elements of a given type will need to be tesselated
322  * for use of a nodal mesh with an output writer.
323  *
324  * This function should be called before any fvm_writer_export_...()
325  *
326  * parameters:
327  * this_writer <-- pointer to mesh and field output writer
328  * mesh <-- pointer to nodal mesh
329  * element_type <-- type of element
330  *
331  * returns:
332  * 0 if no tesselation is necessary, 1 if tesselation is necessary.
333  *----------------------------------------------------------------------------*/
334 
335 int
336 fvm_writer_needs_tesselation(fvm_writer_t *this_writer,
337  const fvm_nodal_t *mesh,
338  fvm_element_t element_type);
339 
340 /*----------------------------------------------------------------------------
341  * Export FVM nodal mesh.
342  *
343  * parameters:
344  * this_writer <-- pointer to mesh and field output writer
345  * mesh <-- pointer to nodal mesh
346  *----------------------------------------------------------------------------*/
347 
348 void
349 fvm_writer_export_nodal(fvm_writer_t *this_writer,
350  const fvm_nodal_t *mesh);
351 
352 /*----------------------------------------------------------------------------
353  * Export field associated with a nodal mesh.
354  *
355  * Assigning a negative value to the time step indicates a time-independent
356  * field (in which case the time_value argument is unused).
357  *
358  * parameters:
359  * this_writer <-- pointer to mesh and field output writer
360  * mesh <-- pointer to associated nodal mesh structure
361  * name <-- variable name
362  * location <-- variable definition location (nodes or elements)
363  * dimension <-- variable dimension (0: constant, 1: scalar,
364  * 3: vector, 6: sym. tensor, 9: asym. tensor)
365  * interlace <-- indicates if variable in memory is interlaced
366  * n_parent_lists <-- indicates if variable values are to be obtained
367  * directly through the local entity index (when 0) or
368  * through the parent entity numbers (when 1 or more)
369  * parent_num_shift <-- parent number to value array index shifts;
370  * size: n_parent_lists
371  * datatype <-- indicates the data type of (source) field values
372  * time_step <-- number of the current time step
373  * time_value <-- associated time value
374  * field_values <-- array of associated field value arrays
375  *----------------------------------------------------------------------------*/
376 
377 void
378 fvm_writer_export_field(fvm_writer_t *this_writer,
379  const fvm_nodal_t *mesh,
380  const char *name,
381  fvm_writer_var_loc_t location,
382  int dimension,
383  cs_interlace_t interlace,
384  int n_parent_lists,
385  const cs_lnum_t parent_num_shift[],
386  cs_datatype_t datatype,
387  int time_step,
388  double time_value,
389  const void *const field_values[]);
390 
391 /*----------------------------------------------------------------------------
392  * Flush files associated with a given writer.
393  *
394  * parameters:
395  * this_writer <-- pointer to mesh and field output writer
396  *----------------------------------------------------------------------------*/
397 
398 void
399 fvm_writer_flush(fvm_writer_t *this_writer);
400 
401 /*----------------------------------------------------------------------------
402  * Return accumulated times associated with output for a given writer.
403  *
404  * parameters:
405  * this_writer <-- pointer to mesh and field output writer
406  * mesh_time --> Meshes output time (or NULL)
407  * field_time --> Fields output time (or NULL)
408  * flush_time --> remaining (applying output) time (or NULL)
409  *----------------------------------------------------------------------------*/
410 
411 void
412 fvm_writer_get_times(fvm_writer_t *this_writer,
416 
417 /*----------------------------------------------------------------------------*/
418 
420 
421 #endif /* __FVM_WRITER_H__ */
cs_datatype_t
Definition: cs_defs.h:255
int fvm_writer_get_format_id(const char *format_name)
Definition: fvm_writer.c:537
fvm_writer_var_loc_t
Definition: fvm_writer.h:69
cs_interlace_t
Definition: cs_defs.h:411
Definition: fvm_writer_priv.h:166
#define BEGIN_C_DECLS
Definition: cs_defs.h:429
void fvm_writer_export_nodal(fvm_writer_t *this_writer, const fvm_nodal_t *mesh)
Definition: fvm_writer.c:1070
const char * fvm_writer_get_name(const fvm_writer_t *this_writer)
Definition: fvm_writer.c:925
cs_timer_counter_t flush_time
Definition: fvm_writer_priv.h:177
Definition: fvm_writer.h:71
fvm_writer_time_dep_t fvm_writer_get_time_dep(const fvm_writer_t *this_writer)
Definition: fvm_writer.c:995
int fvm_writer_needs_tesselation(fvm_writer_t *this_writer, const fvm_nodal_t *mesh, fvm_element_t element_type)
Definition: fvm_writer.c:1046
fvm_writer_time_dep_t
Definition: fvm_writer.h:57
const char * fvm_writer_time_dep_name[]
Definition: fvm_writer.c:306
Definition: fvm_writer.h:73
int fvm_writer_format_available(int format_index)
Definition: fvm_writer.c:622
fvm_element_t
Definition: fvm_defs.h:48
Definition: fvm_writer.h:72
void fvm_writer_flush(fvm_writer_t *this_writer)
Definition: fvm_writer.c:1175
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.c:1215
Definition: fvm_writer.h:59
Definition: fvm_writer.h:61
int fvm_writer_n_version_strings(int format_index)
Definition: fvm_writer.c:658
int fvm_writer_n_formats(void)
Definition: fvm_writer.c:586
const char * fvm_writer_version_string(int format_index, int string_index, int compile_time_version)
Definition: fvm_writer.c:698
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
fvm_writer_t * fvm_writer_finalize(fvm_writer_t *this_writer)
Definition: fvm_writer.c:881
#define END_C_DECLS
Definition: cs_defs.h:430
void fvm_writer_set_mesh_time(fvm_writer_t *this_writer, int time_step, double time_value)
Definition: fvm_writer.c:1010
const char * fvm_writer_get_format(const fvm_writer_t *this_writer)
Definition: fvm_writer.c:941
char * name
Definition: fvm_writer_priv.h:168
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.c:1121
const char * fvm_writer_format_name(int format_index)
Definition: fvm_writer.c:602
Definition: fvm_writer.h:60
const char * fvm_writer_get_path(const fvm_writer_t *this_writer)
Definition: fvm_writer.c:976
cs_timer_counter_t mesh_time
Definition: fvm_writer_priv.h:175
char * path
Definition: fvm_writer_priv.h:171
cs_timer_counter_t field_time
Definition: fvm_writer_priv.h:176
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.c:744
Definition: mesh.f90:26
const char * fvm_writer_get_options(const fvm_writer_t *this_writer)
Definition: fvm_writer.c:957
Definition: cs_timer.h:57