Alpha version of kWaveArray (off-grid sources)

k-Wave User Forum » k-Wave Support » Announcements

[sticky]

Alpha version of kWaveArray (off-grid sources)

(29 posts) (11 voices)

Started 3 years ago by Bradley Treeby
Latest reply from nhaidour

12 Next »

Bradley Treeby

Developer
Joined: Mar '10
Posts: 1,640

We have made available an alpha-version of a new transducer class for k-Wave called kWaveArray. This is based on the staircase-free source definition discussed in this paper. This requires k-Wave 1.3 to run.

The main class is called kWaveArray. This supports several different types of elements (circular, focused, rectangular) which can be any size (in physical space) and placed anywhere in the grid (not constrained to the grid points). The class takes care of applying weighted source signals to each grid point that forms part of each element in the physical array (when used as a source) and combining the source signals from each grid point to give one sensor signal per physical element of the array (when used as a sensor). See help kWaveArray to get started.

Note, currently, the kWaveArray class does not have full integration with the k-Wave simulation functions. This means that helper methods must be used to turn the kWaveArray into conventional k-Wave source inputs, and to combine the output sensor data. One downside is that the source and sensor masks can become very large. It can also take some time to generate the source inputs. We are working on both of these issues by integrating kWaveArray more directly with the simulation functions so that only one driving signal (source) or received signal (sensor) needs to be stored per element, and the scaling and averaging is down within the time loop.

Several examples of how to use kWaveArray are given in the examples folder. Note, as these are alpha codes, syntax and functionality may change, and won't necessarily be backwards compatible.

The codes are currently in alpha 0.1, and we welcome any feedback (particularly from users who are already familiar with k-Wave). Please post comments and questions specific to kWaveArray to this thread.

Brad.

--------

UPDATE: 1 November 2020 - Download link updated to alpha 0.2.

Bug fix in addRectElement and new example of a linear array.

--------

UPDATE: 8 June 2021 - Download link updated to alpha 0.3.

Added support for annular arrays.

--------

UPDATE: 8 November 2022 - kWaveArray is now part of k-Wave V1.4. Removed download link to alpha version.

--------

KNOWN ISSUES:

Setting the transducer position using setAffineTransform or setArrayPosition when using a transducer with rectangular elements does not currently rotate the angle of the individual elements. As a work around, set the element angle in addRectElement to the same angle as the array rotation (see example).

Posted 3 years ago #
fantasyhaha

Member
Joined: Sep '16
Posts: 9

Hello,
When I added more than elements in the karray by using addrectelement multiple times, karray.getdistributeedsourcesinal showed error that index exceeds matrix dimensions. How can I solve this problem. Thank you!

Posted 3 years ago #
Bradley Treeby

Developer
Joined: Mar '10
Posts: 1,640

Could you post a minimum working example? I’ll take a look.

Posted 3 years ago #
fantasyhaha

Member
Joined: Sep '16
Posts: 9

model = 1;

% medium parameters
c0 = 1500; % sound speed [m/s]
rho0 = 1000; % density [kg/m^3]

% source parameters
source_f0 = 2e6; % source frequency [Hz]
source_roc = 10e-3; % bowl radius of curvature [m]
source_diameter = 20e-3; % bowl aperture diameter [m]
source_amp = 1e6; % source pressure [Pa]

% grid parameters
axial_size = 30e-3; % total grid size in the axial dimension [m]
lateral_size = 30e-3; % total grid size in the lateral dimension [m]

% computational parameters
ppw = 3; % number of points per wavelength
t_end = 40e-6; % total compute time [s] (this must be long enough to reach steady state)
record_periods = 3; % number of periods to record
cfl = 0.5; % CFL number
source_x_offset = 10; % grid points to offset the source

% =========================================================================
% RUN SIMULATION
% =========================================================================

% --------------------
% GRID
% --------------------

% calculate the grid spacing based on the PPW and F0
dx = c0 / (ppw * source_f0); % [m]

% compute the size of the grid
Nx = roundEven(axial_size / dx) + source_x_offset;
Ny = roundEven(lateral_size / dx);
Nz = Ny;

