Variables¶

Variables and their metadata¶

Variables are represented by datasets with attributes. The attribute vsMesh gives the mesh that the data lives on. Other attributes can denote whether the data lives at the nodes or centers of cells. Of course, the data shape must match up to the mesh shape.
Each variable can optionally show the time group it belongs too (using optional attribute vsTimeGroup). If there is no such attribute, we assume that there is only one global time group to which a variable is tied too. Otherwise (multiple time groups with variables not referencing a particular one) the data is VizSchema compliant. Another problem may occur if a variable uses the vsTimeGroup attribute and its mesh is actually temporal. Such data is also considered not compliant.

Jump to

• Variables and their metadata
• Variables that are combined with their meshes
• Data ordering
• Variables defined in terms of other variables
• Multidomain metadata
• Other metadata

Nodal structured scalar data

GROUP "/" {
  Group "A" {
    Dataset "phi" {
      Att vsType = "variable"                     // Required string
      Att vsMesh = "mycartgrid"                   // Required string
      DATASPACE [201, 301, 105]
      Att vsCentering = "nodal"                   // Optional string, defaults to "nodal", other allowed values 
                                                  // are "zonal", "edge" or "face"
      Att vsIndexOrder = "compMinorC"             // Optional string with default value is "compMinorC"
                                                  // ("compMajorC" and "compMajorF" have the same result as the minor variants). 
      Att vsTimeGroup = "/mytime"                 // Optional string
    }
    Group mycartgrid {
      Att vsType = "mesh"                         // Required string
      Att vsKind = "uniform"                      // Required string
      Att vsStartCell = [0, 0, 0]                 // Required integer array
      Att vsNumCells = [200, 300, 104]            // Required integer array
      Att vsLowerBounds = [-2.5, -2.5, -1.3]      // Required float array
      Att vsUpperBounds = [2.5, 2.5, 1.3]         // Required float array
    }
  }
}

• vsType identifies phi as a variable.
• vsMesh gives the mesh that this variable lives on. See Naming Conventions for details
• vsCentering set to "nodal" denotes that the variable lives at the mesh nodes. Accordingly, the array is one larger in each dimension than vsNumCells of the mesh. If it is "zonal", then the data is centered at the cell (zone) centers, and the number of points equals the number of cells. In the future, we hope to support face and edge, but for now, any data that is not labeled specifically "zonal" is assumed to be nodal. Other labels are ignored.
• vsIndexOrder indicates the interpretation of the indices for the data set. See Data Ordering. E.g., for "compMinorC", the first index is the x index, the second index is the y index, and the last index is the z index.
• vsTimeGroup denotes a time group for this data as described here.
• The data is assumed to have the same index ordering as the spatial part of its corresponding mesh.

See meshes for the definition of the mesh description.

Nodal structured vector data

GROUP "/" {
  Group "A" {
    Dataset "phi" {
      Att vsType = "variable"                     // Required string
      Att vsMesh = "mycartgrid"                   // Required string
      DATASPACE [201, 301, 105, 4]
      Att vsIndexOrder = "compMinorC"             // Required string, defaults to "compMinorC", denoting that the component
                                                  // index is the last, most rapidly varying. 
      Att vsCentering = "nodal"                   // Optional string, defaults to "nodal", other allowed values 
                                                  // are "zonal", "edge" or "face"
      Att vsTimeGroup = "mytime"                  // Optional string
      Att vsLabels = "x, y, z"                    // Optional string
    }
    Group mycartgrid {
      Att vsType = "mesh"                         // Required string
      Att vsKind = "uniform"                      // Required string
      Att vsStartCell = [0, 0, 0]                 // Required integer array
      Att vsNumCells = [200, 300, 104]            // Required integer array
      Att vsLowerBounds = [-2.5, -2.5, -1.3]      // Required float array
      Att vsUpperBounds = [2.5, 2.5, 1.3]         // Required float array
    }
  }
}

