Surface Evolver Documentation: commands

# Surface Evolver Documentation

Back to top of Surface Evolver documentation. Index.

# Surface Evolver command language

The Surface Evolver has an interactive command language. It has variables, expressions, subroutines, conditionals,iteration constructs, subroutines and functions with arguments, local variables, and arrays. But not structures or objects or pointers. 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.

Command input Command separator Compound commands Command repetition User-defined commands User-defined procedures User-defined functions Assignment commands Permanent assignment commands | Local scope 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:

- Single letter commands that don't have optional arguments (`K,k,l,t,j,m,n,p,w,y,P,M,G` have optional arguments),
- Compound commands in braces,
- User-defined command names.
- Redefined single-letter commands.

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, Ex: `gogo := {g 100; r; g 100}`
- User-defined variables, Ex: `foo := 2.3`
- Writable internal variables, Ex: `scale := 0.1`
- Named quantity modulus, target, and volconst. Syntax:

         quantityname.modulus := expr
         quantityname.target := expr
         quantityname.volconst := expr

- Method instance modulus. Syntax:

         instancename.modulus := expr

## Permanent assignment commands

The permanent assignment operator `::=` can be used to make assignments to variables and commands that are not forgotten when a new datafile is loaded. Such a command may only make reference to permanent variables, permanent commands, and internal variables. See permload command for an example of use.

## 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 and strongly advised 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}

## User-defined procedures

Users may define their own procedures with arguments with the syntax

       procedure identifier ( type arg1, type arg2, ... )
       { commands }

Right now the implemented types for arguments are `real` and `integer`. The argument list can be empty. Example:

       procedure proc1 ( real ht, real wd )
       {
         prod := ht*wd;   // this would make prod a global variable
         return;
       }

Note that the procedure arguments act as local variables, i.e. their scope is the procedure body, and they have stack storage so procedures may be recursive. Procedure prototypes may be used to declare procedures before their bodies are defined with the same syntax, just replacing the body of the procedure with a semicolon. Prototype syntax:

       procedure identifier ( type arg1, type arg2, ... );

Note that a procedure is used as a command, and a function is used in a numerical expression.

## User-defined functions

Users may define their own functions that have arguments and return values with the syntax

       function type identifier ( type arg1, type arg2, ... )
       { commands }

Right now the implemented types for return value and arguments are `real` and `integer`. The argument list can be empty. The return value is given in a `return` expr statement. Example:

       function real func1 ( real ht, real wd )
       { local prod;
         prod := ht*wd;
         return prod;
       }

Note that the function arguments act as local variables, i.e. their scope is the function body, and they have stack storage so functions may be recursive. Function prototypes may be used to declare functions before their bodies are defined with the same syntax, just replacing the body of the function with a semicolon. Prototype syntax:

       function type identifier ( type arg1, type arg2, ... );

Note that a procedure is used as a command, and a function is used in a numerical expression.

## 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

## Local scope

The scope of a variable name may be restricted to a compound command block by declaring the name to be local. Example:

       do_stuff := {
         local inx;
         for ( inx := 1 ; inx < 5 ; inx += 1 )
         { local jnx;
           jnx := inx*2;
           print jnx;
         };
       }

Using local variables is good for avoiding pollution of global namespace and for writing recursive functions (storage space for locals is allocated on the runtime stack). Note that the local declaration is a scope declaration, not a type declaration. Also, it cannot be combined with initialization of the variable (yet), and there is one name per declaration. Function arguments also act as local variables.

## 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
- do ... while ....
- while .... do ...
- for
- foreach
- break
- continue
- return

## 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)

## FOR

This is the Evolver's version of the C language "for" construct. Syntax:

      FOR ( command1 ; expr ; commmand2 ) command3

