Naming¶

Naming Conventions¶

There are several situations where it is necessary for VizSchema objects to refer to one another. For example, variables must specify their mesh. VizSchema uses a simple naming scheme, similar to paths in a file system, to allow these references.

Groups

The Hdf5 file format allows the creation of Groups, which may in turn contain other groups or datasets. Each file begins with a single root group, denoted with a single forward slash - "/". Each successive level of group nesting is denoted by adding the name of the group at each level, separated by another forward slash. This is essentially the same as directories or folders in a file system. In hdf5 data files, a common use of groups is to store data from separate timesteps.

Relative vs Fully-qualified Paths

Both relative and fully-qualified path names are accepted for any of the situations that require referencing another object in a file. Fully-qualified names begin with a forward slash, which tells VizSchema that the path begins in the root of the file. A name without a leading forward slash tells VizSchema that the path begins in the group where it is located. Note that fully qualified names are valid no matter where they are located in a file, while a relative name will need to be changed if the name of the enclosing group changes.

Examples

Both acceptable
In this example, a variable refers to a uniform mesh located in the root of the file. In this case, the fully qualified name of the mesh is "/mycartgrid". Since the variable is located in the root of the file as well, the relative path "mycartgrid" would also work.

GROUP "/" {
  Group "A" {
    Dataset "phi" {
      Att vsType = "variable"                     // Required string
      Att vsMesh = "/mycartgrid"                  // Required string
      DATASPACE [201, 301, 105]                   // Required float array
    }
  }
  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
  }
}

Time steps

In this example, there are multiple time steps in the same file. The data and mesh for step 0 are in the group "Step_0000", and the data and mesh for step 1 are in the group "Step_0001". The variable in step 0 uses a fully-qualified path to refer to its mesh. The variable in step 1 uses a relative path to refer to its mesh.

GROUP "/" {
  Group "Step_0000" {
    Group "A" {
      Dataset "phi" {
        Att vsType = "variable"
        Att vsMesh = "/Step_0000/mycartgrid"        // Fully qualified reference
        DATASPACE [201, 301, 105]
      }
    }
    Group mycartgrid {
      Att vsType = "mesh"
      Att vsKind = "uniform"
      Att vsStartCell = [0, 0, 0]
      Att vsNumCells = [200, 300, 104]
      Att vsLowerBounds = [-2.5, -2.5, -1.3] 
      Att vsUpperBounds = [2.5, 2.5, 1.3]
    }
  }

Group "Step_0001" {
    Group "A" {
      Dataset "phi" {
        Att vsType = "variable"                     
        Att vsMesh = "mycartgrid"                   // Relative reference
        DATASPACE [201, 301, 105]  
      }
    }
    Group mycartgrid {
      Att vsType = "mesh"       
      Att vsKind = "uniform"                      
      Att vsStartCell = [0, 0, 0]               
      Att vsNumCells = [200, 300, 104]        
      Att vsLowerBounds = [-2.5, -2.5, -1.3]     
      Att vsUpperBounds = [2.5, 2.5, 1.3]      
    }
  }
}