The HHDB Solution File Format

The HHDB Solution File Format was created by Richard Sanders for the Houston Hypersonic Database.

Example input and output routines can be found at the end of this document.

Words and Records

All words within a HHDB solution file must be one of the following:

Integers must be in 4-byte big-endian format, where big-endian stands for "big-end-first", meaning that within each 4-byte integer, the byte ordering is most significant byte first to least significant byte last. All floating point numbers must be 4-byte IEEE floating point numbers. C-language subroutines are supplied to convert your local machine's integer and floating point numbers to these standards.
Character arrays must be right padded with null characters (ascii 0) to 4-byte boundaries. For example, in Fortran:
```
        str1(1:20) = 'This is a string.'//char(0)//char(0)//char(0) 
        str2(1:8)  = 'This too'
```

A HHDB solution file is composed of multiple records. Within the HHSFD, a record is defined as a byte stream delimited by a 4-byte big-endian integer header and a 4-byte integer trailer both of which are the size, in bytes, of the delimited record. For example, an empty record is composed of 8 zero bytes. Every record size measured in bytes must be a multiple of 4.

Fortran unformatted file output often produces these delimiting bytes automatically. For example:

        real*4 record(*)
        open(unit=1,file='solution.hhdb',form='unformatted')
        write(1) (record(i),i=1,record_size_in_4_byte_units)

In C, you can mimic this by using the following stub as a reference:

        fp=fopen("solution.hhdb","wb");
        rsize=4*record_size_in_4_byte_units;
        fwrite(&rsize,4,1,fp);
        fwrite(record,4,record_size_in_4_byte_units,fp);
        fwrite(&rsize,4,1,fp);

General File Structure

A HHDB solution file has the following structured components:

MAGIC	The first component of every solution file must be a magic number record containing a single big-endian integer. (This record as with all records must be delimited by the record size in bytes. Therefore, the MAGIC record is actually composed of twelve bytes.)
ITEM	A single record typically containing data. Items may be context sensitive.
SECTION	Multi-record components that are delimited by a Beginning-Of-Section (BOS) record and an End-Of-Section (EOS) record. Sections may contain other sections (i.e. subsections) as well as items.

The first word of every record is an integer tag. The following tags are currently defined:

Record Type	Tag
MAGIC	1212432974	The magic number.
ITM_COMM	0	A comment.
BOS_HHDB	32	BOS for a HHDB solution.
EOS_HHDB	33	EOS for a HHDB solution.
BOS_UNSTR	64	BOS for an unstructured mesh/data block.
EOS_UNSTR	65	EOS for an unstructured mesh/data block.
BOS_STRUC	66	BOS for a structured mesh/data block.
EOS_STRUC	67	EOS for a structured mesh/data block.
ITM_VCINT	256	Vertex-centered interior data.
ITM_CCINT	257	Cell-centered interior data.
ITM_VCBOU	258	Vertex-centered boundary data.
ITM_CCBOU	259	Cell-centered boundary data.

"file structure anchor"
A valid HHDB solution file is structured as follows:

MAGIC

ITM_COMM (See 1 below.)

BOS_HHDB

. . .

BOS_STRUC (See 2 below.)

ITM_VCINT	\|	ITM_CCINT	(See 3 below.)
ITM_VCBOU	\|	ITM_CCBOU	(See 4 below.)

EOS_STRUC

. . .

BOS_UNSTR

ITM_VCINT	\|	ITM_CCINT	(See 3 below.)
ITM_VCBOU	\|	ITM_CCBOU	(See 4 below.)

EOS_UNSTR

. . .

EOS_HHDB

BOS_HHDB (See 5 below.)

. . .

EOS_HHDB

. . .

(1) Comments may appear anywhere within the file following MAGIC. We must stress that for word alignment reasons, the number of characters in a comment must be a multiple of four. Pad with null characters if not.
(2) Structured and/or unstructured blocks may be mixed within a HHDB solution section.
(3) Every block, both structured and unstructured, must contain exactly one item of type ITM_VCINT or ITM_CCINT. Note that the format of these items is context sensitive depending on whether the block is structured or unstructured.
(4) Blocks may have any number of boundary patches of type ITM_VCBOU and/or ITM_CCBOU. The format of these items is also context sensitive.
(5) Any number of HHDB solution sections are allowed within the file.