The first command is the initialization command; note that it is a single command, rather than an expression as in C. If you want multiple commands in the initialization, use a compound command enclosed in curly braces. The middle expression is evaluated at the start of each loop iteration; if its value is true (i.e. nonzero) then the loop is executed; otherwise the flow of control passes to the command after command3. The command2 is executed at the end of each loop iteration; again, it is a single command. The body of the loop is the single command command3, often a compound] command. Note: Command3 should end with a semicolon, unless it is the if clause of an if-then statement. Examples:

       for ( inx := 1 ; inx < 3 ; inx += 1 )
          print facet[inx].area;
       for ( {inx := 1; factorial := 1; } ; inx < 7 ; inx += 1 )
       { factorial *= inx;
         printf "factorial %d is %d\n",inx,factorial;
       };

## 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 element type, `vertex, edge, facet, or body`. Indexing starts at 1. The index may be negative, in which case the generated element has negative orientation.
  - an indexed subelement of an element (error if no element of that index). Indexing starts at 1. The indexing is the same as the order produced by the foreach generator. Indexed subelements of an edge or facet follow the orientation of the edge or facet.

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 BODY_METIS CHDIR CLOSE_SHOW DEFINE DELETE DIRICHLET DIRICHLET_SEEK DISSOLVE DUMP EDGE_MERGE EDGESWAP EDGEWEED EQUIANGULATE EIGENPROBE ERRPRINTF EXEC EXPRINT FACET_MERGE FIX FLUSH_COUNTS GEOMPIPE GEOMVIEW HELP HESSIAN HESSIAN_MENU HESSIAN_SEEK HISTOGRAM HISTORY KMETIS LAGRANGE LANCZOS | LINEAR LIST LIST ATTRIBUTES LIST BOTTOMINFO LIST PROCEDURES LIST TOPINFO LOAD LONGJ METIS MOVE NEW_VERTEX NEW_EDGE NEW_FACET NEW_BODY NOTCH OMETIS OOGLFILE OPTIMIZE PAUSE PERMLOAD POP POP_EDGE_TO_TRI POP_QUAD_TO_QUAD POP_TRI_TO_EDGE POSTSCRIPT PRINT PRINTF QUADRATIC | QUIT RAWESTV RAWEST_VERTEX_AVERAGE RAWV RAW_VERTEX_AVERAGE READ REBODY RECALC REFINE RESET_COUNTS RITZ RENUMBER_ALL REORDER_STORAGE SADDLE SET SHELL SHOW SHOW_EXPR SHOWQ SOBOLEV SPRINTF SYSTEM T1_EDGESWAP UNFIX UNSET VALID_ELEMENT VERTEX_AVERAGE VERTEX_MERGE WRAP_VERTEX ZOOM

## 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)

## BODY_METIS

Main prompt command. Partitions the set of bodies into n parts using the METIS library of Karypis and Kumar, if this library has been compiled into the Evolver. The partition number of each body is left in its extra attribute bpart (which will be created if it does not already exist). BODY_METIS works only in the soapfilm model; for the string model, partition facets using metis or kmetis. BODY_METIS uses the PMETIS algorithm. Meant for experiments in partitioning the surface for multiprocessors. Syntax:

     BODY_METIS n

Example:

      body_metis 50;  // supposing we have thousands of bodies, say
      for each body bb do set bb.facet frontcolor (bb.bpart imod 15)+1;

## 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 version. Synonym: show_off.

## DEFINE

Main prompt command. For runtime defining of variables, arrays, level set constraints, boundaries, named quantities, named method instances, and extra attributes of elements. The syntax for defining single variables is

        DEFINE variable type

