## DESCRIPTION

This module generates particles (random, uniform or in a ring structure) in a user specified subvolume or probe of a given vector lattice field. It advects all the particles until they are out of the data domain, or for a time interval. The calculation will always stop when a pre-set maximum number of iterations has been reached, or when the particle has reached a stationary position (i.e. the particle has zero velocity).

Integration is done by using the Runge-Kutta solver nag_ode_ivp_rk from the NAG C Library, and utilises the 4(5) formula pair. The size of the integration step is determined by the routine. A relative tolerance error of 0.001 is used, with threshold values determined by the velocity lattice, such that the local errors in direction i will not be greater than 0.001 * max(s, t[i]), where s is the average magnitude of the velocity over the time step, and t[i] = 0.001 * the minimum value of all components in the velocity lattice in direction i. Lattices with all data types may be connected to the module; the integration is always done in double precision.

You may specify the time interval at which the particle positions are sampled; smaller time intervals will lead to smoother particle trajectories, at the cost of increased sizes of geometry passed to the Render module. The sample frequency has no effect on the integration itself.

Vector values are interpolated either by using linear or nearest neighbour interpolation methods. For more information on the interpolation methods used you are referred to the man pages on cxLookupCreate and cxLookupInterp.

Note: the main differences between this module and the ncsa particle advection module lie in the integration method employed, and the fact that lattices of all types may be used. The calculation of the particle trajectories is done in double precision.

Acknowledgement

Portions of this module were developed at the National Center for Supercomputing Applications at the University of Illinois at Urbana-Champaign.

THE UNIVERSITY OF ILLINOIS GIVES NO WARRANTY, EXPRESSED OR IMPLIED, FOR THE SOFTWARE AND/OR DOCUMENTATION PROVIDED, INCLUDING, WITHOUT LIMITATION, WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE.

## INPUTS

**Port:** Velocity

**Type:** Lattice

**Constraints:** 3..-D

**Constraints:** 3..-vector

Lattice describing the velocity vector. The first 3 channels will be used to define the three-dimensional velocity.

## WIDGETS

**Port:** Mode

**Type:** Option Menu

**Menu Item:** Build

**Menu Item:** Run

When the module is in "Build" mode, you may set the various widgets, but no particle trajectories will be calculated for these settings. In "Run" mode particle trajectories are calculated and displayed for each widget change.

If the module was previously in "Run" mode, the particle trajectory as it was last displayed remains visible. The probe position will change to reflect changes in the probe definition.

**Port:** X Low

**Type:** Slider

Minimum value of the first coordinate of the probe volume. If this value does not allow a minimum size probe inside the velocity lattice domain, then the value will be moved accordingly (see below).

**Port:** Y Low

**Type:** Slider

Minimum value of the second coordinate of the probe volume. If this value does not allow a minimum size probe inside the velocity lattice domain, then the value will be moved accordingly (see below).

**Port:** Z Low

**Type:** Slider

Minimum value of the third coordinate of the probe volume. If this value does not allow a minimum size probe inside the velocity lattice domain, then the value will be moved accordingly (see below).

**Port:** X Size

**Type:** Slider

Size of the probe volume in the first dimension. The size will be restricted such that the probe will not extend beyond the velocity lattice domain, while the minimum size is restricted to 0.01 of the velocity lattice domain in this direction.

**Port:** Y Size

**Type:** Slider

Size of the probe volume in the second dimension. The size will be restricted such that the probe will not extend beyond the velocity lattice domain, while the minimum size is restricted to 0.01 of the velocity lattice domain in this direction.

**Port:** Z Size

**Type:** Slider

Size of the probe volume in the third dimension. The size will be restricted such that the probe will not extend beyond the velocity lattice domain, while the minimum size is restricted to 0.01 of the velocity lattice domain in this direction.

**Port:** Number

**Type:** Slider

Number of particles in the probe.

**Port:** Scale

**Type:** Dial

The size of the spheres may be scaled. If the resulting size is less than a cutoff value (0.0005 of the smallest lattice dimension) no spheres will be drawn.

**Port:** Distribution

