# 12. `elements` — Definition of elements.

This modules allows for a consistent local numbering scheme of element connectivities throughout pyFormex. When interfacing with other programs, one should be aware that conversions may be necessary. Conversions to/from external programs should be done by the interface modules.

class `elements.``ElementType`

  Base class for element type classes.

  Element type data are stored in a class derived from ElementType. The derived element type classes contain only static data. No instances of these classes should be created. The base class defines the access methods, which are all class methods.

  Derived classes should be created by calling the function `createElementType()`.

  Each element is defined by the following attributes:

  - name: a string. It is capitalized before use, thus all ElementType subclasses have a name starting with an uppercase letter. Usually the name has a numeric last part, equal to the plexitude of the element.
  - doc: a string with a longer description of the lement type.
  - ndim: int (0..3): the dimensionality of the element:
    - 0: point
    - 1: line
    - 2: surface
    - 3: volume
  - vertices: the natural coordinates of its vertices,
  - edges: a list of edges, each defined by 2 or 3 node numbers,
  - faces: a list of faces, each defined by a list of minimum 3 node numbers,
  - element: a list of all node numbers
  - drawfaces: a list of faces to be drawn, if different from faces. This is an optional attribute. If defined, it will be used instead of the faces attribute to draw the element. This can e.g. be used to draw approximate representations for higher order elements for which there is no correct drawing function.

  The vertices of the elements are defined in a unit space [0,1] in each axis direction.

  The elements guarantee a fixed local numbering scheme of the vertices. One should however not rely on a specific numbering scheme of edges, faces or elements.

  For solid elements, it is guaranteed that the vertices of all faces are numbered in a consecutive order spinning positively around the outward normal on the face.

  The list of available element types can be found from:

      >>> printElementTypes()
      Available Element Types:
        0-dimensional elements: ['point']
        1-dimensional elements: ['line2', 'line3', 'line4']
        2-dimensional elements: ['tri3', 'tri6', 'quad4', 'quad6', 'quad8', 'quad9', 'quad12']
        3-dimensional elements: ['tet4', 'tet10', 'tet14', 'tet15', 'wedge6', 'hex8', 'hex16', 'hex20', 'hex27', 'octa', 'icosa']

  Optional attributes:

  - conversions: Defines possible strategies for conversion of the element to other element types. It is a dictionary with the target element name as key, and a list of actions as value. Each action in the list consists of a tuple ( action, data ), where action is one of the action identifier characters defined below, and data are the data needed for this action.

  Conversion actions:

  - ‘m’: add new nodes to the element by taking the mean values of existing nodes. data is a list of tuples containing the nodes numbers whose coorrdinates have to be averaged.
  - ‘s’: select nodes from the existing ones. data is a list of the node numbers to retain in the new element. This can be used to reduce the plexitude but also just to reorder the existing nodes.
  - ‘v’: perform a conversion via an intermediate type. data is the name of the intermediate element type. The current element will first be converted to the intermediate type, and then conversion from that type to the target will be attempted.
  - ‘r’: randomly choose one of the possible conversions. data is a list of element names. This can e.g. be used to select randomly between different but equivalent conversion paths.
  classmethod `nplex`()

    Return the plexitude of the element

  classmethod `nvertices`()

    Return the plexitude of the element

  classmethod `nnodes`()

    Return the plexitude of the element

  classmethod `getEntities`(level, reduce=False)

    Return the type and connectivity table of some element entities.

    The full list of entities with increasing dimensionality 0,1,2,3 is:

        ['points', 'edges', 'faces', 'cells' ]

    If level is negative, the dimensionality returned is relative to the highest dimensionality (.i.e., that of the element). If it is positive, it is taken absolute.

    Thus, for a 3D element type, getEntities(-1) returns the faces, while for a 2D element type, it returns the edges. For both types however, getLowerEntities(+1) returns the edges.

    The return value is a dict where the keys are element types and the values are connectivity tables. If reduce == False: there will be only one connectivity table and it may include degenerate elements. If reduce == True, an attempt is made to reduce the degenerate elements. The returned dict may then have multiple entries.

    If the requested entity level is outside the range 0..ndim, the return value is None.

  classmethod `getDrawFaces`(quadratic=False)

    Returns the local connectivity for drawing the element’s faces

  classmethod `toMesh`()

    Convert the element type to a Mesh.

    Returns a Mesh with a single element of natural size.

  classmethod `toFormex`()

    Convert the element type to a Formex.

    Returns a Formex with a single element of natural size.

  classmethod `name`()

    Return the lowercase name of the element.

    For compatibility, name() returns the lower case version of the ElementType’s name. To get the real name, use the attribute __name__ or format the ElementType as a string.

  classmethod `family`()

    Return the element family name.

    The element family name is the first part of the name that consists only of lower case letter.

## 12.1. Functions defined in module elements

`elements.``elementType`(name=None, nplex=-1)

  Return the requested element type

  Parameters:

  - name: a string (case ignored) with the name of an element. If not specified, or the named element does not exist, the default element for the specified plexitude is returned.
  - nplex: plexitude of the element. If specified and no element name was given, the default element type for this plexitude is returned.

  Returns a subclass of `ElementType`.

  Errors:

  > If neither name nor nplex can resolve into an element type, an error is raised.

  Example

      >>> elementType('tri3').name()
      'tri3'
      >>> elementType(nplex=2).name()
      'line2'

`elements.``elementTypes`(ndim=None)

  Return the available ElementTypes matching the criteria.

  If a value is specified for ndim, only the elements with the matching dimensionality are returned.

`elements.``elementNames`(ndim=None)

  Return the list of element names matching the criteria

`elements.``printElementTypes`(lower=False)

  Print all available element types.

  Prints a list of the names of all available element types, grouped by their dimensionality.