Routines for printing a forest and associated fields to VTK format. More...

#include <p4est_geometry.h>
#include <p4est.h>

Include dependency graph for p4est_vtk.h:

Typedefs
typedef struct p4est_vtk_context	p4est_vtk_context_t
	Opaque context type for writing VTK output with multiple function calls.

Functions
void	p4est_vtk_write_file (p4est_t p4est, p4est_geometry_t geom, const char *filename)
	Write the p4est in VTK format. More...

p4est_vtk_context_t *	p4est_vtk_context_new (p4est_t p4est, const char filename)
	The first call to write a VTK file using individual functions. More...

void	p4est_vtk_context_set_geom (p4est_vtk_context_t cont, p4est_geometry_t geom)
	Modify the geometry transformation registered in the context. More...

void	p4est_vtk_context_set_scale (p4est_vtk_context_t *cont, double scale)
	Modify the context parameter for scaling the quadrants. More...

void	p4est_vtk_context_set_continuous (p4est_vtk_context_t *cont, int continuous)
	Modify the context parameter for expecting continuous point data. More...

void	p4est_vtk_context_destroy (p4est_vtk_context_t *context)
	Cleanly destroy a p4est_vtk_context_t structure. More...

p4est_vtk_context_t *	p4est_vtk_write_header (p4est_vtk_context_t *cont)
	Write the VTK header. More...

p4est_vtk_context_t *	p4est_vtk_write_header_ho (p4est_vtk_context_t cont, sc_array_t positions, int Nnodes1D)
	Write the VTK header for higher order visualization. More...

p4est_vtk_context_t *	p4est_vtk_write_cell_data (p4est_vtk_context_t cont, int write_tree, int write_level, int write_rank, int wrap_rank, int num_cell_scalars, int num_cell_vectors, const char fieldnames[], sc_array_t *values[])
	Write VTK cell data. More...

p4est_vtk_context_t *	p4est_vtk_write_cell_dataf (p4est_vtk_context_t *cont, int write_tree, int write_level, int write_rank, int wrap_rank, int num_cell_scalars, int num_cell_vectors,...)
	Write VTK cell data. More...

p4est_vtk_context_t *	p4est_vtk_write_cell_datav (p4est_vtk_context_t *cont, int write_tree, int write_level, int write_rank, int wrap_rank, int num_cell_scalars, int num_cell_vectors, va_list ap)
	Write VTK cell data. More...

p4est_vtk_context_t *	p4est_vtk_write_point_dataf (p4est_vtk_context_t *cont, int num_point_scalars, int num_point_vectors,...)
	Write VTK point data. More...

int	p4est_vtk_write_footer (p4est_vtk_context_t *cont)
	Write the VTU footer and clean up. More...

Detailed Description

Routines for printing a forest and associated fields to VTK format.

Function Documentation

◆ p4est_vtk_context_destroy()

void p4est_vtk_context_destroy ( p4est_vtk_context_t * context )

Cleanly destroy a p4est_vtk_context_t structure.

This function closes all the file pointers and frees the context. It can be called even if the VTK output has only been partially written, the files' content will be incomplete.

Parameters

[in] context The VTK file context to be destroyed.

◆ p4est_vtk_context_new()

p4est_vtk_context_t * p4est_vtk_context_new	(	p4est_t *	p4est,
		const char *	filename
	)

The first call to write a VTK file using individual functions.

Writing a VTK file is split into multiple functions that keep a context. This is the first function that allocates the opaque context structure. After allocation, further parameters can be set for the context. Then, the header, possible data fields, and the footer must be written. The process can be aborted any time by destroying the context. In this case, open files are closed cleanly with only partially written content.

Parameters

p4est	The p4est to be written. If no geometry is specified in p4est_vtk_context_set_geom, we require p4est->connectivity to have valid vertex arrays.
filename	The first part of the name which will have the processor number appended to it (i.e., the output file will be filename_rank.vtu). The parallel meta-files for Paraview and Visit use this basename, too. We copy this filename to internal storage, so it is not needed to remain alive after calling this function.

Returns: A VTK context for further use.

◆ p4est_vtk_context_set_continuous()

void p4est_vtk_context_set_continuous	(	p4est_vtk_context_t *	cont,
		int	continuous
	)

