Basic structure and properties

Name

Basic structure and properties -- 

Synopsis


#include <gfs.h>


struct      FttCell;
enum        FttCellFlags;
struct      FttVector;

#define     FTT_CELL_IS_ROOT                (c)
#define     FTT_CELL_IS_LEAF                (c)
#define     FTT_MAINTAINER

FttCell*    ftt_cell_new                    (FttCellInitFunc init,
                                             gpointer data);
void        (*FttCellInitFunc)              (FttCell *cell,
                                             gpointer data);
FttCell*    ftt_cell_copy                   (const FttCell *root,
                                             FttCellCopyFunc copy,
                                             gpointer data);
void        (*FttCellCopyFunc)              (const FttCell *from,
                                             FttCell *to,
                                             gpointer data);
void        ftt_cell_refine                 (FttCell *root,
                                             FttCellRefineFunc refine,
                                             gpointer refine_data,
                                             FttCellInitFunc init,
                                             gpointer init_data);
void        ftt_cell_refine_single          (FttCell *cell,
                                             FttCellInitFunc init,
                                             gpointer init_data);
gboolean    (*FttCellRefineFunc)            (FttCell *cell,
                                             gpointer data);
gboolean    ftt_refine_corner               (const FttCell *cell);
void        ftt_cell_refine_corners         (FttCell *cell,
                                             FttCellInitFunc init,
                                             gpointer data);
gboolean    (*FttCellCoarsenFunc)           (FttCell *cell,
                                             gpointer data);
gboolean    ftt_cell_coarsen                (FttCell *root,
                                             FttCellCoarsenFunc coarsen,
                                             gpointer coarsen_data,
                                             FttCellCleanupFunc cleanup,
                                             gpointer cleanup_data);
void        ftt_cell_flatten                (FttCell *root,
                                             FttDirection d,
                                             FttCellCleanupFunc cleanup,
                                             gpointer data);
gboolean    ftt_cell_check                  (const FttCell *cell);
void        ftt_cell_destroy                (FttCell *cell,
                                             FttCellCleanupFunc cleanup,
                                             gpointer data);
void        ftt_cell_destroy_root           (FttCell *root,
                                             FttCellChildren *children,
                                             FttCellCleanupFunc cleanup,
                                             gpointer data);
void        (*FttCellCleanupFunc)           (FttCell *cell,
                                             gpointer data);

#define     ftt_cell_level                  (c)
void        ftt_cell_set_level              (FttCell *root,
                                             guint level);
void        ftt_cell_pos                    (const FttCell *cell,
                                             FttVector *pos);
void        ftt_cell_relative_pos           (const FttCell *cell,
                                             FttVector *pos);
void        ftt_cell_set_pos                (FttCell *root,
                                             const FttVector *pos);
void        ftt_corner_pos                  (const FttCell *cell,
                                             FttDirection d[FTT_DIMENSION],
                                             FttVector *pos);
void        ftt_corner_relative_pos         (const FttCell *cell,
                                             FttDirection d[FTT_DIMENSION],
                                             FttVector *pos);
gdouble     ftt_level_size                  (guint level);
gdouble     ftt_cell_size                   (const FttCell *cell);
gdouble     ftt_cell_volume                 (const FttCell *cell);
#define     ftt_cell_parent                 (c)
guint       ftt_cell_depth                  (const FttCell *root);

Description

Details

struct FttCell

struct FttCell {

  guint flags;
  gpointer data;

};


enum FttCellFlags

typedef enum {
  FTT_FLAG_ID        = 7,
  FTT_FLAG_DESTROYED = 1 << 3,
  FTT_FLAG_LEAF      = 1 << 4,        /* used only for I/O operations */
  FTT_FLAG_TRAVERSED = FTT_FLAG_LEAF, /* used for face traversal */
  FTT_FLAG_USER      =      5         /* user flags start here */
} FttCellFlags;


struct FttVector

struct FttVector {

  gdouble x, y, z;
};


FTT_CELL_IS_ROOT()

#define  FTT_CELL_IS_ROOT(c)      ((c)->parent == NULL)

Evaluates to TRUE if c does not have any parent, FALSE otherwise.

c :

a FttCell.


FTT_CELL_IS_LEAF()

#define  FTT_CELL_IS_LEAF(c)      ((c)->children == NULL)

Evaluates to TRUE if c does not have any children, FALSE otherwise.

c :

