Dataset Specification and Management

Datasets are the core unit for organizing and accessing data in HOOPS Access. Each dataset provides a consistent way to name and structure simulation results, metadata, and other values. By following a clear naming and specification convention, you can reliably identify, retrieve, and interpret data across contexts such as load steps, increments, and modes.

This guide defines the dataset specification, including naming conventions, numeric identifiers, expansion rules, parameters, attributes, and supported formats.

Dataset Specification Syntax

Datasets are identified by name, and a dataset specification follows the format:

dataset_name:id1:id2:id3

Dataset Name (dataset_name)

The dataset name is a character string that may include letters, digits, and the special characters . (period), $ (dollar sign), and _ (underscore).

  • The period (``.``) is commonly used to divide the name into multiple fields.
  • By convention, the last field (following the final period) indicates the data structure.
  • A dataset name cannot exceed 256 characters.

Examples of valid dataset specifications:

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

Numeric Identifiers (:id1:id2:id3)

Numeric identifiers are positive integers, separated from the dataset name and from each other using a colon (:).

  • They are optional, though one or more are usually included.
  • Their interpretation depends on context (e.g., load step number, time step, increment, vibration mode, buckling mode).

Example: Node displacements at load step 3, increment 2 on an ABAQUS .fil database:

D.N:3:2

Dataset Specification Expansion

In many cases, it is useful to refer to a group of related datasets with a single specification, or to abbreviate a specific dataset with a unique substring. This is achieved with dataset name expansion.

Expansion works on both the dataset name and numeric identifiers, using a syntax similar to UNIX filename expansion.

Wildcards

The following substitutions are supported:

  • * → Matches any string of characters (including empty).
  • ? → Matches exactly one character.
  • ( ) → Encloses a set of matching characters.
    • If the first character is ^, the match is negated.
    • S-E specifies all characters from S through E (inclusive).

Examples:

D*

Matches all datasets starting with D.

*:(2-4)

Matches all datasets associated with solution steps 2, 3, and 4.

Numeric Identifier Ranges

Numeric ranges are specified as:

FiTjBk

Where:

  • Fi = starting index
  • Tj = ending index
  • Bk = increment

Example:

D.N:F1T49B2

Matches:

D.N:1, D.N:3, D.N:5, ... D.N:49

Highest and Lowest Identifiers

The letters H (highest) and L (lowest) can be used to select the first or last identifier.

Example:

S.EL:H

Matches the dataset S.EL.n, where n is the highest solution step.

Combining Wildcards and Ranges

Wildcards can be combined with ranges.

Example:

D.N:H:*

Matches displacement datasets at the last iteration of each load step.

Dataset Parameters and Attributes

Every dataset has associated parameters and attributes.

  • Parameters describe the dataset’s physical characteristics, structure, and type.
  • Attributes provide metadata that further describe or refine the dataset.

Dataset Parameters

Parameters define the dataset’s size and structure:

  • lrec → Record length (in units of data type size)
  • nrow → Number of rows
  • ncol → Number of columns
  • ntyp → Data type
  • natt → Number of dataset attributes

The total dataset size (in bytes) is:

Total size = record length x size of data type

Supported Data Types (ntyp)

=1  Integer                  (Vint)        (SYS_INTEGER)
=2  Real, single precision   (Vfloat)      (SYS_FLOAT)
=3  Hollerith (character)    (Vuint)       (SYS_HOLLERITH)
=4  Real, double precision   (Vdouble)     (SYS_DOUBLE)
=6  Complex, single precision (Vfloat[2])  (SYS_COMPLEX)
=7  Complex, double precision (Vdouble[2]) (SYS_DOUBLECOMPLEX)

Dataset Attributes

Attributes are metadata that describe a dataset.

  • Attribute names are ≤ 16 characters
  • The period (.) is often used to separate fields

Examples:

Link.Size
Link.Index
Link.Complex
Link.Cid
Link.Section
Link.Layers

Constraints:

  • Max 16 integers or floats
  • Max 8 double-precision numbers
  • Max 256 characters
  • Attribute values must be homogeneous

Data Structures

The data management system supports two primary data structures:

  1. Rectangular Array
  2. Variable Row Array

Other structures are defined by using dataset attributes to link datasets.

