NAME

cxPyrMerge - selectively merges duplicated elements in layer of a pyramid

C SPECIFICATION

#include <cx/Pyramid.h>

enum cxPyrEquivType {
 CX_PYRAMID_EQUIV_IDENTICAL,
 CX_PYRAMID_EQUIV_IDENTICALR,
 CX_PYRAMID_EQUIV_CYCLIC,
 CX_PYRAMID_EQUIV_CYCLICR,
 CX_PYRAMID_EQUIV_SET
};

void cxPyrMerge(cxPyramid *pyr, int layer, cxPyrEquivType type)

FORTRAN SPECIFICATION

integer CX_PYRAMID_EQUIV_IDENTICAL
integer CX_PYRAMID_EQUIV_IDENTICALR
integer CX_PYRAMID_EQUIV_CYCLIC
integer CX_PYRAMID_EQUIV_CYCLICR
integer CX_PYRAMID_EQUIV_SET

parameter (CX_PYRAMID_EQUIV_IDENTICAL = 0)
parameter (CX_PYRAMID_EQUIV_IDENTICALR = 1)
parameter (CX_PYRAMID_EQUIV_CYCLIC  = 2)
parameter (CX_PYRAMID_EQUIV_CYCLICR  = 3)
parameter (CX_PYRAMID_EQUIV_SET  = 4)

subroutine cxPyrMerge(pyr,layer,type)
integer pyr
integer layer
integer type

PARAMETERS

pyr: Input pyramid data structure.
layer: Input number of the pyramid layer to be merged.
type: Input equivalence type to govern merging of elements.

DESCRIPTION

cxPyrMerge merges equivalent elements in one layer of a pyramid. The cxConnection connection list structure relates each element in layer layer to an ordered sequence of elements in layer layer - 1. Two elements in a layer are considered equivalent if they connect to the same sequence of elements in the lower layer, subject to the ordering restrictions specified by type. The equivalence types and their ordering restrictions are:

CX_PYRAMID_EQUIV_IDENTICAL sequences must be exactly identical.

CX_PYRAMID_EQUIV_IDENTICALR sequences must be exactly identical or be identical when one is reversed (same as CX_PYRAMID_EQUIV_IDENTICAL with reversal allowed).

CX_PYRAMID_EQUIV_CYCLIC sequences must be identical under some cyclical shift (or rotation) of one sequence.

CX_PYRAMID_EQUIV_CYCLICR sequences must be identical under a cyclical shift of one sequence or of its reversal (same as CX_PYRAMID_EQUIV_CYCLIC with reversal allowed).

CX_PYRAMID_SET sequences must contain the same indices in any order. The several equivalence types control the details of pyramid merging. A different equivalent definition may be, and often is, supplied for each layer when merging an entire pyramid. cxPyrMerge can be used to merge an entire pyramid as follows. cxPyrMerge is applied to one layer at a time, from layer zero (that is, closest to the base lattice) to the highest-numbered layer. Thus, at each layer equivalent elements are merged and references to the duplicates are removed. After the topmost layer is merged, cxPyrClean is called to remove unused elements in the pyramid. cxPyrClean can also remove duplicate entries in the topmost layer. Note that cxPyrMerge by itself does not remove the unreferenced elements in a pyramid. For example, to merge a finite element pyramid of tetrahedra, each of which is successively made up of vertices, edges, and faces, one would call cxPyrMerge three times, followed by a call to cxPyrClean. The merged pyramid will have only one representation of each face, edge, and vertex in the finite element grid. Each edge (at layer 0) is made up of two vertices from the base lattice. In this example, two edges are considered equivalent if they have the same vertices. For edges this is CX_PYRAMID_EQUIV_IDENTICALR equivalence. In a tetrahedron, each face (at layer 1) has three edges. In this example, two faces are considered equivalent if they have the same edges. For faces this is CX_PYRAMID_EQUIV_CYCLICR equivalence. Each tetrahedron (at layer 2) has four faces. In this example, two tetrahedra are considered equivalent if they have the same four faces, but in any order. For tetrahedra this is CX_PYRAMID_EQUIV_SET equivalence. Thus tetrahedral merging can be accomplished with the following C program fragment:

	cxPyrMerge( pyr, 0, CX_PYRAMID_EQUIV_IDENTICALR );
	cxPyrMerge( pyr, 1, CX_PYRAMID_EQUIV_CYCLICR );
	cxPyrMerge( pyr, 2, CX_PYRAMID_EQUIV_SET );
	cxPyrClean( pyr, 0 );

In Fortran the previous program fragment must pass an array of marks to cxPyrClean rather than a scalar, because it is not possible to pass a NULL pointer in Fortran. Merging elements in layer layer may modify connection entries in layer layer + 1, as the reference to the duplicate element is replaced by a reference to the original element.

NOTE