Surface Evolver Documentation - Installation

# Surface Evolver Documentation

Back to top of Surface Evolver documentation. Index.

# Surface Evolver Aquisition and Installation

This chapter explains how to get and install the Evolver. Evolver is written to be portable between systems. There are pre-compiled versions for Windows and Macintosh; source files and a Makefile are provided for unix/Linux systems. The distribution packages for various systems are available from the Evolver homepage. Each package also contains documentation and sample datafiles and scripts. The documentation subdirectory is named `doc`, and contains the manual in PDF format, an HTML version of the documentation (except for the mathematical parts), and a brief unix man page evolver.1. The HTML files are also used by the Evolver help command. The samples are in the subdirectory `fe` (which is the file extension I use for datafiles; it stands for "facet-edge," referring to the internal structure of surfaces in the Evolver). Below are instructions for standard packages:

- UNIX/Linux
- MS-Windows 95/98, Windows NT/2000/XP/2003
- Macintosh OS X

The complete manual in PDF format is separately available as manual220.pdf. A PostScript form is available as manual220.ps.

## Unix version

The program is distributed in a compressed tar file evolver-2.20.tar.gz. Get this file into a working directory. Uncompress it with

     gunzip evolver-2.20.tar.gz

Extract the files with

     tar xvf evolver.tar

This will unpack into three subdirectories: src (source code), doc (the manual), and fe (sample datafiles). The packed archive is about 2MB, unpacks to about 5MB. You will probably need another 3 or 4 MB to compile. See below for compilation instructions.

#### EVOLVERPATH environment variable

Evolver needs to find the initial data file and sometimes other files (e.g. command files for the "read" command). If the named file is not in the current directory, then an environment variable called `EVOLVERPATH` will be consulted for a directory search list. The datafile directory and the directory with these HTML files should definitely be included. The format is the same as the usual `PATH` variable.

Set it up as usual in your system, in .profile or .login or .cshrc or wherever:

Unix C shell:

         setenv EVOLVERPATH /usr/you/evolver/fe:/usr/you/evolver/doc

Bourne shell:

         EVOLVERPATH=/usr/you/evolver/fe:/usr/you/evolver/doc
         export EVOLVERPATH

#### Unix compilation

Change to the `src` subdirectory of your Evolver directory. First, you need to modify `Makefile` for your system. `Makefile` begins with sets of macro definitions for various systems. If your system is listed, remove the comment symbols '`#`' from start of your definitions. If your system is not there, use the `GENERIC` defines, or set up your own. If you do define your own, be sure to put a corresponding section in `include.h`. Edit `CFLAGS` to have the proper options (optimization, floating point option, etc.). `GRAPH` should be the name of a screen graphics interface file. Use `glutgraph.o` if possible; most systems have OpenGL/GLUT graphics now. Otherwise, for primitive X windows graphics you can use `xgraph.o`. For no built-in screen graphics at all you can use `nulgraph.o`. `GRAPHLIB` should be the appropriate graphics library plus any other libraries needed. Check all paths and change if necessary for your system.

GLUT graphics uses a separate thread to display graphics, so if you use GLUT, you must compile with `-DPTHREADS` and put `-lpthread` in `GRAPHLIB`.

If you want Evolver to be able to use geomview, include `-DOOGL` in `CFLAGS`.

If you want Evolver to operate in a higher space dimension n than the default maximum of 4, include `-DMAXCOORD=`n in `CFLAGS`. This sets the upper limit of dimensionality, and is used for allocating space in data structures. You can use `-DMAXCOORD=3` to save a little memory.

If your system supports the long double data type, you can compute in higher precision by compiling with `-DLONGDOUBLE` in CFLAGS. But this slows computations, and should be used only by precision fanatics.

You can let the compiler optimize better if you hard-wire the space dimension into the code with the compiler option `-DSDIM=`n, where n is the desired dimension of space. But such an Evolver can handle only the given space dimension, nothing higher or lower.

Silicon Graphics systems with multiple processors may compile a version that will use all processors for some calculations by including `-DSGI_MULTI` in `CFLAGS`. This version will run fine with one processor, also. Currently, the only calculations done in parallel are the "named quantities". The number of processes actually done in parallel can be controlled with the `-p` n command line option.

The file `include.h` lists the include files for various systems. If your system isn't listed, you will have to put in a list of your own. Try copying the generic list (or one of the others) and compiling. Your compiler will no doubt be very friendly and helpful in pointing out unfound header files. `include.h` also has various other system-specific defines. See the `GENERIC` section of it for comments on these, and include the appropriate ones for your system.

