9. Utilities - Model, ElemChk, MassPrp

The Model module is designed to provide a convenient encapsulation of all objects which define an entire finite element model. The ElemChk module performs certain checks on element shape quality and connectivity consistency. The MassPrp module computes the gross mass properties of a finite element model. Computed quantities consist of total mass, center of mass and the mass moment of inertia tensor.

9.1. Finite Element Model - Model

The Model module encapsulates all VisTools objects which define a complete finite element model. This includes such information as element connectivity, node coordinates, element and material properties, load, restraint and initial condition cases, etc. It provides a single container for all other VisTools objects required to describe a finite element model.

The functions associated with a Model object are the following.

Instance a Model object initially using vis_ModelBegin(). The Model object primarily serves as a container for other VisTools objects which together define a complete finite element model. Use vis_ModelSetObject() to register the Connect and/or GridFun objects which define the element connectivity and associations and node coordinates. If a Connect object is registered and a GridFun object is not registered, Model will internally create and register a GridFun object tied to the Connect object. The Connect or GridFun object currently registered with the Model object can be queried using vis_ModelGetObject().

A ColorMap, GProp and/or Units object may also be registered using vis_ModelSetObject(). The ColorMap object is used to relate color indices (such as the VIS_COLORID node and element associations) to actual RGB color components. The GProp object is used to define global properties. The Units object is used to define the units for physical quantities.

Node and element sets are entered into IdTran objects. The IdTran objects are, in turn, entered into HashTable objects with a user defined integer key. If there is a useful integer associated with the node or element set, this integer should be used as the HashTable key otherwise use keys starting from one. The HashTable objects of node and/or element sets are registered in the Model object using vis_ModelSetHashTable(). For the HashTable of node sets the type argument in the vis_ModelSetHashTable() function is VIS_IDTRAN_NODE, for element sets it is VIS_IDTRAN_ELEM.

Element edge and face sets are also entered into IdTran objects. These IdTran objects are, in turn, entered into a HashTable object This HashTable object is registerd in the Model object using vis_ModelSetHashTable() with type argument VIS_IDTRAN_ELEMENT.

Element and material properties are entered into one or more EProp and MProp objects respectively. There should be an EProp object for each element property identifier and a MProp object for each material property identifier. The EProp objects are then entered into a HashTable object using the element property identifier as a key. The MProp objects are also entered into a HashTable object using the associated material property identifier as a key. The two HashTable objects containing the EProp and MProp objects are then registered in the Model object using vis_ModelSetHashTable().

Certain vector valued functions may be stored in one or more TCurve objects. These functions may represent relationships such as temperature dependent material properties or load factor time functions. The TCurve objects are entered into a HashTable object in a manner similar to EProp and MProp objects using an integer curve identifier as key. The HashTable object containing the TCurve objects is then registered in the Model object using vis_ModelSetHashTable().

Analytical surfaces may be stored in one or more ASurf objects. There should be an ASurf object for each analytical surface in the model. Each ASurf object is stored into a HashTable with an integer key. This HashTable, in turn, is stored in the Model object using vis_ModelSetHashTable() with the key VIS_ASURF.

Rigid bodies may be stored in one or more RBody objects. There should be an RBody object for each rigid body in the model. Each RBody object is stored into a HashTable with an integer key. This HashTable, in turn, is stored in the Model object using vis_ModelSetHashTable() with the key VIS_RBODY.

Some element properties, such as shell thickness, may be specified on an element by element basis using ElemDat objects. Each element property so defined is installed in a HashTable object using the property type as a key. Currently supported property types are as follows:

  • SYS_PROP_THICKNESS - thickness

  • SYS_PROP_NORMAL - normal

  • SYS_PROP_OFFSETVEC - offset vector

  • SYS_PROP_ELEMVEC - element local system orientation vector

  • SYS_PROP_MATLVEC - material local system orientation vector

  • SYS_PROP_ENDAX - end point A position or offset vector

  • SYS_PROP_ENDBX - end point B position or offset vector

  • SYS_PROP_FIBERBOT - location of shell bottom, usually for output

  • SYS_PROP_FIBERTOP - location of shell top, usually for output

A similar technique is used for load, restraint and initial condition cases. A LCase object is instanced for each load case and entered into a HashTable object using the load case identifier as a key. A RCase object is instanced for each restraint case and entered into a HashTable object using the restraint case identifier as a key. A MCase object is instanced for each multipoint constraint case and entered into a HashTable object using the multipoint constraint case identifier as a key. A ICase object is instanced for each initial condition case and entered into a HashTable object using the initial condition case identifier as a key. Register these HashTable objects with the Model using vis_ModelSetHashTable(). Any HashTable object registered with the Model object can be queried using vis_ModelGetHashTable().

Node and elements sets may be entered into series of IdTran objects. These IdTran objects of node sets and element sets are entered into a HashTable object of node sets and a HashTable object of element sets using the set identifier as a key. A name associated with each set may be specified using the vis_IdTranSetName() function. The node and element indices (not user id) are entered into the IdTran objects. Register these HashTable objects with the Model using vis_ModelSetHashTable().

Contact pairs may be entered into sets of CPair objects. The CPair objects are entered into a HashTable object using an integer key. Register this HashTable object with the Model using vis_ModelSetHashTable().

The properties of solution steps are entered into a sequence of SProp objects. The sequence of SProp objects are entered into a List object in the order in which the solution steps are to be performed. The first solution step is given identifier 1 in the List object, the second step identifier 2, etc. Register this List object with the Model using vis_ModelSetList(). Any List object registered with the Model object can be queried using vis_ModelGetList().

The function, vis_ModelDelete() is provided as a convenient mechanism for deleting all objects set in the Model object. This includes all attribute objects set using vis_ModelSetObject(), all HashTable objects set using vis_ModelSetHashTable() and the objects they in turn contain, and all List objects set using vis_ModelSetList() and the objects they in turn contain.

The vis_ModelWrite() function is provided to write the contents of the model object to industry standard file formats. An example of such a format is NASTRAN bulk data format.

