# Surface Evolver command language

The Surface Evolver has an interactive command language. It has variables, expressions, subroutines, conditionals, and iteration constructs. But not subroutine arguments, local variables, structures, or arrays. Variables are either floating point, string, or subroutine names. The Evolver command language continues to grow by accretion, and it looks like it's headed towards a full programming language.
 Redirecting and piping output Control structures Element generators Single letter commands Toggle commands General commands

## Command input

The Surface Evolver command interpreter reads from an input stream, which may be from the end of the
datafile, from a file given on the system command line, from stdin (the terminal), or from a file given in a READ command.

The interactive command prompt is "Enter command: ".

Commands are read one at a time, parsed, and executed. By default, a line is expected to contain a complete command, so no special end-of-command token is needed.

Multi-line commands may be entered by enclosing them in braces {...}. If a line ends while nested in braces or parenthesis, Evolver will ask for more input with the prompt "more> ". It will also ask for more if the line ends with certain tokens (such as +') that cannot legally end a command. Unclosed quotes will also ask for more, and embedded newlines will be omitted from the final string. Explicit continuation to the next line may be indicated by ending a line with a backslash (linesplicing). You may want to use the read command to read long commands from a file, since there is no command line editing.

Successfully parsed commands are saved in a history list, up to 100 commands. They may be accessed with !! for the last command or !string for the latest command with matching initial string. !n will repeat a command by history list number. The command will be echoed. The saved history list may be printed with the history command.

Some single-letter commands require interactive input. For those, there are equivalent commands that take input information as part of the command. This is so commands may be read from a script without having to put input data on additional lines after the command, although that can still be done for the single-letter versions.

General note: Some commands will prompt you for a value. A null response (just RETURN) will leave the old value unchanged and return you to the command prompt. On options where a zero value is significant, the zero must be explicitly entered. Commands that need a real value will accept an arbitrary expression.

Many commands that change the surface or change the model will cause energies and volumes to be recalculated. If you suspect a command has not done this, the recalc command will recalculate everything. It will also update any automatic display.

In the command syntax descriptions, keywords are shown in upper case, although case is irrelevant in actual commands, except for single-letter commands.

## Command separator

Several commands on the same line or within a compound command must be separated by a semicolon. A semicolon is not needed after the last command, but won't hurt. Do not use a semicolon after the first command in an IF THEN ELSE command. Do use a semicolon to separate a compound command from the next. Example:
      g 10; r; g 10; u
myc := { print 5;
g 10;
if qwer < foo then print 3 else { print 2; print 4; };
aa := 23
}


## Compound commands

Curly braces group a list of commands into one command. The commands are separated by semicolons. A semicolon is needed after a compound command within a compound command to separate it from following commands (note this is different from the C language). Do not use a semicolon after the first command in an IF THEN ELSE command. An empty compound command {} is legal. Examples:
  if ( foo > 4 ) then { g;g;u; } else print 4;
while ( xx < 2 ) do { g; xx := xx + 1 }
aa := { g 5;
foreach vertex vv do {
printf "id: %g  coord: %f %f %f\n",id,x,y,z;
count := count + 1;
};  // note semicolon here!
printf "done.\n"
}


## Command repetition

Certain types of commands can be repeated a number of times by following the command with an integer. Be sure to leave a space between a single-letter command and the expression lest your command be interpreted as one identifier. To avoid several types of confusion, only certain types of commands are repeatable:
Examples:
   g 10
U 2
{ g 20; u; V; u } 20
myc := { g 20; V }; myc 10


## Assignment commands

The assignment operator := can be used to assign values to various entities. Note that ':=' is used for assignment, not '='. The C-style arithmetic assignments +=, -=, *=, and /= work. For example, val += 2 is equivalent to val := val + 2. These also work in other assignment situations where I thought they made sense, such as attribute assignment. Possible assignments:

## User-defined commands

Users may define their own commands with the syntax
   identifier := command

The shortest complete command on the right side is used. Thus "gg := g 10; u" would give gg the same value as "gg := g 10". It is wise to use braces to enclose the command on the right side so the parser can tell it's a command and not an expression. Also multiline commands then don't need linesplicing. Do not try to redefine single-letter commands this way; use :::=. Example:
   gg := {g 10; u}


## Variable assignment

Values can be assigned to variables. Values can be numeric or string. The variable names must be two or more letters, in order they not be confused with single-letter commands. Syntax:
   identifier := expr
identifier := stringexpr

If the variable does not exist, it will be created. These are the same class of variables as the adjustable parameters in the datafile, hence are all of global scope and may also be inspected and changed with the 'A' command. Examples:
   maxlen := max(edge,length)
newname := sprintf "file%03g",counter


## Redirecting and piping command output

The output of a command can be redirected to a file with the unix-style append symbol '>>'. This appends output to the file; it does not erase any existing file. Syntax:
   command >> stringexpr

The output of a command can be redirected to a file with the symbol '>>>'. This overwrites an existing file. Syntax:
   command >>> stringexpr

Redirection with >' is not available due to the use of >' as an comparison operator. The output of a command can be piped to a system command using the unix-style pipe symbol |'. Syntax:
   command | stringexpr

The stringexpr is interpreted as a system command.

On systems (such as DOS, Windows, and Macs) without true piping, the string is interpreted as a filename, so output goes directly to a file instead of a command, replacing any old contents. Examples:

   list facets | "more"
list vertices | "tee vlist" ; g 10 | "tee g.out"
{ {g 10; u } 20 } >> "logfile"
{foreach facet do print area} | "cat >areafile"


## Control structures

The following control structures are available in the Evolver commmand language:

## IF ... THEN ... ELSE

Commands may be conditionally executed by the syntax
   IF expr THEN command

IF expr THEN command ELSE command

expr is true if nonzero. Parentheses around expr are not needed, but do not hurt. Do not use a semicolon to end the first command. Example:
   if max(edges,length) > 0.02 then {r; g 100} else g 4


## WHILE ... DO ...

Command syntax for pretest iteration loop. Syntax:
  WHILE expr DO command

expr is true if nonzero. Parentheses around expr are not needed, but do not hurt. Example:
   count := 0
while count < 10 do { g 10; u; print total_energy; count := count + 1 }


## DO ... WHILE ...

Command syntax for posttest iteration loop. Syntax:
   DO command WHILE expr

expr is true if nonzero. Parentheses around expr are not needed, but do not hurt. Example:
   do { oldenergy := total_energy; g 10 }
while (oldenergy-total_energy < 1e-6)


## FOREACH

Repeat a command for each element produced by an element generator. Syntax:
FOREACH generator DO command

Examples:
 foreach vertex do print x^2 + y^2 + z^2

foreach edge ee where ee.dihedral > .4 do {
printf "id %g\n",id;
foreach ee.vertex do printf " %g %g %g\n",x,y,z;
}


## BREAK

Command syntax for exiting loops. Syntax:
   BREAK

BREAK n

The first form exits the innermost current loop. The second form exits n loops. Note: Commands with repetition counts do not qualify as loops. Example:
   foreach vertex do { print x; if y < 0 then break; print z }


## CONTINUE

Command syntax for skipping the rest of the body of the current loop, and going to the next iteration of the loop.
   CONTINUE

CONTINUE n

The second form exits the innermost n-1 loops, and skips to the loop control of the nth innermost loop. Note: Commands with repetition counts do not qualify as loops. Example:
   foreach vertex vv do {
foreach vv.edge do {
print length; if length < .4 then continue 2;
}
}


## RETURN

Command syntax for exiting the current command. This is essentially a return from a subroutine. If the current command is a user-defined command called by another command, the parent command continues. Example:
  if ( acc < 1.e-10 ) then return;


## Element generators

One feature different from ordinary C is the presence of generators of sets of geometric elements. These occur wherever an element type (vertices, edges, facets, bodies, singular or plural) appears in a command. Attributes of the iteration element may be used later in the command. The general form of a generator is
  elementgen name where expr

elementgen may be
• a multiple element generator, which can be
• an element type, vertex, edge, facet, or body, which generates all elements of that type in the surface. But new elements created during a loop will not be generated, so "refine edges" will refine all existing edges just once.
• a single element subelement. The implemented subelements are:
• of a vertex: edge, facet (in no particular order)
• of an edge: vertex (in tail, head order), facet (in geometric order)
• of a facet: vertex, edge, body (all in order around the facet)
• of a body: facet (in no particular order)
• a single element, which can be
• an element name of an active generator
• an indexed multiple element (may generate nothing if no element of that index). Indexing starts at 1.
name is an optional identifier which can be used in the body of a loop to refer to the generated element. expr is interpreted as a boolean expression, 0 for false, nonzero for true. Only elements for which expr is true are generated. The where expr clause is optional. The innermost generator generates a default element, which can have its attributes referred to just by attribute name. But be sure to remember that in a nested iteration, an unqualified element type generates all elements of that type, not just those associated with the parent element. Examples:
   list facet where color == red

foreach edge ee where ee.length < .3 do list ee.vertex

print facet[2].edge[1].vertex[2].id

foreach facet ff do { printf "facet %g:\n"; list ff.edge }

print max(edge where on_constraint 1, length)


## General commands

Many commands in the Evolver command language have a sentence-like structure and start with a verb.

## AREAWEED

Main prompt command. For deleting facets with less than a given area. Syntax:
   AREAWEED expr
Same as 'w' command, except does not need interactive response. Also same as "delete facets where area < expr". Examples:
   areaweed 0.001
areaweed 2*min(facet,area)


## CHDIR

Main prompt command. Changes the current directory, used for searching for files before EVOLVERPATH is used. Syntax:
   CHDIR stringexpr
In MS-Windows, use a front slash '/' or a double backslash '\\' instead of a single backslash as the path character. Example:
  chdir "/usr/smith/project"


## CLOSE_SHOW

Main prompt command. Closes the native graphics window started by the s' or SHOW commands. Does not affect geomview or OpenGL version. Synonym: show_off.

## DEFINE

Main prompt command. For defining extra attributes of elements. Syntax:
 DEFINE elementtype ATTRIBUTE name  REAL|INTEGER [dim]

where elementtype is vertex, edge, facet, or body; name is an identifier of your choice; and [dim] is an optional expression for the vector dimension (with the brackets). There is no practical distinction between real and integer types at the moment, since everything is stored internally as reals. But there may be more datatypes added in the future. It is not an error to redefine an attribute that already exists, as long as the definition is the same. Extra attributes are inherited by elements of the same type generated by subdivision. Examples:
  define edge attribute charlie real
define vertex attribute oldx real[3]

It is also possible to use DEFINE to declare a variable without giving it an initial value. This is primarily a mechanism to be sure a variable is defined before use, without overwriting an existing value. If the variable is new, the initial value is zero or the null string. Syntax:
    DEFINE name  REAL|INTEGER|STRING}


