p4est  2.8.643-dbc7-dirty
p4est is a software library for parallel adaptive mesh refinement.
Data Structures | Macros | Typedefs | Enumerations | Functions
p4est_io.h File Reference

Provide functions to serialize/deserialize a forest. More...

#include <p4est.h>
Include dependency graph for p4est_io.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  p4est_file_section_metadata
 A data type that encodes the metadata of one data block in a p4est data file. More...
 

Macros

#define P4EST_FILE_MAGIC_NUMBER   "p4data0"
 magic string for p4est data files
 
#define P4EST_FILE_METADATA_BYTES   96
 number of file metadata bytes
 
#define P4EST_FILE_MAGIC_BYTES   8
 number of bytes of the magic number
 
#define P4EST_FILE_VERSION_STR_BYTES   24
 number of bytes of the version string
 
#define P4EST_FILE_ARRAY_METADATA_BYTES   14
 number of array metadata bytes
 
#define P4EST_FILE_ARRAY_METADATA_CHARS   (P4EST_FILE_ARRAY_METADATA_BYTES - 2)
 number of array metadata chars
 
#define P4EST_FILE_BYTE_DIV   16
 All data blocks are padded to be divisible by this.
 
#define P4EST_FILE_MAX_NUM_PAD_BYTES   (P4EST_FILE_BYTE_DIV + 1)
 We enforce to pad in any case and the padding string needs to contain two newline characters and therefore this is the maximal number of pad bytes.
 
#define P4EST_FILE_USER_STRING_BYTES   48
 number of user string bytes
 
#define P4EST_FILE_FIELD_HEADER_BYTES   (2 + P4EST_FILE_ARRAY_METADATA_BYTES + P4EST_FILE_USER_STRING_BYTES)
 number of bytes of one field header
 
#define P4EST_FILE_MAX_GLOBAL_QUAD   9999999999999999
 maximal number of global quadrants
 
#define P4EST_FILE_MAX_BLOCK_SIZE   9999999999999
 maximal number of block bytes
 
#define P4EST_FILE_MAX_FIELD_ENTRY_SIZE   9999999999999
 maximal number of bytes per field entry
 

Typedefs

typedef struct p4est_file_context p4est_file_context_t
 p4est data file format All p4est data files have 64 bytes file header section at the beginning of the file. More...
 
typedef enum p4est_file_error p4est_file_error_t
 Error values for p4est_file functions.
 
typedef struct p4est_file_section_metadata p4est_file_section_metadata_t
 A data type that encodes the metadata of one data block in a p4est data file.
 

Enumerations

enum  p4est_file_error {
  P4EST_FILE_ERR_SUCCESS = sc_MPI_ERR_LASTCODE ,
  P4EST_FILE_ERR_FILE ,
  P4EST_FILE_ERR_NOT_SAME ,
  P4EST_FILE_ERR_AMODE ,
  P4EST_FILE_ERR_NO_SUCH_FILE ,
  P4EST_FILE_ERR_FILE_EXIST ,
  P4EST_FILE_ERR_BAD_FILE ,
  P4EST_FILE_ERR_ACCESS ,
  P4EST_FILE_ERR_NO_SPACE ,
  P4EST_FILE_ERR_QUOTA ,
  P4EST_FILE_ERR_READ_ONLY ,
  P4EST_FILE_ERR_IN_USE ,
  P4EST_FILE_ERR_IO ,
  P4EST_FILE_ERR_FORMAT ,
  P4EST_FILE_ERR_SECTION_TYPE ,
  P4EST_FILE_ERR_CONN ,
  P4EST_FILE_ERR_P4EST ,
  P4EST_FILE_ERR_IN_DATA ,
  P4EST_FILE_ERR_COUNT ,
  P4EST_FILE_ERR_UNKNOWN ,
  P4EST_FILE_ERR_LASTCODE
}
 Error values for p4est_file functions. More...
 

Functions

sc_array_tp4est_deflate_quadrants (p4est_t *p4est, sc_array_t **data)
 Extract processor local quadrants' x y level data. More...
 
p4est_tp4est_inflate (sc_MPI_Comm mpicomm, p4est_connectivity_t *connectivity, const p4est_gloidx_t *global_first_quadrant, const p4est_gloidx_t *pertree, sc_array_t *quadrants, sc_array_t *data, void *user_pointer)
 Create a new p4est based on serialized data. More...
 