Modify the context parameter for expecting continuous point data.

If set to true, the point data is understood as a continuous field. In this case, we can significantly reduce the file size when scale == 1. For discontinuous point data, it should be set to false. After p4est_vtk_context_new, it is at the default false.

Parameters

[in,out]	cont	The context is modified. It must not yet have been used to start writing in p4est_vtk_write_header.
[in]	continuous	Boolean parameter.

◆ p4est_vtk_context_set_geom()

void p4est_vtk_context_set_geom	(	p4est_vtk_context_t *	cont,
		p4est_geometry_t *	geom
	)

Modify the geometry transformation registered in the context.

After p4est_vtk_context_new, it is at the default NULL.

Parameters

[in,out]	cont	The context is modified. It must not yet have been used to start writing in p4est_vtk_write_header.
	geom	A p4est_geometry_t structure, or NULL for vertex space. If NULL, p4est->connectivity->vertices and tree_to_vertex must be non-NULL.

◆ p4est_vtk_context_set_scale()

void p4est_vtk_context_set_scale	(	p4est_vtk_context_t *	cont,
		double	scale
	)

Modify the context parameter for scaling the quadrants.

A scale < 1 places a visual gap between adjacent quadrants. After p4est_vtk_context_new, it is at the default 0.95.

Parameters

[in,out]	cont	The context is modified. It must not yet have been used to start writing in p4est_vtk_write_header.
[in]	scale	Scale parameter must be in (0, 1].

◆ p4est_vtk_write_cell_data()

p4est_vtk_context_t * p4est_vtk_write_cell_data	(	p4est_vtk_context_t *	cont,
		int	write_tree,
		int	write_level,
		int	write_rank,
		int	wrap_rank,
		int	num_cell_scalars,
		int	num_cell_vectors,
		const char *	fieldnames[],
		sc_array_t *	values[]
	)

Write VTK cell data.

There are options to have this function write the tree id, quadrant level, or MPI rank without explicit input data.

Writing a VTK file is split into a few routines. This allows there to be an arbitrary number of fields.

Parameters

[in,out]	cont	A VTK context created by p4est_vtk_context_new.
[in]	write_tree	Boolean to determine if the tree id should be output.
[in]	write_level	Boolean to determine if the tree levels should be output.
[in]	write_rank	Boolean to determine if the MPI rank should be output.
[in]	wrap_rank	Number to wrap around the rank with a modulo operation. Can be 0 for no wrapping.
[in]	num_cell_scalars	Number of cell scalar datasets to output.
[in]	num_cell_vectors	Number of cell vector datasets to output.
[in]	fieldnames	Array of char strings containing the name of each data field.
[in]	values	Array of pointers to sc_array_t holding variables of type double, one value (scalar data) or three values (vector data) for each local quadrant.

The number of doubles in each sc_array must be exactly p4est->local_num_quadrants for scalar data and 3*p4est->local_num_quadrants for vector data. The cell scalar data come first, followed by the cell vector data.

Returns: On success, the context that has been passed in. On failure, returns NULL and deallocates the context.

◆ p4est_vtk_write_cell_dataf()

p4est_vtk_context_t * p4est_vtk_write_cell_dataf	(	p4est_vtk_context_t *	cont,
		int	write_tree,
		int	write_level,
		int	write_rank,
		int	wrap_rank,
		int	num_cell_scalars,
		int	num_cell_vectors,
			...
	)

Write VTK cell data.

There are options to have this function write the tree id, quadrant level, or MPI rank without explicit input data.

Writing a VTK file is split into a few routines. This allows there to be an arbitrary number of fields.

Parameters

[in,out]	cont	A VTK context created by p4est_vtk_context_new.
[in]	write_tree	Boolean to determine if the tree id should be output.
[in]	write_level	Boolean to determine if the tree levels should be output.
[in]	write_rank	Boolean to determine if the MPI rank should be output.
[in]	wrap_rank	Number to wrap around the rank with a modulo operation. Can be 0 for no wrapping.
[in]	num_cell_scalars	Number of cell scalar datasets to output.
[in]	num_cell_vectors	Number of cell vector datasets to output.

