Table of Contents

1. Introduction

The VdmTools library from Visual Kinematics, Inc. is designed to provide a comprehensive mechanism for accessing data from the model and solution results data files of many important commercial finite element analysis (FEA) software systems used in the fields of mechanical computer aided engineering (MCAE) and computational fluid dynamics (CFD).

A data model consisting of the notion of a library - dataset - attribute hierarchy is mapped onto the data structure of all model and solution results data files (libraries). The net result being that VdmTools allows a consistent interface to finite element data from many sources. VdmTools also provides a "native" library which supports both read and write operations. All library formats, whether native or "external" may be accessed through VdmTools in an identical manner. The basic features of VdmTools are summarized below.

Table of Contents

1.1 Module Summary

Each solution results data file or library is viewed as a collection of named datasets which logically group associated information on the library. Each dataset in turn is composed of three parts; parameters, named attributes, and actual data. These components together provide data description and data storage mechanisms for finite element analysis data. There are two broad classes of libraries, native and external. External libraries are accessed by a mechanism called direct binary access. This mechanism allows data to be accessed from external libraries as quickly as the FEA programs which created them. Direct binary access, as the term implies, accesses data randomly on external libraries in binary mode with little or no translation processing involved. The modules currently available in VdmTools may be divided into 4 categories: 1) library device components, 2) library interfaces 3) data functions and 4) high level library management.

Each instance of a module is termed an object. In order to access the finite element model and results data from an external library a series of steps must be followed to open the data file, declare its format, query for the amount and type of information on the file and finally request the information to be read into memory. Using the SDRC Universal file format as an example, the methodology for reading the base model and results information can be described by the following steps:
       vdm_SDRCLib *sdrclib;
       vdm_DataFun *df;
                   /* create SDRC Universal File device object */
       sdrclib = vdm_SDRCLibBegin();
                   /* create data function */
       df = vdm_DataFunBegin();
                   /* load data functions for SDRCLib device */
       vdm_SDRCLibDataFun (sdrclib,df);

       Vint ierr;
                   /* open library on file "example.unv" */
       vdm_DataFunOpen (df,0,"example.unv",VDM_SDRC_UNIVERSAL);
       ierr = vdm_DataFunError(df);
                   /* error opening file */ 
       if(ierr) {
       }
                   /* append library on file "append.op2" */
       vdm_DataFunAppend (df,"append.op2",VDM_NASTRAN_OUTPUT2);
       ierr = vdm_DataFunError(df);
                   /* error appending file */ 
       if(ierr) {
       }
       Vint numnp, numel;
       Vint idst, ndsts;

                   /* get number of nodes and element */ 
       vdm_DataFunGetNumEntities (datafun,SYS_NODE,&numnp);
       vdm_DataFunGetNumEntities (datafun,SYS_ELEM,&numel);
                   /* get library object */
       vdm_DataFunGetLibrary (datafun,&library);
                   /* search for node coordinate dataset */
       vdm_LibrarySearchDataset (library,"X.N",1,&idst,&ndsts);
       vdm_Dataset *dataset;
       Vchar name[33];
       Vlong lrec;
       Vint nrow, ncol, ntyp;

                   /* get dataset object of idst dataset */
       vdm_LibraryGetDataset (library,idst,&dataset);
                   /* inquire dataset parameters */
       vdm_DatasetInq (dataset,name,&lrec,&nrow,&ncol,&ntyp);
       Vfloat *x;

                   /* allocate memory */ 
       x = (Vfloat*)malloc(lrec*sizeof(Vfloat));
                   /* read data */ 
       vdm_DataFunReadDataset (df,idst,(void*)x);
                   /* free user memory */ 
       free(x);
                   /* close library device */
       vdm_DataFunClose (df);
                   /* delete objects */
       vdm_SDRCLibEnd (sdrclib);
       vdm_DataFunEnd (df);
Table of Contents

1.2 Interface Support Information

The following section is meant to summarize the following information for each interface module: 1) the vendor of the commercial analysis system producing the result files and 2) the release levels of the analysis systems supported by the interface module.

   NX/NASTRAN 12
   Siemens
   URL: http://www.siemens.com/nx
Table of Contents

1.3 Compiling and Linking a VdmTools Application

In addition to the overall C preprocessor definitions described in section DevTools, Compiling and Linking a DevTools Application, another C preprocessor definition specifies external library interface APIs. The current external library APIs used in VdmTools are to support the ABAQUS .odb, PAM-CRASH .DSY, PAM-CRASH .erfh5, MSC/NASTRAN .h5, STAR-CCM results file, CGNS data base, AUTODYN results file, Altair H3D file, CFX results file, SAMCEF results file interfaces and any HDF5 based interface.

VKI_LIBAPI_ABAODB      ABAQUS .odb interface
VKI_LIBAPI_AUTODYN     AUTODYN interface
VKI_LIBAPI_CFX         CFX results file
VKI_LIBAPI_CGNS        CGNS data base
VKI_LIBAPI_FEMZIP      FEMZIP LS-DYNA d3plot interface
VKI_LIBAPI_FEMZIP_     FEMZIP LS-DYNA d3plot interface appended
VKI_LIBAPI_HDF5        PAM-CRASH ERF, MSC/NASTRAN .h5, Native HDF5
VKI_LIBAPI_H3D         Altair H3D interface
VKI_LIBAPI_PAMDSY      PAM-CRASH .DSY interface
VKI_LIBAPI_STARCCM     STAR-CCM .ccm results file
VKI_LIBAPI_SAMCEF      SAMCEF .des results file
VKI_LIBAPI_ZLIB        ANSYS 17 compressed results files

1.3.1 ABAQUS .odb interface

Since the .odb API is implemented in C++, the .odb interface requires the use of a C++ compiler and an installation of ABAQUS. The compiler required on a specific system must match the compiler used by ABAQUS. See the following URL.
http://www.simulia.com
The file vdm/vdmodb.cxx must be compiled with the required C++ compiler. All other DevTools source code may be compiled with a compatible C compiler. Compiler options and linker options and required libraries are dependent upon the specific version of ABAQUS and computer platform.

1.3.2 AUTODYN interface

The AUTODYN interface is implemented using the AUTODYN toolkit provided by ANSYS AUTODYN. Calls to the AUTODYN functions are conditionally compiled by defining VKI_LIBAPI_AUTODYN, then the application must be linked with the AUTODYN libraries. See the following URL.
http://www.ansys.com

1.3.3 FEMZIP LS-DYNA d3plot interface

FEMZIP is used to compress a family of LS-DYNA d3plot files. The FEMZIP API is implemented using a toolkit provided by Fraunhofer SCAI. Apparently FEMZIP is written in Fortran so that the function names may be appended by an underscore on some platforms. Calls to the toolkit functions are conditionally compiled by defining VKI_LIBAPI_FEMZIP_ or VKI_LIBAPI_FEMZIP to access functions with or without an appended underscore respectively. See the following URL.
http://www.sidact.com/femzip.html

1.3.4 CFX results file

The CFX results file API is implemented using a toolkit provided by ANSYS CFX. Calls to the toolkit functions are conditionally compiled by defining VKI_LIBAPI_CFX, then the application must be linked with the CFX libraries. See the following URL.
http://www.ansys.com

1.3.5 CGNS data base