p4est_tp4est_inflate_null (sc_MPI_Comm mpicomm, p4est_connectivity_t *connectivity, const p4est_gloidx_t *global_first_quadrant, const p4est_gloidx_t *pertree, sc_array_t *quadrants, sc_array_t *data, void *user_pointer)
 Create a new p4est based on serialized data. More...
 
p4est_file_context_tp4est_file_open_create (p4est_t *p4est, const char *filename, const char *user_string, int *errcode)
 Begin writing file header and saving data blocks into a parallel file. More...
 
p4est_file_context_tp4est_file_open_read (p4est_t *p4est, const char *filename, char *user_string, int *errcode)
 Open a file for reading and read its user string on rank zero. More...
 
p4est_file_context_tp4est_file_write_block (p4est_file_context_t *fc, size_t block_size, sc_array_t *block_data, const char *user_string, int *errcode)
 Write a block section to an opened file. More...
 
p4est_file_context_tp4est_file_read_block (p4est_file_context_t *fc, size_t header_size, sc_array_t *header_data, char *user_string, int *errcode)
 Read a header block from an opened file. More...
 
p4est_file_context_tp4est_file_write_field (p4est_file_context_t *fc, size_t quadrant_size, sc_array_t *quadrant_data, const char *user_string, int *errcode)
 Write one (more) per-quadrant data set to a parallel output file. More...
 
p4est_file_context_tp4est_file_read_field (p4est_file_context_t *fc, size_t quadrant_size, sc_array_t *quadrant_data, char *user_string, int *errcode)
 Read one (more) per-quadrant data set from a parallel input file. More...
 
int p4est_file_info (p4est_t *p4est, const char *filename, char *user_string, sc_array_t *data_sections, int *errcode)
 Read metadata information of a file written by a matching forest. More...
 
int p4est_file_error_string (int errclass, char *string, int *resultlen)
 Turn p4est_file errcode into a string. More...
 
p4est_file_context_tp4est_file_write_p4est (p4est_file_context_t *fc, p4est_t *p4est, const char *quad_string, const char *quad_data_string, int *errcode)
 Write a p4est to an opened file. More...
 
p4est_file_context_tp4est_file_read_p4est (p4est_file_context_t *fc, p4est_connectivity_t *conn, size_t data_size, p4est_t **p4est, char *quad_string, char *quad_data_string, int *errcode)
 Read a p4est to an opened file using the MPI communicator of fc. More...
 
p4est_file_context_tp4est_file_write_connectivity (p4est_file_context_t *fc, p4est_connectivity_t *conn, const char *conn_string, int *errcode)
 Write a connectivity to an opened file. More...
 
p4est_file_context_tp4est_file_read_connectivity (p4est_file_context_t *fc, p4est_connectivity_t **conn, char *conn_string, int *errcode)
 Read a connectivity from an opened file. More...
 
int p4est_file_close (p4est_file_context_t *fc, int *errcode)
 Close a file opened for parallel write/read and free the context. More...
 

Detailed Description

Provide functions to serialize/deserialize a forest.

Some are used as building blocks for p4est_load and p4est_save. Others allow for saving and loading user-defined data to a parallel file.

Furthermore, this module provides functions to write and read general data files associated with a p4est.

Typedef Documentation

◆ p4est_file_context_t

typedef struct p4est_file_context p4est_file_context_t

p4est data file format All p4est data files have 64 bytes file header section at the beginning of the file.

The file header section is written to the file as string without NUL-termination (called string*) and is therefore readable in a text editor.

File Header (96 bytes): 7 bytes magic number (p4data0) and 1 byte new line char. 23 bytes p4est version string* and 1 byte new line char. 47 bytes user string* and 1 byte new line char. 16 bytes number of global quadrants.

The file header section is padded by 16 bytes consisting of 1 byte new line char succeeded by 14 bytes of spaces and 1 trailing byte new line char.

The actual data is stored in arrays corresponding to a mesh of a p4est or in block sections that have a fixed user-defined size. The block sections are written and read on rank 0. One data field stores a fixed number of bytes of user- defined data per quadrant of a certain p4est. Therefore, one user-defined data field is of the size p4est->global_num_quadrants * data_size, where data_size is set by the user. The file format is partition independent. The data fields are padded such that the number of bytes for an array is divisible by 16. The padding also enforced for data blocks that have a size that is divisble by 16. The p4est data file consists of a variable number (including 0) of these two types of data sections. Every data section includes 64 bytes of section header written at the beginning by p4est. These 64 bytes are again written to the file as string* and can be read using a text editor.

