Table of Contents

19. Data Manipulation - ElemDat,State,History,RedMat,ZState

Three modules (ElemDat, State, and History) are provided for storing and manipulating data associated with the nodes and elements in the finite element model. The data may be either scalar, vector, tensor (symmetric tensor) or general tensor. Both real and complex valued data may be stored. The RedMat module is designed to store matrix based results. It has specific facilities to associate system degrees of freedom with the matrix values. The ZState module is specifically designed for lossy compression of node and element based simulation results.

The State module is designed to hold solution results at nodes, particles, element centroids or element nodes. It has been optimized to hold a complete set of results at an analysis step for each entity in the model such as a complete set of displacement vectors for each node or stress tensors for each element.

By contrast, the ElemDat module is designed to complement the State module by providing a sparse storage mechanism for data based at element faces and edges. It has been optimized to hold quantities such as element distributed traction loads and line loads.

The History module is used to hold solution results for a selected set of nodes or elements over several analysis steps.

By convention, vector data is assumed to be ordered by (x,y,z) components, six dof vector data by (tx,ty,tz,rx,ry,rz) components, symmetric tensor data by (xx,yy,zz,xy,yz,zx) components, and general tensor data by (xx,xy,xz,yx,yy,yz,zx,zy,zz) components. Element result data is generally used for shell, beam and spring element forces, moments, strains and curvatures. Shell element stress results are ordered (Nxx,Nyy,Nxy,Mxx,Myy,Mxy,Qxz,Qyz), beam element stress results are ordered (Nxx,Myy,Mzz,Torque,Qxy,Qzx,TBimom) with a corresponding ordering for the associated strains and curvatures. Spring element stress results are ordered (Fx,Fy,Fz,Mx,My,Mz).

The RedMat module is used to hold matrix results. As an option the matrix entries may be associated with system degrees of freedom. Each degree of freedom is paired with a specific node or element and a degree of freedom type. An example of such a result is a reduced stiffness matrix generated by a superelement creation solution procedure.

Table of Contents

19.1 Element Face and Edge Data - ElemDat

The ElemDat module is designed to provide a sparse storage mechanism for scalar, vector, tensor (symmetric tensor) and general tensor data based at elements, element faces, element edges or element nodes. The data may be located at the element face and edge centroids or face and edge nodes. This feature makes the ElemDat module useful for holding finite element load condition information such as uniform or varying distributed tractions and line loads. In addition, accurate element face normals may be computed and maintained for rendering purposes. The functions associated with a ElemDat object are the following.

Instance a ElemDat object using vis_ElemDatBegin. Once a ElemDat object is instanced, the user may specify the precision used to maintain the element data using vis_ElemDatPre. By default, element data is held in single precision. Define element parent and child entity types and element size using vis_ElemDatDef. The function is also used to specify the data type (scalar, vector, etc.) of the element data to be maintained by the ElemDat object. Use vis_ElemDatSetData to initially enter element data into a ElemDat object and vis_ElemDatClear to clear (unset) all element data. Use vis_ElemDatEnd to release all memory associated with a ElemDat object.

Complex valued element data may be specified. The real and imaginary parts of a complex value may be specified one at a time or together depending upon the state of the complex mode of ElemDat. The user sets the complex mode using vis_ElemDatSetComplexMode. See section VisTools, Complex Numbers for a description of the general usage of complex valued data in Vistools modules.

Use vis_ElemDatData to query for element data at an element. The function vis_ElemDatDataStat may be used to query for the elements, element faces or element edges that have had data set. The function vis_ElemDatNormal computes accurate element face normals for smooth shaded rendering. The function vis_ElemDatIdTran can be used to derive an IdTran indicating the elements, element edges or faces for which data has been set.

Table of Contents

19.2 Attribute Objects

A ElemDat object uses a GridFun object to access finite element data from the host application. This attribute object is required.

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

Coords
ElemAdj
Only in vis_ElemDatNormal
ElemCon
ElemCnn
ElemNode
ElemNum
ElemTopo
MaxNodeElem
Only in vis_ElemDatNormal
Number
Topology

Table of Contents

19.3 Function Descriptions

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


Table of Contents , ElemDat

NAME

*vis_ElemDatBegin - create an instance of an ElemDat object

C SPECIFICATION

vis_ElemDat *vis_ElemDatBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an ElemDat object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL.

Destroy an instance of a ElemDat object using

     void vis_ElemDatEnd (vis_ElemDat *elemdat)

Return the current value of a ElemDat object error flag using

     Vint vis_ElemDatError (vis_ElemDat *elemdat)


Table of Contents , ElemDat

NAME

vis_ElemDatClear - clear any set element data

C SPECIFICATION

void vis_ElemDatClear (vis_ElemDat *elemdat)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Clear any defined element data. This function "unsets" all element face or edge data which has been set using vis_ElemDatSetData. All memory used to store the data is freed.


Table of Contents , ElemDat

NAME

vis_ElemDatPre - specify precision of element data

C SPECIFICATION

void vis_ElemDatPre (vis_ElemDat *elemdat,
                     Vint pre)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
pre          Precision of data
             =SYS_FLOAT              Single precision
             =SYS_DOUBLE             Double precision

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper pre is specified.

DESCRIPTION

Specify the precision used to maintain element data The function should be called before vis_ElemDatDef. By default, element data are held in single precision.


Table of Contents , ElemDat

NAME

vis_ElemDatData - get element data for an element

C SPECIFICATION

void vis_ElemDatData (const vis_ElemDat *elemdat,
                      Vint index,
                      Vint no,
                      Vfloat s[])

void vis_ElemDatDatadv (const vis_ElemDat *elemdat,
                        Vint index,
                        Vint no,
                        Vdouble s[])

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
index        Element index
no           Element face or edge number

OUTPUT ARGUMENTS

s            Array of returned element data

DESCRIPTION

Get element data, s, for element index at face or edge no. If the parent type is element then no is ignored. If no data has been set zeroes are returned in s. Use vis_ElemDatSetData to set element data. Use vis_ElemDatSetDatadv to set element data in double precision.


Table of Contents , ElemDat

NAME

vis_ElemDatDef - define parent and child entities and data type

C SPECIFICATION

void vis_ElemDatDef (vis_ElemDat *elemdat,
                     Vint nument,
                     Vint parenttype,
                     Vint childtype,
                     Vint datatype)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
nument       Number of elements
parenttype   Type of element parent entity
             =SYS_ELEM     Element
             =SYS_FACE     Element face
             =SYS_EDGE     Element edge
childtype    Type of element child entity.
             =SYS_NONE     No child entity
             =SYS_NODE     Node type
datatype     Data type
             =VIS_SCALAR             Scalar data
             =VIS_VECTOR             Vector data
             =VIS_SIXDOF             Six dof vector data
             =VIS_TENSOR             Symmetric tensor data
             =VIS_GENERALTENSOR      General Tensor data
             =VIS_ELEMRES            Element Result data
             =VIS_SCALARSn           n scalars data

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if nument is non positive. VIS_ERROR_ENUM is generated if an improper parenttype, childtype or datatype is specified.

DESCRIPTION

Specify the number of elements and type of element parent and child entities and data type. If purely element, element face or element edge centroid data are to be managed, then childtype should be set to SYS_NONE.

Inquire of defined nument, parenttype, childtype and datatype as output arguments using

     void vis_ElemDatInq (const vis_ElemDat *elemdat,
                          Vint *nument,
                          Vint *parenttype,
                          Vint *childtype,
                          Vint *datatype)


Table of Contents , ElemDat

NAME

vis_ElemDatDataStat - query data status

C SPECIFICATION

void vis_ElemDatDataStat (const vis_ElemDat *elemdat,
                          Vint index,
                          Vint no,
                          Vint *stat)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
index        Element index
no           Element face or edge number

OUTPUT ARGUMENTS

stat         returned results data status

DESCRIPTION

Get data status for element index at face or edge no indicating which element entities have had data set. The data status will be 1 if the data for a given entity has been defined. If the parent type is element then no is ignored.


Table of Contents , ElemDat

NAME

vis_ElemDatSetData - set element face or edge data

C SPECIFICATION

void vis_ElemDatSetData (vis_ElemDat *elemdat,
                         Vint index,
                         Vint no,
                         Vfloat s[])

void vis_ElemDatSetDatadv (vis_ElemDat *elemdat,
                           Vint index,
                           Vint no,
                           Vdouble s[])

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
index        Element index
no           Element face or edge number
s            Array of element data to be set

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper index is specified. VIS_ERROR_NULLOBJECT is generated if a GridFun attribute object has not been set. VIS_ERROR_OPERATION is generated if the the GridFun attribute object returns a total number of elements which does not match the number of elements declared in vis_ElemDatDef.

DESCRIPTION

Set element data, s, for a specified index and face or edge number no. If the parent type is element then no is ignored. Use vis_ElemDatData to retrieve data. Use vis_ElemDatDatadv to retrieve data in double precision. If the elemdat object manages node or element centroid data, the array s contains 1, 3, 6 or 9 values corresponding to scalar, vector, tensor or general tensor data types. If element, element face or element edge node data is managed, s contains 1, 3, 6 or 9 values for each element, element face or element edge node.


Table of Contents , ElemDat

NAME

vis_ElemDatSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_ElemDatSetObject (vis_ElemDat *elemdat,
                           Vint objecttype,
                           Vobject *object)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
objecttype   The name of the object type to be set.
             =VIS_GRIDFUN            GridFun object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. All finite element topology, connectivity, node coordinate and node and element association queries are made through the GridFun attribute object.

Get object as an output argument using

     void vis_ElemDatGetObject (vis_ElemDat *elemdat,
                                Vint objecttype,
                                Vobject **object)


Table of Contents , ElemDat

NAME

vis_ElemDatSetParamf - set floating point parameters

C SPECIFICATION

void vis_ElemDatSetParamf (vis_ElemDat *elemdat,
                           Vint ptype,
                           Vfloat param)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
ptype        Type of parameter to set
             =ELEMDAT_FEATUREANGLE   Feature angle in degrees
param        Specifies the floating value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Set floating point parameters. The parameter ELEMDAT_FEATUREANGLE sets the feature angle used by the function vis_ElemDatNormal. By default ELEMDAT_FEATUREANGLE is set to 30. degrees.


Table of Contents , ElemDat

NAME

vis_ElemDatSetParami - set integer parameters

C SPECIFICATION

void vis_ElemDatSetParami (vis_ElemDat *elemdat,
                           Vint ptype,
                           Vint iparam)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
ptype        Type of parameter to set
             =ELEMDAT_FEATUREBRANCH  Feature branch flag
             =ELEMDAT_LINNORMAL      Linearize normals from corner nodes
iparam       Specifies the integer value that ptype will be set to.
             =VIS_OFF                Turn parameter off
             =VIS_ON                 Turn parameter on

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Set integer parameters.

The parameter ELEMDAT_FEATUREBRANCH toggles the treatment of edges connecting more than 2 element faces for the determination of element face normals using the function vis_ElemDatNormal. By default ELEMDAT_FEATUREBRANCH is set to VIS_OFF.

The parameter ELEMDAT_LINNORMAL toggles the method used for computation of element face normals at midside nodes using the function vis_ElemDatNormal. If this flag is disabled, midside node normals are normal to the element face at the location of the midside node. If this flag is enabled, midside node normals are computed using the corner node normals, the midside normals are linearly interpolated from the corner node normals. By default ELEMDAT_LINNORMAL is set to VIS_OFF.


Table of Contents , ElemDat

NAME

vis_ElemDatSetComplexMode - set specify/query mode for complex data

C SPECIFICATION

void vis_ElemDatSetComplexMode (vis_ElemDat *elemdat,
                                Vint complexmode)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
complexmode  Complex mode
             =SYS_COMPLEX_REAL           Real
             =SYS_COMPLEX_IMAGINARY      Imaginary
             =SYS_COMPLEX_REALIMAGINARY  Real and imaginary

OUTPUT ARGUMENTS

None

DESCRIPTION

Set complex mode. By default the complex mode is SYS_COMPLEX_REAL.

Get complexmode as an output argument.

     void vis_ElemDatGetComplexMode (const vis_ElemDat *elemdat,
                                     Vint *complexmode)


Table of Contents , ElemDat

NAME

vis_ElemDatGetComplex - query for complex data existence

C SPECIFICATION

void vis_ElemDatGetComplex (vis_ElemDat *elemdat,
                            Vint *complexflag)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.

OUTPUT ARGUMENTS

complexflag  Complex data existence flag

DESCRIPTION

Query for complex data. The complexflag will be returned as one if the complex mode set by vis_ElemDatSetComplexMode is ever SYS_COMPLEX_IMAGINARY or SYS_COMPLEX_REALIMAGINARY, otherwise it is returned as zero.


Table of Contents , ElemDat

NAME

vis_ElemDatIdTran - derive list of element entities

C SPECIFICATION

void vis_ElemDatIdTran (vis_ElemDat *elemdat,
                        Vint oper,
                        vis_IdTran *idtran)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
oper         Operation specified to derive group
             =ELEMDAT_SETDATA        Edges at which data has been set

OUTPUT ARGUMENTS

idtran       Pointer to derived IdTran object of element entities.

ERRORS

VIS_ERROR_ENUM is generated if an improper operation oper is specified. VIS_ERROR_NULLOBJECT is generated if the GridFun has not been set.

DESCRIPTION

Derive an IdTran of element entities. The output idtran will be overwritten by this function. The entity type of the output IdTran will be set to SYS_ELEM. For SYS_ELEM parent types the IdTran entity type and subtype will match the ElemDat parent type and child type. For SYS_FACE and SYS_EDGE parent types, the IdTran entity type will be SYS_ELEM and the subtype will be the parent type.


Table of Contents , ElemDat

NAME

vis_ElemDatNormal - compute accurate element face normals

C SPECIFICATION

void vis_ElemDatNormal (vis_ElemDat *elemdat,
                        vis_Group *group)

INPUT ARGUMENTS

elemdat      Pointer to ElemDat object.
group        Pointer to Group object of element faces
             If NULL, then all element faces are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if group is not an element face group. VIS_ERROR_NULLOBJECT is generated if the GridFun has not been set. VIS_ERROR_OPERATION is generated if the ElemDat object is not defined for element face vectors.

DESCRIPTION

Compute accurate element face normals for a set of element faces. Element face normals are determined by averaging normals at nodes contributed by connected element faces across element face edges. Normals are not averaged across an edge if the angles between element face normals of adjacent element faces exceed a specified feature angle. The feature angle is set using vis_ElemDatSetParamf. Optionally the averaging of normals across any edge with more than 2 adjacent faces may be inhibited by setting the ELEMDAT_FEATUREBRANCH parameter using vis_ElemDatSetParami.


Table of Contents

19.4 Results Manipulation - State

The State module supports the management of solution results data for scalar, vector, six dof vector (translations and rotations), tensor (symmetric tensor) and general tensor fields defined over a solution domain. The results data may be located at nodes, elements, element nodes, element faces, element edges, element face nodes and element edge nodes. The additional, non element or node related locations, are particule and mode. For element and element node results, data may also be present for several "sections" at each element location. Sections most often represent stress results for several layers in a composite shell element or points throughout a beam cross section. The State module contains functions for mapping results quantities between node, element and element node locations. For example solution results based at element centroids may be mapped to a state in which the results quantities are represented at the nodes. In addition, the State module provides a set of derived quantities for vector and tensor fields which may be automatically calculated. such as vector magnitude for tensor principal values. These derived quantities, such as vector magnitude for tensor principal values, are generally based on the invariants of the vector or tensor. The functions associated with a State object are the following.

Instance a State object using vis_StateBegin. Once a State is instanced, the user may specify the precision used to maintain the state data using vis_StatePre. By default, state data are held in single precision.

Define parent and child entity types and parent size using vis_StateDef. The function is also used to specify the data type (scalar, vector, etc.) of the solution results data to be maintained by the state object. Use vis_StateSetData to enter solution results into a State object at specified entity indices. If results data is not specified at a specific entity index it is assumed to be zero. Use vis_StateClear to clear (set to zero) all results data. Use vis_StateEnd to release all memory associated with a State object.

Complex valued element data may be specified. The real and imaginary parts of a complex value may be specified one at a time or together depending upon the value of the complex mode of State. The user sets the complex mode using vis_StateSetComplexMode. See section VisTools, Complex Numbers for a description of the general usage of complex valued data in Vistools modules.

Complex data in State may be held as real and imaginary components or magnitude phase components. By default, complex data is assumed to be in real and imaginary form. If complex data has been entered in magnitude and phase form, use the function vis_StateSetMagnitudePhase to flag this fact. The function vis_StateConvertComplex can be used to convert complex data from real/imaginary to/from magnitude/phase. The function vis_StateSetMagnitudePhase will be called appropriately internally to flag the current form of complex data. Note that the units of the phase angles are degrees.

