NAGAdvectAnimatePyr

DESCRIPTION

This module generates particles (random, uniform or in a ring structure) in a user specified subvolume or probe of a given vector pyramid field. It advects all the particles until they are out of the data domain. 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 pyramid, 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 pyramid in direction i. Pyramids 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.

This module generates a sequence of geometry outputs on its port. The timing of placing these outputs on the module's output port depends on the mode in which the module is run.

In `normal' operation, an internal timer ensures that the module is fired as often as is required to output the complete sequence pertinent to the current widget settings. The module can also be placed in a loop, with the "Firing Done" output port on the Render module connected to its "Fire" port. In this case the module MUST be made the loop controller of the ensuing loop, and the module will fire as often as is required, and as soon as new output arrives on its "Fire" port, indicating that previous output has been dealt with by the Render module.

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.

Other portions of this module were developed by H. Chiba, IECJ, Japan.

Other portions of this module were developed by A. Van Maanen, NAG Ltd

Pyramid version written by Jason Wood, University of Leeds

INPUTS

Port: Velocity
Type: Pyramid
Optional: This port is optional.
Constraints: 3-layer
Constraints: 1..-baseLat
Constraints: 3-D compression
Constraints: unique-compression type

Pyramid describing the velocity vector. The first 3 channels will be used to define the three-dimensional velocity. Any additional channels may be used as the scalar value for colouring the generated paths and/or particles.

Port: Color Map
Type: Lattice
Optional: This port is optional.
Constraints: 1-D
Constraints: 1..4-vector
Constraints: uniform

Color map for coloring the particles.

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.

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 pyramid 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 pyramid domain, then the value will be moved accordingly (see below).

Port: Z Low
Type: Slider

Minimum value of the third coordinate of the proble volume. If this value does not allow a minimum size probe inside the velocity pyramid 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 pyramid domain, while the minimum size is restricted to 0.01 of the velocity pyramid 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 pyramid domain, while the minimum size is restricted to 0.01 of the velocity pyramid 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 pyramid domain, while the minimum size is restricted to 0.01 of the velocity pyramid domain in this direction.

Port: Number
Type: Slider

Number of particles in the probe.

Port: Radius
Type: Dial

Radius of the particles to be displayed.

Port: Complexity
Type: Dial

The complecity of the spheres used to display the particles determines the speed with which the particle trajectories are rendered. A complexity value of zero will give the fastest result.

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: 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 pyramid, 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 pyramid, for example when the pyramid would describe circular motion. In such cases it is important to be able to stop the calculation by imposing a maximum number of steps on the integrator.

Port: Streak Type
Type: Option Menu
Menu Item: Paths
Menu Item: Spheres
Menu Item: Animate Paths
Menu Item: Animate Paths, Spheres
Menu Item: Paths, Spheres
Menu Item: All

The setting of the streak type widget determines how the particle trajectories will be displayed:

Paths                   The particle trajectories are displayed in a
                        single firing.

Spheres                 The particle positions at the sampled times
                        are drawn one by one.

Animate Paths, Spheres  The particle trajectories are built up step
                        by step, and the particle positions at the
                        sampled times are then drawn one by one.

Paths, Spheres          The complete particle trajectories are drawn,
                        and the particle positions at the sampled times
                        are then indicated one by one.

All                     The complete particle trajectories are
                        drawn. Then the trajectories are retraced step
                        by step, and the particle positions at the
                        sampled times are drawn one by one.

Port: Line Width
Type: Slider

This widget determines the line width of the particle trajectories.

Port: Color Type
Type: Option Menu
Menu Item: Default
Menu Item: W_Vector
Menu Item: W_Scalar
Menu Item: W_Time
Menu Item: Vector
Menu Item: Scalar
Menu Item: Time

The spheres and particle trajectories may be colored according to a number of criteria:

Default  Spheres are drawn in white.
         Complete particle trajectories are drawn in blue. Particle
         trajectories that are drawn step by step are colored green.

W_Vector Spheres are drawn in white.
         Particle trajectories that are drawn step by step are
         colored according to the particle velocity at the beginning
         of the step.

W_Scalar Spheres are drawn in white.
         Particle trajectories that are drawn step by step are
         colored according to the scalar component of the pyramid.

W_Time   Spheres are drawn in white.
         Particle trajectories that are drawn step by step are
         colored according to the the time step.

Vector   Spheres and particle trajectories that are drawn step by
         step are colored according to the particle velocity at the
         beginning of the step.

Scalar   Spheres and particle trajectories that are drawn step by
         step are colored according to the scalar component of the pyramid.

Time     Spheres and particle trajectories that are drawn step by
         step are colored according to the time step.

Port: Color Channel
Type: Slider

Specifies which of the input channels to use as the Scalar quantity for generating colour when the "Color Type" widget is set to W_Scalar or Scalar. Requires a colourmap to be present. Channels 1 -> 3 are the x,y and z components of the vector respectively.

Port: Distance
Type: Slider

Specifies the distance (in sample intervals) between repeated sets of particles.

Port: Nrepeat
Type: Slider

Specifies the number of times that the particle trajectories and/or spheres are to be displayed.

Port: Repeat
Type: Option Menu
Menu Item: No
Menu Item: Yes

Particle trajectories and/or spheres are to be displayed repeatedly only if the "Repeat" widget specifies yes.

Port: Animate Step
Type: Slider

The number of animation steps.

OUTPUTS

Port: Particles
Type: Geometry

Geometry representing either the probe and initial position of the particles (build mode), or the probe and particle trajectories and/or spheres indicating the particle positions at the sampled times (run mode).

KNOWN PROBLEMS

The trajectories may not always be displayed up to the pyramid boundary, but may end inside the domain.

It is possible that boundaries occur inside the pyramid 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 pyramid 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

NAGAdvectSimplePyr

The modules NAGAdvectSimplePyr and NAGAdvectAnimatePyr both use the same integration method to calculate the particle trajectories.

NAGAdvectSimplePyr 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.

NAGAdvectSimplePyr 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 pyramid domain (which may be difficult and/or computationally expensive). It may also be preferred if it is important to distinguish individual particle trajectories.

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


[Documentation Home]