The CFD General Notation System (CGNS) data base is a collection of conventions and software for the storage and retrieval of CFD data. Calls to the CGNS functions are conditionally compiled by defining VKI_LIBAPI_CGNS. If CGNS is used by compiled with VKI_LIBAPI_CGNS then the application must be linked with the CGNS libraries. The source code for the underlying CGNS library are publicly available. See the following URL.
http://cgns.sourceforge.net

1.3.6 Altair H3D interface

The H3D interface is implemented using the H3d toolkit provided by Altair Engineering. Calls to the H3D functions are conditionally compiled by defining VKI_LIBAPI_H3D then the application must be linked with the H3D libraries. See the following URL.
http://www.altair.com

1.3.7 PAM-CRASH .DSY interface

The .DSY API is implemented using a toolkit provided by ESI-GROUP. Calls to the toolkit functions are conditionally compiled by defining VKI_LIBAPI_PAMDSY. See the following URL,
http://www.esi-group.com

1.3.8 PAM-CRASH .erfh5 interface, MSC/NASTRAN .h5, Native .vh5

The above file formats are implemented on top of the HDF5 interface. Calls to the toolkit functions are conditionally compiled by defining VKI_LIBAPI_HDF5. See the following URL,
http://www.hdfgroup.org

1.3.9 STAR-CCM .ccm results file interface

The STAR-CCM API is implemented using a toolkit provided by CD-Adapco. Calls to the toolkit functions are conditionally compiled by defining VKI_LIBAPI_STARCCM. See the following URL,
http://www.cd-adapco.com

1.3.10 SAMCEF .des results file interface

The SAMCEF API is implemented using a toolkit provided by Siemens. Calls to the toolkit functions are conditionally compiled by defining VKI_LIBAPI_SAMCEF. See the following URL,
http://www.siemens.com

The SAMCEF interface requires the definition of two environment variables: SAM_ZONE refers to the memory usage in the SAMCEF library. SAM_EXE identifies the SAMCEF library installation path.

Table of Contents

1.4 Dataset Specification Syntax

Datasets are identified by name. A dataset specification has the following form,

dataset_name:id1:id2:id3

1.4.1 Dataset Name, dataset_name

The dataset name is a character string which may contain any letter or digit including the special characters period, dollar sign and underscore. The period is most often used in dataset names to separate the name into two or more fields. By convention the last field, delimited by a period, indicates the data structure. The length of a dataset specification name may not exceed 256 characters. Below are examples of some legal dataset specifications.

V.N:1
S.E:10
D.N:1:5
TEMP.[Total].E
SET.ELEM.T

1.4.2 Numeric Identifiers, :id1:id2:id3

The numeric identifiers are positive integers. They are delimited from the dataset name and other numeric identifiers by the colon, :. The numeric identifiers are optional in the dataset specification, however one or more of the numeric identifiers is usually present. Their exact interpretation depends upon the context in which they are used. They are used in many places to signify the load step or time step number, increment number, vibration, or buckling mode number, etc. For example, on an external ABAQUS .fil database the node displacements at load step 3, increment 2 are resident in dataset D.N:3:2

1.4.3 Dataset Specification Expansion

It is useful in many instances to be able to refer to a group of related datasets with a single dataset specification or a single dataset with an abbreviated but unique character string. These tasks are accomplished with dataset name expansion. The dataset name and numerical identifiers may be expanded with a syntax which resembles UNIX file name expansion. The following wild card substitutions are used. For example,

D*
matches all datasets starting with the letter D. The dataset specification,

*:(2-4)
matches all datasets associated with solution step 2, 3 and 4.

In a departure from standard UNIX file expansion syntax, dataset specifications may also contain numeric identifier ranges. Ranges are specified in the form, FiTjBk, representing From the ith To the jth By increments of k. For example,

D.N:F1T49B2
matches all datasets named D.N:1, D.N:3, D.N:5, ...,D.N:49. The highest and lowest numeric identifier may be referenced using the letters H and L respectively. This is useful in quickly selecting the first or last solution on a library. For example,

S.EL:H
matches the dataset S.EL.n, where n is the highest numbered solution step. The asterisk wild card may be combined with identifier ranges. For example,

D.N:H:*
matches displacement datasets at the last iteration of each load step.

Table of Contents

1.5 Dataset Parameters and Attributes

Associated with each dataset on a library are a set of dataset parameters and attributes. The dataset parameters describe the basic physical characteristics, data structure and data type of the dataset. Dataset attributes are given a name and a value. They are used to help describe the contents of a dataset or refine its data structure.

Dataset parameters include record length, number of rows and columns, data type and number of dataset attributes. The total size of the dataset in (bytes) is the product of record length and the size of the data type. The data type of a dataset should be homogeneous. The basic data structure of a dataset is that of a dimensioned array. The dimensionality of the array is specified by the number of rows and columns. Variations on the basic dimensioned array data type are accomplished using special reserved dataset attributes. These data structures are described in more detail later in this chapter. The description of each dataset parameter is as follows.

Dataset attributes are meant to contain information about a dataset. An attribute has an associated name, length, data type and value. An individual attribute is identified by specifying a dataset name and attribute name. Attribute names are character strings containing 16 characters or less. The period is often used to delimit an attribute name into two or more fields. For example, attributes which have other dataset names as values are named as follows,

Link.Size
Link.Index
Link.Complex
Link.Cid
Link.Section
Link.Layers
The data type and length of an attribute describe the data type and length of an attribute value. An attribute value cannot contain more than 16 integer or floating point numbers, 8 double precision numbers or 256 characters. An attribute value must be of a single data type.

Table of Contents

1.6 Data Structures

The basic data structures supported by the data management system are the single data type rectangular array and single data type variable row array. Dataset attributes are used to logically link datasets to other datasets to augment these basic data structures. VdmTools uses a dataset naming convention to indicate the data structure and data class of each dataset. These conventions are referred to as formats. The following formats are used. Complex results quantities may be stored as real-imaginary or magnitude-phase pairs of datasets. The real or magnitude part of the complex result will be stored in a dataset which is named as if the result were purely real. The imaginary or phase part of the complex result is stored in a dataset which adds a .I immediately after the dataset name (including optional dataset qualifier) for the real or magnitude part. A Complex attribute is added with the character value Real, Magnitude, Imaginary or Phase. Note that phase is always in degrees. The real or magnitude dataset will have an additional Link.Complex attribute which names the associated dataset containing the imaginary or phase part of the complex result. If only the real or magnitude part exists, then the Link.Complex Attribute will be omitted. For example, a complex displacement result containing both magnitude and phase parts would result in the following datasets and attributes.

D.N:1:1
 Complex = Magnitude
 Link.Complex = D.I.N:1:1
D.I.N:1:1
 Complex = Phase
Table of Contents

1.7 Finite Element Model Dataset Names and Descriptions

Datasets appearing on native and external libraries follow a naming convention and adhere to one of the basic data structures detailed in the preceding section. Each model dataset will contain a "Model" attribute. The character value of the attribute will give the class of model data that the dataset contains.

Each model dataset also contains a "Description" attribute whose character value is a basic description of the dataset contents. A summary of the "Mesh" datasets is given below.

MODEL DATASETS

COLORID.E
COLORID.N
Integer vectors of object colors for each object type. ncol=maximum possible number of objects of the given type, nrow=1.
COLORMAP.T
Real array of RGB floating point triples for each color index. nrow=3, ncol=maximum number of color map entries defined. Column j contains the red, green and blue intensities in the range [0.,1.] of color map identifier j.
CSYS.T
Real array of the origin and orientation of defined coordinate system objects. nrow=12, ncol=maximum number of coordinate systems defined. Column j contains the definition of coordinate system internal identifier j.