where type is `REAL`, `INTEGER`, or `STRING`. Note that this way of declaring a variable does not take an initial value; thus it is a way of making sure a variable is defined without overwriting an existing value of the variable. The syntax for defining arrays and extra attributes is the same as in the top of the datafile; for constraints, boundaries, named quantities, and method instances, it is the same as in the top of the datafile except the word "define" comes first. Multi-line definitions should be enclosed in brackets and terminated with a semicolon. Or they can be enclosed in quotes and fed to the exec command. Of course, using exec means the parser doesn't know about the define until the exec is executed, so you cannot use the defined item in commands until then. It is legal to re-define an existing array or array extra attribute with different dimensions (but the same number of dimensions); data will be preserved as best as possible in the resized array. An array may be given the dimension 0 to free its memory allocation. Examples:

      define fudge_factor real
      define pqlist real[imax][jmax]
      define edge attribute charlie real
      define vertex attribute oldx real[3]
      define facet attribute knots real[5][5][5]
      { define constraint frontcon formula z = 0
        energy:
        e1: -y/2
        e2:  x/2
        e3:  0; }
      exec "define boundary newboundary parameters 1
        x: sin(p1)
        y: cos(p1)
        z: 3"
      exec "define quantity qarea info_only method facet_area global"

## 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

## EDGE_MERGE

Main prompt command. Merges two edges into one in a side-by-side fashion. Meant for joining together surfaces that bump into each other. Should not be used on edges already connected by a facet, but merging edges that already have a common endpoint(s) is fine. Syntax:

      edge_merge(integer,integer)

Note the arguments are signed integer ids for the elements, not element generators. The tails of the edges are merged, and so are the heads. Orientation is important. Example:

       edge_merge(3,-12)

## 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.

## EQUIANGULATE

Main prompt command. This command tests the given edges to see if flipping them would improve equiangularity. It is the u command applied to a specified set of edges. It differs from the edgeswap command in that only edges that pass the test are flipped. Syntax:

      EQUIANGULATE edge_generator

Examples:

      equiangulate edge[3];
      equilangulate edge where color == red;

## ERRPRINTF

Main prompt command. Same as printf, except it sends its output to stderr instead of stdout. Useful in reporting error messages in scripts that have their output redirected to a file.

## EXEC

Main prompt command. Executes a command in string form. Good for runtime generation of commands. Syntax:

       EXEC stringexpr

Example:

       exec sprintf "define vertex attribute prop%d real",propnumber

## EXPRINT

Main prompt command. Prints the original input string defining a user-defined command, including comments. Syntax:

       EXPRINT commandname

Example:

    Enter command: aa := { print 5; /* this is a test */ }
    Enter command: exprint aa
     { print 5; /* this is a test */ }

## FACET_MERGE

Main prompt command. Merges two soapfilm-model facets into one in a side-by-side fashion. Meant for joining together surfaces that bump into each other. The pairs of vertices to be merged are selected in a way to minimize the distance between merged pairs subject to the orientations given, so there are three choices the algorithm has to choose from. It is legal to merge facets that already have some endpoints or edges merged. Syntax:

      facet_merge(integer,integer)

Note the syntax is a function taking signed integer facet id arguments, not element generators. IMPORTANT: The frontbody of the first facet should be equal to the backbody of the second (this includes having no body); this is the body that will be squeezed out when the facets are merged. If this is not true, then facet_merge will try flipping the facets orientations until it finds a legal match. Example:

       facet_merge(3,-12)

## 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.

## FLUSH_COUNTS

Main prompt command. Causes the printing of various internal counters that have become nonzero. The counters are: equi_count, edge_delete_count, facet_delete_count, edge_refine_count, facet_refine_count, notch_count, vertex_dissolve_count, edge_dissolve_count, facet_dissolve_count, body_dissolve_count, vertex_pop_count, edge_pop_count, facet_pop_count, pop_tri_to_edge_count, pop_edge_to_tri_count, pop_quad_to_quad_count, where_count, edgeswap_count, fix_count, unfix_count, t1_edgeswap_count, and notch_count. Normally, these counts are accumulated during the execution of a command and printed at the end of the command. Flush_counts can be used to display them at some point within a command. Flush_counts is usually followed by reset_counts, which resets all these counters to 0.

## 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.

