k-Wave Input File

class kwave_input_file.KWaveInputFile(file_name, domain_shape, nt, spatial_delta, time_delta, c_ref=1500.0, pml_alpha=2, pml_size=20, reoder_output_data=True)

Represents k-Wave input file.

class SensorType

An enumeration.

class SourceMode

An enumeration.

__init__(file_name, domain_shape, nt, spatial_delta, time_delta, c_ref=1500.0, pml_alpha=2, pml_size=20, reoder_output_data=True)

Constructor of k-Wave input file generator.

Parameters
  • file_name – Name of the generated input file.

  • domain_shape – Spatial shape of the simulation domain in number of grid points.

  • nt – Total number of time-steps of “time_delta” to be performed in the simulation.

  • spatial_delta – Spatial resolution of the simulation domain in meters [m].

  • time_delta – Temporal resolution of the simulation in seconds [s].

  • c_ref – Reference sound-speed of the medium used to compute k-space correction coefficient [m/s].

  • pml_alpha – Absorption coefficient [Nepers per grid point]

  • pml_size – Width of the PML used to absorb wave leaving the simulation domain [grid points].

  • reoder_output_data – When set to True simulation data are reordered so that MATLAB semantics is preserved. Otherwise ONLY the simulation shape is changed to (Nz, Ny, Nx) and data ordering is preserved (spatial resolution, pml properties etc. are likewise reordered)

close()

Finalize the output file and close it.

domain_mask_to_index(mask)

Convert the domain shaped non-zero mask to flat array of indexes in the data order written to the file. This should be used to generate indexes for source and sensor masks.

Parameters

mask – Domain shaped ND-array representing the non-zero mask.

Returns

Flat array of indexes valid in output file data order.

domain_mask_values_in_index_order(mask)

Extract non-zero values from domain shaped mask to flat array of values. The order of values is returned in the order in which indexes would be written to the file.

Parameters

mask – Domain shaped ND-array representing the non-zero mask.

Returns

Flat array of non-zero values in output file data order.

open()

Creates output HDF5 file.

write_medium_absorbing(alpha_coeff, alpha_power=1.0)

Write frequency dependent absorption properties of the medium.

Parameters
  • alpha_coeff – Power law absorption coefficient (N-dim array or scalar float).

  • alpha_power – Power law absorption exponent (scalar float).

write_medium_density(rho0)

Write medium density [kg/m^3] into the opened file. The value has to be either scalar or N-dim array of same shape as the simulation domain.

Parameters

rho0 – Medium density N-dim array or scalar float value [kg/m^3].

write_medium_non_linear(b_on_a)

Write non-linear coefficient (B/A) into the opened file. The value has to be either scalar or N-dim array of the same shape as the simulation domain.

Parameters

b_on_a – Medium non-linear coefficient (B/A) N-dim array or scalar float.

write_medium_sound_speed(c0, c_ref=None)

Write medium sound speed [m/s] into the opened file. The value has to be either scalar or N-dim array of the same shape as the simulation domain.

Parameters
  • c0 – Medium sound speed N-dim array or scalar float value [m/s].

  • c_ref – Reference sound-speed of the medium used to compute k-space correction coefficient [m/s].

write_sensor_mask_corners(corners)

Write corners sensor mask to the output file. Corners sensor mask denotes cuboids in the simulation domain whose values will be stored at each time step.

Parameters

corners – Corners of sampled axis-aligned cuboids stored as 3D array of: ((LTx, LTy, LTz), (RBx, RBy, RBz)), … in Nx2x3 array. Example: [[(0, 0, 0), (10, 10, 10)], [(20, 20, 20), (30, 30, 30)]] is two cuboids, where first starts at grid point 0,0,0 and extends to 10,10,10 and second starts at 20,20,20 and ends at 30,30,30.

write_sensor_mask_index(index)

Write index sensor mask to the output file. Sensor mask denotes grid points whose value will be stored to the output file at each time step.

Parameters

index – Zero based indexes into the simulation domain denoting sensor grid points (1D vector).

write_source_input_p(index, data, mode: kwave_input_file.KWaveInputFile.SourceMode, c0)

Write pressure source data to the output file. Pressure sources support two modes:

Single series mode (SSM): This mode uses single series to drive all source points.

Multi series mode (MSM): This mode uses separate series to drive each source point.

Sources can be either dirichlet or additive in both modes.

Parameters
  • index – Zero based indexes into the simulation domain denoting source grid points.

  • data – Source values to be applied at each time step [Pa]. In SSM 1D vector is expected while in MSM 2D matrix of (len(index), [signal_len]) is expected instead.

  • mode – Dirichlet or Additive source mode (member of SourceMode enum)

  • c0 – Medium sound speed used to normalize the source (N-dim array or scalar float value [m/s]). Reference sound speed is used if not provided.

write_source_input_p0(p0)

Write initial acoustic pressure distribution it the simulation domain.

Parameters

p0 – Initial pressure (N-dim array) in [Pa].

write_source_input_transducer(index, series_data, delay_mask, c0)

Write transducer source data to the output file. Transducer source is additive velocity source, which is flat and assumes that all the energy is transferred in the X-direction. While signals in all source points are the same each point is associated with “delay_mask”, which is added to current time step to compute offset in the “series_data”.

Parameters
  • index – Zero based indexes into the simulation domain denoting source grid points (1D vector).

  • series_data – X-axis component of source values applied at each time step (1D vector).

  • delay_mask – Delay (# of time steps) of the series for each source point in “index” (1D vector).

  • c0 – Medium sound speed used to normalize the source (N-dim array or scalar float value [m/s]). Reference sound speed is used if not provided.

write_source_input_u(index, data_ux, data_uy, data_uz, mode: kwave_input_file.KWaveInputFile.SourceMode, c0)

Write velocity source data to the output file. Velocity source consist of vector valued elements for each time step. While its possible to leave any of vector components implicitly zero at least one component has to be specified. Velocity sources support two modes:

Single series mode (SSM): This mode uses single series to drive all source points.

Multi series mode (MSM): This mode uses separate series to drive each source point.

The data series “data_u{x,y,z}” are expected to be 1D vectors in the SSM mode and 2D matrices of (len(index), [signal_len]) in MSM mode. Sources can be either dirichlet or additive in both modes.

Parameters
  • index – Zero based indexes into the simulation domain denoting source grid points.

  • data_ux – X-axis component of source values applied at each time step.

  • data_uy – Y-axis component of source values applied at each time step.

  • data_uz – Z-axis component of source values applied at each time step.

  • mode – Dirichlet or Additive source mode (member of SourceMode enum)

  • c0 – Medium sound speed used to normalize the source (N-dim array or scalar float value [m/s]). Reference sound speed is used if not provided.