	Release Notes for Points
	Jon Leech (leech@cs.unc.edu)
	2/7/96


INTRODUCTION

    Points and distribute are programs that attempt to answer the
comp.graphics.algorithms FAQs "How do I evenly distribute N points on a
sphere?" and "How do I tesselate a sphere?".

    Both programs are written in C++. Distribute is non-interactive and has
a command-line interface; it should run on almost any system with a decent
C++ compiler. Points is interactive and fun to play with. It uses on the Tk
GUI, Tcl interpreter, and [incr Tcl] OOP libraries, which are available for
Unix, Microsoft Windows, and MacOS. While it should be straightforward to
get these programs working under Windows and MacOS, I haven't done so. The
supplied Makefile only works for Unix systems and the code has only been
tested under HP-UX.

    If you don't have Tcl, Tk, and [incr Tcl] and would like to install
them, see URLs

	http://www.sunlabs.com:80/research/tcl/
	http://www.tcltk.com/itcl/

    or read the FAQ of the Usenet newsgroup "comp.lang.tcl". Tk is a
marvelous way to do GUI work; I recommend looking into it whether or not you
want to run this GUI.


COPYRIGHT

    These programs are not public domain. However, the copyright is intended
to make them freely usable and redistributable. Please follow it.


CREDITS

    Convex hulls are computed using a slightly modified version of Dave
Watson's "nnsort.c". For more information on his algorithm, see comments in
that file or URL

	http://maths.uwa.edu.au/~watson/nnsort.c


PORTING AND BUILDING

    Both programs have been run under HP/UX 9.03 using HP C++, Tk 4.0, Tcl
7.4, [incr Tcl] 1.5, and X11R5. They should port easily to any Unix platform
running this version of Tcl and Tk libraries and with a modern C++ compiler.
You will need to edit the Makefile to change the following variables:

    CC	  - C++ compiler (defaults to 'CC')
    TKINC - compiler flags to specify location of Tcl/Tk header files
    TKLIB - loader flags to specify location of Tcl/Tk libraries
    XINC  - compiler flags to specify location of X11 header files
    XLIB  - loader flags to specify location of X11 libraries

    To build the programs, type "make points_wish" for the GUI version, or
"make distribute" for the command-line version.


DEFINING "EVENLY DISTRIBUTED"

    It doesn't have a single definition. From a mathematical point of view,
this turns out to be a moderatedly complicated subject. And this topic
happens to be a FAQ on sci.math as well as on comp.graphics.algorithms; a
much more extensive and rigorous discussion written by Dave Rusin can be
found at

	http://www.math.niu.edu/~rusin/papers/known-math/spheres/sphere.faq

    But since we're computer graphics people, not mathematicians, we'll
engage in the ancient Chinese art of Chi-Ting (as Jim Blinn is fond of
saying) and make some horrid approximations below. Onward.

    One frequently used definition is a distribution that minimizes a 1/r
potential energy function of all the points, so that in a global sense
points are as "far away" from each other as possible. Starting from an
arbitrary distribution, we can either use numerical minimization algorithms
or point repulsion, in which all the points are considered to repel each
other according to a 1/r^2 force law and dynamics are simulated. The
algorithm is run until some convergence criterion is satisfied, and the
resulting distribution is our approximation.


SOME SAMPLE FILES

    The subdirectory "samples" contains files in the format read and written
by these programs, with extremely good energy-minimizing distributions. A
file named e.g. '42' will contain the distribution for 42 points in the
format used by my point-repulsion codes.

    These distributions were generated by R. H. Hardin, N. J. A. Sloane and
W. D. Smith of AT&T Bell Labs; I simply converted them to the format my
programs use. Their original data and discussions thereof may be found at
URL

	ftp://netlib.att.com/netlib/att/math/sloane/electrons/

    My force computations apparently are slightly less accurate than theirs;
starting with their configurations, my code generates tiny perturbations.


ALGORITHM

    The problem is simulated by randomly placing each point on a unit
sphere. The points are assumed to repel each other with a 1/r^2 force law (r
measured as arc distance along the sphere).

    At each time step, forces are computed between the points, and the total
force on each point used to update its velocity vector. Depending on the
simulation parameters, the velocity may be "critically damped" (computed
solely from the forces at the current timestep, which is a really cheesy way
of doing energy minimization) or damped by a smaller constant factor. The
second type of damping makes the system less noisy, but slower to converge.

    After computing velocities, each point is then moved along the great
circle coplanar with its velocity vector by an amount proportional to the
velocity component tangent to the sphere. Each points' velocity vector is
rotated to be tangent to the sphere at its location. Steps are taken until
the stopping criteria is satisfied.

    Several heuristics are used. Velocities are clamped so that no particle
can move further than half the ideal minimium pair distance (which is itself
an approximation obtained from looking at the distances in the sample
distributions) in one timestep. This helps stabilize the simulation against
extreme parameter values. Unless otherwise specified, initial values for the
parameters are chosen to cause relatively rapid convergence. If the cutoff
distance is specified, forces are only computed between "nearby" pairs of
points within the cutoff distance. This prunes the majority of the (assumed
evenly distributed) far-field interactions, speeding the simulation up
significantly. By default the cutoff distance is Pi, so all interactions are
computed.


CONVERGENCE

    How do we know when to stop the algorithm? Many criteria are possible.
The best criteria for most purposes is probably when potential energy is
minimized to within a specified error tolerance.

    The default criteria this code uses is to stop when the kinetic energy
drops below a constant factor (1e-5) times the number of points in the
system, which corresponds to all points moving very slowly.


INTERFACE

    Both distribute and points have a similar command-line interface; points
has a GUI allowing varying parameters while the simulation is running. While
there are many options (see the man page), to produce a distribution of 53
points just say:

	distribute -nbody 53 -save savefile

    Distribute runs the simulation until the default stopping criteria is
met, then prints something like:

	360   # (converged)

    indicating that the simulation satisfied the stopping criteria after 7
iterations. The -save option causes the final points to be written to
a specified file in the following format:

	53
	0.092809 0.901930 0.421792
	-0.092635 -0.692603 0.715346
	-0.881011 0.452765 -0.137196
	0.299735 -0.422514 -0.855360
	...

    That is, the number of points, then the final coordinates of each point.
The -vrml option computes the convex hull of the points and writes
a VRML format geometry file which is a tesselation approximating a sphere.


BUGS

    You can send bugs to me by email to 'leech@cs.unc.edu'. I don't
anticipate any significant enhancements beyond what the programs do now, but
you're welcome to make such changes yourself.

    Philosophical objections or argumentative commentary about the way the
programs work, why I should have written them in C, the evil of Euler
methods, the copyright notice, or anything else of that nature will be
ignored.
