4. 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.

4.1. 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.

Begin and end an instance of an object, return object error flag
- vis_ElemDatBegin() - create an instance of a ElemDat object
- vis_ElemDatEnd() - destroy an instance of a ElemDat object
- vis_ElemDatError() - return ElemDat object error flag
- vis_ElemDatPre() - specify precision of element data
Set, manipulate and compute data
- vis_ElemDatClear() - clear any set element data
- vis_ElemDatData() - get element data for an element
- vis_ElemDatDataStat() - query data status
- vis_ElemDatDef() - define parent and child entities
- vis_ElemDatInq() - inquire parent and child entities
- vis_ElemDatIdTran() - derive list of element entities
- vis_ElemDatNormal() - compute accurate element face normals
- vis_ElemDatSetData() - set element face or edge data
- vis_ElemDatSetObject() - set pointers to attribute objects.
- vis_ElemDatGetObject() - get pointers to attribute objects.
- vis_ElemDatSetParamf() - set floating point parameters
- vis_ElemDatSetParami() - set integer parameters
- vis_ElemDatSetComplexMode() - set specify/query mode for complex data
- vis_ElemDatGetComplexMode() - get specify/query mode for complex data
- vis_ElemDatGetComplex() - query for complex data existence

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.

4.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

4.3. Function Descriptions

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

vis_ElemDat *vis_ElemDatBegin(void)

create an instance of an ElemDat object

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)

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

void vis_ElemDatEnd(vis_ElemDat *p)

destroy an instance of an ElemDat object

See vis_ElemDatBegin()

Vint vis_ElemDatError(vis_ElemDat *p)

return the current value of an ElemDat object error flag

See vis_ElemDatBegin()

void vis_ElemDatPre(vis_ElemDat *p, Vint pre)

specify precision of element data

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.

Errors: VIS_ERROR_ENUM is generated if an improper pre is specified.

Parameters:

p – Pointer to ElemDat object.

pre – Precision of data

x=SYS_FLOAT              Single precision
 =SYS_DOUBLE             Double precision

void vis_ElemDatSetObject(vis_ElemDat *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

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)

Errors: VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

p – Pointer to ElemDat object.
objecttype – The name of the object type to be set.
```
x=VIS_GRIDFUN            GridFun object
```
object – Pointer to the object to be set.

void vis_ElemDatGetObject(vis_ElemDat *p, Vint objecttype, Vobject **object)

get pointers to attribute objects

See vis_ElemDatSetObject()

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

define parent and child entities and data type

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)

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.

Parameters:

p – 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

x=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

void vis_ElemDatInq(const vis_ElemDat *p, Vint *nument, Vint *enttype, Vint *subtype, Vint *datatype)

inquire of defined nument, enttype, subtype and datatype as output arguments

See vis_ElemDatDef()

void vis_ElemDatSetParami(vis_ElemDat *p, Vint ptype, Vint iparam)

set integer parameters

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.

Errors: VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

p – Pointer to ElemDat object.

ptype – Type of parameter to set

x=ELEMDAT_FEATUREBRANCH  Feature branch flag
x=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

void vis_ElemDatSetParamf(vis_ElemDat *p, Vint ptype, Vfloat param)

set floating point parameters

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.

Errors: VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

p – Pointer to ElemDat object.

ptype – Type of parameter to set

x=ELEMDAT_FEATUREANGLE   Feature angle in degrees

param – Specifies the floating value that ptype will be set to.

void vis_ElemDatSetComplexMode(vis_ElemDat *p, Vint complexmode)

set specify/query mode for complex data

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)

Parameters:

p – Pointer to ElemDat object.

complexmode – Complex mode

x=SYS_COMPLEX_REAL           Real
 =SYS_COMPLEX_IMAGINARY      Imaginary
 =SYS_COMPLEX_REALIMAGINARY  Real and imaginary

void vis_ElemDatGetComplexMode(vis_ElemDat *p, Vint *complexmode)

get specify/query mode for complex data

See vis_ElemDatSetComplexMode()

void vis_ElemDatGetComplex(vis_ElemDat *p, Vint *complexflag)

query for complex data existence

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.

Parameters:

p – Pointer to ElemDat object.
complexflag – [out] Complex data existence flag

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

set element face or edge data

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 p 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.

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().

Parameters:

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

void vis_ElemDatSetDatadv(vis_ElemDat *p, Vint id, Vint no, Vdouble s[])

set element face or edge data

See vis_ElemDatSetData()

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

get element data for an element

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.

Parameters:

p – Pointer to ElemDat object.
index – Element index
no – Element face or edge number
s – [out] Array of returned element data

void vis_ElemDatDatadv(const vis_ElemDat *p, Vint id, Vint no, Vdouble s[])

get element data for an element

See vis_ElemDatData()

void vis_ElemDatClear(vis_ElemDat *p)

clear any set element data

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.

Parameters:: p – Pointer to ElemDat object.

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

query data status

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.

Parameters:

p – Pointer to ElemDat object.
index – Element index
no – Element face or edge number
stat – [out] returned results data status

void vis_ElemDatNormal(vis_ElemDat *p, vis_Group *group)

compute accurate element face normals

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().

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.

Parameters:

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

void vis_ElemDatIdTran(vis_ElemDat *p, Vint oper, vis_IdTran *idtran)

derive list of element entities

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.

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.

Parameters:

p – Pointer to ElemDat object.

oper – Operation specified to derive group

x=ELEMDAT_SETDATA        Edges at which data has been set

idtran – [out] Pointer to derived IdTran object of element entities.

4.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.