The consistency of the entities and objects in the model object may be checked using vis_ModelCheck() and vis_ModelCheckSProp(). The vis_ModelCheck() function checks all node and elements in the Connect object for the existence of references to other entities and objects. For example, all nodes are checked for a VIS_CSYSID coordinate system identifier association. If the identifier is positive, then the existence of the associated CoordSys object in the VIS_COORDSYS HashTable is checked. For elements, all referenced nodes, element properties, materials, coordinate systems, etc. are checked for existence. The vis_ModelCheckSProp() checks a given SProp solution property object for the existence of all referenced objects.

Gap element property mapping.

Gap element          ABAQUS
-----------          ------
EPROP_UZERO
EPROP_FZERO
EPROP_KCLOSE > 0.    *SURFACE BEHAVIOR, PRESSURE-OVERCLOSURE=TABULAR
            = 0.    *SURFACE BEHAVIOR, PRESSURE-OVERCLOSURE=HARD
EPROP_KOPEN
EPROP_KTRANS
EPROP_MUSY           *FRICTION, ANISOTROPIC
EPROP_MUSZ
EPROP_MUKY
EPROP_MUKZ
EPROP_NOSEPARATION   *SURFACE BEHAVIOR, NO SEPARATION
EPROP_NOSLIP         *FRICTION, ROUGH

If EPROP_KCLOSE > 0., then the EPROP_UZERO, EPROP_FZERO and EPROP_KOPEN properties are used to create a tabular pressure-overclosure definition under the *SURFACE BEHAVIOR keyword.

Gap element          NASTRAN
-----------          -------
EPROP_UZERO          PGAP U0
EPROP_FZERO          PGAP F0
EPROP_KCLOSE         PGAP KA
EPROP_KOPEN          PGAP KB
EPROP_KTRANS         PGAP KT
EPROP_MUSY           PGAP MU1
EPROP_MUSZ != 0      PGAP MU2 (TMAX = -1.)
EPROP_MUKY != 0      PGAP MU2 (TMAX = 0.)
EPROP_MUKZ           ignored
EPROP_NOSEPARATION   ignored
EPROP_NOSLIP         ignored

9.2. Function Descriptions

The currently available Model functions are described in detail in this section.

vis_Model *vis_ModelBegin(void)

create an instance of a Model object

Create an instance of a Model object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a Model object using

void vis_ModelEnd (vis_Model *model)

Return the current value of a Model object error flag using

Vint vis_ModelError (vis_Model *model)

Returns:

The function returns a pointer to the newly created Model object. If the object creation fails, NULL is returned.

void vis_ModelEnd(vis_Model *p)

destroy an instance of a Model object

See vis_ModelBegin()

Vint vis_ModelError(vis_Model *p)

return the current value of a Model object error flag

See vis_ModelBegin()

void vis_ModelSetObject(vis_Model *p, Vint objecttype, Vobject *object)

set pointers to attribute objects.

Set a pointer to an attribute object. By default, all finite element topology, connectivity, node coordinate and node and element association queries are made through the Connect attribute object.

If the GridFun object is registered, it is used by the vis_ModelWrite() function for basic finite model queries rather than the Connect object.

The ColorMap object is useful for associating actual RGB color components to the VIS_COLORID node and element associations.

The GProp object is useful for defining global properties.

The Units object is useful for defining the units of physical quantities.

Get object as an output argument using

void vis_ModelGetObject (vis_Model *model,
                         Vint objecttype,
                         Vobject **object)

Parameters:
  • p – Pointer to Model object.

  • objecttype – The name of the object type to be set.

    x=VIS_CONNECT            Connect object
     =VIS_COLORMAP           ColorMap object
     =VIS_GRIDFUN            GridFun object
     =VIS_GPROP              GProp object
     =VIS_UNITS              Units object
    

  • object – Pointer to the object to be set.

void vis_ModelGetObject(vis_Model *p, Vint objecttype, Vobject **object)

get pointers to attribute objects.

See vis_ModelSetObject()

void vis_ModelSetHashTable(vis_Model *p, Vint type, vsy_HashTable *hashtable)

set pointers to HashTable objects.

Set a pointer to a HashTable object containing coordinate system, property, case and set objects.

Get hashtable as an output argument using

void vis_ModelGetHashTable (vis_Model *model,
                            Vint type,
                            vsy_HashTable **hashtable)

Parameters:
  • p – Pointer to Model object.

  • type – The name of the object type contained in the HashTable.

    x=VIS_COORDSYS           CoordSys objects
     =VIS_EPROP              EProp objects
     =VIS_MPROP              MProp objects
     =VIS_TCURVE             TCurve objects
     =VIS_ELEMDAT            ElemDat objects
     =VIS_IDTRAN_ELEM        IdTran objects of element sets
     =VIS_IDTRAN_NODE        IdTran objects of node sets
     =VIS_IDTRAN_ELEMENT     IdTran objects of element entities
     =VIS_LCASE              LCase objects
     =VIS_RCASE              RCase objects
     =VIS_MCASE              MCase objects
     =VIS_ICASE              ICase objects
     =VIS_CPAIR              CPair objects
     =VIS_ASURF              ASurf objects
    

  • hashtable – Pointer to the HashTable to be set.

void vis_ModelGetHashTable(vis_Model *p, Vint type, vsy_HashTable **hashtable)

get pointers to HashTable objects.

See vis_ModelSetHashTable()

void vis_ModelSetList(vis_Model *p, Vint type, vsy_List *list)

set pointers to List objects.

Set a pointer to a List object containing solution property or contact pair objects.

Get list as an output argument using

void vis_ModelGetList (vis_Model *model,
                       Vint type,
                       vsy_List **list)

Parameters:
  • p – Pointer to Model object.

  • type – The name of the object type contained in the List.

    x=VIS_SPROP              SProp objects
    

  • list – Pointer to the List to be set.

void vis_ModelWrite(vis_Model *p, Vint type, Vchar *path)

write model to standard file formats