Rectangular Array

  • Dimensions: nrow x ncol
  • Data type: ntyp
  • Storage: row-major
  • Columns start at 1

Sparse storage is supported using:

Link.Index     integer vector of column indices

Example: Sparse Array

Non sparse format     Sparse format    Indices
--         --         --         --    -- --
| 0.  | 0.  |         | 2.1 | 1.5 |    | 2 |
| 2.1 | 1.5 |         | 4.0 | 6.0 |    | 4 |
| 0.  | 0.  |         --         --    -- --
| 4.0 | 6.0 |
--         --

Element Face/Edge Variation

Used for element face/edge data. Always sparse, with:

Link.Index     integer 2-row vector of element indices + entity number

Variable Row Array

Columns may contain different row lengths.

  • nrow → number of components OR maximum rows per column
  • ncol → number of columns
  • Structure attribute defines meaning:
    • VariableRow
    • ElementNode
    • ElementIP
    • ElementFaceNode
    • ElementEdgeNode
    • LowerTriangle
    • Diagonal

VariableRow Example:

Link.Size     integer vector of column lengths (length = ncol)

ElementNode Example:

nrow x (nodes per element from ELEM.SIZE.E) x (sections from Link.Section)

Link.Section   integer vector of section lengths

ElementIP Example:

nrow x (integration points per element from ELEM.EIPS.E) x (sections from Link.Section)

ElementFaceNode/ElementEdgeNode Example:

  • Always sparse
  • Indexed with:
Link.Index     integer 2-row vector of element indices + entity number

LowerTriangle/Diagonal Example:

  • Columns = degrees of freedom in set
  • Lower triangular matrices stored by rows

Dataset Formats

HOOPS Access uses dataset naming conventions to indicate both structure and data class. These conventions are called formats.

Node Array (.N)

Rectangular arrays at nodes.

  • Rows = items per node (e.g., scalar, vector)
  • Columns = number of nodes

Examples: coordinates, displacements, normals.

Element Array (.E)

Rectangular arrays at elements.

Examples: element stresses, temperatures.

Element Node Array (.EL)

Variable column length arrays at element nodes.

Examples: connectivity, stress results.

Element Integration Point Array (.EIP)

Variable column length arrays at integration points.

Examples: stress/strain at integration points.

Element Face/Edge Arrays (.EF, .EE, .EFN, .EEN)

Store data at element faces, edges, face nodes, and edge nodes.

Degree of Freedom (.D)

System-wide DOF data.

  • Structure = LowerTriangle or Diagonal

Example: reduced stiffness matrices.

Mode Format (.MOD)

Rectangular arrays associated with modes.

Examples: frequencies, generalized mass.

Particle Format (.PCL)

Rectangular arrays at particles (point objects).

  • Columns = number of particles
  • Never indexed

Examples: physical particles, visualization points.

Contact Pair Format (.CPR)

Rectangular arrays for contact pairs.

Panel Format (.PNL)

Rectangular arrays for panels.

Table Format (.T)

Rectangular arrays for miscellaneous objects.

  • Rows = items per object
  • Columns = number of objects

Examples: coordinate systems, material properties.

Table Variable Row (.TL)

Variable row arrays for generic entities.

Library Dataset (.L)

Contains a sublibrary (like a Linux directory). To make current:

vdm_DataFunLibDataset

Examples:

REMESH.L:ith    → Adaptive mesh model
SEMESH.L:seid   → Superelement recovery mesh
GEOMESH.L       → Tessellated geometry model

Complex Result Datasets

Complex results may be stored as:

  • Real-Imaginary
  • Magnitude-Phase

Naming convention: the imaginary/phase dataset adds .I after the real/magnitude dataset name.

Attributes:

  • Complex = Real | Imaginary | Magnitude | Phase
  • Link.Complex points to the paired dataset

Example: Displacement with Magnitude + Phase

D.N:1:1
  Complex = Magnitude
  Link.Complex = D.I.N:1:1

D.I.N:1:1
  Complex = Phase

Finite Element Model Dataset Names and Descriptions

Datasets appearing in native and external libraries follow a consistent naming convention and adhere to one of the basic data structures described in the previous section. Each model dataset includes a Model attribute, whose character value identifies the class of model data contained in the dataset.