The variable arguments need to be pairs of (fieldname, fieldvalues), followed by a final argument of the VTK context cont (same as the first argument). The cell scalar pairs come first, followed by the cell vector pairs, then cont. Each 'fieldname' argument shall be a char string containing the name of the data contained in the following 'fieldvalues'. Each of the 'fieldvalues' arguments shall be an sc_array_t * holding double variables. The number of doubles in each sc_array must be exactly p4est->local_num_quadrants for scalar data and 3*p4est->local_num_quadrants for vector data.

Note: The current p4est_vtk_context_t structure, cont, must be the first and the last argument of any call to this function; this argument is used to verify that the correct number of variable arguments have been provided.

Returns: On success, the context that has been passed in. On failure, returns NULL and deallocates the context.

◆ p4est_vtk_write_cell_datav()

p4est_vtk_context_t * p4est_vtk_write_cell_datav	(	p4est_vtk_context_t *	cont,
		int	write_tree,
		int	write_level,
		int	write_rank,
		int	wrap_rank,
		int	num_cell_scalars,
		int	num_cell_vectors,
		va_list	ap
	)

Write VTK cell data.

This function exports custom cell data to the vtk file; it is functionally the same as p4est_vtk_write_cell_dataf with the only difference being that instead of a variable argument list, an initialized va_list is passed as the last argument. That means va_start has already been called. The va_list is initialized from the variable argument list of the calling function. Elements of va_list are processed as "pairs" of (fieldname, fieldvalues). That means <va_list[0], va_list[1]> represents one pair, <va_list[2], va_list[3]> next one and so on. Each 'fieldname' shall be a char string containing the name of the data contained in the following 'fieldvalues'. Each of the 'fieldvalues' shall be an sc_array_t * holding double variables. The cell scalar pairs come first, followed by the cell vector pairs, followed by VTK context cont (same as the first argument). The number of * doubles in each sc_array must be exactly p4est->local_num_quadrants for scalar data and 3*p4est->local_num_quadrants for vector data.

Parameters

[in,out]	cont	A VTK context created by p4est_vtk_context_new.
[in]	write_tree	Boolean to determine if the tree id should be output.
[in]	write_level	Boolean to determine if the tree levels should be output.
[in]	write_rank	Boolean to determine if the MPI rank should be output.
[in]	wrap_rank	Number to wrap around the rank with a modulo operation. Can be 0 for no wrapping.
[in]	num_cell_scalars	Number of cell scalar datasets to output.
[in]	num_cell_vectors	Number of cell vector datasets to output.
[in,out]	ap	An initialized va_list used to access the scalar/vector data.

Returns: On success, the context that has been passed in. On failure, returns NULL and deallocates the context.

◆ p4est_vtk_write_file()

void p4est_vtk_write_file	(	p4est_t *	p4est,
		p4est_geometry_t *	geom,
		const char *	filename
	)

Write the p4est in VTK format.

This is a convenience function for the special case of writing out the tree id, quadrant level, and MPI rank of each quadrant as cell data. One file is written per MPI rank, and one meta file on rank 0. The quadrants are scaled to length .95; see p4est_vtk_write_header. This function will abort if there is a file error.

Parameters

[in]	p4est	The p4est to be written.
[in]	geom	A p4est_geometry_t structure or NULL for vertex space as defined by the p4est's p4est_connectivity_t member.
[in]	filename	The first part of the file name which will have the MPI rank appended to it: The output file will be filename_rank.vtu, and the meta file filename.pvtu.

Examples: simple/simple2.c, and steps/p4est_step1.c.

◆ p4est_vtk_write_footer()

int p4est_vtk_write_footer ( p4est_vtk_context_t * cont )

Write the VTU footer and clean up.

Writing a VTK file is split into a few routines. This function writes the footer information to the VTK file and cleanly destroys the VTK context.

Parameters

[in] cont Context is deallocated before the function returns.

Returns: This returns 0 if no error and -1 if there is an error.

◆ p4est_vtk_write_header()

p4est_vtk_context_t * p4est_vtk_write_header ( p4est_vtk_context_t * cont )

Write the VTK header.

Writing a VTK file is split into a few routines. This allows there to be an arbitrary number of fields. The calling sequence would be something like

