VizSchema

# 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](https://ice.txcorp.com/projects/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]      

    }

  }

}

```