options

Simulation options module for k-Wave.

This module provides classes for configuring simulation parameters and execution options for k-Wave simulations.

class SimulationExecutionOptions[source]

Bases: object

A class to manage and configure the execution options for k-Wave simulations.

backend

Execution backend to use. Options: - “OMP”: C++ OpenMP binary (default for CPU) - “CUDA”: C++ CUDA binary (default for GPU) - “python”: Pure Python/CuPy solver (no external binaries required)

__init__(is_gpu_simulation=False, binary_path=None, binary_dir=None, binary_name=None, kwave_function_name='kspaceFirstOrder3D', delete_data=True, device_num=None, num_threads=None, thread_binding=None, system_call=None, verbose_level=0, auto_chunking=True, show_sim_log=True, checkpoint_interval=None, checkpoint_timesteps=None, checkpoint_file=None, backend=None)[source]
Parameters:

  • is_gpu_simulation (bool)

  • binary_path (str | None)

  • binary_dir (str | None)

  • binary_name (str | None)

  • kwave_function_name (str | None)

  • delete_data (bool)

  • device_num (int | None)

  • num_threads (int | None)

  • thread_binding (bool | None)

  • system_call (str | None)

  • verbose_level (int)

  • auto_chunking (bool | None)

  • show_sim_log (bool)

  • checkpoint_interval (int | None)

  • checkpoint_timesteps (int | None)

  • checkpoint_file (Path | str | None)

  • backend (str | None)

as_list(sensor)[source]
Parameters:

sensor (kSensor)

Return type:

list[str]

property backend: str | None
property binary_dir: str
property binary_name: str
property binary_path: Path
property checkpoint_file: Path | None
property checkpoint_interval: int | None
property checkpoint_timesteps: int | None
property device_num: int | None
property env_vars: dict
get_options_string(sensor)[source]
Parameters:

sensor (kSensor)

Return type:

str

property is_gpu_simulation: bool | None
property is_python_backend: bool
property num_threads: int | str
property num_threads_explicit: bool

True if user explicitly set num_threads (vs auto-detected cpu_count).

property verbose_level: int
class SimulationOptions[source]

Bases: object

Parameters:

  • axisymmetric – Flag that indicates whether axisymmetric simulation is used

  • cart_interp – Interpolation mode used to extract the pressure when a Cartesian sensor mask is given. If set to ‘nearest’ and more than one Cartesian point maps to the same grid point, duplicated data points are discarded and sensor_data will be returned with less points than that specified by sensor.mask (default = ‘linear’).

  • pml_inside – put the PML inside the grid defined by the user

  • pml_alpha – Absorption within the perfectly matched layer in Nepers per grid point (default = 2).

  • save_to_disk – save the input data to a HDF5 file

  • save_to_disk_exit – exit the simulation after saving the HDF5 file

  • scale_source_terms – apply the source scaling term to time varying sources

  • smooth_c0 – smooth the sound speed distribution

  • smooth_rho0 – smooth the density distribution

  • smooth_p0 – smooth the initial pressure distribution

  • use_kspace – use the k-space correction

  • use_sg – use a staggered grid

  • use_fd – Use finite difference gradients instead of spectral (in 1D)

  • pml_auto – automatically choose the PML size to give small prime factors

  • create_log – create a log using diary

  • use_finite_difference – use finite difference gradients instead of spectral (in 1D)

  • stream_to_disk – String containing a filename (including pathname if required). If set, after the precomputation phase, the input variables used in the time loop are saved the specified location in HDF5 format. The simulation then exits. The saved variables can be used to run simulations using the C++ code.

  • data_recast – recast the sensor data back to double precision

  • cartesian_interp – interpolation mode for Cartesian sensor mask

  • hdf_compression_level – zip compression level for HDF5 input files

  • data_cast – data cast

  • pml_search_range – search range used when automatically determining PML size

  • radial_symmetry – radial symmetry used in axisymmetric code

  • multi_axial_PML_ratio – MPML settings

  • pml_x_alpha – PML Alpha for x-axis

  • pml_y_alpha – PML Alpha for y-axis

  • pml_z_alpha – PML Alpha for z-axis

  • pml_x_size – PML Size for x-axis

  • pml_y_size – PML Size for y-axis

  • pml_z_size – PML Size for z-axis