Results data is maintained at nodes, element centroids or element nodes by a state object. The number of data locations per entity for node and element states is one, for element node states, the number of data locations is the number of nodes in an element. Element and element node states may also carry data for any number of sections at each data location. These sections usually represent layers in a composite shell element or points throughout a beam cross section. If data is to represented at sections, then the number of sections for each element must be defined using vis_StateSetDataSect before data may be set using vis_StateSetData. Use vis_StateDataSect to query the number of sections at an element. By default the number of sections is 1. The layer position type of the sections at an element may be set as an option using vis_StateSetDataLayPos. The layer position type specifies more detail concerning the position of a section within a layer, ie top, middle, bottom, etc. More detailed information about layer number and layer position of each section can be set using the function vis_StateSetDataLayers. The function vis_StateDataLayers can retrieve the layer numbers and positions. If explicit layer numbers and positions are not defined for each section index, then the layer numbers are assumed to start from 1 and increment sequentially with a layer number multiplicity dependent upon the layer position type. If there are several sections of data at an element, use vis_StateSetSection to control whether all sections or only a selected section of data are returned using vis_StateData. By default section 1 is set.

For element face, element face node, element edge and element edge node locations, the element faces or edges for which data will be defined must be specified using function vis_StateSetDataEnt before the actual data is set. Use the function vis_StateSetDataElemEnt to set data at a specific element face or element edge.

By convention, vector data is assumed to be ordered by (x,y,z) components, six dof vector data by (tx,ty,tz,rx,ry,rz) components, symmetric tensor data by (xx,yy,zz,xy,yz,zx) components, and general tensor data by (xx,xy,xz,yx,yy,yz,zx,zy,zz) components, Use vis_StateData to query for results data for some entity subset. A State object will automatically return a derived quantity when vis_StateData is called by setting a derived quantity with vis_StateSetDerive.

The function vis_StateDataElem is a convenient function to use for returning data at an element regardless of the parent and child entity types of the State object. This function is sensitive to the mapping options which are used to map element node data to elements.

The function vis_StateDataElemEnt is a convenient function to use for returning data for all element nodes, element face nodes or element edge nodes regardless of the parent and child entity types of the State object. Use vis_StateDataElemRST to retrieve interpolated values at a given natural coordinates location within an element. The function vis_StateDataStat may be used to determine if the data for a given set of entities as been specified using vis_StateSetData. The function vis_StateDataStatElemEnt may be used for element face and element edge states to determine data define at a specific element face or element edge.

Vectoral derived quantities include only the vector magnitude.

Tensoral derived quantities include the following. The quantities tmax,tmid and tmin are the maximum, middle and minimum principal values.

If Von Mises strain is requested, it will be computed as 2./3. the value of Von Mises stress. This is a special case (Nu=.5) of a more general formula in which Von Mises strain is 1./(1.+Nu) of the Von Mises stress where Nu is an effective Poisson's ratio.

If tensor principal values are requested the values are sorted by numeric value, not absolute value.

Note that in the direction of max shear stress, two of the direct stresses are equal and may be derived using VIS_TENSOR_EQUDIRECT, the other stress is equal to the middle principal value and may be derived using VIS_TENSOR_MIDPRINC. The maximum shear is derived using VIS_TENSOR_MAXSHEAR, the other two shear stresses are zero. The maximum shear angle, VIS_TENSOR_ANGSHEAR, is the angle formed by the direction of maximum shear with the x axis in degrees.

Note that the tensor intensity definition is taken directly from ANSYS documentation. Since (tmax-tmin) is always the maximum, the other terms are unnecessary. It is always equal to twice the maximum shear.

A practical note should be made concerning representing shear strains as a tensoral quantity with the State module. In many commercial finite element programs shear strain is reported as engineering strain rather than tensor strain. The shear strain components of engineering strain are twice the value of the corresponding components of tensor strain. The user may enable the State module to treat the engineering strain variant of a tensor by calling vis_StateSetEngineeringStrain. This is required so that all invariant calculations, transformations, etc. are properly performed. Note that the Max Shear derived value for engineering strain will be returned as twice the tensoral value. The function vis_StateConvertStrain can be used to convert strain data from tensor to/from engineering strain. The function vis_StateSetEngineeringStrain will be called appropriately internally to flag the current form of strain data.

The vis_StateExtent function returns the minimum and maximum results data values over a specified subset of the solution domain. The domain subset is defined by an input Group object.

Results data is maintained at nodes, element centroids or element nodes by a state object. It is often useful to be able to interpolate or extrapolate results data from one location to another. The vis_StateMap function is designed to perform this operation. The mapping of data from elements or element nodes to nodes may be performed using a topologically or geometrically based weighting. A topological weighting assigns an equal weight to each element contribution connected to a node. A geometric weighting assigns a weight proportional to the reciprocal of the volume of the element (area for 2D elements, length for 1D elements and unity for 0D elements).

A specific function, vis_StateMapElemNode, is available for averaging and mapping element centroid or element node data to element nodes in which averaging is performed only within user specified regions. For example, it is common for element stress results to be output at element nodes in which the stresses have been computed using local element methods. This results in general stress discontinuities between all elements. A typical post processing function is to average the element nodal stresses at nodes within regions of homogeneous elements. This will result in removing the element stress discontinuities between elements in the same region but preserving the discontinuity at the boundaries between regions. The resulting data location must be element nodal to represent the region discontinuity.

The function, vis_StateMidside, is available for specialized processing of data at element midside nodes as a function of the element corner nodes. Options include linear interpolation of the data at midside nodes and clamping the data midside nodes. Only edge midside nodes are affected, midface and midbody nodes are not processed.

Table of Contents

19.5 Local Coordinate Systems

The State module may also be used to maintain local coordinate system information for vector, sixdof vector, tensor and general tensor states and perform transformations of the state data between the local system and the global coordinate system. Use vis_StateTransform to transform state data between the local and global systems. The coordinate system state (local or global) of the data is specified by vis_StateSetSystem. The current coordinate system state of the data may be queried using vis_StateGetSystem. There are two basic types of local coordinate systems: 1) local systems in the undeformed coordinates and 2) local systems in deformed coordinates. The function vis_StateDirCos may be used to obtain the direction cosine matrix of the current coordinate system of any node and/or element.

The local undeformed coordinate system information may be maintained by any combination of user defined local coordinate systems represented by a HashTable of CoordSys objects and element local coordinates systems which are computed using a specified algorithm, usually as a function of element geometry. The element geometry consists of the element node coordinates and an optional HashTable of ElemDat objects which contain vectors to orient local coordinate systems.

The way in which local undeformed coordinate system information is maintained at each node or element is specified by a set of integer flags. By default, these coordinate system identifiers are defined by the node or element VIS_CSYSID association. However an option is provided to specify integer flags contained in an IdTran attribute object. Use the function vis_StateSetObject to register the IdTran object. Normally element node states assume that the coordinate system identifiers are associated with elements, however the user can specify that the coordinate system identifiers be associated with the element nodes. Set this option using vis_StateSetSystemType. Use the function vis_StateSetHashTable to register the HashTable of CoordSys objects and the HashTable of ElemDat objects.

The local undeformed coordinate system flags are assigned as follows: See section VisTools, Element Coordinate Systems for a description of element coordinate systems.

=0
Global coordinate system
>0
Identifier of local coordinate system defined by CoordSys object. All CoordSys objects referenced in this way must be installed in a HashTable attribute object.
<0
Identifier of element geometry dependent algorithm. The algorithm may require the geometry information contained in an ElemDat object. All ElemDat objects referenced in this way must be installed in a HashTable attribute object.

The local deformed coordinate system information is maintained as an associated State object containing the rotation angle vectors which define the coordinate systems of each entity. Use the function vis_StateSetObject to register the State object of rotation angle vectors.

Table of Contents

19.6 Parallel Functions

 + vis_StateExtent
 + vis_StateTransform
Table of Contents

19.7 Attribute Objects

A State object uses a GridFun object to access finite element data from the host application. This attribute object is required for any operations which relate elements to nodes or vice versa. For example, storing element node results in a state object or performing any mapping operation requires a GridFun object to be set as an attribute object.

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

Coords
ElemCon
ElemCnn
ElemNode
ElemNum
ElemAssoc
Extent
Only in vis_StateDemo
NodeAssoc
Number
Topology

A IdTran attribute object is required for specifying local coordinate system flags for each entity, node or element, contained in the State object. Depending upon how the coordinate system information is maintained, either a HashTable attribute object of CoordSys objects and/or a State attribute object of direction cosine matrices may be required.

Table of Contents

19.8 Function Descriptions

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


Table of Contents , State

NAME

*vis_StateBegin - create an instance of an State object

C SPECIFICATION

vis_State *vis_StateBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an State object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL.

Destroy an instance of a State object using

     void vis_StateEnd (vis_State *state)

Return the current value of a State object error flag using

     Vint vis_StateError (vis_State *state)

Make a copy of a State object. The private data from the fromstate object is copied to the state object. Any previous private data in state is lost.

     void vis_StateCopy (vis_State *state,
                         vis_State *fromstate)


Table of Contents , State

NAME

vis_StatePre - specify precision of state data

C SPECIFICATION

void vis_StatePre (vis_State *state,
                   Vint pre)

INPUT ARGUMENTS

state        Pointer to State object.
pre          Precision of state data
             =SYS_FLOAT              Single precision
             =SYS_DOUBLE             Double precision

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper pre is specified.

DESCRIPTION

Specify the precision used to maintain state data All previously defined data is cleared by this function. The function should be called before vis_StateDef. By default, state data are held in single precision. See section DevTools, Floating Point Precision for a description of precision types.


Table of Contents , State

NAME

vis_StateClear - clear all results data

C SPECIFICATION

void vis_StateClear (vis_State *state)

INPUT ARGUMENTS

state        Pointer to State object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Clear all results data to zero.


Table of Contents , State

NAME

vis_StateClearData - clear results data for a single entity

C SPECIFICATION