## HESSIAN_MENU

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, or lists individual constraint, boundary, quantity, or method instance definitions. Syntax:

       LIST  generator
       LIST constraintname
       LIST CONSTRAINT constraintnumber
       LIST boundaryname
       LIST BOUNDARY boundarynumber
       LIST quantityname
       LIST instancename

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 facet[3]
       list facet[3].edges where on_constraint 1
       list facet[3].edge[2].vertex[1]
       list constraint 1

See also LIST ATTRIBUTES, LIST BOTTOMINFO, LIST PROCEDURES, and LIST TOPINFO.

## 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.

## LOAD

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. For loading a new surface and continuing with the current command, see permload. Wildcard matching is in effect on some systems (Windows, linux, maybe others), but be very careful when using wildcards since there can be unexpected matches.

## LOGFILE

Main prompt command. Syntax:

    LOGFILE stringexpr
    LOGFILE OFF

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`. To record just input keystrokes, use keylogfile.

## KEYLOGFILE

Main prompt command. Syntax:

    KEYLOGFILE stringexpr
    KEYLOGFILE OFF

Starts recording all input keystrokes 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 `keylogfile off`. To record both input and output, use logfile.

## METIS, KMETIS

Main prompt command. Partitions the set of 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. Meant for experiments in partitioning the surface for multiprocessors. The partition number of facet is left in the facet extra attribute fpart (edge epart for string model), which will be created if it does not already exist. METIS uses the PMETIS algorithm, KMETIS uses the KMETIS algorithm. Syntax:

      METIS n
      KMETIS n

Example:

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

      metis 20;
      set facet color (fpart imod 15) + 1;

    For partitioning bodies, see body_metis.

    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:
      newid1 := new_vertex(0,0,1)
      newid2 := 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 facet.  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.
    Note: ometis no longer works for Metis version 3 or later, since Metis
    does not return the tree any more.  But metis_factor still works.
    Syntax:

      OMETIS n  // n is smallest partition size
      OMETIS           // defaults to n = 100

    OOGLFILE
    Main prompt command.
    Writes a file containing OOGL-formatted graphics data for the surface as a
    POLY or CPOLY quad file.  This is a non-interactive version of the
    P 2 command.  Syntax:
     ooglfile stringexpr

    The string gets ".quad" appended to form the filename.
    This command does not ask any of the other questions the P 2 command
    asks; it uses the default values, or whatever the last responses were to
    the previous use of the interactive P 2 command. Good for use in
    scripts.  Example:
       ooglfilename := sprintf "frame%d",framecounter;
       ooglfile ooglfilename;
       framecounter += 1;

    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.

    PERMLOAD
    Main prompt command.
    Loads a new datafile and continues with the current command after the
    read section of the datafile finishes.  The filename is
    the datafile name, and can be either a quoted string or a string variable.
    Since the automatic re-initialization makes Evolver forget all non-permanent
    variables, care should be taken that the current command only uses
    permanently assigned variables (assigned with ::= ).  Useful for
    writing scripts that run a sequence of evolutions based on varying
    parameter values.  Using permload is a little tricky, since
    you don't want to be redefining your permanent commands and variables
    every time you reload the datafile, and your permanent command cannot
    refer directly to variables parameterizing the surface.  One way to do it
    is to read in commands from separate files.  For example, the catenoid
    of cat.fe has height controlled by the variable zmax.
     You could have
    a file permcat.cmd containing the overall series script command

      run_series ::= {
        for ( height ::= 0.5 ; height < 0.9 ; height ::= height + .05 )
        { permload "cat"; read "permcat.gogo"; }
      }

    and a file permcat.gogo containing the evolution commands

      u; zmax := height; recalc; r; g 10; r; g 10; hessian;
      printf "height: %f  area: %18.15f\n",height,total_area >> "permcat.out";

    Then at the Evolver command prompt,

      Enter command: read "permcat.cmd"
      Enter command: run_series

    For loading a new surface and not continuing with the current command,
    see load.
      Wildcard matching is in effect
    on some systems (Windows, linux, maybe others), but be very careful when
    using wildcards since there can be unexpected matches.

    POP
    Main prompt command.
    Pops an individual edge or vertex or set of edges or vertices,
    giving finer control than
    the universal popping of the
    O and o
     commands.  The specified vertices or edges are
    tested for not being minimal in the soap film sense. For vertices, this
    means having more than four triple edges adjacent; higher valence
    edges are automatically popped.  For edges, this means
    having more than three adjacent facets when not on constraints or
    otherwise restricted.  It tries to act properly on constrained edges
    also, but beware that my idea of proper behavior may be different from
    yours.  Normally, popping puts in new edges and facets to keep originally
    separated regions separate, but that behavior can be changed with the
    pop_disjoin toggle.  The style
    of popping a cone over a triangular prism can be controlled with
    the pop_to_edge
    and pop_to_face commands.
     Examples:

       pop edge[2]
       pop edge where valence==5

    POP_EDGE_TO_TRI
    Main prompt command.
     This command does a particular topological transformation common in
    three-dimensional foam evolution.  An edge with tetrahedral point endpoints
    is transformed to a single facet.  A preliminary geometry check is made to
    be sure the edge satisfies the necessary conditions, one of which is that
    the triple edges radiating from the endpoints have no common farther endpoints.
    If run in verbose mode, messages are printed
    when a specified edge fails to be transformed. This command
     is the inverse of the
    pop_tri_to_edge command.
      Works in linear and quadratic mode.
    Examples:

       pop_edge_to_tri edge[2]
       pop_edge_to_tri edge where valence==3 and length < 0.001

    POP_QUAD_TO_QUAD
    Main prompt command.
     This command does a particular topological transformation common in
    three-dimensional foam evolution. A quadrilateral bounded by four
    triple edges is transformed to a quadrilateral oriented in the opposite
    direction.  The shortest pair of opposite quadrilateral edges are shrunk
    to zero length, converting the quadrilateral to an edge, then the edge
    is expanded in the opposite direction to form the new quadrilateral.
    The new quadrilateral inherits attributes such as color from the first
    quadrilateral, although all the facet numbers are different.
    A preliminary geometry check is made to
    be sure the edge satisfies the necessary conditions, one of which is that
    the triple edges radiating from the quadrilateral corners
     have no common farther endpoints.
    If run in verbose mode, messages are printed
    when a specified quadriteral fails to be transformed.
    The specified facet can be any one of the facets of the quadrilateral
    with a triple line on its border.  It doesn't hurt to apply the command to
    all the facets of the quadrilateral, or to facets of multilple quadrilaterals.
    Quadrilaterals may be arbitrarily subdivided into facets; in particular,
    they may have some purely interior facets.
      Works in linear and quadratic mode.
     Examples:

       pop_quad_to_quad facet[2]
       pop_quad_to_quad facet where color==red

    POP_TRI_TO_EDGE
    Main prompt command.
     This command does a particular topological transformation common in
    three-dimensional foam evolution.  A facet with three tetrahedral point
    vertices
    is transformed to a single facet.  A preliminary geometry check is made to
    be sure the edge satisfies the necessary conditions, one of which is that
    the triple edges radiating from the vertices have no common farther endpoints.
    If run in verbose mode, messages are printed
    when a specified edge fails to be transformed. This command
     is the inverse of the
    pop_edge_to_tri command.
      Works in linear and quadratic mode.
     Examples:

       pop_tri_to_edge facet[2]
       pop_tri_to_edge facet where color == red

    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
    ps_colorflag,
    gridflag,
    crossingflag, and
    labelflag toggles.
    full_bounding_box toggles.

    PRINT
    Main prompt command.
    For printing expression values, strings, commands, arrays, or accumulated
    warning messages. Syntax:

    PRINT expr
    PRINT stringexpr
    PRINT commandname
    PRINT arrayslice
    PRINT WARNING_MESSAGES

      The arrayslice option takes an array name or a partially indexed array name.
      If more than one element results, the slice is printed in nested curly
      braces.  The arrayslice can also be that of an array attribute of an
      element.  The warning_messages option is handy for reviewing warning
      messages that occur early in the loading of a datafile but scroll off the
      screen too rapidly to see.
      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;
      define parts real[3][2][3];
      print parts;
      print parts[3][2];

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

      Prints to standard output using the standard C sprintf function.
      All string, integer, and floating point formats are valid.
      Integer formats force floating point arguments to be converted to integer.
      The format string can be a string variable or a quoted string.
      There is a limit of 1000 characters on the format string, otherwise
      there is no limit on the number of arguments.
     Example:

      printf "This is %s with total energy %f\n",datafilename,total_energy

    QUADRATIC

    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_AVERAGE

    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

    READ

    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.  This command does not respect the
    no_refine attribute.
       Example:

           refine edges where not fixed and length > .1

    RESET_COUNTS
    Main prompt command.
    Resets to 0 various internal counters.
    The counters are:

    equi_count,
    edge_delete_count,
    facet_delete_count,
    edge_refine_count,
    facet_refine_count,
    notch_count,
    vertex_dissolve_count,
    edge_dissolve_count,
    facet_dissolve_count,
    body_dissolve_count,
    vertex_pop_count,
    edge_pop_count,
    facet_pop_count,
    pop_tri_to_edge_count,
    pop_edge_to_tri_count,
    pop_quad_to_quad_count,
    where_count,
    edgeswap_count,
    fix_count,
    unfix_count,
    t1_edgeswap_count, and
    notch_count.

    Normally, a count is set to 0 at the start of a command that
    potentially affects it,
     accumulated during the execution of the command,
    and printed at the end of the command.  To be precise, each counter has
    a "reported" bit associated with it, and if the "reported" bit is set when
    the appropriate command (such as 'u') is encountered, the counter will
    be reset to 0 and the "reported" bit cleared. The "reported" bit is set by
    either flush_counts or the end of a command.
    The idea is to have the counts from previous commands available to
    subsequent commands as long as possible, but still have the counter
    reflect recent activity.

    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;
         }

    SADDLE

    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, boundary, 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.  Setting the pressure on a body automatically unfixes
        its volume. For constraint, the expr is the constraint number.
        If using set to put a vertex on a parametric boundary, set the
        vertex's boundary parameters p1, p2, etc. first.
    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

    T1_EDGESWAP
    Main prompt command.
    Does a T1 topological transition in the string model.
    When applied to an edge joining two triple points, it reconnects edges
    so that opposite faces originally adjacent are no longer adjacent, but
    two originally non-adjacent faces become adjacent.

          \_/   =>   \/
          / \         |
                     /\

    It will silently
    skip edges it is applied to that don't fulfill the two triple endpoint
    criteria, or whose flipping is barred due to fixedness or constraint
    incompatibilities.  The number of edges flipped can be accessed through
    the t1_edgeswap_count internal
    variable. Running with the verbose
    toggle on will print details of what it is doing.
    Syntax:
     T1_EDGESWAP edge_generator

    Examples:

       t1_edgeswap edge[23]
       t1_edgeswap edge where length < 0.1

    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

    VALID_ELEMENT
    Main prompt Boolean function.
    Returns 1 or 0 depending on whether an element of a given index
    exists. Syntax:
     VALID_ELEMENT(indexed_element)

    Examples:

       if valid_element(edge[12]) then refine edge[12]
       if valid_element(body[2]) then set body[2].facet color red

    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

    VERTEX_MERGE
    Main prompt command.
    Merges two soapfilm-model vertices into one.
    Meant for joining together surfaces that bump into each other.
    Should not be used for vertices already joined by an edge.
     Syntax:

      vertex_merge(integer,integer)

    Note the syntax is a function taking integer vertex id arguments, not element
    generators.
    Example:

       vertex_merge(3,12)

    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.

    Back to top of Surface Evolver documentation.
    Index.