p4est  2.8.7
p4est is a software library for parallel adaptive mesh refinement.
•All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Data Structures | Typedefs | Enumerations | Functions
p8est_geometry.h File Reference
p8est

Transform from tree-local "reference" coordinate system to global "physical space" coordinates. More...

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

Go to the source code of this file.

Data Structures

struct  p8est_geometry
 This structure can be created by the user, p4est will never change its contents. More...
 

Typedefs

typedef struct p8est_geometry p8est_geometry_t
 This object encapsulates a custom geometry transformation.
 
typedef void(* p8est_geometry_X_t) (p8est_geometry_t *geom, p4est_topidx_t which_tree, const double abc[3], double xyz[3])
 Forward transformation from the reference unit square to physical space. More...
 
typedef void(* p8est_geometry_destroy_t) (p8est_geometry_t *geom)
 Destructor prototype for a user-allocated p8est_geometry_t. More...
 

Enumerations

enum  pillow_sphere_config_t {
  FIG52B = 0 ,
  FIG52C = 1
}
 Characterize different mappings of the solid sphere using a 1-tree connectivity. More...
 

Functions

void p8est_geometry_transform_coordinates (p8est_geometry_t *geom, p4est_topidx_t which_tree, p4est_qcoord_t coords_in[3], double coords_out[3])
 Transform a quadrant reference coordinate into the geometry. More...
 
void p8est_geometry_destroy (p8est_geometry_t *geom)
 Can be used to conveniently destroy a geometry structure. More...
 
p8est_geometry_t * p8est_geometry_new_connectivity (p8est_connectivity_t *conn)
 Create a geometry structure based on the vertices in a connectivity. More...
 
void p8est_geometry_connectivity_X (p8est_geometry_t *geom, p4est_topidx_t which_tree, const double abc[3], double xyz[3])
 Geometric coordinate transformation for geometry created with p8est_geometry_new_connectivity. More...
 
p8est_geometry_t * p8est_geometry_new_pillow (p8est_connectivity_t *conn, double R2, double R1)
 Create a geometry structure for the spherical shell of 2 trees. More...
 
p8est_geometry_t * p8est_geometry_new_pillow_sphere (p8est_connectivity_t *conn, double R, pillow_sphere_config_t config)
 Create a geometry for mapping the solid sphere using the 1-tree unit connectivity. More...
 
p8est_geometry_t * p8est_geometry_new_shell (p8est_connectivity_t *conn, double R2, double R1)
 Create a geometry structure for the spherical shell of 24 trees. More...
 
p8est_geometry_t * p8est_geometry_new_sphere (p8est_connectivity_t *conn, double R2, double R1, double R0)
 Create a geometry structure for the solid sphere of 13 trees. More...
 
p8est_geometry_t * p8est_geometry_new_torus (p8est_connectivity_t *conn, double R0, double R1, double R2)
 Create a geometry structure for the torus. More...
 
void p8est_geometry_coordinates_lnodes (p8est_t *p8est, p8est_lnodes_t *lnodes, const double *refloc, p8est_geometry_t *geom, sc_array_t *coordinates, sc_array_t *element_coordinates)
 Compute node coordinates for a p8est_lnodes structure. More...
 

Detailed Description

Transform from tree-local "reference" coordinate system to global "physical space" coordinates.

These are used in p8est_vtk.h to write global coordinate meshes to disk.

We provide several example geometries for use. You may also implement your own geometry as you see fit.

Note
For geometry purposes, each tree has the local coordinate system $[0,1]^3$.

Typedef Documentation

◆ p8est_geometry_destroy_t

typedef void(* p8est_geometry_destroy_t) (p8est_geometry_t *geom)

Destructor prototype for a user-allocated p8est_geometry_t.

It is invoked by p8est_geometry_destroy. If the user chooses to reserve the structure statically, there is no need to provide it.

◆ p8est_geometry_X_t

typedef void(* p8est_geometry_X_t) (p8est_geometry_t *geom, p4est_topidx_t which_tree, const double abc[3], double xyz[3])

Forward transformation from the reference unit square to physical space.

The physical space "xyz" is user-defined, currently used for VTK output.

Enumeration Type Documentation