row_1-3      Global coordinates of origin of coordinate system
row_4-12     Direction cosines of coordinate system axes
CSYS.TYPE.T
Integer vector of types for each coordinate system. ncol=maximum number of coordinate systems, nrow=1.

row_1        Coordinate system type, type
             =1          Rectangular        (SYS_CARTESIAN)
             =2          Cylindrical        (SYS_CYLINDRICAL)
             =3          Spherical, type a  (SYS_SPHERICAL)
             =4          Spherical, type b  (SYS_SPHERICAL_ALT)
             =5          Toroidal           (SYS_TORODIAL)
CSYS.ID.T
Integer vector of user assigned identifiers for each coordinate system. ncol=maximum number of coordinate systems, nrow=1.
DOF.CID.N
Integer vector of coordinate system identifiers in which nodal degrees of freedom are expressed for each node. ncol=maximum number of nodes, nrow=1.
EID.E
Integer vector of user assigned identifiers for each element. ncol=maximum number of elements, nrow=1.
ELEM.NODE.EL
Integer variable row array of element node connectivity for each element. ncol=maximum number of elements, nrow=maximum length of element node connectivity. Connectivity references internal node number ordering. The datasets .ELEM.NODE.PNTR.E and .ELEM.NODE.SIZE.E are the integer pointer and size of each column in dataset ELEM.NODE.EL.
ELEM.SHAP.E
Integer vector of element shape of each element. ncol=maximum number of elements, nrow=1. See section VisTools, Computational Cells for a description of element topologies.

shape        Element shape
             =SYS_SHAPEPOINT
             =SYS_SHAPELINE
             =SYS_SHAPETRI
             =SYS_SHAPEQUAD
             =SYS_SHAPETET
             =SYS_SHAPEPYR
             =SYS_SHAPEWED
             =SYS_SHAPEHEX
             =SYS_SHAPEPOLYGON
             =SYS_SHAPEPOLYHED
ELEM.MIJK.E
Integer array of element order for each element. ncol=maximum number of elements, nrow=3. Column j contains 3 form parameters for element j.

maxi         Number of nodes in I direction
maxj         Number of nodes in J direction
maxk         Number of nodes in K direction
ELEM.SPEC.E
Integer vector of element specific type of each element. The specific type is designed to distinguish variations within the general element types contained in dataset ELEM.TYPE.E. See section VisTools, Element Types for a description of element specific types. ncol=maximum number of elements, nrow=1.

row_1        Element specific type code
ELEM.TYPE.E
Integer vector of internal element type of each element. Use dataset ELEM.SPEC.E to determine element variations within a particular element type. See section VisTools, Element Types for a description of element types. ncol=maximum number of elements, nrow=1.

row_1        Element type code
             =SYS_ELEM_SOLID
             =SYS_ELEM_SHELL
             =SYS_ELEM_MEMBRANE
             =SYS_ELEM_BEAM
             =SYS_ELEM_TRUSS
             =SYS_ELEM_INFINITE
             =SYS_ELEM_GAP
             =SYS_ELEM_JOINT
             =SYS_ELEM_SPRINGDASHPOT
             =SYS_ELEM_RIGID
             =SYS_ELEM_CONSTRAINT
             =SYS_ELEM_PLOT
             =SYS_ELEM_MASS
             =SYS_ELEM_INTER
             =SYS_ELEM_SUPER
ELEM.TYPE.EXT.E
Integer vector of external element type of each element. The external element type number is the identifying element type number which is assigned by the originating, external finite element system. For example, for ANSYS, this number is the ANSYS element routine number. ncol=maximum number of elements, nrow=1.
ELEM.TYPE.HOL.E
Character valued external element name for each element. Each element name consists of 8 characters. Character strings are stored in Hollerith form, 4 characters per integer word. ncol=maximum number of elements, nrow=2.

row_1        First four characters
row_2        Second four characters
ERS.CID.E
Integer vector of element local coordinate system identifiers. This dataset may be referenced by element result datasets to indicate the coordinate system in which element vector and tensor results are expressed. ncol=maximum number of elements, nrow=1. User defined coordinate systems are located in the CSYS.T model dataset. Vector or position orientations are located in the ERS.VEC.E model dataset. Direction cosine matrices are located in the DIR_COS result dataset. See section VisTools, Element Coordinate Systems for a description of element coordinate systems.

row_1        Element local coordinate system identifier
             >0                         User defined coordinate system
             =SYS_ELEMSYS_GLOBAL          Global coordinate system
             =SYS_ELEMSYS_STANDARD        Standard
             =SYS_ELEMSYS_POSITION        Position
             =SYS_ELEMSYS_GLOBALPROJECT   Global project
             =SYS_ELEMSYS_VECTOR          Vector
             =SYS_ELEMSYS_VECTORELEMNODE  Element node vector
             =SYS_ELEMSYS_BISECTOR        Bisector
             =SYS_ELEMSYS_ROTANG          Rotation angles
             =SYS_ELEMSYS_ROTANGELEMNODE  Element node rotation angles
             =SYS_ELEMSYS_FIRSTEDGE       First edge
ERS.VEC.E
Real array of global coordinates of element orientation positions or vectors. ncol=maximum number of elements, nrow=3. Each column j contains the x,y,z global coordinates of a orientation position or vector for the jth element. These orientations are required for certain types of element local systems. Element local coordinate system identifiers are located in the ERS.CID.E model dataset.
INDX.ELEM.T:id
INDX.NODE.T:id
INDX.MODE.T:id
INDX.PANEL.T:id
Integer vector of element, node, mode or panel indices. ncol=number of element, node, mode or panel indices, nrow=1.
INDX.ELEM.FACE.T:id
INDX.ELEM.EDGE.T:id
Integer 2 row vector of element indices and associated element face or edge number. ncol=number of element indices, nrow=2.
MID.E
Integer vector of user assigned material property identifiers for each element. ncol=maximum number of elements, nrow=1.
NID.N
Integer vector of user assigned identifiers for each node. ncol=maximum number of nodes, nrow=1.
NORMAL.N
Real array of the components of normal vectors at nodes. ncol=maximum number of nodes, nrow=3. Each column j contains the components nx,ny,nz of the normal vector at the jth node expressed in the global coordinate system.
PARAMETER.HOL.T
Character valued active model parameters. Character strings are stored in Hollerith form, 4 characters per word.

col_1-20     Title
col_21-24    Originating code name
col_25-28    Originating code version
col_29-32    Origination time
col_33-36    Origination date
PARAMETER.IJK.T
Integer array of grid dimensions for a model containing one or more structured grids. ncol=number of grids in structured grid model, nrow=3. Column j contains the number of vertices in each of the I,J,K directions.

row_1        Number of vertices in I direction
row_2        Number of vertices in J direction
row_3        Number of vertices in K direction
PARAMETER.INT.T
Integer valued active model parameters.

col_1        Number of nodes
col_2        Number of elements
col_3        Dimensionality of model
col_4        Number of degrees of freedom per node
col_5        Number of material properties
col_6        Number of physical properties
col_7        Total number of active degrees of freedom
col_8        Total number of suppressed degrees of freedom
col_9        Analysis type
             =0          Unknown
             =1          Structural   (SYS_ANALYSIS_STRUCTURAL)
             =2          Thermal      (SYS_ANALYSIS_THERMAL)
             =3          Electric     (SYS_ANALYSIS_ELECTRIC)
             =4          Magnetic     (SYS_ANALYSIS_MAGNETIC)
             =5          Fluid        (SYS_ANALYSIS_FLUID)
             =6          Acoustic     (SYS_ANALYSIS_ACOUSTIC)
             =7          Diffusion    (SYS_ANALYSIS_DIFFUSION)