• vsType identifies phi as a variable.
• vsMesh gives the mesh that this variable lives on. See Naming Conventions for details
• vsCentering set to "nodal" denotes that the variable lives at the mesh nodes. Accordingly, the array is one larger in each dimension than vsNumCells of the mesh. If it is "zonal", then the data is centered at the cell (zone) centers, and the number of points equals the number of cells. In the future, we hope to support face and edge, but for now, any data that is not labeled specifically "zonal" is assumed to be nodal. Other labels are ignored.
• vsTimeGroup denotes a time group for this data.
• vsIndexOrder can be either "compMinor", the default, or compMajor, with the latter denoting that the most slowly varying index is the component index. This attribute is not needed for data on irregular structured or unstructured meshes, where it is assumed that the data index order matches that of the mesh.
• vsLabels gives names to the components of the variable. In this case, the first three components of variable 'phi' will be named 'x', 'y', and 'z' instead of 'phi_0', 'phi_1', and 'phi_2'. Since there are 3 names given, but 4 components, the last component will retain its default name, 'phi_3'.

Zonal structured data

GROUP "/" {
  Group "A" {
    Dataset "phi" {
      Att vsType = "variable"                     // Required string
      Att vsMesh = "mycartgrid"                   // Required string
      DATASPACE [200, 300, 104] 
      Att vsCentering = "zonal"                   // Optional string, defaults to "nodal", other allowed values 
                                                  // are "zonal", "edge" or "face"
      Att vsTimeGroup = "mytime"                  // Optional string
    }
    Group mycartgrid {
      Att vsType = "mesh"                         // Required string
      Att vsKind = "uniform"                      // Required string
      Att vsStartCell = [0, 0, 0]                 // Required integer array
      Att vsNumCells = [200, 300, 104]            // Required integer array
      Att vsLowerBounds = [-2.5, -2.5, -1.3]      // Required float array
      Att vsUpperBounds = [2.5, 2.5, 1.3]         // Required float array
    }
  }
}

This array now is zonal, so that the data is associated with the centers of the zones. Accordingly, the number of data points per direction should match up to vsNumCells.

Structured data with arbitrary offsets

For structured data that are neither nodal nor zonal, one must specify the location of the data within the cell using the vsNodeOffset attribute, a float vector, to be used in place of the vsCentering attribute defined above. The values of vsNodeOffset are in the range 0...1, where 0 refers to the lower, let, bottom node, and 1 to the upper, right, top position within the cell. The number of elements in vsNodeOffset should match the number of topological dimensions. The presence of vsNodeOffset overrides any vsCentering setting. The size of data must match vsNumCells (even in the case where vsNodeOffset is [0., 0., 0.]). Use masking to turn off some cells (see next section). Following are examples of offsets:

vsNodeOffset = [0., 0., 0.]     // same as nodal 
vsNodeOffset = [0.5, 0.5, 0.5]  // same as zonal
vsNodeOffset = [0.5, 0., 0.]    // x-edge
vsNodeOffset = [0.5, 0.5, 0.]   // z-face

More details are provided at https://ice.txcorp.com/staggeredviz/wiki/VizSchemaEdgeFace.

Vector edge and face fields

In addition to "nodal" or "zonal", the vsCentering attribute can take the values of "edge" or "face" to denote vector fields which are centred on the faces or the edges of the cell. Edge/face fields are common occurrences in electromagnetic simulations with the electric field (E) located on edges and the magnetic field (B) on faces. In finite volume schemes, the flux is typically face-centered.
A field cannot have vsCentering="face" or vsCentering="edge" and vsNodeOffset defined, as an "edge" ("face") centering has a different meaning from a vsNodeOffset. An edge (face) field value represents an average value over the edge (face) whereas a vsNodeOffset denotes the point location of the field with respect to the base node of the cell.
Contrary to "zonal" and "nodal" data, "face" and "edge" data must correspond to vector fields. The number of components of the vector field is expected to match the number of space dimensions. An exception is in 2D where a face/edge vector field will be allowed to have a third component (Bz) which is assumed to be zonal for a face field, and nodal for an edge field (Ez).
For structured grids, the sizes of all components must match the number of nodes in this case. Each component will be implicitly assumed to be attached to the low end face/edge of each cell. For instance, given the nodes (i, j), (i+1, j), (i+1, j+1),and (i, j+1), the edge Ex component will be attached to the segment (i, j) -> (i+1, j) and the Ey component to (i, j) -> (i, j+1). Note that if the number of nodes is (nx + 1) * (ny + 1) then all components are expected to have dimensions (nx + 1, ny + 1). In other words, there is an additional row/column of cells on the upper side of the domain to accommodate the last face/edge values. In the example below, the grid is 2 by 3 cells and has been padded to become 3 by 4 in order to attach face/edge values along i = 2 and j = 3. Face/edge values falling outside the domain, e.g. edge Ey or face Bx at i = 0 and j = 3, are assumed to be invalid. However, edge Ex and face By are valid at i = 0 and j = 3.