## DELETE

Main prompt command. For collapsing edges or facets. Syntax:
   DELETE  generator

Deletes edges by shrinking the edge to zero length (as in the tiny edge weed command t) and facets by eliminating one edge of the facet. Facet edges will be tried for elimination in shortest to longest order. Edges will not be deleted if both endpoints are fixed, or both endpoints have different constraints or boundaries from the edge. DELETE maintains the continuity and connectedness of the surface, as opposed to DISSOLVE. Example:
      delete facets where area < 0.0001


## DIRICHLET

Main prompt command. Does one iteration of minimizing the Dirichlet integral of the surface. The current surface is the domain, and the Dirichlet integral is of the map from the current surface to the next. This is according to a scheme of Konrad Polthier and Ulrich Pinkall [PP]. At minimum Dirichlet integral, the area is minimized also. Works only on area with fixed boundary; no volume constraints or anything else. Seems to converge very slowly near minimum, so not a substitute for other iteration methods. But if you have just a simple soap film far, far from the minimum, then this method can make a big first step. DIRICHLET_SEEK will do an energy-minimizing search in the direction.

## DIRICHLET_SEEK

Main prompt command. Calculates a motion as in the DIRICHLET command, but uses this as a direction of motion instead of as the motion itself. DIRICHLET_SEEK then uses a line-search along this direction to find a minimum of energy.

