Input File Structure

The HDF5 input file for the C++ simulation code contains a file header with a brief description of the simulation stored in string attributes, and the root group ‘/’ which stores all the simulation properties in the form of 3D datasets irrespective of whether the simulation is in 2D or 3D. In the case of 2D simulation, Nz equals to 1. A complete list of input datasets is given below.

The HDF5 checkpoint file contains the same file header as the input file and the root group ‘/’ with a few datasets which capture the actual simulation state. The HDF5 output file contains a file header with the simulation description as well as performance statistics, such as the simulation time and memory consumption, stored in string attributes.

Input File / Checkpoint File Header

created_by

Short description of the tool that created this file

creation_date

Date when the file was created

file_description

Short description of the content of the file (e.g. simulation name)

file_type

Type of the file (input)

major_version

Major version of the file definition (1)

minor_version

Minor version of the file definition (2)

The input and checkpoint files store all quantities as three dimensional datasets stored in row-major order. If the simulation is 2D, Nz equals to 1. In order to support scalars and 1D and 2D arrays, the unused dimensions are set to 1. For example, scalar variables are stored with a dimension size of (1,1,1), 1D vectors oriented in y-direction are stored with a dimension size of (1, Ny, 1), and so on. If the dataset stores a complex variable, the real and imaginary parts are stored in an interleaved layout and the lowest used dimension size is doubled (i.e., Nx for a 3D matrix, Ny for a 1D vector oriented in the y-direction). The datasets are physically stored using either the ‘H5T_IEEE_F32LE’ or ‘H5T_STD_U64LE’ data type for floating point or integer based datasets, respectively. All the datasets are stored under the root group.

All datasets have two attributes that specify the content of the dataset. The ‘data_type’ attribute specifies the data type of the dataset. The admissible values are either ‘float’ or ‘long’. The ‘domain_type’ attribute specifies the domain of the dataset. The admissible values are either ‘real’ for the real domain or ‘complex’ for the complex domain. The C++ code reads these attributes and checks their values.

Simulation Flags

Name

Size

Data Type

Domain Type

Condition of Presence

ux_source_flag

(1, 1, 1)

long

real

uy_source_flag

(1, 1, 1)

long

real

uz_source_flag

(1, 1, 1)

long

real

Nz > 1

p_source_flag

(1, 1, 1)

long

real

p0_source_flag

(1, 1, 1)

long

real

transducer_source_flag

(1, 1, 1)

long

real

nonuniform_grid_flag

(1, 1, 1)

long

real

must be set to 0

nonlinear_flag

(1, 1, 1)

long

real

absorbing_flag

(1, 1, 1)

long

real

axisymmetric_flag

(1, 1, 1)

long

real

file_ver == 1.2

Grid Properties

Name

Size

Data Type

Domain Type

Condition of Presence

Nx

(1, 1, 1)

long

real

Ny

(1, 1, 1)

long

real

Nz

(1, 1, 1)

long

real

Nt

(1, 1, 1)

long

real

dt

(1, 1, 1)

float

real

dx

(1, 1, 1)

float

real

dy

(1, 1, 1)

float

real

dz

(1, 1, 1)

float

real

Nz > 1

Medium Properties

Name

Size

Data Type

Domain Type

Condition of Presence

Regular Medium Properties

rho0

(Nx, Ny, Nz)

float

real

heterogenous

(1, 1, 1)

float

real

homogenous

rho0_sgx

(Nx, Ny, Nz)

float

real

heterogenous

(1, 1, 1)

float

real

homogenous

rho0_sgy

(Nx, Ny, Nz)

float

real

heterogenous

(1, 1, 1)

float

real

homogenous

rho0_sgz

(Nx, Ny, Nz)

float

real

Nz > 1 and heterogenous

(1, 1, 1)

float

real

Nz > 1 and homogenous

c0

(Nx, Ny, Nz)

float

real

heterogenous

(1, 1, 1)

float

real

homogenous

c_ref

(1, 1, 1)

float

real

Nonlinear Medium Properties (defined if (nonlinear_flag == 1))

BonA

(Nx, Ny, Nz)

float

real

heterogenous

(1, 1, 1)

float

real

homogenous

Absorbing Medium Properties (defined if (absorbing_flag == 1))

