Surface Evolver Documentation

Surface Evolver Acquisition 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
Microsoft Windows
Macintosh OS X

The complete manual in PDF format is separately available as manual270.pdf.

Unix version

Instructions for installing the Surface Evolver on unix-style systems. Evolver compiles on 64 bit systems as well as 32 bit systems.

Quick start:
1. Download evolver-2.70.tar.gz.
2. Unpack the Evolver archive.
3. In the src subdirectory, edit Makefile to uncomment the lines for your system.
4. Run "make".
5. Test by running "./evolver ../fe/cube.fe"

Detailed instructions:

1. The Evolver is distributed in a compressed tar archive evolver-2.70.tar.gz, available from http://www.susqu.edu/brakke/evolver. Get this file into a working directory. The packed archive is about 2MB, unpacks to about 5MB. You will probably need another 3 or 4 MB to compile.

2. Uncompress the archive with

      gunzip evolver-2.70.tar.gz

Extract the files with

      tar xvf evolver.tar

This will unpack into three subdirectories: src (source code), doc (the html version of the manual), and fe (sample datafiles and scripts). The working directory will also contain a PDF version of the manual, and a man page, evolver.1.

3. Install the man page: copy evolver.1 to some appropriate place on your manpath, such as /usr/local/share/man/man1. You may have to become root to have permission to do this.

4. Set the EVOLVERPATH environment variable: Evolver needs to find the initial datafile and sometimes other files (e.g. command files for the read command and the help documentation files). 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 the HTML documentation files should definitely be included. The format is the same as the usual PATH environment 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

5. Change to the src subdirectory of your Evolver directory.

6. 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 the appropriate lines. If your system is not there, use the GENERIC lines, or set up your own. If you do define your own, be sure to put a corresponding section in include.h.

7. In Makefile, edit the CFLAGS line to have the proper options (optimization, floating point option, etc.).

8. In Makefile, GRAPH should be the name of a screen graphics interface file. Use glutgraph.o if possible; most systems have OpenGL/GLUT graphics now. GLUT graphics uses a separate thread to display graphics, so if you use GLUT, you must put -DPTHREADS in CFLAGS and put -lpthread in GRAPHLIB. If not using GLUT, 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.

9. If you want to use parallel processes on a multiprocessor machine, put -DPTHREADS in CFLAGS and put -lpthread in GRAPHLIB. Currently, the only calculations done in parallel are basic energies and named quantities. The number of processes actually done in parallel can be controlled with the -p n command line option.

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

11. If you want Evolver to operate in a higher space dimension than the the default maximum of 4, include -DMAXCOORD=n in CFLAGS, where n is the maximum space dimension. This sets the upper limit of dimensionality, and is used for allocating space in data structures.

12. If your system supports the long double data type, you can compute and print values in higher precision by compiling with -DLONGDOUBLE in CFLAGS. But this slows computations somewhat, and should be used only by precision fanatics. And on Intel chips, it only does 80 bit precision, even if it allocates 128 bits of storage, since that is the hardware precision of the 8087 math coprocessor. For 128 bit precision (in software, so much slower), compile with -DFLOAT128 and link with the quadmath library (which you have to find on your own).

13. 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 from, http://www-users.cs.umn.edu/~karypis/metis/ 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 -L metispath 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.

14. From the shell command prompt in the src directory, run "make". This will produce the Evolver executable file named "evolver" in the src directory. If there are errors, 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 at brakke@susqu.edu.

15. Copy the evolver executable to someplace on your PATH, such as $HOME/bin or /usr/local/bin, or make a link someplace on your PATH to the evolver executable.

16. Test by opening a new shell and running "evolver cube". Now you should be able to follow the tutorials in the HTML manual or the printed manual.

Installing geomview

If your system does not have OpenGL/GLUT, I suggest you get it (the freeglut developer package, for instance). Otherwise you might 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.

Microsoft Windows version

The distributions available here include both the 32-bit version of Evolver (evolver.exe) and the 64-bit version (evolver64.exe). The 64-bit version is meant for very large models (hundreds of thousands of facets). Unless you have such a large surface, use the 32-bit version since it is 10 to 20 percent faster, having less data to move around.

There are now two alternative ways to install Evolver:

I. Download `Evolver-2.70-Win32.msi` and run it.

This is an installation program that will lead you through all steps and options in the installation procedure. It will automatically set up the environment variables described below and copy files to folders. Puts the Evolver executables on your PATH, and associates the .fe extension with Evolver, so clicking on a datafile launches it. Includes both the 32-bit version (evolver.exe) and the 64-bit version (evolver64.exe).

II. Download `evolver2.70-Win32.zip`.

For an old-fashioned do-it-yourself installation, this file has the executable files evolver.exe and evolver64.exe along with the documentation and sample datafile subdirectories. Steps to follow after downloading:

Create a directory (such as C:\evolver), and unzip the distribution package there.
Add your installation directory ro your PATH (Control Panel/System/Advanced System Settings/Environment Variables/System Variables/PATH/Edit) 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 the Mac OSX version is just a port of the unix version, so there are no Mac bells and whistles.

Quick start:
1. Download Evolver270-OSX.tar.gz.
2. Open the Evolver270-OSX folder and double-click on the evolver file.
3. Evolver prompts for a file; tell it fe/cube
4. You should now be able to follow the tutorial in the manual.

Detailed instructions:

1. Download Evolver270-OSX.tar.gz.

2. The download probably created a folder Evolver270-OSX on your desktop. This folder really has a unix path something like /Users/yourname/Evolver270-OSX. These notes will mostly refer to the terminal command line, so you should be able to open a terminal and use a command line prompt.

3. The Evolver270-OSX folder has the executable file evolver, the samples folder fe, the documentation folder doc, a PDF version of the manual, and a man page evolver.1.

4. Move the executable to some place on your PATH, e.g.

   cp evolver /Users/yourname/bin

or add the Evolver folder to your PATH.

5. You should also create an environment variable EVOLVERPATH containing paths to the fe and doc folders by placing the following line in your shell initialization file, with appropriate modifications. You can tell which shell you are running by running the ps command at the command prompt.

C Shell (csh, tcsh): put the following in /Users/yourname/.cshrc or /Users/yourname/.tcshrc:

 setenv EVOLVERPATH /Users/yourname/Evolver270-OSX/fe:/Users/yourname/Evolver270-OSX/doc

Bourne shell (sh,bash): put the following in /Users/yourname/.profile or /Users/yourname/.bashrc:

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

6. Install the man page by copying evolver.1 to some place on your manpath, e.g.

     cp evolver.1 /usr/share/man/man1

You may have to become root to have permission to do this.

7. Test by opening a new shell and running "evolver cube". Now you should be able to follow the tutorials in the HTML manual or printed manual.

8. If you wish to compile your own version of the Evolver, and have a C compiler, then follow the unix instructions.