Surface Evolver Documentation

Command line options

The syntax for starting the Evolver from the system command prompt is:

evolver [-ffilename] [-a-] [-d] [-e] [-i] [-m] [-pn] [-q] [-w] [-x] [datafile]

The current directory and EVOLVERPATH will be searched for datafile. If the datafile is not found, then a new search with extension .fe is done. If still not found, or the datafile is not given on the command line, then the user will be prompted. Options:

-a-

Do not enable automatic conversion to named methods and quantities mode when a situation requiring it arises.

-d

Prints YACC debugging trace as datafile is parsed. May be helpful if you can't figure out why your datafile doesn't get read in properly AND you know YACC.

-ffilename

Specifies the name of a file to be used as command input after the datafile is read. At the end of this file, input reverts to standard input. The effect is the same as redirecting input from the file, except that -f will echo commands to the screen and revert to standard input at the end. Also note that errors will cause input to revert to standard input.

-e

Echo input. Meant for echoing commands of piped input to screen so the user can follow what is going on in case Evolver is being controlled by another process.

-i

Keeps elements numbers as listed in the datafile, instead of renumbering them consecutively. Leaves no good way to compact or order element ids in list, so it is not default for now.

-m

Turn memory debugging on at start of program. Same effect as Evolver memdebug command.

-pn

Forces use of n processes for an Evolver compiled in multi-processor mode. n may be larger or smaller than the physically available number of processors. The default is 1.

-q

Convert everything to named quantities internally. There are a few things for which no quantities exist yet; they will produce error messages.

-w

Causes Evolver to exit whenever a warning occurs. Meant to be used when Evolver is run in a shell script.

-x

Causes Evolver to exit whenever an error occurs. Meant to be used when Evolver is run in a shell script, so that Evolver doesn't get hung up waiting for input in response to an error.

---

Bugs

Bug reports should be submitted by email to brakke@susqu.edu. Please include the Evolver version number, a description of the problem, the initial data file, and the sequence of commands necessary to reproduce the problem.

---

Evolver Newsletters

The group of Surface Evolver users has grown large enough that I have started a newsletter. Contents include announcement of new versions and latest features, bibliography, and anything else anybody would like to contribute. If you would like to be on the mailing list, send your email address to brakke@susqu.edu.

Back issues:

• Newsletter 1
• Newsletter 2
• Newsletter 3
• Newsletter 4
• Newsletter 5
• Newsletter 6
• Newsletter 7
• Newsletter 8
• Newsletter 9
• Newsletter 10
• Newsletter 11
• Newsletter 12
• Newsletter 13
• Newsletter 14

---

Error handling

When the Surface Evolver detects an error, it prints an error message and tries to take appropriate action. If the -x command line option was given when Evolver was started, then Evolver exits immediately with a nonzero error code. This is useful when running Evolver from shell scripts. There are several categories of errors:

• WARNING - Something has happened that you should know about, but Evolver proceeds normally after printing the message.
• SYNTAX ERROR - The parser has detected an error. Recent input up to the detection of the error is printed, but the actual problem may be earlier.
• DATAFILE ERROR - There is an error in the datafile being read in. Evolver attempts to recover by skipping to the next recognizable part of the datafile, but will abandon the datafile after 5 such errors. The surface data that was read in is available for your inspection, but it probably forms an inconsistent surface and you should not try to evolve it.
• ERROR - This is an error encountered during the execution of a command. The command is abandoned and Evolver returns to the main prompt. The actions of the command are not undone.
• FATAL ERROR - An error from which recovery is impossible. Evolver exits immediately.

---

Surface initialization

Whenever the Surface Evolver loads a new surface, either on startup or in response to the q or load commands, the following actions occur:

• Any previous surface has all memory deallocated. All user-defined variables and commands are deleted, including any currently executing commands.
• Internal variables are initialized to default values.
• The datafile is read in.
• In the soapfilm model, any nontriangular face is divided into triangles by creating a vertex in the center and making edges from the center to the vertices.
• In the soapfilm model, the order of facets around each edge is determined geometrically.
• Vertices are projected to any level set constraints.
• Checks as described for the C command are done.
• Initial areas, energies, and volumes are calculated.
• The viewing matrix is reset to center the object in the graphics window.
• If any graphics are active, the new surface is drawn.
• The main command prompt is started.

---

Interrupting execution

Evolver operation may be interrupted with the standard keyboard interrupt, CTRL-C usually (SIGINT for you unix gurus). During repeated operations, this will set a flag which is checked at the end of each loop. Repetition will cease after the current step and control will return to the main prompt. If you give a second interrupt before the loop has ended, Evolver will abort the command and return to the main prompt. Beware that this may leave the surface in an inconsistent state if surface topology changing operations were going on. An immediate abort will also happen if an interrupt is received outside a loop. If Evolver receives SIGTERM (say from the unix kill command), it will dump to the default dump file and exit. This is useful for stopping a background Evolver running a script. The same thing will happen with SIGHUP, so losing a modem connection will save the current surface.

Note: In Windows NT/95/98, the second interrupt doesn't do anything much since Windows creates a separate thread to handle the interrupt, and I can't find any way to force the offending thread to stop and longjmp back to where it should. So if the Evolver is really, really stuck, you may just have to kill the whole program.

---

Parallel computation

Parallel versions of the Surface Evolver are available for several types of systems:
• Silicon Graphics
• PVM (Parallel Virtual Machine)
• MPI

Silicon Graphics parallel version

Silicon Graphics systems with multiple processors may run a version that will use some or all processor by including -DSGI_MULTI in CFLAGS in Makefile. This version will run fine with one processor, also. Currently, the only calculations done in parallel are the "named quantities", so it is best to start Evolver with the -q option. The number n of processes actually done in parallel can be controlled with the -pn command line option. It will slow things down to use more processes than are physically available, but it is possible to run multiple processes on a single-processor system. SGI's use shared memory, so no message passing is necessary, and this version runs pretty well.

PVM parallel version

PVM (Parallel Virtual Machine) is a portable message-passing interface for distributed parallel processing. The PVM Evolver is not too sophisticated yet, passing all data to all processes. Hence it should be regarded as experimental rather than practical. Improvements are planned some day. The only practical use of it so far has been massive knot energy calculations, where every process does need to have all data. Interested users should contact brakke@susqu.edu.

MPI parallel version

MPI (Message Passing Interface) is a portable message-passing interface for distributed parallel processing. The MPI Evolver is not too sophisticated yet, passing all data to all processes. Hence it should be regarded as experimental rather than practical. Improvements are planned some day. The only practical use of it so far has been massive knot energy calculations, where every process does need to have all data. Interested users should contact brakke@susqu.edu.

---

---

Back to top of Surface Evolver documentation.

---

Author's home page.