Data section Header (64 bytes): One byte data section type specific character (B for a block section and F for a data field), 1 byte space and 13 bytes size in number of bytes for a block section and data size per element in byte for a field section and one trailing byte new line char. 47 bytes user-defined string* and 1 byte new line char.

The structure of p4est and p8est data files differs only by the magic number.

The p4est metadata of a p4est data file can be accessed by p4est_file_info(). Opaque context used for writing a p4est data file.

Enumeration Type Documentation

◆ p4est_file_error

Error values for p4est_file functions.

Enumerator
P4EST_FILE_ERR_SUCCESS 

file function completed with success

P4EST_FILE_ERR_FILE 

invalid file handle

P4EST_FILE_ERR_NOT_SAME 

collective arg not identical

P4EST_FILE_ERR_AMODE 

access mode error

P4EST_FILE_ERR_NO_SUCH_FILE 

file does not exist

P4EST_FILE_ERR_FILE_EXIST 

file exists already

P4EST_FILE_ERR_BAD_FILE 

invalid file name

P4EST_FILE_ERR_ACCESS 

permission denied

P4EST_FILE_ERR_NO_SPACE 

not enough space

P4EST_FILE_ERR_QUOTA 

quota exceeded

P4EST_FILE_ERR_READ_ONLY 

read only file (system)

P4EST_FILE_ERR_IN_USE 

file currently open by other process

P4EST_FILE_ERR_IO 

other I/O error

P4EST_FILE_ERR_FORMAT 

read file has a wrong format

P4EST_FILE_ERR_SECTION_TYPE 

a valid non-matching section type

P4EST_FILE_ERR_CONN 

invalid serialized connectivity data

P4EST_FILE_ERR_P4EST 

invalid p4est data

P4EST_FILE_ERR_IN_DATA 

input data of file function is invalid

P4EST_FILE_ERR_COUNT 

read or write count error that was not classified as a format error

P4EST_FILE_ERR_UNKNOWN 

unknown error

P4EST_FILE_ERR_LASTCODE 

to define own error codes for a higher level application that is using p4est_file functions

Function Documentation

◆ p4est_deflate_quadrants()

sc_array_t* p4est_deflate_quadrants ( p4est_t p4est,
sc_array_t **  data 
)

Extract processor local quadrants' x y level data.

Optionally extracts the quadrant data as well into a separate array.

Parameters
[in]p4estThe forest is not modified.
[in,out]dataIf not NULL, pointer to a pointer that will be set to a newly allocated array with per-quadrant data. Must be NULL if p4est->data_size == 0.
Returns
An array of type p4est_qcoord_t that contains x y level for each quadrant on this processor. The tree information is not extracted.

◆ p4est_file_close()

int p4est_file_close ( p4est_file_context_t fc,
int *  errcode 
)

Close a file opened for parallel write/read and free the context.

This function does not abort on MPI I/O errors but returns NULL. Without MPI I/O the function may abort on file system dependent errors.

Parameters
[in,out]fcContext previously created by p4est_file_open_create or p4est_file_open_read (_ext). Is freed.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
0 for a successful call and -1 in case of an error. See also errcode argument.

◆ p4est_file_error_string()

int p4est_file_error_string ( int  errclass,
char *  string,
int *  resultlen 
)

Turn p4est_file errcode into a string.

Parameters
[in]errclassAn errcode that is output by a p4est_file function.
[in,out]stringAt least sc_MPI_MAX_ERROR_STRING bytes.
[out]resultlenLength of string on return.
Returns
P4EST_FILE_ERR_SUCCESS on success or something else on invalid arguments.

◆ p4est_file_info()

int p4est_file_info ( p4est_t p4est,
const char *  filename,
char *  user_string,
sc_array_t data_sections,
int *  errcode 
)

Read metadata information of a file written by a matching forest.

Matching refers to the global count of quadrants; partition is irrelevant.

This function parses the given file on rank 0 and broadcasts the information on the number of data fields contained to all other ranks. Collective call.

This function catches all I/O and file format errors and returns a valid MPI error class related to file handling. Errors are collectively synchronized.

