Chombo HDF Format

AstroBEAR's default output format is Chombo HDF5. These files are created using the ​HDF5 API and can be rendered into images by ChomboVis and VisIt. A full description of the Chombo HDF format can be found ​here. note that we do not use any of the optional Particle data, so that section can be safely ignored.

HDF files are made up of ​groups, ​attributes, and ​datasets. A full description of these elements can be found on the linked pages above, but for our purpose the important thing to understand is that groups are used to organize attributes and datasets. The root group (usually names "/") contains most of the data in the file. This can include one or more nested subgroups with their own attributes and datasets. The group structure of a Chombo-formatted HDF file looks like this:

  "/" (root) {
  
       ...  ([attributes and datasets])

       "/Chombo_global" {
            ...
       }

       "/level_n" {

            ...

            "/level_n/data_attributes" {
                 ...
            }
       }
  }

As long as the group structure remains intact and the required elements listed in the ​Chombo file description are present, the Chombo format can be extended at will. The ​HDF5 API allows programs to access only those HDF elements they need, so any additional elements in a Chombo HDF5 file will just be ignored.

The AstroBEAR data mappings to Chombo fields are as follows:

GROUP "/"

ATTRIBUTE "time": tnow, the time at which the given frame was taken.

ATTRIBUTE "iteration": RootInfo%nFrame, the number of the file's frame. This number will be the same for all nodes in the AMR structure, but the MakeChomboFile function uses RootInfo for convenience.

ATTRIBUTE "num_levels": RootInfo%MaxLevel + 1, the maximum refinement level of the grid plus one. Again, in AstroBEAR the MaxLevel value is the same for all nodes, so RootInfo is used for convenience.

ATTRIBUTE "max_level": RootInfo%MaxLevel, the maximum refinement level of the grid.

ATTRIBUTE "num_components": SIZE(RootInfo%q). The component_n attributes of the Chombo file are analogous to the q variables in AstroBEAR, so we just use the size of the q array. We can get away with this in AstroBEAR because all nodes have the same variables. Other implementations of BearCLAW may not be so forgiving, though.

ATTRIBUTE "component_n": The component_n attributes are strings containing the names of the q variables. Typically this will be a list of named physical variables, followed by special user-defined variables called Tracer variables. In AstroBEAR, the component_n variables depend on whether or not the problem uses MHD:

2D non-MHD		3D non-MHD	MHD
component_0	rho	rho	rho
component_1	px	px	px
component_2	py	py	py
component_3	E	pz	pz
component_4	Tracer00*	E	E
component_5	Tracer01*	Tracer00*	Bx
component_6	Tracer02*	Tracer01*	By
component_7	Tracer03*	Tracer02*	Bz

_{*After the basic problem fields are defined, the Component_n fields are filled up with Tracer until the number of components is equal to SIZE(RootInfo%q).}

GROUP "/Chombo_global"

ATTRIBUTE "testReal": For the testReal attribute, we just use a constant real value 1.0.

ATTRIBUTE "SpaceDim": RootInfo%nDim, the number of dimensions in the problem. We don't generally do 4D simulations, and we usually only do 1D simulations for testing purposes, so the odds are good that this value will be either 2 or 3.

GROUP "/level_n"

ATTRIBUTE "dx": NodeInfo%dX(1). MakeChomboFile assumes that the differential increment is identical in all dimensions for all grids on a level, so we just pick a node on level n and pull its first NodeInfo%dX value.

ATTRIBUTE "ref_ratio": NodeInfo%r, the refinement ratio of some grid on level n. All nodes on a level should have the same refinement ratio, so we can just pick one and use it.

ATTRIBUTE "prob_domain": This attribute uses the Box data type. The problem domain for a level is created by finding the minimum lower bound and maximum upper bound in each dimension across all the grids on the level. This is done by checking the NodeInfo%Xlower and NodeInfo%Xupper array values of each grid on level n (this is performed by the GetMinimumXlowers and GetMaximumXuppers functions).

DATASET "boxes": A one-dimensional set of Box objects, this dataset contains the dimensions of each level n grid, relative to the prob_domain grid. The lower bound of each Box is calculated using the formula (NodeInfo%Xlowers - prob_domain%Xlowers) / dX, which gives us the offset in grid cells from the lower bound of the problem domain grid. The upper bound is obtained by adding NodeInfo%mX, the number of cells in each dimension, to the boxes lower bound.

DATASET "data:datatype=0": This dataset contains the actual problem data, NodeInfo%q values for each cell of each grid on the level, all strung together in a one-dimensional floating-point array. The data is "flattened" from a multi-dimensional problem space by looping over all four BearCLAW dimensions plus qand writing each value to the dataset. The data-flattening rules are described in more detail in ​Section 2.1 of the Chombo HDF specification page.

DATASET "MHD_data": This dataset is NOT part of the Chombo HDF specification, but VisIt ignores it and it is a useful thing to have, so we included it anyway for MHD problems. MHD_data stores the magnetic field values (Bx, By, Bz) for the points on each grid in the level. In AstroBEAR terms, these are the first 2-3 variables tracked by the NodeInfo%aux array. Note that the aux values are edge-determined, so the NodeInfo%aux array is shaped a little differently from NodeInfo%q.

GROUP "/level_n/data_attributes"

ATTRIBUTE "output_ghost": A literal Chombo integer vector [0, 0, 0].

ATTRIBUTE "comps": NodePtrInfo%NrOutVars, the number of variables in the problem. For AstroBEAR, this is identical to num_components, since we generally have the same number of variables for all levels.

ATTRIBUTE "objectType": A string literal "FArrayBox".