src/fvm/fvm_writer.h Source File

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups 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-2013 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
43 BEGIN_C_DECLS
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
63 } fvm_writer_time_dep_t;
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
75 } fvm_writer_var_loc_t;
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
113 fvm_writer_n_formats(void);
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
303 fvm_writer_time_dep_t
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,
413 cs_timer_counter_t *mesh_time,
414 cs_timer_counter_t *field_time,
415 cs_timer_counter_t *flush_time);
416
417 /*----------------------------------------------------------------------------*/
418
419 END_C_DECLS
420
421 #endif /* __FVM_WRITER_H__ */