vtk_context = p4est_vtk_context_new (p4est, "output");
p4est_vtk_context_set_* (vtk_context, parameter);
vtk_context = p4est_vtk_write_header (vtk_context, ...);
if (vtk_context == NULL) { error; }
vtk_context = p4est_vtk_write_cell_data (vtk_context, ...);
if (vtk_context == NULL) { error; }
vtk_context = p4est_vtk_write_point_data (vtk_context, ...);
if (vtk_context == NULL) { error; }
retval = p4est_vtk_write_footer (vtk_context);
if (retval) { error; }

Each of these functions opens and closes files as necessary. Generally, each output file is written in subsequent chunks.

This function writes point positions for the quadrants' vertices and the maps of elements to types and vertices as required by VTK.

Parameters

[in,out] cont A VTK context created by p4est_vtk_context_new. None of the vtk_write functions must have been called. This context is the return value if no error occurs.

Returns: On success, an opaque context (p4est_vtk_context_t) pointer that must be passed to subsequent p4est_vtk calls. It is required to call p4est_vtk_write_footer eventually with this value. Returns NULL on error.

◆ p4est_vtk_write_header_ho()

p4est_vtk_context_t * p4est_vtk_write_header_ho	(	p4est_vtk_context_t *	cont,
		sc_array_t *	positions,
		int	Nnodes1D
	)

Write the VTK header for higher order visualization.

This function follows the same routines as p4est_vtk_write_header. In addition, the caller must pass in an array containing coordinates for each point, as well as an integer representing the number of points in one direction each element has (for example, in an 8x8x8 cell, pass in 8).

Parameters

[in,out]	cont	A VTK context created by p4est_vtk_context_new. None of the vtk_write functions must have been called. This context is the return value if no error occurs.
[in]	positions	An sc_array_t of doubles containing the coordinates of all points to be written. Ordering of data is [ x_0, y_0, (z_0) ... x_n, y_n, (z_n) ]
[in]	Nnodes1D	Integer number of points in each element in 1D.

Returns: On success, an opaque context (p4est_vtk_context_t) pointer that must be passed to subsequent p4est_vtk calls. It is required to call p4est_vtk_write_footer eventually with this value. Returns NULL on error.

◆ p4est_vtk_write_point_dataf()

p4est_vtk_context_t * p4est_vtk_write_point_dataf	(	p4est_vtk_context_t *	cont,
		int	num_point_scalars,
		int	num_point_vectors,
			...
	)

Write VTK point data.

Writing a VTK file is split into a few routines. This allows there to be an arbitrary number of fields.

Parameters

[in,out]	cont	A VTK context created by p4est_vtk_context_new.
[in]	num_point_scalars	Number of point scalar datasets to output.
[in]	num_point_vectors	Number of point vector datasets to output.

The variable arguments need to be pairs of (fieldname, fieldvalues) where the point scalar pairs come first, followed by the point vector pairs. Each 'fieldname' argument shall be a char string containing the name of the data contained in the following 'fieldvalues'. Each of the 'fieldvalues' arguments shall be an sc_array_t * holding double variables. The number of doubles in each sc_array must be exactly the number of components (1 for scalar and 3 for vector) times 4 times number of elements.

Note: The current p4est_vtk_context_t structure, cont, must be the last argument of any call to this function; this argument is used to verify that the correct number of variable arguments have been provided.; The number of point scalar data in each sc_array must be exactly P4EST_CHILDREN*local_num_quadrants, and the number of point vector data must be exactly 3*P4EST_CHILDREN*local_num_quadrants. I.e. there must be data for every corner of every quadrant in the p4est, even if the corner is shared by multiple quadrants.

Returns: On success, the context that has been passed in. On failure, returns NULL and deallocates the context.

Typedefs

Functions

Detailed Description

Function Documentation

◆ p4est_vtk_context_destroy()

◆ p4est_vtk_context_new()

◆ p4est_vtk_context_set_continuous()

◆ p4est_vtk_context_set_geom()

◆ p4est_vtk_context_set_scale()

◆ p4est_vtk_write_cell_data()

◆ p4est_vtk_write_cell_dataf()

◆ p4est_vtk_write_cell_datav()

◆ p4est_vtk_write_file()

◆ p4est_vtk_write_footer()

◆ p4est_vtk_write_header()

◆ p4est_vtk_write_header_ho()

◆ p4est_vtk_write_point_dataf()