col_10       Solution type
             =0          Unknown
             =1          Static              (SYS_SOL_STATIC)
             =2          Vibration           (SYS_SOL_VIBRATION)
             =3          Buckling            (SYS_SOL_BUCKLING)
             =4          Transient           (SYS_SOL_TRANSIENT)
             =5          Superelement        (SYS_SOL_SUPERELEMENT)
             =6          Frequency response  (SYS_SOL_FREQRESPONSE)
             =7          Complex eigenvalue  (SYS_SOL_COMPLEXEIGEN)
col_11       2D type
             =0          Unknown
             =1          Plane strain          (SYS_PLANESTRAIN)
             =2          Plane stress          (SYS_PLANESTRESS)
             =3          Axisymmetric          (SYS_AXISYMMETRIC)
             =4          Axisymmetric Fourier  (SYS_AXISYMFOURIER)
col_12       Nonlinear flag
             =0          Linear
             =1          Nonlinear
col_13       Number of grids in structured grid model
col_14       Library type
PARTID.E
Integer vector of user assigned part identifiers for each element. Part identifiers are determined to be the most useful integer partitioning quantity for a finite element model. ncol=maximum number of elements, nrow=1.
PARTID.N
Integer vector of user assigned part identifiers for each node. ncol=maximum number of nodes, nrow=1.
PID.E
Integer vector of user assigned physical property identifiers for each element. ncol=maximum number of elements, nrow=1.
SET.ELEM.T:id
Integer vector of element indices assigned to element set identifier id. ncol=number of elements, nrow=1.
SET.ELEM.EDGE.T:id
Integer vector of element indices and edge numbers assigned to element edge set identifier id. ncol=number of elements, nrow=2.

row_1        Element index
row_2        Edge number
SET.ELEM.FACE.T:id
Integer vector of element indices and face numbers assigned to element face set identifier id. ncol=number of elements, nrow=2.

row_1        Element index
row_2        Face number
SET.NODE.T:id
Integer vector of node indices assigned to node set identifier id. ncol=number of nodes, nrow=1.
X.N
Real array of global coordinates of nodes. ncol=maximum number of nodes, nrow=3. Each column j contains the x,y,z global coordinates of the jth node.

Table of Contents

1.8 Finite Element Result Dataset Names and Descriptions

Results data may be resident on native and/or external libraries. If results data is resident on a native library, the native library interface uses binary direct access I/O to read data directly to memory resident data structures without transformation. If the results data resides on an external library, the data is meant to be able to be accessed logically in the same manner as native libraries. The external library interface contains several functions which have been designed for this purpose. The basic concept is to establish a dataset naming convention which maps dataset names to finite element results data residing on the external library. The physical layer of the external library interface must be written to access data from the external library in response to dataset access requests and perform any transformations necessary to reformat the data into the specified VdmTools data structure.

VdmTools supports finite element results data located at nodes, element centroids and element nodes. The results may be represented as conventional scalar, vector or symmetric tensor quantities. The special cases of stress resultants and strains in shell and beam elements are handled as well.

The data management system is designed to access, with any single request for results data, a result at all nodes or elements in the finite element model. For example, a single request for nodal temperatures expects a column of scalars representing the temperature at each node in the finite element model to be returned. Dataset names are mapped by convention to specific finite element results quantities which reside on the library. Dataset attributes are mapped to appropriate global variables associated with each dataset. An example of a global variable is the frequency of a vibration mode. As discussed earlier, VdmTools dataset names have the following syntax,

dataset_name:id1:id2:id3
The dataset name is an alphanumeric string consisting of two or more fields delimited by periods. The first field, termed the dataset root name, is chosen to reflect the contents of the datasets, such as TEMP for temperature and, SE_DENSITY for strain energy density. The last field must be one of several reserved strings which indicates the format of the dataset. Formats applicable to results quantities are .N (node array), .E (element array), and .EL (element node array). The dataset numeric identifiers may be used to indicate any appropriate identifiers such as load case, time step, load step, iteration, vibration or buckling mode, etc.

Very often there may be several variations of a specific result type such as temperature. For example there may be a quantity described as "Temperature Total". In this case the specific result type is temperature and "Total" is considered to be a qualifier. Qualifier strings are appended to the dataset root name enclosed in square brackets. The "Temperature Total" at elements for step one would then result in the following dataset name.

TEMP.[TOTAL].E:1
If the dataset contains the Complex attribute value of Imaginary or Phase, then the field, I, is appended to the dataset root name or the optional dataset qualifier. This is done in order to distinguish the dataset name from the dataset name containing the Complex attribute value of Real or Magnitude.

In some cases, a result quantity will appear on an external library for which there is no current predefined result type. If the external library contains a descriptive auxiliary string for the result quantity then the first two fields in the dataset name will be constructed consisting of the dataset root string UNKNOWN. followed by the descriptive auxiliary string treated as a qualifier. For example, an unknown element quantity with descriptive auxiliary string ViscosityMolecular would have the following dataset name.

UNKNOWN.[ViscosityMolecular].E:1
The Contents attribute contains an alphanumeric string which is a short description of the contents of the dataset.

The Title, Subtitle, Label and Sublabel attributes contain alphanumeric strings which are short descriptions of the dataset. These attributes are meant to range from the more general to the more specific descriptions of the dataset. More specifically, the Title and Subtitle attributes are associated with the overall model and the Label and Sublabel attributes are associated with solution steps. Some interfaces will also define up to four additional subtitles, ie. Subtitle1, Subtitle2, Subtitle3 or Subtitle4.

The DataSource attribute contains an alphanumeric string which indicates the primary source of the data contained in the dataset. This string may be a file name or a data block or record number, etc. depending on the technical nature of the interface.

The DataType attribute contains an alphanumeric string which specifies the mathematical data type of the contents of the dataset.

The Category attribute contains an alphanumeric string which qualifies the contents of the dataset. The Complex attribute contains an alphanumeric string which specifies the interpretation of the components of complex data types. The Link.Complex attribute which names the associated dataset containing the imaginary or phase part of the complex result. If only the real or magnitude part exists, then the Link.Complex Attribute will be omitted. Note that phase is always in degrees.

The StrainType attribute contains an alphanumeric string which specifies the specific interpretation of strain results. This attribute will only appear on results datasets containing strain. The shear strain components of engineering strain are twice the value of the corresponding components of tensor strain.

If the contents of a results dataset are expressed in a coordinate system other than the global coordinate system, then a Link.Cid global variable will be present and will point to a dataset of associated coordinate system identifiers for each node or element.

A complete list of supported result types are listed below. A defined constant is associated with each result type. The convention for defined constants is to prepend "SYS_RES_" to the dataset root. For example the defined constant SYS_RES_A refers to acceleration results. A data type is associated with each result type. It is possible for some result types with an associated vector data type in the table below to actually be either a vector (SYS_VECTOR) or sixdof (SYS_SIXDOF). data type. This is particularly true of Displacement type results. It is also possible for any result type to be either a scalar (SYS_SCALAR) or scalars (SYS_SCALARS) if the number of components representing the result does not match the default number of components for the data type.