Specifics

We'll use Fortran as a guide to outline the specifics of above. Suppose that we have opened a file for reading:

        open(unit=1,file='solution.hhdb',form='unformatted')

Return

Read the MAGIC item for the HHDB solution section (tag = 1212432974):
```
        read(1) magn  ! check that magn == 1212432974  
```
Return to "file structure anchor".

Read a comment item ITM_COMM (tag = 0):

        character str(*)
        read(1) tag,num,(str(i),i=1,num) ! num must be a multiple of 4.

Return to "file structure anchor".

Read the BOS_HHDB section header for a HHDB solution section (tag = 32):
```
        read(1) tag,soln,nblks,ndims,nvars,bvars  
```
where
1. tag=32, identifying this as the beginning of a HHDB solution section.
2. soln is an index (integer) assigned to this HHDB solution section.
3. nblks is the number of (STRUC and/or UNSTR) mesh/data block subsections contained within this HHDB solution section.
4. ndims is the number of space dimensions (1, 2, or 3) for the current solution.
5. nvars is the number of flow variables present in the current solution.
6. bvars is the number of boundary flow variables present in the current solution.
Read any number of unstructured mesh/data block subsections as follows:
1. Read the BOS_UNSTR subsection header for this mesh/data block (tag=64):
```
        read(1) tag,blk,nptchs    
```
  where
  1. tag=64, identifying this BOS as the beginning of an unstructured mesh/data block subsection,
  2. blk is an integer assigned to the current mesh subsection,
  3. nptchs is the number of boundary patches within this block.
2. Either read ONE and ONLY ONE vertex-centered mesh/data item ITM_VCINT (tag=256):
```
          read(1) tag,nnodes,ncells,nconns,
     *      ((node(id,no),id=1,ndims),no=1,nnodes),
     *      ((solu(no,va),no=1,nnodes),va=1,nvars),
     *      (type,(conn(ve,ce),ve=1,nperc(type)),ce=1,ncells)    
```
  where
  1. tag=256, identifying the current interior data as vertex-centered,
  2. nnodes is total number of mesh nodes in this mesh block,
  3. ncells is the number of mesh cells in this block,
  4. nconns is the total size (*) of the connectivity array,
  5. node(id,no) is a list of spatial coordinates,
  6. solu(no,va) is a list of solution floating point values for each flow variable, where the values are located at nodes,
  7. type is the type of cell and
  8. conn(ve,ce) is a list of connectivity indices identifying the cell vertices with the listed nodes.
  (*) To help clarify this, suppose that nperc is constant for each cell throughout the block. Then nconns=(1+nperc)*ncells.
  
  Or ONE and ONLY ONE cell-centered ITM_CCINT item (tag=257):
```
          read(1) tag,nnodes,ncells,nconns,
     *      ((node(id,no),id=1,ndims),no=1,nnodes),
     *      ((solu(ce,va),ce=1,ncells),va=1,nvars),
     *      (type,(conn(ve,ce),ve=1,nperc(type)),ce=1,ncells)    
```
  where
  1. tag=257, identifying the current interior data as cell-centered,
  2. nnodes is total number of mesh nodes in this mesh block,
  3. ncells is the number of mesh cells in this block,
  4. nconns is the total size of the connectivity array,
  5. node(id,no) is a list of spatial coordinates,
  6. solu(ce,va) is a list of solution floating point values for each flow variable, where the values are located at cell centers,
  7. type is the type of cell and
  8. conn(ve,ce) is a list of connectivity indices identifying the cell vertices with the listed nodes.