If the number of bytes that the user intend to read is larger than the number bytes left in the file, the function prints out an information about this situation using P4EST_LERROR. In this case the function reads the bytes that are possible to read but returns NULL to indicate an error. If the file or block header information is not matching the passed parameters the function sets P4EST_FILE_ERR_FORMAT for errcode.

This function does not abort on MPI I/O errors but returns NULL. Without MPI I/O the function may abort on file system dependent errors.

Parameters
[in]p4estA p4est that is only required for the MPI communicator, and to verify the global quadrant count found in the file.
[in]filenamePath to parallel file.
[in,out]user_stringAt least P4EST_FILE_USER_STRING_BYTES bytes. This array will be filled with the user string of the file after a successful call of this function.
[in,out]data_sectionsAfter a successful function call this variable holds an array with a length corresponding to the number of data section in the file that are successfully found and seeked. The values in the array are the number of bytes of stored data per quadrant. Require elem_size->elem_size == sizeof (p4est_file_block_metadata_t) on input and preserve it on output. See p4est_file_block_metadata_t to obtain detailed information about the data blocks of the file.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
0 for a successful call and -1 in case of an error. See also errcode argument.

◆ p4est_file_open_create()

p4est_file_context_t* p4est_file_open_create ( p4est_t p4est,
const char *  filename,
const char *  user_string,
int *  errcode 
)

Begin writing file header and saving data blocks into a parallel file.

This function creates a new file or overwrites an existing one. It is collective and creates the file on a parallel file system. It takes an (optional) pointer to write a header of given size. This function leaves the file open if MPI I/O is available. It is necessary to call p4est_file_close (possibly after writing one or more data sets). The file is opened in a write-only mode.

We add some basic metadata to the file. The file written contains the file header and data sets as specified by the open/write functions called. The file header consists of the metadata specified by p4est.

The number of global quadrants must be less or equal P4EST_FILE_MAX_GLOBAL_QUAD.

It is the application's responsibility to write sufficient header information (cf. p4est_file_write_block) to determine the number and size of the data sets if such information is not recorded and maintained externally. However, p4est makes some metadata accessible via p4est_file_info.

This function does not abort on MPI I/O errors but returns NULL. Without MPI I/O the function may abort on file system dependent errors.

Parameters
[in]p4estValid forest.
[in]filenamePath to parallel file that is to be created.
[in]user_stringA user string that is written to the file header. Only P4EST_FILE_USER_STRING_BYTES bytes without NUL-termination are written to the file. If the user gives less bytes the user_string in the file header is padded by spaces.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Newly allocated context to continue writing and eventually closing the file. NULL in case of error.

◆ p4est_file_open_read()

p4est_file_context_t* p4est_file_open_read ( p4est_t p4est,
const char *  filename,
char *  user_string,
int *  errcode 
)

Open a file for reading and read its user string on rank zero.

The user string is broadcasted to all ranks after reading. The file must exist and be at least of the size of the file header.

If the file has wrong metadata the function reports the error using /ref P4EST_LERRORF, collectively close the file and deallocate the file context. In this case the function returns NULL on all ranks. The wrong file format or a wrong file header causes P4EST_FILE_ERR_FORMAT as errcode.

This function does not abort on MPI I/O errors but returns NULL. Without MPI I/O the function may abort on file system dependent errors.

Parameters
[in]p4estThe forest must be of the same refinement pattern as the one used for writing the file. Its global number of quadrants must match. It is possible, however, to use a different partition or number of ranks from writing it.
[in]filenameThe path to the file that is opened.
[in,out]user_stringAt least P4EST_FILE_USER_STRING_BYTES bytes. The user string is written to the passed array including padding spaces and a trailing NUL-termination.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Newly allocated context to continue reading and eventually closing the file. NULL in case of error.

◆ p4est_file_read_block()

p4est_file_context_t* p4est_file_read_block ( p4est_file_context_t fc,
size_t  header_size,
sc_array_t header_data,
char *  user_string,
int *  errcode 
)

Read a header block from an opened file.

This function requires an opened file context. The header data is read on rank 0.

If the user does not have the header_size to call this function, the user can user p4est_file_info to obtain the required information.

The passed header_size is compared to the header_size stored in the file. If the values do not equal each other, the function reports details via /ref P4EST_LERRORF and closes and deallocate the file context. The return value in this case is NULL. If the block header information is not matching the passed parameters the function sets P4EST_FILE_ERR_FORMAT for errcode.