__init__(simulation_type=SimulationType.FLUID, cart_interp='linear', pml_inside=True, pml_alpha=2.0, save_to_disk=False, save_to_disk_exit=False, scale_source_terms=True, smooth_c0=False, smooth_rho0=False, smooth_p0=True, use_kspace=True, use_sg=True, use_fd=None, pml_auto=False, create_log=False, use_finite_difference=False, stream_to_disk=False, data_recast=False, cartesian_interp='linear', hdf_compression_level=None, data_cast='off', pml_search_range=<factory>, radial_symmetry='WSWA-FFT', multi_axial_PML_ratio=0.1, data_path=<factory>, input_filename=<factory>, output_filename=<factory>, pml_x_alpha=None, pml_y_alpha=None, pml_z_alpha=None, pml_size=None, pml_x_size=None, pml_y_size=None, pml_z_size=None)
Parameters:

  • simulation_type (SimulationType)

  • cart_interp (str)

  • pml_inside (bool)

  • pml_alpha (float)

  • save_to_disk (bool)

  • save_to_disk_exit (bool)

  • scale_source_terms (bool)

  • smooth_c0 (bool)

  • smooth_rho0 (bool)

  • smooth_p0 (bool)

  • use_kspace (bool)

  • use_sg (bool)

  • use_fd (int | None)

  • pml_auto (bool)

  • create_log (bool)

  • use_finite_difference (bool)

  • stream_to_disk (bool)

  • data_recast (bool | None)

  • cartesian_interp (str)

  • hdf_compression_level (int | None)

  • data_cast (str)

  • pml_search_range (List[int])

  • radial_symmetry (str)

  • multi_axial_PML_ratio (float)

  • data_path (str | None)

  • input_filename (str | None)

  • output_filename (str | None)

  • pml_x_alpha (float | None)

  • pml_y_alpha (float | None)

  • pml_z_alpha (float | None)

  • pml_size (List[int] | None)

  • pml_x_size (int | None)

  • pml_y_size (int | None)

  • pml_z_size (int | None)

Return type:

None

cart_interp: str = 'linear'
cartesian_interp: str = 'linear'
create_log: bool = False
data_cast: str = 'off'
data_path: str | None
data_recast: bool | None = False
hdf_compression_level: int | None = None
input_filename: str | None
multi_axial_PML_ratio: float = 0.1
static option_factory(kgrid, options)[source]

Initialize the Simulation Options

Parameters:

  • kgrid (kWaveGrid) – kWaveGrid instance

  • elastic_code – Flag that indicates whether elastic simulation is used

  • **kwargs –

    Dictionary that holds following optional simulation properties:

    • cart_interp: Interpolation mode used to extract the pressure when a Cartesian sensor mask is given.

      If set to ‘nearest’, duplicated data points are discarded and sensor_data will be returned with fewer points than specified by sensor.mask (default = ‘linear’).

    • create_log: Boolean controlling whether the command line output is saved using the diary function

      with a date and time stamped filename (default = false).

    • data_cast: String input of the data type that variables are cast to before computation.

      For example, setting to ‘single’ will speed up the computation time (due to the improved efficiency of fftn and ifftn for this data type) at the expense of a loss in precision (default = ‘off’).

    • data_recast: Boolean controlling whether the output data is cast back to double precision.

      If set to false, sensor_data will be returned in the data format set using the ‘data_cast’ option.

    • hdf_compression_level: Compression level used for writing the input HDF5 file when using

      ’save_to_disk’ or kspaceFirstOrder3DC. Can be set to an integer between 0 (no compression, the default) and 9 (maximum compression). The compression is lossless. Increasing the compression level will reduce the file size if there are portions of the medium that are homogeneous, but will also increase the time to create the HDF5 file.

    • multi_axial_pml_ratio: MPML settings

    • pml_alpha: Absorption within the perfectly matched layer in Nepers per grid point (default = 2).

    • pml_inside: Boolean controlling whether the perfectly matched layer is inside or outside the grid.

      If set to false, the input grids are enlarged by pml_size before running the simulation (default = true).

    • pml_range: Search range used when automatically determining PML size. Tuple of two elements

    • pml_size: Size of the perfectly matched layer in grid points. By default, the PML is added evenly to

      all sides of the grid, however, both pml_size and pml_alpha can be given as three element arrays to specify the x, y, and z properties, respectively. To remove the PML, set the appropriate pml_alpha to zero rather than forcing the PML to be of zero size (default = 10).

    • radial_symmetry: Radial symmetry used in axisymmetric code

    • stream_to_disk: Boolean controlling whether sensor_data is periodically saved to disk to avoid storing

      the complete matrix in memory. StreamToDisk may also be given as an integer which specifies the number of time steps that are taken before the data is saved to disk (default = 200).

    • save_to_disk: String containing a filename (including pathname if required).

      If set, after the precomputation phase, the input variables used in the time loop are saved the specified location in HDF5 format. The simulation then exits. The saved variables can be used to run simulations using the C++ code.

    • save_to_disk_exit: Exit the simulation after saving the HDF5 file

    • scale_source_terms: Apply the source scaling term to time varying sources

    • use_fd: Use finite difference gradients instead of spectral (in 1D)

    • use_k_space: use the k-space correction

    • use_sg: Use a staggered grid

  • options (SimulationOptions)

Returns:

SimulationOptions instance

output_filename: str | None
pml_alpha: float = 2.0
pml_auto: bool = False
pml_inside: bool = True
pml_search_range: List[int]
pml_size: List[int] | None = None
pml_x_alpha: float | None = None
pml_x_size: int | None = None
pml_y_alpha: float | None = None
pml_y_size: int | None = None
pml_z_alpha: float | None = None
pml_z_size: int | None = None
radial_symmetry: str = 'WSWA-FFT'
save_to_disk: bool = False
save_to_disk_exit: bool = False
scale_source_terms: bool = True
simulation_type: SimulationType = 1
smooth_c0: bool = False
smooth_p0: bool = True
smooth_rho0: bool = False
stream_to_disk: bool = False
use_fd: int | None = None
use_finite_difference: bool = False
use_kspace: bool = True
use_sg: bool = True