The PARTICLE_TRACE procedure traces the path of a massless particle through a vector field, given a set of starting points (or seed points).
Particles are tracked by treating the vector field as a velocity field and integrating. Each particle is tracked from the seed point until the path leaves the input volume or a maximum number of iterations is reached. The vertices generated along the paths are returned packed into a single array along with a polyline connectivity array. The polyline connectivity array organizes the vertices into separate paths (one per seed). Each path has an orientation. The initial orientation may be set using the SEED_NORMAL keyword. As a path is tracked, the change in the normal is also computed and may be returned to the user as the optional Normals argument.
Path output can be passed directly to an IDLgrPolyline object or passed to the STREAMLINE procedure for generation of ribbons. Control over aspects of the integration (e.g. method or stepsize) is also provided.
Example
The following procedure calculates the path of three particles through a vector field representing wind and plots it against a background displaying the vector field itself.
PRO ex_particle_trace
; Restore u, v, x, and y variables containing wind data
RESTORE, FILEPATH('globalwinds.dat', $
SUBDIR=['examples','data'])
; Build a data array from the wind data.
data = FLTARR(2, 128, 64)
data[0, *, *] = u
data[1, *, *] = v
; Define starting points for the streamlines
seeds = [[32, 32], [64, 32], [96, 32]]
; Calculate the vertext and connectivity data for the
; streamline paths
PARTICLE_TRACE, data, seeds, verts, conn, MAX_ITERATIONS=30
; Plot the underlying vector field
VELOVECT, u, v, x, y, COLOR='AAAAAA'x
; Overplot the streamlines
i = 0
sz = SIZE(verts, /STRUCTURE)
WHILE (i LT sz.dimensions[1]) DO BEGIN
nverts = conn[i]
PLOTS, x[verts[0, conn[i+1:i+nverts]]], $
y[verts[1, conn[i+1:i+nverts]]], $
COLOR='0000FF'x, THICK=2
i += nverts + 1
ENDWHILE
END
Syntax
PARTICLE_TRACE, Data, Seeds, Verts, Conn [, Normals] [, MAX_ITERATIONS=value] [, ANISOTROPY=array] [, INTEGRATION={0 | 1}] [, SEED_NORMAL=vector] [, TOLERANCE=value] [, MAX_STEPSIZE=value] [, /UNIFORM]
Arguments
Data
A three- or four-dimensional array that defines the vector field. Data can be of dimensions [2, dx, dy] for a two-dimensional vector field or [3, dx, dy, dz] for a three-dimensional vector field, where:
- Data[0,*,*] or Data[0,*,*,*] contains the X components of the two- or three-dimensional vector field (commonly referred to as U).
- Data[1,*,*] or Data[1,*,*,*] contains the Y components of the two- or three-dimensional vector field (commonly referred to as V).
- Data[2,*,*,*] contains the Z components of the three-dimensional vector field (commonly referred to as W).
Seeds
An array of two- or three-element vectors ([2, n] or [3, n]) specifying the indices of the n points in the Data array at which the tracing operation is to begin. The result will be n output paths.
Verts
A named variable that will contain the output path vertices as a [2, n] or [3, n] array of floating-point values.
Conn
A named variable that will contain the output path connectivity array in IDLgrPolyline POLYLINES keyword format. There is one set of line segments in this array for each input seed point.
Normals
A named variable that will contain the output normal estimate at each output vertex ([3, n] array of floats).
Keywords
ANISOTROPY
Set this input keyword to a two- or three- element array describing the distance between grid points in each dimension. The default value is [1.0, 1.0, 1.0] for three-dimensional data and [1.0, 1.0] for two-dimensional data.
INTEGRATION
Set this keyword to one of the following values to select the integration method:
- 0 = 2nd order Runge-Kutta (the default)
- 1 = 4th order Runge-Kutta
SEED_NORMAL
Set this keyword to a three-element vector which selects the initial normal for the paths. The default value is [0.0, 0.0, 1.0]. This keyword is ignored for 2-D data.
TOLERANCE
This keyword is used with adaptive step-size control in the 4th order Runge-Kutta integration scheme. It is ignored if the UNIFORM keyword is set or the 2nd order Runge-Kutta scheme is selected.
MAX_ITERATIONS
This keyword specifies the maximum number of line segments to return for each path. The default value is 200.
MAX_STEPSIZE
This keyword specifies the maximum path step size. The default value is 1.0.
UNIFORM
If this keyword is set, the step size will be set to a fixed value, set via the MAX_STEPSIZE keyword. If this keyword is not specified, and TOLERANCE is either unspecified or inapplicable, then the step size is computed based on the velocity at the current point on the path according to the formula:
stepsize = MIN(MaxStepSize, MaxStepSize/MAX(ABS(U), ABS(V), ABS(W)))
where (U,V,W) is the local velocity vector.
Version History
| 5.5 |
Introduced |
Comments
This page has no comments yet. Be the first one!