kspaceFirstOrder3D

kspaceFirstOrder3D(kgrid, source, sensor, medium, simulation_options, execution_options, time_rev=False)[source]

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

This simulation function performs time-domain acoustic simulations in 3D 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. The time_rev parameter will be removed in v2.0.

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, plane)

  • 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]

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)

time_revbool, optional

Deprecated parameter for time reversal mode. Use TimeReversal class instead.

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.

  4. GPU execution requires the C++/CUDA binary from k-wave.org.

See Also:

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

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

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

This function provides a blind interface to the C++ version of kspaceFirstOrder3D (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 large simulations, it’s recommended to adjust the ‘NumThreads’ parameter in execution_options to optimize performance for your specific hardware configuration.

Parameters:

kgridkWaveGrid

Grid object containing Cartesian and k-space grid fields

sourcekSource

Source object containing details of acoustic sources

sensorUnion[NotATransducer, kSensor]

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 large simulations, consider adjusting memory usage via chunking options

See Also:

kspaceFirstOrder3D : Main simulation function

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

3D 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 kspaceFirstOrder3D (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]

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:

  1. The GPU version uses the same binary for both 2D and 3D simulations

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

See Also:

kspaceFirstOrder3D : CPU version of this simulation function

Parameters:
Return type:

ndarray | dict