Begin and end an instance of an object, return object error flag
- vis_StateBegin() - create an instance of a State object
- vis_StateEnd() - destroy an instance of a State object
- vis_StateError() - return State object error flag
- vis_StateCopy() - copy a State
- vis_StatePre() - specify precision of state data
Set, manipulate and query results
- vis_StateClear() - clear all results data
- vis_StateClearData() - clear results data for a single entity
- vis_StateConvertComplex() - convert complex data
- vis_StateConvertStrain() - convert strain data
- vis_StateData() - get results data at a set of entities
- vis_StateDataElem() - get results data at element
- vis_StateDataElemEnt() - get results data at element entities
- vis_StateDataElemRST() - get results data at given natural coordinates
- vis_StateDataMax() - get max number of results values and locations
- vis_StateDataNum() - get number of results values and locations
- vis_StateDataLayPos() - get section layer position type
- vis_StateDataLayers() - get section layer number and position
- vis_StateDataSect() - get number of results data sections
- vis_StateCheckSect() - check if any sections defined
- vis_StateDataStat() - get results data status
- vis_StateDataStatElemEnt() - get element face or edge results data status
- vis_StateDef() - define parent and child entities
- vis_StateInq() - inquire parent and child entities
- vis_StateDeform() - create deformed node vector of coordinates
- vis_StateDemo() - create “demo” node vector displacement results
- vis_StateDerivative() - perform differential operations on a state
- vis_StateDirCos() - get local direction cosine matrix
- vis_StateElemGroup() - derive sets of elements
- vis_StateExtent() - (parallel) minimum and maximum values
- vis_StateExtentLoc() - minimum and maximum values and locations
- vis_StateExtentLocSect() - minimum and maximum values,locations,sections
- vis_StateMap() - map results data to another location
- vis_StateMapElemNode() - map results data to element node location
- vis_StateMidside() - process results data at midside nodes
- vis_StateNodeGroup() - derive sets of nodes
- vis_StateNumDerive() - get number of data components
- vis_StateOperateBinary() - operate on a state as a function of two states
- vis_StateOperateUnary() - operate on a state as a function of one state
- vis_StateSetData() - set results data
- vis_StateSetDataElemEnt() - set element face or edge results data
- vis_StateSetDataEnt() - set results data element faces or edges
- vis_StateSetDataLayPos() - set section layer position type
- vis_StateSetDataLayers() - set section layer number and position
- vis_StateSetDataSect() - set number of results data sections
- vis_StateSetDerive() - set derived quantity type
- vis_StateGetDerive() - get derived quantity type
- vis_StateSetEngineeringStrain() - set engineering strain flag
- vis_StateGetEngineeringStrain() - get engineering strain flag
- vis_StateSetMagnitudePhase() - set magnitude phase flag
- vis_StateGetMagnitudePhase() - get magnitude phase flag
- vis_StateSetGroupParam() - set group derivation parameters
- vis_StateSetHashTable() - set pointers to HashTable objects.
- vis_StateSetObject() - set pointers to attribute objects.
- vis_StateGetObject() - get pointers to attribute objects.
- vis_StateSetParami() - set state parameters
- vis_StateSetSection() - set section number
- vis_StateGetSection() - get current section number
- vis_StateSetSystem() - set coordinate system state
- vis_StateGetSystem() - get coordinate system state
- vis_StateSetSystemType() - set coordinate system entity type
- vis_StateGetSystemType() - get coordinate system entity type
- vis_StateSetComplexMode() - set specify/query mode for complex data
- vis_StateGetComplexMode() - get specify/query mode for complex data
- vis_StateGetComplex() - query for complex data existence
- vis_StateSortIdTran() - sort entities into an IdTran object
- vis_StateSum() - sum results data
- vis_StateTransform() - (parallel) perform coordinate system transformations
- vis_StateTypeDerive() - get data type of derived quantity
- vis_StateWrite() - write state to file formats
- vis_StateRead() - read state from file formats

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.

VIS_VECTOR_MAG, Magnitude
```
v(mag) = sqrt(vx**2 + vy**2 + vz**2)
```

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

VIS_TENSOR_MEAN, Mean
```
t(mean) = 1/3*(txx+tyy+tzz);
```

VIS_TENSOR_VONMISES, Von Mises

t(vonmises) = sqrt(1/2*((txx-tyy)**2 + (tyy-tzz)**2 + (tzz-txx)**2) +
                   3*(txy**2 + tyz**2 + tzx**2))

VIS_TENSOR_VONMISES_E, Von Mises Strain

t(vonmises) = 2./3.*sqrt(1/2*((txx-tyy)**2 + (tyy-tzz)**2 + (tzz-txx)**2) +
                         3*(txy**2 + tyz**2 + tzx**2))

VIS_TENSOR_OCTAHEDRAL, Octahedral

t(octahedral) = sqrt(1/9*((txx-tyy)**2 + (tyy-tzz)**2 + (tzz-txx)**2) +
                     2/3*(txy**2 + tyz**2 + tzx**2))

VIS_TENSOR_MAXSHEAR, Max Shear
```
t(max shear) = 1/2*(tmax - tmin)
```
VIS_TENSOR_EQUDIRECT, Equal direct stress in Max Shear directions
```
t(equ direct) = 1/2*(tmax + tmin)
```

VIS_TENSOR_INTENSITY, Intensity

t(intensity) = MAX((tmax-tmin),(tmid-tmin),(tmax-tmid))

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.

4.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 <ElementCoordinateSystems> 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.

4.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.

4.8. Function Descriptions

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

vis_State *vis_StateBegin(void)

create an instance of a State object

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)

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

void vis_StateEnd(vis_State *p)

destroy an instance of a State object

See vis_StateBegin()

Vint vis_StateError(vis_State *p)

return the current value of a State object error flag

See vis_StateBegin()

void vis_StatePre(vis_State *p, Vint pre)

specify precision of state data

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 Floating Point Precision for a description of precision types.

Errors: VIS_ERROR_ENUM is generated if an improper pre is specified.

Parameters:

p – Pointer to State object.

pre – Precision of state data

x=SYS_FLOAT              Single precision
 =SYS_DOUBLE             Double precision

void vis_StateSetObject(vis_State *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

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 p 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)

Errors: VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

p – Pointer to State object.

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

x=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.

void vis_StateGetObject(vis_State *p, Vint objecttype, Vobject **object)

get pointers to attribute objects

See vis_StateSetObject()

void vis_StateSetHashTable(vis_State *p, Vint type, vsy_HashTable *hashtable)

set pointers to HashTable objects.

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

Errors: VIS_ERROR_OBJECTTYPE is generated if an improper type is specified.

Parameters:

p – Pointer to State object.

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

x=VIS_COORDSYS           CoordSys objects
 =VIS_ELEMDAT            ElemDat objects

hashtable – Pointer to the HashTable to be set.

void vis_StateSetParami(vis_State *p, Vint ptype, Vint iparam)

set state parameters

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.

Errors: VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

p – Pointer to State object.

ptype – Type of state parameter to set

x=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.

x=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

void vis_StateSetComplexMode(vis_State *p, Vint complexmode)

set specify/query mode for complex data

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)

Errors: SYS_ERROR_ENUM is generated if an improper complexmode is specified.

Parameters:

p – Pointer to State object.

complexmode – Complex mode

x=SYS_COMPLEX_REAL           Real
 =SYS_COMPLEX_IMAGINARY      Imaginary
 =SYS_COMPLEX_REALIMAGINARY  Real and imaginary

void vis_StateGetComplexMode(vis_State *p, Vint *complexmode)

get specify/query mode for complex data

See vis_StateSetComplexMode()

void vis_StateGetComplex(vis_State *p, Vint *complexmode)

query for complex data existence

Query for complex data. The complexmode 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.

Parameters:

p – Pointer to State object.
complexmode – [out] Complex data existence flag

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

define parent and child entities and data type

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)

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.

Parameters:

p – 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

x=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

void vis_StateInq(const vis_State *p, Vint *nument, Vint *enttype, Vint *subtype, Vint *datatype)

inquire parent and child entities and data type