Possible values for the Model attribute include:

  • Mesh
  • Element Data Arrays
  • Node Sets
  • Element Sets
  • Element Entity Sets
  • Load Cases
  • Restraint Cases
  • Multipoint Constraint Cases
  • Initial Condition Cases
  • Global Properties
  • Material Properties
  • Element Properties
  • Solution Properties
  • Function Properties
  • Units
  • Coordinate Systems
  • Analytical Surfaces
  • Contact Pairs

Each model dataset also includes a Description attribute, providing a concise summary of its contents.

The following sections describe common Mesh-related model datasets.

Model Datasets

COLORID.E / COLORID.N

Integer vectors defining object colors for each object type.

  • ncol = maximum 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

Column j stores red, green, and blue intensities in the range [0.0, 1.0] for color map identifier j.

CSYS.T

Real array defining the origin and orientation of coordinate system objects.

  • nrow = 12
  • ncol = maximum number of coordinate systems

Column j defines coordinate system j:

row_1-3 Global coordinates of system origin
row_4-12 Direction cosines of coordinate system axes

CSYS.TYPE.T

Integer vector of coordinate system types.

  • ncol = maximum number of coordinate systems
  • nrow = 1
row_1        Coordinate system type, type
            =1          Rectangular        (SYS_CARTESIAN)
            =2          Cylindrical        (SYS_CYLINDRICAL)
            =3          Spherical (a)      (SYS_SPHERICAL)
            =4          Spherical (b)      (SYS_SPHERICAL_ALT)
            =5          Toroidal           (SYS_TORODIAL)

CSYS.ID.T

Integer vector of user-assigned IDs for each coordinate system.

  • ncol = maximum number of coordinate systems
  • nrow = 1

DOF.CID.N

Integer vector of coordinate system identifiers for nodal degrees of freedom.

  • ncol = maximum number of nodes
  • nrow = 1

EID.E

Integer vector of user-assigned element identifiers.

  • ncol = maximum number of elements
  • nrow = 1

ELEM.NODE.EL

Variable row array of element node connectivity.

  • ncol = maximum number of elements
  • nrow = maximum length of connectivity

Connectivity references internal node ordering.

Pointers and sizes are defined in:

  • ELEM.NODE.PNTR.E
  • ELEM.NODE.SIZE.E

ELEM.SHAP.E

Integer vector of element shape codes.

  • ncol = maximum number of elements
  • nrow = 1

See VisTools, Computational Cells.

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 describing element order.

  • ncol = maximum number of elements
  • nrow = 3

Each column defines:

  • maxi = nodes in I direction
  • maxj = nodes in J direction
  • maxk = nodes in K direction

ELEM.SPEC.E

Integer vector of element-specific types (distinguishes variations within general types).

  • ncol = maximum number of elements
  • nrow = 1

See VisTools, Element Types.

ELEM.TYPE.E

Integer vector of internal element type codes.

  • ncol = maximum number of elements
  • nrow = 1

Use with ELEM.SPEC.E for variations. See VisTools, Element Types.

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

ELEM.TYPE.EXT.E

Integer vector of external element type IDs (from originating FE system, e.g., ANSYS element routine number).

  • ncol = maximum number of elements
  • nrow = 1

ELEM.TYPE.HOL.E

Character vector of external element names (8 chars). Stored in Hollerith form, 4 chars per word.

  • ncol = maximum number of elements
  • nrow = 2

ERS.CID.E

Integer vector of element local coordinate system IDs. Referenced by element results to indicate result coordinate system.

  • ncol = maximum number of elements
  • nrow = 1

See VisTools, 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
            =SYS_ELEMSYS_CYLINDRICAL_ALT Alternate Cylindrical

ERS.VEC.E

Real array of global coordinates for element orientation vectors.

  • ncol = maximum number of elements
  • nrow = 3

INDX.* Datasets

Index datasets:

  • INDX.ELEM.T:id
  • INDX.NODE.T:id
  • INDX.MODE.T:id
  • INDX.PANEL.T:id

Integer vectors of indices. ncol = number of element, node, mode or panel indices, nrow = 1.

Face/edge indices:

  • INDX.ELEM.FACE.T:id
  • INDX.ELEM.EDGE.T:id

Integer 2-row vectors of element index + face/edge number.

MID.E

Integer vector of material IDs per element.

  • ncol = maximum number of elements
  • nrow = 1

