Installing Vis5D

Mesa

Mesa is a free OpenGL replacement, and is required if your system does not already have OpenGL, IrisGL, or PEX (an old 3d library for X). If you don't know whether you have Mesa or one of these other libraries, you can skip this step for now; when you try to configure Vis5D (in section 2.2.3) , the configure script will stop and complain if it can't find one of the libraries. Then you can go back to this step.

To install Mesa on your machine, go to the Mesa home page and download it.

You'll get a file something like MesaLib-3.1.tar.gz Unpack it:

% gunzip MesaLib-3.1.tar.gz % tar -xf MesaLib-3.1.tar

Then, cd to the MesaLib-3.1 directory and type:

% ./configure % make

This should configure and compile Mesa. Finally, switch to root (superuser) and type:

% make install

If you don't have access to the root account on your machine, and your system administrator is unwilling to install Mesa for you (unlikely, since Mesa is very standard and widely-used), you can instead install it to a location in your home directory, e.g. ~/Mesa. To do this, you would use the following steps instead of the above:

%./configure --prefix=$HOME/Mesa % make % make install

The last step will copy the Mesa libraries and headers to ~/Mesa/lib, ~/Mesa/include, etcetera.

When you run 'make install', it may print out some important directions regarding shared libraries. If you install in a non-standard location, it will typically tell you add the prefix/lib directory to some environment variable. On Linux systems, you may need to run /sbin/ldconfig, etcetera.

NetCDF (optional)

NetCDF is a free library for reading scientific data that can optionally be used by Vis5D. If you do not have NetCDF, then certain features of Vis5D will be disabled, notably irregular dataset support.

To get NetCDF, go to the NetCDF home page and download the NetCDF package. As of this writing, the current version is 3.4.

Once you have downloaded it, unpack and compile the package with:

% uncompress netcdf-3.4.tar.Z % tar xf netcdf-3.4.tar % cd netcdf-3.4/src % ./configure % make

On Linux systems, you may instead have to use:

% make CC="gcc -Df2cFortran"

because NetCDF doesn't know how to deal with GNU g77.

Vis5D only needs the libnetcdf.a file, located in libsrc/libnetcdf.a. If you have downloaded and unpacked Vis5D already, you can copy this file to the Vis5D directory now; otherwise, just leave it there and remember where it is.

Vis5d+

Since you are reading this file, you have probably already downloaded and unpacked Vis5d+. Otherwise, go to the Vis5d+ home page and download the latest version. It will be something like vis5d+-1.0.1.tar.gz. Unpack it with:

% gunzip vis5d+-1.0.1.tar.gz % tar xf vis5d+-1.0.1.tar

Now, cd to the Vis5D directory (cd vis5d+-1.0.1 if you were following the steps above). At this point, you will run a "configure" script to automatically configure Vis5D for your machine. The most basic way to run configure is by:

% ./configure

but there are several optional arguments that you may want to pass it:

You can also set one or more environment variables before running configure, to help it find libraries and otherwise control its behavior. (You can go back and do this if configure has trouble.) You set an environment variable by the syntax setenv variable value (or export variable=value if you are using ksh, bash, or the like). Most of the time, you won't need to do this, but if you do, some possible environment variables are:

• CC: the name of the C compiler

• CPPFLAGS: -I dir flags to tell the C compiler where to look for header files

• CFLAGS: C compiler flags

• F77: the name of the Fortran compiler

• FFLAGS: Fortran compiler flags

• LDFLAGS: linker flags (e.g. -L dir to look for libraries in dir)

The most common use for these variables is when you have libraries installed in nonstandard locations, in which case you will use the CPPFLAGS and LDFLAGS environment variables. For example, consider the case above where you installed the Mesa library in ~/Mesa. You would then tell configure where to find the Mesa libraries and header files with:

% setenv CPPFLAGS "-I$HOME/Mesa/include" % setenv LDFLAGS "-L$HOME/Mesa/lib"

Be sure to scan the configure output for important warning messages, which will be surrounded by asterisks (*******). Once you have run configure successfully, you can compile Vis5D by typing:

% make

If you want, you can run the program right away by typing:

% src/vis5d hole.v5d -path src

hole.v5d is a sample data file included with Vis5D. The -path src argument is necessary to tell it where the map data files are located; it will no longer be need after you do a 'make install' (see below). Click and drag in the display window to rotate it, and click on buttons in the lower portion of the control window to plot the data.

If this completes succesfully, you will then want to install Vis5D:

% make install

(You may need to switch to root first, or do su -c "make install", if you are installing in system locations.)

Note that the make install output may contain important instructions regarding shared libraries (if you want to link to the Vis5D libraries in your programs). e.g. on Linux you'll need to run /etc/ldconfig and possibly edit /etc/ld.so.conf.

Once this is done, the vis5d program, utilities, data, and libraries are installed under /usr/local, or wherever you specified with the --prefix argument to configure (as described above). You should now be able to run it by simply typing vis5d (if you installed in a system directory) or by typing prefix/bin/vis5d (otherwise, where prefix was the argument to --prefix), in either case followed by the name of a data file.

One sample data file, hole.v5d, is included with Vis5D, and more may be downloaded from the Vis5D ftp site.

If you want to uninstall Vis5d at any time, you can do:

% make uninstall

which removes the files installed by make install.

Manifest

The files installed by Vis5D include:

(Programs using the full Vis5D API should link with -lvis5d -lv5d, while programs just doing file I/O can link with just -lv5d.)

You can also download from the Vis5D web site sample code for user supplied data formats, including:

LAMPS.v5d: Sample LAMPS data set

SCHL.v5d: Sample data set; Bob Schlesinger's thunderstorm model

Customizing

After installation and testing you may want to customize the vis5d program by editing the src/vis5d.h file:

1. The visualization program vis5d assumes your system has 32 megabytes of memory. Although you can override this when you invoke vis5d, it may be convenient to change the default if your system has more than 32MB. This value is now controlled by the --with-memory=MB option to the configure script (see above).

2. There are two ways to specify a different topography and/or map file. One way is to edit src/vis5d.h and change the values for TOPOFILE and/or MAPFILE. For example, if you move the map and topography files to /usr/local/data, you would specify /usr/local/data/EARTH.TOPO and /usr/local/data/OUTLUSAM respectively. The other way is press the 'DISPLAY' button on the main contral panel, then press the 'Options' button found above each display menu. The 'toponame' and/or 'mapname' fields can be changed accordingly.

   By default, these files are looked for in /usr/local/share/vis5d+, or whereever Vis5D was installed. You can change this by either the -path argument to Vis5D or the VIS5D_PATH environment variable.

When you are finished changing the src/vis5d.h file, you must recompile. the programs.