3 Mesh Nodes and Elements

These routines describe and retreive the finite element mesh for this computation. A mesh, from the framework's perspective, is a list of elements, nodes, and other data that describes the computational domain. The FEM framework provides extensive support for creating, manipulating, and partitioning meshes.

A serial mesh consists of a single large piece. It's usually easiest to read and write serial meshes to existing, non-parallel file formats, and it can be easier to manipulate serial meshes. By contrast, a parallel mesh consists of several pieces, called chunks or partitions. Different processors can work on different pieces of a parallel mesh, so most of the computation is done using parallel meshes. A simple program might create or read in a single serial mesh in init, get a local chunk of the partitioned¹mesh in driver, and work on that chunk for the rest of the program. A more complex program might set an initial mesh in init; then get, work on, reassemble and repartition the mesh several times in driver via FEM_Update_mesh.

3.1 Mesh Entity Types

A mesh consists of entities, such as nodes and elements. Entities always have a local number, which is just the entities' current index in its array. Entites may also have a global number, which is the entity's index in the unpartitioned serial mesh. Entities have data values called attributes. For example, the location of each node might be called the ``location'' attribute of the ``node'' entity type. Attributes are always stored in regular arrays indexed by the entity's local number. This table lists the different attributes that can be read or written for each type of entity.

A shared entity is a boundary entitity that two or more chunks can both update--currently, only nodes can be shared. Shared nodes are mixed in with regular nodes, and the framework currently provides no way to identify which nodes are shared.

A ghost entity is a boundary entity that is asymmetrically shared--one side provides values for the ghost from one of its real entities, and the other sides accept read-only copies of these values. Ghosts are described in more detail in Section 5, and can be accessed by adding the constant FEM_GHOST to the corresponding real entity's type.

The different kinds of entities are described in the following sections.

Real Entity	Ghost Entity
FEM_NODE	FEM_GHOST+FEM_NODE
FEM_ELEM+	FEM_GHOST+FEM_ELEM+
FEM_SPARSE+	FEM_GHOST+FEM_SPARSE+

3.1.1 Nodes

FEM_NODE is the entity code for nodes, the simplest kind of entity. A node is a single point in the domain, and elements are defined by their nodes. Nodes can have the following attributes:

• FEM_DATA+ Uninterpreted user data, which might include material properties, boundary conditions, flags, etc. User data can have any data type and width. can be any number from 0 to one billion--it allows you to register several data fields with a single entity.

• FEM_GLOBALNO Global node numbers. Always a 1-wide index type.

• FEM_SYMMETRIES Symmetries that apply to this node. Always a 1-wide FEM_BYTE.

• FEM_NODE_PRIMARY Marker indicating that this chunk is responsible for this node. Every node is primary in exactly one chunk. This attribute is always a 1-wide FEM_BYTE containing 0 or 1.

3.1.2 Elements

FEM_ELEM+ is the entity code for one kind of element. is a small, user-defined value that uniquely identifies this element type. Like nodes, elements can have the attributes FEM_DATA+, FEM_GLOBALNO, or FEM_SYMMETRIES; but every element type must have this attribute:

• FEM_CONN Lists the numbers of the nodes around this element. See the description in the ghost section for special ghost connectivity. Always an index type-FEM_INDEX_0 for C-style 0-based node indexing, or FEM_INDEX_1 for Fortran-style 1-based node indexing.

3.1.3 Sparse Elements

FEM_SPARSE+ is the entity code for one kind of sparse element. Again, is a small, user-defined unique value. The only difference between ordinary elements and sparse elements regards partitioning. Ignoring ghosts, ordinary elements are never duplicated--each element is sent to its own chunk. Sparse elements may be duplicated, and are always dependent on some other entity for their partitioning. Sparse elements have all the attributes of ordinary elements: FEM_DATA+, FEM_GLOBALNO, FEM_SYMMETRIES, and FEM_CONN, as well as the special attribute FEM_SPARSE_ELEM.

Without the FEM_SPARSE_ELEM attribute, a sparse element will be copied to every chunk that contains all the sparse element's nodes. This is useful for things like node-associated boundary conditions, where the sparse element connectivity might list the nodes with boundary conditions, and the sparse element data might list the boundary condition values.