The results dimensions use the following symbols for basic physical dimensions.

Specific Results Types
Dataset Root Data Type Contents Dimensions
A Vector Acceleration L/T2,Rad/T2
AREA Scalar Area L2
BODY_FORCE Vector Body Force M/L2T2
CAP_MAT Matrix Capacitance Matrix ML2/T2K
CHEM_SHRINKAGE Scalar Chemical Shrinkage None
CLOSURE Scalar Closure L
CODE_CHECK Scalar Code Check Value deprecate
CONC Scalar Concentration Unknown
COND Scalar Thermal Conductivity ML/T3K
COND_MAT Matrix Thermal Conductivity Matrix ML/T3K
CONV_COEF Scalar Convection Coefficient M/T3K
CP Scalar Specific Heat M2/KT2
CRACK_DENSITY Scalar Crack Density 1/L
D Vector Displacement L,Rad
DAMAGE Scalars Damage
DAMP Scalar Damping M/T
DECIBEL Scalar Decibel None
DELETED Scalar Deleted Entities None
DENS Scalar Density M/L3
DENS_GRAD Vector Density Gradient M/L4
DIR Vector Direction Vector None
DIR_COS GeneralTensor Direction Cosine Matrix None
DISP_CONTACT Vector Contact Displacement L
DIST Scalar Distance L
DOM_FLUID_PHASE Scalar Dominant Fluid Phase
D_MAT Matrix Damping Matrix M/T
E Tensor Strain None
ELEC_FIELD Vector Electric Field ML/T2Q
ELEC_FLUX Vector Electric Flux ML3/T2Q
ELEC_POT Scalar Electric Potential ML2/T2Q
ENERGY Scalar Energy ML2/T2
ENERGY_DENSITY Scalar Energy Density M/LT2
ENTROPY Scalar Entropy ML2/T2K
EN_FLUX Scalar Element Nodal Heat Flux ML2/T3
EN_FORC Vector Element Nodal Force ML/T2,ML2/T2
E_RATE Tensor Strain Rate 1/T
FACTOR Scalar Factor None
FAIL_INDEX Scalars Failure Index None
FAT_DAMAGE Scalar Fatigue Damage
FAT_DAMAGE_DIR Vector Fatigue Damage Direction None
FAT_LIFE Scalar Fatigue Life
FAT_SAFE_FACT Scalar Fatigue Safety Factor None
FILM_COEF Scalar Film Coefficient M/T3K
FLUENCE Scalar Fluence M/T2
FORCE Vector Force ML/T2
FORCE_MOMENT SixDof Force Moment ML/T2,ML2/T2
FRACTION Scalar Fraction None
FREQ Scalar Frequency Cyc/T
GAP Scalar Gap L
H Scalar Enthalpy ML2/T2
HEAT Scalar Heat Generated ML2/T2
HEAT_FLOW Scalar Heat flow ML2/T3
HEAT_FLUX Vector Heat Flux M/T3
HEAT_GRAD Vector Heat Gradient ML/T2
H_DOT Scalar Enthalpy Rate ML2/T3
ID Scalar Identifier None
INERTIA Tensor Rotary Inertia ML/Rad
INTENSITY Vector Intensity M/T3
J Scalar Current Q/T
J_DENSITY Vector Current Density Q/TL2
KE Scalar Kinetic Energy ML2/T2
KE_DENSITY Scalar Kinetic Energy Density M/LT2
KE_PERCENT Scalar Kinetic Energy Percent %
K_MAT Matrix Stiffness Matrix M/T2
LENGTH Scalar Length L
LOAD_FACT Scalar Load Factor None
L_VEC Vector Load Vector ML/T2
MACH Scalar Mach Number None
MAG_FIELD Vector Magnetic Field M/TQ
MAG_FLUX Vector Magnetic Flux M/TQ
MAG_POT Scalar Magnetic Potential ML/TQ
MARG_SAFE Scalar Margin of Safety None
MASS Scalar Mass M
MASS_FLOW Scalar Mass Flow M/T
MASS_FLUX Vector Mass Flux M/L2T1
MOMENT Vector Moment ML2/T2
MU_LAMB Scalar Mu Lambda
MU_TURB Scalar Mu Turbulent
M_MAT Matrix Mass Matrix M
NUMBER Scalar Number None
ORDER Scalar Order None
P Vector Momentum ML/T
PENE_CONTACT Scalar Contact Penetration L
PHASE_DIAMETER Scalar Phase Diameter
POISSONS_RATIO Scalar Poisson's Ratio None
POROSITY Scalar Porosity None
POWER Scalar Power ML2/T3
POWER_DENSITY Scalar Power Density M/LT3
PRANDTL Scalar Prandtl Number None
PRES Scalar Pressure M/LT2
PRES_COEF Scalar Pressure Coefficient None
PRES_DOT Scalar Pressure 1st Time Derivative M/LT3
PRES_DOTDOT Scalar Pressure 2nd Time Derivative M/LT4
PRES_GRAD Scalar Pressure Gradient M/L2T2
PROBABILITY Scalar Probability None
Q Scalar Electric Charge Q
QUAL_INDEX Scalar Quality Index deprecate
R Vector Reaction Force ML/T2,ML2/T2
RADIANCE Scalar Radiance M/T3
RADIUS Scalar Radius L
RC_PROD Scalar RC Product T
REACTION_PROGRESS Scalar Reaction Progress
REYNOLDS Scalar Reynolds Number None
ROTATION Vector Rotation Rad
ROT_ANG Vector Rotation Angle Vector Deg
ROUGHNESS Scalar Roughness L
R_HEAT_FLOW Scalar Reaction Heat Flow ML2/T3
R_J Scalar Reaction Current Q/T
R_MASS_FLOW Scalar Reaction Mass Flow M/T
R_Q Scalar Reaction Charge Q
S Tensor Stress M/LT2
SAFE_FACT Scalar Safety Factor None
SCALARS Scalars Scalars Unknown
SD Vector Element Displacement L
SDV Scalars Solution Dependent Variable Unknown
SE Scalar Strain Energy ML2/T2
SEK ElementResult Strain and Curvature Variable
SEP Scalar Separation L
SE_DENSITY Scalar Strain Energy Density M/LT2
SE_ERROR Scalar Strain Energy Error ML2/T2
SE_PERCENT Scalar Strain Energy Percent %
SF Vector Element Force ML/T2
SFM ElementResult Stress and Moment Resultant Variable
SHEAR_MODULUS Scalar Shear Modulus M/LT2
SOUND_LEVEL Scalar Sound Level SDRC
SOUND_MODEL Scalar Sound Wave Model Source
STAT Scalar Status None
STATE Scalar State None
STIFF Scalar Stiffness M/T2
STREAM Scalar Stream Function L2/T
STRENGTH_RATIO Scalars Strength Ratio None
STRENGTH_SAFE_FACT Scalar Strength Safety Factor None
S_ERROR_DENSITY Scalar Stress Error Density deprecate
TE Scalar Thermal Energy ML2/T2
TEMP Scalar Temperature K
TEMP_DOT Scalar Temperature 1st Time Derivative K/T
TEMP_GRAD Vector Temperature Gradient T/L
TEXP_COEF Scalar Thermal Expansion Coefficient 1/K
TE_DENSITY Scalar Thermal Energy Density M/LT2
TE_ERROR Scalar Thermal Energy Error ML2/T2
TF Vector Total Residual Force ML/T2
THICKNESS Scalar Element Thickness L
TIME Scalar Time T
TRAC Vector Traction M/LT2
TRANSLATION Vector Translation L
TURB_DIST Scalar Turbulent Distance L
TURB_ED Scalar Turbulent Energy Dissipation
TURB_KE Scalar Turbulent Kinetic Energy L2/T2
TURB_SD Scalar Turbulent Specific Dissipation
UNKNOWN Scalars Unknown Unknown
USER Scalar User Selected Variable Unknown
UTAU Scalar U Tau
V Vector Velocity L/T,Rad/T
VIEW_FACT Scalar View Factor None
VISC Scalar Viscosity M/LT
VISC_EDDY Scalar Eddy Viscosity M/LT
VOF Scalar Volume of Fluid
VOID_RATIO Scalar Void Ratio None
VOLT Scalar Voltage ML2/T2Q
VOLUME Scalar Volume L3
VOLUME_FLUX Scalar Volume Flux L/T
VORTICITY Vector Vorticity 1/T
V_DIV Scalar Velocity Divergence 1/T
V_GRAD GeneralTensor Velocity Gradient 1/T
WALL_SHEAR Vector Wall Shear M/LT2
WATER_ACCUM Scalar Water Accumulation Maya
WEIGHT Scalar Weight ML/T2
X Vector Position L
XF Vector External Applied Force ML/T2,ML2/T2
XF_HEAT_FLOW Scalar External Applied Heat Flow ML2/T3
XF_J Scalar External Applied Current Q/T
XF_MASS_FLOW Scalar External Applied Mass Flow M/T
XF_Q Scalar External Applied Charge Q
YOUNGS_MODULUS Scalar Young's Modulus M/LT2
YPLUS Scalar Y Plus None