See vis_StateDef()

void vis_StateSetEngineeringStrain(vis_State *p, Vint flag)

set engineering strain flag

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)

Parameters:

p – Pointer to State object.

flag – Engineering strain flag

x=SYS_OFF                Tensor strain
 =SYS_ON                 Engineering strain

void vis_StateGetEngineeringStrain(const vis_State *p, Vint *flag)

get engineering strain flag

See vis_StateSetEngineeringStrain()

void vis_StateSetMagnitudePhase(vis_State *p, Vint flag)

set magnitude phase flag

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)

Parameters:

p – Pointer to State object.

flag – Magnitude phase flag

x=SYS_OFF                Tensor strain
 =SYS_ON                 Engineering strain

void vis_StateGetMagnitudePhase(const vis_State *p, Vint *flag)

get magnitude phase flag

See vis_StateSetMagnitudePhase()

void vis_StateClear(vis_State *p)

clear all results data

Clear all results data to zero.

Parameters:: p – Pointer to State object.

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

get results data status

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().

Parameters:

p – Pointer to State object.
nix – Number of entities to return results
ix – Array of entity indices
stat – [out] Array of returned results data status

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

get element face or edge results data status

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

Parameters:

p – Pointer to State object.
index – Entity index
no – Element face or edge number
stat – [out] Returned results data status

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

set results data element faces or edges

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.

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

Parameters:

p – 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

void vis_StateSetDataSect(vis_State *p, Vint index, Vint nsec)

set number of results data sections

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.

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.

Parameters:

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

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

get number of results data sections

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

Parameters:

p – Pointer to State object.
nix – Number of entities to return
ix – Array of entity indices
nsec – [out] Array of returned number of results sections

void vis_StateCheckSect(const vis_State *p, Vint *flag)

check if any sections defined

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.

Parameters:

p – Pointer to State object.
flag – [out] Section data defined.

void vis_StateSetDataLayPos(vis_State *p, Vint index, Vint lpos)

set section layer position type

Set layer position type, laypos, 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.

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.

Parameters:

p – Pointer to State object.
index – Entity index to set number of results sections

lpos – Section layer position type

x=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

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

get section layer position type

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.

Parameters:

p – Pointer to State object.
nix – Number of entities to return
ix – Array of entity indices
lpos – [out] Array of returned section layer position types

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

set section layer number and position

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.

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.

Parameters:

p – Pointer to State object.
index – Entity index

pos – Section layer position type

x=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

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

get section layer number and position

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().

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.

Parameters:

p – Pointer to State object.
index – Entity index

pos – [out] Section layer positions

x=SYS_LAYERPOSITION_NONE    None, unknown
 =SYS_LAYERPOSITION_BOT     Bottom
 =SYS_LAYERPOSITION_MID     Middle
 =SYS_LAYERPOSITION_TOP     Top
 =SYS_LAYERPOSITION_INTPNT  Integration Point

lay – [out] Section layer numbers

void vis_StateClearData(vis_State *p, Vint index)

clear results data for a single entity

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

Errors: VIS_ERROR_VALUE is generated if an improper index is specified.

Parameters:

p – Pointer to State object.
index – Entity index to set results data

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

set element face or edge results data

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.

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.

Parameters:

p – 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

void vis_StateSetDataElemEntdv(vis_State *p, Vint id, Vint no, Vdouble s[])

set element face or edge results data

See vis_StateSetDataElemEnt()

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

set results data

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 p 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.

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().

Parameters:

p – Pointer to State object.
index – Entity index to set results data
s – [out] Array of results data to be set at entity index

void vis_StateSetDatadv(vis_State *p, Vint id, Vdouble s[])

set results data

See vis_StateSetData()

void vis_StateSetDerive(vis_State *p, Vint derive)

set derived quantity

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)

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

Parameters:

p – Pointer to State object.

derive – Type of derived quantity

x=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

void vis_StateGetDerive(const vis_State *p, Vint *derive)

get derived quantity

See vis_StateSetDerive()

void vis_StateNumDerive(const vis_State *p, Vint *ncmp)

get number of data components

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

Parameters:

p – Pointer to State object.
ncmp – [out] Number of components in current derived quantity type

void vis_StateTypeDerive(const vis_State *p, Vint *typederive)

get data type of derived quantity

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

Parameters:

p – Pointer to State object.
typederive – [out] Primitive data type of derived quantity

void vis_StateSetSection(vis_State *p, Vint section)

set section number

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)

Errors: VIS_ERROR_VALUE is generated if an improper section is specified.

Parameters:

p – Pointer to State object.

section – The section number to select data.

section=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

void vis_StateGetSection(const vis_State *p, Vint *section)

get section number

See vis_StateSetSection()

void vis_StateSetSystem(vis_State *p, Vint system)

set coordinate system state

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)

Errors: VIS_ERROR_ENUM is generated if an improper system is specified.

Parameters:

p – Pointer to State object.

system – The coordinate system state to transform to.

x=STATE_GLOBAL           System state is global
 =STATE_LOCAL            System state is local undeformed.
 =STATE_ROTANG           System state is local deformed.

void vis_StateGetSystem(const vis_State *p, Vint *system)

get coordinate system state

See vis_StateSetSystem()

void vis_StateSetSystemType(vis_State *p, Vint systemtype)

set coordinate system entity type

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)

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.

Parameters:

p – Pointer to State object.

systemtype – The coordinate system state to transform to.

x=SYS_ELEM               System entity type is element
 =SYS_NODE               System entity type is node

void vis_StateGetSystemType(const vis_State *p, Vint *systemtype)

get coordinate system entity type

See vis_StateSetSystemType()

void vis_StateEntitySystemId(const vis_State *p, Vint index, Vint *csysid)

get coordinate system identifier used in system state for an entity

Get coordinate system identifier csysid used in the system state for an entities index .

Parameters:

p – Pointer to State object.
index – Entity index to get coordinate system identifier
csysid – [out] Coordinate system identifier used for entity index

void vis_StateTransform(vis_State *p, Vint system, vis_Group *group)

parallel perform coordinate system transformations

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.

Errors

VIS_ERROR_VALUE is generated if group is not the same entity type as p.
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.

Parameters:

p – Pointer to State object.

system – The coordinate system state to transform to.

x=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.

void vis_StateConvertStrain(vis_State *p, Vint straintype)

convert strain data

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.

Parameters:

p – Pointer to State object.

straintype – Strain type

x=SYS_STRAINTYPE_TENSOR      Tensor strain
 =SYS_STRAINTYPE_ENGINEERING Engineering strain

void vis_StateConvertComplex(vis_State *p, Vint complextype)

convert complex data

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.

Parameters:

p – Pointer to State object.

complextype – Complex type

x=SYS_COMPLEX_REALIMAGINARY  Real imaginary
 =SYS_COMPLEX_MAGNITUDEPHASE Magnitude phase

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