## DISSOLVE

Main prompt command. Removes elements from the surface without closing the gap left. Syntax:
  DISSOLVE  generator

The effect is the same as if the line for the element were erased from a datafile. Hence no element will be dissolved that is used by a higher dimensional element. (There are two exceptions: dissolving an edge on a facet in the string model, and dissolving a facet on a body in the soapfilm model.) Thus "dissolve edges; dissolve vertices" is safe because only unused edges and vertices will be dissolved. No error messages are generated by doing this. Good for poking holes in a surface. Example:
  dissolve facets where original == 2;
dissolve edges; dissolve vertices

Thus "dissolve edges; dissolve vertices" is safe because only unused edges and vertices will be dissolved. No error messages are generated by doing this.

## DUMP

Main prompt command. Dumps current surface to named file in datafile format. Syntax:
  DUMP filename

The filename is a string. With no filename, dumps to the default dump file, which is the current datafile name with ".dmp" extension. Same as the 'd' command, except 'd' requires a response from the user for the filename. Examples:
   dump "foo.dmp"
dump sprintf "%s.%g.dmp",datafilename,counter


## EDGESWAP

Main prompt command. For changing the endpoints of edges. Syntax:
 EDGESWAP edgegenerator

If any of the qualifying edges are diagonals of quadrilaterals, they are flipped in the same way as in equiangulation, regardless of whether equiangularity is improved. "edgeswap edge" will try to swap all edges, and is not recommended, unless you like weird things. Various conditions will prevent an edge from being swapped:
• The edge is fixed.
• There are not exactly two facets adjacent to the edge.
• The adjacent facets do not have equal density.
• The adjacent facets are not on the same level set constraints as the edge.
• The adjacent facets are not on the same parametric boundary as the edge.
• Swapping would create an edge with both endpoints the same (a loop).
• Swapping would create two edges with the same endpoints (an "ear").
All but the first two reasons print messages. This is a compromise between informing the user why edges were not switched and preventing a cascade of messages. When edge swapping is invoked through the 'u' command, none of these messages are printed. Examples:
 edgeswap edge[22]

edgeswap edge where color == red


## EDGEWEED

Main prompt command. Deletes edges shorter than given value. Syntax:
 EDGEWEED expr

Same as 't' command, except does not need interactive response. Same as "delete edge where length < expr".

## EIGENPROBE

Main prompt command. For finding the number of eigenvalues of the energy Hessian that are less than, equal to, and greater than a given value. Syntax:
EIGENPROBE expr
EIGENPROBE(expr,expr)

The first form prints the number of eigenvalues of the energy Hessian that are less than, equal to, and greater than expr. It is OK to use an exact eigenvalue (like 0, often) for the value, but not really recommended. Useful for probing stability. Second form will further do inverse power iteration to find an eigenvector. The second argument is the limit on the number of iterations. The eigenvalue will be stored in the last_eigenvalue internal variable, and the eigenvector can be used by the move command. The direction of the eigenvector is chosen to be downhill in energy, if the energy gradient is nonzero.

## FIX

Main prompt command. For setting the FIXED attribute of elements. Syntax:
   FIX generator

Example:
   fix vertices where on_constraint 2

Can also convert a parameter from optimizing to non-optimizing. Example:
  fix radius

Can also convert a named quantity from info_only to fixed. See also unfix.

## GEOMPIPE

Main prompt command. Redirects Evolver's geomview output to a command in place of sending it to geomview. Syntax:
   geompipe stringexpr

The redirection can be closed with the command "P 9". geompipe is useful for debugging geomview data; but be sure to toggle gv_binary OFF to get ascii data to look at.

## GEOMVIEW

Main prompt command. The plain form "geomview" toggles the geomview display on and off. The form
   geomview stringexpr

will send a command to an already started geomview. This string must be in the geomview command language, for which consult the geomview documentation.

## HELP

Main prompt command. For help on keywords, this command invokes a simple built-in HTML browser that prints out a section of Evolver HTML documentation, based on a keyword (i.e. HTML anchors). Please excuse the occasional ugliness in the translation of the HTML. For user-defined names, it prints some information. Syntax:
   help keyword

The keyword need not be in quotes, unless there are embedded blanks. After printing the help section exactly matching the keyword, a list of related terms is printed. These are just the keywords containing your keyword as a substring.

For help to work, the directory containing the Evolver HTML files must be in the EVOLVERPATH environment variable.

The built-in browser is in no way a complete substitute for using a full-fledged browser such as Netscape or Mosaic.

## HESSIAN

Main prompt command. Does one step using Newton's method with the Hessian matrix of the energy. If the Hessian is not positive definite, a warning will be printed, but the move will be made anyway. If the check_increase toggle is on, then no move will be made if it would increase energy. Hessian_seek will use a variable step size to seek minimum energy in the direction of motion. The motion vector is stored, and may be accessed with the move command. Not all energies and constraints have Hessian calculations yet. See the Hessian tutorial for more.