Note that DELETED is defined as follows:

0.  active, not deleted
1.  deleted
Note that STATE is defined as follows:

0.  open and not near contact or simply open
1.  open and near contact
2.  closed and sliding or simply closed
3.  closed and sticking
4.  sealed
5.  leaked
6.  crushed
A complete list of supported specific qualifier types are listed below. Like result types, a defined constant is associated with each qualifier type. The convention for qualifier defined constants is to prepend "SYS_QUA_" to the dataset qualifier string. For example the defined constant SYS_QUA_MAG refers to the MAG qualifier. A dataset name may contain several qualifiers.

Specific Qualfier Types
Dataset Qualifier Contents
X X Component
Y Y Component
Z Z Component
MAG Magnitude
XX XX Component
YY YY Component
ZZ ZZ Component
XY XY Component
YZ YZ Component
ZX ZX Component
VONVISES Von Mises
NXX NXX Component
NYY NYY Component
NXY NXY Component
MXX MXX Component
MYY MYY Component
MXY MXY Component
QXY QXY Component
QZX QZX Component
TX X Translation
TY Y Translation
TZ Z Translation
RX X Rotation
RY Y Rotation
RZ Z Rotation
MINIMUM Minimum
MAXIMUM Maximum
INTERMEDIATE Intermediate
EFF Effective
TOT Total
INC Incremental
REL Relative
ABS Absolute
EQUIV Equivalent
PLAST Plastic
CREEP Creep
THERMAL Thermal
ELAST Elastic
INELAST Inelastic
REYNOLDS Reynolds
STAG Stagnation
CAUCHY Cauchy
PK Piola-Kirchhoff
LOG Logarithmic
TRESCA Tresca
YIELD Yield
MEAN Mean
NONLIN Nonlinear
TORSION Torsion
SWELLING Swelling
CRACKING Cracking
NORMAL Normal
SHEAR Shear
PSD Power Spectral Density
RMS Root Mean Square
NOM Nominal
COMPONENT Component
INTERLAMINAR Interlaminar
PLY Ply
BOND Bond
CONSTRAINT Constraint
PORE Pore
GASKET Gasket
CONTACT Contact
INITIAL Initial
FINAL Final
TENS Tension
COMP Compression
INFRARED Infrared
DIFFUSE Diffuse
COLLIMATED Collimated
SOLAR Solar
SOUND Sound
RADIATIVE Radiative
CONDUCTIVE Conductive
CONVECTIVE Convective
RESIDUAL Residual
ADJUSTED Adjusted
PSIDE Plus Side
MSIDE Minus Side
LOCAL Local
INTERNAL Internal
BULK Bulk
STATIC Static
DYNAMIC Dynamic
SLIP Slip
FREE Free
FORCED Forced
FLUID Fluid
HARMONIC Harmonic
LORENTZ Lorentz
BEARING Bearing
RADIAL Radial
TANG Tangential
AXIAL Axial
GREEN Green
MEANPRES Mean Pressure
DEFORM Deformation
GPF Element Grid Point
VISC Viscous
GLUE Glue
FRICTION Friction
SCALAR Scalar
PRINCIPAL Principal
NOZ Number of Zero Crossings
ATO Auto-correlation
CRM CRMS
SOURCE Source
SUM Sum
NET Net
ACOUSTIC Acoustic
RADIOSITY Radiosity
IRRADIANCE Irradiance
TRANSMITTED Transmitted
REFLECTED Reflected
INCIDENT Incident
ABSORBED Absorbed
SOLID Solid
DISSIPATED Dissipated
OPT Optimization
CONC Concentrated
DIST Distributed
ATTACHMENT Attachment
INERTIA Inertia
REDUCED Reduced
MODAL Modal
PARTICLE Particle
NEIGHBORS Neighbors
SHELL Shell
ERROR Error
NORM Norm
EIP Element Integration Point
PANEL Panel
LCR Level Crossing
PEAK Peak
DIFFERENCE Difference
CYCLIC Cyclic
SIN Sine
COS Cosine
MPC Multi-Point Constraint
TURB Turbulent
SYM Symmetric
ASYM ASymmetric
DAMAGE Damage
COHESIVE Cohesive
BOLT Bolt
CHOCKING Chocking
MECH Mechanical
ENTHALPY Enthalpy
FLAME Flame
GLASSTRANS Glass Transition
EMITTED Emitted
COUPLED Coupled
UNCOUPLED Uncoupled
STRUCT Structural
TRANSPORT Transport
WELD Weld
KIRCH Kirchhoff
NORMALIZED Normalized
APPLIED Applied
GYROSCOPIC Gyroscopic
DAMPING Damping
CIRCULATORY_FORCES Circulatory Forces
TSAI_HILL Tsai Hill
TSAI_WU Tsai Wu
HASHIN Hashin
STRESS Stress
STRAIN Strain
RICE_TRACEY Rice Tracey
HOFFMAN Hoffman
PUCK Puck
LARC04 Larc04
TRACTION Traction
PLANE_STRESS Plane Stress
FIBER Fiber
MATRIX Matrix
RATIO Ratio
VARIANT Variant
CRITICAL Critical
FULL Full
MATERIAL Material
AWEIGHT A Weighted
INACTIVE Inactive
OVERHEATING Overheating
UNCONVERGED Unconverged
VOLUME Volume
VIBE Vibration
PENETRATION Penetration
BIOT Biot
ENG Engineering
CG Center of Gravity
PARTICIPATION Participation
AERO Aeroelastic
MASS Mass
RIGID Rigid
UNIT Unit
RESTRAINED Restrained
UNRESTRAINED Unrestrained
HOMOGENIZED Homogenized

