Skip to content

Commit

Permalink
Add documentation, 2 assertions
Browse files Browse the repository at this point in the history
  • Loading branch information
@ljcarlin
ljcarlin committed Oct 22, 2023
1 parent 0de9313 commit 9ee0447
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 35 deletions.
53 changes: 30 additions & 23 deletions src/p4est_geometry.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@

/**
* \file p4est_geometry.c
* We provide the identity transformation for reference.
* We provide several transformations for reference.
* Please implement p4est_geometry_t as you see fit.
*/

Expand Down Expand Up @@ -108,17 +108,17 @@ p4est_geometry_destroy (p4est_geometry_t * geom)
}

/**
* Geometric coordinate transformation for default geometry created with
* \ref p4est_geometry_new_connectivity. May also be used for user
* convenience to build custom geometric coordinate transforms. See for
* example \ref p4est_geometry_sphere2d_X or \ref p4est_geometry_disk2d_X.
*
* Define the geometric transformation from logical space (where AMR
* is performed) to the physical space.
* Geometric coordinate transformation for geometry created with
* \ref p4est_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 \ref p4est_geometry_sphere2d_X or \ref p4est_geometry_disk2d_X.
*
* \param[in] geom associated geometry
* \param[in] which_tree tree id inside forest
* \param[in] abc coordinates in AMR space : [0,1]^3
* \param[in] abc tree-local reference coordinates : [0,1]^d.
* Note: abc[2] is only accessed by the P4_TO_P8 version
* \param[out] xyz cartesian coordinates in physical space after geometry
*
* \warning The associated geometry is assumed to have a connectivity
Expand All @@ -130,7 +130,9 @@ p4est_geometry_connectivity_X (p4est_geometry_t * geom,
p4est_topidx_t which_tree,
const double abc[3], double xyz[3])
{
P4EST_ASSERT(geom->user != NULL);
p4est_connectivity_t *connectivity = (p4est_connectivity_t *) geom->user;
P4EST_ASSERT(connectivity->tree_to_vertex != NULL);
const p4est_topidx_t *tree_to_vertex = connectivity->tree_to_vertex;
const double *v = connectivity->vertices;
double eta_x, eta_y, eta_z = 0.;
Expand Down Expand Up @@ -189,12 +191,13 @@ p4est_geometry_new_connectivity (p4est_connectivity_t * conn)
/**
* Geometric coordinate transformation for icosahedron geometry.
*
* Define the geometric transformation from logical space (where AMR
* is performed) to the physical space.
* Define the geometric transformation from tree-local reference coordinates
* to physical space
*
* \param[in] geom associated geometry
* \param[in] which_tree tree id inside forest
* \param[in] rst coordinates in AMR space : [0,1]^3
* \param[in] rst tree-local reference coordinates : [0,1]^2.
* Note: rst[2] is never accessed
* \param[out] xyz cartesian coordinates in physical space after geometry
*
*/
Expand Down Expand Up @@ -355,12 +358,13 @@ p4est_geometry_new_icosahedron (p4est_connectivity_t * conn, double R)
/**
* Geometric coordinate transformation for shell2d geometry.
*
* Define the geometric transformation from logical space (where AMR
* is performed) to the physical space.
* Define the geometric transformation from tree-local reference coordinates
* to physical space.
*
* \param[in] geom associated geometry
* \param[in] which_tree tree id inside forest
* \param[in] rst coordinates in AMR space : [0,1]^3
* \param[in] rst tree-local reference coordinates : [0,1]^2.
* Note: rst[2] is never accessed
* \param[out] xyz cartesian coordinates in physical space after geometry
*
*/
Expand Down Expand Up @@ -444,12 +448,13 @@ p4est_geometry_new_shell2d (p4est_connectivity_t * conn, double R2, double R1)
/**
* geometric coordinate transformation for disk2d geometry.
*
* Define the geometric transformation from logical space (where AMR
* is performed) to the physical space.
* Define the geometric transformation from tree-local reference coordinates
* to physical space.
*
* \param[in] geom associated geometry
* \param[in] which_tree tree id inside forest
* \param[in] rst coordinates in AMR space : [0,1]^3
* \param[in] rst tree-local reference coordinates : [0,1]^2.
* Note: rst[2] is never accessed.
* \param[out] xyz cartesian coordinates in physical space after geometry
*
* Note abc[3] contains cartesian coordinates in logical
Expand Down Expand Up @@ -571,12 +576,13 @@ p4est_geometry_new_disk2d (p4est_connectivity_t * conn, double R0, double R1)
/**
* geometric coordinate transformation for sphere2d geometry.
*
* Define the geometric transformation from logical space (where AMR
* is performed) to the physical space.
* Define the geometric transformation from tree-local reference coordinates to the
* physical space.
*
* \param[in] geom associated geometry
* \param[in] which_tree tree id inside forest
* \param[in] rst coordinates in AMR space : [0,1]^3
* \param[in] rst tree-local reference coordinates : [0,1]^2.
* Note: rst[2] is never accessed
* \param[out] xyz cartesian coordinates in physical space after geometry
*
*/
Expand All @@ -589,8 +595,9 @@ p4est_geometry_sphere2d_X (p4est_geometry_t * geom,
= &((p4est_geometry_builtin_t *) geom)->p.sphere2d;
double R;

/* transform from the AMR space into physical space using bi/trilinear
transformation of connectivity*/
/* transform from the tree-local reference coordinates into the cube-surface
* in physical space using vertex bi/trilinear transformation.
*/
p4est_geometry_connectivity_X (geom, which_tree, rst, xyz);

/* align cube center with origin */
Expand Down
49 changes: 37 additions & 12 deletions src/p4est_geometry.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,17 @@
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/

/** \file p4est_geometry.h transforms from vertex frame to physical space.
/** \file p4est_geometry.h transforms from tree-local "reference" coordinate system
* to global "physical space" coordinates. These are used in \ref p4est_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 Each tree has the local coordinate system [0,1]^d. For legacy/p8est
* compatibility reasons the local coordinates are always represented as a triple abc[3].
* For a 2D quadtree mesh the local coordinates are abc[0] and abc[1] and the third
* coordinate abc[2] should be ignored.
*
* \ingroup p4est
*/
Expand All @@ -37,10 +47,17 @@ SC_EXTERN_C_BEGIN;
/** This object encapsulates a custom geometry transformation. */
typedef struct p4est_geometry p4est_geometry_t;

/** Forward transformation from the reference unit square to physical space.
* Note that the two-dimensional connectivities have 3D vertex coordinates
* that can be used in the transformation if so desired.
* The physical space "xyz" is user-defined, currently used for VTK output.
/** Forward transformation from the tree-local coordinates to physical space.
*
* \note The two-dimensional connectivities built into p4est have 3D vertex coordinates
* that can be used in the transformation if so desired. However, connectivities are
* not in general required to have vertex coordinate information.
*
* \param[in] geom associated geometry
* \param[in] which_tree tree id inside forest
* \param[in] abc tree-local coordinates : [0,1]^d.
* For 2D meshes abc[2] should never be accessed.
* \param[out] xyz cartesian coordinates in physical space after geometry
*/
typedef void (*p4est_geometry_X_t) (p4est_geometry_t * geom,
p4est_topidx_t which_tree,
Expand All @@ -53,10 +70,10 @@ typedef void (*p4est_geometry_X_t) (p4est_geometry_t * geom,
*/
typedef void (*p4est_geometry_destroy_t) (p4est_geometry_t * geom);

/** Encapsulates a custom transformation from AMR space to
/** Encapsulates a custom transformation from tree-local coordinates to
* user defined physical space.
*
* Used in \ref p4est_vtk.h to write vtk files for visualization.
* \warning Used in \ref p4est_vtk.h to write global-coordinate meshes.
* In this case *user is assumed to point to a \ref p4est_connectivity.
* In general it can be used however the user likes.
*
Expand All @@ -81,27 +98,35 @@ void p4est_geometry_destroy (p4est_geometry_t * geom);

/** Create a geometry structure based on the vertices in a connectivity.
* The transformation is constructed using bilinear interpolation.
* \param [in] conn A p4est_connectivity_t with valid vertices. We do NOT
* take ownership and expect this structure to stay alive.
* \param [in] conn A p4est_connectivity_t with vertex coordinate information.
* We do NOT take ownership and expect this structure to stay alive.
* \return Geometry structure; use with p4est_geometry_destroy.
*/
p4est_geometry_t *p4est_geometry_new_connectivity (p4est_connectivity_t *
conn);

/** Create a geometry for mapping the 3d sphere using 2d connectivity icosahedron.
/** Create a geometry for mapping the sphere using 2d connectivity icosahedron.
*
* \param[in] conn The result of \ref p4est_connectivity_new_icosahedron.
* \param[in] R The radius of the sphere.
*
*/
p4est_geometry_t *p4est_geometry_new_icosahedron (p4est_connectivity_t *
conn, double R);

/** Create a geometry for mapping 2d shell.
/** Create a geometry for mapping the annulus.
* This a direct adaptation of geometric shell in 3d.
*
* \param[in] conn The result of \ref p4est_connectivity_new_shell2d.
* \param[in] R0 radius of the inner circle (internal border).
* \param[in] R1 radius of the outer circle (external border).
*
*/
p4est_geometry_t *p4est_geometry_new_shell2d (p4est_connectivity_t * conn,
double R2, double R1);

/**
* disk2d geometry associated to disk2d connectivity.
* Create disk2d geometry associated to disk2d connectivity.
*
* \param[in] conn The result of \ref p4est_connectivity_new_disk2d.
* \param[in] R0 radius of the inner circle.
Expand Down

0 comments on commit 9ee0447

Please sign in to comment.