kwave.kspaceFirstOrder module

kspaceFirstOrder(kgrid, medium, source, sensor=None, *, pml_size=20, pml_alpha=2.0, pml_inside=False, use_sg=True, use_kspace=True, smooth_p0=True, backend='python', device='cpu', save_only=False, data_path=None, quiet=False, debug=False, num_threads=None, device_num=None)[source]

Run a k-Wave simulation.

Unified entry point replacing the legacy kspaceFirstOrder2D / 3D functions. Works with 1-D, 2-D, and 3-D grids.

Parameters:

  • kgrid (kWaveGrid) – Simulation grid (defines dimensionality, spacing, and time steps).

  • medium (kWaveMedium) – Acoustic medium properties (sound speed, density, absorption, nonlinearity).

  • source (kSource) – Pressure and/or velocity source terms.

  • sensor (kSensor | NotATransducer | None) – Sensor mask defining where the field is recorded. None records the entire grid.

  • pml_size (int | tuple | str)

  • pml_alpha (float | tuple)

  • pml_inside (bool)

  • use_sg (bool)

  • use_kspace (bool)

  • smooth_p0 (bool)

  • backend (str)

  • device (str)

  • save_only (bool)

  • data_path (str | None)

  • quiet (bool)

  • debug (bool)

  • num_threads (int | None)

  • device_num (int | None)

Keyword Arguments:

  • pml_size – Perfectly-matched-layer thickness in grid points. A scalar applies to all dimensions; a tuple sets each dimension independently. "auto" selects an optimal size via FFT-based analysis. Default 20.

  • pml_alpha – PML absorption coefficient (Nepers per grid point). Scalar or per-dimension tuple. Default 2.0.

  • pml_inside – When False (default), the grid is automatically expanded by 2 * pml_size so the PML sits outside the user domain; full-grid output fields (_final, _max, etc.) are cropped back to the original size. When True, the PML occupies the outermost grid points of the user-supplied grid, which saves memory but means PML absorption will modify field values near the domain boundary.

  • use_sg – Use a staggered grid for velocity fields. Default True.

  • use_kspace – Apply the k-space correction to the time-stepping scheme. Default True.

  • smooth_p0 – Smooth the initial pressure distribution to suppress staircasing artifacts. Default True.

  • backend – Simulation engine. "python" runs a pure-Python / NumPy / CuPy solver; "cpp" serializes to HDF5 and invokes the compiled C++ binary. Default "python".

  • device – "cpu" or "gpu". For backend="python" this selects NumPy (cpu) vs CuPy (gpu). For backend="cpp" it selects the OMP vs CUDA binary. Default "cpu".

  • save_only – When True (backend="cpp" only), write the HDF5 input file and return without running the binary. Useful for cluster submission. Default False.

  • data_path – Directory for HDF5 input/output files (backend="cpp" only). If None a temporary directory is created and cleaned up automatically after the run. Set explicitly to inspect or reuse the HDF5 files. Default None.

  • quiet – Suppress progress output. Default False.

  • debug – Print detailed diagnostic output. Default False.

  • num_threads – Thread count for the C++ OMP binary. None uses all available cores. Default None.

  • device_num – GPU device index for CUDA execution. Default None.

Returns:

Recorded sensor data keyed by field name (e.g. "p", "p_final", "ux", "uy").

Return type:

dict