handybeam.samplers

Module handybeam.samplers.rectilinear_sampler

File: rectilinear_sampler.py

Holds the class handybeam.samplers.rectilinear_sampler.RectilinearSampler

Original contributor: Salvador Catsis

class handybeam.samplers.rectilinear_sampler.RectilinearSampler(parent=None, normal_vector=array([0., 0., 1.]), parallel_vector=array([0., 1., 0.]), origin=array([0., 0., 0.2]), grid_spacing_per_wavelength=0.2, grid_spacing_per_m=None, grid_extent_around_origin_x=0.2, grid_extent_around_origin_y=0.2, local_work_size=(1, 1, 1), align_grid_size_to_gpu=64)[source]

Takes the specification for a rectilinear sampling grid, creates a grid of points, and then enables sampling the acoustic field at these points.

__init__(parent=None, normal_vector=array([0., 0., 1.]), parallel_vector=array([0., 1., 0.]), origin=array([0., 0., 0.2]), grid_spacing_per_wavelength=0.2, grid_spacing_per_m=None, grid_extent_around_origin_x=0.2, grid_extent_around_origin_y=0.2, local_work_size=(1, 1, 1), align_grid_size_to_gpu=64)[source]

Initialises an instance of the RectilinearSampler class.

Parameters:
  • parent (handybeam.world.World) – This is an instance of the handybeam world class.
  • normal_vector (numpy array) – This is the vector normal to the desired sampling grid.
  • parallel_vector (numpy array) – This is a vector parallel to the desired sampling grid.
  • origin (numpy array) – This is a vector specifying the origin of the sampling grid.
  • grid_spacing_per_wavelength (float) – This specifies the grid spacing as a fraction of the medium wavelength.
  • grid_spacing_per_m (float) – This specifies the grid spacing in meters.
  • grid_extent_around_origin_x (float) – This specifies the distance between the origin of the sampling grid and the edge along the x-axis.
  • grid_extent_around_origin_y (float) – This specifies the distance between the origin of the sampling grid and the edge along the y-axis.
  • local_work_size (tuple) – This sets the local work size for the GPU, not recommended to change unless the user has experience with OpenCL and pyopencl.
  • align_grid_size_to_gpu (int) – if set to true, the precise sampling density will be adjusted so that the count of pixels is a multiply of 256. This increases overall throughput of the GPU
__repr__()[source]

links to self.__str__()

__str__()[source]

Return str(self).

_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
extent

extent as for use in imshow(extent=this.extent)

Returns:a tuple suitable to give to imshow
find_rect_grid_area()[source]

This method finds the area of the requested sampling grid.

generate_propagation_parameters()[source]

This method finds the parameters to pass to the opencl kernel to correctly define the sampling grid.

print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
propagate(print_performance_feedback=False, local_work_size=None)[source]

Calls the rect_propagator to propagate the acoustic field to the desired sampling points.

Parameters:
  • print_performance_feedback (boolean) – Boolean value determining whether or not to output the GPU performance.
  • local_work_size (tuple or None) – Tuple e.g. (1,1,1) - set to use that work unit size. Note that correct setting require in-depth understanding of the GPU properties. Do not change away from (1,1,1) unless you know what You are doing.
set_parent(parent)

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(filename=None)

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.

class handybeam.samplers.abstract_sampler.AbstractSampler(parent=None)[source]

Defines the common attributes of each sampler class.

__init__(parent=None)[source]

Initialises an instance of the AbstractSampler class.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
__repr__()

part of RememberInstanceCreationInfo. Overrides the regular __repr__(), and adds the creation name to the existing object’s __repr__()

__str__

Return str(self).

_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
set_parent(parent)[source]

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')[source]

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)[source]

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)[source]

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(filename=None)[source]

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
class handybeam.samplers.clist_sampler.ClistSampler(parent=None, local_work_size=(128, 1, 1))[source]

This is the general sampling grid class. It takes a list of sampling points and samples the acoustic field at these points.

__init__(parent=None, local_work_size=(128, 1, 1))[source]

This method intialises an instance of the ClistSampler class.

Parameters:
  • parent (handybeam_core.world.World) – This is an instance of the handybeam world class.
  • local_work_size (tuple) – This sets the local work size for the GPU, not recommended to change unless the user has experience with OpenCL and pyopencl.
__repr__()[source]

links to __str__()

__str__()[source]
Returns:a formatted string representing some fun fucts about this instance …
_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
add_sampling_points(x_list, y_list, z_list)[source]

This method adds the requested sampling points to the sampler object.