NID.N

Integer vector of user-assigned node IDs.

  • ncol = maximum number of nodes
  • nrow = 1

NORMAL.N

Real array of nodal normal vector components.

  • ncol = maximum number of nodes
  • nrow = 3

PARAMETER.HOL.T

Character-valued active model parameters (Hollerith encoding).

col_1-20 Title
col_21-24 col_25-28 col_29-32 col_33-36 Originating code name Originating code version Origination time Origination date

PARAMETER.IJK.T

Integer array of structured grid dimensions for a model containing one or more structured grids. ncol = number of grids in the 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 (nodes, elements, DOFs, etc). Includes analysis type, solution type, 2D type, nonlinear flag, etc.

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 / PARTID.N

Integer vectors of part identifiers per element or node. nrow = 1, ncol = max elements/nodes.

PID.E

Integer vector of physical property IDs per element. nrow = 1, ncol = max elements.

SET.ELEM.T:id

Integer vector of element indices in element set id.

SET.ELEM.EDGE.T:id

Integer 2-row vector of element indices + edge numbers for set id.

SET.ELEM.FACE.T:id

Integer 2-row vector of element indices + face numbers for set id.

SET.NODE.T:id

Integer vector of node indices in node set id.

X.N

Real array of global node coordinates.

  • nrow = 3
  • ncol = maximum number of nodes

j``th column = (x, y, z) of node ``j.

Finite Element Result Dataset Names and Descriptions

Results data may reside on native or external libraries.

  • On native libraries, the interface uses binary direct-access I/O to read data directly into memory-resident data structures without transformation.
  • On external libraries, the data is accessed logically in the same manner as native libraries. The external library interface must map dataset names to result data and perform any transformations necessary to reformat the data into the specified HOOPS Access data structure.

HOOPS Access supports results data at nodes, element centroids, and element nodes. The results may be scalars, vectors, or symmetric tensors. Special cases such as stress resultants and strains in shells and beams are also handled.

The system is designed so that a single request returns a result for all nodes or all elements in the model. For example, requesting nodal temperatures returns a column of scalars with one temperature value per node.

Dataset Naming Conventions

Dataset names are mapped by convention to specific results. The general syntax is:

dataset_name:id1:id2:id3
  • The root name (first field) indicates the result type.
    • Example: TEMP (temperature), SE_DENSITY (strain energy density)
  • The last field indicates the dataset format, such as:
    • .N → node array
    • .E → element array
    • .EL → element node array
  • Numeric identifiers (:id1:id2:id3) indicate load case, step, iteration, vibration mode, buckling mode, etc.

Example with qualifier:

Specific variations (e.g., Temperature Total) use qualifiers in brackets:

TEMP.[TOTAL].E:1

Complex results:

If the dataset has the Complex attribute = Imaginary or Phase, an ``.I`` field is appended to distinguish it from real/magnitude datasets.

Example:

D.I.N:1:1

Unknown results:

If the external library has no predefined result type, the dataset root is UNKNOWN. followed by the auxiliary descriptive string.

UNKNOWN.[ViscosityMolecular].E:1

Result Dataset Attributes