3. Read any number of vertex-centered boundary patch items ITM_VCBOU (tag=258):
```
          read(1) tag,ptch,bnodes,bcells,bconns,
     *      ((bnod(no),no=1,bnodes),
     *      ((bsol(no,va),no=1,bnodes),va=1,bvars),
     *      (type,(bcon(ve,ce),ve=1,nperc(type)),ce=1,bcells)    
```
  where
  1. tag=258, identifying the current boundary data as vertex-centered,
  2. ptch is an index assigned to the current boundary patch,
  3. bnodes is the number of boundary mesh nodes in the current boundary patch,
  4. bcells is the number of boundary mesh cells in the current boundary patch,
  5. bconns is the total size of the boundary patch connectivity array,
  6. bnod(no) is a list of boundary mesh node indices in the current boundary patch, where the indices here equal those indices of the appropriate mesh nodes defined in the mesh node coordinate list,
  7. bsol(no,va) is a list of solution floating point values for each boundary variable, where the values are located at the boundary mesh nodes, with the ordering and number of values consistent with the ordering and number of boundary mesh nodes,
  8. type is the type of boundary cell and
  9. bcon(ve,ce) is a list of mesh node indices identifying the cell's vertices.
  And/or read any number of cell-centered boundary patch items ITM_CCBOU (tag=259):
```
          read(1) tag,ptch,bnodes,bcells,bconns,
     *      ((bnod(no),no=1,bnodes),
     *      ((bsol(ce,va),ce=1,bcells),va=1,bvars),
     *      (type,(bcon(ve,ce),ve=1,nperc(type)),ce=1,bcells)    
```
  where
  1. tag=259, identifying the current boundary data as cell-centered,
  2. ptch is an index assigned to the current boundary patch,
  3. bnodes is the number of boundary mesh nodes in the current boundary patch,
  4. bcells is the number of boundary mesh cells in the current boundary patch,
  5. bconns is the total size of the boundary patch connectivity array,
  6. bnod(no) is a list of boundary mesh node indices in the current boundary patch, where the indices here equal those indices of the appropriate mesh nodes defined in the mesh node coordinate list,
  7. bsol(ce,va) is a list of solution floating point values for each boundary variable, where the values are located at the boundary cell center, with the ordering and number of values consistent with the ordering and number of boundary cells,
  8. type is the type of boundary cell and
  9. bcon(ve,ce) is a list of mesh node indices identifying the cell's vertices.
  Return to "file structure anchor".
4. Read the EOS_UNSTR end of section this unstructured mesh/data block (tag=65):
```
        read(1) tag    
```
  where
  1. tag=65, identifying this EOS as one ending an unstructured mesh/data block subsection.
Read any number of structured mesh/data block subsections as follows:
1. Read the BOS_STRUC section header for this mesh/data block (tag=66):
```
        read(1) tag,blk,nptchs    
```
  where
  1. tag=66, identifying this BOS as one beginning a STRUC mesh/data block subsection,
  2. blk is an index assigned to the current mesh subsection,
  3. nptchs is the number of boundary mesh patches in the current block.
2. Either read ONE and ONLY ONE vertex-centered mesh/data item ITM_VCINT (tag=256):
```
          read(1) tag,idim,jdim,kdim,
     *      ((((node(id,i,j,k),id=1,ndims),
     *                         i=1,idim),
     *                         j=1,jdim),
     *                         k=1,kdim),
     *      ((((solu(i,j,k,va),i=1,idim),
     *                         j=1,jdim),
     *                         k=1,kdim),va=1,nvars)    
```
  where
  1. tag=256, identifying the current interior data as vertex-centered,
  2. idim is the total number of mesh nodes in the first spatial coordinate in the current mesh (must be >= 1),
  3. jdim is the total number of mesh nodes in the second spatial coordinate in the current mesh (must be >= 1),
  4. kdim is the total number of mesh nodes in the third spatial coordinate in the current mesh (must be >= 1),
  5. node(id,i,j,k) is a list of coordinates for the mesh nodes in the current mesh, and
  6. solu(i,j,k,va) is a list of solution floating point values for each flow variable, where the values are located at the mesh nodes, with the ordering and number of values consistent with the ordering and number of mesh nodes.
  Or ONE and ONLY ONE cell-centered ITM_CCINT item (tag=257):
```
          read(1) tag,idim,jdim,kdim,
     *      ((((node(id,i,j,k),id=1,ndims),
     *                         i=1,idim),
     *                         j=1,jdim),
     *                         k=1,kdim),
     *      ((((solu(i,j,k,va),i=1,max(idim-1,1)),
     *                         j=1,max(jdim-1,1)),
     *                         k=1,max(kdim-1,1)),va=1,nvars)    
```
  where
  1. tag=257, identifying the current interior data as cell-centered,
  2. idim is the total number of mesh nodes in the first spatial coordinate in the current mesh (must be >= 1),
  3. jdim is the total number of mesh nodes in the second spatial coordinate in the current mesh (must be >= 1),
  4. kdim is the total number of mesh nodes in the third spatial coordinate in the current mesh (must be >= 1),
  5. node(id,i,j,k) is a list of coordinates for the mesh nodes in the current mesh, and
  6. solu(i,j,k,va) is a list of solution floating point values for each flow variable, where the values are located at the cell centers, with the ordering and number of values consistent with the ordering and number of cells.