Write models to industry standard file formats. If a GridFun object is set in Model using vis_ModelSetObject() then it is used for basic finite element model queries rather than the Connect object. As a general rule, only those objects registered in the Model object are written. For example, if only load cases are to be written then only the HashTable of LCase objects and a GridFun object should be set in Model.

The model entities supported at any one time may vary. Please contact Visual Kinematics for details.

Errors

  • SYS_ERROR_ENUM is generated if an improper type is specified.

  • SYS_ERROR_FILE is generated if the file can not be opened.

  • SYS_ERROR_NULLOBJECT is generated if a required object has not been set.

Parameters:
  • p – Pointer to Model object.

  • type – File type

    x=SYS_NASTRAN_BULKDATA   Write to NASTRAN bulk data file
     =SYS_ABAQUS_INPUT       Write to ABAQUS input file
     =SYS_ANSYS_INPUT        Write to ANSYS input file
     =SYS_PATRAN_NEUTRAL     Write to Patran neutral file
     =SYS_SDRC_UNIVERSAL     Write to SDRC universal file
     =SYS_FLUENT_MESH        Write to FLUENT (ASCII) mesh file
     =SYS_STL                Write to ASCII STL file.
    

  • path – File path

void vis_ModelDelete(vis_Model *p)

delete all set objects

Delete all objects which have been “Set” in the Model object. This includes all objects set using vis_ModelSetObject(), vis_ModelSetHashTable() and vis_ModelSetList() and the objects they may in turn contain.

Parameters:

p – Pointer to Model object.

void vis_ModelGetInteger(vis_Model *p, Vint type, Vint iparam[])

get integer model checking information

Query for integer model checking information. This function is useful for determining where non-existent or inconsistent references occurred during a call to vis_ModelCheck() or vis_ModelCheckSProp().

The parameter MODEL_NUMCHECKSTRING returns the number of descriptive strings generated during the model checking process. Access the descriptive strings using vis_ModelGetString().

Errors

VIS_ERROR_ENUM is generated if an improper type is specified.

Parameters:
  • p – Pointer to Model object.

  • type – Type of integer information to query

    x=SYS_NODE               Node index
     =SYS_ELEM               Element index
     =VIS_MPROP              Material identifier
     =VIS_EPROP              Property identifier
     =VIS_ELEMDAT            Element data identifier
     =VIS_TCURVE             Curve identifier
     =VIS_COORDSYS           Coordinate system identifier
     =VIS_RCASE              Restraint case identifier
     =VIS_LCASE              Load case identifier
     =VIS_ICASE              Initial condition case identifier
     =VIS_MCASE              Multipoint constraint case identifier
     =MODEL_NUMCHECKSTRING   Number of check strings generated
    

  • iparam[out] Returned integer information

void vis_ModelGetString(vis_Model *p, Vint type, Vchar cparam[])

get model checking descriptive string

Query for model checking descriptive strings. The number of descriptive strings may be obtained using vis_ModelGetInteger() with parameter MODEL_NUMCHECKSTRING. Note that MODEL_CHECKSTRINGn is the same as MODEL_CHECKSTRING + n.

Errors

SYS_ERROR_ENUM is generated if an improper type is specified.

Parameters:
  • p – Pointer to Model object.

  • type – Type of string information to query

    x=MODEL_CHECKSTRING      String 0
     =MODEL_CHECKSTRING0     String 0
     =MODEL_CHECKSTRING1     String 1
     =MODEL_CHECKSTRING2     String 2
     =MODEL_CHECKSTRING3     String 3
     =MODEL_CHECKSTRING4     String 4
    

  • cparam[out] Returned string information

void vis_ModelCheck(vis_Model *p, Vint *status)

check model entities and objects

Check the consistency of the node and element entities and the existence of objects which they may reference through positive integer node and element associations. If all model references exist and are consistent then the status is returned as 0, otherwise it is returned as 1. Checking is currently terminated after the first occurrence of a non-existent reference. If a non-zero status is returned then the function vis_ModelGetInteger() may be used to query for the node and element entities and associations which identify objects which do not exist. In addition the function vis_ModelGetString() may be called to access descriptive strings detailing the model errors detected.

Nodes are checked for the following associations.

  • VIS_CSYSID, Coordinate system identifier for CoordSys object in the VIS_COORDSYS HashTable.

Elements are checked for the existence of each node in their element connectivity as well as the following associations.

  • VIS_CSYSID, Coordinate system identifier for CoordSys object in the VIS_COORDSYS HashTable. If the identifier is a defined negative value, SYS_ELEMSYS_VECTOR or SYS_ELEMSYS_POSITION, then the SYS_PROP_ELEMVEC ElemDat object is checked for existence in the VIS_ELEMDAT HashTable.

  • If VIS_CMATFLAG is non-zero then VIS_CMATID material coordinate system identifier for CoordSys object in the VIS_COORDSYS HashTable. If the identifier is a defined negative value, SYS_ELEMSYS_VECTOR or SYS_ELEMSYS_POSITION, then the SYS_PROP_MATLVEC ElemDat object is checked for existence in the VIS_ELEMDAT HashTable.

  • VIS_MATLID, Material identifier for MProp object in the VIS_MPROP HashTable. If any material properties in MProp objects are defined by TCurve objects, then the existence of the TCurve object is checked in the VIS_TCURVE HashTable.

  • VIS_PROPID, Property identifier for EProp object in the VIS_EPROP HashTable. If any non-zero material identifiers exist in the EProp object, then the existence of the associated MProp objects is checked in the VIS_MPROP HashTable. The MProp objects are then checked for any referenced TCurve objects.

Errors

  • SYS_ERROR_NULLOBJECT is generated if no Connect object has been set.

  • SYS_ERROR_OPERATION is generated if the set Connect object contains no node or elements.

Parameters:
  • p – Pointer to Model object.

  • status[out] Status flag of model check

void vis_ModelCheckSProp(vis_Model *p, vis_SProp *sprop, Vint *status)

check model solution objects