Several attributes refine result datasets:

  • Contents

    Short description of dataset contents.

  • Title / Subtitle / Label / Sublabel

    Text descriptions (from general to specific).

    • Title, Subtitle → model-level
    • Label, Sublabel → solution-step level
    • Some interfaces may also define Subtitle1-Subtitle4

  • DataSource

    Indicates the origin of the dataset (e.g., filename, block, record).

  • DataType

    Specifies the mathematical type of the result:

    Scalar single component
    Vector x, y, z
    Tensor xx, yy, zz, xy, yz, zx
    GeneralTensor xx, xy, xz, yx, yy, yz, zx, zy, zz
    ElementResult Beams - Nxx, Myy, Mzz, Torque, Qxy, Qzx, TBimom
    Beams - Exx, Kyy, Kzz, Twist, Txy, Tzx, TBicur
    Shells - Nxx, Nyy, Nxy, Mxx, Myy, Mxy, Qxz, Qyz
    Shells - Exx, Eyy, Exy, Kxx, Kyy, Kxy, Txz, Tyz
    Spring - Fx, Fy, Fz, Mx, My, Mz
    Spring - Ex, Ey, Ez, Kx, Ky, Kz
    Scalars multiple scalar components
    SixDof Tx, Ty, Tz, Rx, Ry, Rz

  • Category

    Qualifies the type of solution:

    Buckling Buckling mode
    Vibration Vibration mode
    Static Static solution
    Transient Transient solution
    Constraint Unit applied DOF mode
    ConcentratedLoad Single DOF concentrated load mode
    DistributedLoad Distributed load mode

  • Complex

    Defines interpretation of complex results:

    Real Real part of real-imaginary results
    Magnitude Magnitude part of magnitude-phase results
    Imaginary Imaginary part of real-imaginary results
    Phase Phase part of magnitude-phase results (degrees)

    If both real/magnitude and imaginary/phase parts exist, the real or magnitude dataset contains a Link.Complex attribute pointing to the associated dataset.

  • StrainType

    Specifies interpretation of strain results (applies only to strain datasets):

    Tensor Tensor strain
    Engineering Engineering strain (shear = 2 × tensor shear)

  • Link.Cid

    If results are expressed in a local coordinate system, this points to a dataset containing coordinate system IDs for each node/element.

Result Types and Conventions

Each supported result type has an associated defined constant (prepended with SYS_RES_).

  • Example: SYS_RES_A = Acceleration

A default data type is associated with each result type. In some cases, results may appear in alternate forms (e.g., Displacement may be Vector or SixDof). Any result type may also appear as Scalar or Scalars if its number of components does not match the default definition.

Physical Dimensions

Physical dimension symbols used in results:

  • None → Dimensionless
  • Unknown → Unknown dimensions
  • Variable → Variable dimensions
  • M → Mass
  • L → Length
  • T → Time
  • Q → Charge
  • K → Temperature
  • % → Percent
  • Rad → Radians
  • Deg → Degrees
  • Cyc → Cycles

Specific Result Types

The following table lists all supported result types, their dataset root names, associated data types, content descriptions, and physical dimensions.

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
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/L2T
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

Notes

DELETED is defined as:

0  Active, not deleted
1  Deleted

STATE is defined as:

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

Specific Qualifier Types

A complete list of supported qualifier types is shown below. Like result types, each qualifier type has an associated defined constant. The convention for qualifier constants is to prepend SYS_QUA_ to the dataset qualifier string.

For example, the defined constant SYS_QUA_MAG corresponds to the MAG qualifier.

A dataset name may contain multiple qualifiers, combined as needed to fully describe the results.

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
SHEARPANEL Shear Panel
BENDING Bending

Specific Valued Qualifier Types

A complete list of supported valued qualifiers is shown 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 corresponds to the qualifier Phase=.

A dataset name may contain multiple qualifiers, combined as needed.

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

Finite Element Results at Section Points

The term section point refers to a set of results located within an element but not at a connecting node. Section points are used primarily for shell and beam type elements.

For example, stress data may be positioned at layers in a laminated shell or at points across a beam cross-section.

Dataset Attributes

A results dataset with section data will include special attributes:

  • Link.Section → Points to an integer element dataset describing layer position type and number of section points per element.
  • Link.Layers → (Optional) Points to an integer dataset containing the layer position type and layer number of each section. This appears only if layer numbering is non-sequential.

Example 1: With sequential layers

S.EL:1:1
 Link.Section = ELEM.SECT.E:1

Example 2: With non-sequential layers

S.EL:1:1
 Link.Section = ELEM.SECT.E:1
 Link.Layers  = ELEM.LAYS.T:1

Supported Layer Position Types

  • SYS_LAYERPOSITION_NONE → 0, unknown (generic section)
  • SYS_LAYERPOSITION_MID → Mid layer
  • SYS_LAYERPOSITION_BOTTOP → Bottom and top of layer
  • SYS_LAYERPOSITION_BOTMIDTOP → Bottom, middle, and top of layer
  • SYS_LAYERPOSITION_INTPNT → Integration point
  • SYS_LAYERPOSITION_BOTMID → Bottom and middle of layer
  • SYS_LAYERPOSITION_MIDTOP → Middle and top of layer
  • SYS_LAYERPOSITION_BOT → Bottom of layer
  • SYS_LAYERPOSITION_TOP → Top of layer
  • SYS_LAYERPOSITION_B1M → Between bottom and middle
  • SYS_LAYERPOSITION_M1T → Between middle and top
  • SYS_LAYERPOSITION_B5T → Bottom, B1M, Middle, M1T, Top of layer