alpha_coef

(Nx, Ny, Nz)

float

real

heterogenous

(1, 1, 1)

float

real

homogenous

alpha_power

(1, 1, 1)

float

real

Sensor Variables

Name

Size

Data Type

Domain Type

Condition of Presence

sensor_mask_type

(1, 1, 1)

long

real

file_ver > 1.0 (0 = index, 1 = corners)

sensor_mask_index

(Nsens, 1, 1)

long

real

file_ver == 1.0 always, file_ver > 1 and sensor_mask_type == 0

sensor_mask_corners

(Ncubes, 1, 1)

long

real

file_ver > 1 and sensor_mask_type == 1

Source Properties

Name

Size

Data Type

Domain Type

Condition of Presence

Velocity Source Terms (defined if (ux_source_flag > 0 || uy_source_flag > 0 || uz_source_flag > 1))

u_source_mode

(1, 1, 1)

long

real

u_source_many

(1, 1, 1)

long

real

u_source_index

(Nsrc, 1, 1)

long

real

ux_source_input

(1, Nt_src, 1)

float

real

u_source_many == 0

(Nsrc, Nt_src, 1)

float

real

u_source_many == 1

uy_source_input

(1, Nt_src, 1)

float

real

u_source_many == 0

(Nsrc, Nt_src, 1)

float

real

u_source_many == 1

uz_source_input

(1, Nt_src, 1)

float

real

Nz > 1 and u_source_many == 0

(Nsrc, Nt_src, 1)

float

real

Nz > 1 and u_source_many == 1

Pressure Source Terms (defined if (p_source_flag > 0))

p_source_mode

(1, 1, 1)

long

real

p_source_many

(1, 1, 1)

long

real

p_source_index

(Nsrc, 1, 1)

long

real

p_source_input

(Nsrc, Nt_src, 1)

float

real

p_source_many == 0

(1, Nt_src, 1)

float

real

p_source_many == 1

Transducer Source Terms (defined if (transducer_source_flag > 0))

u_source_index

(Nsrc, 1, 1)

long

real

transducer_source_input

(Nt_src, 1, 1)

float

real

delay_mask

(Nsrc, 1, 1)

float

real

IVP Source Terms (defined if ( p0_source_flag == 1))

u_source_index

(Nx, Ny, Nz)

float

real

K-space and Shift Variables

defined if (file version < 1.2)

Name

Size

Data Type

Domain Type

Condition of Presence

ddx_k_shift_pos_r

(Nx/2+1, 1, 1)

float

complex

ddx_k_shift_neg_r

(Nx/2+1, 1, 1)

float

complex

ddy_k_shift_pos_r

(1, Ny, 1)

float

complex

ddy_k_shift_neg_r

(1, Ny, 1)

float

complex

ddz_k_shift_pos_r

(1, 1, Nz)

float

complex

Nz > 1

ddz_k_shift_neg_r

(1, 1, Nz)

float

complex

Nz > 1

x_shift_neg_r

(Nx/2+1, 1, 1)

float

complex

file_ver > 1.0

y_shift_neg_r

(1, Ny/2+1, 1)

float

complex

file_ver > 1.0

z_shift_neg_r

(1, 1, Nz/2+1)

float

complex

Nz > 1 and file_ver > 1.0

PML Variables

Name

Size

Data Type

Domain Type

Condition of Presence

pml_x_size

(1, 1, 1)

long

real

pml_y_size

(1, 1, 1)

long

real

pml_z_size

(1, 1, 1)

long

real

Nz > 1

pml_x_alpha

(1, 1, 1)

float

real

pml_y_alpha

(1, 1, 1)

float

real

pml_z_alpha

(1, 1, 1)

float

real

Nz > 1

pml_x

(Nx, 1, 1)

float

real

file_ver < 1.2

pml_x_sgx

(Nx, 1, 1)

float

real

file_ver < 1.2

pml_y

(1, Ny, 1)

float

real

file_ver < 1.2

pml_y_sgx

(1, Ny, 1)

float

real

file_ver < 1.2

pml_z

(1, 1, Nz)

float

real

Nz > 1 and file_ver < 1.2

pml_z_sgx

(1, 1, Nz)

float

real

Nz > 1 and file_ver < 1.2