Main prompt command. Brings up a menu of experimental stuff involving the energy Hessian matrix. Not all of it works well, and may disappear in future versions. A one-line prompt with options appears. Use option '?' to get a fuller description of the choices. For those options that calculate an eigenvalue, the eigenvalue (or first, if several) is saved in the internal variable last_eigenvalue. A quick summary of the current options:
1. Fill in hessian matrix.
Allocation and calculation of Hessian matrix.
2. Fill in right side. (Do 1 first)
Calculates gradient and constraint values.
3. Solve. (Do 2 first)
Solves system for a motion direction.
4. Move. (Do 3, A, B, C, E, K, or L first)
Having a motion direction, this will move some stepsize in that direction. Will prompt for stepsize. The direction of motion is saved and is available in the move command.
7. Restore original coordinates.
Will undo any moves. So you can move without fear.
9. Toggle debugging. (Don't do this!)
Prints Hessian matrix and right side as they are calculated in other options. Produces copious output, and is meant for development only. Do NOT try this option.
B. Chebyshev (For Hessian solution ).
Chebyshev iteration to solve system. This option takes care of its own initialization, so you don't have to do steps 1 and 2 first. Not too useful.
C. Chebyshev (For most negative eigenvalue eigenvector).
Chebyshev iteration to find most negative eigenvalue and eigenvector. Will ask for number of iterations, and will prompt for further iterations. End by just saying 0 iterations. Prints Rayleigh quotient every 50 iterations. After finding an eigenpair, gives you the chance to find next lowest. Last eigenvector found becomes motion for step 4. Self initializing. Not too useful.
E. Lowest eigenvalue. (By factoring. Do 1 first)
Uses factoring to probe the inertia of the shifted Hessian H-cI until it has the lowest eigenvalue located within .01. Then uses inverse iteration to find eigenpair.
F. Lowest eigenvalue. (By conjugate gradient. Do 1 first)
Uses conjugate gradient to minimize the Rayleigh quotient.
L. Lanczos. (Finds eigenvalues near probe value. )
Uses Lanczos method to solve for 15 eigenvalues near the probe value left over from menu choices 'P' or 'V'. These are approximate eigenvalues, but the first one is usually very accurate. Do not trust apparent multiplicities. From the main command prompt, you can use the lanczos command.
R. Lanczos with selective reorthogonalization.
Same as 'L', but a little more elaborate to cut down on spurious multiplicities by saving some vectors to reorthogonalize the Lanczos vectors. Not quite the same as the official "selective reorthogonalization" found in textbooks.
Z. Ritz subspace iteration for eigenvalues. (Do 1 first)
Calculate a number of eigenpairs near a probe value. Will prompt for probe value and number of eigenpairs. Same as ritz main command. Can be interrupted gracefully by keyboard interrupt. Afterwards, one can use the X option to pick a particular eigenvector to look at.
X. Pick Ritz vector for motion. (Do Z first)
Selects an eigenvector calculated by the Z option for use in motion (option 4). First eigenvalue listed is number 1, etc. Particularly useful for discriminating among high multiplicity eigenvalues, which the V option does not let you do.
P. Eigenvalue probe. (By factoring. Do 1 first)
Reports the inertia of the shifted Hessian H-cI for user-supplied values of the shift c. The Hessian H includes the effects of constraints. Will prompt repeatedly for c. Null response exits. From the main command prompt, you can use the eigenprobe command.
V. Eigenvalue probe with eigenvector. (By factoring. Do 1 first)
Reports the inertia of the shifted Hessian H-cI for user-supplied values of the shift c, and calculates the eigenvector for the eigenvalue nearest c by inverse power iteration. You will be prompted for c and for the maximum number of iterations to do. From the main command prompt, you can use the eigenprobe command.
S. Seek along direction. (Do 3, A, B, E, C, K, or L first)
Can do this instead of option 4 if you want Evolver to seek to lowest energy in an already found direction of motion. Uses the same line search algorithm as the optimizing g' command.
Y. Toggle YSMP/alternate minimal degree factoring.
Default Hessian factoring is by Yale Sparse Matrix Package. The alternate is a minimal degree factoring routine of my own devising that is a little more aware of the surface structure, and maybe more efficient. If YSMP gives problems, like running out of storage, try the alternate. This option is available at the main prompt as the ysmp toggle.
U. Toggle Bunch-Kaufman version of min deg.
YSMP is designed for positive definite matrices, since it doesn't do any pivoting or anything. The alternate minimal degree factoring method, though, has the option of handling negative diagonal elements in a special way. This option is available at the main prompt as the bunch_kaufman toggle.
M. Toggle projecting to global constraints in move.
Toggles projecting to global constraints, such as volume constraints. Default is ON. Don't mess with this. Actually, I don't remember why I put it in.
G. Toggle minimizing square gradient in seek.
For converging to unstable critical points. When this is on, option 'S' will minimize the square of the energy gradient rather than minimizing the energy. Also the regular saddle and hessian_seek commands will minimize square gradient instead of energy.
0. Exit hessian.
Exits the menu. q' also works.
For example, to inspect what eigenvectors look like, one would do steps 1 and z, then repeatedly use x to pick an eigenvector, 4 to move, and 7 to restore.

## HESSIAN_SEEK

Main prompt command. Seeks to minimize energy along the direction found by Newton's method using the Hessian. Otherwise same as the hessian command. Syntax:

HESSIAN_SEEK maxscale

where maxscale is an optional upper bound for the distance to seek. The default maxscale is 1, which corresponds to a plain hessian step. The seek will look both ways along the direction, and will test down to 1e-6 of the maxscale before giving up and returning a scale of 0. This command is meant to be used when the surface is far enough away from equilibrium that the plain hessian command is unreliable, as hessian_seek guarantees an energy decrease, if it moves at all.

## HISTOGRAM, LOGHISTOGRAM

Main prompt command. For printing histograms in text form to standard output. Syntax:
HISTOGRAM(generator, expr)
LOGHISTOGRAM(generator, expr)

Prints a histogram of the values of expr for the generated elements. It uses 20 bins evenly divided between minimum and maximum values. It finds its own maximum and minimum values, so the user does not have to specify binsize. The log version will lump all zero and negative values into one bin. Examples:
 histogram(edge,dihedral*180/pi)
loghistogram(facet where color == red, area)
histogram(vertex where on_constraint 1, sqrt(x^2+y^2+z^2))


## HISTORY

Main prompt command. Print the saved history list of commands.

## LAGRANGE

Main prompt command. Changes to Lagrange model from quadratic or linear models. Syntax:
LAGRANGE n

where n is the lagrange_order, which is between 1 and some built-in maximum (currently 8). This command can also convert between Lagrange models of different orders. Note that lagrange 1 gives the Lagrange model of order 1, which has a different internal representation than the linear model. Likewise, lagrange 2 does not give the quadratic model.

## LANCZOS

Main prompt command. For finding eigenvalues of the energy Hessian near a given value. Syntax:
   LANCZOS expr

LANCZOS (expr,expr)

Does a little Lanczos algorithm and reports the nearest approximate eigenvalues to the given probe value. In the first form, expr is the probe value, and 15 eigenvalues are found. In the second form, the first argument is the probe value, the second is the number of eigenvalues desired. The output begins with the number of eigenvalues less than, equal to, and greater than the probe value. Then come the eigenvalues in distance order from the probe. Not real polished yet. Beware that multiplicities reported can be inaccurate. The eigenvalue nearest the probe value is usually very accurate, but others can be misleading due to incomplete convergence. Since the algorithm starts with a random vector, running it twice can give an idea of its accuracy.

## LINEAR

Main prompt command. Changes to linear model from quadratic or Lagrange models.

## LIST

Main prompt command. List elements on the screen in the same format as in the datafile. Syntax:
   LIST  generator

On unix systems, piping to more can be used for long displays. Examples:
   list edges where id <= 12
list vertices | "more"
list vertices where x < 1 and y > 2 and z >= 3  | "tee vfile"


## LIST ATTRIBUTES

Prints a list of the "extra attributes" of each type of element. Besides user-defined extra attributes, this list also contains the predefined attributes that make use of the extra attribute mechanism (being of variable size), such as coordinates, parameters, forces, and velocities. It does not list permanent, fixed-size attributes such as color or fixedness, or possible attributes that are not used at all.

## LIST BOTTOMINFO

Main prompt command. Prints what would be dumped in the "read" section at the end of a dumpfile: command definitions and various toggle states.

## LIST PROCEDURES

Main prompt command. Prints definitions of all current user-defined commands, same as at the end of a dump file.

## LIST TOPINFO

Main prompt command. Prints the first section of the datafile on the screen. This is everything before the vertices section.

Main prompt command. For loading a new surface. Syntax:
LOAD filename

Terminates the current surface and loads a new datafile. The filename is the datafile name, and can be either a quoted string or a string variable. This completely re-initializes everything, including the command interpreter. In particular, the currently executing command ends. Useful only as the last command in a script.

## LOGFILE

Main prompt command. Syntax:
LOGFILE stringexpr

Starts recording all input and output to the file specified by stringexpr, which must be a quoted string or a string variable or expression. Appends to an existing file. To end logging, use logfile off.

## METIS, KMETIS

Main prompt command. Partitions facets (edges in string model) into n parts using the METIS library of Karypis and Kumar, if this library has been compiled into the Evolver (not part of the public distribution yet). Meant for experiments in partitioning the surface for multiprocessors. Partition number of facet left in extra attribute fpart (epart for string model). METIS uses the PMETIS algorithm, KMETIS uses the KMETIS algorithm. Syntax:
  METIS n
KMETIS n


## LONGJ

Main prompt command. For perturbing the surface. This does a "long jiggle", which provides long wavelength perturbations that can test a surface for stability. The parameters are a wavevector, a phase, and a vector amplitude. The user will be prompted for values. Numbers for vectors should be entered separated by blanks, not commas. An empty reply will accept the defaults. A reply of r will generate random values. Any other will exit the command without doing a jiggle. In the random cases, a random amplitude $\vec A$ and a random wavelength $\vec L$ are chosen from a sphere whose radius is the size of the object. The wavelength is inverted to a wavevector $\vec w$. A random phase $\psi$ is picked. Then each vertex $\vec v$ is moved by $\vec A\sin(\vec v \cdot \vec w + \psi)$. This command is archaic. More control over perturbations may be had with the "set vertex x ..." type of command.

## MOVE

Main prompt command. For moving along the current direction of motion. Syntax:
  MOVE expr

Moves the surface along the previous direction of motion by the stepsize given by expr. The previous direction can be either from a gradient step (g command) or a hessian step (hessian, saddle, hessian_seek, hessian_menu option 4, etc.). The stepsize does not affect the current scale factor. A negative step is not a perfect undo, since it cannot undo projections to constraints. "Move" sometimes does not work well with optimizing parameters and hessian together.

## NEW_VERTEX

Main prompt command. For creating a new vertex. The syntax is that of a function instead of a verb, since it returns the id number of the new vertex. The arguments are the coordinates of the vertex. The new vertex is not connected to anything else; use the new_edge command to connect it. Syntax:
  newid := NEW_VERTEX(expr, expr,...)

Examples:
  newid := new_vertex(0,0,1)
newid := new_vertex(pi/2,0,max(vertex,x))


## NEW_EDGE

Main prompt command. For creating a new edge. The syntax is that of a function instead of a verb, since it returns the id number of the new edge. The arguments are the id's of the tail and head vertices. Syntax:
  newid := NEW_EDGE(expr, expr)

The new edge has the same default properties as if it had been created in the datafile with no attributes, so you will need to explicitly add any attributes you want. Example to create a set of coordinate axes in 3D:
  newv1 := new_vertex(0,0,0); fix vertex[newv1];
newv2 := new_vertex(1,0,0); fix vertex[newv2];
newv3 := new_vertex(0,1,0); fix vertex[newv3];
newv4 := new_vertex(0,0,1); fix vertex[newv4];
newe1 := new_edge(newv1,newv2); fix edge[newe1];
newe2 := new_edge(newv1,newv3); fix edge[newe2];
newe3 := new_edge(newv1,newv4); fix edge[newe3];
set edge[newe1] no_refine; set edge[newe1] bare;
set edge[newe2] no_refine; set edge[newe2] bare;
set edge[newe3] no_refine; set edge[newe3] bare;


## NEW_FACET

Main prompt command. For creating a new facet. The syntax is that of a function instead of a verb, since it returns the id number of the new edge. The arguments are the oriented id's of the edges around the boundary of the facet, in the same manner that a face is defined in the datafile. The number of edges is arbitrary, and they need not form a closed loop in the string model. In the soapfilm model, if more than three edges are given, the new face will be triangulated by insertion of a central vertex. In that case, the returned value will be the original attribute of the new facets. In the simplex model, the arguments are the id's of the facet vertices. Syntax:
  newid := NEW_FACET(expr, expr,...)

The new facet has the same default properties as if it had been created in the datafile with no attributes, so you will need to explicitly add any attributes you want. Example:
  newf := new_facet(1,2,-3,-4); fix facet where original == newf;


## NEW_BODY

Main prompt command. For creating a new body. The syntax is that of a function instead of a verb, since it returns the id number of the new body. There are no arguments. Syntax:
  newid := NEW_BODY

The body is created with no facets. Use the set facet frontbody and set facet backbody commands to install the body's facets. The new body has the same default properties as if it had been created in the datafile with no attributes, so you will need to explicitly add any attributes you want, such as density or target volume. Example:
  newb := new_body
set facet frontbody newb where color == red


## NOTCH

Main prompt command. For refining a surface in regions of high curvature. Syntax:
 NOTCH expr

Notches all edges with dihedral angle greater than given value. Same as 'n' command, or
   foreach edge ee where ee.dihedral > expr do refine ee.facet

Notching is done by adding a vertex in the middle of adjacent facets. Should be followed by equiangulation.

## OMETIS

Main prompt command. Computes an ordering for Hessian factoring using the METIS library of Karypis and Kumar, if this library has been compiled into the Evolver (not part of the public distribution yet). Prints ordering tree. To actually use METIS ordering during factoring, use the toggle metis_factor. Syntax:
  OMETIS n  // n is smallest partition size
OMETIS           // defaults to n = 100


## OPTIMIZE

Main prompt command. Set gradient descent iteration to optimizing mode, with an upper bound on the scale factor. "Optimise" is a synonym. Syntax:
  OPTIMIZE expr


## PAUSE

Main prompt command. Pauses execution until the user hits RETURN. Useful in scripts to give the user a chance to look at some output before proceeding.

## POSTSCRIPT

Main prompt command. Creates a PostScript file of the current surface in a file. Syntax:
  POSTSCRIPT stringexpr 
The string gives the name of the file; a .ps extension will be appended if it is missing. It is the same as the P option 3 command, except that there are no interactive responses needed. Output options are controlled by the pscolorflag, gridflag, crossingflag, and labelflag toggles.

## PRINT

Main prompt command. For printing expression values, strings, and commands. Syntax:
PRINT expr
PRINT stringexpr
PRINT commandname

PRINT expr can also be used inside an expression, where it prints the expression and evaluates to the value of its expression. Examples:
  print datafilename
print max(edge,length)
print max(vertex, print (x^2+y^2+z^2) )
gg := {list vertex where id < 10; g 5}
print gg


## PRINTF

Main prompt command. For printing formatted output. Syntax:
PRINTF string,expr,expr,...

Prints to standard output using the standard C sprintf function. Only string and real-valued numeric expressions are valid, so the format string should use only %s, %f and %g formats. Do not use %d format for things like element id's, because these are automatically converted to reals in expressions; use %g to print integral values. The format string can be a string variable or a quoted string. Example:
  printf "This is %s with total energy %f\n",datafilename,total_energy


Main prompt command. Changes to quadratic model from linear or Lagrange models.

## QUIT, BYE, EXIT

Main prompt command. Exits Evolver or starts new datafile. Same as q' command.

## RAWESTV

Main prompt command. Does vertex averaging for all vertices without regard for conserving volume or whether averaged vertices have like constraints. But doesn't move vertices on boundaries. To do a selected group of vertices, use rawest_vertex_average.

## RAWEST_VERTEX_AVERAGEV

Main prompt command. Does vertex averaging on selected vertices without conserving volume on each side of surface, or attention to being on like constraints. Doesn't move vertices on boundaries. Using the verbose toggle will print messages. Syntax:
RAWEST_VERTEX_AVERAGE generator

Example:
rawest_vertex_average vertex[3]


## RAWV

Main prompt command. Does vertex averaging for all vertices without conserving volume on each side of surface. Will only average vertices with those of like type of constraints. Doesn't move vertices on boundaries. To do a selected group of vertices, use raw_vertex_average.

## RAW_VERTEX_AVERAGE

Main prompt command. Does vertex averaging on selected vertices without conserving volume on each side of surface. Will only average vertices with those of like type of constraints. Doesn't move vertices on boundaries. Using the verbose toggle will print messages. Syntax:
RAW_VERTEX_AVERAGE generator

Example:
raw_vertex_average vertex where valence == 6


Main prompt command. For reading commands from a file. Syntax:
READ filename

The filename can be either a quoted string or a string variable. The effect is as if the file were typed in at the keyboard. Hence main commands, responses to commands, and graphics mode commands can be included. Read commands may be nested. On the occurence of an error, input reverts to the original standard input. Example:
   read "zebra.cmd"


## REBODY

Main prompt command. Recalculates connected bodies. Useful after a body has been disconnected by a neck pinching off. Facets of an old body are divided into edge-connected sets, and each set defines a new body (one of which gets the old body id). The new bodies inherit the attributes of the old body. If the original body volume was fixed, then the new bodies' target volumes become the new actual volumes. If the original body had a volconst, the new bodies will inherit the same value. This will likely lead to incorrect values, so you will have to adjust the volconsts by hand. In commands, you may specify the new bodies descended from an original body by using the 'original' atttribute.

## RECALC

Main prompt command. Recalculates and redisplays everything. Useful after changing some variable or something and recalculation is not automatically done. Evolver tries to automatically recalculate when some significant change is made, but doesn't always know. Also see autorecalc.

## REFINE

Main prompt command. For subdividing sets of edges or facets. Syntax:
REFINE generator

Subdivides the generated edges or facets. Subdivides edges by putting a vertex in the middle of each edge, and splitting neighboring facets in two in the soapfilm model. It is the same action as the long edge subdivide command (command l). Facets will be subdivided by putting a vertex in the center and creating edges out to the old vertices. It is strongly suggested that you follow this with equiangulation to nicen up the triangulation. Edge refinement is better than facet refinement as facet refinement can leave long edges even after equiangulation. Example:
       refine edges where not fixed and length > .1


## RITZ

Main prompt command. For finding eigenvalues of the energy Hessian near a given value. Syntax:
RITZ(expr,expr)

Applies powers of inverse shifted Hessian to a random subspace to calculate eigenvalues near the shift value. First argument is the shift. Second argument is the dimension of the subspace. Prints out eigenvalues as they converge to machine accuracy. The first eigenvalue is subsequently available in the last_eigenvalue internal variable. This may happen slowly, so you can interrupt it by hitting whatever your interrupt key is, such as CTRL-C, and the current values of the remaining eigenvalues will be printed out. Good for examining multiplicities of eigenvalues. It is legal to shift to an exact eigenvalue, but not wise, as they will not be printed. See the Hessian tutorial for more. Example: To get the lowest 5 eigenvalues of a Hessian you know is positive definite:
   ritz(0,5)


## RENUMBER_ALL

Reassigns element id numbers of all types of elements in accordance with order in storage, i.e. as printed with the LIST commands. Besides renumbering after massive topology changes, this can be used with the reorder_storage command to number elements as you desire. Do NOT use this command inside an element generator loop!

## REORDER_STORAGE

Reorders the storage of element data structures, sorted by the extra attributes vertex_order_key, edge_order_key, facet_order_key, body_order_key, and facetedge_order_key. Originally written for testing dependence of execution speed on storage ordering, but could be useful for other purposes, particularly when renumber_all is used afterwards. Example:
   define vertex attribute vertex_order_key real
define edge attribute edge_order_key real
define facet attribute facet_order_key real
define body attribute body_order_key real
define facetedge attribute facetedge_order_key real

reorder := {
set vertex vertex_order_key x+y+z;
set edge ee edge_order_key min(ee.vertex,vertex_order_key);
set facetedge fe facetedge_order_key fe.edge[1].edge_order_key;
set facet ff facet_order_key min(ff.vertex,vertex_order_key);
set body bb body_order_key min(bb.facet,facet_order_key);
reorder_storage;
}


Main prompt command. Seek to minimum energy along the eigenvector of the lowest negative eigenvalue of the Hessian. If there is no negative eigenvalue, then the surface is unchanged. The alternate form
SADDLE expr

will limit the step size to expr. The motion vector is available afterwards through the move command.

## SET

Main prompt command. For setting element attributes to values. Syntax:
 SET elementtype [name] attrib expr1 where expr2

SET elementtype.attrib expr1 where expr2

SET name attrib expr

SET name.attrib expr

SET quantityname attrib expr

SET instancename attrib expr


The first two forms set the value of the attribute attrib to the value expr1 for all elements of the given type that satisfy expr2. elementtype can be vertex, edge, facet, or body, or any element generator without a where clause. The optional name refers to the element under consideration, and can be used in expr1 and expr2 to refer to attributes of that element. Even without name, attributes of the element can be referred to if the references are not nested in element generators in expr1 or expr2. The next two forms can be used inside an element generator which defines name. When name is not used, a '.' can be used, for those who like that sort of thing. SET can change the following attributes: constraint, coordinates, density, orientation, non-global named quantity or named method, user-defined extra attributes, body target volume, body volconst, fixed, frontbody, backbody, pressure, color, frontcolor, backcolor, and opacity (for the appropriate type elements). Fixed, named quantity, and named method attributes are just toggled on; they do not need the first expr. For constraint, the expr is the constraint number. Examples:
  set facets density 0.3 where original == 2
set vertices x 3*x where id < 5  // multiplies x coordinate by 3
set body target 5 where id == 1   // sets body 1 target volume to 5
set vertices constraint 1 where id == 4
set facet color clear where original < 5
foreach facet ff do set ff color red
define vertex attribute weight real; set vertex weight 3
set vertex quantity my_quantity
set vertex[1].facet color red

Note the first form of syntax has the attribute and new value in the middle of an element generator. Syntactically inconsistent with other commands that use element generators, but more natural English. Actually, the syntactically consistent
set facet where id < 5 color red
does work.

The last two forms set the value of a named quantity or named method instance attribute. For a named quantity, the settable attributes are target, modulus, volconst, and tolerance. For a named method instance, only modulus. There is no implicit reference to the quantity in the expression, so say

   set myquant target myquant.value

rather than set myquant target value. Also see unset.

## SHELL

Main prompt command. Invokes a system subshell for the user on systems where this is possible. No arguments. See the system command for execution of an explicit shell command.

## SHOW

Main prompt command. Which edges and facets are actually shown in graphics displays can be controlled by defining boolean expressions that edges or facets must satisfy in order to be passed to the graphics display. There are two expressions inernally: one for edges and one for facets. They may be set with the syntax
   show edges where expr

show facets where expr

The default is to show all facets, and to show all special edges: fixed edges, constraint edges, boundary edges, and edges without exactly two adjacent facets. The defaults can be restored with "show facets" and "show edges". Some graphics modules (like geomview) can show edges of facets on their own initiative. This is separate from the edge show criterion here; to show the colors of edges, the edges must satisfy the criterion. Show causes graphics to be redrawn. If a graphics display is not active, show will start screen graphics. Show_expr is the same as show in setting the show expressions, except it does not start graphics. Show alone will just start screen graphics. Examples:
 show facets where color == red
show edges where 1
show edges where color != black


## SHOW_EXPR

Main prompt command. This does the same as show, except it does not start or redraw graphics; it just sets a show expression. Good for use in the read section of the datafile for controlling which elements will be displayed without automatically starting a display.

## SHOW_TRANS

Main prompt command. Applies string of graphics commands to the image transformation matrix without doing any graphic display. The string must be in double quotes or be a string variable, and is the same format as is accepted by the regular graphics command prompt. Example:
  show_trans "rrdd5z"


## SHOWQ

Main prompt command. Displays screen graphics, but returns immediately to the main prompt and does not go into graphics command mode.

## SOBOLEV

Main prompt command. Uses a positive definite approximation to the area Hessian to do one Newton iteration, following a scheme due to Renka and Neuberger [RN]. Works only on area with fixed boundary; no volume constraints or anything else. Seems to converge very slowly near minimum, so not a substitute for other iteration methods. But if you have just a simple soap film far, far from the minimum, then this method can make a big first step. SOBOLEV_SEEK will do an energy-minimizing search in the direction.

## SPRINTF

Main prompt command. Prints to a string using the standard C sprintf function. May be used whereever a stringexpr is called for in syntax. Otherwise same as printf. Syntax:
SPRINTF stringexpr,expr,expr,...

Example:
   dumpname := SPRINTF "file%04g.dmp",counter


## SYSTEM

Main prompt command. For executing a program. Syntax:
  SYSTEM stringexpr

Invokes a subshell to execute the given command, on systems where this is possible. Command must be a quoted string or a string variable. Will wait for command to finish before resuming.

## TRANSFORM_DEPTH

Main prompt command. Quick way of generating all possible view transforms from view transform generators, to a given depth n. Syntax:
  TRANSFORM_DEPTH n

where n is the maximum number of generators to multiply together. This will toggle immediate showing of transforms, if they are not already being shown.

## TRANSFORM_EXPR

Main prompt command. If view transform generators were included in the datafile, then a set of view transforms may be generated by an expression with syntax much like a regular expression. An expression generates a set of transform matrices, and are compounded by the following rules. Here a lower-case letter stands for one of the generators, and an upper-case letter for an expression.
 a Generates set {I,a}. AB Generates all ordered products of pairs from A and B. nA Generates all n-fold ordered products. A|B Generates union of sets A and B. (A) Grouping; generates same set as A.
The precedence order is that nA is higher than AB which is higher than A|B. Note that the expression string must be enclosed in double quotes or be a string variable. Examples:
  transform_expr "3(a|b|c)"    //all products of 3 or fewer generators
transform_expr "abcd"  // generates 16 transforms

All duplicate transforms are removed, so the growth of the sets does not get out of hand. Note the identity transform is always included. The letter denoting a single generator may be upper or lower case. The order of generators is the same as in the datafile. In the torus model, transforms along the three period vectors are always added to the end of the list of generators given in the datafile. If 26 generators are not enough for somebody, let me know. The current value of the expression may be accessed as a string variable, and the number of transformations generated can be accessed as transform_count. For example,
  print transform_expr
print transform_count


## UNFIX

Main prompt command. Removes the FIXED attribute from a set of elements. Syntax:
 UNFIX generator

Example:
  unfix vertices where on_constraint 2

Can also convert a parameter from non-optimizing to optimizing. Example:
  unfix radius

Can also convert a named quantity from fixed to info_only.

## UNSET

Main prompt command. Removes an attribute from a set of elements. Syntax:
UNSET elements [name] attrib where clause

Unsettable attributes are fixed (vertices, edges, or facets) , body target volume, body pressure, body gravitational density, non-global named quantities, non-global named methods, level-set constraints, parametric boundary. frontbody, or backbody. A use for the last is to use a boundary or constraint to define an initial curve or surface, refine to get a decent triangulation, then use "unset vertices boundary 1" and "unset edges boundary 1" to free the curve or surface to evolve. The form "unset facet bodies ..." is also available to disassociate given facets from their bodies. Examples:
   unset body[1] target
unset vertices constraint 1; unset edges constraint 1


## VERTEX_AVERAGE

Main prompt command. Does vertex averaging for one vertex at a time. Syntax:
  VERTEX_AVERAGE vertex_generator

The action is the same as the V command, except that each new vertex position is calculated sequentially, instead of simultaneously, and an arbitrary subset of vertices may be specified. Fixed vertices do not move. Examples:
  vertex_average vertex[2]
vertex_average vertex where id < 10
vertex_average vertex vv where max(vv.facet,color==red) == 1


## WRAP_VERTEX

Main prompt command. Syntax:
 wrap_vertex(vexpr,wexpr)

In a symmetry group model, transforms the coordinates of vertex number vexpr by symmetry group element wexpr and adjusts wraps of adjacent edges accordingly.

## ZOOM

Main prompt command. For isolating a region of a surface. Syntax:
 ZOOM integer expr

Zooms in on vertex whose id is the given integer, with radius the given expr. Same as the 'Z' command, but not interactive.