This function does not abort on MPI I/O errors but returns NULL. Without MPI I/O the function may abort on file system dependent errors.

Parameters
[out]fcContext previously created by p4est_file_open_create.
[in]header_sizeThe size of the header that is read.
[in,out]header_dataheader_size allocated bytes in an sc_array with one element and header_size as element size. This data will be filled with the header data from file. If this is NULL it means that the current header block is skipped and the internal file pointer of the file context is set to the next data block. If current data block is not a header block, the file is closed and the file context is deallocated. Furthermore, in this case the function returns NULL and sets errcode to P4EST_FILE_ERR_FORMAT. In case of skipping the header section header_size needs also to coincide with the header size given in the file.
[in,out]user_stringAt least P4EST_FILE_USER_STRING_BYTES bytes. Filled by the padded user string and a trailing NUL-termination char.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Return the input context to continue reading and eventually closing the file. The return value is NULL if the function was called for header_size == 0. The return value is also NULL in case of error but then it also holds errcode != 0 and the file is tried to close and fc is freed.

◆ p4est_file_read_connectivity()

p4est_file_context_t* p4est_file_read_connectivity ( p4est_file_context_t fc,
p4est_connectivity_t **  conn,
char *  conn_string,
int *  errcode 
)

Read a connectivity from an opened file.

This function reads two block sections from the opened file. The first block contains the size of the serialized connectivity data and the second data block contains serialized connectivity.

Parameters
[in,out]fcContext previously created by p4est_file_open_read (_ext). It keeps track of the data sets written one after another.
[out]connThe connectivity that is read from the file.
[in,out]conn_stringThe user string that read for the connectivity data block section. At least P4EST_FILE_USER_STRING_BYTES bytes. The user string is read on rank 0 and internally broadcasted to all ranks.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Return a pointer to input context or NULL in case of errors that does not abort the program. In case of error the file is tried to close and fc is freed.

◆ p4est_file_read_field()

p4est_file_context_t* p4est_file_read_field ( p4est_file_context_t fc,
size_t  quadrant_size,
sc_array_t quadrant_data,
char *  user_string,
int *  errcode 
)

Read one (more) per-quadrant data set from a parallel input file.

This function requires an opened file context. This function requires the appropriate number of readable bytes. In practice, the data size to read should match the size written. This function reports an error if the number of bytes to read is bigger than the dataset that corresponds to the processor. The data size to read is encoded by the element size of quadrant_data It is legal to close a file before all data sets have been read.

The function closes and deallocates the file context and returns NULL if the bytes the user wants to read exceed the given file and/or the element size of the array given by quadrant_data->elem_size does not coincide with the element size according to the array metadata given in the file.

If the block header information is not matching the passed parameters the function sets P4EST_FILE_ERR_FORMAT for errcode.

This function does not abort on MPI I/O errors but returns NULL. Without MPI I/O the function may abort on file system dependent errors.

Parameters
[in,out]fcContext previously created by p4est_file_open_read (_ext). It keeps track of the data sets read one after another.
[in]quadrant_sizeThe number of bytes per quadrant. This number must coincide with quadrant_data->elem_size.
[in,out]quadrant_dataAn array of the length number of local quadrants with the element size equal to number of bytes read per quadrant. The quadrant data is read according to the Morton order of the quadrants. quadrant_data->elem_size must coincide with the section data size in the file. quadrant_data == NULL means that the data is skipped and the internal file pointer is incremented. In the case of skipping quadrant_size is still checked using the corresponding value read from the file. If fc was opened by p4est_file_open_read_ext and fc->global_first_quadrant was not set by the user, the function uses a uniform partition to read the data field in parallel. quadrant_data is resized by sc_array_resize.
[in,out]user_stringAt least P4EST_FILE_USER_STRING_BYTES bytes. The user string is read on rank 0 and internally broadcasted to all ranks.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Return a pointer to input context or NULL in case of errors that does not abort the program or if the function was called with quadrant_data == NULL. In case of error the file is tried to close and fc is freed.

◆ p4est_file_read_p4est()

p4est_file_context_t* p4est_file_read_p4est ( p4est_file_context_t fc,
p4est_connectivity_t conn,
size_t  data_size,
p4est_t **  p4est,
char *  quad_string,
char *  quad_data_string,
int *  errcode 
)

Read a p4est to an opened file using the MPI communicator of fc.