A complete list of supported valued qualifier types are listed below. The convention for valued qualifier defined constants is to prepend "SYS_QUAVAL_" to the dataset qualifier string before the = sign in capital letters. For example the defined constant SYS_QUAVAL_PHASE refers to the Phase= qualifier. A dataset name may contain several qualifiers.

Specific Valued Qualfier Types
SYS_QUAVAL_xxxxx Dataset Qualifier/Contents Value
CONTACTPAIR ContactPair=integer Contact Pair
DESIGNCYCLE DesignCycle=integer Design cycle
HARMONIC Harmonic=integer Harmonic number
INTPNT IntPnt=integer Element integration point number
MATERIAL Material=integer Material number
NODE Node=integer Node number
PHASE Phase=integer Chemical phase
ROTORSPEED RotorSpeed=real Rotor speed
SET Set=integer Set number
SECTION Section=integer Section number or BOT, MID, TOP
SPECIES Species=integer Species number
BOLTSEQUENCE BoltSequence=integer Bolt sequence number
STEP Step=integer Step identifier

Table of Contents

1.9 Finite Element Results at Section Points

The term "section point" refers to a set of results located at a point within an element which is not spanned by the connecting nodes. This type of point is used primarily for shell and beam type elements. For example stress data may be positioned at layers in a laminated shell element or points within the cross section of a beam element. In this case the dataset will have a Link.Section attribute which points to an integer element dataset containing the layer position type and number of section points per element. The dataset may also have a Link.Layers attribute which points to an integer dataset containing the layer position type and layer number of each section. The Link.Layers attribute is only present if the layer numbers in the element are not numbered sequentially from one. For example, a stress dataset with section data would appear as follows:

S.EL:1:1
 Link.Section = ELEM.SECT.E:1
If the layer numbers are not numbered sequentially from one, then a Link.Layers attribute will appear.

S.EL:1:1
 Link.Section = ELEM.SECT.E:1
 Link.Layers = ELEM.LAYS.T:1
An entry in the Link.Section dataset for an element consists of the layer position type and the number of sections. These two items are represented by 8 bit and 24 bit numbers and are concatenated together into a single integer. The layer position type is in the upper 8 bits and the number of sections is in the lower 24 bits. Possible layer position types are:

For example if the layer position type is SYS_LAYERPOSITION_BOTTOP and the number of sections is 10, this implies that there are 5 layers. The first section is the bottom of layer 1, the second section is the top of layer 1, the third section is the bottom of layer 2 and so on until the 10th section is the top of layer 5.

Elements which generally do not have multiple section points, such as solid elements, are given a layer position type of SYS_LAYERPOSITION_NONE and the number of sections is 1.

If there is a Link.Layers attribute, then there is an entry in the Link.Layers dataset for each section point at each element in ascending element index order. This implies that the length of this dataset is the sum of the number of section points indicated in the Link.Section dataset. An entry in the Link.Layers dataset consists of a layer position and a layer number. The possible layer position types are a subset of the layer position types listed above.

These two items are represented in a manner similar to the Link.Section dataset. The layer position type is in the upper 8 bits and the layer number is in the lower 24 bits. This limits the layer number to a non-negative value less than approximately 16 million. This dataset must be traversed serially using the number of sections for each element obtained from the Link.Section dataset.

If the layer position for an element in the Link.Section dataset is SYS_LAYERPOSITION_NONE, then the layer position is assumed to be in the Link.Layers dataset entry for the element.

Table of Contents

1.10 Finite Element Results at System Degrees of Freedom

The term system degree of freedom refers to a result associated with a specific degree of freedom (unknown) at a node or element and/or a generalized degree of freedom associated with a mode of some type, ie. vibration mode or residual load mode. Examples of system degrees of freedom are the x translation at a node or the pressure in an element. A dataset with results associated with system degrees of freedom is given a name with a .D suffix and requires a list of associated entities and degree of freedom types. In this case the dataset will have a Link.EntDof attribute which points to an integer dataset with two rows containing the entity index and degree of freedom type for each system degree of freedom. These datasets are useful for storing reduced mass and stiffness matrices resulting from some form of superelement generation.

For example, a superelement stiffness dataset with coefficients associated with specific degrees of freedom would appear as follows:

K_RED.D:1
 Link.EntDof = ENT.DOF.T:1
Table of Contents

1.11 Finite Element Results History Datasets

A results history dataset (or simply history dataset) contains a result for a small subset of a finite element model for many steps of a solution. This is in contrast to a full model results dataset which generally contains a result for an entire finite element model at a single step. For example, a single history dataset may contain the velocity for nodes 100,200 and 300 for every 10th time step from time steps 10 to 1000.

The rules for constructing a history dataset name and attributes for a particular result quantity are built upon the methodology used for a full model results dataset. All history dataset names start with the string HIST. The remaining fields are constructed in a manner identical to the syntax for a full model dataset for the same quantity (TEMP, SE_DENSITY, etc.) and format (.N, .E, .EL, etc.). The dataset numeric identifiers for a history dataset generally contain one less identifier than the corresponding full model results dataset. This is due to the fact that the last identifier in a full model results dataset is the single "step" value for which the corresponding history dataset will contain values for many steps.

A number of additional history datasets are required to hold the node or element indices of the history subset, the step numbers and any dataset attributes such as Time or Frequency. It is also possible that some components of a multi-dimensional data type, such as a vector or tensor data type, may be defined and others not defined. The results history dataset will contain link attributes which point to these additional history datasets. The following links are used.

Link.Index       node or element indices for subset
Link.Component   component defined/undefined flags
Link.Step        step numbers
Link.Time        step times
Link.Frequency   step frequencies
Link.LoadFactor  step load factors
For example, if a series of 100 results datasets for displacement at nodes for a transient response analysis were to exist as follows:

D.N:2:1
D.N:2:2
...
D.N:2:100
A corresponding time history dataset containing displacements for a subset of nodes for all 100 steps would be named as follows:

HIST.D.N:2
 Link.Index = INDX.NODE.T
 Link.Time = HIST.TIME.T:2
 Link.Step = HIST.STEP.T:2
For node array format, .N, or element array format, .E, ncol=number of nodes or elements and nrow=number of data type components. In general, the number of steps is must be computed as the length of the Link.Step dataset. However, in the case of rectangular array format the number of steps can be computed by dividing the record length, lrec , by ncol*nrow. The order of the data in history datasets is the data components of the first entity at all steps followed by the data components of the second entity at all steps, etc.

The node indices of the subset are placed in the following dataset.

INDX.NODE.T
The associated dataset attributes such as Time, Frequency which may exist for the history of steps are placed in separate history datasets.

HIST.TIME.T:2
 Link.Step = HIST.STEP.T:2
HIST.FREQUENCY.T:2
 Link.Step = HIST.STEP.T:2
Certain quantities such as strain energy for the whole model are placed in separate history datasets.

HIST.SE.T:2
 Link.Time = HIST.TIME.T:2
 Link.Step = HIST.STEP.T:2
The step numbers themselves, in this case 1,2,...,100, are placed in a separate integer valued history dataset.

HIST.STEP.T:2
If only a subset of the vector components are defined for certain nodes, then the defined component flags for the velocity components of each node are placed in a dataset and a link attribute is created as follows.

 Link.Component = COMP.N:1
The dataset, COMP.N:1, contains an integer flag for each component of the vector data for each node. The value will be 0 if the component is undefined. The component flags dataset itself is, in general, a sparse dataset and will therefore have a link to the defined indices.