void vis_StateClearData (vis_State *state,
                         Vint index,

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index to set results data

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Clear results data for entity index. The results data is set to zero and the data status is set to zero.


Table of Contents , State

NAME

vis_StateConvertComplex - convert complex data

C SPECIFICATION

void vis_StateConvertComplex (vis_State *state,
                              Vint complextype)

INPUT ARGUMENTS

state        Pointer to State object.
complextype  Complex type
             =SYS_COMPLEX_REALIMAGINARY  Real imaginary
             =SYS_COMPLEX_MAGNITUDEPHASE Magnitude phase

OUTPUT ARGUMENTS

None

DESCRIPTION

Convert complex data from real/imaginary to/from magnitude/phase form. If the data is not complex, complextype is not SYS_COMPLEX_REALIMAGINARY or SYS_COMPLEX_MAGNITUDEPHASE or the complextype matches the current internal type, this function returns. The function vis_StateSetMagnitudePhase is called internally to set the current state of the complex data after conversion.


Table of Contents , State

NAME

vis_StateConvertStrain - convert strain data

C SPECIFICATION

void vis_StateConvertStrain (vis_State *state,
                             Vint straintype)

INPUT ARGUMENTS

state        Pointer to State object.
straintype   Strain type
             =SYS_STRAINTYPE_TENSOR      Tensor strain
             =SYS_STRAINTYPE_ENGINEERING Engineering strain

OUTPUT ARGUMENTS

None

DESCRIPTION

Convert strain data from tensor to/from engineering form. If straintype is not x=SYS_STRAINTYPE_TENSOR or =SYS_STRAINTYPE_ENGINEERING or the straintype matches the current internal type, this function returns. The function vis_StateSetEngineeringStrain is called internally to set the current state of the strain data after conversion.


Table of Contents , State

NAME

vis_StateData - query results data for a set of entities

C SPECIFICATION

void vis_StateData (const vis_State *state,
                    Vint nix,
                    Vint ix[],
                    Vfloat s[])

void vis_StateDatadv (const vis_State *state,
                      Vint nix,
                      Vint ix[],
                      Vdouble s[])

INPUT ARGUMENTS

state        Pointer to State object.
nix          Number of entities to return results
ix           Array of entity indices

OUTPUT ARGUMENTS

s            Array of returned results data

ERRORS

VIS_ERROR_VALUE is generated if an improper nix or ix are specified.

DESCRIPTION

Get results data, s, for a set of entities, ix. The results data is subject to the current derived quantity specified by vis_StateSetDerive and the current section set by vis_StateSetSection. The results data returned in array s is ordered as results data for entity ix[0] followed by results data for ix[1],...,ix[nix-1]. If the current section is greater than the number of sections for a particular entity, then zeros are returned for that section.

Use vis_StateSetData to set results data. Use vis_StateSetDatadv to set results data in double precision.


Table of Contents , State

NAME

vis_StateDataElem - get results data at elements

C SPECIFICATION

void vis_StateDataElem (const vis_State *state,
                        Vint index,
                        Vfloat s[])

void vis_StateDataElemdv (const vis_State *state,
                          Vint index,
                          Vdouble s[])

INPUT ARGUMENTS

state        Pointer to State object.
index        Element index to get results data

OUTPUT ARGUMENTS

s            Array of returned results data

ERRORS

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

DESCRIPTION

Get results data, s, for element index. The results data is subject to the current derived quantity specified by vis_StateSetDerive and the current section set by vis_StateSetSection. The results data is also sensitive to the STATE_MAPELEM mapping options which are set using vis_StateSetParami.


Table of Contents , State

NAME

vis_StateDataElemEnt - get results data for element entities

C SPECIFICATION

void vis_StateDataElemEnt (const vis_State *state,
                           Vint type,
                           Vint index,
                           Vint no,
                           Vfloat s[])

void vis_StateDataElemEntdv (const vis_State *state,
                             Vint type,
                             Vint index,
                             Vint no,
                             Vdouble s[])

INPUT ARGUMENTS

state        Pointer to State object.
type         Type of element feature.
             =SYS_ELEM     Element nodes
             =SYS_FACE     Element face nodes
             =SYS_EDGE     Element edge nodes
index        Element index to get results data
no           Element face or edge number

OUTPUT ARGUMENTS

s            Array of returned results data

ERRORS

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

DESCRIPTION

Get results data, s, for a set nodes connected to element index. The nodes may include all the element nodes or only those nodes connected to a specified, no, element face or edge. If type is set to SYS_ELEM then the argument, no, is ignored. The results data is subject to the current derived quantity specified by vis_StateSetDerive. if the state is element or element node, the results data is subject to the current section set by vis_StateSetSection.


Table of Contents , State

NAME

vis_StateDataElemRST - get results data at given natural coordinates

C SPECIFICATION

void vis_StateDataElemRST (vis_State *state,
                           Vint index,
                           Vfloat r[],
                           Vfloat s[])

void vis_StateDataElemRSTdv (vis_State *state,
                             Vint index,
                             Vdouble r[],
                             Vdouble s[])

INPUT ARGUMENTS

state        Pointer to State object.
index        Element index to get results data
r            Element natural coordinates

OUTPUT ARGUMENTS

s            Array of returned results data

ERRORS

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

DESCRIPTION

Get results data, s, for a natural coordinate value r at element index. Like other retrieval methods, the results data is subject to the current derived quantity specified by vis_StateSetDerive and the current section set by vis_StateSetSection.


Table of Contents , State

NAME

vis_StateDataMax - get max number of results values and locations

C SPECIFICATION

void vis_StateDataMax (const vis_State *state,
                       Vint *maxdat,
                       Vint *maxloc,
                       Vint *maxsec)

INPUT ARGUMENTS

state        Pointer to State object.

OUTPUT ARGUMENTS

maxdat       Maximum number of data values
maxloc       Maximum number of data locations
maxsec       Maximum number of data sections

DESCRIPTION

Return the maximum number of data values, locations and sections. The maxdat value can be used to allocate memory which is guaranteed to hold the data returned by any call to vis_StateData. The maxsec value can be used to determine if any section data has been defined on any element.


Table of Contents , State

NAME

vis_StateDataNum - get number of results values and locations

C SPECIFICATION

void vis_StateDataNum (const vis_State *state,
                       Vint index,
                       Vint *ndat,
                       Vint *nloc,
                       Vint *nsec)

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index to query

OUTPUT ARGUMENTS

ndat         Total number of data values
nloc         Number of data locations
nsec         Number of data sections

ERRORS

VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Return the number of data values, locations and sections returned by subsequent queries of the state. These query functions include vis_StateData and vis_StateExtent. The number of sections, nsec, depends upon the number of sections defined for the element and the current returned section option specified by vis_StateSetSection. The number of locations, nloc, will be 1 for node and element sections and equal to the number of element nodes for element node sections. The total number of data values, ndat, will be the product of the number of components in the current derived quantity with the number of locations and the number of sections. Note that if the data is complex and the complex mode is SYS_COMPLEX_REALIMAGINARY the number of data values, ndat, is multiplied by 2.


Table of Contents , State

NAME

vis_StateDataLayPos - get section layer position type

C SPECIFICATION

void vis_StateDataLayPos (const vis_State *state,
                          Vint nix,
                          Vint ix[],
                          Vint lpos[])

INPUT ARGUMENTS

state        Pointer to State object.
nix          Number of entities to return
ix           Array of entity indices

OUTPUT ARGUMENTS

lpos         Array of returned section layer position types

DESCRIPTION

Get layer position types, lpos, for a set of entities, ix. If no layer position types have been defined for an element, 0 is returned.


Table of Contents , State

NAME

vis_StateDataLayers - get section layer number and position

C SPECIFICATION

void vis_StateDataLayers (const vis_State *state,
                          Vint index,
                          Vint pos[],
                          Vint lay[])

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index

OUTPUT ARGUMENTS

pos          Section layer positions
             =SYS_LAYERPOSITION_NONE    None, unknown
             =SYS_LAYERPOSITION_BOT     Bottom
             =SYS_LAYERPOSITION_MID     Middle
             =SYS_LAYERPOSITION_TOP     Top
             =SYS_LAYERPOSITION_INTPNT  Integration Point
lay          Section layer numbers

ERRORS

VIS_ERROR_OPERATION is generated if not an element state or state data has been previously set. VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Get layer position and layer number for each section for a specified index. The number of layer positions and layer numbers returned in the pos and lay arguments is equal to the number of sections specified for index using vis_StateSetDataSect.


Table of Contents , State

NAME

vis_StateDataSect - get number of results data sections

C SPECIFICATION

void vis_StateDataSect (const vis_State *state,
                        Vint nix,
                        Vint ix[],
                        Vint nsec[])

INPUT ARGUMENTS

state        Pointer to State object.
nix          Number of entities to return
ix           Array of entity indices

OUTPUT ARGUMENTS

nsec         Array of returned number of results sections

DESCRIPTION

Get number of results sections, nsec, for a set of entities, ix. If an element has no sections, 0 is returned.


Table of Contents , State

NAME

vis_StateCheckSect - check if any sections defined

C SPECIFICATION

void vis_StateCheckSect (const vis_State *state,
                         Vint *flag)

INPUT ARGUMENTS

state        Pointer to State object.

OUTPUT ARGUMENTS

flag         Section data defined.

DESCRIPTION

Query if section data has been defined. The return value flag = 0 If no sections have been defined 0 is returned, else a 1 is returned.


Table of Contents , State

NAME

vis_StateDataStat - get results data status

C SPECIFICATION

void vis_StateDataStat (const vis_State *state,
                        Vint nix,
                        Vint ix[],
                        Vint stat[])

INPUT ARGUMENTS

state        Pointer to State object.
nix          Number of entities to return results
ix           Array of entity indices

OUTPUT ARGUMENTS

stat         Array of returned results data status

DESCRIPTION

Get results data status, stat, for a set of entities, ix. The data status will be 1 if the data for a given entity has been defined and the current section number defined using vis_StateSetSection is less than or equal to the number of sections defined using vis_StateSetDataSect.

Conversely, the data status will be 0 if the data for a given entity has not been defined using vis_StateSetData or the section number defined using vis_StateSetSection is greater than the number of sections defined using vis_StateSetDataSect.


Table of Contents , State

NAME

vis_StateDataStatElemEnt - get element face or edge results data status

C SPECIFICATION

void vis_StateDataStatElemEnt (const vis_State *state,
                               Vint index,
                               Vint no,
                               Vint *stat)

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index
no           Element face or edge number

OUTPUT ARGUMENTS

stat         Returned results data status

DESCRIPTION

Get element face or element edge results data status, stat, for a given element, index and face or edge number, no. The data status will be 1 if the data has been defined, otherwise 0


Table of Contents , State

NAME

vis_StateDef - define parent and child entities and data type

C SPECIFICATION

void vis_StateDef (vis_State *state,
                   Vint nument,
                   Vint parenttype,
                   Vint childtype,
                   Vint datatype)

INPUT ARGUMENTS

state        Pointer to State object.
nument       Number of parent entities
parenttype   Type of parent entity
             =SYS_ELEM     Element type
             =SYS_FACE     Element face type
             =SYS_EDGE     Element edge type
             =SYS_NODE     Node type
             =SYS_PARTICLE Particle type
             =SYS_MODE     Mode type
childtype    Type of child entity.
             =SYS_NONE     No child entity
             =SYS_NODE     Node type
             =SYS_INTPNT   Integration Point type
datatype     Data type
             =VIS_SCALAR             Scalar data
             =VIS_VECTOR             Vector data
             =VIS_SIXDOF             Six dof vector data
             =VIS_TENSOR             Symmetric tensor data
             =VIS_GENERALTENSOR      General Tensor data
             =VIS_ELEMRES            Element Result data
             =VIS_SCALARS+n          n scalars data

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if nument is non positive. VIS_ERROR_ENUM is generated if an improper parenttype, childtype or datatype is specified.

DESCRIPTION

Specify the number of parent entities, and type of parent and child entities and data type. A child entity type may be specified if element node results are to be managed by the state. If purely node, particle, mode or element, element face or element edge results data are to be managed by the state, then childtype should be set to SYS_NONE. This function call initializes all data to zero.

The valid range of scalars data is VIS_SCALARS1, VIS_SCALARS2 through VIS_SCALARS256. The relationship VIS_SCALARSn = VIS_SCALARS + n always holds.

Inquire of defined nument, parenttype, childtype and datatype as output arguments using

     void vis_StateInq (const vis_State *state,
                        Vint *nument,
                        Vint *parenttype,
                        Vint *childtype,
                        Vint *datatype)


Table of Contents , State

NAME

vis_StateDeform - create deformed node vector of coordinates

C SPECIFICATION

void vis_StateDeform (vis_State *state,
                      Vfloat f,
                      vis_State *stated,
                      vis_Group *group)

INPUT ARGUMENTS

state        Pointer to State object.
f            Floating point coefficient.
stated       Pointer to State object of node displacements.
group        Pointer to Group object.
             If NULL, then all entities are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if group is not the same entity type as state. VIS_ERROR_OPERATION is generated if state is not a node vector state or stated is not a node vector or node sixdof state. VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

DESCRIPTION

Set the contents of state to the sum of the undeformed coordinates plus some factor, f, times the displacements contained in stated. The undeformed coordinates are accessed from the GridFun attribute object. Set the GridFun attribute object using vis_StateSetObject. The states must be node states. The input state object must be a vector state, the stated object must be a node vector or node sixdof state. This routine implements the following equation,
     state = undeformed_coordinates + f * stated


Table of Contents , State

NAME

vis_StateDemo - create "demo" node vector displacement results

C SPECIFICATION

void vis_StateDemo (vis_State *state,
                    Vint oper,
                    Vfloat f,
                    vis_Group *group)

INPUT ARGUMENTS

state        Pointer to State object.
oper         Operation specified to create state
             =STATE_DEMO_BEAM        Create beam bending displacements
             =STATE_DEMO_PLATE       Create plate bending displacements
f            Floating point factor.
group        Pointer to Group object.
             If NULL, then all entities are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper operation oper is specified. VIS_ERROR_VALUE is generated if group is not the same entity type as state. VIS_ERROR_OPERATION is generated if the state is not a node vector state. VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

DESCRIPTION

Set the contents of state to a vector of node displacements which resemble either beam or plate bending. The maximum displacement magnitude is f times one half of the maximum model extent along the global axes. The undeformed coordinates are accessed from the GridFun attribute object. Set the GridFun attribute object using vis_StateSetObject.


Table of Contents , State

NAME

vis_StateDerivative - perform differential operations on a state

C SPECIFICATION

void vis_StateDerivative (vis_State *state,
                          Vint oper,
                          Vfloat f,
                          Vint func,
                          vis_State *statex,
                          vis_Group *group)

INPUT ARGUMENTS

state        Pointer to State object.
oper         Operation specified to modify state
             =STATE_EQUAL            Operation =
             =STATE_PLUSEQUAL        Operation +=
             =STATE_MINUSEQUAL       Operation -=
             =STATE_MULTIPLYEQUAL    Operation *=
             =STATE_DIVIDEEQUAL      Operation /=
f            Floating point coefficient.
func         Function specified to perform on statex
             =STATE_CURL             Curl function
             =STATE_DIV              Divergence function
             =STATE_GRAD             Gradient function
             =STATE_GRADNORM         Normalized Gradient function
             =STATE_STRAIN           Infinitesimal strain function
             =STATE_VECTORGRAD       Vector gradient function
statex       Pointer to State operand object.
group        Pointer to Group object.
             If NULL, then all entities are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper operation oper or function func are specified. VIS_ERROR_VALUE is generated if group is not the same entity type as state. VIS_ERROR_OPERATION is generated if the state and statex entity types are not proper or the derived data type of statex does not match the proper data type for the function. VIS_ERROR_NULLOBJECT is generated if the state object does not have a GridFun attribute object.

DESCRIPTION

Modify the contents of state as a function of a single state, statex. The function, func is performed upon the state, statex. This result is scaled by a specified constant factor, f. The result then modifies the destination state, state in some way depending upon oper. The source state, statex must be a node or element node state. The destination state, state may be either a element or element node state. The data type of state and the derived type of statex depend upon the specified function, func as follows:
     oper               state          statex
     ----------------------------------------
     STATE_CURL         vector         vector
     STATE_DIV          scalar         vector
     STATE_GRAD         vector         scalar
     STATE_GRADNORM     vector         scalar
     STATE_STRAIN       tensor         vector
     STATE_VECTORGRAD   generaltensor  vector
This routine implements the following equation,
     state oper f*func(statex)
For example the call,
     vis_StateDerivative(state,STATE_PLUSEQUAL,2.,STATE_DIV,statex,NULL);
executes the following equation,
     state += 2.*DIV(statex)

In particular the STATE_GRADNORM operator may be used to compute normals to a scalar field for use in smooth shading of isosurfaces. Assume that a node state object contains a continuous scalar field. Smoothly varying node normals to the scalar field may be generated by first using vis_StateDerivative to compute normal vectors at element nodes and then using vis_StateMap to map the element node normals to nodes. The mapping operation is requred since the computation of gradient normals at element nodes will, in general, result in discontinuous values of the gradients between elements.


Table of Contents , State

NAME

vis_StateDirCos - get local direction cosine matrix

C SPECIFICATION

void vis_StateDirCos (vis_State *state,
                      Vint index,
                      Vfloat tm[][3][3])

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index

OUTPUT ARGUMENTS

tm           Array of returned direction cosine matrices

ERRORS

VIS_ERROR_NULLOBJECT is generated if the GridFun or IdTran attribute objects have not been set.

DESCRIPTION

Get direction cosine matrices, tm, for an entity, index. The direction cosine matrices are the local system of the node, element or element nodes used in the vis_StateTransform function.


Table of Contents , State

NAME

vis_StateElemGroup - derive groups of elements

C SPECIFICATION

void vis_StateElemGroup (vis_State *state,
                         Vint oper,
                         vis_Group *group,
                         vis_Group *groupdst)

INPUT ARGUMENTS

state        Pointer to State object.
oper         Operation specified to derive group
             =STATE_EXTENT           Elements lying within an interval
             =STATE_OUTBOUND         Elements lying outside an interval
             =STATE_NONZERO          Elements with non zero value
             =STATE_DEFINED          Elements with defined data
             =STATE_LOCALMIN         Elements with local minimum
             =STATE_LOCALMAX         Elements with local maximum
             =STATE_LOCALMINMAX      Elements with local min or max
group        Pointer to Group object of elements.
             If NULL, then all elements are assumed.

OUTPUT ARGUMENTS

groupdst     Pointer to derived Group object of elements.

ERRORS

VIS_ERROR_ENUM is generated if an improper operation oper is specified. VIS_ERROR_VALUE is generated if group is not an element group. VIS_ERROR_OPERATION is generated if state parent type is not element.

DESCRIPTION

Derive a group of elements from an input group of elements using a specified operation. The output groupdst must have been previously created and defined as an element group. Note that groupdst is not cleared by this function, the derived element entities are added to any existing elements in the output groupdst. Any entities for which data has not been defined are skipped.

For the operation STATE_EXTENT and STATE_OUTBOUND the extent limits are specified using vis_StateSetGroupParamfv If any of the data components at a element satisfy the test condition then the element is added to the group.

The operation STATE_DEFINED adds all nodes for which data has been defined using vis_StateData.

The operation STATE_LOCALMIN, STATE_LOCALMAX or STATE_LOCALMINMAX adds all elements which are a local data minimum, maximum or either minimum or maximum for which data has been defined using vis_StateData. The state must either be a scalar state or the current derived quantity is a scalar.


Table of Contents , State

NAME

vis_StateExtent - (parallel) minimum and maximum values

C SPECIFICATION

void vis_StateExtent (vis_State *state,
                      vis_Group *group,
                      Vfloat extent[])

INPUT ARGUMENTS

state        Pointer to State object.
group        Pointer to Group object of entities.  If NULL then all 
             entities are assumed.

OUTPUT ARGUMENTS

extent       Minimum and maximum values of results data

ERRORS

VIS_ERROR_VALUE is generated if group parent entity size and type does not match the parent entity size and type of the state object.

DESCRIPTION

Compute minimum and maximum values of results data for a set of entities specified by an optional input group. The extent array contains the minimum results data values followed by the maximum results data values. The minimum and maximum are calculated for the current derived quantity. For example for a vector state a total of 6 values (minimum x,y,z followed by maximum x,y,z) will be returned in extent. Any entities for which data has not been defined are skipped.


Table of Contents , State

NAME

vis_StateExtentLoc - minimum and maximum values and locations

C SPECIFICATION

void vis_StateExtentLoc (vis_State *state,
                         vis_Group *group,
                         Vfloat extent[],
                         Vint ix[],
                         Vint no[])

INPUT ARGUMENTS

state        Pointer to State object.
group        Pointer to Group object of entities.  If NULL then all
             entities are assumed.

OUTPUT ARGUMENTS

extent       Minimum and maximum values of results data
ix           Entity indices
no           Element node connectivity indices

ERRORS

VIS_ERROR_VALUE is generated if group parent entity size and type does not match the parent entity size and type of the state object.

DESCRIPTION

Compute minimum and maximum values of results data for a set of entities specified by an optional input group and return the corresponding locations at which the extremes occur. The extent array contains the minimum results data values followed by the maximum results data values. The minimum and maximum are calculated for the current derived quantity. The ix array contains the node or element indices corresponding to the extreme values in extent. The no array is filled only if the state is an element node state. It contains the element connectivity index of the element node. For example, no[0] = 2 indicates the second node in the element connectivity of element index ix[0]. Note that for a general tensor state 18 values will be returned in extent. Any entities for which data has not been defined are skipped.


Table of Contents , State

NAME

vis_StateExtentLocSect - minimum and maximum values,locations,sections

C SPECIFICATION

void vis_StateExtentLocSect (vis_State *state,
                             vis_Group *group,
                             Vfloat extent[],
                             Vint ix[],
                             Vint no[],
                             Vint sc[])

INPUT ARGUMENTS

state        Pointer to State object.
group        Pointer to Group object of entities.  If NULL then all
             entities are assumed.

OUTPUT ARGUMENTS

extent       Minimum and maximum values of results data
ix           Entity indices
no           Element node connectivity indices
sc           Section numbers

ERRORS

VIS_ERROR_VALUE is generated if group parent entity size and type does not match the parent entity size and type of the state object.

DESCRIPTION

Compute minimum and maximum values of results data for a set of entities specified by an optional input group and return the corresponding locations and sections at which the extremes occur. This function is similar to vis_StateExtentLoc except that section numbers are also returned.


Table of Contents , State

NAME

vis_StateMap - map results data between node, element and element node locations

C SPECIFICATION

void vis_StateMap (vis_State *state,
                   vis_State *fromstate,
                   vis_Group *group)

INPUT ARGUMENTS

state        Pointer to destination State object.
fromstate    Pointer to source State object.
group        Pointer to Group object of elements.  If NULL then all
             elements are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if group parent entity type is not SYS_ELEM or size does not match the number of elements. VIS_ERROR_NULLOBJECT is generated if a GridFun attribute object has not been set. VIS_ERROR_OPERATION is generated if the parent and child entity types of the state and fromstate objects are identical.

DESCRIPTION

Map results quantities between node, element and element node locations. This function maps results data from the entity locations of the source fromstate object to the entity locations of the destination state object. The fromstate object is unchanged by this function. The quantity mapped from the fromstate is dependent upon the current derived quantity in fromstate, see vis_StateSetDerive. The mapping process is subject to an optional group which determines the element entities which are to be mapped to the state object. The state and fromstate objects must be distinct.

Note that a GridFun attribute object must be set in any element or element node states for any mapping operation. Set this attribute object using vis_StateSetObject.

The algorithm used to map quantities to elements from nodes or element nodes may select an average quantity, geometry weighted average quantity, maximum difference quantity or minimum or maximum quantities. Use vis_StateSetParami with STATE_MAPNODE to set the node mapping type. Use vis_StateSetParami with STATE_MAPELEM to set the element mapping type. The mapping algorithm is subject to several other options specified using vis_StateSetParami.


Table of Contents , State

NAME

vis_StateMapElemNode - map results data to element node location

C SPECIFICATION

void vis_StateMapElemNode (vis_State *state,
                           vis_State *fromstate,
                           vis_Group *group,
                           vis_IdTran *idtran)

INPUT ARGUMENTS

state        Pointer to destination State object.
fromstate    Pointer to source State object.
group        Pointer to Group object of elements.  If NULL then all
             elements are assumed.
idtran       Pointer to IdTran object of element region numbers.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if group parent entity type is not SYS_ELEM or size does not match the number of elements. VIS_ERROR_NULLOBJECT is generated if a GridFun attribute object has not been set.

DESCRIPTION

Map results quantities between element and element node locations. This function maps results data from the entity locations of the source fromstate object to the entity locations of the destination state object. The fromstate object is unchanged by this function. The quantity mapped from the fromstate is dependent upon the current derived quantity in fromstate, see vis_StateSetDerive. The input idtran object must contain a region number for each element. Data is averaged at element nodes using only elements within the same region. If idtran is NULL, then all elements are assumed to be in a single mapping region. The mapping process is subject to an optional group which determines the element entities which are to be mapped to the state object. The state and fromstate objects must be distinct.

Note that a GridFun attribute object must be set in any element or element node states for any mapping operation. Set this attribute object using vis_StateSetObject.

The algorithm used to map quantities to elements from element nodes may select an average quantity, geometry weighted average quantity, maximum difference quantity or minimum or maximum quantities. Use vis_StateSetParami with STATE_MAPNODE to set the node mapping type. Use vis_StateSetParami with STATE_MAPELEM to set the element mapping type.


Table of Contents , State

NAME

vis_StateMidside - process results data at midside nodes

C SPECIFICATION

void vis_StateMidside (vis_State *state,
                       vis_Group *group)

INPUT ARGUMENTS

state        Pointer to State object.
group        Pointer to Group object of elements.  If NULL then all
             elements are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if group parent entity type is not SYS_ELEM or size does not match the number of elements. VIS_ERROR_NULLOBJECT is generated if a GridFun attribute object has not been set. VIS_ERROR_OPERATION is generated if sections are defined.

DESCRIPTION

Provide specialized processing for data at the midside nodes of elements as a function of the corner nodes (edge endpoint nodes) of the element. Only edge midside nodes are affected, midface and midbody nodes are not processed. Note that a GridFun attribute object must be set in the object. Set this attribute object using vis_StateSetObject.

Processing options include linearly interpolating the midside node data as a function of the edge endpoint node data or clamping the midside node data to the minimum and maximum of the edge endpoint node data. By default, the midside node data is linearly interpolated. Use vis_StateSetParami with STATE_MIDSIDE to control the processing option.


Table of Contents , State

NAME

vis_StateNodeGroup - derive groups of nodes

C SPECIFICATION

void vis_StateNodeGroup (vis_State *state,
                         Vint oper,
                         vis_Group *group,
                         vis_Group *groupdst)

INPUT ARGUMENTS

state        Pointer to State object.
oper         Operation specified to derive group
             =STATE_EXTENT           Nodes lying within an interval
             =STATE_OUTBOUND         Nodes lying outside an interval
             =STATE_NONZERO          Nodes with non zero value
             =STATE_DEFINED          Nodes with defined data
             =STATE_LOCALMIN         Nodes with local minimum
             =STATE_LOCALMAX         Nodes with local maximum
             =STATE_LOCALMINMAX      Nodes with local min or max
group        Pointer to Group object of nodes.
             If NULL, then all nodes are assumed.

OUTPUT ARGUMENTS

groupdst     Pointer to derived Group object of nodes.

ERRORS

VIS_ERROR_ENUM is generated if an improper operation oper is specified. VIS_ERROR_VALUE is generated if group is not an node group. VIS_ERROR_OPERATION is generated if state parent type is not node.

DESCRIPTION

Derive a group of nodes from an input group of nodes using a specified operation. The output groupdst must have been previously created and defined as an node group. Note that groupdst is not cleared by this function, the derived node entities are added to any existing nodes in the output groupdst. Any entities for which data has not been defined are skipped.

For the operation STATE_EXTENT and STATE_OUTBOUND the extent limits are specified using vis_StateSetGroupParamfv If any of the data components at a node satisfy the test condition then the node is added to the group.

The operation STATE_DEFINED adds all nodes for which data has been defined using vis_StateData.

The operation STATE_LOCALMIN, STATE_LOCALMAX or STATE_LOCALMINMAX adds all nodes which are a local data minimum, maximum or either minimum or maximum for which data has been defined using vis_StateData. The state must either be a scalar state or the current derived quantity is a scalar.


Table of Contents , State

NAME

vis_StateNumDerive - get number of data components

C SPECIFICATION

void vis_StateNumDerive (vis_State *state,
                         Vint *ncmp)

INPUT ARGUMENTS

state        Pointer to State object.

OUTPUT ARGUMENTS

ncmp         Number of components in current derived quantity type

DESCRIPTION

Return the number of components in the current derived quantity type.


Table of Contents , State

NAME

vis_StateOperateBinary - operate on a state as a function of two states

C SPECIFICATION

void vis_StateOperateBinary (vis_State *state,
                             Vint oper,
                             Vfloat f,
                             Vint func,
                             vis_State *statex,
                             vis_State *statey,
                             vis_Group *group)

void vis_StateOperateBinarydv (vis_State *state,
                               Vint oper,
                               Vdouble f,
                               Vint func,
                               vis_State *statex,
                               vis_State *statey,
                               vis_Group *group)

INPUT ARGUMENTS

state        Pointer to State object.
oper         Operation specified to modify state
             =STATE_EQUAL            Operation =
             =STATE_PLUSEQUAL        Operation +=
             =STATE_MINUSEQUAL       Operation -=
             =STATE_MULTIPLYEQUAL    Operation *=
             =STATE_DIVIDEEQUAL      Operation /=
f            Floating point coefficient.
func         Function specified to perform on statex and statey
             =STATE_MIN    minimum function
             =STATE_MAX    maximum function
             =STATE_AVE    average function
             =STATE_CROSS  vector cross product function
             =STATE_DOT    vector dot product function
             =STATE_SUM    sum function
statex       Pointer to State operand object.
statey       Pointer to State operand object.
group        Pointer to Group object.
             If NULL, then all entities are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper operation oper or function func are specified. VIS_ERROR_VALUE is generated if group is not the same entity type as state. VIS_ERROR_OPERATION is generated if the state, statex and statey entity types are not identical. VIS_ERROR_OPERATION is generated for the STATE_CROSS operation if the derived data types of state, statex and statey are not vector. VIS_ERROR_OPERATION is generated for the STATE_DOT operation if the basic data type of state is not scalar and the derived data types of statex and statey are not vector. VIS_ERROR_OPERATION is generated for all other operations if the derived data types of statex and statey are not the same as the basic data type of state. VIS_ERROR_OPERATION is generated if the state, statex and statey have incompatible section configurations.

DESCRIPTION

Modify the contents of state as a function of a two states, statex and statey. The function, func is performed upon the states, statex and statey. This result is scaled by a specified constant factor, f. The result then modifies the destination state, state in some way depending upon oper. Any entities for which data has not been defined are skipped.

If state has no prior data set, then state is initialized with the derived section configuration of statex.

This routine implements the following equation,

     state oper f*func(statex,statey)
For example the call,
     vis_StateOperateBinary(state,STATE_EQUAL,2.,STATE_MIN,statex,statey,NULL);
executes the following equation,
     state = 2.*min(statex,statey)
The state, statex and statey objects may be the same.


Table of Contents , State

NAME

vis_StateOperateUnary - operate on a state as a function of another state

C SPECIFICATION

void vis_StateOperateUnary (vis_State *state,
                            Vint oper,
                            Vfloat f,
                            Vint func,
                            vis_State *statex,
                            vis_Group *group)

void vis_StateOperateUnarydv (vis_State *state,
                              Vint oper,
                              Vdouble f,
                              Vint func,
                              vis_State *statex,
                              vis_Group *group)

INPUT ARGUMENTS

state        Pointer to State object.
oper         Operation specified to modify state
             =STATE_EQUAL            Operation =
             =STATE_PLUSEQUAL        Operation +=
             =STATE_MINUSEQUAL       Operation -=
             =STATE_MULTIPLYEQUAL    Operation *=
             =STATE_DIVIDEEQUAL      Operation /=
f            Floating point coefficient.
func         Function specified to perform on statex
             =STATE_IDENTITY         identity returns statex value
             =STATE_UNITY            value of 1.
             =STATE_ACOS             acos function
             =STATE_ASIN             asin function
             =STATE_ATAN             atan function
             =STATE_COS              cos function
             =STATE_SIN              sin function
             =STATE_TAN              tan function
             =STATE_SQRT             sqrt function
             =STATE_LOG              log function
             =STATE_EXP              exp function
             =STATE_ABS              absolute value function
             =STATE_RECIPROCAL       reciprocal function
statex       Pointer to State operand object.
group        Pointer to Group object.
             If NULL, then all entities are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper operation oper or function func are specified. VIS_ERROR_VALUE is generated if group is not the same entity type as state. VIS_ERROR_OPERATION is generated if the state and statex entity types are not identical or the derived data type of statex does not match the basic data type of state. VIS_ERROR_OPERATION is generated if the state and statex have incompatible section configurations.

DESCRIPTION

Modify the contents of state as a function of a single state, statex. The function, func is performed upon the state, statex. This result is scaled by a specified constant factor, f. The result then modifies the destination state, state in some way depending upon oper. Any entities for which data has not been defined are skipped. Note that func of STATE_UNITY ignores statex.

If state has no prior data set, then state is initialized with the derived section configuration of statex.

This routine implements the following equation,

     state oper f*func(statex)
For example the call,
     vis_StateOperateUnary(state,STATE_PLUSEQUAL,2.,STATE_SQRT,statex,NULL);
executes the following equation,
     state += 2.*sqrt(statex)
The state and statex objects may be the same.


Table of Contents , State

NAME

vis_StateSetData - set results data

C SPECIFICATION

void vis_StateSetData (vis_State *state,
                       Vint index,
                       Vfloat s[])

void vis_StateSetDatadv (vis_State *state,
                         Vint index,
                         Vdouble s[])

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index to set results data
s            Array of results data to be set at entity index

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper index is specified. VIS_ERROR_NULLOBJECT is generated if a GridFun attribute object has not been set and the state manages element node results data. VIS_ERROR_OPERATION is generated if the state manages element node results data and the GridFun attribute object returns a total number of entities which does not match the number of entities declared in vis_StateDef.

DESCRIPTION

Set results data, s, for a specified index. Use vis_StateData to retrieve state data. Use vis_StateDatadv to retrieve state data in double precision. If the state object manages node or element centroid data, the array s contains 1, 3, 6 or 9 components corresponding to scalar, vector, six dof vector, tensor or general tensor data types. If element node data is managed, s contains 1, 3, 6 or 9 components for each element node.


Table of Contents , State

NAME

vis_StateSetDataElemEnt - set element face or edge results data

C SPECIFICATION

void vis_StateSetDataElemEnt (vis_State *state,
                              Vint index,
                              Vint no,
                              Vfloat s[])

void vis_StateSetDataElemEntdv (vis_State *state,
                                Vint index,
                                Vint no,
                                Vdouble s[])

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index to set results data
no           Element face or edge number
s            Array of results data to be set at entity index

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper index is specified. VIS_ERROR_NULLOBJECT is generated if a GridFun attribute object has not been set and the state manages element node results data. VIS_ERROR_OPERATION is generated if not an element face or element edge state.

DESCRIPTION

Set results data, s, for a specified element index and element face or edge number, no. The functions vis_StateDataElemEnt and vis_StateDataElemEntdv are specifically designed to retrieve element face and element edge data.


Table of Contents , State

NAME

vis_StateSetDataEnt - set results data element faces or edges

C SPECIFICATION

void vis_StateSetDataEnt (vis_State *state,
                          Vint index,
                          Vint numno,
                          Vint no[]),

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index to set number of results sections
numno        Number of element faces or element edges
no           Array of element face or element edge numbers

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if not an element face or element edge state.

DESCRIPTION

Set element faces or edges at which data is to be specified. Use vis_StateDataStatElemEnt to query if data is specified for a particular element face or element edge.


Table of Contents , State

NAME

vis_StateSetDataLayPos - set section layer position type

C SPECIFICATION

void vis_StateSetDataLayPos (vis_State *state,
                             Vint index,
                             Vint lpos)

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index to set number of results sections
lpos         Section layer position type
             =SYS_LAYERPOSITION_NONE    None, unknown
             =SYS_LAYERPOSITION_MID     Middle
             =SYS_LAYERPOSITION_BOTTOP  Bottom and top
             =SYS_LAYERPOSITION_BOTTOPMID  Bottom, middle and top
             =SYS_LAYERPOSITION_INTPNT  Integration Point

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if not an element state or state data has been previously set. VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Set layer position type, lpos, for a specified index. Layer position types can only be specified for element or element node states. This value does not affect the operation of the State object, it is used for query only. Use vis_StateDataLayPos to retrieve the layer position type.


Table of Contents , State

NAME

vis_StateSetDataLayers - set section layer number and position

C SPECIFICATION

void vis_StateSetDataLayers (vis_State *state,
                             Vint index,
                             Vint pos[],
                             Vint lay[])

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index
pos          Section layer position type
             =SYS_LAYERPOSITION_NONE    None, unknown
             =SYS_LAYERPOSITION_BOT     Bottom
             =SYS_LAYERPOSITION_MID     Middle
             =SYS_LAYERPOSITION_TOP     Top
             =SYS_LAYERPOSITION_INTPNT  Integration Point
lay          Section layer numbers

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if not an element state or state data has been previously set. VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Set layer position and layer number for each section for a specified index. The number of layer positions and layer numbers in the pos and lay arguments is equal to the number of sections specified for index using vis_StateSetDataSect. Layer position types can only be specified for element or element node states. This value does not affect the operation of the State object, it is used for query only. Use vis_StateDataLayers to retrieve the layer number and position.


Table of Contents , State

NAME

vis_StateSetDataSect - set number of results data sections

C SPECIFICATION

void vis_StateSetDataSect (vis_State *state,
                           Vint index,
                           Vint nsec)

INPUT ARGUMENTS

state        Pointer to State object.
index        Entity index
nsec         Number of results sections

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if not an element state or state data has been previously set. VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Set number of results sections, nsec, for a specified index. Section results may only be specified for element or element node states. Use vis_StateDataSect to retrieve the number of sections.


Table of Contents , State

NAME

vis_StateSetDerive - set derived quantity

C SPECIFICATION

void vis_StateSetDerive (vis_State *state,
                         Vint derive)

INPUT ARGUMENTS

state        Pointer to State object.
derive       Type of derived quantity
             =VIS_SCALAR             Primitive scalar
             =VIS_VECTOR             Primitive vector
             =VIS_VECTOR_X           Vector x component
             =VIS_VECTOR_Y           Vector y component
             =VIS_VECTOR_Z           Vector z component
             =VIS_VECTOR_MAG         Vector magnitude
             =VIS_SIXDOF             Primitive six dof vectors
             =VIS_SIXDOF_TX          Six dof tx component
             =VIS_SIXDOF_TY          Six dof ty component
             =VIS_SIXDOF_TZ          Six dof tz component
             =VIS_SIXDOF_RX          Six dof rx component
             =VIS_SIXDOF_RY          Six dof ry component
             =VIS_SIXDOF_RZ          Six dof rz component
             =VIS_SIXDOF_TMAG        Six dof translation magnitude
             =VIS_SIXDOF_RMAG        Six dof rotation magnitude
             =VIS_SIXDOF_TVEC        Six dof translation vector
             =VIS_SIXDOF_RVEC        Six dof rotation vector
             =VIS_TENSOR             Primitive tensor
             =VIS_TENSOR_XX          Tensor xx component
             =VIS_TENSOR_YY          Tensor yy component
             =VIS_TENSOR_ZZ          Tensor zz component
             =VIS_TENSOR_XY          Tensor xy component
             =VIS_TENSOR_YZ          Tensor yz component
             =VIS_TENSOR_ZX          Tensor zx component
             =VIS_TENSOR_MEAN        Tensor mean
             =VIS_TENSOR_VONMISES    Tensor Von Mises stress
             =VIS_TENSOR_VONMISES_E  Tensor Von Mises strain
             =VIS_TENSOR_OCTAHEDRAL  Tensor octahedral shear
             =VIS_TENSOR_DETERMINANT Tensor determinant
             =VIS_TENSOR_INTENSITY   Tensor intensity
             =VIS_TENSOR_ANGSHEAR    Tensor max shear angle in degrees
             =VIS_TENSOR_MAXSHEAR    Tensor max shear
             =VIS_TENSOR_EQUDIRECT   Tensor equal direct at max shear
             =VIS_TENSOR_MINPRINC    Tensor minimum principal value
             =VIS_TENSOR_MIDPRINC    Tensor middle principal value
             =VIS_TENSOR_MAXPRINC    Tensor maximum principal value
             =VIS_TENSOR_MINPRINCDEV Tensor minimum principal deviatoric
                                     value
             =VIS_TENSOR_MIDPRINCDEV Tensor middle principal deviatoric
                                     value
             =VIS_TENSOR_MAXPRINCDEV Tensor maximum principal deviatoric
                                     value
             =VIS_TENSOR_PRINC       Tensor principal values
             =VIS_TENSOR_PRINCDIRCOS Tensor principal directions
             =VIS_GENERALTENSOR      Primitive general tensor
             =VIS_GENERALTENSOR_XX   General tensor xx component
             =VIS_GENERALTENSOR_XY   General tensor xy component
             =VIS_GENERALTENSOR_XZ   General tensor xz component
             =VIS_GENERALTENSOR_YX   General tensor yx component
             =VIS_GENERALTENSOR_YY   General tensor yy component
             =VIS_GENERALTENSOR_YZ   General tensor yz component
             =VIS_GENERALTENSOR_ZX   General tensor zx component
             =VIS_GENERALTENSOR_ZY   General tensor zy component
             =VIS_GENERALTENSOR_ZZ   General tensor zz component
             =VIS_GENERALTENSOR_SYM  General tensor symmetrized tensor
             =VIS_GENERALTENSOR_XVEC General tensor first row vector
             =VIS_GENERALTENSOR_YVEC General tensor second row vector
             =VIS_GENERALTENSOR_ZVEC General tensor third row vector
             =VIS_ELEMRES            Element results
             =VIS_ELEMRES_SHELL_NXX  Shell Nxx component
             =VIS_ELEMRES_SHELL_NYY  Shell Nyy component
             =VIS_ELEMRES_SHELL_NXY  Shell Nxy component
             =VIS_ELEMRES_SHELL_MXX  Shell Mxx component
             =VIS_ELEMRES_SHELL_MYY  Shell Myy component
             =VIS_ELEMRES_SHELL_MXY  Shell Mxy component
             =VIS_ELEMRES_SHELL_QXZ  Shell Qxz component
             =VIS_ELEMRES_SHELL_QYZ  Shell Qyz component
             =VIS_ELEMRES_BEAM_NXX   Beam Nxx component
             =VIS_ELEMRES_BEAM_MYY   Beam Myy component
             =VIS_ELEMRES_BEAM_MZZ   Beam Mzz component
             =VIS_ELEMRES_BEAM_T     Beam Torque component
             =VIS_ELEMRES_BEAM_QXY   Beam Qxy component
             =VIS_ELEMRES_BEAM_QZX   Beam Qzx component
             =VIS_ELEMRES_BEAM_TB    Beam Bimoment component
             =VIS_ELEMRES_SPRINGDASHPOT_F SpringDashpot Force component
             =VIS_ELEMRES_SPRINGDASHPOT_FX SpringDashpot Force X component
             =VIS_ELEMRES_SPRINGDASHPOT_FY SpringDashpot Force Y component
             =VIS_ELEMRES_SPRINGDASHPOT_FZ SpringDashpot Force Z component
             =VIS_ELEMRES_SPRINGDASHPOT_MX SpringDashpot Moment X component
             =VIS_ELEMRES_SPRINGDASHPOT_MY SpringDashpot Moment Y component
             =VIS_ELEMRES_SPRINGDASHPOT_MZ SpringDashpot Moment Z component
             =VIS_SCALARS1 thru 10   Primitive scalars
             =VIS_SCALARS_1          First scalar
             =VIS_SCALARS_2          Second scalar
             =VIS_SCALARS_3          Third scalar
             =VIS_SCALARS_4          Fourth scalar
             =VIS_SCALARS_5          Fifth scalar
             =VIS_SCALARS_6          Sixth scalar
             =VIS_SCALARS_7          Seventh scalar
             =VIS_SCALARS_8          Eighth scalar
             =VIS_SCALARS_9          Ninth scalar
             =VIS_SCALARS_10         Tenth scalar

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper derived quantity derive is specified.

DESCRIPTION

Set current derived quantity type. All subsequent queries of the state will return the specified derived quantity. These query functions include vis_StateData and vis_StateExtent. Use vis_StateNumDerive to return the number of components in the current derived quantity type.

The relationship VIS_SCALARS_n = VIS_SCALARS_1 + n-1 always holds.

Inquire of set derive as an output argument using

     void vis_StateGetDerive (const vis_State *state,
                              Vint *derive)


Table of Contents , State

NAME

vis_StateSetEngineeringStrain - set engineering strain flag

C SPECIFICATION

void vis_StateSetEngineeringStrain (vis_State *state,
                                    Vint flag)

INPUT ARGUMENTS

state        Pointer to State object.
flag         Engineering strain flag
             =SYS_OFF                Tensor strain
             =SYS_ON                 Engineering strain

OUTPUT ARGUMENTS

None

DESCRIPTION

Set engineering strain interpretation of tensor data type. If this flag is enabled then the shear (off diagonal) components of a tensor data type, as set by vis_StateDef, are assumed to be twice the standard tensor values. The Max Shear derived value is also returned as twice the standard tensor value. By default the engineering strain flag is SYS_OFF. Note that this flag is automatically set when converting strain data using vis_StateConvertStrain.

Inquire of set flag as an output argument using

     void vis_StateGetEngineeringStrain (const vis_State *state,
                                         Vint *flag)


Table of Contents , State

NAME

vis_StateSetMagnitudePhase - set magnitude phase flag

C SPECIFICATION

void vis_StateSetMagnitudePhase (vis_State *state,
                                 Vint flag)

INPUT ARGUMENTS

state        Pointer to State object.
flag         Magnitude phase flag
             =SYS_OFF                Real imaginary
             =SYS_ON                 Magnitude phase

OUTPUT ARGUMENTS

None

DESCRIPTION

Set magnitude phase interpretation of complex data type. By default the magnitude phase flag is SYS_OFF and complex data is interpreted as real imaginary. Note that this flag is automatically set when converting complex data using vis_StateConvertComplex.

Inquire of set flag as an output argument using

     void vis_StateGetMagnitudePhase (const vis_State *state,
                                      Vint *flag)


Table of Contents , State

NAME

vis_StateSetGroupParam - set group derivation parameters

C SPECIFICATION

void vis_StateSetGroupParamfv (vis_State *state,
                               Vint ptype,
                               Vfloat vparam[])

INPUT ARGUMENTS

state        Pointer to State object.
ptype        Type of group parameter to set
             =STATE_EXTENT           Scalar state extent, vparam
vparam       Specifies the float values that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper node ptype is specified.

DESCRIPTION

Set group derivation parameters. The STATE_EXTENT parameters are two float values specifying scalar state extent, minimum scalar value followed by maximum scalar value. The extent check includes the extreme values.


Table of Contents , State

NAME

vis_StateSetHashTable - set pointers to HashTable objects.

C SPECIFICATION

void vis_StateSetHashTable (vis_State *state,
                            Vint type,
                            vsy_HashTable *hashtable)

INPUT ARGUMENTS

state        Pointer to State object.
type         The name of the object type contained in the HashTable.
             =VIS_COORDSYS           CoordSys objects
             =VIS_ELEMDAT            ElemDat objects
hashtable    Pointer to the HashTable to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper type is specified.

DESCRIPTION

Set a pointer to a HashTable object containing coordinate system, or element data objects.


Table of Contents , State

NAME

vis_StateSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_StateSetObject (vis_State *state,
                         Vint objecttype,
                         Vobject *object)

INPUT ARGUMENTS

state        Pointer to State object.
objecttype   The name of the object type to be set.
             =VIS_GRIDFUN            GridFun object
             =VIS_IDTRAN             IdTran object containing local
                                     coordinate system flags.
             =VIS_STATE              State object containing local
                                     coordinate system direction cosines.
             =VIS_STATE_ROTANG       State object containing rotation
                                     angle vectors.
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. If a GridFun attribute object is set then all finite element topology, connectivity, node coordinate and node and element association queries will be made through the GridFun interface. To deactivate the GridFun interface, set a NULL GridFun object pointer. A GridFun attribute object is required to store element node results data in a state or to perform any mapping operation using vis_StateMap.

The IdTran object is required if local coordinate system is to be maintained for the state data. Depending upon the local coordinate system flags contained in the IdTran object HashTable objects and/or a State may also be required. Set HashTable objects using vis_StateSetHashTable. Set State objects using vis_StateSetObject.

Local coordinate systems are used by the vis_StateTransform and vis_StateDirCos functions.

Get object as an output argument using

     void vis_StateGetObject (vis_State *state,
                              Vint objecttype,
                              Vobject **object)


Table of Contents , State

NAME

vis_StateSetParami - set state parameters

C SPECIFICATION

void vis_StateSetParami (vis_State *state,
                         Vint ptype,
                         Vint iparam)

INPUT ARGUMENTS

state        Pointer to State object.
ptype        Type of state parameter to set
             =STATE_MAPELEM          Select element mapping type
             =STATE_MAPNODE          Select node mapping type
             =STATE_MAPDEFINED       Enable mapping defined entities only
             =STATE_MAPNONZERO       Enable mapping nonzero contributions
             =STATE_MIDSIDE          Select midside node processing
             =STATE_SORTHIGHLOW      Enable high to low sort
             =STATE_SORTABSVALUE     Enable absolute value sort
iparam       Specifies the integer value that ptype will be set to.
             =STATE_MAPAVE           Average to node or element
             =STATE_MAPMIN           Minimum to node or element
             =STATE_MAPMAX           Maximum to node or element
             =STATE_MAPABSMIN        Absolute minimum to node or element
             =STATE_MAPABSMAX        Absolute maximum to node or element
             =STATE_MAPCENT          Centroidal value to element
             =STATE_MAPDIFF          Difference to node
             =STATE_MAPGEOM          Geometry weighted average to node
             =STATE_MIDSIDEAVE       Average midside node values
             =STATE_MIDSIDECLAMP     Clamp midside node values
             =VIS_OFF                Turn parameter off
             =VIS_ON                 Turn parameter on

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify state parameters.

The parameter STATE_MAPELEM selects the type of element mapping from nodes or element nodes to elements. The average, STATE_MAPAVE, minimum, STATE_MAPMIN or STATE_MAPABSMIN, maximum, STATE_MAPMAX or STATE_MAPABSMAX or element centroidal, STATE_MAPCENT contribution may be selected on a component level basis. Note that the use of minimum or maximum for anything other than scalar data should be used with care. The STATE_MAPABSMIN and STATE_MAPABSMAX options test on absolute value but set the actual value. The element centroidal value will generally differ from the element average value for higher order elements only. By default STATE_MAPELEM is set to STATE_MAPAVE.

The parameter STATE_MAPNODE selects the type of node mapping from elements or element nodes to nodes. The average, STATE_MAPAVE, element geometry weighted average, STATE_MAPGEOM, minimum, STATE_MAPMIN or STATE_MAPABSMIN, maximum, STATE_MAPMAX or STATE_MAPABSMAX, or maximum difference, STATE_MAPDIFF element contribution may be selected on a component level basis. Note that the use of minimum or maximum for anything other than scalar data should be used with care. The STATE_MAPABSMIN and STATE_MAPABSMAX options test on absolute value but set the actual value. If STATE_MAPAVE is used then element quantities from adjacent elements are given equal weight when accumulated and averaged at shared nodes. If STATE_MAPGEOM is used the contribution from a given element is weighted by the size of the element. This will produce more accurate results when adjacent elements have significant size differences. By default STATE_MAPNODE is set to STATE_MAPAVE.

The parameter STATE_MAPNONZERO enables mapping of non zero element quantities only to nodes. If disabled all elements connected to a node will contribute element quantities to the node. If enabled any elements connected to a node in which all element quantities are zero will not contribute to the node. By default STATE_MAPNONZERO is set to VIS_OFF.

The parameter STATE_MAPDEFINED enables mapping of defined entities only. If disabled undefined node and element data is assumed to be zero. If enabled undefined node and element data is ignored, ie. only defined nodes and elements are mapped. Specifically, in the case of mapping from element to node, any undefined elements are skipped with the effect of not being attached to any node. In the case of mapping from node to element, any element with an undefined node contribution is skipped. By default STATE_MAPDEFINED is set to VIS_ON.

The parameter STATE_MIDSIDE is used to control the processing midside node values with the function vis_StateMidside. If STATE_MIDSIDE is set to STATE_MIDSIDEAVE then midside node values are set to the average of the corner node values of the edge. If STATE_MIDSIDE is set to STATE_MIDSIDECLAMP then midside node values are clamped to the corner node values of the edge. By default STATE_MIDSIDE is set to STATE_MIDSIDEAVE.

The parameter STATE_SORTHIGHLOW enables sorting from positive to negative in vis_StateSortIdTran. By default STATE_SORTHIGHLOW is set to VIS_OFF.

The parameter STATE_SORTABSVALUE enables sorting of the absolute value of the state quantity in vis_StateSortIdTran. By default STATE_SORTABSVALUE is set to VIS_OFF.

The parameter STATE_SORTELEMNODEAVE enables sorting of the element average of element node quantities in vis_StateSortIdTran. By default STATE_SORTELEMNODEAVE is set to VIS_ON.


Table of Contents , State

NAME

vis_StateSortIdTran - sort entities into an IdTran object

C SPECIFICATION

void vis_StateSortIdTran (vis_State *state,
                          vis_Group *group,
                          vis_IdTran *idtran)

INPUT ARGUMENTS

state        Pointer to State object.
group        Pointer to Group object.
             If NULL, then all entities are assumed.

OUTPUT ARGUMENTS

idtran       Pointer to derived IdTran object of sorted entities.

ERRORS

VIS_ERROR_VALUE is generated if group is not the same entity type as state. VIS_ERROR_OPERATION is generated if the state object does not have a scalar derived type.

DESCRIPTION

Generate a list of entity indices and output in the idtran object. The entities are placed in the idtran object sorted by their scalar derived value in the state object. The previous contents of the idtran object are lost.

By default, for element node states, the average of the element node values is used as the sorting value. Optionally, the individual element node values can be used as the sorting value by setting STATE_SORTELEMNODEAVE off in vis_StateSetParami. If this option is used, then the output IdTran object contains two integers in order for each element node value. The first integer of the pair is the element number and the second integer is the connectivity index (greater than or equal to 1) of the element node. The output IdTran object will contain two times the number of element nodes integers.

By default, the values are sorted from negative to positive. The sorting can be changed from positive to negative by setting STATE_SORTHIGHLOW in vis_StateSetParami. The absolute value can be sorted by setting STATE_SORTABSVALUE in vis_StateSetParami.


Table of Contents , State

NAME

vis_StateSum - sum results data

C SPECIFICATION

void vis_StateSum (vis_State *state,
                   vis_Group *group,
                   Vfloat s[])

void vis_StateSumdv (vis_State *state,
                     vis_Group *group,
                     Vdouble s[])

INPUT ARGUMENTS

state        Pointer to State object.
group        Pointer to Group object of entities.  If NULL then all
             entities are assumed.

OUTPUT ARGUMENTS

s            Array of summed results data

ERRORS

VIS_ERROR_VALUE is generated if group parent entity size and type does not match the parent entity size and type of the state object.

DESCRIPTION

Sum results data, s, for a set of entities specified by an optional input group. The sum is calculated for the current derived quantity.


Table of Contents , State

NAME

vis_StateSetSection - set section number

C SPECIFICATION

void vis_StateSetSection (vis_State *state,
                          Vint section)

INPUT ARGUMENTS

state        Pointer to State object.
section      The section number to select data.
             =0                      Return data for all sections
             =SYS_ELEMSEC_BOT        First section, same as 1
             =SYS_ELEMSEC_TOP        Last section.
             >0                      Return data for specified section
             

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper section is specified.

DESCRIPTION

Set current section. All subsequent queries of the state will return data for the specified section. If the section number is set to 0 then data will be returned for all sections. Setting section to SYS_ELEMSEC_BOT will return the first section for each element and is the same as setting section to 1. Setting section to SYS_ELEMSEC_TOP will return the last section defined for each element. By default the section number is set to 1 These query functions include vis_StateData and vis_StateExtent.

Get the current section as an output argument using

     void vis_StateGetSection (vis_State *state,
                               Vint *section)


Table of Contents , State

NAME

vis_StateSetSystem - set coordinate system state

C SPECIFICATION

void vis_StateSetSystem (vis_State *state,
                         Vint system)

INPUT ARGUMENTS

state        Pointer to State object.
system       The coordinate system state to transform to.
             =STATE_GLOBAL           System state is global
             =STATE_LOCAL            System state is local undeformed.
             =STATE_ROTANG           System state is local deformed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper system is specified.

DESCRIPTION

Specify the coordinate system state of the State object. The coordinate system state is changed by the vis_StateTransform function. By default the coordinate system state is STATE_GLOBAL.

Get the current system as an output argument using

     void vis_StateGetSystem (vis_State *state,
                              Vint *system)


Table of Contents , State

NAME

vis_StateSetSystemType - set coordinate system entity type

C SPECIFICATION

void vis_StateSetSystemType (vis_State *state,
                             Vint systemtype)

INPUT ARGUMENTS

state        Pointer to State object.
systemtype   The coordinate system state to transform to.
             =SYS_ELEM               System entity type is element
             =SYS_NODE               System entity type is node

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper systemtype is specified. VIS_ERROR_OPERATION is generated if a systemtype of SYS_NODE is specified for an element state or a systemtype of SYS_ELEM is specified for a node state.

DESCRIPTION

Specify the coordinate system entity type of the State object. By default the coordinate system entity type is the same as the parent entity type. Note that this is needed in the case of element node state in which the nodal data is in a node based coordinate system.

Get the current systemtype as an output argument using

     void vis_StateGetSystemType (vis_State *state,
                                  Vint *systemtype)


Table of Contents , State

NAME

vis_StateSetComplexMode - set specify/query mode for complex data

C SPECIFICATION

void vis_StateSetComplexMode (vis_State *lcase,
                              Vint complexmode)

INPUT ARGUMENTS

state        Pointer to State object.
complexmode  Complex mode
             =SYS_COMPLEX_REAL           Real
             =SYS_COMPLEX_IMAGINARY      Imaginary
             =SYS_COMPLEX_REALIMAGINARY  Real and imaginary

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper complexmode is specified.

DESCRIPTION

Set complex mode. By default the complex mode is SYS_COMPLEX_REAL.

Get complexmode as an output argument.

     void vis_StateGetComplexMode (const vis_State *lcase,
                                   Vint *complexmode)


Table of Contents , State

NAME

vis_StateGetComplex - query for complex data existence

C SPECIFICATION

void vis_StateGetComplex (vis_State *lcase,
                          Vint *complexflag)

INPUT ARGUMENTS

state        Pointer to State object.

OUTPUT ARGUMENTS

complexflag  Complex data existence flag

DESCRIPTION

Query for complex data. The complexflag will be returned as one if the complex mode set by vis_StateSetComplexMode is ever SYS_COMPLEX_IMAGINARY or SYS_COMPLEX_REALIMAGINARY, otherwise it is returned as zero.


Table of Contents , State

NAME

vis_StateTransform - (parallel) perform coordinate system transformations

C SPECIFICATION

void vis_StateTransform (vis_State *state,
                         Vint system,
                         vis_Group *group)

INPUT ARGUMENTS

state        Pointer to State object.
system       The coordinate system state to transform to.
             =STATE_GLOBAL           Transform from the current coordinate
                                     system to the global coordinate system
             =STATE_LOCAL            Transform from the global system to
                                     the local undeformed coordinate system
             =STATE_ROTANG           Transform from the global system to
                                     the local deformed coordinate system
group        Pointer to Group object.
             If NULL, then all entities are assumed.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if group is not the same entity type as state. VIS_ERROR_NULLOBJECT is generated if the GridFun, IdTran, HashTable or State attribute objects have not been set. VIS_ERROR_OPERATION is generated if the datatype is VIS_ELEMRES. VIS_ERROR_OPERATION is generated if not a node or element state. VIS_ERROR_OPERATION is generated if an element integration point state does not involve a STATE_ROTANG system.

DESCRIPTION

Transform vector, six dof vector, tensor or general tensor data from the current coordinate system state to global coordinates or vice versa. The coordinate system state of the data is set using vis_StateSetSystem. The current coordinate system state may be queried using vis_StateGetSystem. If the current coordinate system state is the same as system, this function returns immediately. If the state data type is scalar this function returns immediately.


Table of Contents , State

NAME

vis_StateTypeDerive - get data type of derived quantity

C SPECIFICATION

void vis_StateTypeDerive (vis_State *state,
                          Vint *typederive)

INPUT ARGUMENTS

state        Pointer to State object.

OUTPUT ARGUMENTS

typederive   Primitive data type of derived quantity

DESCRIPTION

Return the primitive data type of the current derived quantity type. For example, the primtive data type of VIS_VECTOR_MAG is VIS_SCALAR.


Table of Contents , State

NAME

vis_StateWrite - write state to file formats

C SPECIFICATION

void vis_StateWrite (vis_State *state,
                     vis_RProp *rprop,
                     Vint type,
                     const Vchar *path)

INPUT ARGUMENTS

state        Pointer to State object.
rprop        Pointer to RProp object.
type         File type
             =SYS_ASCII              ASCII format
             =SYS_BINARY             Binary format
             =SYS_SDRC_UNIVERSAL     Write to SDRC Universal file
path         File path

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified. SYS_ERROR_FILE is generated if the file can not be opened.

DESCRIPTION

Write the state data to a file. The RProp object is used to provide additional result property information so that the state data may be given proper context in the output file format. It is suggested that the RProp object contain the result type, solution type, analysis type, section number and numeric identifiers. The SYS_ASCII and SYS_BINARY formats are VKI internal formats. Use vis_StateRead to read state data from VKI internal formats.


Table of Contents , State

NAME

vis_StateRead - read state from file formats

C SPECIFICATION

void vis_StateRead (vis_State *state,
                     Vint type,
                     const Vchar *path)

INPUT ARGUMENTS

state        Pointer to State object.
type         File type
             =SYS_ASCII              ASCII format
             =SYS_BINARY             Binary format
path         File path

OUTPUT ARGUMENTS

None

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_FORMAT is generated if the file contents are not correctly formatted.

DESCRIPTION

Read the state data from a file. The SYS_ASCII and SYS_BINARY formats are VKI internal formats. Use vis_StateWrite to write state data to a file format.


Table of Contents

19.9 History Results Manipulation - History

The History module supports the management of solution results data for scalar, vector, six dof vector (translations and rotations), tensor (symmetric tensor) and general tensor fields defined over several solution steps. The results data may be located at nodes, element centroids and element nodes. The History module provides a set of derived quantities for vector and tensor fields which may be automatically calculated. such as vector magnitude for tensor principal values. These derived quantities, such as vector magnitude for tensor principal values, are generally based on the invariants of the vector or tensor. The functions associated with a History object are the following.

Instance a History object using vis_HistoryBegin. Once a History is instanced, the user may specify the precision used to maintain the history data using vis_HistoryPre. By default, history data are held in single precision. Define number of solution steps, number of entities and parent and child entity types using vis_HistoryDef. The function is also used to specify the data type (scalar, vector, etc.) of the solution results data to be maintained by the History object. If the initial number of steps is exceeded, the History module will automatically expand storage to allow for the additional steps.

Complex valued element data may be specified. The real and imaginary parts of a complex value may be specified one at a time or together depending upon the state of the complex mode of History. The user sets the complex mode using vis_HistorySetComplexMode. See section VisTools, Complex Numbers for a description of the general usage of complex valued data in Vistools modules.

Use vis_HistorySetData to enter solution results into a History object at specified solution steps and entity indices. If results data is not specified at a specific solution step and/or entity index it is assumed to be zero. The function vis_HistorySetIndep may be used to set the value of an independent quantity, such as a time value, for each step. Use vis_HistoryClear to clear (set to zero) all results data. Use vis_HistoryEnd to release all memory associated with a History object.

By convention, vector data is assumed to be ordered by (x,y,z) components, six dof vector data by (tx,ty,tz,rx,ry,rz) components, symmetric tensor data by (xx,yy,zz,xy,yz,zx) components, and general tensor data by (xx,xy,xz,yx,yy,yz,zx,zy,zz) components, Use vis_HistoryData to query for results data for some entity subset at a solution step. A History object will automatically return a derived quantity when vis_HistoryData is called by setting a derived quantity with vis_HistorySetDerive. The derived quantities are identical to those supported by the State module.

It is possible that history data may not be defined for all components of a particular result data type such as vector or tensor. For example, only the xx component of a stress tensor may be defined. The History object supports the notion of undefined components using the vis_HistorySetDataStat and vis_HistoryDataStat functions.

The History module contains functions to assist in down sampling large datasets. Use vis_HistorySample to compute a rank for each step number. The rank of a step is the priority of a step in describing the "shape" of the data. A rank of 1 has the lowest priority, a rank of numstp, where numstp is the total number of steps, has the highest priority. The lowest and highest time step numbers have the highest priorities. The rank of a step is computed by determining the worst deviation from linearity of the step data from neighboring step data. To down sample the history data when drawing a graph of all the data, determine the number of data points, num, to be drawn and ignore any history data with a rank lower than numstp - num. Once the ranking has been computed use vis_HistoryGetRank to access the rank of any step. If drawing an interval of the time step numbers use the function vis_HistoryCutoffRank to determine the cutoff rank to be used for the specific time interval of interest.

Table of Contents

19.10 Attribute Objects

A History object uses a GridFun object to access finite element data from the host application. Storing element node results in a History object requires a GridFun object to be set as an attribute object.

Table of Contents

19.11 Function Descriptions

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


Table of Contents , History

NAME

*vis_HistoryBegin - create an instance of an History object

C SPECIFICATION

vis_History *vis_HistoryBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an History object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL.

Destroy an instance of a History object using

     void vis_HistoryEnd (vis_History *history)

Return the current value of a History object error flag using

     Vint vis_HistoryError (vis_History *history)

Make a copy of a History object. The private data from the fromhistory object is copied to the history object. Any previous private data in history is lost.

     void vis_HistoryCopy (vis_History *history,
                           vis_History *fromhistory)


Table of Contents , History

NAME

vis_HistoryPre - specify precision of history data

C SPECIFICATION

void vis_HistoryPre (vis_History *history,
                     Vint pre)

INPUT ARGUMENTS

history      Pointer to History object.
pre          Precision of history data
             =SYS_FLOAT              Single precision
             =SYS_DOUBLE             Double precision

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper pre is specified.

DESCRIPTION

Specify the precision used to maintain history data The function should be called before vis_HistoryDef. By default, history data are held in single precision.


Table of Contents , History

NAME

vis_HistoryClear - clear all results data

C SPECIFICATION

void vis_HistoryClear (vis_History *history)

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Clear all results data to zero.


Table of Contents , History

NAME

vis_HistoryData - query results data for a set of entities

C SPECIFICATION

void vis_HistoryData (vis_History *history,
                      Vint istep,
                      Vint nix,
                      Vint ix[],
                      Vfloat s[])

void vis_HistoryDatadv (vis_History *history,
                        Vint istep,
                        Vint nix,
                        Vint ix[],
                        Vdouble s[])

INPUT ARGUMENTS

history      Pointer to History object.
istep        Solution step
nix          Number of entities to return results
ix           Array of entity indices

OUTPUT ARGUMENTS

s            Array of returned results data

ERRORS

VIS_ERROR_VALUE is generated if an improper istep or ix index is specified.

DESCRIPTION

Get results data, s, at solution step, istep, for a set of entities, ix. The results data is subject to the current derived quantity specified by vis_HistorySetDerive. The results data returned in array s is ordered as results data for entity ix[0] followed by results data for ix[1],...,ix[nix-1]. Use vis_HistorySetData to set results data. Use vis_HistorySetDatadv to set results data in double precision.


Table of Contents , History

NAME

vis_HistoryDataLayPos - get section layer position type

C SPECIFICATION

void vis_HistoryDataLayPos (vis_History *history,
                            Vint nix,
                            Vint ix[],
                            Vint lpos[])

INPUT ARGUMENTS

history      Pointer to History object.
nix          Number of entities to return
ix           Array of entity indices

OUTPUT ARGUMENTS

lpos         Array of returned section layer position types

DESCRIPTION

Get layer position types, lpos, for a set of entities, ix. If no layer position types have been defined for an element, 0 is returned.


Table of Contents , History

NAME

vis_HistoryDataLayers - get section layer number and position

C SPECIFICATION

void vis_HistoryDataLayers (vis_History *history,
                          Vint index,
                          Vint pos[],
                          Vint lay[])

INPUT ARGUMENTS

history      Pointer to History object.
index        Entity index

OUTPUT ARGUMENTS

pos          Section layer positions
             =SYS_LAYERPOSITION_NONE    None, unknown
             =SYS_LAYERPOSITION_BOT     Bottom
             =SYS_LAYERPOSITION_MID     Middle
             =SYS_LAYERPOSITION_TOP     Top
             =SYS_LAYERPOSITION_INTPNT  Integration Point
lay          Section layer numbers

ERRORS

VIS_ERROR_OPERATION is generated if not an element history or history data has been previously set. VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Get layer position and layer number for each section for a specified index. The number of layer positions and layer numbers returned in the pos and lay arguments is equal to the number of sections specified for index using vis_HistorySetDataSect.


Table of Contents , History

NAME

vis_HistoryDataSect - get number of results data sections

C SPECIFICATION

void vis_HistoryDataSect (vis_History *history,
                          Vint nix,
                          Vint ix[],
                          Vint nsec[])

INPUT ARGUMENTS

history      Pointer to History object.
nix          Number of entities to return
ix           Array of entity indices

OUTPUT ARGUMENTS

nsec         Array of returned number of results sections

DESCRIPTION

Get number of results sections, nsec, for a set of entities, ix. If no sections have been defined for an element, 1 is returned.


Table of Contents , History

NAME

vis_HistoryDataMax - get max number of results values and locations

C SPECIFICATION

void vis_HistoryDataMax (vis_History *history,
                         Vint *maxdat,
                         Vint *maxloc,
                         Vint *maxsec)

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

maxdat       Maximum number of data values
maxloc       Maximum number of data locations
maxsec       Maximum number of data sections

DESCRIPTION

Return the maximum number of data values, locations and sections. The maxdat value can be used to allocated memory which is guaranteed to hold the data returned by any call to vis_HistoryData. The maxsec value can be used to determine if any section data has been defined on any element.


Table of Contents , History

NAME

vis_HistoryDataNum - get number of results values and locations

C SPECIFICATION

void vis_HistoryDataNum (vis_History *history,
                         Vint index,
                         Vint *ndat,
                         Vint *nloc,
                         Vint *nsec)

INPUT ARGUMENTS

history      Pointer to History object.
index        Entity index to query

OUTPUT ARGUMENTS

ndat         Total number of data values
nloc         Number of data locations
nsec         Number of data sections

ERRORS

VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Return the number of data values, locations and sections returned by subsequent queries of the history. These query functions include vis_HistoryData. The number of sections, nsec, depends upon the number of sections defined for the element and the current returned section option specified by vis_HistorySetSection. The number of locations, nloc, will be 1 for node and element sections and equal to the number of element nodes for element node sections. The total number of data values, ndat, will be the product of the number of components in the current derived quantity with the number of locations and the number of sections.


Table of Contents , History

NAME

vis_HistoryDataStat - get results data status

C SPECIFICATION

void vis_HistoryDataStat (vis_History *history,
                          Vint index,
                          Vint stat[])

INPUT ARGUMENTS

history      Pointer to History object.
index        Entity index to get results status

OUTPUT ARGUMENTS

stat         Array of returned results data status

ERRORS

VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Get results data status, stat, for entity index. The array, stat will contain a 0 if the data component is not defined and a 1 if it is. By default all data components are defined. Data components can only be specified as undefined by calling vis_HistorySetDataStat. If the history object manages node or element centroid data, the array stat contains 1, 3, 6 or 9 values corresponding to scalar, vector, six dof vector, tensor or general tensor data types. If element node data is managed, stat contains 1, 3, 6 or 9 values for each element node.


Table of Contents , History

NAME

vis_HistoryDataSteps - get results data at all steps

C SPECIFICATION

void vis_HistoryDataSteps (vis_History *history,
                           Vint nix,
                           Vint ix[],
                           Vfloat s[])

void vis_HistoryDataStepsdv (vis_History *history,
                             Vint nix,
                             Vint ix[],
                             Vdouble s[])

INPUT ARGUMENTS

history      Pointer to History object.
nix          Number of entities to return results
ix           Array of entity indices

OUTPUT ARGUMENTS

s            Array of returned results data

ERRORS

VIS_ERROR_VALUE is generated if an improper ix index is specified.

DESCRIPTION

Get results data, s, at all solution steps for a set of entities, ix. The results data is subject to the current derived quantity specified by vis_HistorySetDerive. The results data returned in array s is ordered as results data for entity ix[0] followed by results data for ix[1],...,ix[nix-1] for the first step followed by the entity results for the second step, etc.


Table of Contents , History

NAME

vis_HistoryDef - define parent and child entities and data type

C SPECIFICATION

void vis_HistoryDef (vis_History *history,
                   Vint numstp,
                   Vint nument,
                   Vint parenttype,
                   Vint childtype,
                   Vint datatype)

INPUT ARGUMENTS

history      Pointer to History object.
numstp       Number of solution steps
nument       Number of parent entities
parenttype   Type of parent entity
             =SYS_ELEM     Element type
             =SYS_NODE     Node type
childtype    Type of child entity.
             =SYS_NONE     No child entity
             =SYS_NODE     Node type
datatype     Data type
             =VIS_SCALAR             Scalar data
             =VIS_VECTOR             Vector data
             =VIS_SIXDOF             Six dof vector data
             =VIS_TENSOR             Symmetric tensor data
             =VIS_GENERALTENSOR      General Tensor data
             =VIS_ELEMRES            Element Result data

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if numstp or nument is non positive. VIS_ERROR_ENUM is generated if an improper parenttype, childtype or datatype is specified.

DESCRIPTION

Specify the number of solution steps and parent entities, the type of parent and child entities and data type. A child entity type may be specified if element node results are to be managed. If purely node or element centroid results data are to be managed, then childtype should be set to SYS_NONE. This function call initializes all data to zero.

Inquire of defined numstp, nument, parenttype, childtype and datatype as output arguments using

     void vis_HistoryInq (const vis_History *history,
                          Vint *numstp,
                          Vint *nument,
                          Vint *parenttype,
                          Vint *childtype,
                          Vint *datatype)


Table of Contents , History

NAME

vis_HistoryExtent - minimum and maximum values

C SPECIFICATION

void vis_HistoryExtent (vis_State *state,
                        Vfloat extent[])

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

extent       Minimum and maximum values of results data

DESCRIPTION

Compute minimum and maximum values of history data for all steps.


Table of Contents , History

NAME

vis_HistoryIndep - get independent variable at step

C SPECIFICATION

void vis_HistoryIndep (vis_History *history,
                       Vint istep,
                       Vfloat *t)

void vis_HistoryIndepdv (vis_History *history,
                         Vint istep,
                         Vdouble *t)

INPUT ARGUMENTS

history      Pointer to History object.
istep        Solution step

OUTPUT ARGUMENTS

t            Independent variable.

ERRORS

VIS_ERROR_VALUE is generated if an improper istep is specified.

DESCRIPTION

Get value of independent variable at step istep.


Table of Contents , History

NAME

vis_HistoryIndepSteps - get independent variables at all steps

C SPECIFICATION

void vis_HistoryIndepSteps (vis_History *history,
                            Vfloat t[])

void vis_HistoryIndepStepsdv (vis_History *history,
                              Vdouble t[])

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

t            Array of independent variables at all steps

DESCRIPTION

Get values of independent variable at all steps.


Table of Contents , History

NAME

vis_HistoryNumDerive - get number of data components

C SPECIFICATION

void vis_HistoryNumDerive (vis_History *history,
                           Vint *ncmp)

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

ncmp         Number of components in current derived quantity type

DESCRIPTION

Return the number of components in the current derived quantity type.


Table of Contents , History

NAME

vis_HistoryNumIndices - get number of indices

C SPECIFICATION

void vis_HistoryNumIndices (vis_History *history,
                            Vint *nument)

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

nument       Number of parent entities

DESCRIPTION

Return the number of parent entities. Query for parent entity indices using vis_HistoryIndices.


Table of Contents , History

NAME

vis_HistoryGetIndex - get an index number

C SPECIFICATION

void vis_HistoryGetIndex (vis_History *history,
                          Vint in,
                          Vint *index)

INPUT ARGUMENTS

history      Pointer to History object.
in           In-th index to return 1 <= in <= nument

OUTPUT ARGUMENTS

index        Index

ERRORS

VIS_ERROR_VALUE is generated if an improper in is specified.

DESCRIPTION

Return the inth index.


Table of Contents , History

NAME

vis_HistoryIndices - get index numbers

C SPECIFICATION

void vis_HistoryIndices (vis_History *history,
                         Vint *nument,
                         Vint indices[])

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

nument       Number of parent entities
indices      Array of indices

DESCRIPTION

Return the number of parent entities and all indices.


Table of Contents , History

NAME

vis_HistoryNumSteps - get number of steps

C SPECIFICATION

void vis_HistoryNumSteps (vis_History *history,
                          Vint *numstp)

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

numstp       Number of solution steps

DESCRIPTION

Return the number of solution steps. Query for solution step numbers using vis_HistorySteps.


Table of Contents , History

NAME

vis_HistoryGetStep - get a step number

C SPECIFICATION

void vis_HistoryGetStep (vis_History *history,
                         Vint in,
                         Vint *istep)

INPUT ARGUMENTS

history      Pointer to History object.
in           In-th step number to return 1 <= in <= numstp

OUTPUT ARGUMENTS

istep        Step number

ERRORS

VIS_ERROR_VALUE is generated if an improper in is specified.

DESCRIPTION

Return the inth step number.


Table of Contents , History

NAME

vis_HistorySteps - get step numbers

C SPECIFICATION

void vis_HistorySteps (vis_History *history,
                       Vint *numstp,
                       Vint isteps[])

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

nument       Number of parent entities
isteps       Array of solution step numbers.

DESCRIPTION

Return the number of solution steps and all step numbers.


Table of Contents , History

NAME

vis_HistorySample - compute down sample ranking

C SPECIFICATION

void vis_HistorySample (vis_History *history)

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_MEMORY is generated if a memory allocation failure occurs.

DESCRIPTION

Compute down sampling rank for each step. Use vis_HistoryGetRank to query the rank of a step. Use vis_HistoryCutoffRank to determine the cutoff rank to retain a given number of step sample for a given step number interval.


Table of Contents , History

NAME

vis_HistoryGetRank - get step rank

C SPECIFICATION

void vis_HistoryGetRank (vis_History *history,
                         Vint istep,
                         Vint *rank)

INPUT ARGUMENTS

history      Pointer to History object.
istep        Step number

OUTPUT ARGUMENTS

rank         Step rank

ERRORS

VIS_ERROR_VALUE is generated if an improper istep is specified.

DESCRIPTION

Return the rank of istep step number.


Table of Contents , History

NAME

vis_HistoryCutoffRank - determine cutoff rank for step interval

C SPECIFICATION

void vis_HistoryCutoffRank (vis_History *history,
                            Vint istep1,
                            Vint istep2,
                            Vint num,
                            Vint *cutoffrank)

INPUT ARGUMENTS

history      Pointer to History object.
istep1       Starting step number
istep2       Ending step number
num          Number of step samples to retain

OUTPUT ARGUMENTS

cutoffrank   Cutoff rank

ERRORS

VIS_ERROR_VALUE is generated if an improper istep1 or istep2 is specified.

DESCRIPTION

Return the cutoff rank to retain num step samples in the step number interval istep1 to istep2.


Table of Contents , History

NAME

vis_HistorySetData - set results data

C SPECIFICATION

void vis_HistorySetData (vis_History *history,
                         Vint istep,
                         Vint index,
                         Vfloat s[])

void vis_HistorySetDatadv (vis_History *history,
                           Vint istep,
                           Vint index,
                           Vdouble s[])

INPUT ARGUMENTS

history      Pointer to History object.
istep        Solution step
index        Entity index to set results data
s            Array of results data to be set at entity index

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper istep or index is specified. VIS_ERROR_NULLOBJECT is generated if a GridFun attribute object has not been set and the history manages element node results data. VIS_ERROR_OPERATION is generated if the history manages element node results data and the GridFun attribute object returns a total number of entities which does not match the number of entities declared in vis_HistoryDef.

DESCRIPTION

Set results data, s, at a solution step for a specified index. Use vis_HistoryData to retrieve data. Use vis_HistoryDatadv to retrieve data in double precision. If the history object manages node or element centroid data, the array s contains 1, 3, 6 or 9 values corresponding to scalar, vector, six dof vector, tensor or general tensor data types. If element node data is managed, s contains 1, 3, 6 or 9 values for each element node.


Table of Contents , History

NAME

vis_HistorySetDataLayPos - set section layer position type

C SPECIFICATION

void vis_HistorySetDataLayPos (vis_History *history,
                               Vint index,
                               Vint lpos)

INPUT ARGUMENTS

history      Pointer to History object.
index        Entity index to set number of results sections

OUTPUT ARGUMENTS

lpos         Section layer position type
             =SYS_LAYERPOSITION_NONE    None
             =SYS_LAYERPOSITION_MID     Middle
             =SYS_LAYERPOSITION_BOTTOP  Bottom and top
             =SYS_LAYERPOSITION_BOTTOPMID  Bottom, middle and top

ERRORS

VIS_ERROR_OPERATION is generated if not an element history or history data has been previously set. VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Set layer position type, lpos, for a specified index. Layer position types can only be specified for element or element node histories. This value does not affect the operation of the History object, it is used for query only. Use vis_HistoryDataLayPos to retrieve the layer position type.


Table of Contents , History

NAME

vis_HistorySetDataLayers - set section layer number and position

C SPECIFICATION

void vis_HistorySetDataLayers (vis_History *history,
                               Vint index,
                               Vint pos[],
                               Vint lay[])

INPUT ARGUMENTS

history      Pointer to History object.
index        Entity index
pos          Section layer position type
             =SYS_LAYERPOSITION_NONE    None, unknown
             =SYS_LAYERPOSITION_BOT     Bottom
             =SYS_LAYERPOSITION_MID     Middle
             =SYS_LAYERPOSITION_TOP     Top
             =SYS_LAYERPOSITION_INTPNT  Integration Point
lay          Section layer numbers

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if not an element history or history data has been previously set. VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Set layer position and layer number for each section for a specified index. The number of layer positions and layer numbers in the pos and lay arguments is equal to the number of sections specified for index using vis_HistorySetDataSect. Layer position types can only be specified for element or element node histories. This value does not affect the operation of the History object, it is used for query only. Use vis_HistoryDataLayers to retrieve the layer number and position.


Table of Contents , History

NAME

vis_HistorySetDataSect - set number of results data sections

C SPECIFICATION

void vis_HistorySetDataSect (vis_History *history,
                             Vint index,
                             Vint nsec)

INPUT ARGUMENTS

history      Pointer to History object.
index        Entity index to set number of results sections

OUTPUT ARGUMENTS

nsec         Number of results sections

ERRORS

VIS_ERROR_OPERATION is generated if not an element history or history data has been previously set. VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Set number of results sections, nsec, for a specified index. Section results may only be specified for element or element node histories. Use vis_HistoryDataSect to retrieve the number of sections.


Table of Contents , History

NAME

vis_HistorySetDataStat - set solution results data status

C SPECIFICATION

void vis_HistorySetDataStat (vis_History *history,
                             Vint index,
                             Vint stat[])

INPUT ARGUMENTS

history      Pointer to History object.
index        Entity index to get results status
stat         Array of returned results data status

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Set results data status, stat, for entity index. The array, stat will contain a 0 if the data component is not defined and a 1 if it is. By default all data components are defined. This function may only be called after the data for index has been set using vis_HistorySetData or vis_HistorySetDatadv. If the history object manages node or element centroid data, the array stat contains 1, 3, 6 or 9 values corresponding to scalar, vector, six dof vector, tensor or general tensor data types. If element node data is managed, stat contains 1, 3, 6 or 9 values for each element node.


Table of Contents , History

NAME

vis_HistorySetDerive - set derived quantity

C SPECIFICATION

void vis_HistorySetDerive (vis_History *history,
                           Vint derive)

INPUT ARGUMENTS

history      Pointer to History object.
derive       Type of derived quantity, same as vis_StateSetDerive

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper derived quantity derive is specified.

DESCRIPTION

Set current derived quantity type. All subsequent queries will return the specified derived quantity. These query functions include vis_HistoryData and vis_HistoryExtent. Use vis_HistoryNumDerive to return the number of components in the current derived quantity type.

Inquire of set derive as an output argument using

     void vis_HistoryGetDerive (const vis_History *history,
                                Vint *derive)


Table of Contents , History

NAME

vis_HistorySetEngineeringStrain - set engineering strain flag

C SPECIFICATION

void vis_HistorySetEngineeringStrain (vis_History *history,
                                      Vint flag)

INPUT ARGUMENTS

history      Pointer to History object.
flag         Engineering strain flag
             =SYS_OFF                Tensor strain
             =SYS_ON                 Engineering strain

OUTPUT ARGUMENTS

None

DESCRIPTION

Set engineering strain interpretation of tensor data type. If this flag is enabled then the shear (off diagonal) components of a tensor data type, as set by vis_HistoryDef, are assumed to be twice the standard tensor values. The Max Shear derived value is also returned as twice the standard tensor value. By default the engineering strain flag is SYS_OFF.

Inquire of set flag as an output argument using

     void vis_HistoryGetEngineeringStrain (const vis_History *history,
                                           Vint *flag)


Table of Contents , History

NAME

vis_HistorySetIndep - set independent variable

C SPECIFICATION

void vis_HistorySetIndep (vis_History *history,
                          Vint istep,
                          Vfloat t)

void vis_HistorySetIndepdv (vis_History *history,
                            Vint istep,
                            Vdouble t)

INPUT ARGUMENTS

history      Pointer to History object.
istep        Solution step
t            Value of independent variable

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper istep is specified.

DESCRIPTION

Set value of independent variable at istep. Set the name of the independent variable using vis_HistorySetIndepName.


Table of Contents , History

NAME

vis_HistorySetObject - set pointers to attribute objects

C SPECIFICATION

void vis_HistorySetObject (vis_History *history,
                           Vint objecttype,
                           Vobject *object)

INPUT ARGUMENTS

history      Pointer to History object.
objecttype   The name of the object type to be set.
             =VIS_GRIDFUN            GridFun object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. If a GridFun attribute object is set then all finite element topology, connectivity, node coordinate and node and element association queries will be made through the GridFun interface. To deactivate the GridFun interface, set a NULL GridFun object pointer. A GridFun attribute object is required to store element node results data.

Get object as an output argument using

     void vis_HistoryGetObject (vis_History *history,
                                Vint objecttype,
                                Vobject **object)


Table of Contents , History

NAME

vis_HistorySetIndepName - set independent variable name

C SPECIFICATION

void vis_HistorySetIndepName (vis_History *history,
                              Vchar *name);

INPUT ARGUMENTS

history      Pointer to History object.
name         Name string

OUTPUT ARGUMENTS

None

DESCRIPTION

Set a name string. The name string can contain up to 81 characters including the terminating NULL. If the name is not specified it is returned as a single NULL character using vis_HistoryGetIndepName.

Get the current name as an output argument using

     void vis_HistoryGetIndepName (vis_History *history,
                                   Vint name[])


Table of Contents , History

NAME

vis_HistorySetSection - set section number

C SPECIFICATION

void vis_HistorySetSection (vis_History *history,
                            Vint section)

INPUT ARGUMENTS

history      Pointer to History object.
section      The section number to select data.
             =0                      Return data for all sections
             >0                      Return data for specified section
             =SYS_ELEMSEC_BOT        Return data for bottom section
             =SYS_ELEMSEC_TOP        Return data for top section

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper section is specified.

DESCRIPTION

Set current section. All subsequent queries of the history will return data for the specified section. If the section number is set to 0 then data will be returned for all sections. By default the section number is set to 1 (bottom section). If the section is set to SYS_ELEMSEC_BOT, it is reset to 1 internally. These query functions include vis_HistoryData.

Get the current section as an output argument using

     void vis_HistoryGetSection (vis_History *history,
                                 Vint *section)


Table of Contents , History

NAME

vis_HistorySetSystem - set coordinate system state

C SPECIFICATION

void vis_HistorySetSystem (vis_History *history,
                           Vint system)

INPUT ARGUMENTS

history      Pointer to History object.
system       The coordinate system state
             =HISTORY_GLOBAL         System state is global
             =HISTORY_LOCAL          System state is local.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper system is specified.

DESCRIPTION

Specify the initial coordinate system state of the History object. By default the coordinate system state is HISTORY_GLOBAL.

Get the current system as an output argument using

     void vis_HistoryGetSystem (vis_History *history,
                                Vint *system)


Table of Contents , History

NAME

vis_HistorySetComplexMode - set specify/query mode for complex data

C SPECIFICATION

void vis_HistorySetComplexMode (vis_History *lcase,
                                Vint complexmode)

INPUT ARGUMENTS

history      Pointer to History object.
complexmode  Complex mode
             =SYS_COMPLEX_REAL           Real
             =SYS_COMPLEX_IMAGINARY      Imaginary
             =SYS_COMPLEX_REALIMAGINARY  Real and imaginary

OUTPUT ARGUMENTS

None

DESCRIPTION

Set complex mode. By default the complex mode is SYS_COMPLEX_REAL.

Get complexmode as an output argument.

     void vis_HistoryGetComplexMode (const vis_History *lcase,
                                     Vint *complexmode)


Table of Contents , History

NAME

vis_HistoryGetComplex - query for complex data existence

C SPECIFICATION

void vis_HistoryGetComplex (vis_History *lcase,
                            Vint *complexflag)

INPUT ARGUMENTS

history      Pointer to History object.

OUTPUT ARGUMENTS

complexflag  Complex data existence flag

DESCRIPTION

Query for complex data. The complexflag will be returned as one if the complex mode set by vis_HistorySetComplexMode is ever SYS_COMPLEX_IMAGINARY or SYS_COMPLEX_REALIMAGINARY, otherwise it is returned as zero.


Table of Contents

19.12 System Degree of Freedom Data - RedMat

The RedMat module supports the management of matrix solution results data for system degrees of freedom. A typical use of RedMat is to store superelement stiffness and mass matrices. RedMat may also contain the sparse assembled matrices of the full system. The functions associated with a RedMat object are the following.

Instance a RedMat object using vis_RedMatBegin. Once a RedMat is instanced, the user may specify the precision used to maintain the matrix data using vis_RedMatPre. By default, matrix data is held in double precision. Use vis_RedMatDef to set the rank of the matrix and the data type. Possible data types include diagonal matrix, symmetric matrix, unsymmetric matrix and vector. For data types of diagonal matrix and vector the number of rows is one and the number of columns is equal to the rank. For symmetric and unsymmetric matrices the number of rows and columns is equal to the rank. By default the symmetric and unsymmetric matrices are assumed to be full. Sparse matrices may be defined by specifying the number of columns associated with each row with vis_RedMatSetDataSize.

Complex valued element data may be specified. The real and imaginary parts of a complex value may be specified one at a time or together depending upon the state of the complex mode of RedMat. The user sets the complex mode using vis_RedMatSetComplexMode. See section VisTools, Complex Numbers for a description of the general usage of complex valued data in Vistools modules.

Use vis_RedMatSetData to set value at a specific row and column. Use vis_RedMatData to get value at a specific row and column. Use vis_RedMatSetDof to set the entity index and degree of freedom type associated with each system degree of freedom. If the matrix is sparse, then vis_RedMatSetData must set, for each row, the column data in monotonic column index order. Use vis_RedMatDataCols to get the column indicies for each row.

Table of Contents

19.13 Function Descriptions

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


Table of Contents , RedMat

NAME

*vis_RedMatBegin - create an instance of an RedMat object

C SPECIFICATION

vis_RedMat *vis_RedMatBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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

Destroy an instance of a RedMat object using

     void vis_RedMatEnd (vis_RedMat *redmat)

Return the current value of a RedMat object error flag using

     Vint vis_RedMatError (vis_RedMat *redmat)


Table of Contents , RedMat

NAME

vis_RedMatPre - specify precision of redmat data

C SPECIFICATION

void vis_RedMatPre (vis_RedMat *redmat,
                    Vint pre)

INPUT ARGUMENTS

redmat       Pointer to RedMat object.
pre          Precision of redmat data
             =SYS_FLOAT              Single precision
             =SYS_DOUBLE             Double precision

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper pre is specified.

DESCRIPTION

Specify the precision used to maintain redmat data All previously defined data is cleared by this function. The function should be called before vis_RedMatDef. By default, redmat data are held in double precision. See section DevTools, Floating Point Precision for a description of precision types.


Table of Contents , RedMat

NAME

vis_RedMatDef - define number of freedoms and data type.

C SPECIFICATION

void vis_RedMatDef (vis_RedMat *redmat,
                    Vint ndofs,
                    Vint type)

INPUT ARGUMENTS

redmat       Pointer to RedMat object.
ndofs        Rank or number of degrees of freedom.
type         Data type
             =SYS_VECTOR             Vector
             =SYS_MATRIX_DIAG        Diagonal matrix
             =SYS_MATRIX_SYMM        Symmetric matrix
             =SYS_MATRIX_USYMM       Unsymmetric matrix

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper ndofs is specified. VIS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Specify the number of degrees of freedom and the data type.

Inquire of defined ndofs and type as output arguments using

     void vis_RedMatInq (const vis_RedMat *redmat,
                         Vint *ndofs,
                         Vint *type)


Table of Contents , RedMat

NAME

vis_RedMatNum - inquire number of matrix entries

C SPECIFICATION

void vis_RedMatNum (vis_RedMat *redmat,
                    Vlong *nent,
                    Vint *nval)

INPUT ARGUMENTS

redmat       Pointer to RedMat object.

OUTPUT ARGUMENTS

nent         Number of vector/matrix entries
nval         Number of values per entry

DESCRIPTION

Inquire of the number of entries in the matrix and the number of values, nval, per entry. For real data the number of values is 1, for complex data the number of values is 2.


Table of Contents , RedMat

NAME

vis_RedMatSparse - inquire sparsity of matrix entries

C SPECIFICATION

void vis_RedMatSparse (vis_RedMat *redmat,
                       Vint *sparse)

INPUT ARGUMENTS

redmat       Pointer to RedMat object.

OUTPUT ARGUMENTS

sparse       Sparsity flag.

DESCRIPTION

Inquire the sparsity of the matrix. If the data type is symmetric or unsymmetric matrix and is sparse then sparse is returned as 1, else it is returned as 0.


Table of Contents , RedMat

NAME

vis_RedMatData - get results data at degree of freedom

C SPECIFICATION

void vis_RedMatData (vis_RedMat *redmat,
                     Vint idof,
                     Vint jdof,
                     Vfloat v[])

void vis_RedMatDatadv (vis_RedMat *redmat,
                       Vint idof,
                       Vint jdof,
                       Vdouble v[])

INPUT ARGUMENTS

redmat       Pointer to RedMat object.
idof         Row Dof index
jdof         Column Dof index

OUTPUT ARGUMENTS

v            Returned results data

ERRORS

VIS_ERROR_VALUE is generated if an improper i or j are specified.

DESCRIPTION

Get results data, v, for matrix entry at row i and column j. Use vis_RedMatSetData to set results data. Use vis_RedMatSetDatadv to set results data in double precision. Note that for complex data 2 values are returned in v.


Table of Contents , RedMat

NAME

vis_RedMatSetData - set results data at degree of freedom

C SPECIFICATION

void vis_RedMatSetData (vis_RedMat *redmat,
                        Vint idof,
                        Vint jdof,
                        Vfloat v[])

void vis_RedMatSetDatadv (vis_RedMat *redmat,
                          Vint idof,
                          Vint jdof,
                          Vdouble v[])

INPUT ARGUMENTS

redmat       Pointer to RedMat object.
idof         Row Dof index
jdof         Column Dof index
v            Results data to set

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper i or j are specified.

DESCRIPTION

Set results data, v, for matrix entry at row i and column j. Use vis_RedMatData to get results data. Use vis_RedMatDatadv to get results data in double precision. Note that for complex data 2 values are set from v. If the matrix is sparse, then for each row, idof, the results values must be set for each column index, jdof, in monotonically increasing column index order.


Table of Contents , RedMat

NAME

vis_RedMatSetDataSize - set number of columns per row

C SPECIFICATION

void vis_RedMatSetDataSize (vis_RedMat *redmat,
                            Vint idof,
                            Vint ncols)

INPUT ARGUMENTS

redmat       Pointer to RedMat object.
idof         Row Dof index
ncols        Number of columns at row

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper idof is specified.

DESCRIPTION

Set number of columns for row, idof. By default the number of rows is equal to idof for symmetric matrices and matrix rank, ndofs if an unsymmetric matrix. Use this to define sparse matrices.

Get ncols as an output argument using

     void vis_RedMatGetDataSize (vis_RedMat *redmat,
                                 Vint idof,
                                 Vint *ncols)


Table of Contents , RedMat

NAME

vis_RedMatDataCols - get column indicies per row

C SPECIFICATION

void vis_RedMatDataCols (vis_RedMat *redmat,
                         Vint idof,
                         Vint *ncols,
                         Vint icols[]),

INPUT ARGUMENTS

redmat       Pointer to RedMat object.
idof         Row Dof index

OUTPUT ARGUMENTS

ncols        Number of columns at row
icols        Column indicies at row.

ERRORS

VIS_ERROR_VALUE is generated if an improper idof is specified.

DESCRIPTION

Get the number of columns, ncols defined at row idof and the column indicies, icols.


Table of Contents , RedMat

NAME

vis_RedMatSetDof - set entity index and degree of freedom type

C SPECIFICATION

void vis_RedMatSetDof (vis_RedMat *redmat,
                       Vint dof,
                       Vint index,
                       Vint doftag)

INPUT ARGUMENTS

redmat       Pointer to RedMat object.
dof          Dof index
index        Entity index
doftag       Degree of freedom type.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an improper dof is specified.

DESCRIPTION

Set entity index, index, and degree of freedom type, doftag for system degree of freedom dof.

Get the index and doftag as output arguments using

     void vis_RedMatGetDof (vis_RedMat *redmat,
                            Vint dof,
                            Vint *index,
                            Vint *doftag)


Table of Contents , RedMat

NAME

vis_RedMatSetComplexMode - set specify/query mode for complex data

C SPECIFICATION

void vis_RedMatSetComplexMode (vis_RedMat *lcase,
                               Vint complexmode)

INPUT ARGUMENTS

redmat       Pointer to RedMat object.
complexmode  Complex mode
             =SYS_COMPLEX_REAL           Real
             =SYS_COMPLEX_IMAGINARY      Imaginary
             =SYS_COMPLEX_REALIMAGINARY  Real and imaginary

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper complexmode is specified.

DESCRIPTION

Set complex mode. By default the complex mode is SYS_COMPLEX_REAL.

Get complexmode as an output argument.

     void vis_RedMatGetComplexMode (const vis_RedMat *lcase,
                                    Vint *complexmode)


Table of Contents , RedMat

NAME

vis_RedMatGetComplex - query for complex data existence

C SPECIFICATION

void vis_RedMatGetComplex (vis_RedMat *lcase,
                           Vint *complexflag)

INPUT ARGUMENTS

redmat       Pointer to RedMat object.

OUTPUT ARGUMENTS

complexflag  Complex data existence flag

DESCRIPTION

Query for complex data. The complexflag will be returned as one if the complex mode set by vis_RedMatSetComplexMode is ever SYS_COMPLEX_IMAGINARY or SYS_COMPLEX_REALIMAGINARY, otherwise it is returned as zero.


Table of Contents

19.14 Results Compression - ZState

The ZState module supports the lossy compression of solution results data which can be held in a State object. The functions associated with a ZState object are the following.

Instance a ZState object using vis_ZStateBegin. Once a ZState is instanced, the user may specify the precision Define parent and child entity types and parent size using vis_ZStateDef. Use vis_ZStateEnd to release all memory associated with a ZState object.

Table of Contents

19.15 Attribute Objects

A ZState object uses a GridFun object to access finite element data from the host application. This attribute object is required for compression of all data types.

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

Coords
ElemCon
ElemCnn
ElemNode
ElemNum
ElemAssoc
NodeAssoc
Number
Topology

Table of Contents

19.16 Function Descriptions

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


Table of Contents , ZState

NAME

*vis_ZStateBegin - create an instance of an ZState object

C SPECIFICATION

vis_ZState *vis_ZStateBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an ZState object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL.

Destroy an instance of a ZState object using

     void vis_ZStateEnd (vis_ZState *zstate)

Return the current value of a ZState object error flag using

     Vint vis_ZStateError (vis_ZState *zstate)


Table of Contents , ZState

NAME

vis_ZStateDef - define parent and child entities

C SPECIFICATION

void vis_ZStateDef (vis_ZState *zstate,
                    Vint nument,
                    Vint parenttype,
                    Vint childtype)

INPUT ARGUMENTS

zstate       Pointer to ZState object.
nument       Number of parent entities
parenttype   Type of parent entity
             =SYS_ELEM     Element type
             =SYS_NODE     Node type
childtype    Type of child entity.
             =SYS_NONE     No child entity
             =SYS_NODE     Node type

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if nument is non positive. VIS_ERROR_ENUM is generated if an improper parenttype, childtype or datatype is specified.

DESCRIPTION

Specify the number of parent entities, and type of parent and child entities.

     void vis_ZStateInq (const vis_ZState *zstate,
                         Vint *nument,
                         Vint *parenttype,
                         Vint *childtype)


Table of Contents , ZState

NAME

vis_ZStateKernel - form compression kernel

C SPECIFICATION

void vis_ZStateKernel (vis_ZState *zstate,
                       vis_IdTran *idtran)

INPUT ARGUMENTS

zstate       Pointer to ZState object.
idtran       Pointer to IdTran object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Form compression kernel.


Table of Contents , ZState

NAME

vis_ZStateLngKernel - get byte length of kernel

C SPECIFICATION

void vis_ZStateLngKernel (vis_ZState *zstate,
                          Vulong *nbytes)

INPUT ARGUMENTS

zstate       Pointer to ZState object.

OUTPUT ARGUMENTS

nbytes       Number of bytes in compression kernel

DESCRIPTION

Get byte length of kernel.


Table of Contents , ZState

NAME

vis_ZStateLoadKernel - load kernel from memory buffer into ZState

C SPECIFICATION

void vis_ZStateLoadKernel (vis_ZState *zstate,
                           void *buff)

INPUT ARGUMENTS

zstate       Pointer to ZState object.
buff         Input buffer for kernel

OUTPUT ARGUMENTS

None

DESCRIPTION

Read kernel from input buffer, buff.


Table of Contents , ZState

NAME

vis_ZStateSaveKernel - save kernel from ZState into memory buffer

C SPECIFICATION

void vis_ZStateSaveKernel (vis_ZState *zstate,
                           void *buff,
                           Vulong *nbytes)

INPUT ARGUMENTS

zstate       Pointer to ZState object.

OUTPUT ARGUMENTS

buff         Output buffer for kernel
nbytes       Final number of bytes in compression kernel

DESCRIPTION

Write kernel to output buffer, buff. The total memory used is returned in nbytes.


Table of Contents , ZState

NAME

vis_ZStateSetMode - set operation modes

C SPECIFICATION

void vis_ZStateSetMode (vis_ZState *zstate,
                        Vint type,
                        Vint value)

INPUT ARGUMENTS

zstate       Pointer to ZState object.
type         Type of mode
             =ZSTATE_SPATIALCONTINUITY  Toggle spatial continuity
value        Mode value
             =SYS_ON                    Enable
             =SYS_OFF                   Disable

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Enable or disable the assumption of spatial continuity. If a field is not spatially continuous, then no attempt will be made to use spatial compression. By default ZSTATE_SPATIALCONTINUITY if on.


Table of Contents , ZState

NAME

vis_ZStateSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_ZStateSetObject (vis_ZState *zstate,
                          Vint objecttype,
                          Vobject *object)

INPUT ARGUMENTS

zstate       Pointer to ZState object.
objecttype   The name of the object type to be set.
             =VIS_GRIDFUN            GridFun object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. If a GridFun attribute object is set then all finite element topology, connectivity, node coordinate and node and element association queries will be made through the GridFun interface. To deactivate the GridFun interface, set a NULL GridFun object pointer.

Get object as an output argument using

     void vis_ZStateGetObject (vis_ZState *zstate,
                               Vint objecttype,
                               Vobject **object)


Table of Contents , ZState

NAME

vis_ZStateState - process input state

C SPECIFICATION

void vis_ZStateState (vis_ZState *zstate,
                      vis_State *state)

INPUT ARGUMENTS

zstate       Pointer to ZState object.
state        Pointer to State object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Process state data.


Table of Contents , ZState

NAME

vis_ZStateLngState - get byte length of compressed state

C SPECIFICATION

void vis_ZStateLngState (vis_ZState *zstate,
                         Vulong *nbytes)

INPUT ARGUMENTS

zstate       Pointer to ZState object.

OUTPUT ARGUMENTS

nbytes       Number of bytes in compressed state

DESCRIPTION

Get byte length of compressed state.


Table of Contents , ZState

NAME

vis_ZStateLoadState - load compressed data from memory buffer

C SPECIFICATION

void vis_ZStateLoadState (vis_ZState *zstate,
                          void *buff,
                          vis_State *state)

INPUT ARGUMENTS

zstate       Pointer to ZState object.
buff         Input buffer for compressed data

OUTPUT ARGUMENTS

state        Pointer to State object.

DESCRIPTION

Load compressed data into state object.


Table of Contents , ZState

NAME

vis_ZStateSaveState - save compressed data into memory buffer

C SPECIFICATION

void vis_ZStateSaveState (vis_ZState *zstate,
                          vis_State *state,
                          void *buff,
                          Vulong *nbytes)

INPUT ARGUMENTS

zstate       Pointer to ZState object.
state        Pointer to State object.

OUTPUT ARGUMENTS

buff         Output buffer for compressed data
nbytes       Final number of bytes in compressed state

DESCRIPTION

Save compressed data from state to output buffer, buff. The total memory used is returned in nbytes.