All integrable Hamiltonian systems are alike, while each nonintegrable one is nonintegrable in its own way
Synopsis
vfplot
[-a aspect
]
[-c crop
] [-d path
] [-D pen
] [-e
epsilon
] [-E ellipse
] [-f fill
]
[-F format
] [-G path
] [-h ] [-i iter
] [-j threads
]
[-H head
] [-k dB
] [-l length
] [-L
path
] [-m margin
] [-n num
]
[-o path
] [-O format
] [-p placement
] [-P pen
]
[-s scale
] [-S symbol
] [-t field
]
[-v ] [-w width
] [-W height
] path
path
...
DESCRIPTION
The vfplot utility creates PostScript plots of two-dimensional vector fields using curved arrows or other symbols.
Fields can be built-in (see --test
) or specified by data (see --format
and the section on input formats
below).
OPTIONS
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.
General
-
-h
--help
-
Brief help.
-
-j
--threads
num
-
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-pthread
option was not specified in configuration). -
-L
--log-path
path
-
Write run-time information to the specified
path
. If the file does not exist then it will be created. If the file does exist then it will be appended.See also the
--log-level
option. -
--log-level
level
-
Log at the specified
level
, one oftrace
,debug
,info
,warn
,error
orfatal
; with their usual meanings. If the--log-path
option has not been specified then this option has no effect. -
-v
--verbose
-
Verbose operation.
-
-V
--version
-
Version information.
Plot tyoe, input, output
-
-F
--format
type
-
Give the format of the data-files to be used as input. See the INPUT FORMATS section below.
-
--grid-range
floats
-
When input data lacks x-y information (as with CSV input), specify the x-y extent of the input grid as x miumum/maximum then y minimum/maximum, joined with slashes.
Example:
--grid-range 0/5/0/1
. -
--grid-size
ints
-
When the input grid uses explicit indices (as with CSV input) specify the size of the grid with a pair of integers: the number in each dimension joined with slashes.
Example:
--grid-size 32/128
. In this case (31, 127) will be the maximal index in the grid.Note that for some (most) input formats the grid size cannot be modified; for those formats this option will cause the program to error.
-
-o
--output
path
-
Plot output to
path
rather than standard output. -
-O
--output-format
format
-
Output is in the specified
format
:eps
-
the encapsulated PostScript format (the default);
povray
-
a scene description in the POV-Ray rendering format.
-
-p
--placement
strategy
-
Specify the symbol placement strategy:
hedgehog
-
The symbols are placed on a regular rectangular grid;
adaptive
-
The symbols are placed with a molecular dynamics (Lennard-Jones) simulation of their bounding ellipses.
-
-t
--test
field
-
Plot a test-field rather than data. Use the value
list
to see the fields available.
Plot features
-
-c
--crop
lengths
-
Crop the final image by the specified
lengths
.In many cases (in particular, in fluid dynamics), one has an infinite or near infinite field in mind when plotting, so the edge effects (whereby the arrows will be aligned with the boundary) are undesirable. Then the
--crop
option is useful to generate a plot without those effects, giving the impression of boundlessness.The
lengths
give the amount to crop from each edge: the values are with respect to the plot output and have optional units. If four values are given (as inW/E/S/N
) then these are used for each of the left, right, bottom and upper parts of the plot, if two then these are applied to the vertical sides (East and West) and the horizontal sides (South and North) respectively. If a single value, that is applied to all sides.Note that cropping will reduce the size of the plot, so one should increase the
--height
or--width
values by the amount cropped to recover a plot of the desired size.Note also that cropping is not implemented for POV-Ray output, the three-dimensionality makes the effect look unnatural and increases rendering time enormously; better to use the rendering window for this purpose.
-
-d
--domain
path
-
Read the function's domain (boundary) from the specified
path
. The domain file is useful when the vector field is not defined on the whole of a rectangle. See vfplot-geojson (5) for details on the file format.If this option is not given then built-in plots will use their default domain; for data plots a domain will be built and can be output with the
--dump-domain
option. -
-D
--domain-pen
pen
-
Draw the function's domain using the specified pen.
-
-w
--width
val
-
The width of the output image with an optional unit.
-
-W
--height
val
-
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.
Symbols
The type and appearance of the plotted symbols.
-
-a
--aspect
value
-
Specify the symbol aspect: the ratio of its length to width. For the
arrow
symbol try a value around 8.0, for thetriangle
symbol try around 4.0. -
-f
--fill
fill
-
Specify the symbol fill.
-
-H
--head
length
/width
-
Specify the arrowhead geometry where the
length
andwidth
values are relative to the shaft width. A reasonable value might be2.2/1.7
. Note that the values are ratios and so dimensionless, units will be ignored. -
-l
--length
min
/max
-
Specify bounds on the symbol lengths with an optional unit. Symbols outside this range will not be drawn.
-
-n
--number
num
-
The number of symbols to be used in the plot (roughly).
The interaction with the
--scale
option (which controls the arrow size) depends on the plotting mode: -
-P
--pen
pen
-
Specify the pen used to draw the symbol outlines.
-
-s
--scale
factor
-
Scale symbol size by the specified factor.
-
-S
--symbol
type
-
Select the symbol to draw:
arrow
-
An arrow with a curved shaft of uniform width and a (uncurved) triangular head;
triangle
-
A circularly curved triangle with the sharp end in the direction of the field;
-
--sort
type
-
Sort the symbols before plotting (to have the largest on top, etc). Use the value
list
to see the sort-types available.
Adaptive mode
Arrow placement by a packing of the bounding ellipses.
-
-E
--ellipse
-
Draw the bounding ellipses.
-
--ellipse-pen
pen
-
Use the specified pen for the bounding ellipses.
-
--ellipse-fill
fill
-
Use the specified fill for the bounding ellipses.
-
-i
--iterations
outer
/inner
-
Specify the number of iterations in the Lennard-Jones simulation.
-
--overfill
factor
-
The initial number of symbols is
factor
times 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. -
-k
--ke-drop
dB
-
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.
-
-m
--margin
major
/minor
/rate
-
Give the margin to pad the symbols. The
major
andminor
are the margins of a zero-sized symbol (with optional units) andrate
is the rate at which the margins increase with respect to the symbol's size. In other words, the margin used along the major axis ismajor
+rate
xlength
.The
rate
determines how sparse or dense the symbols are at different sizes. Withrate
> 1, large symbols are sparse, small symbols dense, forrate
< 1, large symbols are dense, small symbols sparse. A negative value ofrate
is accepted, the margins decrease frommajor
andminor
until they are zero and then remains zero. The visual result is that small symbols are sparse, large symbols congested.Small values of
major
andminor
will lead to a large numbers of small symbols (and a long execution time).Try
-m 3m/3m/0.5
as a starting point for experimentation. -
--network-pen
pen
-
Specify the pen used to draw the neighbours network in adaptive mode. For debugging.
-
--timestep
dt
-
Set the timestep for the Lennard-Jones simulation. Mainly for debugging and development.
Advanced
Mainly for development.
-
--animate
-
Adaptive mode. Create an output file for each step of the dimension two iteration, the files named anim.
n
.m
.eps wheren
andm
are the main and inner iteration numbers.Converting these plots to an animation is outside the scope of this program, typically one would convert each plot to the PNG format with convert (1) and then convert those files to an animation with ffmpeg (1) . See
src/misc/animation
in the source of the package for an example of this approach. -
--animate-dir
directory
-
As for the
--animate
option, but use the passeddirectory
as the location into which to write the animation files. The specifieddirectory
should already exist. -
--break
break
-
Adaptive mode. Break off processing early. Use the a value of
list
to see possible break types. -
--cache
n
-
Adaptive mode. Cache the metric tensor on an
n
xn
grid. On a rectanglen
is the smaller of dimensions of the grid. -
--dump-domain
path
-
Write the domain to the specified
path
. -
--dump-vectors
path
-
Write the vector field to the specified
path
, useful in exporting to other formats. The format is described in vfplot-csv (5) .Note that the output is pixel-aligned, in other words the samples are at the centres of pixels.
-
-e
--epsilon
eps
-
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 symbols being straight. -
-G
--graphic-state
path
-
Use specified
path
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, symbol type, and so on.
The file format is JSON and contains an object with an array of arrows objects and an array of neighbours. These should be self-explanatory.
-
--histogram
path
-
Adaptive mode. Write data for a histogram of Perram-Wertheim distances of near neighbours to the specified
path
. -
--statistics
path
-
Write statistics on the processing to the specified
path
; the format is JSON and should be self-explanatory.
INPUT FORMATS
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.
csv
-
A simple CSV grid format described in vfplot-csv (5) , intended to be easy to write.
mat
-
Matlab binary format, as produced by the Matlab save command (with Octave add the -mat-binary option). The file should contain matrices
u
andv
(which must be of the same size) interpreted as the components of the field. The file may optionally contain 2x1 matricesxrange
andyrange
which 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). grd2
-
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).
gfs
-
A simulation file from the Gerris flow solver.
UNITS
Options of length take units specified by appending a unit: p
for PostScript points, P
for printer's points, i
for inches, m
for millimetres, c
for centimetres.
One can add extra characters to the unit if that makes it easier to read (in
, mm
and so on), those will be ignored.
PENS
A pen
is given in the form width
/colour
where
the width
is a floating point value (with optional
unit) and the optional colour
is as described in the fill section below, default black.
For example, 1
is a black pen with width one PostScript point;
1pt/0
is exactly the same; 0.2mm/red
is a
0.2 mm red pen.
FILLS
A fill is:
-
A single integer in the range 0–255, for greyscale
-
A
red
/green
/blue
triple of 0–255 values, for colour, or -
A named colour: "red", "beige" and so-on, as used commonly on the web, the full list of names can be found in Section 4.4 of the SVG-11 specification.
RUNTIME INFORMATION
In verbose operation (with the --verbose
option), the program prints information of the progress of the
Lennard-Jones annealing with columns of numbers. These indicate:
n
-
The number of the outer iteration (see
-i
option). symbol
-
The number of symbols remaining in the simulation. This value is reduced as symbols escape from the domain during the course of the simulation, or as a result of decimation (see the
ocl
data below). ocl
-
During the decimation phase of the simulation those symbols which are overclose to their neighbours are removed from the simulation. This column shows the number of symbols which have been removed in this way. This will result in a decrease in the
symbol
value. edge
-
The calculation of inter-symbol 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.
e/g
-
The number of edges divided by the number of symbols.
ke
-
The logarithm (base 10) of the kinetic energy of the simulation.
prop
-
The ratio of the combined area of the ellipses bounding the symbols 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.