^
|
j 
  +...+...+...+
  :   :   :   :
3 +---+---+...+
  |   |   |   :
2 +---+---+...+
  |   |   |   :
1 +---+---+...+
  |   |   |   :
0 +---+---+...+
  0   1   2   --> I

Edge vector structured data

GROUP "/" {
  Group "A" {
    Dataset "phi" {
      Att vsType = "variable"                     // Required string
      Att vsMesh = "mycartgrid"                   // Required string
      DATASPACE [202, 302, 106, 4]
      Att vsCentering = "edge"                    // Optional string, defaults to "nodal", other allowed value 
                                                  // are "zonal", "edge" and "face"
      Att vsIndexOrder = "compMinorC"             // Optional string with default value is "compMinorC"
                                                  // ("compMajorC" and "compMajorF" have the same result as the minor variants). 
      Att vsTimeGroup = "/mytime"                 // Optional string
    }
    Group mycartgrid {
      Att vsType = "mesh"                         // Required string
      Att vsKind = "uniform"                      // Required string
      Att vsStartCell = [0, 0, 0]                 // Required integer array
      Att vsNumCells = [200, 300, 104]            // Required integer array
      Att vsLowerBounds = [-2.5, -2.5, -1.3]      // Required float array
      Att vsUpperBounds = [2.5, 2.5, 1.3]         // Required float array
    }
  }
}

Face vector structured data

GROUP "/" {
  Group "A" {
    Dataset "phi" {
      Att vsType = "variable"                     // Required string
      Att vsMesh = "mycartgrid"                   // Required string
      DATASPACE [202, 302, 106, 4]
      Att vsCentering = "face"                    // Optional string, defaults to "nodal", other allowed value 
                                                  // are "zonal", "edge" and "face"
      Att vsIndexOrder = "compMinorC"             // Optional string with default value is "compMinorC"
                                                  // ("compMajorC" and "compMajorF" have the same result as the minor variants). 
      Att vsTimeGroup = "/mytime"                 // Optional string
    }
    Group mycartgrid {
      Att vsType = "mesh"                         // Required string
      Att vsKind = "uniform"                      // Required string
      Att vsStartCell = [0, 0, 0]                 // Required integer array
      Att vsNumCells = [200, 300, 104]            // Required integer array
      Att vsLowerBounds = [-2.5, -2.5, -1.3]      // Required float array
      Att vsUpperBounds = [2.5, 2.5, 1.3]         // Required float array
    }
  }
}

For unstructured grids, the attributes "face" and "edge" can also be used. In this case, the user is expected to attach a scalar value to each oriented face/edge element, the list of edges and faces must be provided as a list of node indexes. Note that edges are defined by two nodes (i, j) and that edge (j, i) = - edge(i, j). Similarly, faces are defined by 3 nodes (i, j, k) and face(i, k, j) = - face(i, j, k). In other words, the permutation of two indexes introduces a negative sign.

Below are vector basis functions for edge (silver) and face (gold) vector fields in the case of a tetrahedral cell (left and middle) and a cuboid cell. Theses basis functions, known as Whitney forms, determine the interpolation weights inside a cell. They have the important property that the line (area) integral of the vector field over the edge (face) is zero on all edges (faces) except one. Note that the direction of the edge (face) vector field is not necessarily along the edge (perpendicular to the face).

Missing data values

There are cases where the data are corrupted or otherwise not known. Since data values are expected to be provided over the entire mesh, special values must be chosen to indicate that the data are invalid at these locations. This is known as a missing value. Missing values should be chosen outside the range of data validity, if possible. Thus, variables that are positive definite (density, temperature in Kelvin, etc.) may choose a negative value. When this is not possible then an extremely unlikely value can also serve the purpose of a missing value, e.g. close to the minimum or maximum range of the floating point number representation (-3.402823466E+38, 3.402823466E+38).

The optional variable attribute for a missing value is vsMissingValue. This attribute cannot apply to a variable that has vsType == "mask".