Example:

If layer position = SYS_LAYERPOSITION_BOTTOP and number of sections = 10, this implies 5 layers: bottom/top pairs for each.

Note

Solid elements typically use SYS_LAYERPOSITION_NONE with sections = 1.

Supported Layer Position Types (subset)

  • SYS_LAYERPOSITION_NONE → Unknown, generic section
  • SYS_LAYERPOSITION_MID → Mid layer
  • SYS_LAYERPOSITION_INTPNT → Integration point
  • SYS_LAYERPOSITION_BOT → Bottom of layer
  • SYS_LAYERPOSITION_TOP → Top of layer
  • SYS_LAYERPOSITION_B1M → Between bottom and middle
  • SYS_LAYERPOSITION_M1T → Between middle and top

If Link.Section uses SYS_LAYERPOSITION_NONE, then the layer position must be derived from Link.Layers instead.

Finite Element Results at System Degrees of Freedom

A system degree of freedom (DOF) refers to a result associated with a specific degree of freedom at a node or element, or with a generalized degree of freedom such as a vibration mode or residual load mode.

Examples include:

  • The x-translation at a node
  • The pressure within an element

Datasets containing results tied to system DOFs use the .D suffix and require an associated mapping of entities and DOF types.

Attributes

  • Link.EntDof → Points to an integer dataset with two rows:
    • Row 1: Entity index
    • Row 2: Degree of freedom type

This mapping ensures that each dataset entry corresponds precisely to a defined entity-DOF pair.

Example

A superelement stiffness dataset with coefficients tied to specific DOFs would appear as:

K_RED.D:1
  Link.EntDof = ENT.DOF.T:1

These datasets are particularly useful for storing reduced mass and stiffness matrices resulting from superelement generation.

Finite Element Results History Datasets

A results history dataset (or history dataset) contains results for a small subset of a finite element model across many solution steps.

This contrasts with a full model results dataset, which typically represents an entire finite element model at a single solution step.

Key Characteristics

  • History datasets begin with the prefix HIST.
  • Remaining fields follow the same naming syntax as the corresponding full-model dataset (e.g., TEMP, SE_DENSITY, etc.), including format suffixes (.N, .E, .EL).
  • Numeric identifiers usually contain one fewer identifier than full-model datasets, since history datasets represent multiple steps rather than a single step.

Additional Required Datasets

History datasets are linked to auxiliary datasets that store metadata such as indices, steps, and attributes:

Link.Index       → Node or element indices for the subset
Link.Component   → Flags for defined/undefined components
Link.Step        → Step numbers
Link.Time        → Step times
Link.Frequency   → Step frequencies
Link.LoadFactor  → Step load factors

Example

Suppose we have 100 displacement result datasets:

D.N:2:1
D.N:2:2
...
D.N:2:100

A corresponding time history dataset for a subset of nodes across all 100 steps would be defined as:

HIST.D.N:2
  Link.Index = INDX.NODE.T
  Link.Time  = HIST.TIME.T:2
  Link.Step  = HIST.STEP.T:2

Data Layout

  • For .N (node array) or .E (element array):
    • ncol = number of nodes/elements
    • nrow = number of data type components
  • The number of steps is typically inferred from the length of the Link.Step dataset.
  • For rectangular arrays, steps may be computed from:
nsteps = lrec / (ncol * nrow)

  • Ordering convention:

    Components of the first entity at all steps, followed by the second entity at all steps, etc.

Subset Indices

Node indices for the subset are stored in:

INDX.NODE.T

Step-related attributes (e.g., time, frequency) are stored in separate datasets:

HIST.TIME.T:2
  Link.Step = HIST.STEP.T:2

HIST.FREQUENCY.T:2
  Link.Step = HIST.STEP.T:2

Whole-model quantities (e.g., strain energy) are also stored in dedicated history datasets:

HIST.SE.T:2
  Link.Time = HIST.TIME.T:2
  Link.Step = HIST.STEP.T:2

Step Numbers

Step numbers themselves (e.g., 1, 2, …, 100) are stored separately:

