openlifu.sim.kwave_if.run_simulation

openlifu.sim.kwave_if.run_simulation(arr: Transducer, params: Dataset, delays: ndarray | None = None, apod: ndarray | None = None, freq: float = 1000000.0, cycles: float = 20, amplitude: float = 1, dt: float = 0, t_end: float = 0, cfl: float = 0.5, bli_tolerance: float = 0.05, upsampling_rate: int = 5, gpu: bool = True, ref_values_only: bool = False, return_kwave_outputs: bool = False, return_kwave_inputs: bool = False, sensor_record: List[str] = ['p_max', 'p_min'], _source=None, _sensor=None)[source]

Run a k-wave simulation for the given transducer array and parameters. :param arr: The transducer array to simulate. :param params: The simulation parameters as an xarray Dataset. Must include ‘sound_speed’, ‘ :param density’: :param and ‘attenuation’ variables with appropriate units.: :param delays: Optional array of time delays for each element in the transducer array, in seconds. If None, no delays will be applied. :param apod: Optional array of apodization values for each

element in the transducer array. If None, no apodization will be applied.

Parameters:

  • freq – The frequency of the input signal in Hz. Default is 1 MHz.

  • cycles – The number of cycles in the input signal. Default is 20.

  • amplitude – The amplitude of the input signal. Default is 1.

  • dt – The time step for the simulation in seconds. If 0, it will be automatically calculated based on the CFL condition.

  • t_end – The total time for the simulation in seconds. If 0, it will be automatically calculated based on the input signal duration and the CFL condition.

  • cfl – The Courant-Friedrichs-Lewy (CFL) number for the simulation. Default is 0.5.

  • bli_tolerance – The tolerance for the boundary layer integral method used in k-wave. Default is 0.05.

  • upsampling_rate – The upsampling rate for the boundary layer integral method used in k-wave Default is 5.

  • gpu – Whether to use GPU for the simulation. Default is True. If False, the simulation will run on the CPU. Note that running on CPU may be very slow for large simulations.

  • ref_values_only – Whether to use only the reference values for the medium properties (sound speed, density, attenuation) instead of the full spatial maps. Default is False. Setting this to True can significantly speed up the simulation, but will not capture any spatial variations in the medium properties.

  • return_kwave_outputs – Whether to return the raw outputs from k-wave in addition to the processed xarray Dataset. Default is False.

  • return_kwave_inputs – Whether to return the inputs to k-wave (kgrid, source, sensor, medium) in addition to the processed xarray Dataset. Default is False.

  • sensor_record – List of strings specifying which k-wave sensor outputs to record. Can include ‘

  • p_max'

  • 'p_min'

  • ['p_max' (and 'p'. Default is)

  • 'p_min'].

Additional Args:

_source: Optional kSource object to use for the simulation. If None, a source will be created based on the transducer array and input signal. _sensor: Optional kSensor object to use for the simulation. If None, a sensor

Returns:

An xarray Dataset containing the simulation results, with variables corresponding to the requested sensor outputs and coordinates corresponding to the spatial dimensions of the simulation. If return_kwave_outputs is True, also returns a dictionary containing the raw outputs from k-wave. If return_kwave_inputs is True, also returns a dictionary containing the inputs to k-wave.