p4est  1.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Typedefs | Functions
p8est_extended.h File Reference

Interface routines with extended capabilities. More...

#include <p8est.h>
#include <p8est_mesh.h>
#include <p8est_iterate.h>

Go to the source code of this file.

Data Structures

struct  p8est_inspect_t
 Data pertaining to selecting, inspecting, and profiling algorithms. More...
 

Typedefs

typedef void(* p8est_replace_t )(p8est_t *p8est, p4est_topidx_t which_tree, int num_outgoing, p8est_quadrant_t *outgoing[], int num_incoming, p8est_quadrant_t *incoming[])
 Callback function prototype to replace one set of quadrants with another. More...
 

Functions

p8est_tp8est_new_ext (sc_MPI_Comm mpicomm, p8est_connectivity_t *connectivity, p4est_locidx_t min_quadrants, int min_level, int fill_uniform, size_t data_size, p8est_init_t init_fn, void *user_pointer)
 Create a new forest. More...
 
p8est_mesh_tp8est_mesh_new_ext (p8est_t *p4est, p8est_ghost_t *ghost, int compute_tree_index, int compute_level_lists, p8est_connect_type_t btype)
 Create a new mesh. More...
 
void p8est_refine_ext (p8est_t *p8est, int refine_recursive, int maxlevel, p8est_refine_t refine_fn, p8est_init_t init_fn, p8est_replace_t replace_fn)
 Refine a forest with a bounded refinement level and a replace option. More...
 
void p8est_coarsen_ext (p8est_t *p8est, int coarsen_recursive, int callback_orphans, p8est_coarsen_t coarsen_fn, p8est_init_t init_fn, p8est_replace_t replace_fn)
 Coarsen a forest. More...
 
void p8est_balance_ext (p8est_t *p8est, p8est_connect_type_t btype, p8est_init_t init_fn, p8est_replace_t replace_fn)
 2:1 balance the size differences of neighboring elements in a forest. More...
 
void p8est_balance_subtree_ext (p8est_t *p8est, p8est_connect_type_t btype, p4est_topidx_t which_tree, p8est_init_t init_fn, p8est_replace_t replace_fn)
 
p4est_gloidx_t p8est_partition_ext (p8est_t *p8est, int partition_for_coarsening, p8est_weight_t weight_fn)
 Repartition the forest. More...
 
void p8est_iterate_ext (p8est_t *p8est, p8est_ghost_t *ghost_layer, void *user_data, p8est_iter_volume_t iter_volume, p8est_iter_face_t iter_face, p8est_iter_edge_t iter_edge, p8est_iter_corner_t iter_corner, int remote)
 p8est_iterate_ext adds the option remote: if this is false, then it is the same as p8est_iterate; if this is true, then corner/edge callbacks are also called on corners/edges for hanging faces/edges touched by local quadrants.
 
void p8est_save_ext (const char *filename, p8est_t *p8est, int save_data, int save_partition)
 Save the complete connectivity/p8est data to disk. More...
 
p8est_tp8est_load_ext (const char *filename, sc_MPI_Comm mpicomm, size_t data_size, int load_data, int autopartition, int broadcasthead, void *user_pointer, p8est_connectivity_t **connectivity)
 Load the complete connectivity/p4est structure from disk. More...
 
p8est_tp8est_source_ext (sc_io_source_t *src, sc_MPI_Comm mpicomm, size_t data_size, int load_data, int autopartition, int broadcasthead, void *user_pointer, p8est_connectivity_t **connectivity)
 The same as p8est_load_ext, but reading the connectivity/p8est from an open sc_io_source_t stream.
 

Detailed Description

Interface routines with extended capabilities.

Typedef Documentation

typedef void(* p8est_replace_t)(p8est_t *p8est, p4est_topidx_t which_tree, int num_outgoing, p8est_quadrant_t *outgoing[], int num_incoming, p8est_quadrant_t *incoming[])

Callback function prototype to replace one set of quadrants with another.

This is used by extended routines when the quadrants of an existing, valid p8est are changed. The callback allows the user to make changes to newly initialized quadrants before the quadrants that they replace are destroyed.

Parameters
[in]num_outgoingThe number of outgoing quadrants.
[in]outgoingThe outgoing quadrants: after the callback, the user_data, if p8est->data_size is nonzero, will be destroyed.
[in]num_incomingThe number of incoming quadrants.
[in,out]incomingThe incoming quadrants: prior to the callback, the user_data, if p8est->data_size is nonzero, is allocated, and the p8est_init_t callback, if it has been provided, will be called.

If the mesh is being refined, num_outgoing will be 1 and num_incoming will be 8, and vice versa if the mesh is being coarsened.

Function Documentation

void p8est_balance_ext ( p8est_t p8est,
p8est_connect_type_t  btype,
p8est_init_t  init_fn,
p8est_replace_t  replace_fn 
)

2:1 balance the size differences of neighboring elements in a forest.

Parameters
[in,out]p8estThe p8est to be worked on.
[in]btypeBalance type (face, edge, or corner/full). Corner balance is almost never required when discretizing a PDE; just causes smoother mesh grading.
[in]init_fnCallback function to initialize the user_data which is already allocated automatically.
[in]replace_fnCallback function that allows the user to change incoming quadrants based on the quadrants they replace.
void p8est_coarsen_ext ( p8est_t p8est,
int  coarsen_recursive,
int  callback_orphans,
p8est_coarsen_t  coarsen_fn,
p8est_init_t  init_fn,
p8est_replace_t  replace_fn 
)

Coarsen a forest.