Check the existence of objects which are referenced by the specified SProp object. If all references exist and are consistent then the status is returned as 0, otherwise it is returned as 1. Checking is currently terminated after the first occurrence of a non-existent reference. If a non-zero status is returned then the function vis_ModelGetInteger() may be used to query for the object identifiers which do not exist. In addition the function vis_ModelGetString() may be called to access descriptive strings detailing the model errors detected. The following SProp references are checked for existence.

  • SPROP_RCASE, Restraint case Id for RCase object in the VIS_RCASE HashTable.

  • SPROP_LCASE, Load case Id for LCase objects in the VIS_LCASE HashTable.

  • SPROP_TCURVE, Time case Id for TCurve objects in the VIS_TCURVE HashTable.

  • SPROP_LCASE_TREF, Load case Id for LCase object in the VIS_LCASE HashTable.

  • SPROP_MCASE, Multipoint constraint case Id for MCase objects in the VIS_MCASE HashTable.

Parameters:
  • p – Pointer to Model object.

  • sprop – Pointer to SProp object.

  • status[out] Status flag of solution property check

void vis_ModelPrint(vis_Model *p)

print model to standard output

Print model to standard output.

Parameters:

p – Pointer to Model object.

void vis_ModelElemThickness(vis_Model *p, Vint index, Vdouble thickness[])

query for element thickness property

Get the thicknesses at all nodes of the element index. The thickness is computed by first testing for an ElemDat object stored under the SYS_PROP_THICKNESS key in the VIS_ELEMDAT HashTable. If a non-zero thickness is not defined then a SYS_ELEM_SHELL type EProp object is tested for thickness using the element property identifier. If no thicknesses are defined they are all returned as zero.

Parameters:
  • p – Pointer to Model object.

  • index – Element index

  • thickness[out] Vector of element nodal thicknesses

void vis_ModelElemOffset(vis_Model *p, Vint index, Vdouble offset[])

query for element offset property

Get the offsets at all nodes of the element index. The offset is computed by first testing for an ElemDat object stored under the SYS_PROP_OFFSET key in the VIS_ELEMDAT HashTable. If a non-zero offset is not defined then a SYS_ELEM_SHELL type EProp object is tested for offset using the element property identifier. If no offsets are defined they are all returned as zero.

Parameters:
  • p – Pointer to Model object.

  • index – Element index

  • offset[out] Vector of element nodal offsets

9.3. Element Checking - ElemChk

The ElemChk module contains a number of functions to compute element shape parameters, perform connectivity consistency checks, compute normals to surface elements and compute the variation of scalar fields between adjacent elements. These functions are designed to allow poorly shaped elements or elements whose connectivity or normals may not be consistently aligned with adjacent elements. The ElemChk module also supports analysis error estimation and projected element sizes needed for mesh adaptation.

The functions associated with a ElemChk object are the following.

Instance a ElemChk object initially using vis_ElemChkBegin(). At this point a GridFun object must be set as an attribute object using vis_ElemChkSetObject() so that the ElemChk object can access finite element model information. Note that all internal computations are performed in double precision and data is accessed in double precison from the GridFun attribute object and any other State objects which are passed as arguments. If full double precison accuracy is required then the internal representation of real values in the implementation of GridFun and the State object should be double precision.

The most generally useful computation performed by ElemChk is the calculation of element shape data using vis_ElemChkData(). These shape parameters, often termed “distortion” parameters, include element aspect ratio, taper, skew, total volume (Jacobian sum), etc. Element properties such as shell thickness, beam cross section, etc. are not included in the shape parameter calculation. The ElemChk module uses only element topology, connectivity and node coordinate location which are provided by the GridFun attribute object. Not all element shape parameters are computed for all element types, for example element aspect ratio is not meaningful for line elements. The calculation of the shape data is relatively costly so the exact set of parameters to be computed is specified using vis_ElemChkSetType(). The definition of shape distortion parameters appears below.

Another important element check involves the proper alignment of the normals of surface elements such as shell elements. The function vis_ElemChkNorm() computes the normal to a surface element at the centroid and checks the consistency of the element connectivity with that of all adjacent surface elements. This operation accesses element adjacency functions in the GridFun attribute object. This requires that if the GridFun is supported by an underlying Connect object, that the connection kernel, generated by calling vis_ConnectKernel(), be present.

The maximum rate of change and absolute value of change of a scalar field at an element for all adjacent elements may be computed using vis_ElemChkRate(). This function is useful for, among other things, computing the growth rate of element size. This may be performed by computing the element volume for each element using vis_ElemChkData() and entering the scalar data into a State object. The vis_ElemChkRate() may then be used to compute the growth rate of element size for each element. This operation accesses element adjacency functions in the GridFun attribute object. This requires that if the GridFun is supported by an underlying Connect object, that the connection kernel, generated by calling vis_ConnectKernel(), be present.

Use the function vis_ElemChkAdapt() to perform analysis error estimation and compute new element sizes based on h-mesh refinement. This function requires the strain energy and strain energy error for each element. The function vis_ElemChkEnergy() may be used to compute the element strain energy and strain energy error from element node stress and strain. Use vis_ElemChkSetParamd() to set the target error tolerance.

Use the function vis_ElemChkFaceWeight() to compute face based node area weights. These values are useful for distributing load consistently to node attachments from distributing coupling constraints.

9.4. Shape Parameters