% create the computational grid
kgrid = kWaveGrid(Nx, dx, Ny, dx, Nz, dx);

% compute points per temporal period
PPP = round(ppw / cfl);

% compute corresponding time spacing
dt = 1 / (PPP * source_f0);

% create the time array using an integer number of points per period
Nt = round(t_end / dt);
kgrid.setTime(Nt, dt);

% calculate the actual CFL and PPW
disp(['PPW = ' num2str(c0 / (dx * source_f0))]);
disp(['CFL = ' num2str(c0 * dt / dx)]);

% --------------------
% SOURCE
% --------------------

% create time varying source
source_sig = createCWSignals(kgrid.t_array, source_f0, source_amp, 0);

% set bowl position and orientation
bowl_pos = [kgrid.x_vec(1) + source_x_offset * kgrid.dx, 0, 0];
focus_pos = [kgrid.x_vec(end), 0, 0];

% create empty kWaveArray
karray = kWaveArray('BLITolerance', 0.01, 'UpsamplingRate', 10);

% add bowl shaped element
karray.addBowlElement(bowl_pos, source_roc, source_diameter, focus_pos);

karray.addBowlElement([kgrid.x_vec(1) + source_x_offset * kgrid.dx, -0.0287, 0], source_roc, source_diameter, focus_pos);
% assign binary mask
source.p_mask = karray.getArrayBinaryMask(kgrid);

% assign source signals
source.p = karray.getDistributedSourceSignal(kgrid, source_sig);

The erro showed:Index exceeds matrix dimensions.

Besides, when using karray.plotArray it seems do not support bowl, rect etc.

Posted 3 years ago #
Bradley Treeby

Developer
Joined: Mar '10
Posts: 1,640
source_sig must have the same number of rows as elements in the array. Try:
```
% create time varying source
source_sig = createCWSignals(kgrid.t_array, source_f0, [source_amp, source_amp], 0);
```
Extending the plotting is on the list, but not implemented yet.

Brad.
Posted 3 years ago #
s148275

Member
Joined: Mar '20
Posts: 15

Hi Brad,

From your paper follows that an apodised ultrasound transducer can be made with the kWaveArray class. I understand that I will have to multiply the grid weights with some window (Hanning for example). Could you please explain to me how to do this or could you implement this in the KWaveArray class?

Thanks in advance!

Frank

Posted 3 years ago #
Bradley Treeby

Developer
Joined: Mar '10
Posts: 1,640

Are you using a multi-element array? If so, you can just weight the input signals for each array element accordingly.

Posted 3 years ago #
s148275

Member
Joined: Mar '20
Posts: 15

Yes that is a possibility, thanks!

Posted 3 years ago #

s148275

Member
Joined: Mar '20
Posts: 15

Hi Brad,

In case you want rectangular arrays in 3D, theta (the orientation) has to be given per element. The following line of code is used for the integration points:

integration_points = makeCartRect(...
                        obj.affine(obj.elements{element_num}.position), ...
                        obj.elements{obj.number_elements}.length, ...
                        obj.elements{obj.number_elements}.width, ...
                        obj.elements{obj.number_elements}.orientation, ...
                        m_integration);

However I think this is incorrect, because now you only take the last orientation? Shouldn't it be:

integration_points = makeCartRect(...
                        obj.affine(obj.elements{element_num}.position), ...
                        obj.elements{obj.number_elements}.length, ...
                        obj.elements{obj.number_elements}.width, ...
                        obj.elements{element_num}.orientation, ...
                        m_integration);

I don't know if I need to use affine() as well?

Best,
Frank

Posted 3 years ago #

Bradley Treeby

Developer
Joined: Mar '10
Posts: 1,640

Hi Frank,

This is a bug - thanks for reporting. In all cases it should be element_num. New download link with bug fix in the original post above.

Applying the affine transform won't work here (these are angles, rather than a position as in the other elements). I've left it as an issue for now. What needs to happen is the angles extracted from the affine transform, and these angles added to the individual element angles.

Brad.

Posted 3 years ago #
kdreher