create “demo” node vector displacement results

Set the contents of p 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().

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 p.
VIS_ERROR_OPERATION is generated if the p is not a node vector state.
VIS_ERROR_NULLOBJECT is generated if a GridFun object has not been set.

Parameters:

p – Pointer to State object.

oper – Operation specified to create p

x=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.

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

create deformed node vector of coordinates

Set the contents of p 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 p 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

Errors

VIS_ERROR_VALUE is generated if group is not the same entity type as p.
VIS_ERROR_OPERATION is generated if p 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.

Parameters:

p – 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.

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

query results data for a set of entities

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.

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

Parameters:

p – Pointer to State object.
nix – Number of entities to return results
ix – Array of entity indices
s – [out] Array of returned results data

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

get results data at elements

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().

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

Parameters:

p – Pointer to State object.
index – Element index to get results data
s – [out] Array of returned results data

void vis_StateDataElemdv(const vis_State *p, Vint id, Vdouble s[])

get results data at elements

See vis_StateDataElem()

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

get results data for element entities

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().

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

Parameters:

p – 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
s – [out] Array of returned results data

void vis_StateDataElemEntdv(const vis_State *p, Vint type, Vint id, Vint no, Vdouble s[])

get results data for element entities

See vis_StateDataElemEnt()

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

get results data at given natural coordinates

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().

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

Parameters:

p – Pointer to State object.
index – Element index to get results data
r – Element natural coordinates
s – [out] Array of returned results data

void vis_StateDataElemRSTdv(vis_State *p, Vint id, Vdouble r[], Vdouble s[])

get results data at given natural coordinates

See vis_StateDataElemRST()

void vis_StateDatadv(const vis_State *p, Vint nids, Vint ids[], Vdouble s[])

query results data for a set of entities

See vis_StateData()

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

get number of results values and locations

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.

Errors: VIS_ERROR_VALUE is generated if an improper index is specified.

Parameters:

p – Pointer to State object.
index – Entity index to query
ndat – [out] Total number of data values
nloc – [out] Number of data locations
nsec – [out] Number of data sections

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

get max number of results values and locations

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.

Parameters:

p – Pointer to State object.
maxdat – [out] Maximum number of data values
maxloc – [out] Maximum number of data locations
maxsec – [out] Maximum number of data sections

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

get local direction cosine matrix

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.

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

Parameters:

p – Pointer to State object.
index – Entity index
tm – [out] Array of returned direction cosine matrices

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

parallel minimum and maximum values

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.

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

Parameters:

p – Pointer to State object.
group – Pointer to Group object of entities. If NULL then all entities are assumed.
extent – [out] Minimum and maximum values of results data

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