A variety of shape parameters can be computed using vis_ElemChkData(). Use vis_ElemChkDatadv() to compute shape parameters in double precision. The exact type of shape parameters to be computed by vis_ElemChkData() are flagged using vis_ElemChkSetType() The possible shape parameters are computed as follows. Assume that j is the Jacobian matrix and dj is the determinant of the Jacobian matrix in an element.

  • ELEMCHK_JACOBIAN_SUM is the total volume of an element. For surface and line elements total area and length are computed respectively. It is the sum of dj times weights for each integration point.

  • ELEMCHK_JACOBIAN_RATIO keeps track of the minimum and maximum dj within an element. Absolute values are not taken. The ratio is the maximum dj over the minimum dj.

  • ELEMCHK_JACOBIAN_SMALL computes the minimum dj within an element at standard internal integration points.

  • ELEMCHK_JACOBIAN_NODAL computes the minimum dj in an element at the element corner nodes.

  • ELEMCHK_MIDSIDE_OFF computes the maximum ratio of the distance of a midside node from the center of the edge to the length of the edge for all edges in an element with midside nodes.

  • ELEMCHK_ASPECT_RATIO computes maximum aspect ratio of an element. It is computed as follows. Find the lengths of each column of j. At each point in the element find the maximum and minimum lengths and form the ratio = maximum/minimum. Keep track of the maximum ratio occurring in the element.

  • ELEMCHK_FACE_TAPER computes the taper of each face of 2D and 3D elements. The taper of a triagular face is unity. The taper of a quadrilateral face is the maximum ratio of the triangle formed at each corner node of the face to one half the area of the quadrilateral. The maximum computed taper within an element is returned.

  • ELEMCHK_SKEW computes the angles between the columns of j. For rectilinear elements return the deviation from 90 degrees. For triangular and tetrahedral coordinates return the deviation from 60 degrees.

  • ELEMCHK_TWIST computes the eigenvalues of the gradients of j. Complex eigenvalues indicate twist.

  • ELEMCHK_SUBTENDED_ANGLE computes the maximum angle spanned by all columns of j separately for all integration points. The subtended angle is the maximum of the three angles.

  • ELEMCHK_CIRCUM_RATIO computes the ratio of the circumradius/smallest chordal edge length for triangles, tetrahedra and the two faces of wedges.

  • ELEMCHK_MIN_ANGLE computes the angle between edges at all corner nodes of all faces of 2D and 3D elements. The minimum computed angle in degrees within an element is returned.

  • ELEMCHK_MAX_ANGLE computes the angle between edges at all corner nodes of all faces of 2D and 3D elements. The maximum computed angle in degrees within an element is returned.

  • ELEMCHK_MIN_DIHEDANGLE computes the angle between faces of all 3D elements. The minimum computed dihedral angle in degrees within an element is returned.

  • ELEMCHK_MAX_DIHEDANGLE computes the angle between faces of all 3D elements. The maximum computed dihedral angle in degrees within an element is returned.

  • ELEMCHK_MIN_EDGELENGTH computes the minimum element edge length for 1D, 2D and 3D elements. The edge length is the straight line distance between edge endpoints.

  • ELEMCHK_MAX_EDGELENGTH computes the maximum element edge length for 1D, 2D and 3D elements. The edge length is the straight line distance between edge endpoints.

  • ELEMCHK_CG_X,ELEMCHK_CG_Y,ELEMCHK_CG_Z computes the x,y,z coordinates of the center of gravity. If any of the three coordinates are requested then all coordinates are computed.

  • ELEMCHK_EDGEALT_RATIO computes the ratio of the maximum edge length/smallest altitude for triangles and tetrahedra.

  • ELEMCHK_DIMENSION returns the spatial dimension of the element. A value of 3. is returned for tetrahedral, pyramid, pentahedral and hexahedral element shapes. A value of 2. is returned for triangular and quadrilateral elements shapes. A value of 1. is returned for line elements and a value of 0. for point elements.

  • ELEMCHK_PORDER returns the maximum polynomial order of the element. For example, a value of 1. is returned for linear elements, a value of 2. for parabolic elements, etc.

  • ELEMCHK_H computes the effective size of an element. The effective size is the edge length of an equilateral element of an equivalent volume.

  • ELEMCHK_FACE_WARP computes the angle in degrees of the warp of each face of 2D and 3D elements. The warp is the maximum angle subtended by the normals at any two corners of an element face. The maximum computed warp within an element is returned.

  • ELEMCHK_CORN_WARP computes the angle in degrees of the warp of each quadrilateral face of 2D and 3D elements. The warp is the maximum angle subtended by the normals of the two sets of triangles formed by the quadrilateral corner node locations of each face.

  • ELEMCHK_CORN_SKEW computes the angle in degrees of the skew of triangular and quadrilateral faces using the corner point geometry. For quadrilaterals the skew is the deviation from 90 degrees of the angles formed between straight lines connecting the midpoints of opposite edges. For triangles the skew is the deviation from 90 degress of the angles formed between a straight line connecting each corner of the triangle with a straight line connecting the midpoints of the two adjacent edges.

  • ELEMCHK_HANDEDNESS computes the dot product of the normal to each face of the element and a unit vector directed from the centroid of the element to the centroid of the face. For 2D solid elements, the element edges are used. The minimum dot product is returned.

9.5. Attribute Objects

A ElemChk object uses a GridFun object to access finite element data from the host application.

The ElemChk object calls the following grid functions set in the GridFun attribute object.

Coords
ElemNode
ElemNum
Number
Topology

9.6. Function Descriptions

The currently available ElemChk functions are described in detail in this section.

vis_ElemChk *vis_ElemChkBegin(void)

create an instance of an ElemChk object

Create an instance of an ElemChk object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of an ElemChk object using

void vis_ElemChkEnd (vis_ElemChk *elemchk)

Return the current value of an ElemChk object error flag using

Vint vis_ElemChkError (vis_ElemChk *elemchk)

Returns:

The function returns a pointer to the newly created ElemChk object. If the object creation fails, NULL is returned.

void vis_ElemChkEnd(vis_ElemChk *p)

destroy an instance of an ElemChk object

See vis_ElemChkBegin()

Vint vis_ElemChkError(vis_ElemChk *p)

return the current value of an ElemChk object error flag

See vis_ElemChkBegin()

void vis_ElemChkSetObject(vis_ElemChk *p, Vint objecttype, Vobject *object)

set pointers to attribute objects.

Set a pointer to an attribute object. A GridFun attribute object is required so that all finite element topology, connectivity, node coordinate and node and element adjacency queries will be made through the GridFun interface.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:
  • p – Pointer to ElemChk object.

  • objecttype – The name of the object type to be set.

    x=VIS_GRIDFUN            GridFun object
    

  • object – Pointer to the object to be set.

void vis_ElemChkSetType(vis_ElemChk *p, Vint type, Vint flag)

set shape parameter type to compute