**Type:** Option Menu

**Menu Item:** Random

**Menu Item:** Uniform

**Menu Item:** Ring YZ Plane

**Menu Item:** Ring XZ Plane

**Menu Item:** Ring XY Plane

The particles in the probe may be generated randomly, uniformly, or in a ring structure inside the probe.

**Port:** Show Probe

**Type:** Check Box

The probe volume is displayed or not depending on the value of this widget.

**Port:** Interpolation Method

**Type:** Option Menu

**Menu Item:** Nearest Neighbour

**Menu Item:** Trilinear

Trilinear or nearest neighbour interpolation can be used to determine the velocity at an arbitrary point in the lattice.

**Port:** Display Mode

**Type:** Option Menu

**Menu Item:** Completed

**Menu Item:** Time Interval

Completed Particles are advected and displayed until their trajectory leaves the domain specified by the vector lattice. Time interval Particles are advected and displayed for the duration of "Display Interval" or until their trajectory leaves the domain, if this occurs within the specified time interval.

**Port:** Display Interval

**Type:** Text

The time interval over which the particle trajectories are to be displayed, if the display mode is "Time interval". Particles may be advected forwards or backwards in time, i.e. the particle positions in the probe volume are to be seen as the initial or final positions of the particles.

Note: the sign of the time interval and the sample time must be consistent, i.e. both positive or negative.

**Port:** Sample Time

**Type:** Text

The time interval at which particle positions are sampled. These positions determine the particle trajectory that is to be displayed.

The particle trajectory is constructed using straight line segments between the sampled positions. As such a smaller sample time (greater sample frequency) will have the effect of smoothing the particle trajectory, at the same time increasing the size of the geometry passed to the Render module.

**Port:** Max Steps

**Type:** Text

The calculation of the particle trajectories will continue until a particle leaves the domain of the lattice, or after a user-specified time interval. The calculation will also stop when the particle has reached a stationary position (i.e., the particle has zero velocity), or when a maximum number of iteration steps, Max Steps, has been used.

It is possible that a particle may never leave the domain of the lattice, for example when the lattice would describe circular motion. In such cases it is important to be able to stop the calculation. NAGAdvectSimple allows this in two ways; by specifying a fixed time interval, or by imposing a maximum number of steps on the integrator.

## OUTPUTS

**Port:** Particles

**Type:** Geometry

Geometry representing either the probe and initial position of the particles (build mode, if the probe is to be shown), or the probe (if requested) and particle trajectories and spheres indicating the particle positions at the sampled times (run mode).

## KNOWN PROBLEMS

When curvilinear coordinates are used for the vector lattice, the trajectories may not always be displayed up to the lattice boundary, but may end inside the domain.

When curvilinear coordinates are used for the vector lattice, then it is possible that lattice boundaries occur inside the lattice volume. For example, this might be the case when cylindrical or toroidal volumes are modelled. In such cases it is not be possible to advect the particle through an "internal" boundary. If the probe position is near such an "internal" boundary, it may be possible to display more of the particle trajectory by moving the probe to the other side of the "internal" boundary.

As lattice coordinates are of type float rather than double, and the NAG C library requires double precision input, it may be that a problem gets classified as stiff, while in fact it is not. As the implemented ODE solver is inefficient for stiff problems, the calculation will be terminated at this point.

## SEE ALSO

The modules NAGAdvectSimple and NAGAdvectAnimate both use the same integration method to calculate the particle trajectories.

NAGAdvectSimple allows you to generate particle traces over a fixed time interval. If more than one particle is used, then the particle trace is distinguishable by its color. Up to 10 different colors are used. If more than 10 particles are followed, then the colors are used cyclically.

NAGAdvectSimple is a "simple-to-use" module. You may prefer to use it for initial experiments, where the particle behaviour is to be studied without the need to generate a complete trajectory through the lattice domain (which may be difficult and/or computationally expensive). It may also be preferred if it is important to distinguish individual particle trajectories.

NAGAdvectAnimate is a comprehensive module, which allows you to enhance the particle trajectories through the use of color, and animation effects.

[Documentation Home]