a FttCell.


FTT_MAINTAINER

#define FTT_MAINTAINER "s.popinet@niwa.cri.nz"


ftt_cell_new ()

FttCell*    ftt_cell_new                    (FttCellInitFunc init,
                                             gpointer data);

init :

a FttCellInitFunc or NULL.

data :

user data to pass to init.

Returns :

a new root FttCell, initialized by calling init (if not NULL).


FttCellInitFunc ()

void        (*FttCellInitFunc)              (FttCell *cell,
                                             gpointer data);

This function is used to initialize extra user data associated with cell. For example to allocate extra memory, initialize user-defined variables etc...

cell :

a FttCell.

data :

user-data passed to the function.


ftt_cell_copy ()

FttCell*    ftt_cell_copy                   (const FttCell *root,
                                             FttCellCopyFunc copy,
                                             gpointer data);

root :

the root of the cell tree to copy.

copy :

a FttCellCopyFunc or NULL.

data :

user data to pass to copy.

Returns :

a new FttCell root of the cell tree copy of root. The attributes of the cells are copied using the user-defined copy function.


FttCellCopyFunc ()

void        (*FttCellCopyFunc)              (const FttCell *from,
                                             FttCell *to,
                                             gpointer data);

from :

to :

data :


ftt_cell_refine ()

void        ftt_cell_refine                 (FttCell *root,
                                             FttCellRefineFunc refine,
                                             gpointer refine_data,
                                             FttCellInitFunc init,
                                             gpointer init_data);

Recursively refines the tree starting from root. Each leaf of the tree is tested for refinement using the refine function. The new refined cells created are initialized using init (if not NULL) and are themselves recursively refined.

root :

a FttCell.

refine :

a FttCellRefineFunc.

refine_data :

user data to pass to refine.

init :

a FttCellInitFunc or NULL.

init_data :

user data to pass to init.


ftt_cell_refine_single ()

void        ftt_cell_refine_single          (FttCell *cell,
                                             FttCellInitFunc init,
                                             gpointer init_data);

Refines cell and eventually its neighbors to ensure that the neighborhood properties are preserved. The new refined cells created are initialized using init (if not NULL).

cell :

a FttCell.

init :

a FttCellInitFunc or NULL.

init_data :

user data to pass to init.


FttCellRefineFunc ()

gboolean    (*FttCellRefineFunc)            (FttCell *cell,
                                             gpointer data);

This function is used to control the refinement process of a cell tree.

cell :

a FttCell.

data :

user-data passed to the function.

Returns :

TRUE if cell must be refined, FALSE otherwise.


ftt_refine_corner ()

gboolean    ftt_refine_corner               (const FttCell *cell);

cell :

a FttCell.

Returns :

TRUE if cell is a leaf and if any of its "corner" neighbors are more than one level more refined, FALSE otherwise (see figure topology.fig).


ftt_cell_refine_corners ()

void        ftt_cell_refine_corners         (FttCell *cell,
                                             FttCellInitFunc init,
                                             gpointer data);

cell :

init :

data :


FttCellCoarsenFunc ()

gboolean    (*FttCellCoarsenFunc)           (FttCell *cell,
                                             gpointer data);

cell :

data :

Returns :


ftt_cell_coarsen ()

gboolean    ftt_cell_coarsen                (FttCell *root,
                                             FttCellCoarsenFunc coarsen,
                                             gpointer coarsen_data,
                                             FttCellCleanupFunc cleanup,
                                             gpointer cleanup_data);

Coarsens the cell tree defined by root according to coarsen.

root :

a FttCell root of a cell tree to coarsen.

coarsen :

a FttCellCoarsenFunc.

coarsen_data :

user data to pass to coarsen.

cleanup :

a FttCellCleanupFunc to call before destroying a cell or NULL.

cleanup_data :

user data to pass to cleanup.

Returns :

TRUE if root has been coarsened (i.e. root is now a leaf cell), FALSE otherwise.


ftt_cell_flatten ()

void        ftt_cell_flatten                (FttCell *root,
                                             FttDirection d,
                                             FttCellCleanupFunc cleanup,
                                             gpointer data);

Recursively destroys all the cells of the tree defined by root which do not form the boundary in direction d. The resulting cell tree is in effect a domain "flattened" in direction d.

The resulting domain is always one-cell thick in direction d.

root :

the root of the cell tree to flatten.

d :

the direction in which to flatten.

