kwave.kWaveSimulation module#

class kWaveSimulation[source]#

Bases: object

kWaveSimulation(kgrid: kwave.kgrid.kWaveGrid, source: kwave.ksource.kSource, sensor: kwave.ktransducer.NotATransducer, medium: kwave.kmedium.kWaveMedium, simulation_options: kwave.options.simulation_options.SimulationOptions)

COLOR_MAP#: default color map

ESTIMATE_SIM_TIME_STEPS#: time steps used to estimate simulation time

HIGHEST_PRIME_FACTOR_WARNING#: largest prime factor before warning

KSPACE_CFL#: default CFL value used if kgrid.t_array is set to ‘auto’

LOG_NAME#: default log filename

PSTD_CFL#: default CFL value used if kgrid.t_array is set to ‘auto’

SOURCE_P_MODE_DEF#: source mode for pressure sources

SOURCE_S_MODE_DEF#: source mode for stress sources

SOURCE_U_MODE_DEF#: source mode for velocity sources

STREAM_TO_DISK_FILENAME#: default disk stream filename

__init__(kgrid, source, sensor, medium, simulation_options)[source]#

Parameters:

kgrid (kWaveGrid) –
source (kSource) –
sensor (NotATransducer) –
medium (kWaveMedium) –
simulation_options (SimulationOptions) –

absorb_eta#: dispersive fractional Laplacian coefficient

absorb_nabla1#: absorbing fractional Laplacian operator

absorb_nabla2#: dispersive fractional Laplacian operator

absorb_tau#: absorbing fractional Laplacian coefficient

assign_pseudonyms(medium, kgrid)[source]#

Shorten commonly used field names (these act only as pointers provided that the values aren’t modified) (done after enlarging and smoothing the grids)

Parameters:

medium (kWaveMedium) – kWaveMedium instance
kgrid (kWaveGrid) – kWaveGrid instance

Returns:

None

Return type:

None

binary_sensor_mask#: Whether the sensor.mask is binary

property blank_sensor#: Returns True if sensor.mask is not defined but _max_all or _final variables are still recorded

c0#: Alias to medium.sound_speed

static check_calling_func_name_and_dim(calling_func_name, kgrid_dim)[source]#

Check correct function has been called for the dimensionality of kgrid

Parameters:

calling_func_name – Name of the script that makes calls to kWaveSimulation
kgrid_dim – Dimensionality of the kWaveGrid

Returns:

None

Return type:

None

check_input_combinations(opt, user_medium_density_input, k_dim, pml_size, kgrid_N)[source]#

Check the input combinations for correctness and validity

Parameters:

opt (SimulationOptions) – SimulationOptions instance
user_medium_density_input (bool) – Medium Density
k_dim – kWaveGrid dimensionality
pml_size – Size of the PML
kgrid_N – kWaveGrid size in each direction

Returns:

None

Return type:

None

check_kgrid_time()[source]#

Check time-related kWaveGrid inputs

Returns:: None
Return type:: None

static check_medium(medium, kgrid_k, simulation_type)[source]#

Check the properties of the medium structure for correctness and validity

Parameters:

medium – kWaveMedium instance
kgrid_k – kWaveGrid.k matrix
is_elastic – Whether the simulation is elastic
is_axisymmetric – Whether the simulation is axisymmetric
simulation_type (SimulationType) –

Returns:

Medium Density

Return type:

bool

check_sensor(kgrid_dim)[source]#

Check the Sensor properties for correctness and validity

Parameters:: k_dim – kWaveGrid dimensionality
Returns:: None
Return type:: None

check_source(k_dim, k_Nt)[source]#

Check the source properties for correctness and validity

Parameters:

kgrid_dim – kWaveGrid dimension
k_Nt – Number of time steps in kWaveGrid

Returns:

None

Return type:

None

property compute_directivity#: Returns: True if directivity calculations in 2D are used by setting sensor.directivity_angle

create_absorption_vars()[source]#

Create absorption variables for the fluid code based on the expanded and smoothed values of the medium parameters (if not saving to disk)

Returns:: None
Return type:: None

create_pml_indices(kgrid_dim, kgrid_N, pml_size, pml_inside, is_axisymmetric)[source]#

Define index variables to remove the PML from the display if the optional input ‘PlotPML’ is set to false

Parameters:

