All integrable Hamiltonian systems are alike, while each nonintegrable one is nonintegrable in its own way
file] [-h ] [-i
[-v ] [-w
The vfplot utility creates PostScript plots of two-dimensional vector fields using curved arrows or other glyphs.
Fields can be built-in (see
-t) or specified by data (see
-F and the section on input formats below).
All options have a long version and most have a short version; those without are intended mainly for development purposes.
See the note below for details on unit, pen and fill specification.
Adaptive mode. Create an output file for each step of the dimension two iteration, the files named anim.
mare the main and inner iteration numbers.
Specify the glyph aspect: the ratio of its length to width. For the
arrowglyph try a value around 8.0, for the
triangleglyphs try around 4.0.
Adaptive mode. Break off processing early. Use the a value of
listto see possible break types.
Adaptive mode. Cache the metric tensor on an
ngrid. On a rectangle
nis the smaller of dimensions of the grid.
Specify the contact value of intersection, as used in the decimation: after decimation there will be no ellipses a contact distance of less than
valuebetween them. A
valueof 1.0 correspond to the usual intersection, 0.8 will allow ellipses to intersect slightly, 1.2 will give no intersection and a small margin.
Read the function's domain from the specified
file. The domain file is useful when the vector field is not defined on the whole of a rectangle. See dom(5) for details on the file format.
Draw the function's domain using the specified pen.
Write the domain to the specified
Write the vector field to the specified
file, useful in exporting to other formats. The format is described in sag(5).
In parts of the field where the curvature is small the difference between a curved and a straight arrow of the same length is small. If it is less than epsilon then a straight arrow will be drawn.
The author cannot tell the difference between values less than 0.5 points,
-e 0.5p, which is the default. A value of 0.1 points corresponds to 1 pixel on a 600 dpi printer and there is no sense in a value less than 0.01 points due to floating point truncation in the PostScript output. Choosing a large value results in all glyphs being straight.
Draw the bounding ellipses.
Use the specified pen for the bounding ellipses.
Use the specified fill for the bounding ellipses.
Specify the glyph fill.
Give the format of the data-files to be used as input. See the INPUT FORMATS section below.
Select the glyph to draw:
An arrow with a curved shaft of uniform width and a (uncurved) triangular head;
A circularly curved triangle with the sharp end in the direction of the field;
A circularly curved triangle with the blunt end in the direction of the field: the
Use specified file for the graphic state. If the file does not exist then the graphic state will be written to it. If the file does exist then it is read and the state used for the plot (rather than calculating it anew).
The point is to cache the results of expensive processing so that one can adjust the final image appearance: the line thicknesses, fill colours, glyph type, and so on.
The file format is described in vgs(5).
Specify the arrowhead geometry where the
widthvalues are relative to the shaft width. A reasonable value might be
2.2/1.7. Note that the values are ratios and so dimensionless, units will be ignored.
Adaptive mode. Write data for a histogram of Perram-Wertheim distances of near neighbours to the specified
Adaptive mode. Specify the number of iterations in the Lennard-Jones simulation.
Use the specified number of threads in CPU-intensive operations like the force accumulation. For multi-CPU hardware this option can increase execution speed substantially.
The default behaviour is to use as many threads as there are CPUs found on the system, if it is possible to determine this number. Otherwise one thread is used.
This option is only available if pthread (POSIX thread) support was found during compilation (and if the
--disable-pthreadoption was not specified in configuration).
Adaptive mode. Delay termination of the dynamic until the kinetic energy has dropped from the value at the end of detruncation (about 4/5ths of the way through) by the specified decibels. Try a value of around 5.
Specify bounds on the glyph lengths with an optional unit. Glyphs outside this range will not be drawn.
Adaptive mode. Decimate the boundary ellipses after edges have been added, not before. This may result in better boundaries for complex domains.
Use of this option can lead to holes in the boundary near corners: the
--decimate-contactoption can be employed to reduce these effects.
Adaptive mode. Give the margin to pad the glyphs. The
minorare the margins of a zero-sized glyph (with optional units) and
rateis the rate at which the margins increase with respect to the glyph's size. In other words, the margin used along the major axis is
ratedetermines how sparse or dense the glyphs are at different sizes. With
rate> 1, large glyphs are sparse, small glyphs dense, for
rate< 1, large glyphs are dense, small glyphs sparse. A negative value of
rateis accepted, the margins decrease from
minoruntil they are zero and then remains zero. The visual result is that small glyphs are sparse, large glyphs congested.
Small values of
minorwill lead to a large numbers of small glyphs (and a long execution time).
-m 3m/3m/0.5as a starting point for experimentation.
Hedgehog mode. The number of glyphs to be used in the plot (roughly).
Adaptive mode. Specify the pen used to draw the neighbours network in adaptive mode. For debugging.
Plot output to
filerather than standard output.
Output is in the specified
the encapsulated PostScript format (the default);
a scene description in the POV-Ray rendering format.
Adaptive mode, the initial number of glyphs is
factortimes the estimated optimal packing number. Useful when there is a singularity in the field which can cause the optimal packing number to be underestimated. Try a value of 2.5 or 3, increasing it until the plots become filled.
Specify the glyph placement strategy:
The glyphs are placed on a regular rectangular grid;
The glyphs are placed with a molecular dynamics (Lennard-Jones) simulation of their bounding ellipses.
Specify the pen used to draw the glyph outlines.
Scale glyph size by the specified factor.
Sort the glyphs before plotting (to have the largest on top, etc). Use the value
listto see the sort-types available.
Plot a test-field rather than data. Use the value
listto see the fields available.
Adaptive mode. Set the timestep for the Lennard-Jones simulation. Mainly for debugging and development.
The width of the output image with an optional unit.
The height of the output image with an optional unit. The odd choice of character for this option is due to scarcity, and the fact that one does not often need to specify the height.
Note that width and height cannot be specified together, the aspect-ratio of the field is preserved by this program for deep mathematical reasons. Actually laziness.
Several input formats can be used to pass vector fields to vfplot. Usually the file format will be autodetected, but if
this fails one can use the
-F option to specify the format.
A simple ASCII grid format described in sag(5), intended to be easy to write.
Matlab binary format, as produced by the Matlab save command (with Octave add the -mat-binary option). The file should contain matrices
v(which must be of the same size) interpreted as the components of the field. The file may optionally contain 2x1 matrices
yrangewhich will be interpreted as the minimum and maximum x and y values (if not present the matrix indices will be taken as the x and y values).
A pair of GMT(1) grd (netCDF) files representing the components of the vector field. This is the recommended data format since it is compact, portable and the GMT package provides excellent support for smoothing and clipping the data grids (as is often needed by vfplot).
A simulation file from the Gerris flow solver.
Options of length take units specified by appending a unit:
for PostScript points,
P for printer's points,
i for inches,
m for millimetres,
c for centimetres.
A fill is either a single integer in the range 0-255
for greyscale, or a
blue triple for
In verbose operation (with the
-v option), the program prints
information of the progress of the Lennard-Jones annealing with columns of numbers. These
The number of the outer iteration (see
The number of glyphs remaining in the simulation. This value is reduced as glyphs escape from the domain during the course of the simulation, or as a result of decimation (see the
During the decimation phase of the simulation those glyphs which are overclose to their neighbours are removed from the simulation. This column shows the number of glyphs which have been removed in this way. This will result in a decrease in the
A reduction in the
glyphvalue in excess of the value in the
oclvalue indicates that a glyph has escaped from the simulation domain. This is quite normal (and even desirable) but excessive amounts of escapees can indicate that the boundary of the domain is badly filled with glyphs, leaving a hole through which others can escape.
The calculation of inter-glyph forces only needs to be performed for near neighbours, and towards this end a graph of near neighbours is created for each outer iteration. The value in this column shows the number of edges in this graph.
The number of edges divided by the number of glyphs.
The logarithm (base 10) of the kinetic energy of the simulation.
The ratio of the combined area of the ellipses bounding the glyphs to the total area of the domain. Typically at the start of the simulation the value will be larger than one (since the domain is overfilled with ellipses), it will decrease to around one during the decimation phase, then decrease slowly to pi divided by the square root of 12 (around 0.9) at the end of the simulation.
Note that with a complex boundary the final value may be larger than 0.9, but in general a value which is smaller indicates an underfilled plot.
For a hedgehog plot of a 3 point electrostatic test field
vfplot -v -f255 -D2 -s0.3 -n300 -t electro3 -p hedgehog -o electro3.eps
To produce an adaptive test-plot of inviscid flow around a cylinder, try
vfplot -v -f150 -D2 -s0.5 -t cylinder -p adaptive -o cylinder.ps
J.J. Green (