Flag the types of shape parameters to be computed using `vis_ElemChkData()´.

Errors

VIS_ERROR_ENUM is generated if an improper type is specified.

Parameters:
  • p – Pointer to ElemChk object.

  • type – Parameter type to flag.

    x=ELEMCHK_ALL             All shape parameters
     =ELEMCHK_JACOBIAN_SUM    Jacobian sum
     =ELEMCHK_JACOBIAN_RATIO  Jacobian ratio
     =ELEMCHK_JACOBIAN_SMALL  Smallest integration point Jacobian
     =ELEMCHK_JACOBIAN_NODAL  Smallest corner node Jacobian
     =ELEMCHK_MIDSIDE_OFF     maximum ratio of midside offset
     =ELEMCHK_ASPECT_RATIO    Aspect ratio
     =ELEMCHK_FACE_TAPER      Face taper
     =ELEMCHK_SKEW            Skew
     =ELEMCHK_TWIST           Twist
     =ELEMCHK_SUBTENDED_ANGLE Subtended angle
     =ELEMCHK_CIRCUM_RATIO    Circumradius ratio
     =ELEMCHK_MIN_ANGLE       Minimum angle between face edges
     =ELEMCHK_MAX_ANGLE       Maximum angle between face edges
     =ELEMCHK_MIN_DIHEDANGLE  Minimum dihedral angle between faces
     =ELEMCHK_MAX_DIHEDANGLE  Maximum dihedral angle between faces
     =ELEMCHK_MIN_EDGELENGTH  Minimum element edge length
     =ELEMCHK_MAX_EDGELENGTH  Maximum element edge length
     =ELEMCHK_FACE_WARP       Face warping
     =ELEMCHK_CG_X            X coordinate of center of gravity
     =ELEMCHK_CG_Y            Y coordinate of center of gravity
     =ELEMCHK_CG_Z            Z coordinate of center of gravity
     =ELEMCHK_EDGEALT_RATIO   Max edge, min altitude ratio
     =ELEMCHK_DIMENSION       Spatial dimension
     =ELEMCHK_PORDER          Polynomial order
     =ELEMCHK_H               Effective edge length
     =ELEMCHK_HANDEDNESS      Element edge/face handedness
    

  • flag – Enable or disable shape parameter

    x=SYS_OFF                 Disable
     =SYS_ON                  Enable
    

void vis_ElemChkSetParami(vis_ElemChk *p, Vint ptype, Vint iparam)

set parameters for element checking

Set the resolution used to compute certain shape parameters using vis_ElemChkData(). If a cheap resolution is enabled then a “reduced” integration is performed to compute certain shape parameters. This will reduce the computational effort. By default ELEMCHK_CHEAP is set to SYS_OFF.

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:
  • p – Pointer to ElemChk object.

  • ptype – Parameter type to set.

    x=ELEMCHK_CHEAP           Performs cheap shape computations
    

  • iparam – Specifies the integer value that ptype will be set to.

    x=SYS_OFF                 Disable
     =SYS_ON                  Enable
    

void vis_ElemChkSetParamd(vis_ElemChk *p, Vint ptype, Vdouble dparam)

set parameters for element checking

Set the tolerance used to compute predicted element sizes using vis_ElemChkAdapt(). By default ELEMCHK_ADAPTTOL is set to .1.

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:
  • p – Pointer to ElemChk object.

  • ptype – Parameter type to set.

    x=ELEMCHK_ADAPTTOL        Error tolerance for adaptivity
    

  • dparam – Specifies the value that ptype will be set to.

void vis_ElemChkDatadv(vis_ElemChk *p, Vint index, Vdouble s[])

compute shape data

See vis_ElemChkData()

void vis_ElemChkData(vis_ElemChk *p, Vint index, Vfloat s[])

compute shape data

Compute a set of shape parameters, s, for element index. The set of shape parameters to compute is specified using vis_ElemChkSetType(). The position in s[] of a given shape parameter is the shape parameter type constant, ie. find the Jacobian sum in s[`ELEMCHK_JACOBIAN_SUM`]. The constant ELEMCHK_MAX is the maximum size of s[].

Errors

  • VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

  • VIS_ERROR_VALUE is generated if an improper index is specified.

Parameters:
  • p – Pointer to ElemChk object.

  • index – Element number

  • s[out] Array of computed shape parameters

void vis_ElemChkRatedv(vis_ElemChk *p, vis_State *state, vis_Group *group, Vint index, Vdouble s[])

compute rate of change

See vis_ElemChkRate()

void vis_ElemChkRate(vis_ElemChk *p, vis_State *state, vis_Group *group, Vint index, Vfloat s[])

compute rate of change

Compute the maximum rate of change and absolute value of change of a scalar field for element index for all adjacent elements in a group. The element scalar field in contained in the input state object. The maximum rate of change is returned in s[0], and the maximum absolute value of change if returned in s[1].

Errors

  • VIS_ERROR_VALUE is generated if state is not an element scalar state.

  • VIS_ERROR_VALUE is generated if group is not an element group.

  • VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

  • VIS_ERROR_VALUE is generated if an improper index is specified.

Parameters:
  • p – Pointer to ElemChk object.

  • state – Pointer to a State object of element scalars.

  • group – Element group including index. If NULL, then all elements are assumed.

  • index – Element number

  • s[out] Computed maximum rate of change and absolute value of change.

void vis_ElemChkNormdv(vis_ElemChk *p, vis_Group *group, Vint index, Vdouble vn[3], Vint *edgeflags)

compute normal and consistency

See vis_ElemChkNorm()

void vis_ElemChkNorm(vis_ElemChk *p, vis_Group *group, Vint index, Vfloat vn[3], Vint *edgeflags)

compute normal and consistency

Compute the normal, vn, to element, index, if it is a surface element. Check each edge of the element for proper connectivity sense with the adjacent element. The adjacent element is checked only if it is a surface element in the input group. Any inconsistent edges are bit flagged in edgeflags. If all edges are consistent edgeflags is returned as zero.

Errors

  • VIS_ERROR_VALUE is generated if group is not an element group.

  • VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

  • VIS_ERROR_VALUE is generated if an improper index is specified.

Parameters:
  • p – Pointer to ElemChk object.

  • group – Element group of adjacent elements, including index. If NULL, then all elements are assumed.

  • index – Element number

  • vn[out] Element surface normal

  • edgeflags[out] Flag edge if adjacent element connectivity sense is improper.

void vis_ElemChkAdapt(vis_ElemChk *p, vis_State *setot, vis_State *seerr, vis_Group *group, vis_State *esize)

compute error estimates and mesh sizes

Compute error estimates and generate new element mesh sizes given the strain energy and the strain energy error in each element. The error estimation method uses a global strain energy error approach. The generated element sizes are placed in element state esize. This output state of element sizes is suitable for mesh refinement as, for example, direct input to vis_SurfMeshRefine() or vis_TetMeshRefine(). The target error tolerance to be used to generate new element sizes is specified as the ELEMCHK_ADAPTTOL parameter in vis_ElemChkSetParamd().

Errors

  • VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

  • VIS_ERROR_COMPUTE is generated if the total strain energy is zero.

Parameters:
  • p – Pointer to ElemChk object.

  • setot – Element State of strain energy

  • seerr – Element State of strain energy error

  • group – Pointer to Group of elements or element faces. If NULL, then all elements are assumed.

  • esize[out] Element State of computed element sizes

void vis_ElemChkEnergy(vis_ElemChk *p, vis_State *stress, vis_State *strain, vis_Group *group, vis_State *setot, vis_State *seerr)

compute strain energies

Compute strain energy and strain energy error in each element given the element node stress and strain. The element node stress and strain should be computed local to the element. The computed strain energy and strain energy error states are suitable for input to vis_ElemChkAdapt().

Errors

VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

Parameters:
  • p – Pointer to ElemChk object.

  • stress – Element node State of stress

  • strain – Element node State of strain

  • group – Pointer to Group of elements or element faces. If NULL, then all elements are assumed.

  • setot[out] Element State of strain energy

  • seerr[out] Element State of strain energy error

void vis_ElemChkFaceWeight(vis_ElemChk *p, vis_Group *group, vis_State *nweight)

compute face based node weights

Compute face based node area weights.

Errors

  • VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

  • VIS_ERROR_NULLOBJECT is generated if the Group or State object is NULL.

Parameters:
  • p – Pointer to ElemChk object.

  • group – Pointer to Group of element faces.

  • nweight[out] Node State of computed node weights

void vis_ElemChkCompliesWithShapeParameters(vis_ElemChk *p, Vint index, Vdouble targetShapeParameters[ELEMCHK_MAX], Vdouble relativeTolerance, Vint *areShapeParametersCompliant, Vint *nonCompliantShapeParameter)

checks if the current element index complies to the target shapeParameters

Compare shape parameters to check if the input element complies with the enabled target shape parameter values.

when a shape parameter refer to a minimum value, if the input element index contains a shape parameter lower then the target shape parameters, SYS_OFF is returned. When a MAX shape parameter is compared, if the element shape parameter value is higher than the MAX target SYS_OFF is returned.

The relative tolerance is used for comparing shape parameter values evaluated with approximate equality The final absolute tolerance is compute by doing relativeTolerance*targetShapeParameter[ELEMNCHK_TYPE] The set of shape parameters to compute is specified using vis_ElemChkSetType()

As soon as one shape parameter is not compliant this method returns. The first non-compliant shape parameter is returned.

Parameters:
  • p – Pointer to ElemChk object.

  • index – Element number

  • targetShapeParameters – target shapeParameters values.

    =ELEMCHK_JACOBIAN_SUM          Jacobian sum
    =ELEMCHK_JACOBIAN_RATIO        Jacobian ratio
    =ELEMCHK_JACOBIAN_SMALL        Smallest integration point Jacobian
    =ELEMCHK_JACOBIAN_NODAL        Smallest corner node Jacobian
    =ELEMCHK_MIDSIDE_OFF           maximum ratio of midside offset
    =ELEMCHK_ASPECT_RATIO          Aspect ratio
    =ELEMCHK_FACE_TAPER            Face taper
    =ELEMCHK_SKEW                  Skew
    =ELEMCHK_TWIST                 Twist
    =ELEMCHK_SUBTENDED_ANGLE       Subtended angle
    =ELEMCHK_CIRCUM_RATIO          Circumradius ratio
    =ELEMCHK_MIN_ANGLE             Minimum angle between face edges
    =ELEMCHK_MAX_ANGLE             Maximum angle between face edges
    =ELEMCHK_MIN_DIHEDANGLE        Minimum dihedral angle between faces
    =ELEMCHK_MAX_DIHEDANGLE        Maximum dihedral angle between faces
    =ELEMCHK_MIN_EDGELENGTH        Minimum element edge length
    =ELEMCHK_MAX_EDGELENGTH        Maximum element edge length
    =ELEMCHK_FACE_WARP             Face warping
    =ELEMCHK_CG_X                  X coordinate of center of gravity
    =ELEMCHK_CG_Y                  Y coordinate of center of gravity
    =ELEMCHK_CG_Z                  Z coordinate of center of gravity
    =ELEMCHK_EDGEALT_RATIO         Max edge, min altitude ratio
    =ELEMCHK_DIMENSION             Spatial dimension
    =ELEMCHK_PORDER                Polynomial order
    =ELEMCHK_H                     Effective edge length
    =ELEMCHK_HANDEDNESS            Element edge/face handedness
    

  • relativeTolerance – relative tolerance whne comparing absolute shape parameters

  • areShapeParametersCompliant[out] flag telling if the metric conforms (SYS_ON) or not (SYS_OFF)

  • nonCompliantShapeParameter[out] Store the ELEMCHK parameter failing to comply

void vis_ElemChkFindNonCompliedShapeParameters(vis_ElemChk *p, Vint index, Vdouble targetShapeParameters[ELEMCHK_MAX], Vdouble relativeTolerance, vsy_BitVec *shapeParameterCompliantFlags)

compute, compare and return the results flag for every shape parameter

Compare shape parameters to check if the input element complies with the enabled target shape parameter values.

when a shape parameter refers to a minimum value, if the input element index contains a shape parameter lower then the target shape parameter, SYS_OFF is returned. When a MAX shape parameter is compared, if the element shape parameter value is higher than the MAX target SYS_OFF is returned.

The relative tolerance is used for comparing shape parameter values evaluated with approximate equality The final absolute tolerance is compute by doing relativeTolerance*targetShapeParameter[ELEMNCHK_TYPE] The set of shape parameters to compute is specified using vis_ElemChkSetType()

The output contains the flag summary of all comparison.

Parameters:
  • p – Pointer to ElemChk object.

  • index – Element number

  • targetShapeParameters – target shapeParameters values.

    =ELEMCHK_JACOBIAN_SUM          Jacobian sum
    =ELEMCHK_JACOBIAN_RATIO        Jacobian ratio
    =ELEMCHK_JACOBIAN_SMALL        Smallest integration point Jacobian
    =ELEMCHK_JACOBIAN_NODAL        Smallest corner node Jacobian
    =ELEMCHK_MIDSIDE_OFF           maximum ratio of midside offset
    =ELEMCHK_ASPECT_RATIO          Aspect ratio
    =ELEMCHK_FACE_TAPER            Face taper
    =ELEMCHK_SKEW                  Skew
    =ELEMCHK_TWIST                 Twist
    =ELEMCHK_SUBTENDED_ANGLE       Subtended angle
    =ELEMCHK_CIRCUM_RATIO          Circumradius ratio
    =ELEMCHK_MIN_ANGLE             Minimum angle between face edges
    =ELEMCHK_MAX_ANGLE             Maximum angle between face edges
    =ELEMCHK_MIN_DIHEDANGLE        Minimum dihedral angle between faces
    =ELEMCHK_MAX_DIHEDANGLE        Maximum dihedral angle between faces
    =ELEMCHK_MIN_EDGELENGTH        Minimum element edge length
    =ELEMCHK_MAX_EDGELENGTH        Maximum element edge length
    =ELEMCHK_FACE_WARP             Face warping
    =ELEMCHK_CG_X                  X coordinate of center of gravity
    =ELEMCHK_CG_Y                  Y coordinate of center of gravity
    =ELEMCHK_CG_Z                  Z coordinate of center of gravity
    =ELEMCHK_EDGEALT_RATIO         Max edge, min altitude ratio
    =ELEMCHK_DIMENSION             Spatial dimension
    =ELEMCHK_PORDER                Polynomial order
    =ELEMCHK_H                     Effective edge length
    =ELEMCHK_HANDEDNESS            Element edge/face handedness
    

  • relativeTolerance – relative tolerance whne comparing absolute shape parameters

  • shapeParameterCompliantFlags[out] BitVec telling if the metric conforms (SYS_ON) or not (SYS_OFF)

9.7. Mass Properties - MassPrp

The MassPrp module computes the gross mass properties of a finite element model. Computed quantities consist of total mass, center of mass and the mass moment of inertia tensor.

The functions associated with a MassPrp object are the following.

Instance a MassPrp object initially using vis_MassPrpBegin(). At this point a Model object must be set as an attribute object using vis_MassPrpSetObject() so that the MassPrp object can access finite element model information. The total volume, total mass, center of mass and mass moment of inertia tensor about the center of mass are computed using vis_MassPrpCompute(). Note that surface elements, such as shell elements, use the element thickness property to compute the volume. Line elements, such as beam elements, use th element area to compute volume. Use vis_MassPrpPrincipal() to compute the principal values and directions of a moment of inertia tensor.

9.8. Attribute Objects

A MassPrp object uses a Model object to access finite element data from the host application. The Model object requires the Connect object and element and material property hashtables to be registered.

9.9. Function Descriptions

The currently available MassPrp functions are described in detail in this section.

vis_MassPrp *vis_MassPrpBegin(void)

create an instance of a MassPrp object

Create an instance of a MassPrp object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a MassPrp object using

void vis_MassPrpEnd (vis_MassPrp *massprp)

Return the current value of a MassPrp object error flag using

Vint vis_MassPrpError (vis_MassPrp *massprp)

Returns:

The function returns a pointer to the newly created MassPrp object. If the object creation fails, NULL is returned.

void vis_MassPrpEnd(vis_MassPrp *p)

destroy an instance of a MassPrp object

See vis_MassPrpBegin()

Vint vis_MassPrpError(vis_MassPrp *p)

return the current value of a MassPrp object error flag

See vis_MassPrpBegin()

void vis_MassPrpCompute(vis_MassPrp *p, vis_Group *group, Vfloat *vtot, Vfloat *mtot, Vfloat xcom[3], Vfloat mten[6])

compute mass properties

Compute the total mass, center of mass and mass moment of inertia of all elements in a group.

Errors

  • VIS_ERROR_NULLOBJECT is generated if a Model object has not been set or any required object does not exist in the Model object.

  • VIS_ERROR_VALUE is generated if group is not an element group.

  • VIS_ERROR_COMPUTE is generated if the total mass is zero.

Parameters:
  • p – Pointer to MassPrp object.

  • group – Element group If NULL, then all elements are assumed.

  • vtot[out] Total volume

  • mtot[out] Total mass

  • xcom[out] Location of center of mass

  • mten[out] Mass moment of inertia tensor about center of mass

void vis_MassPrpPrincipal(vis_MassPrp *p, Vfloat mten[6], Vfloat mpri[3], Vfloat tm[3][3])

compute principal moments of inertia

Compute the principal values, mpri and direction cosine matrix, tm, of principal directions of a mass moment of inertia tensor, mten. The principal values are ordered from smallest to largest.

Errors

VIS_ERROR_COMPUTE is generated if the principal directions can not be computed.

Parameters:
  • p – Pointer to MassPrp object.

  • mten – Mass moment of inertia tensor

  • mpri[out] Principal values

  • tm[out] Principal directions