Member
Joined: Jul '19
Posts: 4

Hi everyone,
I really like the new kWaveArray class, so thank you very much for that!

However, I wondered how to use it in combination with the time reversal reconstruction? It doesn't seem to work the same way as before since the number of time series doesn't match the number of source elements in the sensor mask anymore.

Is there some method that does the inverse of the combineSensorData method?

Cheers,
Kris

Posted 2 years ago #
zengqw2021

Member
Joined: Jun '21
Posts: 26

Dear all,
I copy the alpha codes to my installation path of k-Wave:"\k-Wave\ " and "k-Wave\private". I tried to run a example, but it doesn't work. Does anyone know how this bag works?
Cheers
Zeng

Posted 2 years ago #
Bradley Treeby

Developer
Joined: Mar '10
Posts: 1,640

@Kris: Unfortunately, there is currently no good way to use kWaveArray with time reversal. This is because time reversal uses the source.p_mode = 'dirichlet' option, and that doesn't make much sense when the source mask is non-local. I'll give it some thought.

@Zeng: It's just a matter of adding the downloaded folder to the MATLAB path. What error message do you get?

Posted 2 years ago #
Eric Miller

Member
Joined: Nov '20
Posts: 3

Hi Brad, k-wave team,

Thanks so much for the annular array support! It helps my work quite a bit, really awesome work.

Could the 0.3 kArray Alpha package be missing the function "focusedAnnulusOneil.m"? I have "focusedBowlOneil.m" as a part of k-wave 1.3, but I don't see the annulus code in either the k-wave 1.3 or kArray 0.3 downloads and "ex08_focused_annular_array_3D.m" calls that function. I may very well be missing it.

Thanks again,
Eric

Posted 2 years ago #
Bradley Treeby

Developer
Joined: Mar '10
Posts: 1,640

Hi Eric,

I've just up-dated the linked file with the missing function. Note, focusedAnnulusONeil requires an updated version of focusedBowlONeil that also returns the complex pressure, so I've added that also.

Let me know any problems!

Brad.

Posted 2 years ago #
Eric Miller

Member
Joined: Nov '20
Posts: 3

Hi Brad,

Works like a charm!

Another question: I have an annular array with a rectangular central aperture. Trying to work though the kWaveArray class to see what I'll need to tweak. I have my ring inner and outer diameters, I only need to remove the parts of the rings that overlap with the rectangular aperture. Any guidance on doing this such that the grid weights come out correct?

-Eric

Posted 2 years ago #
LewisR

Member
Joined: Dec '19
Posts: 7

Hi Brad,

Can kWaveArray support rectangular curved elements? Specifically curvature to both the height and width of the element. Or would this need to be done using the custom element option? I'm a little confused with how to use the addCustomElement method, would it be possible for you to do an example? If in fact it can be used to solve my problem.

Thanks in advance,

Lewis

Posted 1 year ago #
quetaijiangchu

Member
Joined: Feb '22
Posts: 4

Is there an example of how to create 3D irregularities using function addCustomElement?

Posted 1 year ago #
bencox

Developer
Joined: Mar '10
Posts: 285

Hi quetaijiangchu and LewisR,

There is not such an example yet, no, although the idea behind kWaveArray does have the capability of modelling just such sources. Essentially, given a desired surface, it is necessary to convolve it with the bandlimited interpolant, which has the form sinc(x * pi / dx), and then sample the resulting function at the grid points to give the weights used in kWaveArray. The details are given in this paper. We will add more functionality in due course when we integrate it into k-Wave properly.

Best wishes
Ben

Posted 1 year ago #
Bradley Treeby

Developer
Joined: Mar '10
Posts: 1,640

Noting that kWaveArray is now part of k-Wave v1.4.

Posted 1 year ago #

RSS feed for this topic

12 Next »

Reply »

You must log in to post.

k-Wave

A MATLAB toolbox for the time-domain simulation of acoustic wave fields

Alpha version of kWaveArray (off-grid sources)

Reply »

A MATLAB toolbox for the time-domain
simulation of acoustic wave fields