Parameters
[in,out]fcContext previously created by p4est_file_open_read (_ext). It keeps track of the data sets read one after another.
[in]connA connectivity that is used to create the p4est.
[in]data_sizeThe data size of the p4est that will be created by this function.
[out]p4estThe p4est that is created from the file.
[in,out]quad_stringThe user string of the quadrant section. At least P4EST_FILE_USER_STRING_BYTES bytes. The user string is read on rank 0 and internally broadcasted to all ranks.
[in,out]quad_data_stringThe user string of the quadrant data section. At least P4EST_FILE_USER_STRING_BYTES bytes. The user string is read on rank 0 and internally broadcasted to all ranks.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Return a pointer to input context or NULL in case of errors that does not abort the program. In case of error the file is tried to close and fc is freed.

◆ p4est_file_write_block()

p4est_file_context_t* p4est_file_write_block ( p4est_file_context_t fc,
size_t  block_size,
sc_array_t block_data,
const char *  user_string,
int *  errcode 
)

Write a block section to an opened file.

This function requires an opened file context. The block data and its metadata are written on rank 0. The number of block bytes must be less or equal P4EST_FILE_MAX_BLOCK_SIZE.

This function does not abort on MPI I/O errors but returns NULL. Without MPI I/O the function may abort on file system dependent errors.

Parameters
[out]fcContext previously created by p4est_file_open_create.
[in]block_sizeThe size of block in bytes. May be equal to 0. In this case the section header and the padding is still written. This function returns the passed fc parameter and sets errcode to P4EST_FILE_ERR_SUCCESS if it is called for block_size == 0.
[in]block_dataA sc_array with one element and element size equal to block_size. The array points to the block data. The user is responsible for the validality of the block data. block_data can be NULL if block_size == 0.
[in]user_stringMaximal P4EST_FILE_USER_STRING_BYTES bytes. These chars are written to the block header and padded to P4EST_FILE_USER_STRING_BYTES - 1 chars by adding spaces. The '\0' is not written to the file.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Return the input context to continue writing and eventually closing the file. The return value is NULL in case of error, then it also holds errcode != 0 and the file is tried to close and fc is freed.

◆ p4est_file_write_connectivity()

p4est_file_context_t* p4est_file_write_connectivity ( p4est_file_context_t fc,
p4est_connectivity_t conn,
const char *  conn_string,
int *  errcode 
)

Write a connectivity to an opened file.

This function writes two block sections to the opened file. The first block contains the size of the serialized connectivity data and the second data block contains serialized connectivity.

Parameters
[in,out]fcContext previously created by p4est_file_open_create. It keeps track of the data sets written one after another.
[in]connThe connectivity that is written to the file.
[in]conn_stringThe user string that written for the connectivity data block section. An array of maximal P4EST_FILE_USER_STRING_BYTES bytes that is written without the NUL-termination after the section-dependent metadata and before the actual data. If the char array is shorter the written char array will be padded to the right by spaces. The user_string is written on rank 0 and therefore also only required on rank 0. Can be NULL for other ranks.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Return a pointer to input context or NULL in case of errors that does not abort the program. In case of error the file is tried to close and fc is freed.

◆ p4est_file_write_field()

p4est_file_context_t* p4est_file_write_field ( p4est_file_context_t fc,
size_t  quadrant_size,
sc_array_t quadrant_data,
const char *  user_string,
int *  errcode 
)

Write one (more) per-quadrant data set to a parallel output file.

This function requires an opened file context. The data set is appended to the header/previously written data sets. This function writes a block of the size number of quadrants * data_size.

The number of bytes per field entry must be less or equal P4EST_FILE_MAX_FIELD_ENTRY_SIZE.

This function does not abort on MPI I/O errors but returns NULL. Without MPI I/O the function may abort on file system dependent errors.

Parameters
[out]fcContext previously created by p4est_file_open_create.
[in]quadrant_sizeThe number of bytes per quadrant. This number must coincide with quadrant_data->elem_size.
[in]quadrant_dataAn array of the length number of local quadrants with the element size equal to number of bytes written per quadrant. The quadrant data is expected to be stored according to the Morton order of the quadrants. For quadrant_data->elem_size == 0 the function writes an empty field. The section header and the padding is still written. In this case errcode is set to P4EST_FILE_ERR_SUCCESS.
[in]user_stringAn array of maximal P4EST_FILE_USER_STRING_BYTES bytes that is written without the NUL-termination after the array-dependent metadata and before the actual data. If the char array is shorter the written char array will be padded to the right by spaces. The user_string is written on rank 0 and therefore also only required on rank 0. Can be NULL for other ranks.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Return the input context to continue writing and eventually closing the file. The return value is NULL if the function was called for quadrant_data->elem_size == 0. The return value is also NULL in case of error but then it also holds errcode != 0 and the file is tried to close and fc is freed.