◆ pillow_sphere_config_t

enum pillow_sphere_config_t

Characterize different mappings of the solid sphere using a 1-tree connectivity.

The different mappings correspond to the ones used to produce figure 5.2 in the following publication:

"Logically rectangular grids and finite volume methods for PDEs in circular and spherical domains", Calhoun et al, SIAM Review, volume 50, Issue 4, January 2008. https://doi.org/10.1137/060664094

Examples
simple/simple3.c.

Function Documentation

◆ p8est_geometry_connectivity_X()

void p8est_geometry_connectivity_X ( p8est_geometry_t *  geom,
p4est_topidx_t  which_tree,
const double  abc[3],
double  xyz[3] 
)

Geometric coordinate transformation for geometry created with p8est_geometry_new_connectivity.

This is defined by tri/binlinear interpolation from vertex coordinates.

May also be used as a building block in custom geometric coordinate transforms. See for example p8est_geometry_new_shell or p8est_geometry_new_sphere.

Parameters
[in]geomassociated geometry
[in]which_treetree id inside forest
[in]abctree-local reference coordinates : [0,1]^3.
[out]xyzCartesian coordinates in physical space after geometry
Warning
The associated geometry is assumed to have a connectivity as its *user field, and this connectivity is assumed to have vertex information in its *tree_to_vertex field.

◆ p8est_geometry_coordinates_lnodes()

void p8est_geometry_coordinates_lnodes ( p8est_t *  p8est,
p8est_lnodes_t *  lnodes,
const double *  refloc,
p8est_geometry_t *  geom,
sc_array_t *  coordinates,
sc_array_t *  element_coordinates 
)

Compute node coordinates for a p8est_lnodes structure.

Presently we allow for an lnodes degree of 1 or 2. Cubic or higher degrees may be transparently enabled in the future.

The simple mode assigns one tree reference coordinate to each lnode. This may not be suitable for visualizing periodic connectivities.

In a more advanced mode indicated by NULL element_coordinates input, the coordinates are made unique by reference location: If a tree is periodic, for example, its corners reference the same lnode but will generate separate coordinate entries for proper visualization. There will be more coordinates generated than there are lnodes.

The coordinate numbers generated by the present version of the function are partition-dependent. This may be seen as a flaw. Looking into it.

Parameters
[in]p8estA valid forest structure.
[in]lnodesA valid p4est_lnodes structure of degree 1 or 2. Higher degrees not presently allowed. Must be derived from the p8est.
[in]reflocEventually used for cubic and upwards degrees. We will expect degree + 1 many values for the one-dimensional reference node spacing. Out of these, the indices from 1 to (degree - 1) / 2 inclusive will be accessed by this function. The others default by symmetry considerations.
[in]geomMay be NULL for generating the tree-reference coordinates, or a valid geometry object for transforming the reference into mapped space.
[in,out]coordinatesOn input, an array with entries of 3 double variables each. Resized in this function and populated with coordinate tuples. With a NULL geometry, these are in [0, 1]**3. Otherwise, they are mapped by the geometry.
[in,out]element_coordinatesThis may be NULL, in which case we generate one coordinate tuple for each lnode. Otherwise, this must be an array with entries of type p4est_locidx_t. Is resized to the same number of entries as lnodes->element_nodes. Its entries point into the coordinates array. The tree index of any given entry is implicit in that this array is derived from a p4est, where sets of (degree + 1)**3 entries each correspond to the forest elements in order.

◆ p8est_geometry_destroy()

void p8est_geometry_destroy ( p8est_geometry_t *  geom)

Can be used to conveniently destroy a geometry structure.

The user is free not to call this function at all if they handle the memory of the p8est_geometry_t in their own way.

Examples
simple/simple3.c.

◆ p8est_geometry_new_connectivity()

p8est_geometry_t* p8est_geometry_new_connectivity ( p8est_connectivity_t *  conn)

Create a geometry structure based on the vertices in a connectivity.

The transformation is constructed using trilinear interpolation.

Parameters
[in]connA p8est_connectivity_t with valid vertices. We do NOT take ownership and expect this structure to stay alive.
Returns
Geometry structure; use with p4est_geometry_destroy.

