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', dtype=None, save_only=False, data_path=None, quiet=False, debug=False, num_threads=None, device_num=None, binary_path=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)

  • binary_path (str | 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".

  • dtype – Numerical precision for state arrays in the Python backend. Accepts dtype-like input — a numpy dtype (np.float32, np.float64; cupy aliases like cp.float32 work since cupy re-exports numpy’s scalar types), a string ("float32", "float64", "single", "double"), a Python type (float), or None for the default (float64). The MATLAB-style alias "off" is accepted as a synonym for float64 to ease migration from the legacy SimulationOptions.data_cast. Torch / JAX dtypes are not accepted; pass the numpy equivalent (e.g. np.float32 for torch.float32). np.float32 uses roughly half the memory and is faster on most hardware, at the cost of reduced numerical accuracy. Only float32 and float64 are supported; other dtypes raise ValueError. Has no effect on backend="cpp" (the C++ binary uses fixed internal precision regardless); a warning is emitted if dtype resolves to anything other than float64 with the C++ backend. Default None (float64).

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

  • binary_path – Path to a custom C++ binary. When None (default), the binary bundled with k-wave-data is used. Only applies when backend="cpp".

Returns:

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

All time-series are (n_sensor, Nt) with sensor points in C-flattened order. Use reshape_to_grid() to recover spatial structure for full-grid masks.

Return type:

dict

reshape_to_grid(data, grid_shape)[source]

Reshape flat sensor data to grid shape.

Convenience helper for full-grid sensor masks where n_sensor equals the total number of grid points.

Parameters:

  • data – sensor array — (n_sensor, Nt) time-series or (n_sensor,) aggregate.

  • grid_shape – tuple of grid dimensions, e.g. (Nx, Ny).

Returns:

(*grid_shape, Nt) For aggregates: (*grid_shape)

Return type:

For time-series