#ifndef __FVM_WRITER_H__
#define __FVM_WRITER_H__
/*============================================================================
* Handle export of mesh and fields.
*============================================================================*/
/*
This file is part of the "Finite Volume Mesh" library, intended to provide
finite volume mesh and associated fields I/O and manipulation services.
Copyright (C) 2004-2006 EDF
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
/*----------------------------------------------------------------------------
* Local headers
*----------------------------------------------------------------------------*/
#include <fvm_defs.h>
#include <fvm_nodal.h>
/*----------------------------------------------------------------------------*/
#ifdef __cplusplus
extern "C" {
#if 0
} /* Fake brace to force back Emacs auto-indentation back to column 0 */
#endif
#endif /* __cplusplus */
/*=============================================================================
* Macro definitions
*============================================================================*/
/*============================================================================
* Type definitions
*============================================================================*/
/*----------------------------------------------------------------------------
* Element types
*----------------------------------------------------------------------------*/
typedef enum {
FVM_WRITER_FIXED_MESH, /* Mesh definitions do not change with time */
FVM_WRITER_TRANSIENT_COORDS, /* Vertex coordinates may change with time */
FVM_WRITER_TRANSIENT_CONNECT /* Mesh connectivity may change with time */
} fvm_writer_time_dep_t;
/*----------------------------------------------------------------------------
* Variable definition type
*----------------------------------------------------------------------------*/
typedef enum {
FVM_WRITER_PER_NODE, /* Variable values per node */
FVM_WRITER_PER_ELEMENT, /* Variable values per element */
FVM_WRITER_PER_PARTICLE /* Variable values per particle */
} fvm_writer_var_loc_t;
/*----------------------------------------------------------------------------
* Opaque structure defining a writer definition
*----------------------------------------------------------------------------*/
typedef struct _fvm_writer_t fvm_writer_t;
/*=============================================================================
* Static global variables
*============================================================================*/
/*=============================================================================
* Public function prototypes
*============================================================================*/
/*----------------------------------------------------------------------------
* Returns number of known formats.
*----------------------------------------------------------------------------*/
int
fvm_writer_n_formats(void);
/*----------------------------------------------------------------------------
* Returns name of a known format.
*
* parameters:
* format_index <-- index of format in known format list (0 to n-1)
*
* returns:
* pointer to constant string containing the format's name
*----------------------------------------------------------------------------*/
const char *
fvm_writer_format_name(int format_index);
/*----------------------------------------------------------------------------
* Returns availability of a known format.
*
* parameters:
* format_index <-- index of format in known format list (0 to n-1)
*
* returns:
* 1 if the format is available, 0 otherwise.
*----------------------------------------------------------------------------*/
int
fvm_writer_format_available(int format_index);
/*----------------------------------------------------------------------------
* Returns number of library version strings associated with a given format.
*
* For writers requiring an external library, the first associated
* version string should correspond to that library, with possible
* additional version strings for its dependencies.
*
* For writers only requiring standard libraries (libc, MPI, MPI-IO),
* this function should return 0.
*
* parameters:
* format_index <-- index of format in known format list (0 to n-1)
*
* returns:
* number of library version strings associated with a given format.
*----------------------------------------------------------------------------*/
int
fvm_writer_n_version_strings(int format_index);
/*----------------------------------------------------------------------------
* Returns a library version string associated with a given format.
*
* We must have string_index < fvm_writer_n_version_strings(format_index).
*
* In certain cases, when using dynamic libraries, fvm may be compiled
* with one library version, and linked with another. If both run-time
* and compile-time version information is available, this function
* will return the run-time version string by default.
*
* Setting the compile_time flag to 1, the compile-time version string
* will be returned if this is different from the run-time version.
* If the version is the same, or only one of the 2 version strings are
* available, a NULL character string will be returned with this flag set.
*
* parameters:
* format_index <-- index of format in known format list (0 to n-1)
* string_index <-- index in format's version string list (0 to n-1)
* compile_time <-- 0 by default, 1 if we want the compile-time version
* string, if different from the run-time version.
*
* returns:
* pointer to constant string containing the library's version.
*----------------------------------------------------------------------------*/
const char *
fvm_writer_version_string(int format_index,
int string_index,
int compile_time_version);
/*----------------------------------------------------------------------------
* Initialize FVM mesh and field output writer.
*
* Allowed options depend on what is applicable to a given format. Those
* not relevant to a given writer are ignored. Possible options include:
* text output text files
* binary output binary files (default)
* big_endian force binary files to big-endian
* discard_polygons do not output polygons or related values
* discard_polyhedra do not output polyhedra or related values
* divide_polygons tesselate polygons with triangles
* divide_polyhedra tesselate polyhedra with tetrahedra and pyramids
* (adding a vertex near each polyhedron's center)
* split_tensors write tensor values as separate scalars
*
* parameters:
* name <-- base name of output
* path <-- optional directory name for output
* (directory automatically created if necessary)
* format_name <-- name of selected format (case-independent)
* format_options <-- options for the selected format (case-independent,
* whitespace or comma separated list)
* time_dependency <-- indicates if and how meshes will change with time
*
* returns:
* pointer to mesh and field output writer
*----------------------------------------------------------------------------*/
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);
/*----------------------------------------------------------------------------
* Finalize FVM mesh and field output writer.
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
*
* returns:
* NULL pointer
*----------------------------------------------------------------------------*/
fvm_writer_t *
fvm_writer_finalize(fvm_writer_t *this_writer);
/*----------------------------------------------------------------------------
* Return a writer's name.
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
*
* returns:
* pointer to base name of output associated with the writer
*----------------------------------------------------------------------------*/
const char *
fvm_writer_get_name(const fvm_writer_t *this_writer);
/*----------------------------------------------------------------------------
* Return a writer's associated format name.
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
*
* returns:
* pointer to output format name associated with the writer
*----------------------------------------------------------------------------*/
const char *
fvm_writer_get_format(const fvm_writer_t *this_writer);
/*----------------------------------------------------------------------------
* Return geometry time dependency status of a writer.
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
*
* returns:
* time dependency status
*----------------------------------------------------------------------------*/
fvm_writer_time_dep_t
fvm_writer_get_time_dep(const fvm_writer_t *this_writer);
/*----------------------------------------------------------------------------
* Associate new time step with a mesh.
*
* parameters:
* this_writer_p <-- pointer to associated writer
* time_step <-- time step number
* time_value <-- time_value number
*----------------------------------------------------------------------------*/
void
fvm_writer_set_mesh_time(fvm_writer_t *this_writer,
int time_step,
double time_value);
/*----------------------------------------------------------------------------
* Query if elements of a given type will need to be tesselated
* for use of a nodal mesh with an output writer.
*
* This function should be called before any fvm_writer_export_...()
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
* mesh <-- pointer to nodal mesh
* element_type <-- type of element
*
* returns:
* 0 if no tesselation is necessary, 1 if tesselation is necessary.
*----------------------------------------------------------------------------*/
int
fvm_writer_needs_tesselation(fvm_writer_t *this_writer,
const fvm_nodal_t *mesh,
fvm_element_t element_type);
/*----------------------------------------------------------------------------
* Export FVM nodal mesh.
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
* mesh <-- pointer to nodal mesh
*----------------------------------------------------------------------------*/
void
fvm_writer_export_nodal(fvm_writer_t *this_writer,
const fvm_nodal_t *mesh);
/*----------------------------------------------------------------------------
* Export field associated with a nodal mesh.
*
* Assigning a negative value to the time step indicates a time-independent
* field (in which case the time_value argument is unused).
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
* mesh <-- pointer to associated nodal mesh structure
* name <-- variable name
* location <-- variable definition location (nodes or elements)
* dimension <-- variable dimension (0: constant, 1: scalar,
* 3: vector, 6: sym. tensor, 9: asym. tensor)
* interlace <-- indicates if variable in memory is interlaced
* n_parent_lists <-- indicates if variable values are to be obtained
* directly through the local entity index (when 0) or
* through the parent entity numbers (when 1 or more)
* parent_num_shift <-- parent number to value array index shifts;
* size: n_parent_lists
* datatype <-- indicates the data type of (source) field values
* time_step <-- number of the current time step
* time_value <-- associated time value
* field_values <-- array of associated field value arrays
*----------------------------------------------------------------------------*/
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,
fvm_interlace_t interlace,
int n_parent_lists,
const fvm_lnum_t parent_num_shift[],
fvm_datatype_t datatype,
int time_step,
double time_value,
const void *const field_values[]);
/*----------------------------------------------------------------------------
* Flush files associated with a given writer.
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
*----------------------------------------------------------------------------*/
void
fvm_writer_flush(fvm_writer_t *this_writer);
/*----------------------------------------------------------------------------
* Return accumulated wall-clock and CPU times associated with mesh and
* field exports for a given writer.
*
* parameters:
* this_writer <-- pointer to mesh and field output writer
* mesh_wtime --> Meshes output Wall-clock time (or NULL)
* mesh_cpu_time --> Meshes output CPU time (or NULL)
* field_wtime --> Fields output Wall-clock time (or NULL)
* field_cpu_time --> Fields output CPU time (or NULL)
*----------------------------------------------------------------------------*/
void
fvm_writer_get_times(fvm_writer_t *this_writer,
double *mesh_wtime,
double *mesh_cpu_time,
double *field_wtime,
double *field_cpu_time);
/*----------------------------------------------------------------------------*/
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* __FVM_WRITER_H__ */
syntax highlighted by Code2HTML, v. 0.9.1