◆ p8est_geometry_new_pillow()

p8est_geometry_t* p8est_geometry_new_pillow ( p8est_connectivity_t *  conn,
double  R2,
double  R1 
)

Create a geometry structure for the spherical shell of 2 trees.

Parameters
[in]connResult of p8est_connectivity_new_pillow. We do NOT take ownership and expect it to stay alive.
[in]R2The outer radius of the shell.
[in]R1The inner radius of the shell.
Returns
Geometry structure; use with p4est_geometry_destroy.
Note
this coordinate transformation is describe in "Logically rectangular grids and finite volume methods for PDEs in circular and spherical domains", Calhoun et al., https://doi.org/10.1137/060664094
Examples
simple/simple3.c.

◆ p8est_geometry_new_pillow_sphere()

p8est_geometry_t* p8est_geometry_new_pillow_sphere ( p8est_connectivity_t *  conn,
double  R,
pillow_sphere_config_t  config 
)

Create a geometry for mapping the solid sphere using the 1-tree unit connectivity.

See companion routine p4est_geometry_new_pillow_disk which maps the 2d disk using 1-tree unit connectivity.

Parameters
[in]connThe result of p8est_connectivity_new_unitcube.
[in]RThe radius of the solid sphere.
[in]configThe configuration to identify a mapping variant.
Examples
simple/simple3.c.

◆ p8est_geometry_new_shell()

p8est_geometry_t* p8est_geometry_new_shell ( p8est_connectivity_t *  conn,
double  R2,
double  R1 
)

Create a geometry structure for the spherical shell of 24 trees.

Parameters
[in]connResult of p8est_connectivity_new_shell or equivalent. We do NOT take ownership and expect it to stay alive.
[in]R2The outer radius of the shell.
[in]R1The inner radius of the shell.
Returns
Geometry structure; use with p4est_geometry_destroy.
Examples
simple/simple3.c, and userdata/userdata2.c.

◆ p8est_geometry_new_sphere()

p8est_geometry_t* p8est_geometry_new_sphere ( p8est_connectivity_t *  conn,
double  R2,
double  R1,
double  R0 
)

Create a geometry structure for the solid sphere of 13 trees.

Parameters
[in]connResult of p8est_connectivity_new_sphere or equivalent. We do NOT take ownership and expect it to stay alive.
[in]R2The outer radius of the sphere.
[in]R1The outer radius of the inner shell.
[in]R0The inner radius of the inner shell.
Returns
Geometry structure; use with p4est_geometry_destroy.
Examples
simple/simple3.c, and userdata/userdata2.c.

◆ p8est_geometry_new_torus()

p8est_geometry_t* p8est_geometry_new_torus ( p8est_connectivity_t *  conn,
double  R0,
double  R1,
double  R2 
)

Create a geometry structure for the torus.

This geometry maps a revolution torus, obtained using p8est_connectivity_new_torus.

The torus is divided into into segments around the revolution axis, each segment is made of 5 trees; so here we provided the geometric transformation in a piecewise manner for each tree of the connectivity.

Parameters
[in]connResult of p8est_connectivity_new_torus or equivalent. We do NOT take ownership and expect it to stay alive.
[in]R0The inner radius of the 2d disk slice as cross section.
[in]R1The outer radius of the 2d disk slice as cross section.
[in]R2The radius of the center circle of the torus. The outer radius of the torus is thus R1 + R2.
Returns
Geometry structure; use with p4est_geometry_destroy.
Examples
simple/simple3.c, and userdata/userdata2.c.

◆ p8est_geometry_transform_coordinates()

void p8est_geometry_transform_coordinates ( p8est_geometry_t *  geom,
p4est_topidx_t  which_tree,
p4est_qcoord_t  coords_in[3],
double  coords_out[3] 
)

Transform a quadrant reference coordinate into the geometry.

Parameters
[in]geomProperly initialized geometry object.
[in]which_treeValid tree number relative to the connectivity that is underlying the geometry.
[in]coords_inValid quadrant reference coordinates. They must be in [0, P4EST_ROOT_LEN]^3.
[out]coords_outCoordinates in the physical geometry.
Examples
simple/simple3.c.