cleanup :

a FttCellCleanupFunc to call before destroying a cell.

data :

user data to pass to cleanup.


ftt_cell_check ()

gboolean    ftt_cell_check                  (const FttCell *cell);

cell :

a FttCell.

Returns :

TRUE if cell is consistent, FALSE otherwise.


ftt_cell_destroy ()

void        ftt_cell_destroy                (FttCell *cell,
                                             FttCellCleanupFunc cleanup,
                                             gpointer data);

Frees all memory allocated for cell and its descendants.

The user-defined function cleanup is called prior to freeing memory.

cell :

a FttCell.

cleanup :

a FttCellCleanupFunc to call before destroying cell or NULL.

data :

user data to pass to cleanup.


ftt_cell_destroy_root ()

void        ftt_cell_destroy_root           (FttCell *root,
                                             FttCellChildren *children,
                                             FttCellCleanupFunc cleanup,
                                             gpointer data);

Destroys the root cell of a cell tree but not its children. Each child becomes the root cell of a new cell tree. The new (orphaned) children are returned in children.

Note that the function will fail if root is also a leaf cell.

root :

the root cell of a cell tree.

children :

a FttCellChildren.

cleanup :

a FttCellCleanupFunc to call before destroying a cell. # data: user data to pass to cleanup.

data :


FttCellCleanupFunc ()

void        (*FttCellCleanupFunc)           (FttCell *cell,
                                             gpointer data);

Performs any cleanup action needed for the user data associated with cell prior to its destruction (example: freeing extra memory allocated at cell creation using a FttCellInitFunc function).

cell :

a FttCell about to be destroyed.

data :


ftt_cell_level()

#define     ftt_cell_level(c)

Evaluates to the level of c.

c :

a FttCell.


ftt_cell_set_level ()

void        ftt_cell_set_level              (FttCell *root,
                                             guint level);

Sets the level of the root cell of a cell tree to level. Updates the levels of its children recursively.

root :

a FttCell, root of a cell tree.

level :

the new level.


ftt_cell_pos ()

void        ftt_cell_pos                    (const FttCell *cell,
                                             FttVector *pos);

Fills pos with the coordinates of the center of cell.

cell :

a FttCell.

pos :

a FttVector.


ftt_cell_relative_pos ()

void        ftt_cell_relative_pos           (const FttCell *cell,
                                             FttVector *pos);

Fills pos with the coordinates of the center of cell relative to the center of its parent cell. The length unit is the size of the parent cell.

cell :

a FttCell (not a root cell).

pos :

a FttVector.


ftt_cell_set_pos ()

void        ftt_cell_set_pos                (FttCell *root,
                                             const FttVector *pos);

Sets the position of the center of the root cell of a cell tree to pos. Updates the positions of its children recursively.

root :

a FttCell, root of a cell tree.

pos :

a FttVector.


ftt_corner_pos ()

void        ftt_corner_pos                  (const FttCell *cell,
                                             FttDirection d[FTT_DIMENSION],
                                             FttVector *pos);

Fills pos with the coordinates of the corner of cell defined by d.

cell :

a FttCell.

d :

a set of perpendicular directions.

pos :

a FttVector.


ftt_corner_relative_pos ()

void        ftt_corner_relative_pos         (const FttCell *cell,
                                             FttDirection d[FTT_DIMENSION],
                                             FttVector *pos);

Fills pos with the coordinates (normalised by the size of cell) of the corner of cell defined by d relative to the position of the center of cell.

cell :

a FttCell.

d :

a set of perpendicular directions.

pos :

a FttVector.


ftt_level_size ()

gdouble     ftt_level_size                  (guint level);

level :

a guint.

Returns :

the size of a cell of level level.


ftt_cell_size ()

gdouble     ftt_cell_size                   (const FttCell *cell);

cell :

a FttCell.

Returns :

the size of cell.


ftt_cell_volume ()

gdouble     ftt_cell_volume                 (const FttCell *cell);

cell :

a FttCell.

Returns :

the volume (area in 2D) of cell.


ftt_cell_parent()

#define     ftt_cell_parent(c)

Evaluates to the parent of c. NULL is c is a root cell.

c :

a FttCell.


ftt_cell_depth ()

guint       ftt_cell_depth                  (const FttCell *root);

root :

a FttCell.

Returns :

the depth of the tree starting at root, i.e. the maximum level of any cell descendant of root.