3. Read any number of vertex-centered boundary patch items ITM_VCBOU (tag=258):
```
          read(1) tag,ptch,ilo,ihi,jlo,jhi,klo,khi,
     *      ((((bsol(i,j,k,va),i=1,ihi-ilo+1),
     *                         j=1,jhi-jlo+1),
     *                         k=1,khi-klo+1),va=1,bvars)    
```
  where
  1. tag=258, identifying the current boundary data as vertex-centered,
  2. ptch is an integer assigned to the current boundary patch,
  3. ilo is the lowest mesh node index of the first spatial coordinate in the current boundary patch, where the index here, and in d)-h) below, equals the index of the appropriate mesh node defined in the mesh node coordinate list,
  4. ihi is the highest mesh node index of the first spatial coordinate in the current boundary patch,
  5. jlo is the lowest mesh node index of the second spatial coordinate in the current boundary patch,
  6. jhi is the highest mesh node index of the second spatial coordinate in the current boundary patch,
  7. klo is the lowest mesh node index of the third spatial coordinate in the current boundary patch,
  8. khi is the highest mesh node index of the third spatial coordinate in the current boundary patch,
  9. bsol(i,j,k,va) is a list of solution floating point values for each boundary variable, where the values are located at the boundary mesh nodes, with the ordering and number of values consistent with the ordering and number of boundary mesh nodes.
  And/or read any number of cell-centered boundary patch items ITM_CCBOU (tag=259):
```
          read(1) tag,ptch,ilo,ihi,jlo,jhi,klo,khi,
     *      ((((bsol(i,j,k,va),i=1,max(ihi-ilo,1)),
     *                         j=1,max(jhi-jlo,1)),
     *                         k=1,max(khi-klo,1)),va=1,bvars)    
```
  where
  1. tag=259, identifying the current boundary data as cell-centered,
  2. ptch is an integer assigned to the current boundary patch,
  3. ilo is the lowest mesh node index of the first spatial coordinate in the current boundary patch, where the index here, and in d)-h) below, equals the index of the appropriate mesh node defined in the mesh node coordinate list,
  4. ihi is the highest mesh node index of the first spatial coordinate in the current boundary patch,
  5. jlo is the lowest mesh node index of the second spatial coordinate in the current boundary patch,
  6. jhi is the highest mesh node index of the second spatial coordinate in the current boundary patch,
  7. klo is the lowest mesh node index of the third spatial coordinate in the current boundary patch,
  8. khi is the highest mesh node index of the third spatial coordinate in the current boundary patch,
  9. bsol(i,j,k,va) is a list of solution floating point values for each boundary variable, where the values are located at the boundary cell centers, with the ordering and number of values consistent with the ordering and number of boundary cells.
  Return to "file structure anchor".
4. Read the EOS_STRUC end of section for this mesh/data block (tag=67):
```
        read(1) tag    
```
  where
  1. tag=67, identifying this EOS as one ending a structured mesh/data block subsection.
Return to "file structure anchor".
Read the EOS_HHDB end of section for this HHDB solution section (tag = 33):
```
        read(1) tag  
```
where
1. tag=33, identifying the end of a HHDB solution section.

Example Input and Output Programs

It is fairly simple to create a solution file in the HHDB format. Example subroutines for doing this can be found by following this link. On the other hand, some care must be taken when reading one. We have left room in the format for considerable future expansion. For this reason, unknown records must be disregarded. You will find an example Fortran program for reading a HHDB solution file by following this link. This routine is intended only to demonstrate the reading of an HHDB file.

The HHDB solution file compression routine, hhdbzip.c, can be found by following this link.

A routine for checking the integrity of an HHDB solution file can be found by following this link.

Last modified: Fri Sep 11 14:15:50 MET DST 1998