Parameters
[in,out]p8estThe forest is changed in place.
[in]coarsen_recursiveBoolean to decide on recursive coarsening.
[in]callback_orphansBoolean to enable calling coarsen_fn even on non-families. In this case, the second quadrant pointer in the argument list of the callback is NULL, subsequent pointers are undefined, and the return value is ignored. If coarsen_recursive is true, it is possible that a quadrant is called once or more as an orphan and eventually becomes part of a family.
[in]coarsen_fnCallback function that returns true if a family of quadrants shall be coarsened.
[in]init_fnCallback function to initialize the user_data which is already allocated automatically.
[in]replace_fnCallback function that allows the user to change incoming quadrants based on the quadrants they replace.
p8est_t* p8est_load_ext ( const char *  filename,
sc_MPI_Comm  mpicomm,
size_t  data_size,
int  load_data,
int  autopartition,
int  broadcasthead,
void *  user_pointer,
p8est_connectivity_t **  connectivity 
)

Load the complete connectivity/p4est structure from disk.

It is possible to load the file with a different number of processors than has been used to write it. The partition will then be uniform.

Parameters
[in]filenameName of the file to read.
[in]mpicommA valid MPI communicator.
[in]data_sizeSize of data for each quadrant which can be zero. Then user_data_pool is set to NULL. If data_size is zero, load_data is ignored.
[in]load_dataIf true, the element data is loaded. This is only permitted if the saved data size matches. If false, the stored data size is ignored.
[in]autopartitionIgnore saved partition and make it uniform.
[in]broadcastheadHave only rank 0 read headers and bcast them.
[in]user_pointerAssign to the user_pointer member of the p4est before init_fn is called the first time.
[out]connectivityConnectivity must be destroyed separately.
Returns
Returns a valid forest structure. A pointer to a valid connectivity structure is returned through the last argument.
Note
Aborts on file errors or invalid file contents.
p8est_mesh_t* p8est_mesh_new_ext ( p8est_t p4est,
p8est_ghost_t ghost,
int  compute_tree_index,
int  compute_level_lists,
p8est_connect_type_t  btype 
)

Create a new mesh.

Parameters
[in]p8estA forest that is fully 2:1 balanced.
[in]ghostThe ghost layer created from the provided p4est.
[in]compute_tree_indexBoolean to decide whether to allocate and compute the quad_to_tree list.
[in]compute_level_listsBoolean to decide whether to compute the level lists in quad_level.
[in]btypeCurrently ignored, only face neighbors are stored.
Returns
A fully allocated mesh structure.
p8est_t* p8est_new_ext ( sc_MPI_Comm  mpicomm,
p8est_connectivity_t connectivity,
p4est_locidx_t  min_quadrants,
int  min_level,
int  fill_uniform,
size_t  data_size,
p8est_init_t  init_fn,
void *  user_pointer 
)

Create a new forest.

This is a more general form of p8est_new. See the documentation of p8est_new for basic usage.

Parameters
[in]min_quadrantsMinimum initial quadrants per processor. Makes the refinement pattern mpisize-specific.
[in]min_levelThe forest is refined at least to this level. May be negative or 0, then it has no effect.
[in]fill_uniformIf true, fill the forest with a uniform mesh instead of the coarsest possible one. The latter is partition-specific so that is usually not a good idea.
p4est_gloidx_t p8est_partition_ext ( p8est_t p8est,
int  partition_for_coarsening,
p8est_weight_t  weight_fn 
)

Repartition the forest.

The forest is partitioned between processors such that each processor has an approximately equal number of quadrants (or weight).

Parameters
[in,out]p8estThe forest that will be partitioned.
[in]partition_for_coarseningIf true, the partition is modified to allow one level of coarsening.
[in]weight_fnA weighting function or NULL for uniform partitioning.
Returns
The global number of shipped quadrants
void p8est_refine_ext ( p8est_t p8est,
int  refine_recursive,
int  maxlevel,
p8est_refine_t  refine_fn,
p8est_init_t  init_fn,
p8est_replace_t  replace_fn 
)

Refine a forest with a bounded refinement level and a replace option.

Parameters
[in,out]p8estThe forest is changed in place.
[in]refine_recursiveBoolean to decide on recursive refinement.
[in]maxlevelMaximum allowed refinement level (inclusive). If this is negative the level is restricted only by the compile-time constant QMAXLEVEL in p8est.h.
[in]refine_fnCallback function that must return true if a quadrant shall be refined. If refine_recursive is true, refine_fn is called for every existing and newly created quadrant. Otherwise, it is called for every existing quadrant. It is possible that a refinement request made by the callback is ignored. To catch this case, you can examine whether init_fn or replace_fn gets called.
[in]init_fnCallback function to initialize the user_data for newly created quadrants, which is guaranteed to be allocated. This function pointer may be NULL.
[in]replace_fnCallback function that allows the user to change incoming quadrants based on the quadrants they replace; may be NULL.
void p8est_save_ext ( const char *  filename,
p8est_t p8est,
int  save_data,
int  save_partition 
)

Save the complete connectivity/p8est data to disk.

This is a collective operation that all MPI processes need to call. All processes write into the same file, so the filename given needs to be identical over all parallel invocations. See p8est_load_ext for information on the autopartition parameter.

Parameters
[in]filenameName of the file to write.
[in]p8estValid forest structure.
[in]save_dataIf true, the element data is saved. Otherwise, a data size of 0 is saved.
[in]save_partitionIf false, save file as if 1 core was used. If true, save core count and partition. Advantage: Partition can be recovered on loading with same mpisize and autopartition false. Disadvantage: Makes the file depend on mpisize. Either way the file can be loaded with autopartition true.
Note
Aborts on file errors.