GROUP "/" {
  Group "A" {
    Dataset "myarray" {
      Att vsMissingValue =  -3.402823466E+38      // float attribute
      Att vsMesh = "mycartgrid"                   // Required string
      DATASPACE [201, 301, 105]
      Att vsCentering = "nodal"                   // Optional string, defaults to "nodal", other allowed values 
                                                  // are "zonal", "edge" or "face"
      Att vsIndexOrder = "compMinorC"             // Optional string with default value is "compMinorC"
                                                  // ("compMajorC" and "compMajorF" have the same result as the minor variants). 
      Att vsTimeGroup = "/mytime"                 // Optional string
    }
    Group mycartgrid {
      Att vsType = "mesh"                         // Required string
      Att vsKind = "uniform"                      // Required string
      Att vsStartCell = [0, 0, 0]                 // Required integer array
      Att vsNumCells = [200, 300, 104]            // Required integer array
      Att vsLowerBounds = [-2.5, -2.5, -1.3]      // Required float array
      Att vsUpperBounds = [2.5, 2.5, 1.3]         // Required float array
    }
  }

Labeling Variable Components

The default names given to components of a multi-component variable are generally of the form "datasetName_componentNumber". Users desiring more human-readable labels for components may use the vsLabels attribute to specify different names. This attribute must contain a comma-separated string of names to be used for each component of a variable. In the event of an error such as an incorrectly formatted string, the default component names will be used.
Note that if labels are assigned to components, those components will no longer be available with the default name. This limitation includes any expressions defined with vsVars or in a VisIt session. Any expression that refers to an old component name will fail to find the component under the new name. In order to function properly, these expressions will need to refer to the label as supplied by the vsLabel attribute.
This example shows a variable with 7 components, labeled 'x', 'y', 'z', 'dx', 'dy', 'dz', 'particle_id':

Dataset "myVar" {
  Att vsType = "variable"
  Att vsMesh = "myMesh"
  DATASPACE [200, 7] 
  vsLabels = "x, y, z, dx, dy, dz, particle_id" 
}

Associating Variables with Times

Any Variable or VariableWithMesh may be assigned time information using the vsTimeGroup attribute. This optional attribute should contain the name of a "time" group (see Other metadata for more information).
Note that since Vizschema does not allow multiple timesteps in a single file, conflicting time information will result in undefined behavior.
In this example, the variable "myVar" has been declared to belong to time "0.005" and step "2":

Dataset "myVar" {
  Att vsType = "variable"
  Att vsMesh = "myMesh"
  DATASPACE [200, 7]
  Att vsTimeGroup = "timeGroup"
}

Group "timeGroup" {
  Att vsKind = "time"
  Att vsTime = "0.005"
  Att vsStep = "2"
}

For unstructured grids there are attributes for various shapes. Lines, Triangles, Quadrilaterals, Polygons and Polyherda. Datasets of these types must include the connectivity. The attributes are vsLines, vsTriangles, vsPolygons, vsPolyhedra, vsPoints, vsLines, vsTriangles, vsQuadrilaterals, vsTetrahedrals, vsPyramids, vsPrisms and vsHexahedrals.

Dataset "myVar" {
  Att vsType = "variable"         // 
  Att vsMesh = "myMesh"           //
  DATASPACE [5, 6, 7]
  Att vsLines = "/connectivity"
}
Dataset "connectivity" {
  DATA [210, 2]
}
Group myMesh {
      Att vsType = "mesh"                         // Required string
      Att vsKind = "uniform"                      // Required string
      Att vsStartCell = [0, 0, 0]                 // Required integer array
      Att vsNumCells = [5, 6, 7]                  // Required integer array

High order fields

High order fields can be attached to meshes of type vsKind = "unstructured", "structured", or "uniform". These fields are similar to unstructured, structured, or uniform fields except that they carry an additional index, of dimension n_subCell, which denotes the location of the field inside the coarse cells.

Dataset myScalarVar {
   Att vsType = "variable"
   Att vsMesh = "myMesh"
   DATASPACE [n_coarseCells, n_subCell]
}

Higher order vector fields have the component as last index:

Dataset myVectorVar {
   Att vsType = "variable"
   Att vsMesh = "myMesh"
   DATASPACE [n_coarseCells, n_subCell, n_comps]
}

High order fields cannot have the vsCentering attribute.