HIST.STEP.T:2

Component Flags

If only a subset of vector or tensor components is defined, component flags are managed through a linked dataset:

Link.Component = COMP.N:1

Where COMP.N:1 contains integer flags for each component:

  • 0 → Component undefined
  • 1 → Component defined

This component flag dataset is sparse and links back to defined indices:

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

Monitor Functions

A monitor function allows users to track the progress of an interface as it opens a file or reads data. File opening operations, such as vdm_DataFunOpen(), can be time-consuming. Typically, the process first reads and constructs the basic simulation model before building a list of simulation results.

Monitoring Progress

Progress can be monitored by querying for two attributes:

  • Phase → Indicates the stage of the operation. Possible values:
    • VDM_PHASE_OPENMODEL
    • VDM_PHASE_OPENMODELCOMPLETE
    • VDM_PHASE_OPENRESULT
  • Source → Interface-dependent string describing the current position in the file being read.

Queries are performed via:

When the phase reaches VDM_PHASE_OPENMODELCOMPLETE, the model construction is complete and the user may safely load the model while the interface continues reading simulation results.

Defining Monitor Functions

Because the interface object appears as the first argument in the monitor function, a separate callback function must be defined for each interface requiring monitoring.

Example: In the NASLib interface, the monitor function is set using vdm_NASLibSetFunction(). A similar approach applies to all other interface objects.

Multiple Domains

Some file types support multiple domains, usually associated with domain decomposition in parallel solutions. It is possible to:

  1. Query for the number of domains
  2. Open each domain separately, instancing an interface object and an associated DataFun object for each

This enables domains to be opened and read in parallel.

Querying the Number of Domains

The function vdm_DataFunNumDomains() scans the file and returns the number of domains.

  • Return values:
    • 0 → Library does not support multiple domains
    • >0 → Number of domains present

Opening Domains

  • If numdomains = 0 → Must call vdm_DataFunOpen() with mode = 0
  • If numdomains > 0 → Can call vdm_DataFunOpen() with:
    • mode = 0 → Open all domains at once
    • mode > 0 → Open a specific domain

Example: OpenFOAM Interface

The following code queries an OpenFOAM file for multiple domains:

vdm_OpenFOAMLib *openfoamlib;
vdm_DataFun *df;
Vint numdomains;
            /* create OpenFOAM device object */
openfoamlib = vdm_OpenFOAMLibBegin();
            /* create data function */
df = vdm_DataFunBegin();
            /* load data functions for OpenFOAMLib device */
vdm_OpenFOAMLibDataFun (openfoamlib,df);
            /* query library on file "example/system/controlDict" */
vdm_DataFunNumDomains (df,"example/system/controlDict",SYS_OPENFOAM,
                    &numdomains);

Example: Opening Domains Individually or Collectively

Vint i;
Vint ierr;
            /* open each individual domain */
if(numdomains) {
    dfdom =(vdm_DataFun**)malloc(numdomains*sizeof(vdm_DataFun*));
    ofdom =(vdm_OpenFOAMLib**)malloc(numdomains*sizeof(vdm_OpenFOAMLib*));
    for(i = 0; i < numdomains; i++) {
        ofdom[i] = vdm_OpenFOAMLibBegin();
        dfdom[i] = vdm_DataFunBegin();
        vdm_OpenFOAMLibDataFun (ofdom[i],dfdom[i]);
        vdm_DataFunOpen (dfdom[i],i+1,"example/system/controlDict",
                        SYS_OPENFOAM);
        if(ierr) {
            /* handle error */
        }
    }
            /* open all */
} else {
    vdm_DataFunOpen (df,0,"example/system/controlDict",SYS_OPENFOAM);
    ierr = vdm_DataFunError(df);
    if(ierr) {
            /* handle error */
    }
}

            /* close and delete */
if(numdomains) {
    for(i = 0; i < numdomains; i++) {
        vdm_DataFunClose (dfdom[i]);
        vdm_OpenFOAMLibEnd (ofdom[i]);
        vdm_DataFunEnd (dfdom[i]);
    }
    free(dfdom);
    free(ofdom);
} else {
    vdm_DataFunClose (df);
}
            /* delete common objects */
vdm_OpenFOAMLibEnd (openfoamlib);
vdm_DataFunEnd (df)