The FEM_SPARSE_ELEM attribute lists the ordinary element each sparse element should be partitioned with. This attribute consists of pairs (,), indicating that this sparse element should be sent to wherever the 'th FEM_ELEM+ is partitioned.

• FEM_SPARSE_ELEM Lists the element we should be partitioned with. The width of this attribute is always 2, and the data type must be an index type-FEM_INDEX_0 or FEM_INDEX_1.

3.2 Mesh Entity Manipulation

int FEM_Mesh_default_read(void);
INTEGER function :: FEM_Mesh_default_read()

Return the default reading mesh. This routine is valid:

• From driver(), to return the partitioned mesh.
• During your FEM_Update_mesh routine, to return the assembled mesh.
• Anytime after a call to FEM_Mesh_set_default_read.

int FEM_Mesh_default_write(void);
INTEGER function :: FEM_Mesh_default_write()

Return the default writing mesh. This routine is valid:

• From init(), to change the new serial mesh.
• From driver(), to change the new partitioned mesh.
• During your FEM_Update_mesh routine, to change the new serial mesh.
• Anytime after a call to FEM_Mesh_set_default_write.

int FEM_Mesh_get_length(int mesh,int entity);
INTEGER function :: FEM_Mesh_get_length(mesh,entity)
INTEGER, INTENT(IN) :: mesh,entity

Return the number of entitys that exist in this mesh.

This call can be used with any entity. For example, to get the number of nodes,

      nNodes=FEM_Mesh_get_length(mesh,FEM_NODE)
  

To get the number of ghost nodes,

      nGhostNodes=FEM_Mesh_get_length(mesh,FEM_GHOST+FEM_NODE)
  

To get the number of real elements of type 2,

   nElem=FEM_Mesh_get_length(mesh,FEM_ELEM+2)
  

void FEM_Mesh_data(int mesh,int entity,int attr, void *data, int first, int length, int datatype,int width);
SUBROUTINE FEM_Mesh_data(mesh,entity,attr,data,first,length,datatype,width)
INTEGER, INTENT(IN) :: mesh,entity,attr,first,length,datatype,width
datatype, intent(inout) :: data(width,length)

This is the one routine for getting or setting entity's attributes on the mesh.

• mesh A FEM mesh object. Depending on whether this is a reading or writing mesh, this routine reads from or writes to the data array you pass in.

• entity A FEM entity code, for example FEM_NODE or FEM_GHOST+FEM_ELEM+1.

• attr A FEM attribute code, for example FEM_DATA+ or FEM_CONN.

• data The user data to get or set. Each row of this array consists of width values, and contains the data values of the attribute for the corresponding entity. This data must be formatted as one of:
        datatype :: data(width,length)
        datatype :: data(width*length)
    

• first The first entity to affect. In C, this is normally 0; in Fortran, this is normally 1.

• length The number of entities to affect. The entities affected are thus those numbered from first to first+length-1. For now, length must be either 1, to touch a single entity; or else the total number of entities-that is, FEM_Mesh_get_length(mesh,entity).

• datatype The data type stored in this attribute. This is one of the standard FEM data types FEM_BYTE, FEM_INT, FEM_FLOAT, or FEM_DOUBLE; or else the C-style 0-based index type FEM_INDEX_0 or the Fortran-style 1-based index type FEM_INDEX_1. Alternatively, the equivalent types IDXL_BYTE, IDXL_INT, IDXL_FLOAT, IDXL_DOUBLE, IDXL_INDEX_0, or IDXL_INDEX_1 may be used.

• width The number of data items per entity.

For example, to set the element connectivity, which is stored as 3 integer node indices in nodes, you would:

/* C version */
   int *nodes=new int[3*nElems];
   ... fill out nodes ...
   FEM_Mesh_data(mesh,FEM_ELEM+1,FEM_CONN, nodes, 0,nElems, FEM_INDEX_0, 3);
   ... continue to use or delete nodes ...
   
! F90 version
   ALLOCATE(nodes(3,nElems))
   ... fill out nodes ...
   CALL FEM_Mesh_data(mesh,FEM_ELEM+1,FEM_CONN, nodes, 1,nElems, FEM_INDEX_1, 3)
   ... continue to use or delete nodes ...
  

