This README file is to accompany distribution of routines and demo programs for dynamic display of 3D particle distributions
Questions and/or comments may be sent to akravtso@nmsu.edu
COPYRIGHT
Copyright (c) 1998 Andrey V. Kravtsov. This program can be distributed and used freely for personal, educational or research purposes under terms of GNU General Public License (see file gnu-public-license.txt in this distribution). Use for any other purposes requires special arrangements.
COMPILER
The code was written in the standard fortran 77. Any compiler which understands the standard will do.
COMPILATION
The demo programs can be compiled easily, given that required libraries are installed on the system. The compilation command should include '-lpgplot -lX11' to include routines from the pgplot and X11 libraries. For demo3 it should also include '-lbutton'. Examples, of compilation commands can be found in files demo*.comp
REQUIRED LIBRARIES
To use the routines, you should have PGPLOT (version 5.2 or higher) library installed on your system. If you don't have it installed, the library can be obtained free of charge at the following sites: www : http://astro.caltech.edu/~tjp/pgplot/ anonymous ftp : astro.caltech.edu in /pub/pgplot/, i.e
ftp astro.caltech.edu
login: anonymous
passwd: your e-mail address
cd /pub/pgplot/
binary
get pgplot5.2.tar.gz
If you cannot use WWW or ftp, PGPLOT is available on tape for a fee. Consult tjp@astro.caltech.edu.
Follow the installation instructions in the distribution to install the library on your system. The final library files are relatively small and can, in principle, be installed in the user's home directory for a private use.
To compile demo3.f you will also need BUTTON library installed. This library was witten by N.Cardiel and J.Gorgas (Dept. de Astrofisica, U. Complutense de Madrid) and can be downloaded freely from http://www.ucm.es/info/Astrof/button/button.html The library allows to draw 3D buttons for interactive plot manipulation with a mouse and also uses PGPLOT library
PGPLOT ENVIRONMENT VARIABLES
A few PGPLOT environment variables need to be set for proper functioning of the demo programs. Include the following in your shell startup file or any other batch file to be executed prior to running demo programs:
# directory containing PGPLOT library
setenv PGPLOT_DIR /vol/local/pgplot
# pointer to the PGPLOT file containing character fonts
setenv PGPLOT_FONT /vol/local/pgplot/grfont.dat
# default PGPLOT device (X-window)
setenv PGPLOT_DEV /xwin
# default background and foreground colors (can be changed, as needed)
setenv PGPLOT_BACKGROUND black
setenv PGPLOT_FOREGROUND white
SYSTEM REQUIREMENTS
The only requirement is to have a couple of Mb of free space on the current hard drive. This is required by demo2 which generates about 1Mb of GIF frames.
SHORT DESCRIPTION
The core routines used for plotting of a 3D point on a projected plane are collected in p3d.f. Some other convenient routines (e.g., routine for drawing a 3D box) are also there. The routines are quite simple and self-explanatory. Their use is clarified by the three demo programs: demo1.f, demo2.f, demo3.f
Demo programs are not intended to be any kind of respectable software, the intent is rather to stipulate the creativity of the user with a few simple examples. You will, no doubt, discover limitations of the PGPLOT and inconveniences of having to program even small details (like, for example, axis labels). However, if you are just a bit persistent, you may also discover how much control, power, and freedom PGPLOT gives you to realize your visualization ideas.
demo1.f - this program illustrates the use of routines to plot a
3D distribution of particles and allows for a simple manipulation
of the plot using keys: zoom in/out, rotation, fiddling
with particle coloring, contrast, and brightness. The fiddling
could be used to find an optimum desired rendering that can be
used, for example, to produce a hardcopy.
demo2.f - This program shows how to use the routines to generate a sequence
of GIF frames (any other format of graphic output supported by
the PGPLOT can, of course, be used instead of GIF) of a flyby
through a particle distribution. The frames are combined into
and MPEG file flyby.mpv available with the distribution.
The trajectory of a particular flyby can be controlled by
changing parameters controlling the plot (array psu): box center,
location of the view-point etc. More intricate, than in this demo
trajectories through and around the box can be easily generated.
The frames can be combined to produce a movie file.
TIP1: to experiment with trajectories plotting of particles
can be turned off and output directed to /XWIN device.
This will allow to see the flyby in real time on your
screen.
TIP2: It may be convenient to read the trajectory (i.e. elements
of psu array for each frame from a file). A separate program
can be used to generate the trajectory. This would allow
to experiment with trajectories without changing the main
program.
demo3.f - This program is the same as demo1.f except the interactive
plot manipulation is done with the mouse using buttons. This
demo uses BUTTON library to draw buttons (see above for
installation information). Additional to demo1.f interactive
options include changing rotation angle, zoom factor, and
saving the plot as a GIF or PostScript file.
TIP: The color PostScript in PGPLOT always assumes that foreground
color is black and background color is white. To overcome
that you should swap colors 0 and 1. Consult PGPLOT website
for more details on the use of PS format.
INPUT FORMAT
Demo programs use a particle distribution (particles.dat) drawn randomly (1% of all the particles in the simulation is shown) from a simulation of 5 Mpc volume of the CDM model using Adaptive Refinement Tree N-body code (simulation is by A.Kravtsov and G.Yepes).
The input format is arbitrary and can be modified, as needed. The most important is the range of coordinate values. If particles are distributed in a cube, the code assumes that
3D particle coordinates are in the range [-0.5,0.5] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ with center of the cube having coordinates {0,0,0}. This is a matter of convention, rescaling coordinates to this range is user's responsibility. Particles do not have to be distributed in a cube. The coordinates may span a larger (and different in each of 3 axis) range, if needed. They should be however centered around the point {0,0,0}.
RENDERING OF PARTICLES
In the supplied demo programs particles are rendered (i.e., color-coded and assigned brightness) according to the local density. In this particular case, the natural log of the number of particles within a sphere of the 15 kpc radius centered on the given particle, was used as the density indicator. The logarithmic coloring usually works well for cosmological N-body outputs, although other schemes can be experimented with. The coloring strategy is totally up to user and is best determined for each particular purpose by experiment. Routine Fiddle is very useful for this kind of experimentation.