minimum and maximum values and locations

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, nos[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.

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

Parameters:

p – Pointer to State object.
group – Pointer to Group object of entities. If NULL then all entities are assumed.
extent – [out] Minimum and maximum values of results data
ix – [out] Entity indices
no – [out] Element node connectivity indices

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

minimum and maximum values,locations,sections

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.

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

Parameters:

p – Pointer to State object.
group – Pointer to Group object of entities. If NULL then all entities are assumed.
extent – [out] Minimum and maximum values of results data
ix – [out] Entity indices
no – [out] Element node connectivity indices
sc – [out] Section numbers

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

sum results data

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

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

Parameters:

p – Pointer to State object.
group – Pointer to Group object of entities. If NULL then all entities are assumed.
s – [out] Array of summed results data

void vis_StateSumdv(vis_State *p, vis_Group *group, Vdouble sum[])

sum results data

See vis_StateSum()

void vis_StateMap(vis_State *p, vis_State *statesrc, vis_Group *group)

map results data between node, element and element node locations

Map results quantities between node, element and element node locations. This function maps results data from the entity locations of the source statesrc object to the entity locations of the destination p object. The statesrc object is unchanged by this function. The quantity mapped from the statesrc is dependent upon the current derived quantity in statesrc, see vis_StateSetDerive(). The mapping process is subject to an optional group which determines the element entities which are to be mapped to the p object. The p and statesrc 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().

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 p and statesrc objects are identical.

Parameters:

p – Pointer to destination State object.
statesrc – Pointer to source State object.
group – Pointer to Group object of elements. If NULL then all elements are assumed.

void vis_StateMidside(vis_State *p, vis_Group *group)

process results data at midside nodes

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.

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.

Parameters:

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

void vis_StateMapElemNode(vis_State *p, vis_State *statesrc, vis_Group *group, vis_IdTran *idtran)

map results data to element node location

Map results quantities between element and element node locations. This function maps results data from the entity locations of the source statesrc object to the entity locations of the destination p object. The statesrc object is unchanged by this function. The quantity mapped from the statesrc is dependent upon the current derived quantity in statesrc, see vis_StateSetDerive(). The input indextran object must contain a region number for each element. Data is averaged at element nodes using only elements within the same region. If indextran 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 p object. The p and p 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.

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.

Parameters:

p – Pointer to destination State object.
statesrc – 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.

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

operate on a state as a function of another state

Modify the contents of p 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, p 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 p has no prior data set, then p 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 p and statex objects may be the same.

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 p.
VIS_ERROR_OPERATION is generated if the p and statex entity types are not identical or the derived data type of statex does not match the basic data type of p.
VIS_ERROR_OPERATION is generated if the p and statex have incompatible section configurations.

Parameters:

p – Pointer to State object.

oper – Operation specified to modify p

x=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

x=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.

void vis_StateOperateUnarydv(vis_State *p, Vint oper, Vdouble f, Vint funct, vis_State *statex, vis_Group *group)

operate on a state as a function of another state

See vis_StateOperateUnary()

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

operate on a state as a function of two states

Modify the contents of p 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, p in some way depending upon oper. Any entities for which data has not been defined are skipped.

If p has no prior data set, then p 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 p, statex and statey objects may be the same.

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 p.
VIS_ERROR_OPERATION is generated if the p, statex and statey entity types are not identical.
VIS_ERROR_OPERATION is generated for the STATE_CROSS operation if the derived data types of p, statex and statey are not vector.
VIS_ERROR_OPERATION is generated for the STATE_DOT operation if the basic data type of p 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 p.
VIS_ERROR_OPERATION is generated if the p, statex and statey have incompatible section configurations.

Parameters:

p – Pointer to State object.

oper – Operation specified to modify p

x=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.

void vis_StateOperateBinarydv(vis_State *p, Vint oper, Vdouble f, Vint funct, vis_State *statex, vis_State *statey, vis_Group *group)

operate on a state as a function of two states

See vis_StateOperateBinary()

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

perform differential operations on a state

Modify the contents of p 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, p in some way depending upon oper. The source state, statex must be a node or element node state. The destination state, p may be either a element or element node state. The data type of p 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 p 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.

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 p.
VIS_ERROR_OPERATION is generated if the p 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 p object does not have a GridFun attribute object.

Parameters:

p – Pointer to State object.

oper – Operation specified to modify p

x=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

x=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.

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

set group derivation parameters

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.

Errors: VIS_ERROR_ENUM is generated if an improper node ptype is specified.

Parameters:

p – Pointer to State object.

ptype – Type of group parameter to set

x=STATE_EXTENT           Scalar state extent, vparam

vparam – Specifies the float values that type will be set to.

void vis_StateSortIdTran(vis_State *p, vis_Group *group, vis_IdTran *idtran)

sort entities into an IdTran object

Generate a list of entity indices and output in the indextran object. The entities are placed in the indextran object sorted by their scalar derived value in the p object. The previous contents of the p 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().

Errors

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

Parameters:

p – Pointer to State object.
group – Pointer to Group object. If NULL, then all entities are assumed.
idtran – [out] Pointer to derived IdTran object of sorted entities.

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

derive groups of elements

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.

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.

Parameters:

p – Pointer to State object.

oper – Operation specified to derive group

x=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.
groupdst – [out] Pointer to derived Group object of elements.

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

derive groups of nodes

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.

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.

Parameters:

p – Pointer to State object.

oper – Operation specified to derive group

x=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.
groupdst – [out] Pointer to derived Group object of nodes.

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

write state to file formats

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. Usevis_StateRead()` to read state data from VKI internal formats.

Errors

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

Parameters:

p – Pointer to State object.
rprop – Pointer to RProp object.

type – File type

x=SYS_ASCII              ASCII format
 =SYS_BINARY             Binary format
 =SYS_SDRC_UNIVERSAL     Write to SDRC Universal file

path – File path

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

read state from file formats

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.

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

Parameters:

p – Pointer to State object.

type – File type

x=SYS_ASCII              ASCII format
 =SYS_BINARY             Binary format

path – File path

void vis_StateCopy(vis_State *p, vis_State *fromp)

make a copy of a State object

See vis_StateBegin()

4.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.

Begin and end an instance of an object, return object error flag
- vis_HistoryBegin() - create an instance of a History object
- vis_HistoryEnd() - destroy an instance of a History object
- vis_HistoryError() - return History object error flag
- vis_HistoryCopy() - copy a History
- vis_HistoryPre() - specify precision of history data
Set, manipulate and query results
- vis_HistoryClear() - clear all results data
- vis_HistoryData() - get results data at a set of entities
- vis_HistoryDataLayPos() - get section layer position type
- vis_HistoryDataLayers() - get section layer number and position
- vis_HistoryDataStat() - get results data status
- vis_HistoryDataSteps() - get results data at all steps
- vis_HistoryDataMax() - get max number results values and locations
- vis_HistoryDataNum() - get number of results values and locations
- vis_HistoryDataSect() - get number of results data sections
- vis_HistoryDef() - define parent and child entities
- vis_HistoryInq() - inquire parent and child entities
- vis_HistoryExtent() - minimum and maximum values
- vis_HistoryIndep() - get independent variable at step
- vis_HistoryIndepSteps() - get independent variables at all steps
- vis_HistoryNumDerive() - get number of data components
- vis_HistoryNumIndices() - get number of indices
- vis_HistoryGetIndex() - get an index number
- vis_HistoryIndices() - get index numbers
- vis_HistoryNumSteps() - get number of steps
- vis_HistoryGetStep() - get a step number
- vis_HistorySteps() - get all step numbers
- vis_HistorySample() - compute down sample ranking
- vis_HistoryGetRank() - get step rank
- vis_HistoryCutoffRank() - determine cutoff rank for step interval
- vis_HistorySetData() - set solution results data
- vis_HistorySetDataLayPos() - set section layer position type
- vis_HistorySetDataLayers() - set section layer number and position
- vis_HistorySetDataSect() - set number of results data sections
- vis_HistorySetDataStat() - set solution results data status
- vis_HistorySetDerive() - set derived quantity type
- vis_HistoryGetDerive() - get derived quantity type
- vis_HistorySetEngineeringStrain() - set engineering strain flag
- vis_HistoryGetEngineeringStrain() - get engineering strain flag
- vis_HistorySetObject() - set pointers to attribute objects.
- vis_HistoryGetObject() - get pointers to attribute objects.
- vis_HistorySetIndep() - set independent variable
- vis_HistorySetIndepName() - set independent variable name
- vis_HistoryGetIndepName() - get independent variable name
- vis_HistorySetSection() - set section number
- vis_HistorySetSystem() - set coordinate system state
- vis_HistoryGetSystem() - get coordinate system state
- vis_HistorySetComplexMode() - set specify/query mode for complex data
- vis_HistoryGetComplexMode() - get specify/query mode for complex data
- vis_HistoryGetComplex() - query for complex data existence

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.

4.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.

4.11. Function Descriptions

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

vis_History *vis_HistoryBegin(void)

create an instance of an History object

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)

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

void vis_HistoryEnd(vis_History *p)

destroy an instance of a History object

See vis_HistoryBegin()

Vint vis_HistoryError(vis_History *p)

make a copy of a History object

See vis_HistoryBegin()

void vis_HistoryPre(vis_History *p, Vint pre)

specify precision of history data

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.

Errors: VIS_ERROR_ENUM is generated if an improper pre is specified.

Parameters:

p – Pointer to History object.

pre – Precision of history data

x=SYS_FLOAT              Single precision
 =SYS_DOUBLE             Double precision

void vis_HistorySetObject(vis_History *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

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)

Errors: VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

p – Pointer to History object.
objecttype – The name of the object type to be set.
```
x=VIS_GRIDFUN            GridFun object
```
object – Pointer to the object to be set.

void vis_HistoryGetObject(vis_History *p, Vint objecttype, Vobject **object)

get pointers to attribute objects

See vis_HistorySetObject()

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

define parent and child entities and data type

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)

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.

Parameters:

p – 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

x=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

void vis_HistoryInq(const vis_History *p, Vint *numstp, Vint *nument, Vint *enttype, Vint *subtype, Vint *datatype)

inquire parent and child entities and data type

See vis_HistoryDef()

void vis_HistorySetComplexMode(vis_History *p, Vint complexmode)

set specify/query mode for complex data

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)

Parameters:

p – Pointer to History object.

complexmode – Complex mode

x=SYS_COMPLEX_REAL           Real
 =SYS_COMPLEX_IMAGINARY      Imaginary
 =SYS_COMPLEX_REALIMAGINARY  Real and imaginary

void vis_HistoryGetComplexMode(vis_History *p, Vint *complexmode)

get specify/query mode for complex data

See vis_HistorySetComplexMode()

void vis_HistoryGetComplex(vis_History *p, Vint *complexflag)

query for complex data existence

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.

Parameters:

p – Pointer to History object.
complexflag – [out] Complex data existence flag

void vis_HistorySetEngineeringStrain(vis_History *p, Vint flag)

set engineering strain flag

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)

Parameters:

p – Pointer to History object.

flag – Engineering strain flag

x=SYS_OFF                Tensor strain
 =SYS_ON                 Engineering strain

void vis_HistoryGetEngineeringStrain(vis_History *p, Vint *flag)

get engineering strain flag

See vis_HistorySetEngineeringStrain()

void vis_HistoryClear(vis_History *p)

clear all results data

Clear all results data to zero.

Parameters:: p – Pointer to History object.

void vis_HistorySetDataSect(vis_History *p, Vint index, Vint nsec)

set number of results data sections

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.

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.

Parameters:

p – Pointer to History object.
index – Entity index to set number of results sections
nsec – [out] Number of results sections

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

get number of results data sections

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

Parameters:

p – Pointer to History object.
nix – Number of entities to return
ix – Array of entity indices
nsec – [out] Array of returned number of results sections

void vis_HistorySetDataLayPos(vis_History *p, Vint index, Vint lpos)

set section layer position type

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.

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.

Parameters:

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

lpos – [out] Section layer position type

x=SYS_LAYERPOSITION_NONE    None
 =SYS_LAYERPOSITION_MID     Middle
 =SYS_LAYERPOSITION_BOTTOP  Bottom and top
 =SYS_LAYERPOSITION_BOTTOPMID  Bottom, middle and top

void vis_HistoryDataLayPos(vis_History *p, Vint nix, Vint *lpos)

get section layer position type

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.

Parameters:

p – Pointer to History object.
nix – Number of entities to return
lpos – [out] Array of returned section layer position types

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

set section layer number and position

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.

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.

Parameters:

p – Pointer to History object.
index – Entity index

pos – Section layer position type

x=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

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

get section layer number and position

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().

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.

Parameters:

p – Pointer to History object.
index – Entity index

pos – [out] Section layer positions

x=SYS_LAYERPOSITION_NONE    None, unknown
 =SYS_LAYERPOSITION_BOT     Bottom
 =SYS_LAYERPOSITION_MID     Middle
 =SYS_LAYERPOSITION_TOP     Top
 =SYS_LAYERPOSITION_INTPNT  Integration Point

lay – [out] Section layer numbers

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

set results data

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 p 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.

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().

Parameters:

p – 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

void vis_HistorySetDatadv(vis_History *p, Vint istep, Vint id, Vdouble s[])

set results data

See vis_HistorySetData()

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

set solution results data status

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 p 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.

Errors: VIS_ERROR_VALUE is generated if an improper index is specified.

Parameters:

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

void vis_HistorySetIndep(vis_History *p, Vint istep, Vfloat t)

set independent variable

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

Errors: VIS_ERROR_VALUE is generated if an improper istep is specified.

Parameters:

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

void vis_HistorySetIndepdv(vis_History *p, Vint istep, Vdouble t)

set independent variable

See vis_HistorySetIndep()

void vis_HistoryIndep(vis_History *p, Vint istep, Vfloat *t)

get independent variable at step

Get value of independent variable at step istep.

Errors: VIS_ERROR_VALUE is generated if an improper istep is specified.

Parameters:

p – Pointer to History object.
istep – Solution step
t – [out] Independent variable.

void vis_HistoryIndepdv(vis_History *p, Vint istep, Vdouble *t)

get independent variable at step

See vis_HistoryIndep()

void vis_HistorySetIndepName(vis_History *p, Vchar *name)

set independent variable name

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[])

Parameters:

p – Pointer to History object.
name – Name string

void vis_HistoryGetIndepName(vis_History *p, Vchar name[])

get independent variable name

See vis_HistorySetIndepName()

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

query results data for a set of entities

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.

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

Parameters:

p – Pointer to History object.
istep – Solution step
nix – Number of entities to return results
ix – Array of entity indices
s – [out] Array of returned results data

void vis_HistoryDatadv(vis_History *p, Vint istep, Vint nids, Vint ids[], Vdouble s[])

query results data for a set of entities

See vis_HistoryData()

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

get number of results values and locations

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.

Errors: VIS_ERROR_VALUE is generated if an improper index is specified.

Parameters:

p – Pointer to History object.
index – Entity index to query
ndat – [out] Total number of data values
nloc – [out] Number of data locations
nsec – [out] Number of data sections

void vis_HistoryDataMax(vis_History *p, Vint *maxdat, Vint *maxloc, Vint *maxsec)

get max number of results values and locations

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.

Parameters:

p – Pointer to History object.
maxdat – [out] Maximum number of data values
maxloc – [out] Maximum number of data locations
maxsec – [out] Maximum number of data sections

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

get results data status

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 p 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.

Errors: VIS_ERROR_VALUE is generated if an improper index is specified.

Parameters:

p – Pointer to History object.
index – Entity index to get results status
stat – [out] Array of returned results data status

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

get results data at all steps

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.

Errors: VIS_ERROR_VALUE is generated if an improper ix index is specified.

Parameters:

p – Pointer to History object.
nix – Number of entities to return results
ix – Array of entity indices
s – [out] Array of returned results data

void vis_HistoryDataStepsdv(vis_History *p, Vint nids, Vint ids[], Vdouble s[])

get results data at all steps

See vis_HistoryDataSteps()

void vis_HistorySetDerive(vis_History *p, Vint derive)

set derived quantity

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)

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

Parameters:

p – Pointer to History object.
derive – Type of derived quantity, same as vis_StateSetDerive()

void vis_HistoryGetDerive(const vis_History *p, Vint *derive)

get derived quantity

See vis_HistorySetDerive()

void vis_HistoryNumDerive(const vis_History *p, Vint *ncmp)

get number of data components

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

Parameters:

p – Pointer to History object.
ncmp – [out] Number of components in current derived quantity type

void vis_HistorySetSection(vis_History *p, Vint section)

set section number

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)

Errors: VIS_ERROR_VALUE is generated if an improper section is specified.

Parameters:

p – Pointer to History object.

section – The section number to select data.

x=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

void vis_HistoryGetSection(const vis_History *p, Vint *section)

get section number

See vis_HistorySetSection()

void vis_HistorySetSystem(vis_History *p, Vint system)

set coordinate system state

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)

Errors: VIS_ERROR_ENUM is generated if an improper system is specified.

Parameters:

p – Pointer to History object.

system – The coordinate system state

x=HISTORY_GLOBAL         System state is global
 =HISTORY_LOCAL          System state is local.

void vis_HistoryGetSystem(const vis_History *p, Vint *system)

get coordinate system state

See vis_HistorySetSystem()

void vis_HistoryNumIndices(const vis_History *p, Vint *nument)

get number of indices

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

Parameters:

p – Pointer to History object.
nument – [out] Number of parent entities

void vis_HistoryGetIndex(vis_History *p, Vint in, Vint *index)

get an index number

Return the in ‘th index.

Errors: VIS_ERROR_VALUE is generated if an improper in is specified.

Parameters:

p – Pointer to History object.
in – In-th index to return 1 <= in <= nument
index – [out] Index

void vis_HistoryIndices(const vis_History *p, Vint *nument, Vint indices[])

get index numbers

Return the number of parent entities and all indices.

Parameters:

p – Pointer to History object.
nument – [out] Number of parent entities
indices – [out] Array of indices

void vis_HistoryNumSteps(const vis_History *p, Vint *numstp)

get number of steps

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

Parameters:

p – Pointer to History object.
numstp – [out] Number of solution steps

void vis_HistoryGetStep(vis_History *p, Vint in, Vint *istep)

get a step number

Return the in ‘th step number.

Errors: VIS_ERROR_VALUE is generated if an improper in is specified.

Parameters:

p – Pointer to History object.
in – In-th step number to return 1 <= in <= numstp
istep – [out] Step number

void vis_HistorySteps(const vis_History *p, Vint *numstp, Vint isteps[])

get step numbers

Return the number of solution steps and all step numbers.

Parameters:

p – Pointer to History object.
numstp – [out] Number of parent entities
isteps – [out] Array of solution step numbers.

void vis_HistoryIndepSteps(const vis_History *p, Vfloat t[])

get independent variables at all steps

Get values of independent variable at all steps.

Parameters:

p – Pointer to History object.
t – [out] Array of independent variables at all steps

void vis_HistoryIndepStepsdv(const vis_History *p, Vdouble t[])

get independent variables at all steps

See vis_HistoryIndepSteps()

void vis_HistoryExtent(vis_History *p, Vfloat extent[])

minimum and maximum values

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

Parameters:

p – Pointer to History object.
extent – [out] Minimum and maximum values of results data

void vis_HistoryGetRank(vis_History *p, Vint istep, Vint *rank)

get step rank

Return the rank of istep step number.

Errors: VIS_ERROR_VALUE is generated if an improper istep is specified.

Parameters:

p – Pointer to History object.
istep – Step number
rank – [out] Step rank

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

determine cutoff rank for step interval

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

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

Parameters:

p – Pointer to History object.
istep1 – Starting step number
istep2 – Ending step number
num – Number of step samples to retain
cutoffrank – [out] Cutoff rank

void vis_HistorySample(vis_History *p)

compute down sample ranking

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.

Errors: VIS_ERROR_MEMORY is generated if a memory allocation failure occurs.

Parameters:: p – Pointer to History object.

4.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.

Begin and end an instance of an object, return object error flag
- vis_RedMatBegin() - create an instance of a RedMat object
- vis_RedMatEnd() - destroy an instance of a RedMat object
- vis_RedMatError() - return RedMat object error flag
- vis_RedMatPre() - specify precision of matrix data
Set, manipulate and query results
- vis_RedMatData() - get results data
- vis_RedMatDataCols() - get column indicies per row
- vis_RedMatDef() - define matrix rank and data type.
- vis_RedMatNum() - inquire number of matrix entries
- vis_RedMatSparse() - inquire sparsity of matrix entries
- vis_RedMatSetData() - set results data
- vis_RedMatSetDataSize() - set number of columns per row
- vis_RedMatGetDataSize() - get number of columns per row
- vis_RedMatSetDof() - set entity index and degree of freedom type
- vis_RedMatGetDof() - get entity index and degree of freedom type
- vis_RedMatSetComplexMode() - set specify/query mode for complex data
- vis_RedMatGetComplexMode() - get specify/query mode for complex data
- vis_RedMatGetComplex() - query for complex data existence

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 <ComplexNumbers> 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.

4.13. Function Descriptions

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

vis_RedMat *vis_RedMatBegin(void)

create an instance of a RedMat object

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)

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

void vis_RedMatEnd(vis_RedMat *p)

destroy an instance of a RedMat object

See vis_RedMatBegin()

Vint vis_RedMatError(vis_RedMat *p)

return the current value of a RedMat object error flag

See vis_RedMatBegin()

void vis_RedMatPre(vis_RedMat *p, Vint prec)

specify precision of redmat data

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 Floating Point Precision for a description of precision types.

Errors: VIS_ERROR_ENUM is generated if an improper prec is specified.

Parameters:

p – Pointer to RedMat object.
prec – Precision of redmat data

void vis_RedMatDef(vis_RedMat *p, Vint ndofs, Vint type)

define number of freedoms and data type.

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)

Errors

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

Parameters:

p – Pointer to RedMat object.
ndofs – Rank or number of degrees of freedom.

type – Data type

x=SYS_VECTOR             Vector
 =SYS_MATRIX_DIAG        Diagonal matrix
 =SYS_MATRIX_SYMM        Symmetric matrix
 =SYS_MATRIX_USYMM       Unsymmetric matrix

void vis_RedMatInq(vis_RedMat *p, Vint *ndofs, Vint *type)

inquire of defined ndofs and type as output arguments

See vis_RedMatDef()

void vis_RedMatSetComplexMode(vis_RedMat *p, Vint complexmode)

set specify/query mode for complex data

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)

Errors: SYS_ERROR_ENUM is generated if an improper complexmode is specified.

Parameters:

p – Pointer to RedMat object.

complexmode – Complex mode

x=SYS_COMPLEX_REAL           Real
 =SYS_COMPLEX_IMAGINARY      Imaginary
 =SYS_COMPLEX_REALIMAGINARY  Real and imaginary

void vis_RedMatGetComplexMode(vis_RedMat *p, Vint *complexmode)

get specify/query mode for complex data

See vis_RedMatSetComplexMode()

void vis_RedMatGetComplex(vis_RedMat *p, Vint *complexflag)

query for complex data existence

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.

Parameters:

p – Pointer to RedMat object.
complexflag – [out] Complex data existence flag

void vis_RedMatSetDatadv(vis_RedMat *p, Vint i, Vint j, Vdouble v[])

set results data at degree of freedom

See vis_RedMatSetData()

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

set results data at degree of freedom

Set results data, v, for matrix entry at row idof and column jdof. 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.

Errors: VIS_ERROR_VALUE is generated if an improper idof or jdof are specified.

Parameters:

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

void vis_RedMatDatadv(vis_RedMat *p, Vint i, Vint j, Vdouble v[])

get results data at degree of freedom

See vis_RedMatData()

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

get results data at degree of freedom

Get results data, v, for matrix entry at row idof and column jdof. 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.

Errors: VIS_ERROR_VALUE is generated if an improper idof or jdof are specified.

Parameters:

p – Pointer to RedMat object.
idof – Row Dof index
jdof – Column Dof index
v – [out] Returned results data

void vis_RedMatSetDof(vis_RedMat *p, Vint dof, Vint index, Vint doftag)

set entity index and degree of freedom type

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)

Errors: VIS_ERROR_VALUE is generated if an improper dof is specified.

Parameters:

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

void vis_RedMatGetDof(vis_RedMat *p, Vint dof, Vint *nid, Vint *doftag)

get entity index and degree of freedom type

See vis_RedMatSetDof()

void vis_RedMatNum(vis_RedMat *p, Vlong *nent, Vint *nval)

inquire number of matrix entries

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.

Parameters:

p – Pointer to RedMat object.
nent – [out] Number of vector/matrix entries
nval – [out] Number of values per entry

void vis_RedMatSparse(vis_RedMat *p, Vint *sparse)

inquire sparsity of matrix entries

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.

Parameters:

p – Pointer to RedMat object.
sparse – [out] Sparsity flag.

void vis_RedMatSetDataSize(vis_RedMat *p, Vint idof, Vint ncols)

set number of columns per row

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)

Errors: VIS_ERROR_VALUE is generated if an improper idof is specified.

Parameters:

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

void vis_RedMatGetDataSize(vis_RedMat *p, Vint i, Vint *size)

get number of columns per row

See vis_RedMatSetDataSize()

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

get column indicies per row

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

Errors: VIS_ERROR_VALUE is generated if an improper idof is specified.

Parameters:

p – Pointer to RedMat object.
idof – Row Dof index
ncols – [out] Number of columns at row
icols – [out] Column indicies at row.

4.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.

Begin and end an instance of an object, return object error flag
- vis_ZStateBegin() - create an instance of a Z:ref:State <State> object
- vis_ZStateEnd() - destroy an instance of a Z:ref:State <State> object
- vis_ZStateError() - return Z:ref:State <State> object error flag
Set, manipulate and query results
- vis_ZStateDef() - define parent and child entities.
- vis_ZStateInq() - inquire parent and child entities.
- vis_ZStateKernel() - form compression kernel
- vis_ZStateLngKernel() - get byte length of kernel
- vis_ZStateLoadKernel() - load kernel from memory buffer into ZState
- vis_ZStateSaveKernel() - save kernel from ZState into memory buffer
- vis_ZStateSetMode() - set operation modes
- vis_ZStateSetObject() - set pointers to attribute objects.
- vis_ZStateGetObject() - get pointers to attribute objects.
- vis_ZStateState() - process input state
- vis_ZStateLngState() - get byte length of compressed state
- vis_ZStateLoadState() - load compressed data from memory buffer
- vis_ZStateSaveState() - save compressed data into memory buffer

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.

4.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

4.16. Function Descriptions

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

vis_ZState *vis_ZStateBegin(void)

create an instance of a ZState object

Create an instance of a 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)

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

void vis_ZStateEnd(vis_ZState *p)

destroy an instance of a ZState object

See vis_ZStateBegin()

Vint vis_ZStateError(vis_ZState *p)

return the current value of a ZState object error flag

See vis_ZStateBegin()

void vis_ZStateSetObject(vis_ZState *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

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)

Errors: VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

p – Pointer to ZState object.
objecttype – The name of the object type to be set.
```
x=VIS_GRIDFUN            GridFun object
```
object – Pointer to the object to be set.

void vis_ZStateGetObject(vis_ZState *p, Vint objecttype, Vobject **object)

get pointers to attribute objects

See vis_ZStateSetObject()

void vis_ZStateDef(vis_ZState *p, Vint nument, Vint parenttype, Vint childtype)

define parent and child entities

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)

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.

Parameters:

p – 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

void vis_ZStateInq(const vis_ZState *p, Vint *nument, Vint *enttype, Vint *subtype)

inquire parent and child entities

See vis_ZStateDef()

void vis_ZStateKernel(vis_ZState *p, vis_IdTran *idtran)

form compression kernel

Form compression kernel.

Parameters:

p – Pointer to ZState object.
idtran – Pointer to IdTran object.

void vis_ZStateLngKernel(vis_ZState *p, Vulong *nbytes)

get byte length of kernel

Get byte length of kernel.

Parameters:

p – Pointer to ZState object.
nbytes – [out] Number of bytes in compression kernel

void vis_ZStateSaveKernel(vis_ZState *p, void *buff, Vulong *nbytes)

save kernel from ZState into memory buffer

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

Parameters:

p – Pointer to ZState object.
buff – [out] Output buffer for kernel
nbytes – [out] Final number of bytes in compression kernel

void vis_ZStateLoadKernel(vis_ZState *p, void *buff)

load kernel from memory buffer into ZState

Read kernel from input buffer, buff.

Parameters:

p – Pointer to ZState object.
buff – Input buffer for kernel

void vis_ZStateState(vis_ZState *p, vis_State *state)

process input state

Process state data.

Parameters:

p – Pointer to ZState object.
state – Pointer to State object.

void vis_ZStateLngState(vis_ZState *p, Vulong *nbytes)

get byte length of compressed state

Get byte length of compressed state.

Parameters:

p – Pointer to ZState object.
nbytes – [out] Number of bytes in compressed state

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

save compressed data into memory buffer

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

Parameters:

p – Pointer to ZState object.
state – Pointer to State object.
buff – [out] Output buffer for compressed data
nbytes – [out] Final number of bytes in compressed state

void vis_ZStateLoadState(vis_ZState *p, void *buff, vis_State *state)

load compressed data from memory buffer

Load compressed data into state object.

Parameters:

p – Pointer to ZState object.
buff – Input buffer for compressed data
state – [out] Pointer to State object.

void vis_ZStateSetMode(vis_ZState *p, Vint type, Vint value)

set operation modes

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.

Errors: SYS_ERROR_ENUM is generated if an improper type is specified.

Parameters:

p – Pointer to ZState object.

type – Type of mode

x=ZSTATE_SPATIALCONTINUITY  Toggle spatial continuity

value – Mode value

x=SYS_ON                    Enable
 =SYS_OFF                   Disable

4. Data Manipulation - ElemDat, State, History, RedMat, ZState

4.1. Face and Edge Data - ElemDat

4.2. Attribute Objects

4.3. Function Descriptions

4.4. Results Manipulation - State

4.5. Local Coordinate Systems

4.6. Parallel Functions

4.7. Attribute Objects

4.8. Function Descriptions

4.9. History Results Manipulation - History

4.10. Attribute Objects

4.11. Function Descriptions

4.12. System Degree of Freedom Data - RedMat

4.13. Function Descriptions

4.14. Results Compression - ZState

4.15. Attribute Objects

4.16. Function Descriptions

4. Data Manipulation - ElemDat, State, History, RedMat, ZState 

4.1. Face and Edge Data - ElemDat 

4.4. Results Manipulation - State 

4.9. History Results Manipulation - History 

4.12. System Degree of Freedom Data - RedMat 

4.14. Results Compression - ZState 