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