kgrid_dim – kWaveGrid dimensinality
kgrid_N (Vector) – kWaveGrid size in each direction
pml_size – Size of the PML
pml_inside – Whether the PML is inside the grid defined by the user
is_axisymmetric – Whether the simulation is axisymmetric

create_sensor_variables()[source]#

Create the sensor related variables

Returns:: None
Return type:: None

property cuboid_corners#: Returns: Whether the sensor.mask is a list of cuboid corners

delay_mask#: Delay mask that accounts for the beamforming delays and elevation focussing

dt#: Alias to kgrid.dt

property elastic_time_rev#: Returns: True if using time reversal with the elastic code

property equation_of_state#: Returns: Set equation of state variable

input_checking(calling_func_name)[source]#

Check the input fields for correctness and validness

Parameters:: calling_func_name – Name of the script that calls this function
Returns:: None
Return type:: None

property kelvin_voigt_model#: Returns: Whether the simulation is elastic with absorption

property nonuniform_grid#: Returns: True if the computational grid is non-uniform

p_source_pos_index#: Indexing variable corresponding to the location of all the pressure source elements

static print_start_status(is_elastic_code)[source]#

Update command-line status with the start time

Parameters:: is_elastic_code (bool) – is the simulation elastic
Returns:: None
Return type:: None

reorder_data#: Whether sensor.mask should be re-ordered. True if sensor.mask is Cartesian with nearest neighbour interpolation which is calculated using a binary mask and thus must be re-ordered

rho0#: Alias to medium.density

s_source_pos_index#: Indexing variable corresponding to the location of all the stress source elements

scale_source_terms(is_scale_source_terms)[source]#

Scale the source terms based on the expanded and smoothed values of the medium parameters

Parameters:: is_scale_source_terms – Should the source terms be scaled
Returns:: None
Return type:: None

static select_precision(opt)[source]#

Select the minimal precision for storing the data

Parameters:: opt (SimulationOptions) – SimulationOptions instance
Returns:: Minimal precision for variable allocation

set_index_data_type()[source]#

Pre-calculate the data type needed to store the matrix indices given the total number of grid points: indexing variables will be created using this data type to save memory

Returns:: None
Return type:: None

smooth_and_enlarge(source, k_dim, kgrid_N, opt)[source]#

Smooth and enlarge grids

Parameters:

source – kWaveSource instance
k_dim – kWaveGrid dimensionality
kgrid_N – kWaveGrid size in each direction
opt (SimulationOptions) – SimulationOptions

Returns:

None

Return type:

None

property source_p#: Returns: Whether time-varying pressure source is present (default=False)

property source_p0#: Returns: Whether initial pressure source is present (default=False)

property source_p0_elastic#: Returns: Whether initial pressure source is present in the elastic code (default=False)

property source_p_labelled#: Returns: True/False if labelled/binary source mask, respectively.

property source_s_labelled#: Returns: Whether time-varying stress source with labelled source mask is present (default=False)

property source_sxx#: Returns: Whether time-varying stress source in X->X direction is present (default=False)

property source_sxy#: Returns: Whether time-varying stress source in X->Y direction is present (default=False)

property source_sxz#: Returns: Whether time-varying stress source in X->Z direction is present (default=False)

property source_syy#: Returns: Whether time-varying stress source in Y->Y direction is present (default=False)

property source_syz#: Returns: Whether time-varying stress source in Y->Z direction is present (default=False)

property source_szz#: Returns: Whether time-varying stress source in Z->Z direction is present (default=False)

property source_u_labelled#: Returns: Whether time-varying velocity source with labelled source mask is present (default=False)

property source_ux: bool#: Returns: Whether time-varying particle velocity source is used in X-direction

property source_uy: bool#: Returns: Whether time-varying particle velocity source is used in Y-direction

property source_uz: bool#: Returns: Whether time-varying particle velocity source is used in Z-direction

property time_rev#: Returns: True for time reversal simulaions using sensor.time_reversal_boundary_data

transducer_receive_elevation_focus#: Apply receive elevation focus on the transducer

transducer_sensor#: If tse sensor is an object of the kWaveTransducer class

transducer_source#: transducer is object of kWaveTransducer class

u_source_pos_index#: Indexing variable corresponding to the location of all the velocity source elements

property use_sensor#: Returns: False if no output of any kind is required

property use_w_source_correction_p#: Returns: Whether to use the w source correction instead of the k-space source correction for pressure sources

property use_w_source_correction_u#: Returns: Whether to use the w source correction instead of the k-space source correction for velocity sources