If you wish to use the commands based on the METIS partitioning software (metis, kmetis, body_metis, and metis_factor), then you should download the METIS package, and "make" the library libmetis.a (on some systems, make complains it cannot find ranlib, but the resulting libmetis.a still works). In Evolver's Makefile, add -DMETIS to `CFLAGS`, and add `-lmetis` to GRAPHLIB. You will probably also have to add -Lpath to GRAPHLIB to tell the linker where to find libmetis.a. Note that METIS is incorporated in the Windows executable. If you are using hessian commands on very large surfaces, then metis_factor can be much faster than the other sparse matrix factoring schemes in Evolver, and I highly recommend it.

Now try compiling. Hopefully, you will only have to change the system-specific parts of `Makefile` and `include.h` to get things to work. If significant changes to other files are needed, let me know.

Test by running on the cube sample file as described in the Tutorial.

#### Installing geomview

If your system does not have OpenGL/GLUT, I suggest you get the geomview package from The Geometry Center. There are pre-compiled binaries for many unix systems here. Follow geomview's installation directions, and make sure that geomview is accessible through your `PATH`. NOTE: The X windows versions of geomview seem to require some event to occur in the geomview display window before it will redraw after loading a new datafile. So if geomview seems hung, just run the mouse over the window to give it an event to wake it up.

## MS-Windows 95/98, Windows NT/2000/XP/2003

The file evolver220-NT.zip has the executable file evolver.exe along with the documentation and sample datafile subdirectories. Create a directory (such as C:\evolver), and unzip the distribution package there. You can leave evolver.exe there and add c:\evolver to your PATH, or you can copy evolver.exe to someplace in your PATH, such as C:\windows\system32.

You should also create an environment variable EVOLVERPATH telling Evolver where to search for various files. Do this by opening Control Panel/System/Advanced/Environment Variables, clicking New under System Variables, entering EVOLVERPATH for the Variable name, and `c:\evolver\fe;c:\evolver\doc` for the Variable value. You may add further paths of your own to this list if you wish.

To make Evolver start automatically when you click on a *.fe file, you can associate Evolver with the file extension .fe by opening My Computer/Tools/Folder Options/File Types/New, entering the File Extension fe, clicking OK, clicking Change, and browsing for the evolver.exe program. (This sequence of actions may vary on different Windows versions.)

The Windows version uses OpenGL/GLUT graphics. OpenGL is standard in Windows, and all the necessary GLUT components are included in the executable, so you don't have to install anything.

## Macintosh OSX version

I am not a Mac person, and have only learned enough Mac to get Evolver minimally ported, so there are no Mac bells and whistles.

There is a Mac OSX version at Evolver220-OSX.tar.gz. After downloading and unpacking it, you probably get a folder Evolver220-OSX, which has the executable file Evolver, the samples folder fe, and the documentation folder doc. You can move the executable to some place on your PATH, or add the folder to your PATH. You should also create an environment variable EVOLVERPATH containing paths to the fe and doc folders by placing the following line in your {\tt .tcshrc} file, with appropriate modifications:

     setenv EVOLVERPATH /User/yourname/Evolver220-OSX/fe:/User/yourname/Evolver220-OSX/doc

This version descends from the unix version, not the Mac OS 9 version, so you must run it from a terminal window. It uses OpenGL GLUT graphics, which are standard with OSX.

## Macintosh OS 9 version

There is a Mac PowerPC OS9 version available as `Evolver220-OS9.sit.hqx`. It includes a README file with Mac specific information and datafiles in Mac format.

The archive file contains:

- README.MAC - Mac-specific information.
- EvolverPPC - the application executable file.
- fe - folder of sample datafiles and scripts in Mac format (CR as end-of-line).
- doc - folder of HTML documentation and help files.
- manual220.pdf - manual in Adobe PDF format.

Installation: All you need to do is unpack in a directory somewhere. The datafiles can go in a different directory, but then you will have to supply path names when using them.

#### Mac OS9 version idiosyncracies:

This is a bare-bones port, so there are few Mac bells and whistles like menus. There are two windows: a text window and a graphics window. The text window provides a command-line interface to Evolver. Commands are typed in and text output appears here. All text input will go to the text window when either the text or graphics window is in front, so you can keep the graphics window in front while typing commands. Dragging the mouse in the graphics window will cause the object to rotate in 3D around an axis perpendicular to the mouse drag and with an angle proportional to the length of the drag. The redraw occurs after the mouse is released, not during the drag. Redrawing occurs in the background, so there may be some delay until the picture appears.

At start-up, you will be asked to enter the name of a datafile in the text window. If the file is not in the same directory, you will have to give the path also. For a Mac, the path character is a colon. Leading colons on the path go to parent folders.

Redirecting output: The Mac doesn't have piping to other programs, so piped output of commands goes to a file. Example:

         list vertices | "outfile"

Interrupting a repeating command: Hit command-period. Will complete current command and return to command prompt.

Memory partition: The default partition size is 8 Meg. Evolver will run in 2 Meg, but your surfaces won't be able to be very complex. I suggest making the partition as large as you can. You can change the partition size with Finder GetInfo.

Back to top of Surface Evolver documentation. Index.