◆ p4est_file_write_p4est()

p4est_file_context_t* p4est_file_write_p4est ( p4est_file_context_t fc,
p4est_t p4est,
const char *  quad_string,
const char *  quad_data_string,
int *  errcode 
)

Write a p4est to an opened file.

This function does not write the connectvity of the p4est. If one want to write the connectivity, p4est_file_write_connectivity can be used.

Parameters
[in,out]fcContext previously created by p4est_file_open_create. It keeps track of the data sets written one after another.
[in]p4estThe p4est that is written to the file.
[in]quad_stringThe string that is used as user string for quadrant section. An array of maximal P4EST_FILE_USER_STRING_BYTES bytes that is written without the NUL-termination after the section-dependent metadata and before the actual data. If the char array is shorter the written char array will be padded to the right by spaces. The user_string is written on rank 0 and therefore also only required on rank 0. Can be NULL for other ranks.
[in]quad_data_stringThe string that is used as user string for quadrant data section. An array of maximal P4EST_FILE_USER_STRING_BYTES bytes that is written without the NUL-termination after the section-dependent metadata and before the actual data. If the char array is shorter the written char array will be padded to the right by spaces. The user_string is written on rank 0 and therefore also only required on rank 0. Can be NULL for other ranks.
[out]errcodeAn errcode that can be interpreted by p4est_file_error_string.
Returns
Return a pointer to input context or NULL in case of errors that does not abort the program. In case of error the file is tried to close and fc is freed.

◆ p4est_inflate()

p4est_t* p4est_inflate ( sc_MPI_Comm  mpicomm,
p4est_connectivity_t connectivity,
const p4est_gloidx_t global_first_quadrant,
const p4est_gloidx_t pertree,
sc_array_t quadrants,
sc_array_t data,
void *  user_pointer 
)

Create a new p4est based on serialized data.

Its revision counter is set to zero. See p4est.h and p4est_communication.h for more information on parameters.

Parameters
[in]mpicommA valid MPI communicator.
[in]connectivityThis is the connectivity information that the forest is built with. Note that p4est does not take ownership of the memory.
[in]global_first_quadrantFirst global quadrant on each proc and one beyond. Copied into global_first_quadrant. Local count on rank is gfq[rank + 1] - gfq[rank].
[in]pertreeThe cumulative quadrant counts per tree.
[in]quadrantsArray as returned by p4est_deflate_quadrants.
[in]dataArray as from p4est_deflate_quadrants or NULL. The elem_size of this array informs data_size. Its elem_count equals the number of local quads.
[in]user_pointerAssign to the user_pointer member of the p4est.
Returns
The newly created p4est with a zero revision counter.

◆ p4est_inflate_null()

p4est_t* p4est_inflate_null ( sc_MPI_Comm  mpicomm,
p4est_connectivity_t connectivity,
const p4est_gloidx_t global_first_quadrant,
const p4est_gloidx_t pertree,
sc_array_t quadrants,
sc_array_t data,
void *  user_pointer 
)

Create a new p4est based on serialized data.

Its revision counter is set to zero. See p4est.h and p4est_communication.h for more information on parameters. In contrast to p4est_inflate this function indicates soft errors by returning NULL.

Parameters
[in]mpicommA valid MPI communicator.
[in]connectivityThis is the connectivity information that the forest is built with. Note that p4est does not take ownership of the memory.
[in]global_first_quadrantFirst global quadrant on each proc and one beyond. Copied into global_first_quadrant. Local count on rank is gfq[rank + 1] - gfq[rank].
[in]pertreeThe cumulative quadrant counts per tree.
[in]quadrantsArray as returned by p4est_deflate_quadrants.
[in]dataArray as from p4est_deflate_quadrants or NULL. The elem_size of this array informs data_size. Its elem_count equals the number of local quads.
[in]user_pointerAssign to the user_pointer member of the p4est.
Returns
The newly created p4est with a zero revision counter. If the created p4est would not be valid, no p4est is created and the function returns NULL.