Data Model Schema

This describes the required and optional components of the data model and how to describe them in JSON. The top level JSON object can be given a name by the user. For example:

{
  "VTK_Cartesian_grid": {
  }
}

The following sections describe the objects are placed inside this top-level object.

Data Sources

The data_sources object is required and must have at least 1 data source specified. A data source corresponds to an ADIOS engine output. If you write all of your data using one engine (e.g., single BP file or stream), then you’ll only need one data source. Some simulations write the mesh to a different file from the field data, so in this case, you would set up two data sources.

The following example shows a single data source being defined. The name is any name you want to give it and is the name Fides uses to track the data source. In most cases filename_mode will be relative. In this case, a specific filename is given to the actual name of teh BP file/stream. The file path is assumed to be relative to the location of the JSON file unless an alternate location is provided in the paths provided to the Fides reader methods. In the following example, Fides will look for a file named simulation_data.bp in the same directory as the JSON file.

"data_sources": [
  {
  "name": "source",
  "filename_mode": "relative",
  "filename": "simulation_data.bp"
  }
]

The following example shows two data sources being defined, one for the mesh and one for the fields. In this case, each data source will load a different file.

"data_sources": [
  {
    "name": "mesh",
    "filename_mode": "relative",
    "filename": "data/mesh.bp"
  },
  {
    "name": "fields",
    "filename_mode": "relative",
    "filename": "data/fields.bp"
  }
]

The following example shows a single data source being defined without naming the file by setting the filename_mode to input. In this case, the specific filename is not given, and you will need to give the name to Fides in your code. This is done by providing a paths map that references the given name to the full path of the BP file/stream.

"data_sources": [
  {
  "name": "source",
  "filename_mode": "input"
  }
]

Coordinate System

The coordinate_system object will map your ADIOS Variable(s) to the appropriate VTK-m coordinate system. For any coordinate system, there is an array object that specifies the array_type. Possible values are basic, uniform_point_coordinates, cartesian_product, or composite.

The following example describes a coordinate system with uniform point coordinates:

"coordinate_system": {
  "array" : {
    "array_type": "uniform_point_coordinates",
    "dimensions": {
      "source": "variable_dimensions",
      "data_source": "source",
      "variable": "density"
    },
    "origin": {
      "source": "array",
      "values": [0.0, 0.0, 0.0]
    },
    "spacing": {
      "source": "array",
      "values": [0.1, 0.1, 0.1]
    }
  }
}

dimensions uses an ADIOS Variable to determine the dimensions of the coordinate system, so data_source should name the appropriate data source, while variable is the name of the ADIOS Variable. In this case source should always be variable_dimensions.

The source for the origin and spacing should always be array as it specifies that you will specify an array for the values.

The following example describes a coordinate system with a cartesian product for coordinates:

"coordinate_system": {
  "array" : {
    "array_type": "cartesian_product",
    "x_array": {
      "array_type": "basic",
      "data_source": "source",
      "variable": "x"
    },
    "y_array": {
      "array_type": "basic",
      "data_source": "source",
      "variable": "y"
    },
    "z_array": {
      "array_type": "basic",
      "data_source": "source",
      "variable": "z"
    }
  }
}

In this case, you need to specify your x, y, and z arrays as shown in the example. The array_type should be set to basic for the x, y, and z arrays. Again, data_source should name the appropriate data source.

The composite array_type is similar to cartesian_product, except that instead of performing a cartesian product on the arrays, the array values are zipped together to form points (x0, y0, z0), (x1, y1, z1), …, (xn, yn, zn).

The final array_type of basic for the coordinate system is shown in the following example:

"coordinate_system": {
  "array" : {
    "array_type": "basic",
    "data_source": "source",
    "variable": "points"
  }
}

This is useful for an unstructured grid, where your points are all explicitly written out in a variable.

Cell Set

The cell_set object will map your ADIOS Variable(s) to the appropriate VTK-m cell set. You must specify the cell_set_type, which can be one of the following values: structured, single_type, or explicit.

The following example describes a structured cell set:

"cell_set": {
  "cell_set_type": "structured",
  "dimensions": {
    "source": "variable_dimensions",
    "data_source": "source",
    "variable": "density"
  }
}

The dimensions are determined from an ADIOS Variable, in this case density from the data source named source.

For an explicit cell set, but with only a single type of cells, you can do the following:

"cell_set": {
  "cell_set_type": "single_type",
  "cell_type": "triangle",
  "data_source": "source",
  "variable": "connectivity"
}

cell_type must be one of: vertex, line, triangle, quad, tetrahedron, hexahedron, wedge, pyramid. Then you must specify the variable containing the connectivity.

The following shows an example of an explicit cell set, where different types of cells may be used.

"cell_set": {
  "cell_set_type": "explicit",
  "connectivity": {
    "array_type": "basic",
    "data_source": "source",
    "variable": "connectivity"
  },
  "cell_types": {
    "array_type": "basic",
    "data_source": "source",
    "variable": "cell_types"
  },
  "number_of_vertices": {
    "array_type": "basic",
    "data_source": "source",
    "variable": "num_verts"
  }
}

In this case, you’ll need to specify 3 ADIOS variables, one each for the connectivity, cell types, and number of vertices of each cell.

Fields

The fields section is optional and describes each ADIOS variable that should be read as a Field. For example:

"fields": [
  {
    "name": "density",
    "association": "points",
    "array": {
      "array_type": "basic",
      "data_source": "source",
      "variable": "density"
    }
  }
]

name allows you to specify a different name for the field (or you can choose the same name as it’s called in ADIOS). association should be either points or cells. array is similar to array definitions in other places described earlier, where you need to specify the data source name and the name of the variable in ADIOS.

Each field that should be read in must be specified here, or you can use Wildcard Fields.

Step Information

The step_information section is optional. If defined, the data_source is required, while variable is optional. By specifying a data source, Fides will use that data source for step information (e.g., number of steps available in the dataset). If you add the variable, Fides will use the chosen ADIOS variable to give the time value for each time step, which is useful when using ParaView/VTK to visualize your data.

"step_information": {
  "data_source": "source",
  "variable": "time"
}