Getting Started
Installing FOCUS
More detailed instructions are available if needed.
Prerequisites
FOCUS requires the Microsoft Visual C++ 2008 SP1 Redistributable Package (x86 or x64 depending on the version of MATLAB you have) on Windows.
On Linux, FOCUS requires the newest version of GCC supported by the version of MATLAB you use. This information is available from the MathWorks website.
Installation
- Download FOCUS from our website
- Unzip the resulting .zip archive to a directory on your computer
- Add this directory and its subfolders to your MATLAB path
Using FOCUS
FOCUS is generally used in MATLAB scripts, but the functions provided as part of FOCUS can also be used directly from the MATLAB command window. FOCUS provides hundreds of functions that can be used to write ultrasound simulations, so this document only scratches the surface of what is possible in order to make it easier for new users to get started. Experienced users may prefer to jump directly to the advanced documentation for in-depth information about all of the functions included with FOCUS.
Writing FOCUS Scripts
The steps involved in writing a MATLAB script that uses FOCUS are very similar regardless of the specific application. The order of the first four steps is not critical as long as they are all completed before attempting to calculate the pressure or focus the array. Not all scripts will use all of these steps.
1. Defining the transducer or transducer array
Regardless of the nature of the simulation, the first step is to define the transducers being used. This is done using one of several included transducer definition functions documented here. FOCUS currently supports circular, rectangular, spherically-focused, planar ring, and spherically-focused ring transducers.
Using a Single Transducer
Creating single transducers in FOCUS is very simple. The following example defines a circular transducer located at the origin with a radius of 1 cm.
% 1cm circular transducer
radius = 1e-2;
center = [0 0 0]; % This vector is of the form [x y z] and describes the location of center of the element
angles = [0 0 0]; % These are Euler angles. We use this definition when rotating elements.
xdcr = get_circ(radius, center, angles);
Using a Transducer Array
Below is an example that defines a 128-element array of 3 mm by 50 mm rectangular transducers spaced 500 μm apart.
% 128-element 3x50mm rect array
nelex = 128;
neley = 1;
width = 3e-3;
height = 50e-3;
kerf = 500e-6;
center = [0 0 0]; % This is the center of the array and not of any particular element
angles = [0 0 0]; % These angles will be applied to *each* element in the array
xdcr_array = create_rect_planar_array(nelex, neley, width, height, kerf, center, angles);
A complete list of available array geometries is available in the advanced documentation.
FOCUS treats single transducers and transducer arrays exactly the same, so the following steps are the same in both cases.
2. Defining the excitation function (for transient calculations)
Depending on the calculation method used, FOCUS supports a wide range of excitation functions. The two main transient calculation methods provided by FOCUS are Time-Space Decomposition (TSD) and Frequency Domain Time-Space Decomposition (FDTSD). TSD calculations are faster and simpler to set up, but only three excitation function types are supported (tone burst, Hann-weighted pulse, and t3 pulse). FDTSD uses the Fourier Transform to decompose the input signal, so arbitrary signals can be used with this method at the expense of speed and accuracy. Time-Space Decomposition should be suitable for most transient applications.
Using TSD
The example below shows how to set a transducer (or array) to use a three-cycle Hann-weighted pulse with a center frequency of 1.5 MHz and an amplitude of 1 m/s.
% 3-cycle 1.5 MHz Hann-weighted pulse
f0 = 1.5e6;
a0 = 1;
ncycles = 3;
pulsewidth = ncycles/f0; % Calculate the pulse width in seconds
excitation_function = set_excitation_function(2, a0, f0, pulsewidth); % Hann pulse is type 2; see the full documentation for details
Using FDTSD
FDTSD calculations are more complicated to set up, but they allow you to use arbitrary input signals. This example uses the same excitation signal as the TSD example above in order to highlight the differences between the two methods.
% 3-cycle 1.5 MHz Hann-weighted pulse for use with FDTSD
f0 = 1.5e6;
fs = 10e6; % Sampling frequency
dt = 1/fs; % Time step used to calculate the excitation
a0 = 1;
ncycles = 3;
pulsewidth = ncycles/f0;
time = 0:dt:pulsewidth; % Create sample points in time
signal = zeros(length(time));
for i = 1:length(time):
% Calculate Hann-weighted pulse at this point in time
signal(i) = a0 * 0.5 * (1 - cos(2*pi * time(i)/w)) * sin(2*pi*f0*time(i));
end
% Create an excitation function object
excitation_function = set_excitation_function(signal, dt, pulsewidth);
More details about how to use different excitation functions is available in the advanced documentation.
3. Defining the coordinate grid to use in the calculation
Coordinate grids in FOCUS can be defined in several ways, but the most common by far is to define the boundaries of the grid in x, y, and z and to define the spatial steps in each direction. In the example below, a coordinate grid is defined over x ∈ [-10,10] mm and z ∈ [0,100] mm at y = 5 mm with steps of 100 μm in x and 1 mm in z.
% Coordinate grid from x = -1 cm to x = 1 cm and z = 0 to z = 10 cm at y = 0
xmin = -10e-3;
xmax = 10e-3;
ymin = 5e-3;
ymax = 5e-3; % For 2-D grids, set min and max equal to each other in the dimension you do not wish to use (in this case y). 3-D coordinate grids are possible, but displaying a 3-D pressure field in MATLAB is tricky so this is often avoided if possible.
zmin = 0;
zmax = 100e-3;
dx = 100e-6;
dy = 1; % for 2-D calculations, the delta is ignored in the unused dimension
dz = 1e-3;
coordinate_grid = set_coordinate_grid([dx dy dz], xmin, xmax, ymin, ymax, zmin, zmax);
Coordinate grids can also be defined using three vectors of x, y, and z coordinates or simply as a list of spatial coordinates. These uses are fairly uncommon and so are not covered here, but you can find examples of this in the documentation for set_coordinate_grid.
Transient Calculations
For transient calculations, the temporal equivalent of the coordinate grid must be defined using set_time_samples. This function creates an object very similar to the output of set_coordinate_grid, but in time rather than space.
This example uses set_time_samples to create samples every 100 ns from t = 0 to t = 165 μs.
% Construct time samples at intervals of 100 ns from 0 to 165 μs
tmin = 0;
tmax = 165e-6;
dt = 100e-9;
time_samples = set_time_samples(dt, tmin, tmax);
Note that the start and end times (tmin and tmax) are explicitly set here. Often, the start and end times will depend on the rest of the simulation and so they are calculated using impulse_begin_and_end_times. This method is shown below.
% Same as above but using calculated start and end times
[tmin tmax] = impulse_begin_and_end_times(transducer, coordinate_grid, medium);
dt = 100e-9;
time_samples = set_time_samples(dt, tmin, tmax);
Like set_coordinate_grid, set_time_samples can construct an object using a vector of time points rather than tmin, tmax, and dt. This usage is detailed in the advanced documentation.
4. Defining the propagation medium
FOCUS supports a very large range of medium properties, however most of these are currently unused. For a complete list of all supported properties, see the documentation for set_medium.
There are several pre-defined media included with FOCUS, so using these is the easiest way to get started. For example, to perform a simulation in a lossless medium, use this code:
medium = set_medium('lossless');
Or, to perform a simulation in water:
medium = set_medium('water');
A complete list of the built-in medium structures is available in the advanced documentation.
Most simulations require only basic information about the medium, so the following example constructs a medium by defining its density, sound speed, and attenuation.
% Define a medium with density = 1400 kg/m3, c = 1850 m/s, and alpha = 0.4 dB/cm/MHz
medium = set_medium('density',1400,'soundspeed',1850,'attenuationdBcmMHz',0.4);
The advanced documentation has more details on how to call set_medium with named arguments.
5. Focusing the transducer array
Focusing arrays is optional as the phases and time delays are all set to zero when the elements are created.
Continuous Wave Simulations
In CW simulations, focusing is accomplished by adjusting the phases of the array elements to cause constructive interference at the focus. To calculate these phase shifts, either find_single_focus_phase() or find_multiple_focus_phase() can be used, depending on the number of foci desired.
This example calculates the phase shifts for an array focused at a single point, (0, 0, 50) mm. The array is excited at 1 Mhz in a lossless medium.
% Focus an array at (0,0,50) mm
f0 = 1e6;
medium = set_medium('lossless');
focus_x = 0;
focus_y = 0;
focus_z = 50e-3;
xdcr_array = find_single_focus_phase(xdcr_array, focus_x, focus_y, focus_z, medium);
Transient Simulations
In transient simulations, the same constructive interference is accomplished by adjusting the time delays for each element. This is done using set_time_delays.
In this example, time delays are calculated for an array focused at the same point as in the previous example.
% Focus an array at (0,0,50) mm
medium = set_medium('lossless');
focus_x = 0;
focus_y = 0;
focus_z = 50e-3;
xdcr_array = set_time_delays(xdcr_array, focus_x, focus_y, focus_z, medium);
Notice that in both the transient and CW examples, the variable xdcr_array occurs on both sides of the equals sign. This is because the focusing functions calculate the phase shifts (or time delays) for each element and assign them all at once. The transducer object returned by these functions has therefore already been modified and no further action is required. The reasons for this are related to the way MATLAB handles different types of data and how these data can be changed within functions, but the two variable names should be the same whenever these functions are used to avoid unpredictable behavior.
You can learn more about all of the various focusing methods provided with FOCUS in the advanced documentation.
6. Calling a FOCUS pressure calculation function
FOCUS includes a large number of methods that can be used to calculate pressures, but the most important ones are fnm_cw for continuous wave calculations and fnm_tsd for transient calculations.
What is ndiv?
Both of these functions have an argument called "ndiv" which describes the number of abscissas to use in the integral calculation. Higher numbers are more accurate, but will increase computation time (using twice as many abscissas will make the calculation take about twice as long). The optimium number of abscissas depends on a variety of factors from the shape of the transducer to the coordinate grid, but it is possible to arrive at a solution.
To determine the correct number of abscissas to use, first perform your calculation using a very high number of abscissas, for example 200. Then, starting with one abscissa, repeat the calculation with more and more abscissas until the desired error is reached. For an example of this type of calculation, see the FNMcirc.m example included with FOCUS.
Alternatively, you can simply use a very large number of abscissas for all calculations, but this will almost certainly not be optimal and will take more time than is required to reach an acceptable error.
Continuous Wave Calculations
fnm_cw requires a transducer, a coordinate grid, a medium, the number of abscissas to use, and the excitation frequency. Below is an example of a typical call to fnm_cw.
% Typical fnm_cw call
pressure = fnm_cw(transducer, coordinate_grid, medium, ndiv, f0);
There are two other CW calculation methods that are often used: rayleigh_cw and asa_call. The most similar to fnm_cw is rayleigh_cw; rather than using the Fast Nearfield Method, rayleigh_cw uses the Rayleigh-Sommerfeld Integral to calculate the CW pressure. This method is much slower, but it is included with FOCUS because it is often used as a reference calculation. It is used in the same way as fnm_cw:
% Calling rayleigh_cw
pressure = rayleigh_cw(transducer, coordinate_grid, medium, ndiv, f0);
asa_call is used differently than either fnm_cw or rayleigh_cw. Rather than calculating the pressure directly, asa_call uses the Angular Spectrum Approach to propagate an initial field through space. For more details about how the ASA works, see the background page for the Angular Spectrum Approach.
To use asa_call, an initial CW pressure field must first be calculated in the x-y plane. This is usually done with fnm_cw in the interest of speed, but any of the CW calculation functions can be used. A vector of z-coordinates indicating where to propagate the source pressure must also be provided.
The number of FFT terms to use must also be provided. This is similar to choosing the number of abscissas in the other calculation methods in that the number of FFT terms used determines the calculation time and the error of the result. The correct number to use depends on the desired accuracy, but powers of two are better than other choices because they can be calculated much faster. Usually a number between 512 and 2048 is used.
Finally, asa_call requires the selection of a propagator type. I don't know what the advantages of each one are, so I won't write anything about it.
The example below uses a pressure calculated with fnm_cw as the initial pressure and then propagates it to get a 3D pressure field using asa_call.
% ASA usage example with initial pressure calculated by fnm_cw
f0 = 1e6;
medium = set_medium('lossless');
% Calculate the 2-D pressure in x and y
p0 = fnm_cw(transducer, coordinate_grid, medium, ndiv, f0);
z0 = 0; % Begin ASA calculation at z=0
dz = 100e-6; % Calculate pressure every 100 μm
zmax = 60e-3; % Stop at z = 60 mm
z = z0:dz:zmax; % Vector of z-coordinates to use
nfft = 1024; % Number of FFT terms to use
propagator = 'Pa'; % Type of propagator to use; this is Pressure with angular restriction
% Calculate the 3D pressure using the ASA
pressure_3d = asa_call(p0, z0, z, medium, nfft, dz, propagator, f0);
More details about fnm_cw and the other CW pressure calculations are available in the advanced documentation.
Transient Calculations
Transient calculations performed with fnm_tsd require slightly different arguments than CW calculations. A typical fnm_tsd call looks like this:
pressure = fnm_tsd(transducer, coordinate_grid, medium, time_samples, ndiv, excitation_function);
This returns a MATLAB matrix indexed such that pressure(x, y, z, t) represents the pressure in Pascals at the point (x, y, z) at the time t.
For more information about fnm_tsd and the other transient pressure calculations provided with FOCUS, see the advanced documentation.
Function Documentation
More details about the various FOCUS functions can be found in the advanced documentation.
Below is a list of all of the functions used in the above examples and the documentation for each one.
- asa_call
- create_rect_planar_array
- find_single_focus_phase
- fnm_cw
- fnm_tsd
- get_circ
- impulse_begin_and_end_times
- rayleigh_cw
- set_coordinate_grid
- set_excitation_function
- set_medium
- set_time_delays
- set_time_samples
Complete Examples
More examples are included with FOCUS. Descriptions of these examples and sample output is available here.