To add a new node property with 2 double-precision numbers from an array mat (containing, for example, material properties), you would first pick an unused user data "tag", for example 13, and:

/* C version */
   double *mat=new double[2*nNodes];
   ...
   FEM_Mesh_data(mesh,FEM_NODE, FEM_DATA+13, mat, 0,nNodes, FEM_DOUBLE, 2);
   
! F90 version
   ALLOCATE(mat(2,nNodes))
   CALL FEM_Mesh_data(mesh,FEM_NODE,FEM_DATA+13, mat, 1,nNodes, FEM_DOUBLE, 2)
  

3.3 Entity Inquiry

int FEM_Mesh_get_width(int mesh,int entity,int attr);
INTEGER function :: FEM_Mesh_get_width(mesh,entity,attr)
INTEGER, INTENT(IN) :: mesh,entity,attr

Return the width of the attribute attr of entity of mesh. This is the value previously passed as ``width'' to FEM_Mesh_data.

int FEM_Mesh_get_datatype(int mesh,int entity,int attr);
INTEGER function :: FEM_Mesh_get_datatype(mesh,entity,attr)
INTEGER, INTENT(IN) :: mesh,entity,attr

Return the FEM data type of the attribute attr of entity of mesh. This is the value previously passed as ``datatype'' to FEM_Mesh_data.

int FEM_Mesh_get_entities(int mesh,int *entities);
INTEGER function :: FEM_Mesh_get_entities(mesh,entities)
INTEGER, INTENT(IN) :: mesh
INTEGER, INTENT(OUT) :: entities(:)

Extract an array of the different entities present in this mesh. Returns the number of entity types present. The entities array must be big enough to hold all the different entities in the mesh.

For example, a simple mesh might have two entity types: FEM_NODE and FEM_ELEM+1.

int FEM_Mesh_get_attributes(int mesh,int entity,int *attributes);
INTEGER function :: FEM_Mesh_get_attributes(mesh,entity,attributes)
INTEGER, INTENT(IN) :: mesh, entity
INTEGER, INTENT(OUT) :: attributes(:)

Extract an array of the different attributes of this entity. Returns the number of attribute types present. The attributes array must be big enough to hold all the attributes.

For example, a simple element might have three attributes: FEM_CONN for node connectivity, FEM_GLOBALNO for global element numbers, and FEM_DATA+7 for a material type.

const char *FEM_Get_entity_name(int entity,char *storage);
const char *FEM_Get_attr_name(int attr,char *storage);
const char *FEM_Get_datatype_name(int datatype,char *storage);

Return a human-readable name for this FEM entity, attribute, or datatype. The storage array must point to a buffer of at least 100 characters; this array might be used as temporary space to store the returned string.

These routines are only available in C.

3.4 Advanced Entity Manipulation

void FEM_Mesh_data_offset(int mesh,int entity,int attr, void *data, int first, int length, int datatype,int width, int offsetBytes,int distanceBytes,int skewBytes);
SUBROUTINE FEM_Mesh_data_offset(mesh,entity,attr,data,first,length,datatype,width, offsetBytes,distanceBytes,skewBytes)
INTEGER, INTENT(IN) :: mesh,entity,attr,first,length,datatype,width
INTEGER, INTENT(IN) :: offsetBytes,distanceBytes,skewBytes
datatype, intent(inout) :: data(width,length)

This routine is a more complicated version of FEM_Mesh_data. It allows you to get or set a mesh field directly from a user-defined structure. See the documentation of IDXL_Layout_offset in Section 8.2.2 for details on how to set offsetBytes, distanceBytes, and skewBytes.

void FEM_Mesh_data_layout(int mesh,int entity,int attr, void *data, int firstItem, int length, IDXL_Layout_t layout);
SUBROUTINE FEM_Mesh_data_layout(mesh,entity,attr,data,first,length,layout)
INTEGER, INTENT(IN) :: mesh,entity,attr,first,length,layout
INTEGER, INTENT(IN) :: layout

This routine is a more complicated version of FEM_Mesh_data. Like FEM_Mesh_data_offset, it allows you to get or set a mesh field directly from a user-defined structure; but this routine expects the structure to be described by an IDXL_Layout object.