Parameters:
  • x_list (numpy array) – This is an array containing the x-coordinates of the requested sampling points.
  • y_list (numpy array) – This is an array containing the y-coordinates of the requested sampling points.
  • z_list (numpy array) – This is an array containing the z-coordinates of the requested sampling points.
clear_data()[source]

This method clears the data assigned to the object.

find_clist_grid_volume()[source]

This method finds the volume of the requested sampling grid.

print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
propagate(print_performance_feedback=False)[source]

This method calls the clist_propagator to propagate the acoustic field to the desired sampling points.

Parameters:print_performance_feedback (boolean) – Boolean value determining whether or not to output the GPU performance.
set_parent(parent)

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(filename=None)

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
class handybeam.samplers.hexagonal_sampler.HexagonalSampler(parent=None, normal_vector=array([0, 0, 1]), parallel_vector=array([0, 1, 0]), origin=array([0., 0., 0.2]), grid_spacing_per_wavelength=0.2, grid_spacing_per_m=None, grid_extent_around_origin=0.2, local_work_size=(1, 1, 1))[source]

This is the hexagonal sampling grid class. It takes the specification for a hexagonal sampling array and then samples the acoustic field at these points.

__init__(parent=None, normal_vector=array([0, 0, 1]), parallel_vector=array([0, 1, 0]), origin=array([0., 0., 0.2]), grid_spacing_per_wavelength=0.2, grid_spacing_per_m=None, grid_extent_around_origin=0.2, local_work_size=(1, 1, 1))[source]

This method intialises an instance of the HexagonalSampler class.

Parameters:
  • parent (handybeam.world.World) – This is an instance of the handybeam world class.
  • normal_vector (numpy array) – This is the vector normal to the desired sampling grid.
  • parallel_vector (numpy array) – This is a vector parallel to the desired sampling grid.
  • origin (numpy array) – This is a vector specifying the origin of the sampling grid.
  • grid_spacing_per_wavelength (float) – This specifies the grid spacing as a fraction of the medium wavelength.
  • grid_spacing_per_m (float) – This specifies the grid spacing in meters.
  • grid_extent_around_origin (float) – This specifies the distance between the origin of the sampling grid and the edge.
  • local_work_size (tuple) – This sets the local work size for the GPU, not recommended to change unless the user has experience with OpenCL and pyopencl.
__repr__()

part of RememberInstanceCreationInfo. Overrides the regular __repr__(), and adds the creation name to the existing object’s __repr__()

__str__

Return str(self).

_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
find_hex_grid_area()[source]

This method finds the area of the requested sampling grid.

generate_propagation_parameters()[source]

This method finds the parameters to pass to the opencl kernel to correctly define the sampling grid.

print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
propagate(print_performance_feedback=False)[source]

This method calls the hex_propagator to propagate the acoustic field to the desired sampling points.

Parameters:print_performance_feedback (boolean) – Boolean value determining whether or not to output the GPU performance.
set_parent(parent)

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(filename=None)

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.

Module handybeam.samplers.lambert_sampler

File: lambert_sampler.py

Holds the class handybeam.samplers.lambert_sampler.LambertSampler

Original contributor: Salvador Catsis

class handybeam.samplers.lambert_sampler.LambertSampler(parent=None, origin=array([0, 0, 0]), required_resolution=0.012, radius=0.05, local_work_size=(1, 1, 1))[source]

This is the lambert sampling grid class. It takes the specification for a lambert sampling array and then samples the acoustic field at these points.

__init__(parent=None, origin=array([0, 0, 0]), required_resolution=0.012, radius=0.05, local_work_size=(1, 1, 1))[source]

This method intialises an instance of the LambertSampler class.

Parameters:
  • parent (handybeam.world.World) – This is an instance of the handybeam world class.
  • origin (numpy array) – This is a vector specifying the origin of the sampling grid.
  • required_resolution (float) – This specifies the resolution of the lambert sampling grid, it changes the number of sampling points.
  • radius (float) – This specifies radius of the hemispherical sampling grid.
  • local_work_size (tuple) – This sets the local work size for the GPU, not recommended to change unless the user has experience with OpenCL and pyopencl.
__repr__()

part of RememberInstanceCreationInfo. Overrides the regular __repr__(), and adds the creation name to the existing object’s __repr__()

__str__

Return str(self).

_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
propagate(print_performance_feedback=False)[source]

This method calls the lamb_propagator to propagate the acoustic field to the desired sampling points.

Parameters:print_performance_feedback (boolean) – Boolean value determining whether or not to output the GPU performance.
set_parent(parent)

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(filename=None)

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.

Back to Index

Licence (documentation): Creative Commons CC BY-NC-SA 4.0

Licence (source code): Apache 2.0

EU logo

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 737087.