COMP.N:1
 Link.Index = INDX.NODE.T

Table of Contents

1.12 Monitor Functions

The user may define a monitor function to track the progress of an interface as it opens a file or reads data from the file. The file opening operation, vdm_DataFunOpen, can be particularly time consuming. The opening operation generally reads and develops the basic simulation model first and then continues to build a list of the simulation results.

Using a monitor function, the progress may be monitored by querying for the progress phase and source. The phase may be one of three integer values, VDM_PHASE_OPENMODEL, VDM_PHASE_OPENMODELCOMPLETE and VDM_PHASE_OPENRESULT. The source is an interface dependent string which describes the current position in the file which is being read. The phase is queried using the function vdm_DataFunGetInteger with type VDM_PHASE and the source is queried using the function vdm_DataFunGetString with type VDM_SOURCE. When the phase value is VDM_PHASE_OPENMODELCOMPLETE the model construction is complete and the user may load the model and return to allow the opening of the simulation results.

Because of the appearance of the interface object as the first argument in the monitor function, a separate callback function must be defined for each interface that requires monitoring. For example, the NASLib interface monitor function is set in NASLib using vdm_NASLibSetFunction. A similar methodology is used for all interface objects.


Table of Contents

1.13 Multiple Domains

Some file types support multiple domains, usually associated with a domain decomposition for a parallel solution. It is possible to query for the number of domains and then open each domain separately, instancing an interface object and an associated DataFun object for each one. This allows the individual domains to be opened and read in parallel.

The vdm_DataFunNumDomains function may be called to perform a scan to determine the number of domains. The number of domains is returned. If a library device does not support multiple domains, then the number of domains will be zero. If a non-zero number of domains is returned then vdm_DataFunOpen may then be called with mode set to zero to open all domains or with mode > 0 indicating the specific domain number to open. If the number of domains is returned as zero, then vdm_DataFunOpen must be called with mode set to zero to open the library device.


Table of Contents

1.14 A First Program

As an example of a simple VdmTools application the following program illustrates reading the node coordinates from an SDRC Universal file. Initially a SDRCLib library device object and an associated DataFun object are created. The DataFun object is loaded with function pointers by the SDRCLib object. At this point all further data access of the library device is handled through the data function object.

The library device is opened and attached to a SDRC Universal file residing on file bumper.unv. The library name, "Bumper", is completely arbitrary. Opening a library device is often the most time consuming operation performed on a library. In general the library file must be completely scanned to determine the number and type of datasets, number of nodes and elements, etc. At this point the library device may be queried for dataset information. First the number of nodes are queried. Next, in order to begin to query for the existence of datasets, the internal Library object used by the library device must be retrieved. The Library object is searched for the reserved dataset name for node coordinates, X.N. The dataset indices and number of datasets which satisfy the search are returned. In this case only a single dataset is found. Every library device should contain the node coordinate dataset, X.N, as part of the basic finite element model description. The node coordinates are read into memory and the first and last node coordinates are printed.

Finally the library device is closed and the DataFun and SDRCLib objects are destroyed. Note that the Library object does not "belong" to the user (was not instanced by the user) and therefore must not explicitly destroyed by the user.

#include <stdio.h>
#include <stdlib.h>
#include "base/base.h"
#include "vdm/vdm.h"

/*----------------------------------------------------------------------
                     Read and Print Finite Element Node Coordinates
----------------------------------------------------------------------*/
int
main()
{
   vdm_SDRCLib *sdrclib;
   vdm_DataFun *datafun;
   vdm_Library *library;
   Vint filetype;
   Vint numnp;
   Vint ndsts;
   Vint idst;
   Vfloat *px;
   Vint ind;

                   /* create data function object */
   datafun = vdm_DataFunBegin ();

                   /* create SDRC Universal File library device */
   filetype = VDM_SDRC_UNIVERSAL;
   sdrclib = vdm_SDRCLibBegin ();
   vdm_SDRCLibDataFun (sdrclib,datafun);

                   /* open library device */
   vdm_DataFunOpen (datafun,0,"bumper.unv",filetype);

                   /* get number of nodes */ 
   vdm_DataFunGetNumEntities (datafun,SYS_NODE,&numnp);

                   /* get library object */ 
   vdm_DataFunGetLibrary (datafun,&library);

                   /* search for node coordinate dataset */
   vdm_LibrarySearchDataset (library,"X.N",1,&idst,&ndsts);

                   /* allocate memory for coordinates */ 
   px = (Vfloat*) malloc(3*numnp * sizeof(Vfloat));

                   /* read node coordinates */ 
   vdm_DataFunReadDataset (datafun,idst,px);

                   /* print first and last node coordinates */ 
   printf("Node Coordinates\n");
   ind = 0;
   printf("%10d %12f %12f %12f\n",1,px[ind],px[ind+1],px[ind+2]);
   ind = 3*(numnp-1);
   printf("%10d %12f %12f %12f\n",numnp,px[ind],px[ind+1],px[ind+2]);
                   /* free memory */ 
   free(px);

                   /* close library device */ 
   vdm_DataFunClose (datafun);

                   /* free objects */ 
   vdm_DataFunEnd (datafun);
   vdm_SDRCLibEnd (sdrclib);
   return 0;
}
The output of this example program appears below.
Node Coordinates
         1    30.826799     3.968360    -1.003940
       652   -47.007900    15.984300    -2.007870

Table of Contents

1.15 A First Program - C++ Version

The following program is a listing of the C++ version of the same "A First Program" listed above which used C language bindings.

#include <stdio.h>
#include <stdlib.h>
#include "base/base.h"
#include "vdm/vdm.h"

/*----------------------------------------------------------------------
                     Read and Print Finite Element Node Coordinates
----------------------------------------------------------------------*/
int
main()
{
   vdm_SDRCLib *sdrclib;
   vdm_DataFun *datafun;
   vdm_Library *library;
   Vint filetype;
   Vint numnp;
   Vint ndsts;
   Vint idst;
   Vfloat *px;
   Vint ind;

                   /* create data function object */
   datafun = new vdm_DataFun ();

                   /* create SDRC Universal File library device */
   filetype = VDM_SDRC_UNIVERSAL;
   sdrclib = new vdm_SDRCLib ();
   sdrclib->DataFun (datafun);

                   /* open library device */
   datafun->Open (0,"bumper.unv",filetype);

                   /* get number of nodes */ 
   datafun->GetNumEntities (SYS_NODE,&numnp);

                   /* get library object */ 
   datafun->GetLibrary (&library);

                   /* search for node coordinate dataset */
   library->SearchDataset ("X.N",1,&idst,&ndsts);

                   /* allocate memory for coordinates */ 
   px = (Vfloat*) malloc(3*numnp * sizeof(Vfloat));

                   /* read node coordinates */ 
   datafun->ReadDataset (idst,px);

                   /* print first and last node coordinates */ 
   printf("Node Coordinates\n");
   ind = 0;
   printf("%10d %12f %12f %12f\n",1,px[ind],px[ind+1],px[ind+2]);
   ind = 3*(numnp-1);
   printf("%10d %12f %12f %12f\n",numnp,px[ind],px[ind+1],px[ind+2]);
                   /* free memory */ 
   free(px);

                   /* close library device */ 
   datafun->Close ();

                   /* free objects */ 
   delete datafun;
   delete sdrclib;
   return 0;
}