kspaceFirstOrder2D

kspaceFirstOrder2D(kgrid, source, sensor, medium, simulation_options, execution_options)[source]

2D time-domain simulation of wave propagation using k-space pseudospectral method.

This simulation function performs time-domain acoustic simulations in 2D homogeneous and heterogeneous media. The function is based on a k-space pseudospectral method where spatial derivatives are calculated using the Fourier collocation spectral method, and temporal derivatives are calculated using a k-space corrected finite-difference scheme.

Warning

The time reversal functionality (using sensor.time_reversal_boundary_data) is deprecated. Please use the TimeReversal class from kwave.reconstruction instead.

Key Features:

  • Support for both homogeneous and heterogeneous media

  • Perfectly matched layer (PML) boundary conditions

  • Flexible source and sensor configurations

  • Support for absorption and nonlinearity

  • Time-varying source terms

  • Various sensor types (point, line)

  • Binary and Cartesian sensor masks

  • Recording of pressure, velocity, and intensity

Parameters:

kgridkWaveGrid

Grid object containing Cartesian and k-space grid fields

sourcekSource

Source object containing details of acoustic sources

sensorUnion[NotATransducer, kSensor, None]

Sensor object for recording the acoustic field

mediumkWaveMedium

Medium properties including sound speed, density, etc.

simulation_optionsSimulationOptions

Simulation settings and flags

execution_optionsSimulationExecutionOptions

Options controlling execution environment (CPU/GPU)

Returns:

np.ndarray

Recorded sensor data based on the sensor.record settings

Notes:

  1. The simulation is based on coupled first-order equations for wave propagation.

  2. The time step is chosen based on the CFL stability criterion.

  3. For time reversal reconstruction, use the TimeReversal class from kwave.reconstruction.

See Also:

kwave.reconstruction.TimeReversal : Class for time reversal image reconstruction kspaceFirstOrder3D : 3D version of this simulation function

Parameters:
kspaceFirstOrder2DC(kgrid, source, sensor, medium, simulation_options, execution_options)[source]

2D time-domain simulation of wave propagation using C++ code.

This function provides a blind interface to the C++ version of kspaceFirstOrder2D (called kspaceFirstOrder-OMP). The function works by saving the input files to disk, running the C++ simulation, and loading the output files back into Python.

For small simulations, running the simulation on a smaller number of cores can improve performance as the matrices are often small enough to fit within cache. It is recommended to adjust the value of ‘NumThreads’ to optimize performance for a given simulation size and computer hardware. By default, simulations smaller than 128^2 are set to run using a single thread (this behavior can be over-ridden using the ‘NumThreads’ option).

Parameters:

kgridkWaveGrid

Grid object containing Cartesian and k-space grid fields

sourcekSource

Source object containing details of acoustic sources

sensorUnion[NotATransducer, kSensor, None]

Sensor object for recording the acoustic field

mediumkWaveMedium

Medium properties including sound speed, density, etc.

simulation_optionsSimulationOptions

Simulation settings and flags

execution_optionsSimulationExecutionOptions

Options controlling execution environment (CPU/GPU)

Returns:

np.ndarray

Recorded sensor data based on the sensor.record settings

Notes:

  1. Required binaries are automatically downloaded and managed by k-wave-python

  2. The same binary is used for 2D, 3D, and axisymmetric simulations

  3. For very small simulations, the C++ code can be slower than the Python code

See Also:

kspaceFirstOrder2D : Main simulation function

Parameters:
kspace_first_order_2d_gpu(kgrid, source, sensor, medium, simulation_options, execution_options)[source]

2D time-domain simulation of wave propagation on a GPU using C++ CUDA code.

This function provides a blind interface to the C++/CUDA version of kspaceFirstOrder2D (called kspaceFirstOrder-CUDA). The function works by saving the input files to disk, running the C++/CUDA simulation, and loading the output files back into Python.

Parameters:

kgridkWaveGrid

Grid object containing Cartesian and k-space grid fields

sourcekSource

Source object containing details of acoustic sources

sensorUnion[NotATransducer, kSensor, None]

Sensor object for recording the acoustic field

mediumkWaveMedium

Medium properties including sound speed, density, etc.

simulation_optionsSimulationOptions

Simulation settings and flags

execution_optionsSimulationExecutionOptions

Options controlling execution environment (CPU/GPU)

Returns:

Union[np.ndarray, dict]

Either: - A numpy array containing the recorded sensor data if sensor.record is set - A dictionary containing simulation metadata if sensor.record is not set

Notes:

The GPU version uses the same binary for both 2D and 3D simulations. Required binaries are automatically downloaded and managed by k-wave-python.

See Also:

kspaceFirstOrder2D : CPU version of this simulation function

Parameters:
Return type:

ndarray | dict