File: evhelp.txt

package info (click to toggle)
evolver 2.70%2Bds-8
links: PTS, VCS
area: main
in suites: bookworm, bullseye, trixie
size: 17,148 kB
sloc: ansic: 127,395; makefile: 209; sh: 98
file content (17212 lines) | stat: -rw-r--r-- 742,274 bytes
parent folder | download | duplicates (4)
evhelp.txt
Run-time help file used by Surface Evolver.

 The Surface Evolver

 Kenneth A. Brakke
 Mathematics Department
 Susquehanna University
 Selinsgrove, PA, 17870
 brakke@susqu.edu

<----------------------------- __bhead_index ------------------------------>

A body attribute used internally by Hessian routines.

<----------------------------- __vhead_index ------------------------------>

A vertex attribute used internally by Hessian routines.

<------------------------------ __vgrad_head ------------------------------>

A vertex attribute used internally.

<------------------------------- __volgrad -------------------------------->

A vertex attribute used internally for debugging.  Not declared
by default, but if the user declares it as a 2D array, volume
gradients will be stored for later examination, as one gradient
vector for each body.  Sample declaration at runtime:
   define vertex attribute __volgrad[body_count][3]

<------------------------------ __vgrad_head ------------------------------>

Internal vertex attribute used in volume gradient calculations.

<----------------------------- __volvelocity ------------------------------>

A vertex attribute used internally for debugging.  Not declared
by default, but if the user declares it as a 2D array, volume
velocities will be stored for later examination, as one volume
correction vector vector for each body, i.e. the volume gradient
after application of the metric.  Sample declaration at runtime:
   define vertex attribute __volvelocity[body_count][3]

<------------------------------- v_boundary ------------------------------->

Built-in vertex attribute.
If there are parameterized boundaries, then there is a read-only
integer vertex attribute v_boundary that holds the number of
the boundary the vertex is on, or 0 if it is not on a boundary.  Note
that named parameterized boundaries are internally assigned numbers,
which are what show up here. Use the "set vertex boundary ..." or 
"unset vertex boundary" commands to change the boundary status of 
a vertex; do not try to assign a value to v_boundary.

<------------------------------- e_boundary ------------------------------->

Built-in edge attribute.
If there are parameterized boundaries, then there is a read-only
integer edge attribute e_boundary that holds the number of
the boundary the edge is on, or 0 if it is not on a boundary.  Note
that named parameterized boundaries are internally assigned numbers,
which are what show up here.  Use the "set edge boundary ..." or 
"unset edge boundary" commands to change the boundary status of an 
edge; do not try to assign a value to e_boundary.

<------------------------------- f_boundary ------------------------------->

Built-in facet attribute.
If there are parameterized boundaries, then there is a read-only
integer facet attribute f_boundary that holds the number of
the boundary the facet is on, or 0 if it is not on a boundary.  Note
that named parameterized boundaries are internally assigned numbers,
which are what show up here.  Use the "set facet boundary ..." or 
"unset facet boundary" commands to change the boundary status of an 
facet; do not try to assign a value to f_boundary.

<---------------------------------- __x ----------------------------------->

Built-in read-write vertex attribute name for the coordinates. This is a
vector of length equal to the space dimension.  Useful in referring to 
the coordinates as a whole as a vector, as in a dot product, e.g.
   print vertex[1].__x
   prod := vertex[1].__x * vertex[2].__x
   set vertex __x  2*__x
The underscores in front are to distinguish it from the scalar x attribute.

<--------------------------------- v_oldx --------------------------------->

Internal vertex attribute used to store the old coordinates when doing a 
move to find minimum energy in the "g" or "hessian_seek" commands.  v_oldx 
is writable by the user, just in case you might find it handy, but
any values you store there are very temporary.  v_oldx is a vector of
length equal to the space dimension.

<------------------------------ edge_vector ------------------------------->

Built-in edge array attribute containing the vector components of an edge from 
tail to head.  It is the unwrapped vector in case of torus or symmetry groups, 
i.e. the vector you really want.  The individual scalar components are
available as the edge attributes x,y,z, but edge_vector is able to be used 
as a vector in dot products and the like.   Read only.
Examples:  dprod := edge[1].edge_vector * edge[2].edge_vector
           print edge[1].edge_vector

<------------------------------- e_wrap_list -------------------------------->

Built-in edge integer vector attribute.  Internal name for the "wrap"
attribute of an edge in a torus or symmetry model. It holds the integer used 
to encode the wrap of an edge. Note that this is implemented as an array of 
length 1 rather than just a value, so it could be length 0 if not needed.  
Listed here just because this is the name that shows up in the
"list attributes" command. Readable and writable.
Example:  print edge[3].e_wrap_list[1]
          print edge[3].wrap  // equivalent

<----------------------------------- p ------------------------------------>

Built-in vertex vector attribute name for the parameter values of a vertex
when parameterized boundaries are present.  This is a vector whose
length is equal to the maximum number of parameters in any boundary.
Readable and writable.

<----------------------------- v_method_list ------------------------------>

Built-in vertex vector attribute holding the id numbers of the method
instances that this vertex contributes to.  Size expands as needed.
Read-only.  Meant for internal use only.   Use "set vertex method ... " 
or "unset vertex method .." to change the status of a vertex.

<----------------------------- e_method_list ------------------------------>

Built-in edge vector attribute holding the id numbers of the method
instances that this edge contributes to.  Size expands as needed.
Read-only. Meant for internal use only.  Use "set edge method ... " 
or "unset edge method .." to change the status of a edge.

<----------------------------- f_method_list ------------------------------>

Built-in facet vector attribute holding the id numbers of the method
instances that this facet contributes to.  Size expands as needed.
Read-only.   Meant for internal use only.   Use "set facet method ... " 
or "unset facet method .." to change the status of a facet.

<------------------------------- f_vertices ------------------------------->

Internal facet array attribute holding the id numbers of the vertices
of the facet.  Not accessible to users since the datatype is element_id,
which is not implemented in the user interface.  Mentioned here since
it does show up when you do the list_attributes command.

<------------------------------ facet_normal ------------------------------>

Built-in facet read-only vector attribute holding the normal vector
of the facet, normalized so its length is equal to the area of the
facet.  Synonymous with x[] or x,y,z, (that is, facet[1].x[2] is equal
to facet[1].y is equal to facet[1].facet_normal[2]),  but it is useful 
where it is needed to refer to the normal as a vector, as in dot products. 
Example:
    dprod := facet[1].facet_normal * facet[2].facet_normal

<------------------------------ f_body_list ------------------------------->

Internal facet array attribute holding the front and back body ids.
Not directly accessible to users since its datatype is element_id.
Users access it through the frontbody and backbody attributes of
a facet.  The array size is 0 if no bodies are present, to save room.  
Mentioned here since it does show up when you do the list_attributes command.

<------------------------------ next_vfacet ------------------------------->

Internal facet attribute used to implement linked list of facets
adjacent to a vertex.  This is used in commands that iterate over the
facets adjacent to a vertex, like
   print sum(vertex[1].facet,area)
This attribute is not directly accessible to the user, since its
datatype is element_id.
Mentioned here since it does show up when you do the list_attributes command.

<------------------------------ next_bfacet ------------------------------->

Internal facet attribute used to implement linked lists of facets
comprising bodies.  This is used in commands that iterate over the
facets of a body, like
   print sum(body[1].facet,area)
This attribute is not directly accessible to the user, since its
datatype is element_id.
Mentioned here since it does show up when you do the list_attributes command.

<----------------------------- b_method_list ------------------------------>

Built-in body attribute holding the id numbers of the method
instances that this body contributes to.  Size expands as needed.
Read-only.  Meant for internal use.  Use "set body method_instance ..." 
or "unset body method_instance ... " to change.

    
<----------------------------------- A ------------------------------------>

Single letter main command. Lists the current values of variables.  You 
are allowed you to enter new values. The new value is entered as the number 
of the variable (from the list) and the new value. Exit by hitting RETURN on 
a blank line. All changes that can be made here can also be made with 
assignment commands.  The "A" command dates from the time before
there were assignment commands; now I use this command just for scanning
the values of variables.


<----------------------------------- a ------------------------------------>

Single letter main command. Toggles area normalization of vertex forces
and other gradients, to model motion by mean curvature.  That is, the
velocity of a vertex is the force divided by the area associated to the
vertex (or length in the string model).  Meant to be used with a fixed 
scale factor. Be sure you have a small enough scale factor or else 
things tend to blow up. Reduce the scale factor temporarily after
refinement, since triangle areas are cut by a factor of 4 but the old
creases remain. When this option is toggled ON, you are asked whether
you want an optional check that can be made for facets that move too much. 
This is done by computing the ratio of the length of the normal change to 
the length of the old normal. If this exceeds the user-specified value, 
then all vertices are restored to their previous position. The user should 
reduce the motion scale factor and iterate again.  Same as the 
area_normalization toggle command, except that does not ask about the 
optional check.

<--------------------------------- abort ---------------------------------->

Main prompt command. Causes immediate termination of the executing command
and returns to the command prompt. Meant for stopping execution of a
command when an error condition is found. There will be an error message
output, giving the file and line number where the abort occurred, but it is
still wise to have a script or procedure or function print an error message
using errprintf before doing the abort command, so the user knows why. 
If used at a "subcommand" prompt, the abort command will return to the main
prompt. 
 
<---------------------------------- abs ----------------------------------->

 abs(x) : Absolute value of x.

<-------------------------------- ackerman -------------------------------->

Named method. Description: Not actually an energy, but a kludge to put
inertia on vertices. Uses extra velocity coordinates to represent vertex in
phase space. Invocation actually transfers computed forces from space
coordinates to velocity coordinates, so forces become acceleration instead
of velocity. 

Element: vertex. 
Parameters: none. 
Models: any. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity jeremy energy method ackerman global


<---------------------------------- acos ---------------------------------->
<---------------------------------- asin ---------------------------------->
<---------------------------------- atan ---------------------------------->

acos(x),asin(x),atan(x): Inverse trig functions. acos, asin arguments are
clamped to [-1,1]. Results in radians.  asin(x) range is -pi/2 to pi/2,
acos(x) range is 0 to pi, and atan(x) range is -pi/2 to pi/2.  Also see
atan2(y,x).

<--------------------------------- acosh ---------------------------------->
<--------------------------------- asinh ---------------------------------->
<--------------------------------- atanh ---------------------------------->

asinh(x),acosh(x),atanh(x): Inverse hyperbolic functions.  acosh(x)
domain is x >= 1; other values will give run-time errors.

<----------------------------- actual_volume ------------------------------>

Body datafile attribute. Actual_volume is an optional number that can be 
specified in the datafile definition of a body in the rare circumstances 
where the torus volume volconst calculation gives the wrong answer; volconst 
will be adjusted to give this volume of the body.  Example:
  bodies
    1   1 2 3 4 5  volume 1  actual_volume 0.8
This means the target volume is 1, but the volume of the body as loaded
from the datafile should be 0.8, and the body's volconst will be adjusted
to make that true.

<-------------------------------- addload --------------------------------->

Main prompt command. 
Loads a new datafile without deleting the current surface, permitting the
simultaneous loading of multiple copies of the same datafile or different
datafiles. Syntax: 
 
   ADDLOAD string 

where string is either a sting literal in double quotes, or a string
variable name such as datafilename. Elements in the new datafile are
re-numbered to not conflict with existing elements. This is actually the
same as the default behavior of Evolver when loading a single datafile.
Thus the -i command line option or the keep_originals keyword is not obeyed
for the new datafile. The "read" section of the new datafile is not executed;
this permits a datafile to use the addload command in its read section to
load more copies of itself. Your loading script is responsible for all
initialization that would ordinarily be done in the read section of the new
datafile. Declarations in the top section of the new datafile will
overwrite any existing declarations. This is usually not a problem when
loading multiple copies of the same datafile, but requires attention when
loading different datafiles. For example, numbered constraints are a bad
idea; use named constraints instead. See the sample datafile
addload_example.fe for an example of how to load and distinguish between
multiple copies of the same surface.  For variables you don't want 
written, you can set the no_dump property of a variable to prevent it 
from being dumped in the top of the datafile; it will be dumped in the 
bottom section instead. 
Example (as commands, not in the top of the datafile):
  htvar := 2.3
  htvar.no_dump on
 
<-------------------------- aggregate functions --------------------------->
<---------------------------------- avg ----------------------------------->
<---------------------------------- sum ----------------------------------->
<---------------------------------- min ----------------------------------->
<---------------------------------- max ----------------------------------->
<--------------------------------- count ---------------------------------->

Aggregate functions give a result from a specified set of geometric
elements.  The maximum, minimum, sum, count, or average of an expression over
a set of elements may be done with aggregate functions. The syntax is

   max(generator,expr)
   min(generator,expr)
   sum(generator,expr)
   avg(generator,expr)
   count(generator,expr)

Example: this prints the total area of all green facets:

   print sum(facet where color == green, area)

"Count" is an aggregate function that gives the number of elements
generated, regardless of the expression.

Use maximum(a,b) or minimum(a,b) for the arithmetical maximum or minimum
of two numbers.

<--------------------------- aggregate commands --------------------------->

Certain commands (fix, unfix, set, unset, list, delete, dissolve, 
refine, edgeswap, foreach, vertex_average, equiangulate, pop, 
t1_edgeswap, reverse_orientation, etc.) act on sets of elements. By 
default, the set is all elements of the appropriate type, but the
set may be narrowed by use of a "where" clause.  Examples:
   list vertices
   delete edges where length < 0.001
   set edge[23] color red
   set vertex[2].facets color green

<------------------------- MPI aggregate commands ------------------------->

When MPI Evolver executes an aggregate command (fix, unfix, set, unset, 
histogram, list, delete, dissolve, refine, edgeswap, foreach, 
vertex_average, equiangulate, pop, t1_edgeswap, reverse_orientation, 
etc.) or aggregate function (sum, min, max, avg, count) from the
main prompt, the set of elements used in each task includes only
elements belonging to that task, not imported elements.  However,
when used in a parallel_exec or task_exec command, an aggregate
will include all elements, native and imported.

<--------------------------------- alice ---------------------------------->

A keyword for a special purpose command not documented.


<---------------------------- ambient_pressure ---------------------------->

Run-time toggle command that toggles ideal gas mode with ambient pressure 
outside bodies. The external pressure can be set with the pressure phrase in 
the top of the datafile, or at runtime with the command "p 10" for example, 
to set the external pressure to 10.

<------------------------- ambient_pressure_value ------------------------->

Built-in read-write variable. Value of the external pressure in the
ideal gas model.

<--------------------------- boolean operators ---------------------------->
<---------------------------------- and ----------------------------------->
<----------------------------------- or ----------------------------------->
<---------------------------------- not ----------------------------------->
<------------------------------ greater than ------------------------------>
<------------------------------- less than -------------------------------->
<--------------------------------- equal ---------------------------------->
<------------------------------- not equal -------------------------------->

Boolean operator.  Boolean expressions are a subclass of arithmetic
expressions, with zero as false and nonzero as true; true results
evaluate as 1. The Boolean operators available are, in precedence order:

 ==,>,<,>=,<=,!=    Numerical comparison.
 NOT, !             Boolean NOT.
 AND, &&            Boolean AND, with short-circuit evaluation.
 OR, ||             Boolean OR, with short-circuit evaluation.

I advise you to use parentheses freely in compound boolean expressions,
to be sure you get your desired order of evaluation.

<------------------------------ approx_curv ------------------------------->

Evolver toggle command. Uses polyhedral curvature (linear interpolation
over facets for metric) for mean curvature vector. Actually establishes the
inner product for forms or vectors to be integration over facets of
euclidean inner products of linear interpolation of values at vertices.
Synonyms: APPROX_CURV, APPROX_CURVATURE.


<---------------------------- approx_curvature ---------------------------->

Evolver toggle command. Uses polyhedral curvature (linear interpolation
over facets for metric) for mean curvature vector. Actually establishes the
inner product for forms or vectors to be integration over facets of
euclidean inner products of linear interpolation of values at vertices.
Synonyms: APPROX_CURV, APPROX_CURVATURE.


<------------------------- approximate_curvature -------------------------->

Evolver toggle command. Uses polyhedral curvature (linear interpolation
over facets for metric) for mean curvature vector. Actually establishes the
inner product for forms or vectors to be integration over facets of
euclidean inner products of linear interpolation of values at vertices.
Synonyms: APPROX_CURV, APPROX_CURVATURE.


<---------------------------------- area ---------------------------------->

As a keyword, "area" is a read-only attribute of facets.  Examples:
    print facet[4].area
    histogram(facet where color == blue, area)
Area is normally the Euclidean area as calculated from vertex coordinates
(using Gaussian integration in quadratic and lagrange models), but it is
altered when there is a metric or an area_method_name.

<--------------------------- area_normalization --------------------------->

Toggle command for a type of surface mobility. In motion by mean curvature, 
the resistance to motion is really due to the surfaces, not the vertices. One
way to approximate this is to say the resistance to motion of a vertex is
proportional to the area associated with the vertex. So this mode counts the
area of a vertex as equal to 1/3 of the area of the star of facets around it
(or 1/2 the length of the star of edges in the string model). This is easy
to calculate, since it is a local calculation for each vertex.  The result
is that velocity = force/area, which is a much better approximation to
motion by mean curvature than the default of velocity = force.  This mode
is not restricted to motion by mean curvature.  Area normalization can be
 toggled with the "a" command or the "area_normalizaton" toggle.

<------------------------------- area_fixed ------------------------------->
<------------------------------- fixed_area ------------------------------->

An obsolete way of declaring the total area of the surface fixed in the
datafile. Synonym: fixed_area. The preferred way of doing this now is to
define a fixed named quantity in the datafile, such as
       quantity the_area fixed = 2.3 global_method facet_area
This permits all the named quantity features to be used.


<---------------------------- area_method_name ---------------------------->

This optional top-of-datafile item, area_method_name, specifies the name of the
pre-defined method to be used as the method to compute facet areas in
place of the default edge_area method in the string model or facet_area
method in the soapfilm model. It is optional. Developed so circular arcs
can be used in two-dimensional foams. Current reasonable methods are
circular_arc_area and spherical_arc_area. Synonymous with volume_method_name
in the string model.  Usage implies converting to everything_quantities mode.
Datafile syntax:

    area_method_name quoted_method_name

For example,

    string
    space_dimension 2
    area_method_name "circular_arc_area"
    length_method_name "circular_arc_length"


<------------------------------ area_square ------------------------------->

Named method. Description: Energy of a facet is the square of the facet
area. 

Element: facet. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration:

   quantity asquare energy method area_square global


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


<--------------------------------- arrays --------------------------------->


It is possible to define multidimensional arrays of integers or reals with
the syntax

   DEFINE variablename  REAL|INTEGER|STRING [expr]...

This syntax works both in the datafile header and at the command prompt.
If the array already exists, it will be resized, with old elements kept as
far as possible. Do not resize with a different number of dimensions. Note
that array indexing starts at 1. A size of 0 is legal, and useful if you
are not using an array at the moment and want to free storage space. There
is runtime checking of array bounds. Example:

  define fvalues integer[10][4]
  define basecoord real[10][space_dimension]

Identifier names declared local can be used in array declarations in 
procedures and functions; dynamic sizes can be used, but static sizes 
may be a bit faster since memory doesn't need to be dynamically allocated.

In the top of the datafile, arrays may be initialized with
nested bracket initializers following the definition.  For example:
  define qwerty integer[4] = { 23, 45, 12, 2 }
  define vmat real[3][2] = {{1,2},{3,4},{5,6}}
  define primcol string[3] = {"red","green","blue"}
Initializers need not be complete; missing values will be zero.
Array initializers also work at runtime for assignments, for example:
  vmat[2] := { total_energy, total_area }

Array elements may be used and assigned as is usual for programming
languages:
  fvalues[3][4] := 234;
  if basecoord[3][1] > 2 then print "hello world!\n";

The print command may be used to print whole arrays or array slices in
bracketed form. Example:

   print fvalues
   print fvalues[4]

There are some basic whole-array operations that permit arrays on
the left side of an assignment statement:
   array := scalar
   array := array
   array := scalar * array
   array := array + array
   array := array - array
   array := array * array
Here "array" on both sides of the assignment means a single whole array;
not an array-producing expression  or array slice.  But "scalar" can be 
any expression that evaluates to a single value.  For multiplication, 
the arrays must be two-dimensional with properly matching sizes.  These 
operations also apply to element attributes that are arrays.

See also matrix_inverse.

<-------------------------- array initialization -------------------------->

Array initialization syntax works for runtime assignments to 
arrays and array slices, including element attributes that
are arrays.  The entries in the initializer must be single
numbers, not arrays.  The number of dimensions on the left 
and right side of the assignment must agree, but the sizes
in each dimension need not agree.  Missing elements on the 
right side are regarded as zero.  Examples:
   vertex[1].__x := { 1.2, 3.1, 4.7 }
   define mat real[2][2];
   mat := {{1,2},{3,4}}
The right side is evaluated each time the assignment is 
executed, so the entries on the right can be any expressions
that evaluate to numbers.  Assignment with += and -= also
work, as does *= and /=, but note that all of these
work element-wise (i.e. *= and /= are not matrix multiplication
and division).


<------------------------------- array slice ------------------------------->

A special syntax for the "print" command lets one print various
dimensioned slices of multi-dimensional arrays.  Syntax:

   PRINT arrayslice

The "print" command can take an array name or a partially indexed array
name. If more than one element results, the slice is printed in nested
curly braces. The array slice can also be that of an array attribute of an
element.   Examples:

  define parts real[3][2][3];
  print parts;
  print parts[1][1];

Array slices may also be used in array expressions anywhere full arrays
can be used.

<------------------------------- arrow keys ------------------------------->

Graphics mode command keys. Move the image in the appropriate direction.
May be prefixed by a real number, which is multiple of thirds of screen
width to move. Default move is 1/12 screen width. May not work on all
terminals.  Arrow keys alone may work in the graphics window, again
depending on the system.



<------------------------------- assignment ------------------------------->

The assignment operator := can be used to assign numeric and non-numeric
values to various entities. Note that ':=' is used for assignment, not '='.
The C-style arithmetic assignments +=, -=, *=, and /= work for numerical
variables. 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.  The postincrement operator ++ and 
postdecrement operator -- also exist for single variables as stand-alone
commands.  
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

<---------------------------- assume_oriented ----------------------------->

Evolver toggle command. Tells squared mean curvature routines that they
can assume the surface is locally consistently oriented. Significant only
for extreme shapes.


<--------------------------------- atan2 ---------------------------------->

atan2(y,x): Inverse tangent, range -pi to pi.


<----------------------------- atomic values ------------------------------>

The following evaluate to single numbers in expressions:
 number: An integer, real, hexadecimal, or binary constant. Hex numbers
   begin with 0x; binary numbers have a trailing 'b'.
 pi: Mathematical constant, ratio of circle circumference to radius.
 x1,x2,...; x,y,z,w : Depending on context, space coordinates, vertex
   coordinates, edge vector components, or facet normal components.
 p1,p2,...: Parameters of vertices on boundaries.
 G : Current gravitational constant for calculating gravitational energy.
 User-defined variables : Arbitrary variables defined in the datafile or at
    runtime.
 Fully indexed array variables.
 Internal variables : Special pre-defined variables.
 Element attributes : Things like vertex coordinates, edge length facet
    area, colors.  Array attributes must be fully indexed.
 Named quantity attributes : Including modulus, target, value, pressure.
 Method instance attributes : Including modulus, value.
 Toggle name : Any toggle command name may be used as a Boolean variable in
    an expression (full word toggles, not single letters). But beware the
    ambiguity in interpreting a toggle as a command or a value. You may have 
    to use parentheses to force the toggle to be interpreted as a value. Thus
    "ad := autodisplay" sets ad as a command synonym for autodisplay, while
    "ad := (autodisplay)" records the current boolean value.

<------------------------------- attribute -------------------------------->

As a keyword, "attribute" is used in the define command for element extra
attributes, for example,
   define facet attribute myattrname real
   define vertex attribute newx real[3]
This syntax works both in the top of the datafile and at runtime.
For a list of pre-defined attributes, see "attributes".
To list all attributes with stored values, do "list attributes".

<------------------------------- attributes ------------------------------->

The surface is defined in terms of its geometric elements of each
dimension. Each element has its own set of attributes. Some may be set by
the user; others are set internally but may be queried by the user. It is
also possible to dynamically define extra attributes for any type of
element, which may be single values or vectors of values. Attribute values
can be specified in the datafile, and queried with commands.
The following attributes are pre-defined for all types of elements:
 ID: Element identifying number
 OID: Oriented element identifying number
 ORIGINAL: Number of parent datafile element
 ON_QUANTITY quantityname: True if the given named quantity applies to the
   element.
 ON_METHOD_INSTANCE instancename: True if the given method instance applies
   to the element.
For other attributes, see specific types of elements: vertices, edges,
facets, bodies, facet-edges.   A list of the attributes stored within
element data structures can be printed with the "list attributes" command.


<--------------------------- augmented_hessian ---------------------------->

Evolver toggle command. Solves constrained Hessians by putting the body
and quantity constraint gradients in an augmented matrix with the Hessian,
and using sparse matrix techniques to factor. Vastly speeds things up when
there are thousands of sparse constraints, as in a foam. The default state
is unset (prints as a value of -1), in which case augmentation is used for
50 or more constraints, but not for less.


<-------------------------------- autochop -------------------------------->

Evolver toggle command. Do automatic refining of long edges each iteration. 
Use "autochop_length := expr" to set autochop length. Each iteration, any 
edge that is projected to become longer than the cutoff is bisected. If any 
bisections are done, the motion calculation is redone.  The autochop length 
may be accessed by the read/write internal variable autochop_length;
but note that simply assigning a value to autochop_length does not
toggle autochop on.

<---------------------------- autochop_length ----------------------------->

Evolver internal read-write variable that autochop mode uses as 
the critical length; longer edges will be refined.

<------------------------------ autodisplay ------------------------------->

Evolver toggle command. Toggles automatic redrawing of graphics whenever
the surface changes. Default ON. Same function as the 'D' command.

<-------------------------------- autopop --------------------------------->

Evolver toggle command. Toggles automatic deletion of short edges and
popping of improper vertices each iteration. Before each iteration, any
edge projected to shorten to under the critical length is deleted by
identifying its endpoints. The critical length is calculated as L =
sqrt(2*dt), where dt is the time step or scale factor. Hence this should be
used only with a fixed scale, not optimizing scale factor. The critical
length is chosen so that instabilities do not arise in motion by mean
curvature in the string model. If any edges are deleted, then vertices
are examined for improper vertices as in the 'o' command. Useful in the
string model.

Autopop is also implemented for small facets as of Evolver version 2.30.
The critical area is calculated as sqrt(2*dt)*perimeter/2, where perimeter
is the sum of the lengths of the three sides of the facet.

See also the immediate_autopop and autopop_quartic toggles.

<---------------------------- autopop_quartic ----------------------------->

Toggle.  Modifies the autopop mode.  The critical length for edges is
set to 2*sqrt(sqrt(dt)) and the critical area for facets is set to
2*sqrt(sqrt(dt))*perimeter/2; meant for quantities such as 
laplacian_mean_curvature where velocity is proportional to fourth 
derivative of surface.

<------------------------------- autorecalc ------------------------------->

Evolver toggle command. Toggles automatic recalculation of the surface
whenever adjustable parameters or energy quantity moduli are changed.
Default is OFF.  Alternatively, the user can use the "recalc" command
to force recalculation if the default recalculations are not timely.


<--------------------------- average_crossings ---------------------------->

Named method. Description: To calculate the average crossing number in all
projections of a knot. Contributed by John Sullivan) 

Element: edge. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration:

    quantity across energy method average_crossings global

<------------------------------ axial_point ------------------------------->

Vertex read-write attribute. Certain symmetry groups (e.g. cubocta or
rotate) have axes of rotation that are invariant under some non-identity
group element. A vertex on such an axis must be labeled in the datafile
with the attribute axial_point, since these vertices pose special problems
for the wrap algorithms. If you are only using a subgroup of the full
group, then you only need to label vertices on the axes of the subgroup.
The net wrap around a facet containing an axial point need not be the
identity. Edges out of an axial point must have the axial point at their
tail, and must have zero wrap. Facets including an axial point must have
the axial point at the tail of the first edge in the facet. It is your
responsibility to use constraints to guarantee the vertex remains on the
axis.

<----------------------------------- b ------------------------------------>

Single letter main command. Permits user to interactively change body
prescribed volumes or pressures, depending on which is prescribed.
Prints old value for each body and prompts for new.

Graphics mode command. Toggles display of bounding box. Useful for
visualizing orientation. In the native graphics window, the 'o' key does
the same thing.  The default color of the bounding box is blue, but
that can be changed by setting the variable bounding_box_color to the
desired color, for example
    bounding_box_color := red


<----------------------------------- B ------------------------------------>

Graphics mode command. Toggles display of facets on boundaries or
equality level-set constraints (as opposed to one-sided constraints).


<-------------------------------- backbody -------------------------------->

Facet read-write attribute. The id of the body of which the facet is on
the negatively oriented boundary.  This may disagree with what you think
ought to be the "back body" of a facet, but it's the way I see it.
As a read attribute, the value is 0 if there is no such body. As a write 
attribute, it can be used to assign facets to bodies, and assigning 0 
removes it from its back body. Examples:

  newb := new_body; set facet[1] frontbody newb;
  set facet backbody newb where id == 2 or id == 4;
  print facet[4].backbody

Backbody also works for adding edges to a facet in the string model, but
the added edge must be attach to one end of the edge arc, or close the arc.
See also "frontbody".

<------------------------------- backcolor -------------------------------->

Facet read-write attribute. Color of negative side of facet for graphics.
Default is white. Set also when the "color" attribute is set. Datafile
example:
  Faces
  1   1 2 3 frontcolor green backcolor red

 Command examples:
  list facets where backcolor == red
  set facet[3] backcolor green
  set facet backcolor red where area > 2

If frontcolor and backcolor of a facet are different, the native
graphics display may draw the facet as a double layer.  The "thickness"
variable controls the distance between layers.  If thickness is too small,
the frontcolor and backcolor may both show in a confused manner.

<-------------------------------- backcull -------------------------------->

Evolver toggle command. Prevents display of facets with normal away from
viewer. May have different effects in different graphics displays. For
example, to see the inside back of a body only, "set frontcolor clear"
alone works in 2D displays, but needs backcull also for direct 3D.

<------------------------------- background ------------------------------->

Internal read-write variable. Background color used in certain screen
graphics (xgraph and Windows, at the moment).  See "colors" for the
available colors.  Example:
   background := white

<---------------------------------- bare ---------------------------------->

As a keyword, "bare" is a vertex attribute or an edge attribute set by the
user that tells the Evolver not to expect the vertex or edge to be attached
to a facet.  Useful in a datafile to prevent a lot of warning messages.
But it is not a synonym for "valence 0", since it doesn't check the 
actual valence when you apply it or use it.

<------------------------------- bare edge -------------------------------->

Edge read-write attribute. Declaring an edge "bare" indicates that an edge
does not have an adjacent facet (soapfilm model). Best declared in the
datafile, by adding the keyword bare to the line defining an edge. Useful
in avoiding warning messages. Bare edges are useful to show wires,
frameworks, outlines, etc. in graphics. Example:

  list edge where bare

But it is not a synonym for "valence 0", since it doesn't check the 
actual valence when you apply it or use it.

<------------------------------ bare vertex ------------------------------->

Vertex read-write attribute. Declaring a vertex "bare" says that a vertex
does not have an adjacent edge (string model) or an adjacent facet
(soapfilm model). Useful in avoiding warning messages. A vertex may be
declared bare in the vertices section of the datafile by adding the keyword
bare to the line defining the vertex. Example:

   list vertex where bare

But it is not a synonym for "valence 0", since it doesn't check the 
actual valence when you apply it or use it.

<------------------------------ bezier_basis ------------------------------>

Evolver toggle command. When Evolver is using the Lagrange model for
geometric elements, this toggle replaces the Lagrange interpolation
polynomials (which pass through the control points) with Bezier basis
polynomials (which do not pass through interior control points, but have
positive values, which guarantees the edge or facet is within the convex
hull of the control points). This is experimental at the moment, and not
all features such as graphing or refinement have been suitably adjusted.


<------------------------------- big_endian ------------------------------->

Evolver toggle command. Controls the order of bytes in binary_printf
numerical output. Big-endian is most significant byte first. To change to
little-endian, use little_endian, not "little_endian off".

<----------------------------- binary numbers ----------------------------->

Integer values may be given in binary notation, such as 11001b, indicated
by a trailing 'b'.

<---------------------------- binary_off_file ----------------------------->

Main prompt command.  Produces one frame file for my 3D movie program
evmovie (see http://www.susqu.edu/brakke/evmovie/evmovie-doc.html
for more details).  Syntax:

   binary_off_file string

where string is the name of the output file, either a
double-quoted string, a string variable, or a string-generating
expression (typically using sprintf).

<----------------------------- binary_printf ------------------------------>

Main prompt command. For printing formatted binary output to files.
Syntax:

   BINARY_PRINTF string,expr,expr,...

Prints to standard output using a binary interpretation of the standard C
formats:
   %c    one byte
   %d    two byte integer
   %ld   four byte integer
   %f    four byte float
   %lf   eight byte float
   %s    string, without the trailing null
   non-format characters are copied verbatim as single bytes.

The byte order for numbers can be set with the big_endian or little_endian
toggles. NOTE: Either big_endian or little_endian must be set for
binary_printf to work! 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. Meant to be use
with redirection to a file. In Microsoft Windows, the output file type is
temporarily changed from TEXT to BINARY so newline bytes don't get
converted. Example:

  binary_printf "%ld%ld%ld",vertex_count,edge_count,facet_count >>"out.bin"

<------------------------------- bi_surface ------------------------------->

Named method of the knot energy family.   Double integral over surface, i.e.
all pairs of vertices weighted with adjacent facet areas.  Adapted from 
facet_knot_energy. Uses an arbitrary formula for the pair energy, a function 
of the vector between the vertices.  The formula is given by the 
"scalar_integrand" in datafile definition.  Example datafile definition:
   quantity qqqq energy method bi_surface
   scalar_integrand  x^2 + y^2 + z^2 

The vertex pairs it is evaluated over can be controlled. If the vertex integer
attribute bi_surface_attr is defined, only those with different values of 
bi_surface_attr will be included; otherwise all pairs are included.

<---------------------------- bi_surface_attr ----------------------------->

Vertex attribute used by the bi_surface named method to control which pairs
of vertices are integrated.

<--------------------------------- colors --------------------------------->
<--------------------------------- black ---------------------------------->
<---------------------------------- blue ---------------------------------->
<--------------------------------- green ---------------------------------->
<---------------------------------- red ----------------------------------->
<---------------------------------- cyan ---------------------------------->
<-------------------------------- magenta --------------------------------->
<--------------------------------- brown ---------------------------------->
<------------------------------- lightgray -------------------------------->
<------------------------------- lightgrey -------------------------------->
<---------------------------------- grey ---------------------------------->
<---------------------------------- gray ---------------------------------->
<-------------------------------- darkgray -------------------------------->
<-------------------------------- darkgrey -------------------------------->
<------------------------------- lightblue -------------------------------->
<------------------------------- lightgreen ------------------------------->
<--------------------------------- clear ---------------------------------->
<------------------------------ transparent ------------------------------->
<-------------------------------- lightred -------------------------------->
<------------------------------- lightcyan -------------------------------->
<--------------------------------- yellow --------------------------------->
<------------------------------ lightmagenta ------------------------------>
<--------------------------------- white ---------------------------------->

The colors of edges and facets are normally recorded as integers in the 
range -1 through 15 (see "rgb_colors" for an alternate mode). How these 
integers translate to colors on the screen is determined by how Evolver's 
graphics drivers are written. The following synonyms are supplied, and it 
is hoped that the graphics drivers will be written to display these correctly:

 -1 CLEAR
 0 BLACK
 1 BLUE
 2 GREEN
 3 CYAN
 4 RED
 5 MAGENTA
 6 BROWN
 7 LIGHTGRAY
 8 DARKGRAY
 9 LIGHTBLUE
 10 LIGHTGREEN
 11 LIGHTCYAN
 12 LIGHTRED
 13 LIGHTMAGENTA
 14 YELLOW
 15 WHITE

 The special color value CLEAR (-1) makes a facet transparent. 
"Transparent" is a synonym for clear. These tokens are simply 
translated to integer values wherever they occur, so these are
reserved words. Edge and facet colors may be set in the datafile or by the
set command.  See "rgb_colors" for more detailed control of colors.

<------------------------------- blas_flag -------------------------------->

Evolver toggle command. Toggles using BLAS versions of some matrix
routines, if the Evolver program has been compiled with the -DBLAS option
and linked with some BLAS library. For developer use only at the moment.


<--------------------------------- bodies --------------------------------->
<---------------------------------- body ---------------------------------->


A "body" is an Evolver element type representing a full-dimensional region of 
space. Body interiors are not meshed.  Rather, bodies are determined by their
boundary facets (or edges in 2D).  These facets are used for calculating
body volume and gravitational energy.  Only those facets needed for correct
calculation need be given. In the string model, usually a body corresponds
to one facet. Bodies of the original surface are defined in the "bodies"
section of the datafile; for datafile syntax, see "bodies section".
 Attributes:
  facets
  id
  density
  volume
  target
  volfixed
  actual_volume
  volconst
  pressure
  phase
  extra attributes

As a command keyword, "body" is an element name in element generators,
either as the main element type, or as a subelement of a facet.
Examples:
   foreach body bb do printf "Body %d has volume %f\n",bb.id,bb.volume;
   list facet[1].bodies
Bodies may be created with the "newbody" command, and destroyed with
the "dissolve" command.

<----------------------------- bodies section ----------------------------->

The datafile body list follows the face list, and is started by the
keyword BODIES at the start of a line. It is followed by lines with one
body specification per line in this format:

k  f1 f2 f3 .... [VOLUME constexpr] [VOLCONST constexpr]
   [ACTUAL_VOLUME constexpr] [PRESSURE p] [DENSITY constexpr] [PHASE]

Here k is the body number, and f1 f2 f3 ... is an unordered list of signed
facet numbers. Positive sign indicates that the facet normal (as given by
the right-hand rule from the edge order in the facet list) is outward from
the body and negative means the normal is inward. Giving a VOLUME value
constexpr means the body has a volume constraint, unless the ideal gas
model is in effect, in which case constexpr is the volume at the ambient
pressure. VOLCONST is a value added to the volume; it is useful when the
volume calculation from facet and edge integrals differs from the true
volume by a constant amount, as may happen in the torus model.
ACTUAL_VOLUME is a number that can be specified in the rare circumstances
where the torus volume volconst calculation gives the wrong answer;
volconst will be adjusted to give this volume of the body. Giving a
PRESSURE value means that the body is deemed to have a constant internal
pressure; this is useful for prescribed mean curvature problems. It is
incompatible with prescribed volume. Giving a DENSITY value means that
gravitational potential energy will be included.

To endow a facet with VOLUME, PRESSURE, or DENSITY attributes in the
string model, define a body with just the one facet.

The PHASE number is used in the soapfilm model to determine the surface
tension of facets between bodies of different phases, if phases are used.

The BODIES section is optional.
The "list bodies" command prints the datafile format listing of bodies.


<----------------------------- bodies_predicted ------------------------------>

Datafile keyword in the top section of the datafile that specifies the
initial allocation of body structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the body list grows or as 
the surface is evolved.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the "d" or "dump" commands, based on
the current number of bodies.
Example:
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432

<------------------------------ body density ------------------------------>

Body read-write attribute. This is the density used for gravitational potential
energy. It can be set in the bodies section of the datafile, or with the
set command, or by assignment. Command examples:
  print body[2].density
  set body density 3
  body[2].density := 5


<------------------------------ body facets ------------------------------->

Body read-only attribute. Generates facets bounding a body, with proper
facet orientation with respect to the body. Examples:
  list body[1].facets
  set body[2] facet frontcolor red

<------------------------------- body phase ------------------------------->

Body read-write attribute. For determining facet tension in soapfilm
model, if a phase file is used.

<----------------------------- body pressure ------------------------------>

Body read-write attribute. If a body has a prescribed volume, this is a
read-only attribute, which is the Lagrange multiplier for the volume
constraint. If a body is given a prescribed pressure, then there is an
energy term equal to pressure times volume. A body cannot have a prescribed
volume and a prescribed pressure at the same time. Prescribed volume or
pressure can be set in the bodies section of the datafile. If pressure is
prescribed, then the value can be changed interactively with the b command,
the set command, or by assignment. Examples:
  print body[2].pressure
  body[2].pressure := 1.3
  set body[2] pressure 1.3


<----------------------------- body volconst ------------------------------>

Body read-write attribute. A constant added to the calculated volume.
Useful for correcting for omitted parts of body boundaries. Also used
internally as a correction in the torus model, which will use the target
volume to calculate volconst internally. In the torus model, the target
volume should be set within 1/12 of a torus volume of the actual volume for
each body, so the correct volconst can be computed. Each volconst will be
adjusted proportionately when the volume of a fundamental torus domain is
change by changing the period formulas. Volconst can be set in the datafile
bodies section, or interactively by the set command or by assignment.
Examples:
  print body[1].volconst
  set body[2] volconst 1.2
  body[2].volconst := 1.2

It is best to avoid using volconst except in the torus model. Rather, use
edge content integrals so that the proper adjustments will be made if the
boundary of the surface is moved, or rebody is done.

<------------------------------ body volume ------------------------------->

Body read-only attribute. Actual volume of a body. This is the sum of
three parts, in the soapfilm model:
  1. An integral over the facets bounding the body. This is \int z dx dy
     normally, but \int (x dy dz + y dz dx + z dx dy)/3 if SYMMETRIC_CONTENT is
     in effect.
  2. Any constraint or boundary content edge integrals applying to the body.
  3. The body's volconst attribute.
In the string model, the parts are
  1. An integral over the edges bounding the body's facet. This is \int -y dx.
  2. Any constraint or boundary content vertex integrals applying to the body.
  3. The body's volconst attribute.
Body volumes can be displayed with the v command, or with standard
attribute syntax. Example:
  print body[1].volume
  foreach body where volume > 2 do print id


<------------------------------- body_count ------------------------------->

Internal read-only variable. Number of bodies.

<-------------------------- body_dissolve_count --------------------------->

Internal read-only variable. Number of bodies dissolved by the "dissolve"
command. Prints and resets to 0 at the end of a command execution, or
when flush_counts is done. Also reset by reset_counts.

<------------------------------- 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;
  for each body bb do set bb.facet frontcolor (bb.bpart imod 15)+1;


<------------------------------- bottominfo ------------------------------->

The runtime command "list bottominfo" prints what would be dumped in the "read"
section at the end of a dumpfile: command definitions and various toggle states.

<------------------------------- boundaries ------------------------------->
<-------------------------------- boundary -------------------------------->

Parametric "boundary" curves and surfaces can be used for locating vertices.
Vertex locations may be given in terms of parameters on a parameterized
curve or surface. Such curves or surfaces are called "boundaries" in
Evolver terminology, since they are usually used as boundary curves of
surfaces, for example a soap film on a wire loop could have the wire
implemented as a boundary. Vertices, edges, and facets may be deemed to lie
in a boundary. For a vertex, this means that the fundamental parameters of
the vertex are the parameters of the boundary, and its coordinates are
calculated from these. Vertices on boundaries may move during iteration,
unless declared fixed. See cat.fe for an example.

Boundaries are defined in the top section of the datafile. Vertices on
boundaries are listed in the datafile with their parameter values instead
of their coordinates, with "boundary n" appended to each such vertex
definition. Edges and faces on boundaries are defined as usual, but with
"boundary n" appended to each definition. So the datafile has lines like
these:

boundary 1 parameters 1
x1:  cos(p1)
x2:  sin(p1)
x3:  0.75
...
Vertices
1   0.0  boundary 1
2   pi/3 boundary 1
...
Edges
1   1 2 boundary 1
...

Putting an edge on a boundary means that vertices created on that edge will
be on the boundary. An edge on a boundary must have at least one endpoint
on the boundary, for use in extrapolating the boundary parameters of any
created vertices. Extrapolating instead of interpolating midpoint
parameters solves the problem of wrap-arounds on a boundary such as a
circle or cylinder. However if you do want interpolation, you can use the
keyword INTERP_BDRY_PARAM in the top of the datafile, or use the toggle
command interp_bdry_param. Interpolation requires that both endpoints of an
edge be on the same boundary, which cannot happen where edges on different
boundaries meet. To handle that case, it is possible to add extra boundary
information to a vertex by declaring two particular vertex extra
attributes, extra_boundary and extra_boundary_param:

interp_bdry_param
define vertex attribute extra_boundary integer
define vertex attribute extra_boundary_param real[1]

Then declare attribute values on key vertices, for example

vertices
1    0.00  boundary 1   fixed extra_boundary 2 extra_boundary_param 2*pi

If the extra_boundary attribute is not set on a vertex when wanted,
Evolver will silently fall back on interpolation.

Putting a face on a boundary means that all edges and vertices created
from refining the face will be on the boundary. In this case, the boundary
should have two parameters (or whatever the dimension of the surface is).
This is good for getting a surface to conform to a known parametric shape.
Edges on boundaries have energy and content integrals like level-set
constraints edges, but they are internally implemented as named
quantities.

Whether an element is on a particular boundary can be queried with the
on_boundary Boolean attribute. Elements can be removed from boundaries with
the unset command, and they can be set on boundaries. A typical use of
unset is to define an initial surface using a 2-parameter boundary, refine
a couple of times, then unset. Examples:
  list vertex where on_boundary 2
  unset vertex boundary 1 where on_boundary 1
  unset edge boundary 1
  unset facet boundary 1
  set vertex[10] boundary 1
It does not hurt to unset an element not on the boundary.

Vertex parameters can be accessed in expressions as the attribute p1 (and
p2,... for further parameters). Vertex parameters can be changed with the
set command. Example:
  print vertex[5].p1
  set vertex p1 p1+.1 where id < 4
  vertex[2].p1 := 3

It is not an error to access the parameters of a vertex not on a boundary
as long as some vertex is on a boundary (so that space is allocated in the
vertex structure for parameters).

A general guideline is to use constraints for two-dimensional walls and
boundaries for one-dimensional wires. If you are using a boundary wire, you
can probably declare the vertices and edges on the boundary to be FIXED.
Then the boundary becomes just a guide for refining the boundary edges.

NOTE: A vertex on a boundary cannot also have constraints.

<-------------------------- boundary declaration -------------------------->

A parameterized boundary may be declared in the top section of the
datafile with the syntax

BOUNDARY n PARAMETERS k [CONVEX]
X1: expr
X2: expr
X3: expr
[ENERGY:
 E1: expr
 E2: expr
 E3: expr]
[CONTENT:
 C1: expr
 C2: expr
 C3: expr]

This defines boundary number n, where n is a positive integer and k is the
number of parameters. If CONVEX is given, then an additional gap energy is
attributed to edges on the boundary to prevent them from trying to
short-circuit a convex boundary. The following lines have the functions for
the coordinates in terms of the parameters P1 and maybe P2, P3,.... See the
catenoid example.  Optional energy and content integrals for boundaries are
implemented, with the same syntax as for level set constraints.

<--------------------------- boundary_curvature --------------------------->

Evolver toggle command. When doing integrals of mean curvature or squared
curvature, the curvature of a boundary vertex cannot be defined by its
neighbor vertices, so the area of the boundary vertex star instead is
counted with an adjacent interior vertex.


<------------------------------ bounding box ------------------------------>

 b : Graphics mode command. Toggles display of bounding box. Useful for
visualizing orientation. In the native graphics window, the 'o' key does
the same thing.  Also see "full_bounding_box".

The default color of the bounding box is blue, but that can be changed 
by setting the variable bounding_box_color to the desired color, for example
    bounding_box_color := red

<-------------------------- bounding_box_color ----------------------------->

The default color of the bounding box in the graphics display is blue, but
that can be changed by setting the variable bounding_box_color to the
desired color, for example
    bounding_box_color := red

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


<----------------------- break after warning option ----------------------->
<-------------------------------- option ---------------------------------->

Command line option -y causes Evolver to cease execution of commands
and return to the command prompt after any warning message. Same effect
as break_after_warning runtime toggle.

<-------------------------- break_after_warning --------------------------->

Runtime toggle command. Causes Evolver to cease execution of commands and
return to command prompt after any warning message. The break does not
happen until the executing command or subcommand completes; use
break_on_warning for an instantanous break. Same effect as
command line option -y. Default is OFF.

<-------------------------- break_on_warning --------------------------->

Runtime toggle command. Causes Evolver to cease execution of commands and
return to command prompt immediately after any warning message. Does not
delay until completion of current command as break_after_warning does.
Default is OFF.

<------------------------------- breakflag -------------------------------->

Internal read-write variable. When set to a non-zero value, this
causes the command interpreter to abort and return to the command prompt.
Software equivalent of hitting the keyboard interrupt (typically CTRL-C).
The break doesn't happen immediately, but at a certain point in the
interpreter loop when it periodically checks for user interrupt. Meant for
bailing out of nested commands, since "return" only breaks out of the current
procedure.

<------------------------------- breakpoint ------------------------------->

Main prompt command. The user may set a breakpoint in an already loaded
script with the breakpoint command. The syntax is 
 
  BREAKPOINT scriptname linenumber 

where scriptname is the name of the function or procedure and linenumber
is the line number in the file where the breakpoint is to be set. There
must be executable code on the line, or you will get an error. linenumber
may be an expression. 
 
Breakpoints may be unset individually with 
 
  UNSET BREAKPOINT scriptname linenumber 

or as a group with 
 
  UNSET BREAKPOINTS 

When a breakpoint is reached, Evolver will enter into a subcommand prompt,
at which the user may enter any Evolver commands (although some commands,
such as load would be very unwise). To exit from the subcommand prompt, use
q or exit or quit. 
 
<------------------------------- brightness ------------------------------->

Internal read-only variable. Median gray level used in PostScript output and 
screen graphics.  Default value 0.65.

<---------------------------- buck_knot_energy ---------------------------->

Named method. Description: Energy between pair of edges given by formula
suggested by Greg Buck. Power law of potential is adjustable via the global
parameter `knot_power'. 

Element: edge. 
Parameters: none. 
Models: string; linear.
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

parameter knot_power  2     // the default
quantity knotten energy method buck_knot_energy global


<---------------------------------- bugs ---------------------------------->

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

<----------------------------- bunch_kauffman ----------------------------->
<----------------------------- bunch_kaufman ------------------------------>

Evolver toggle command. Toggles Bunch-Kaufman factoring of the Hessian in
the alternative minimal degree factoring method (ysmp off). This factors
the Hessian as LBL^T where L is lower triangular with ones on the diagonal,
and B is block diagonal, with 1x1 or 2x2 blocks. Supposed to be more stable
when factoring indefinite Hessians.


<-------------------------------- burchard -------------------------------->

A keyword for a special purpose command not documented.

<---------------------------------- bye ----------------------------------->
<---------------------------------- exit ---------------------------------->
<---------------------------------- quit ---------------------------------->

Main prompt command. Syntax:
    quit
    quit value
Alone, "quit" brings up a prompt to enter a new datafile.  At this prompt,
hitting the Enter key will return to the current surface, 'q' will exit
Evolver, and anything else will be taken to be the name of a new datafile.
When "quit" is followed by a value, Evolver exits immediately, and uses
the value as the exit code, which is useful when running Evolver in a
script or from some other program.  Quitting Evolver automatically 
closes any graphics windows, and does not save anything. Same as `q' command. 
"quit", "bye", and "exit" are synonyms.


<----------------------------------- c ------------------------------------>

Single letter main command. Prints counts of elements and memory used. The
memory is just the total of the element structures. On some systems,
enabling the "verbose" toggle will print more complete statistics on total 
memory usage. Synonym: counts.

Graphics mode command. Rotate clockwise about center of screen,
default 6 degrees. Integer prefix is taken as multiples of 6 degrees, and
a decimal prefix is taken as degrees for the rotation.
Examples: `15c' does 90 degree rotation, `15.0c' does 15 degree rotation.
Use upper-case C for counterclockwise rotation.

<--------------------------------- counts --------------------------------->

Main prompt command.  Long form of single-letter command 'c'.
Prints counts of elements and memory used.   The memory is just the total 
of the element structures. On some systems, enabling the  "verbose" toggle
will print more complete statistics on total memory
usage. Synonym: c.

<----------------------------------- C ------------------------------------>

Single letter main command. Runs various internal consistency checks.
Synonym: check. If no problems, just prints "Checks completed." The number
of errors found is stored in the variable check_count. The checks are:
 1. Element list integrity - checks that data structures are intact.
    This kind of error is probably an Evolver bug and should be reported.
 2. Facet-edge check - that if a facet adjoins an edge, then the edge
    adjoins the facet, and that the three edges around a facet link up.
    This kind of error is probably an Evolver bug and should be reported.
 3. Facet-body check - whether adjacent facets have the same body on the
    same side.  Probably a user problem due to mis-oriented faces in 
    body definitions in the datafile, or due to the surface getting
    kinked up at triple lines.
 4. Collapsed elements - check if endpoints of an edge are the same, and
    whether neighboring facets share more than one edge and two vertices.
    Not illegal, but you probably want to avoid.

After "C" or "check" command finishes, there are some variables that 
hold the number of errors of various types that were found:
  bad_next_prev_count - bad links in element linked lists.
  inconsistent_bodies_count - violations of adjacent facets having
     same bodies.
  edge_loop_count - edges that are loops on single vertices.
  edges_same_vertices_count - edge pairs with the same endpoints.
  facets_same_vertices_count - facet pairs with the same endpoints.
  bad_error_count - sum of the various types of errors that I consider
     serious enough that you should revise your evolution to avoid
     them. Bad links within element lists, and bad links between
     elements. 


Graphics mode command. Rotate counterclockwise about center of screen,
default 6 degrees. Integer prefix is taken as multiples of 6 degrees, and
a decimal prefix is taken as degrees for the rotation.
Examples: `15C' does 90 degree rotation, `15.0C' does 15 degree rotation.
Use lower-case c for clockwise rotation.

<---------------------- bad_next_prev_count ------------------------>
<---------------------- inconsistent_bodies_count ----------------------->
<---------------------- edge_loop_count ---------------------------->
<---------------------- edges_same_vertices_count ------------------------>
<---------------------- facets_same_vertices_count ------------------------>
<---------------------- bad_error_count -------------------------->
After "C" or "check" command finishes, there are some variables that 
hold the number of errors of various types that were found:
  bad_next_prev_count - bad links in element linked lists.
  inconsistent_bodies_count - violations of adjacent facets having
     same bodies.
  edge_loop_count - edges that are loops on single vertices.
  edges_same_vertices_count - edge pairs with the same endpoints.
  facets_same_vertices_count - facet pairs with the same endpoints.
  bad_error_count - sum of the various types of errors that I consider
     serious enough that you should revise your evolution to avoid
     them. Bad links within element lists, and bad links between
     elements. 

<----------------------------- calculate_in_3d ------------------------------>

Evolver toggle command.  The squared mean curvature named methods
star_sq_mean_curvature, star_eff_area_sq_mean_curvature,
star_normal_mean_curvature, and star_perp_sq_mean_curvature
work in any dimension space, but if for some reason the space
has an ambient dimension greater than 3, and you want to restrict
the calculation of curvature to the first three coordinates, the
toggle "calculate_in_3d" will do that.


<----------------------------- carter_energy ------------------------------>

Named method. Description: Craig Carter's energy. pre> Given bodies $B_1$
and $B_2$ in $R^3$, define the energy E = \int_{B_1}\int_{B_2} {1 \over
|z_1 - z_2|^{p} } d^3 z_2 d^3 z_1 This reduces to E = {1\over
(3-p)(2-p)}\sum_{F_2\in\partial B_2}\sum_{F_1\in\partial B_1} N_1 \cdot N_2
\int_{F_2}\int_{F_1}{1\over |z_1 - z_2|^{p-2}} d^2 z_1 d^2 z_2. And if we
crudely approximate with centroids $\bar z_1$ and $\bar z_2$, E = {1\over
(3-p)(2-p)}\sum_{F_2\in\partial B_2}\sum_{F_1\in\partial B_1} {A_1 \cdot
A_2 \over |\bar z_1 - \bar z_2|^{p-2}}, where $A_1$ and $A_2$ are
unnormalized area vectors for the facets. The power p is set by the
variable carter_power (default 6).

Element: facet. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: 3.
Hessian: no. 
Example datafile declaration:

   parameter carter_power  6     // the default
   quantity craig energy method carter_energy global


<------------------------------ carter_power ------------------------------>

Internal read-write variable for the denominator power in the formula for
the named method carter_energy.  Default value 6.

<---------------------------------- case ---------------------------------->

Upper and lower case is not significant in the datafile, except for #define
macro names.  In run-time commands, case is only significant for single-letter 
commands.


<---------------------------- catenoid example ---------------------------->

The catenoid is the minimal surface formed between two rings not too far
apart. In cylindrical coordinates (r,z), its equation is r = b*cosh(z/b), 
where b is the radius of the neck. In the sample datafile cat.fe, both the 
upper and lower rings are given as one-parameter boundary wires. The 
separation and radius are parameters, so you can change them during a run 
with assignment statements or the A command. The initial radius given is the 
minimum for which a catenoid can exist for the given separation of the rings. 
To get a stable catenoid, you will have to increase this value. However, if
you do run with the original value, you can watch the neck pinch out. The
initial surface consists of six rectangles forming a cylinder between the
two circles. The vertices on the boundaries are fixed, elsewise they would
slide along the boundary to short-cut the curvature; two diameters is
shorter than one circumference. The boundary edges are fixed so that
vertices arising from subdividing the edges are likewise fixed.


Here is the catenoid datafile:

// cat.fe
// Evolver data for catenoid.

parameter  rmax = 1.5088795   // minimum radius for height
parameter  zmax = 1.0

boundary 1 parameters 1     //  upper ring
x1:  rmax * cos(p1)
x2:  rmax * sin(p1)
x3:  zmax

boundary 2 parameters 1    //   lower ring
x1:  rmax * cos(p1)
x2:  rmax * sin(p1)
x3:  -zmax

vertices   // given in terms of boundary parameter
1    0.00  boundary 1   fixed
2    pi/3  boundary 1   fixed
3  2*pi/3  boundary 1   fixed
4    pi    boundary 1   fixed
5  4*pi/3  boundary 1   fixed
6  5*pi/3  boundary 1   fixed
7    0.00  boundary 2   fixed
8    pi/3  boundary 2   fixed
9  2*pi/3  boundary 2   fixed
10   pi    boundary 2   fixed
11 4*pi/3  boundary 2   fixed
12 5*pi/3  boundary 2   fixed

edges
1    1  2  boundary 1   fixed
2    2  3  boundary 1   fixed
3    3  4  boundary 1   fixed
4    4  5  boundary 1   fixed
5    5  6  boundary 1   fixed
6    6  1  boundary 1   fixed
7    7  8  boundary 2   fixed
8    8  9  boundary 2   fixed
9    9  10 boundary 2   fixed
10   10 11 boundary 2   fixed
11   11 12 boundary 2   fixed
12   12 7  boundary 2   fixed
13   1  7
14   2  8
15   3  9
16   4  10
17   5  11
18   6  12


faces
1   1 14 -7 -13
2   2 15 -8 -14
3   3 16 -9 -15
4   4 17 -10 -16
5   5 18 -11 -17
6   6 13 -12 -18

// End of datafile cat.fe


The parameter in a boundary definition is always P1 (and P2 in a
two-parameter boundary). The Evolver can handle periodic parameterizations,
as is done in this example.

Try this sequence of commands (displaying at your convenience):

    r       (refine to get a crude, but workable, triangulation)
    u       (equiangulation makes much better triangulation)
    g 120   (takes this many iterations for neck to collapse)
    t 0.05  (collapse neck to single vertex by eliminating all
                      edges shorter than 0.05)
    o       (split neck vertex to separate top and bottom surfaces)
    g       (spikes collapse)

The catenoid shows some of the subtleties of evolution. Suppose the
initial radius is set to rmax = 1.0 and the initial height to zmax = 0.55
(these are pre-set in catman.fe). Fifty iterations with optimizing scale
factor result in an area of 6.458483. At this point, each iteration is
reducing the area by only .0000001, the triangles are all nearly
equilateral, everything looks nice, and the innocent user might conclude
the surface is very near its minimum. But this is really a saddle point of
energy. Further iteration shows that the area change per iteration bottoms
out about iteration 70, and by iteration 300 the area is down to 6.4336.
The triangulation really wants to twist around so that there are edges
following the lines of curvature, which are vertical meridians and
horizontal circles. Hence the optimum triangulation appears to be
rectangles with diagonals.

The evolution can be speeded up by turning on the conjugate gradient
method with the U command. With catman.fe, try the script "r; u; U; g 70".
For conjugate gradient cognoscenti, the saddle point demonstrates the
difference between the Fletcher-Reeves and Polak-Ribiere versions of
conjugate gradient. The saddle point seems to confuse the Fletcher-Reeves
version (which used to be the default). However, the Polak-Ribiere version
(the current default) has little problem. The U toggles conjugate gradient
on and off, and ribiere toggles the Polak-Ribiere version. With
Fletcher-Reeves conjugate gradient in effect, the saddle point is reached
at iteration 17 and area starts decreasing again until iteration 30, when
it reaches 6.4486. But then iteration stalls out, and the conjugate
gradient mode has to be turned off and on to erase the history vector. Once
restarted, another 20 iterations will get the area down to 6.4334. In
Polak-Ribiere mode, no restart is necessary.

Exercise for the reader: Get the Surface Evolver to display an unstable
catenoid by declaring the catenoid facets to be the boundary of a body, and
adjusting the body volume with the b command to get zero pressure. See the
sample datafile catbody.fe.


<---------------------------------- ceil ---------------------------------->

 ceil(x),floor(x): Round up or down to integer.

<------------------------------ centerofmass ------------------------------>

Boolean body attribute.  Applies to the "connected" bodies mode of graphical
display in the torus model. When this is set for a body, the center of mass
of the body as displayed is remembered, and the next time a body is graphed,
its wrap is such that its new center of mass is near its previous center
of mass.  This prevents bodies near the boundaries of the fundamental 
region from jumping back and forth as they shift slightly during evolution.
Default on.  Example: 
   set bodies centerofmass

<---------------------------- central_symmetry ---------------------------->

This is the order 2 symmetry group of inversion through the origin, X -> -X.
Datafile declaration:

  symmetry_group "central_symmetry"

Group element encoding: 0 for identity, 1 for inversion.


<---------------------------- charge_gradient ----------------------------->

Named method. Description: This energy is the gradient^2 of the
knot_energy method, assuming the points are constrained to the unit sphere.

Element: vertex. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: any.
Hessian: no. 
Example datafile declaration:

  parameter knot_power  2     // the default
  quantity knotten energy method knot_energy global


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


<--------------------------------- check ---------------------------------->

Main command. Runs various internal consistency checks.
Synonym: C. If no problems, just prints "Checks completed." The number
of errors found is stored in the variable check_count. The checks are:
 1. Element list integrity - checks that data structures are intact.
    This kind of error is probably an Evolver bug and should be reported.
 2. Facet-edge check - that if a facet adjoins an edge, then the edge
    adjoins the facet, and that the three edges around a facet link up.
    This kind of error is probably an Evolver bug and should be reported.
 3. Facet-body check - whether adjacent facets have the same body on the
    same side.  Probably a user problem due to mis-oriented faces in 
    body definitions in the datafile, or due to the surface getting
    kinked up at triple lines.
 4. Collapsed elements - check if endpoints of an edge are the same, and
    whether neighboring facets share more than one edge and two vertices.
    Not illegal, but you probably want to avoid.

After "C" or "check" command finishes, there are some variables that 
hold the number of errors of various types that were found:
  bad_next_prev_count - bad links in element linked lists.
  inconsistent_bodies_count - violations of adjacent facets having
     same bodies.
  edge_loop_count - edges that are loops on single vertices.
  edges_same_vertices_count - edge pairs with the same endpoints.
  facets_same_vertices_count - facet pairs with the same endpoints.
  bad_error_count - sum of the various types of errors that I consider
     serious enough that you should revise your evolution to avoid
     them. Bad links within element lists, and bad links between
     elements. 


<------------------------------ check_count ------------------------------->

Internal read-only variable. Number of errors found by the
most recent "C" or "check" command.

<----------------------------- check_increase ----------------------------->

Evolver toggle command. Toggles checking for increase of energy in an
iteration step. If energy increases, then the step is undone and any
iteration loop is halted. Meant for early detection of instabilities and
other problems causing the surface to misbehave. Useful in doing a multiple
iteration with a fixed scale. Also applies to the hessian command. Caution:
there are circumstances where an energy increase is appropriate, for
example when there are volume or quantity constraints and conforming to the
constraints means an energy increase initially.


<-------------------------------- checking -------------------------------->

Checking your datafile

You should always check your initial datafile to be sure it is doing
exactly what you want. It is easy to get signs on integrands wrong, or
apply quantities to the wrong elements. When you load the initial datafile,
the initial energy, body volumes, and quantities values should be exactly
what you expect, either from hand calculation or from another datafile you
trust. In particular, when using constraint integrals to replace omitted
facets, I suggest you make a separate datafile with facets instead of
integrals just for checking the agreement between the two.
 With the named methods and quantities feature, it is possible to get very
detailed information on where numbers are coming from. If you give the
"convert_to_quantities" command, every energy, volume, and constraint
integrand will be internally converted to named methods and quantities
(although the user interface for all remains the same). These internal
quantities are ordinarily not displayed by the 'v' or 'Q' commands, but if
you do "show_all_quantities" then they will be displayed. Further, 'Q' will
show all the component method instances also. For an example, consider the
following output:
 Enter command: convert_to_quantities
 Enter command: show_all_quantities
 Enter command: Q
Quantities and instances:
(showing internal quantities also; to suppress, do "show_all_quantities off")
 1. default_length                        64.2842712474619  info_only quantity
                            modulus       1.00000000000000
 2. default_area                          4.00000000000000  energy quantity
                            modulus       1.00000000000000
 3. constraint_1_energy                 -0.342020143325669  energy quantity
                            modulus       1.00000000000000
 4. constraint_2_energy                 -0.342020143325669  energy quantity
                            modulus       1.00000000000000
 5. body_1_vol                            1.00000000000000  fixed quantity
                             target       1.00000000000000
                            modulus       1.00000000000000
    body_1_vol_meth                      0.000000000000000  method instance
                            modulus       1.00000000000000
    body_1_con_2_meth                     1.00000000000000  method instance
                            modulus       1.00000000000000
 6. gravity_quant                        0.000000000000000  energy quantity
                            modulus      0.000000000000000

Here's a detailed explanation of the output of the Q command above:

default_length - total edge length, using the edge_length method. This
   would be the default energy in the string model, and I guess it really
   doesn't need to exist here. But it's an info_only quantity, which means it
   is only evaluated when somebody asks to know its value.
default_area - the default energy in the soapfilm model, and included in
   the energy here, as indicated by "energy quantity" at the right.
constraint_1_energy - the energy integral of constraint 1, using the
edge_vector_integral method applied to all edges on constraint 1.
constraint_2_energy - the energy integral of constraint 2, using the
   edge_vector_integral method applied to all edges on constraint 2.
body_1_vol - the volume of body 1, as a sum of several method instances.
body_1_vol_meth is the facet_vector_integral of (0,0,z) over all the facets
   on the body. body_con_2_meth is the integral of the constraint 2 content
   integrand over all edges on facets of body 1 which are edges on constraint 2.
gravity_quant - the total gravitational energy of all bodies with assigned
   densities. This quantity is always present even if you don't have any
   bodies, or don't have any body densities. But you'll notice the modulus is
   0, which means its evaluation is skipped, so the presence of this quantity
   doesn't harm anything.

You can find the quantity or method contribution of single elements by
using the quantity or method name as an attribute of elements. Using a
quantity name really means summing over all its constituent methods that
apply to the element. For example, in plates_column,

 Enter command: foreach edge ee where on_constraint 2 do printf "%d  %f\n",id, 
   ee.body_1_con_2_meth
 5  0.000000
 6  0.000000
 7  1.000000
 8  0.000000
 Enter command: foreach edge where constraint_1_energy != 0 do 
    print constraint_1_energy
  -0.342020143325669


<--------------------------- circle_knot_energy --------------------------->

Named method. Description: This energy is due to Peter Doyle, who says it
is equivalent in the continuous case to the insulating wire with power 2.
Its form is

  E_{e_1e_2} = {L_1L_2 (1 - \cos\alpha)^2 \over |x_1 - x_2|^2},

where x_1,x_2 are the midpoints of the edges and \alpha is the angle
between edge 1 and the circle through x_1 tangent to edge 2 at x_2. Only
power 2 is implemented. 

Element: edge. 
Parameters: none. 
Models: string; linear.
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity knotten energy method circle_knot_energy global

<---------------------------- circle_willmore ----------------------------->
circle_willmore
Named method. Description: Alexander Bobenko's circle-based discrete
Willmore energy, which is conformally invariant. At each vertex, energy is
(sum of the angles between facet circumcircles) - 2*pi. More simply done as
edge quantity, since angles at each end are the same. For edge e, if
adjacent facet edge loops are a,e,d and b,c,-e, then circle angle beta for
edge has 
 
   cos(beta) = (<a,c><b,c>-<a,b><c,d>-<b,c><d,a>)/|a|/|b|/|c|/|d| 

For now, assumes all vertices are faceted, and fully starred. Severe
numerical difficulties: Not smooth when angle beta is zero, which is all
too common. Set of zero angles should be codimension 2, which means
generally avoided, but still crops up. 

Element: edge. 
Parameters: none.
Models: soapfilm; linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration: 
 
  quantity bobenko energy method circle_willmore global 

<--------------------------- circular_arc_area ---------------------------->

Named method. Description: Area between an edge and the y axis, with the
edge modelled as a circular arc through three points. Useful in the
quadratic model; in other models it is the same as edge_area. It is
particularly meant to be used as area_method_name.  

Element: edge. 
Parameters: none. 
Models: string; quadratic. 
Ambient dimension: 2. 
Orientable: yes. 
Hessian: yes. 
Example datafile declaration:

   string
   space_dimension 2
   length_method_name "circular_arc_length"
   area_method_name "circular_arc_area"

Or as a stand-alone quantity:

   quantity arcarea energy method circular_arc_area global

<--------------------------- circular_arc_draw ---------------------------->

Toggle command.  If on, then in quadratic string mode, an edge is drawn as a 
circular arc (actually 16 subsegments) through the endpoints and midpoint, 
instead of a quadratic spline.  Meant to be used when circular_arc_length and
circular_arc_area are being used.


<-------------------------- circular_arc_length --------------------------->

Named method. Description: Edge length, modelling the edge as a circular
arc through three points, hence useful only in the quadratic model. If not
in the quadratic model, it evaluates as the edge_length method. The
presence of this quantity has the side effect of automatically toggling
circular_arc_draw, causing edges to display as circular arcs in the
quadratic model. Particularly meant for length_method_name.

Element: edge. 
Parameters: none. 
Models: string; quadratic.
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

   string
   space_dimension 2
   length_method_name "circular_arc_length"
   area_method_name "circular_arc_area"

Or as a stand-alone quantity:

   quantity arclen energy method circular_arc_length global

<-------------------------------- clipped --------------------------------->
<----------------------------- clipped_cells ------------------------------>

Evolver toggle command. Sets torus model graphics display to clip to the
unit cell parallelogram or parallelpiped. Not an on-off toggle, but a 3-way 
toggle with raw_cells and connected. Clipped_cells and clipped are synonyms.
The origin (lower left back corner) of the unit cell can be set by setting 
entries in the display_origin vector.

Default is unset, so Evolver prompts the user when graphics are first 
displayed.  The setting persists when loading a new surface.  But loading a 
torus model when a non-torus model is currently displayed will not prompt.

Also see display_periods and display_origin for more control of "clipped" 
mode.

<------------------------------- clip_coeff ------------------------------->

Internal 2-dimensional array holding clip plane coefficients for graphics
displays.  See clip_view for details.

<------------------------------- clip_view -------------------------------->

Main prompt command that toggles user-defined clipping planes. It is 
possible to have the graphics display clip the surface with multiple
clipping planes. A clipping plane is defined by a plane of the form 
ax + by + cz = d. The visible volume is ax + by + cz <= d. Up to 10 
clipping planes may be stored in the array clip_coeff[][], with the 
first plane coefficients a,b,c,d stored in clip_coeff[1][1] through 
clip_coeff[1][4], etc. The user does not have to create clip_coeff[][],
and Evolver will initialize it with a default vertical plane through
the middle of the surface. 

To use clip view, first set the coefficients of however many clip planes 
you want and then use the clip_view toggle. For example, to get a vertical 
clipping plane parallel to the y and z axes and a little in front of them: 
 
   clip_coeff[1][1] := 1; 
   clip_coeff[1][2] := 0; 
   clip_coeff[1][3] := 0; 
   clip_coeff[1][4] := .2; 
   clip_view; 

With OpenGL graphics, the first clip plane plane can be varied interactively 
by hitting the 'l' key (lower case L) in the graphics window and dragging 
the mouse horizontally.  The 'k' key will make mouse dragging change the 
orientation of the clip plane. Hit 'r' or 'c' or 't' to get back to
another mouse mode.  The 'L' key will end clip_view.

Clip_view works separately, and after, torus model viewing modes such as
clipped and connected, so it is no problem to have them together. 
In case clip_view and slice_view are both in effect, slice_view operates
instead of clip_view. 

<--------------------------------- clock ---------------------------------->

Internal read-only variable. Total elapsed Evolver execution time
in seconds. Reads system process elapsed time, which often has a fairly
coarse resolution of 0.01 seconds. For nanosecond timing, see cpu_counter.

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

<--------------------------------- color ---------------------------------->

As a keyword, "color" is a read-write attribute of edges and facets. For the
permitted values, see "colors".

<------------------------------- colorfile -------------------------------->

Internal read-write variable.  Name of colormap file used in certain
graphics output.  See the P command. Use COLORFILE := "filename" to set file.

<-------------------------------- colormap -------------------------------->

Evolver toggle command. Use a colormap from a file in certain graphics output.
See the P command. Use COLORFILE := "filename" to set file.

<----------------------------- column example ----------------------------->

Example: Column of liquid solder

Here we have a tiny drop of liquid solder that bridges between two
parallel, horizontal planes at z = 0 and z = ZH. On each plane there is a
circular pad that the solder perfectly wets, and the solder is perfectly
nonwetting off the pads. This would be just a catenoid problem with fixed
volume, except that the pads are offset, and it is desired to find out what
aligning force the solder exerts. The surface is defined the same way as in
the catenoid example, except the lower boundary ring has a shift variable
"SHIFT" in it to provide an offset in the y direction. This makes the shift
adjustable at run time. Since the top and bottom facets of the body are not
included, the constant volume they account for is provided by content
integrals around the upper boundary, and the gravitational energy is
provided by an energy integral. One could use the volconst attribute of the
body instead for the volume, but then one would have to reset that every
time ZH changed.

The interesting part of this example is the calculation of the forces. One
could incrementally shift the pad, minimize the energy at each shift, and
numerically differentiate the energy to get the force. Or one could set up
integrals to calculate the force directly. But the simplest method is to
use the Principle of Virtual Work by shifting the pad, recalculating the
energy without re-evolving, and correcting for the volume change.
Re-evolution is not necessary because when a surface is at an equilibrium,
then by definition any perturbation that respects constraints does not
change the energy to first order. To adjust for changes in constraints such
as volume, the Lagrange multipliers (pressure for the volume constraint)
tell how much the energy changes for given change in the constraints:

          DE = L*DC

where DE is the energy change, L is the row vector of Lagrange multipliers
and DC is the column vector of constraint value changes. Therefore, the
adjusted energy after a change in a parameter is

          E_adj = E_raw - L*DC

where E_raw is the actual energy and DC is the vector of differences of
constraint values from target values. The commands do_yforce and do_zforce
in the datafile do central difference calculations of the forces on the top
pad, and put the surface back to where it was originally. Note that the
perturbations are made smoothly, i.e. the shear varies linearly from bottom
to top. This is not absolutely necessary, but it gives a smoother
perturbation and hence a bit more accuracy.

The initial column skeleton, with vertices and edges numbered.



// column.fe
// Example of calculating forces exerted by a
// column of liquid solder in shape of skewed catenoid.


// All units cgs
parameter RAD = 0.05     // ring radius
parameter ZH = 0.08      // total height
parameter SHIFT = 0.025    // shift
#define SG 8      // specific gravity of solder
#define TENS 460  // surface tension of solder
#define GR  980   // acceleration of gravity

gravity_constant GR

BOUNDARY 1  PARAMETERS 1
X1: RAD*cos(P1)
X2: RAD*sin(P1) + SHIFT
X3: ZH
CONTENT  // used to compensate for missing top facets
c1: 0
c2: -ZH*x
c3: 0
ENERGY  // used to compensate for gravitational energy under top facets
e1: 0
e2: GR*ZH^2/2*x
e3: 0

BOUNDARY 2  PARAMETERS 1
X1: RAD*cos(P1)
X2: RAD*sin(P1)
X3: 0

vertices   // given in terms of boundary parameter
1    0.00  boundary 1   fixed
2    pi/3  boundary 1   fixed
3  2*pi/3  boundary 1   fixed
4    pi    boundary 1   fixed
5  4*pi/3  boundary 1   fixed
6  5*pi/3  boundary 1   fixed
7    0.00  boundary 2   fixed
8    pi/3  boundary 2   fixed
9  2*pi/3  boundary 2   fixed
10   pi    boundary 2   fixed
11 4*pi/3  boundary 2   fixed
12 5*pi/3  boundary 2   fixed

edges
1    1  2  boundary 1   fixed
2    2  3  boundary 1   fixed
3    3  4  boundary 1   fixed
4    4  5  boundary 1   fixed
5    5  6  boundary 1   fixed
6    6  1  boundary 1   fixed
7    7  8  boundary 2   fixed
8    8  9  boundary 2   fixed
9    9  10 boundary 2   fixed
10   10 11 boundary 2   fixed
11   11 12 boundary 2   fixed
12   12 7  boundary 2   fixed
13   1  7
14   2  8
15   3  9
16   4  10
17   5  11
18   6  12

faces
1   1 14  -7 -13   density TENS
2   2 15  -8 -14   density TENS
3   3 16  -9 -15   density TENS
4   4 17 -10 -16   density TENS
5   5 18 -11 -17   density TENS
6   6 13 -12 -18   density TENS

bodies
1    -1 -2 -3 -4 -5 -6 volume 0.00045 density SG

read

// horizontal force on upper pad by central differences
dy := .0001
do_yforce := { oldshift := shift; shift := shift + dy;
               set vertex y  y+dy*z/zh; // uniform shear
               recalc;
               energy1 := total_energy -
                     body[1].pressure*(body[1].volume - body[1].target);
               oldshift := shift; shift := shift - 2*dy;
               set vertex y  y-2*dy*z/zh; // uniform shear
               recalc;
               energy2 := total_energy -
                     body[1].pressure*(body[1].volume - body[1].target);
               yforce := -(energy1-energy2)/2/dy;
               printf "restoring force: %20.15f\n",yforce;
               // restore everything
               oldshift := shift; shift := shift + dy;
               set vertex y  y+dy*z/zh; // uniform shear
               recalc;
             }


// vertical force on upper pad by central differences.
dz := .0001
do_zforce := { oldzh := zh; zh := zh + dz;
               set vertex z  z+dz*z/oldzh; recalc; // uniform stretch
               energy1 := total_energy -
                     body[1].pressure*(body[1].volume - body[1].target);
               oldzh := zh; zh := zh - 2*dz;
               set vertex z  z-2*dz*z/oldzh; recalc; // uniform stretch
               energy2 := total_energy -
                     body[1].pressure*(body[1].volume - body[1].target);
               zforce := -(energy1-energy2)/2/dz;
               printf "vertical force:  %20.15f\n",zforce;
               // restore everything
               oldzh := zh; zh := zh + dz;
               set vertex z  z+dz*z/oldzh; recalc; // uniform stretch
             }

// end of datafile

<----------------------------- combinatorics ------------------------------>

Surface representation and combinatorics:
All surfaces are simplicial complexes made of the basic elements:
vertices, edges, and facets. The Evolver has three different ways of
representing the combinatorics of the surface, depending on the dimension
of the surface. Any of these may be used in any ambient space dimension at
least as great at the surface dimension.
 String model for dimension 1 surface.
 Soapfilm model (default) for dimension 2 surface.
 Simplex model for dimension 3 or higher surface.

<--------------------------- command definition --------------------------->

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}

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

<--------------------------- command separator ---------------------------->
<------------------------------- semicolon -------------------------------->

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. You do need to use a semicolon to separate a compound 
command from the next command. 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
             };  // note the semicolon, even after }
      g 10;

<-------------------------------- comments -------------------------------->

Comments may be enclosed in /* */ pairs (as in C) and may span lines.
Also, // indicates the rest of the line is a comment, as in C++.


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

<------------------------- compressibility energy ------------------------->

If the ideal gas mode is in effect (set by the PRESSURE keyword in the
datafile), then each body contributes an energy

         E = P*V_0*ln(V/V_0)

where P is the ambient pressure, V_0 is the target volume of the body, and
V is the actual volume. To account for work done against the ambeint
pressure, each body also makes a negative contribution of

         E = -P*V.

The ambient pressure can be set in the datafile or with the p command.
This energy is calculated only for bodies given a target volume.

<------------------------------ conditional ------------------------------->

A conditional expression has the same syntax as in the C language:

 expr1 ? expr2 : expr3

evaluates to expr2 if expr1 is nonzero and to expr3 if expr1 is zero.
It is wise to use parentheses around the expressions to ensure the correct
order of evaluation.


<------------------------- conducting_knot_energy ------------------------->

Datafile keyword that automatically creates an energy named quantity using
the method knot_energy as a global method. May be followed in the datafile
with a modulus value.

<------------------------------- conf_edge -------------------------------->

Evolver toggle command. Calculation of squared curvature by fitting sphere
to edge and adjacent vertices (conformal curvature).  Only applies to
square_curvature as declared in the top of the datafile, not to
the squared curvature named methods.

<---------------------------- conformal_metric ---------------------------->

The ambient space can be endowed with a conformal Riemannian metric by
putting the keyword CONFORMAL_METRIC in the datafile followed by a formula
for the conformal factor, i.e. the multiple of the identity matrix that
gives the metric. Only one coordinate patch is allowed, but the quotient
space feature makes this quite flexible. Edges and facets are linear in
coordinates, they are not geodesic. The metric is used solely to calculate
lengths and areas. It is not used for volume. To get a volume constraint on
a body, you will have to define your own named quantity constraint. See
quadm.fe for an example of a metric. Example datafile declaration:

  CONFORMAL_METRIC 1/(1 - x^2 - y^2 - z^2)

<------------------------------- conj_grad -------------------------------->

Evolver toggle command. Use the conjugate gradient method in g command.
Synonym for "U" command.  See "conjugate gradient" for an explanation
of the method.

<--------------------------- conjugate gradient --------------------------->

"Conjugate gradient" is a method of accelerating gradient descent. In
ordinary gradient descent, one uses the gradient of energy to find the
steepest downhill direction, then moves along that line to the minimum
energy in that direction. Hence successive steps are at right angles.
However, this can be very inefficient, as you can spend a lot of time
zigzagging across an energy "valley" without making much progress
"downstream". With conjugate gradient, the search direction is chosen to be
in a "conjugate" direction to the previous direction. For a mathematical
explanation, see any decent book in numerical analysis, such as [P]. In
practice, the conjugate gradient method remembers a cumulative "history
vector", which it combines with the ordinary gradient to figure out the
conjugate gradient direction. The upshot is that conjugate gradient can
converge much faster than ordinary gradient descent.

Conjugate gradient can be toggled with the "U" command, or with the
"conj_grad" toggle. It should always be used with optimizing scale.

Notes: The conjugate gradient method is designed for quadratic energy
functions. As long as the energy function is nearly quadratic, as it should
be near an energy minimum, conjugate gradient works well. Otherwise, it may
misbehave, either by taking too big steps or by getting stalled. Both
effects are due to the history vector being misleading. To prevent too big
steps, one should iterate without conjugate gradient for a few steps
whenever significant changes are made to the surface (refining, changing a
constraint, etc.). On the other hand, if it looks like conjugate gradient
is converging, it may have simply become confused by its own history. See
the catenoid example for a case in point. A danger signal is the scale
factor going to zero. If you are suspicious, toggle conjugate gradient off
and on ("U 2" does nicely) to erase the history vector and start over.
See the "ribiere" toggle for switching between the default Fletcher-Reeves
version and the Ribiere version of conjugate gradient.

<------------------------------- connected -------------------------------->
<---------------------------- connected_cells ----------------------------->

Evolver toggle command. Sets torus model display to do each body as a
connected, wrapped surface. Not an on-off toggle, but a 3-way toggle with 
"clipped" and "raw_cells". Synonym: "connected_cells".  Since slight motions 
during evolution can cause the wrap to change suddenly, there is a body 
boolean attribute "centerofmass" that causes the center of mass of a
body to be remembered, and the next time a body is plotted, the wrap
is adjusted so the center of mass is close to the previous center of mass.
"Connected" and "connected_cells" are synonyms.

Default is unset, so Evolver prompts the user when graphics are first 
displayed.  The setting persists when loading a new surface.  But loading 
a torus model when a non-torus model is currently displayed will not prompt.


<------------------------------- conserved -------------------------------->
<--------------------------- conserved quantity --------------------------->

A use-type of named quantity, along with "energy", "fixed", and "info_only".
A "conserved" named quantity is like a fixed quantity, but the value is
irrelevant. The quantity gradient is used to eliminate a degree of freedom
in motion.  Rarely used, but useful to eliminate rotational degrees of
freedom, for example. Will not work with optimizing parameters, since they
do gradients by numerical differences.

<------------------------------- console_title -------------------------------->

Evolver internal read-write string variable.  This is the title that is
displayed on the Evolver command console window.  The default value is 
"Surface Evolver - datafilename" (with the name of the current datafile, of
course).  Useful when you are simultaneously running various instances, and
you want to tell which is running in which console window.  Just assigning
a string to console_title automatically changes the title on the window.

<-------------------------- constant expressions -------------------------->
<------------------------------- constexpr -------------------------------->

Constant expressions are evaluated when parsed. They are denoted by
constexpr in various syntax definitions. They occur mostly in the datafile.
Although they may contain variables, changing the variable value after
parsing has no effect. Variable expressions (denoted by expr in syntax
definitions) are recorded as parse trees and are re-evaluated each time
needed.

<------------------------------- constraint ------------------------------->
<------------------------------ constraints ------------------------------->

"Constraint" can be used in a general sense, but as a keyword it refers to
level set constraints. "Constraint" and "constraints" are interchangeable
in syntax.  See "level set constraints" for more, and "constraint decl"
for datafile syntax.

<------------------------- constraint declaration ------------------------->

The format for declaring a level set constraint in the top section of the
datafile is

CONSTRAINT n [GLOBAL] [CONVEX] [NONNEGATIVE] [NONPOSITIVE] [NONWALL]
FORMULA FUNCTION  expr
[ENERGY:
 E1: expr
 E2: expr
 E3: expr]
[CONTENT:
 C1: expr
 C2: expr
 C3: expr]

The same syntax also works at runtime, but it is wise to enclose the
entire definition in curly braces to guarantee Evolver reads the definition
as a single unit and is not confused by line breaks.

You may use EQUATION or FUNCTION as synonyms for FORMULA. This defines
constraint number n, where n is a positive integer. The optional keyword
GLOBAL means the constraint automatically applies to all vertices (but not
automatically to edges or faces). GLOBAL constraints count in the number
limit. If CONVEX is given, then an additional gap energy is attributed to
edges on the constraint to prevent them from trying to short-circuit a
convex boundary. NONWALL indicates this constraint is to be ignored in
vertex and edge popping. If NONNEGATIVE or NONPOSITIVE is given, then this
is a one-sided constraint, and all vertices will be forced to conform
appropriately to the constraint at each iteration. The FORMULA expression
defines the zero level set which is the actual constraint. It may be
written as an equation, since '=' is parsed as a low-precedence minus sign.
The formula may include any expressions whose values are known to the
Evolver, given the particular vertex. Most commonly one just uses the
coordinates (x,y,z) of the vertex, but one can use variables, quantity
values, or vertex extra attributes. Using a vertex extra attribute is a
good way to customize one formula to individual vertices. For example, if
there were a vertex extra attribute called zfix, one could force vertices
to individual z values with one constraint with the formula z = zfix, after
of course assigning proper values to zfix for each vertex (be sure to fix
up zfix after refining or otherwise creating vertices). Do not use '>' or
'<' to indicate inequalities; use NONNEGATIVE or NONPOSITIVE. Conditional
expressions, as in C language, are useful for defining constraints composed
of several surfaces joined smoothly, such as a cylinder with hemispherical
caps. Assignments to variables may be made at the start of expressions,
mainly for the purpose of evaluating common subexpressions only once in the
integrands. The syntax for such a compound expression is

    variable :=  expr, expr

The value of the expression is the value of the second expression.

The optional ENERGY section signifies that vertices or edges on the
constraint are deemed to have an energy. In the soapfilm model, the next
lines give components of a vectorfield that will be integrated along each
edge on the constraint. In the string model, just one component is needed,
which is evaluated at each vertex on the constraint. The main purpose of
this is to permit facets entirely on the constraint to be omitted. Any
energy they would have had should be included here. One use is to get
prescribed contact angles at a constraint. This energy should also include
gravitational potential energy due to omitted facets. Integrals are now
also evaluated on fixed edges, which is a change from earlier versions of
Evolver.

The optional CONTENT section signifies that vertices (string model ) or
edges (soapfilm model) on the constraint contribute to the area or volume
of bodies. If the part of a body boundary that is on a constraint is not
defined by facets, then the body volume must get a contribution from a
content integral. It is important to understand how the content is added to
the body in order to get the signs right. The integral is evaluated along
the positive direction of the edge. If the edge is positively oriented on a
facet, and the facet is positively oriented on a body, then the integral is
added to the body. This may wind up giving the opposite sign to the
integrand from what you think may be natural. Always check a new datafile
when you load it to be sure the integrals come out right.


<---------------------- constraint energy integrals ----------------------->

An edge on a level-set constraint may have an energy given by integrating
a vectorfield F over the oriented edge:

           E = \int_{edge} F . dl.

The integrand is defined in the constraint declaration in the datafile.
The integral uses the innate orientation of the edge, but if the
orientation attribute of the edge is negative, the value is negated. This
is useful for prescribed contact angles on walls (in place of wall facets
with equivalent tension) and for gravitational potential energy that would
otherwise require facets in the constraint. The mound example illustrates
this.   See "constraint decl" for syntax.

<-------------------------- constraint fixed -------------------------->

Whether a particular level-set constraint is an equality constraint or
a one-sided constraint can be queried at runtime by the expression
     is_constraint[number].fixed
or   is_constraint[name].fixed
"number" may be an expression; "name" is the unquoted name of the
constraint, if it has one. This has value 1 if the constraint is an 
equality constraint, else the value is zero.  Example of listing all 
the equality constraints that vertices are on:
   foreach vertex vv do
   { for ( inx := 1 ; inx < vv.v_constraint_list[1] ; inx++ )
       if is_constraint[vv.v_constraint_list[i+1]].fixed then
         printf "Vertex %d on equality constraint %d\n",
           vv.id,vv.v_constraint_list[i+1];
   };

<-------------------------- constraint normal -------------------------->

The unit normal vector of a level-set constraint at a vertex may be
found with the vertex vector attribute 
             constraint[number].normal
or           constraint[name].normal
"number" may be an expression; "name" is the unquoted name of the
constraint, if it has one.  Example:
  print vertex[1].constraint[floorcon].normal
would print the unit normal of constraint floorcon at vertex 1.  And
you can put on a subscript to get individual components.  For example,
the y component:
  print vertex[1].constraint[floorcon].normal[2]

There is no necessity for the constraint to be applied to the vertex; 
the vertex is just used as a source of coordinates for evaluating the 
gradient of the constraint formula.



<-------------------------- constraint_tolerance -------------------------->

Internal read-write variable. When vertices are projected to level-set
constraints, projection by Newton's method is repeated until the level-set
function is smaller than constraint_tolerance.  Default value 1e-12.
Example runtime usage:

  constraint_tolerance := 1e-10;
  
There is also a top-of-datafile declaration with the syntax

  CONSTRAINT_TOLERANCE constexpr

<-------------------------------- content --------------------------------->

"Content" is used to mean volume (or area, in the string model) in
constraint integrals.  See "constraint decl".

<------------------------------ content_rank ------------------------------>

A level-set constraint attribute used in conjunction with content integrals.  
If a vertex (string model) or an edge (soapfilm model) is on multiple 
constraints with content integrals (say where walls meet) then if content 
ranks are present, the content integral with the least rank will contribute 
to the content on the negative side body and the highest rank content
will contribute to the content of the positive side body.

<-------------------------------- continue -------------------------------->

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

   CONTINUE

   CONTINUE n

where n is a positive integer.  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;
       }
   }

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

<------------------------- convert_to_quantities -------------------------->

Evolver main prompt command. This will do an automatic conversion of old-style
energies to new-style named quantities. This has the same effect as the -q
command line option, but can be done from the Evolver command prompt.
A few energies don't convert yet. It is my intention that this will be the
default sometime in the near future, if it can be made sufficiently fast
and reliable. If everything has been converted to quantities one way or 
another, the internal variable everything_quantities is set to 1.
Convert_to_quantities cannot be undone. Useful when hessian complains 
about not being able to do a type of energy. It is also useful when 
setting up a datafile, since the `Q' command will show all the internal 
quantities individually (when the show_all_quantities toggle is on), so 
you can tell what value each constraint integral has and so forth.


<--------------------------------- convex --------------------------------->
<--------------------------- convex constraint ---------------------------->

A keyword used in declaring a constraint in the datafile that causes a gap
energy to be included. The idea is to prevent straight edges and facets
from short-cutting curved constraints with big gaps.  See "gap energy".

A constraint may be declared CONVEX, in which case edges in the constraint
have an energy associated with them that is proportional to the area
between the straight edge and the curved wall. This energy (referred to as
"gap energy") is meant to compensate for the tendency for flat facets
meeting a curved wall to minimize their area by lengthening some edges on
the wall and shortening others, with the net effect of increasing the net
gap between the edges and the wall. See tankex.fe for an example.

<------------------------------ coordinates ------------------------------->

Vertex read-write attribute. The coordinates of a vertex are its location
in space. By default, these are Euclidean coordinates, but they may
represent any coordinate system if the user defines appropriate length,
area, volume, etc. integrals. But graphics always treat the coordinates as
Euclidean. The individual coordinates may be referred to as x,y,z,w or
x1,x2,x3,... or x[1], x[2], x[3],... In the vertices section of the datafile,
 vertices of the original surface have their coordinates given unless they
are on a parametric boundary. Vertices on parametric boundaries have their
coordinates calculated from their parameter values. Coordinates may be read
or modified with the command language. Examples:

  foreach vertex do printf "%g  %f %f %f\n",id,x,y,z
  set vertex z z+.1*x

The coordinates may also be referred to as a vector __x, which is useful
in vector expressions such as

   define vertex attribute savedx real[3];
   set vertex savedx __x;
   vertex[7].__x := {1.2,0.4,2.3}
  
<------------------------------ corona_state ------------------------------>
corona_state 
Internal read-write variable for MPI  Evolver.  The "corona" of
a task's piece of surface is the set of elements imported from 
other tasks, so the task has sufficient knowlegde to do its work.
The possible corona_state values are 0 (no corona), 1 (import
neighbor edges and vertices), or 2 (import neighbor vertices, 
edges, and facets). Setting this variable changes the corona state. 
It is a very bad idea to set it to 0. 

<---------------------------------- cos ----------------------------------->

 sin(x),cos(x),tan(x): Trig functions, argument in radians.

<---------------------------------- cosh ---------------------------------->

 sinh(x),cosh(x),tanh(x): Hyperbolic functions.

<------------------------------ cpu_counter ------------------------------->

Internal read-only variable. Processor cycle counter, available only on
systems where I know how to access this (x86 for now). Gives the number 
of CPU cycles since the system booted. Note that this is wall clock time, 
not process time. Also note that it resets to zero when a notebook 
computer hibernates, so it is not guaranteed to be monotone
increasing during the life of a process!

<---------------------------- ps_crossingflag ----------------------------->
<------------------------------ crossingflag ------------------------------>

Evolver toggle command. When "on" and the string model is in effect,
postscript output will show background edges with a break where foreground
edges pass in front.  "crossingflag" is an old name for "ps_crossingflag".


<------------------------------- crossings -------------------------------->

The interactive PostScript command "P 3" asks about several options.
"Do crossings?" is asked if the surface is 1-dimensional (the string
model) and the dimension of space is at least 3. If you reply 'y', a 3D
effect will be created by plotting edges back to front, with each edge
plotted first as a thick white line and then as a thin black line. This
creates a broken back line and continuous foreground line at each crossing.
Default 'n'. The postscript command uses the ps_crossingflag toggle to control
this.

<--------------------------- crystalline energy --------------------------->

The Evolver can model energies of crystalline surfaces. These energies are
proportional to the area of a facet, but they also depend on the direction
of the normal. The energy is given by the largest dot product of the
surface normal with a set of vectors known as the Wulff vectors. Surface
area can be regarded as a crystalline integrand whose Wulff vectors are the
unit sphere. See the datafile section on Wulff vectors for more. A surface
has either crystalline energy or surface tension, not both. Use is not
recommended since nonsmoothness makes Evolver work poorly.
 Example datafile: crystal.fe

<------------------------------ cube example ------------------------------>

Example: Cube evolving into a sphere.

A sample datafile cube.fe comes with Evolver. The initial surface is a
unit cube. The surface bounds one body, and the body is constrained to have
volume 1. There is no gravity or any other force besides surface tension.
Hence the minimal energy surface will turn out to be a sphere. This example
illustrates the basic datafile format and some basic commands.

This is the datafile that specifies the initial unit cube:

// cube.fe
// Evolver data for cube of prescribed volume.

vertices  /* given by coordinates */
1  0.0 0.0 0.0
2  1.0 0.0 0.0
3  1.0 1.0 0.0
4  0.0 1.0 0.0
5  0.0 0.0 1.0
6  1.0 0.0 1.0
7  1.0 1.0 1.0
8  0.0 1.0 1.0

edges  /* given by endpoints */
1   1 2
2   2 3
3   3 4
4   4 1
5   5 6
6   6 7
7   7 8
8   8 5
9   1 5
10  2 6
11  3 7
12  4 8

faces  /* given by oriented edge loop */
1   1 10 -5  -9
2   2 11 -6 -10
3   3 12 -7 -11
4   4  9 -8 -12
5   5  6  7   8
6  -4 -3 -2  -1

bodies  /* one body, defined by its oriented faces */
1   1 2 3 4 5 6  volume 1

// end of cube.fe

The datafile is organized in lines, with one geometric element defined per
line. Vertices must be defined first, then edges, then faces, then bodies.
Each element is numbered for later reference in the datafile.
Comments are delimited by /* to begin and */ to close as in C, or from //
until the end of the line as in C++. Case is not significant, and all input
is made lower-case immediately. Hence error messages about your datafiles
will refer to items in lower case, even when you typed them in upper case.

The datafile syntax is based on keywords. The keywords VERTICES, EDGES,
FACES, and BODIES signal the start of the respective sections. Note that
the faces are not necessarily triangles (which is why they are called FACES
and not FACETS). Any non-triangular face will be automatically triangulated
by putting a vertex at its center and putting in edges to each of the
original vertices. Faces don't have to be planar. Note that a minus sign on
an edge means that the edge is traversed in the opposite direction from
that defined for it in the EDGES section. A face's oriented normal is
defined by the usual right hand rule. The cube faces all have outward
normals, so they all are positive in the body list. In defining a body, the
boundary faces must have outward normals. If a face as defined has an
inward normal, it must be listed with a minus sign.

That the body is constrained to have a volume of 1 is indicated by the
keyword VOLUME after the body definition, with the value of the volume
following. Any attributes or properties an element has are given on the
same line after its definition.


Start Evolver and load the datafile with the command line

     evolver cube.fe

(or you can drag cube.fe and drop it on the evolver executable, or whatever
you do to launch evolver.)

You should get a prompt

     Enter command:

Give the command s to show the surface. You should see a square divided
into four triangles by diagonals. This is the front side of the cube; you
are looking in along the positive x-axis, with the z axis vertical and the
positive y axis to the right. On most systems, you can manipulate the
displayed surface with the mouse: dragging the mouse over the surface with
the left button down rotates the surface; you can change to "zoom" mode by
hitting the z key, to "translate" by hitting t, to "spin" by hitting c, and
back to "rotate" by hitting r. Hit the 'h' key with the mouse focus in the
graphics window to get a summary of the possibilities. You can also give
graphics commands at the graphics command prompt; this is good for precise
control. The graphics command prompt is

     Graphics command:

It takes strings of letters, each letter making a viewing transformation
on the surface: The most used ones are

           r   rotate right by 6 degrees
           l   rotate left by 6 degrees
           u   rotate up by 6 degrees
           d   rotate down by 6 degrees
           R   reset to original position
           q   quit back to main command prompt

Try typing rrdd to get an oblique view of the cube. Any transformations
you make will remain in effect the next time you show the surface. Now do q
to get back to the main prompt.  Actually, it's a lot simpler to use the
mouse to drag around the graphics image, but the graphics prompt remains
for backwards compatibility and the ability to do precision motions.

If you are using geomview for graphics, do command P option 8 to get a
display, or just "P 8" for short. Geomview takes a couple of seconds to
initialize. You can manipulate the geomview display as usual independently
of the Evolver. Evolver will automatically update the image whenever the
surface changes.

Now do some iterations. Give the command "g 5" to do 5 iterations. You
should get this:

  5. area:  5.11442065156005 energy:  5.11442065156005  scale: 0.186828
  4. area:  5.11237323810972 energy:  5.11237323810972  scale: 0.21885
  3. area:  5.11249312304592 energy:  5.11249312304592  scale: 0.204012
  2. area:  5.11249312772740 energy:  5.11249312772740  scale: 0.204386
  1. area:  5.11249312772740 energy:  5.11249312772740  scale: 0
Enter command:

Note that after each iteration a line is printed with the iterations
countdown, area, energy, and current scale factor. By default, the Evolver
seeks the optimal scale factor to minimize energy. At first, there are
large motions, and the volume constraint may not be exactly satisfied.
There may be an energy increase due to the volume constraint taking hold.
At the end, the scale is 0 because the surface has converged as well as it
can at this coarse a triangulation. (Different systems may not give a zero
scale here due to numerics.)

Volume constraints are not strictly enforced, but each iteration tries to
bring the volume closer to the target. Here that results in increases in
area. You can find the current volumes with the v command:

  Body       target volume         actual volume        pressure
    1     1.000000000000000     0.999999779366360   3.408026016427987

The pressure in the last column is actually the Lagrange multiplier for
the volume constraint. Now let's refine the triangulation with the r
command. This subdivides each facet into four smaller similar facets. The
printout here gives the counts of the geometric elements and the memory
they take:

  Vertices: 50 Edges: 144 Facets: 96  Facetedges: 288 Memory: 27554

Iterate another 10 times:

 10. area: 4.908899804670224 energy: 4.908899804670224  scale: 0.268161
  9. area: 4.909526310166165 energy: 4.909526310166165  scale: 0.204016
  8. area: 4.909119925577212 energy: 4.909119925577212  scale: 0.286541
  7. area: 4.908360229118204 energy: 4.908360229118204  scale: 0.304668
  6. area: 4.907421919968726 energy: 4.907421919968726  scale: 0.373881
  5. area: 4.906763705259419 energy: 4.906763705259419  scale: 0.261395
  4. area: 4.906032256943935 energy: 4.906032256943935  scale: 0.46086
  3. area: 4.905484754688263 energy: 4.905484754688263  scale: 0.238871
  2. area: 4.904915540917190 energy: 4.904915540917190  scale: 0.545873
  1. area: 4.904475138593070 energy: 4.904475138593070  scale: 0.227156

You can continue iterating and refining as long as you have time and memory.
Eventually, you will want to quit. So give the q command. You get

     Enter new datafile name (none to continue, q to quit):

You can start a new surface by entering a datafile name (it can be the
same one you just did, to start over), or continue with the present surface
by hitting ENTER with no name (in case you pressed q by accident, or
suddenly you remember something you didn't do), or you can really quit with
another q.

<-------------------------------- cubelat --------------------------------->
<------------------------- cubelat symmetry group ------------------------->

Cubelat is the full symmetry group of the unit cubic lattice.  That is, all 
permutations and sign changes of the coordinates, together with translating
by integer vectors.

Datafile declaration: symmetry_group "cubelat"

Wrap encoding: wrap&{1,2,4} give sign changes for x,y,z; 
              (wrap&24)/8 is power of (xyz) to cycle 
              (wrap&32)/32 tells whether to then swap x,y; that is, wrap&63 
                 is the same as for cubocta. 
              Then wrap/64 is a torus wrap as in the torus symmetry group: 
                 three six-bit signed fields for translation in each 
                 coordinate.  
Translation is to be applied after other operations.

<-------------------------------- cubocta --------------------------------->
<------------------------- cubocta symmetry group ------------------------->

Cubocta is the full symmetry group of the cube. It can be viewed as all
permutations and sign changes of (x,y,z).
Datafile declaration: symmetry_group "cubocta"
Group element encoding: 
    wrap & {1,2,4} give the sign changes for x,y,z;
    (wrap&24)/8 is the power of the (xyz) permutation cycle; 
    (wrap&32)/32 tells whether to then swap x,y. 
(By John Sullivan; source in quotient.c under name pgcube)

<--------------------------- curvature_binormal --------------------------->

Named method. Description: For string model. The energy evaluates to zero,
but the force calculated is the mean curvature vector rotated to the
binormal direction. 

Element: vertex. 
Parameters: none. 
Models: string; linear.
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration:

   quantity curbi energy method curvature_binormal global


<--------------------------- curvature_function --------------------------->

Named method. Description: Calculates forces as function of mean and
Gaussian curvatures at vertices. Function may be changed by user by
altering teix.c. No energy, just forces. 

Element: vertex. 
Parameters: none.
Models: soapfilm; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity curfun energy method curvature_function global

<---------------------------- curvature_power ----------------------------->

Internal read-write variable that sets the power of curvature used
in the string model when squared_curvature is declared in the top
of the datafile or the sqcurve_string named method is used.

<----------------------------------- d ------------------------------------>

Single letter main command. Dumps data to ASCII file in same format as an
initial data file. You will be prompted for a filename. An empty reponse
will use the default dump name, which is the datafile name with a ".dmp"
extension. Same as the "dump" command, except the dump command requires the
filename as part of the command. Useful for checking your input is being
read correctly, for saving current configuration, and for debugging.
See "no_dump" for suppressing dumping of particular variables.

Graphics mode command. Tip down. Rotates image about horizontal axis, 
default 6 degrees down. An integer prefix indicates how many 6 degree rotations
to do, and a decimal prefix indicates an angle in degrees.
Example: `15d' does 90 degree rotation, `15.0d' does 15 degree rotation.


<----------------------------------- D ------------------------------------>

Single letter main command. Toggles updating graphics every iteration or
other surface change. Default is ON. Status can also be changed or
queried with the autodisplay toggle.

<------------------------------ datafilename ------------------------------>

Internal read-only variable. String containing the name of the current datafile.
It is the datafile name as given by the user, without any path or extension 
added by the file finding routine.

<----------------------------- date_and_time ------------------------------>

Internal read-only variable. String containing the current date and time,
as provided by the operating system.

<------------------------------ ddd_gamma_sq ------------------------------>

Named method. Description: Third derivative of curve position as function
of arclength, squared.       

Element: vertex. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration:
  
   quantity ddd energy method ddd_gamma_sq global

<--------------------------------- debug ---------------------------------->

Evolver toggle command. Print YACC debug trace of parsing of commands.
Don't do this!

<------------------------------ debug option ------------------------------>
<--------------------------------- option --------------------------------->

Command line option -d :
Prints YACC debugging trace as datafile is parsed.  Not too useful to
end users.

<----------------------------- default_length ----------------------------->

The name of the energy quantity created for the total length of edges in
the string model when convert_to_quantities is done.  Shown by the "v"
or "Q" commands when the show_all_quantities toggle is on.

<------------------------------ default_area ------------------------------>

The name of the energy quantity created for the total area of facets in
the soapfilm model when convert_to_quantities is done. Shown by the "v" 
or "Q" commands when the show_all_quantities toggle is on.

<----------------------------- gravity_quant ------------------------------>

The name of the energy quantity created for the gravitational potential
energy when convert_to_quantities is done. Shown by the "v" or "Q" commands 
when the show_all_quantities toggle is on.


<------------------------------- gap_quant -------------------------------->

The name of the energy quantity created for the convex edge gap energy when 
convert_to_quantities is done. Shown by the "v" or "Q" commands when the 
show_all_quantities toggle is on.

<------------------------ sq_mean_curvature_quant ------------------------->

The name of the energy quantity created for the squared mean curvature
energy when convert_to_quantities is done, if squared_curvature is 
specified in the top of the datafile. Shown by the "v" or "Q" commands when the 
show_all_quantities toggle is on.

<---------------------------- default symmetry ---------------------------->

By default, the domain of a surface is Euclidean space. A symmetric
surface can be done this way if its fundamental domain is bounded by mirror
planes. Each mirror plane should be implemented as a linear level set
constraint.

<--------------------------------- define --------------------------------->

Syntax for defining various things in the top of the datafile:
variables, arrays, and extra attributes of elements.  "Define" can also
be used at runtime to additionally define level set constraints, boundaries,
named methods, and named quantities.  Note that #define for macro definition
is entirely different; see "macros".

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 newx 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 and removing 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.  In the soapfilm model,
DELETE will also fail if it would create two edges with the same endpoints,
unless the force_deletion toggle is on; also see star_finagling. DELETE 
maintains the continuity and connectedness of the surface, as opposed to 
DISSOLVE.  Examples:

      delete edges where length < 0.01 and valence == 2
      delete facets where area < 0.0001

<------------------------------ delete_count ------------------------------>

Internal read-only variable. Sum of edge_delete_count and
facet_delete_count. Kept for backwards compatibility.
Prints and resets to 0 at the end of a command execution, or
when flush_counts is done. Also reset by reset_counts.

<------------------------------ delete_text ------------------------------->

Main prompt command to delete a text string from the graphics display. 
Syntax: 
 
   delete_text(text_id) 

where text_id is the value returned by the call to display_text that
created the string. 
 
<-------------------------------- density --------------------------------->

An element attribute referring either to the gravitational density
of a body, or to the surface tension of a facet, or to the linear
tension of an edge. In the latter two cases, "density" is synonymous
with "tension".

<-------------------------- density_edge_length --------------------------->

Named method. Description: Length of edge, multiplied by the edge density.
Quadratic model uses Gaussian quadrature of order integral_order_1D.

Element: edge. 
Parameters: none. 
Models: string, soapfilm; linear, quadratic, Lagrange.
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

  quantity len energy method density_edge_length global


<--------------------------- density_facet_area --------------------------->

Named method. Description: Area of facet, multiplied by its density.
Otherwise same as facet_area. 

Element: facet.
Parameters:  none.
Models: soapfilm, simplex; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

  quantity farea energy method density_facet_area global

<-------------------------- density_facet_area_u -------------------------->
<------------------------------ facet_area_u ------------------------------>

Named method. Description: Area of facet. In the quadratic model, it is an
upper bound of area, by the Schwarz Inequality. For the paranoid. In the 
linear model, the same as facet_area. Sets integral_order_2D to 6, since it 
doesn't work well with less. Using the density_facet_area_u name automatically
incorporates the facet tension, but facet_area_u doesn't. 

Element: facet.
Parameters: none. 
Models: soapfilm; linear, quadratic. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

   quantity area_u energy method facet_area_u global

<-------------------------------- detorus --------------------------------->

Main prompt command that converts the displayed surface to a real surface.
It is meant for situations like the torus model where one wants to unwrap 
the torus in reality in order to write an export file for some other 
program.  After detorus, the torus model is not in effect.  Detorus also 
works with view transforms.  Beware that after detorus vertices and 
edges may be removed from boundaries and constraints, so considerable
patching up may be necessary to get an evolvable surface.  But quantities,
colors, and other attributes are inherited, which you may or may not need
to patch also.

There is a toggle detorus_sticky that makes detorus merge 
vertices, edges, and facets that coincide; it defaults to on. The tolerance 
for detorus to identify vertices when detorus_sticky is toggled on is the 
internal variable detorus_epsilon, with default value 1e-6.

<---------------------------- detorus_epsilon ----------------------------->

Variable that is the tolerance for detorus to identify vertices when
detorus_sticky is toggled on.  Default value 1e-6.

<----------------------------- detorus_sticky ----------------------------->

Toggle that controls whether the detorus command will identify
coincident vertices, edges, and facets.

<-------------------------------- deturck --------------------------------->

Evolver toggle command. Motion by unit velocity along normal, instead of
by curvature vector.


<------------------------------- diffusion -------------------------------->
<----------------------------- edge_diffusion ----------------------------->
<---------------------------- facet_diffusion ----------------------------->

The Evolver can simulate the real-life phenomenon of gas diffusion between
neighboring bubbles. This diffusion is driven by the pressure difference
across a surface. This is invoked by the keyword DIFFUSION in the first
part of the datafile, followed by the value of the diffusion constant,
which is the internal variable diffusion_coeff.  Example datafile declaration:

   diffusion 0.1

The amount diffused across a facet during an iteration is calculated as
scale*diffusion_coeff*facet_area*pressure_difference. The scale factor
is included as the time step of an iteration. The amount is added to or
subtracted from the prescribed volumes of the bodies on either side of the
facet.

If you want finer control over the rate of diffusion across various
surfaces, you can define the edge_diffusion edge attribute in the string
model or the facet_diffusion facet attribute in the soapfilm model and give
individual values for edges or facets as you desire. If the attribute is
defined, then its value is used instead of the global diffusion constant.

Diffusion can be toggled at runtime with the "diffusion" toggle command.

<---------------------------- diffusion_coeff ----------------------------->

Internal read-write variable controlling the rate of diffusion of
volume across surfaces when "diffusion" is in effect.  Initially set by the
diffusion statement in the top of the datafile, for example,

   diffusion 0.1

If you want finer control over the rate of diffusion across various
surfaces, you can define the edge_diffusion edge attribute in the string
model or the facet_diffusion facet attribute in the soapfilm model and give
individual values for edges or facets as you desire. If the attribute is
defined, then its value is used instead of the global diffusion constant. 

<-------------------------------- dihedral -------------------------------->

Vertex read-only attribute in the string model. This is the angle in radians
from straightness of two edges at a vertex. If there are less than two edges,
the value is 0. If two or more edges, the value is 2*asin(F/2), where F is
the magnitude of the net force on the vertex, assuming each edge has
tension 1. Upper limit clamped to pi.

Edge read-only attribute in the soapfilm model. The angle in radians
between the normals of two facets on an edge. Zero if there are not
exactly two facets. 

This attribute is not stored, but recalculated each time it is used.


<----------------------------- dihedral_hooke ----------------------------->

Named method. Description: Energy of an edge is edge length times square
of angle between normals of adjacent facets. Actually,
  energy = (1 - cos(angle))*length.

Element: edge. 
Parameters: none. 
Models: soapfilm; linear.
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

  quantity bender energy method dihedral_hooke global


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

Named method. Description: Same as the facet_tension method, but the
Hessian is modified to be guaranteed positive definite, after the scheme of
Polthier and Pinkall. The energy is taken to be the Dirichlet integral
of the perturbation from the current surface, which is exactly quadratic
and positive definite. Hence the hessian command always works, but final
convergence may be slow (no faster than regular iteration) since it is only
an approximate Hessian. Also see the dirichlet command.

Element: facet. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

  quantity dirarea energy method dirichlet_area global

<--------------------------- dirichlet_elastic ---------------------------->

Named method. Description: Calculate the Dirichlet elastic strain energy
for facets, minimization of which gives conformal mapping. Let S be Gram
matrix of unstrained facet (dots of sides). Let Q be the inverse of S. Let
F be Gram matrix of strained facet. Let C = FQ, the linear deformation
matrix. Then energy density is Tr(CC^T) Each facet has an extra attribute
array form_factors[3] = {s11,s12,s22}, which are the entries in S. That is,
s11 = dot(v2-v1,v2-v1), s12 = dot(v2-v1,v3-v1), and s22 = dot(v3-v1,v3-v1).
If form_factor is not defined by the user, it will be created by Evolver,
and the initial facet shape will be assumed to be unstrained. 

Element: facet. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: 3. 
Hessian: yes. 
Example datafile declaration: 
 
  quantity dirich energy method dirichlet_elastic global 

 
<----------------------------- dirichlet_mode ----------------------------->

When the facet_area method is being used to calculate areas in hessian
commands, this toggles using an approximate facet_area hessian that is
positive definite. This permits hessian iteration to make big steps in a
far-from-minimal surface without fear of blowing up. However, since it is
only an approximate hessian, final convergence to the minimum can be slow.
Linear model only. Does convert_to_quantities implicitly. Another variant
of this is triggered by sobolev_mode.

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

<----------------------------- display_origin ----------------------------->

For a torus mode surface, if clipped mode is in effect, the lower back left 
of the clip box is set with the display_origin[] array whose dimension 
is the dimension of the ambient space. This array does not exist
by default, it has to be created by the user in the top of the datafile
with the syntax 
 
  display_origin x y z 

where x y z are the coordinates for the desired center of the clip box. At
runtime, the array elements may be changed as normal for an array: 
 
 display_origin[2] := 0.5 

Changing display_origin will automatically cause the graphics to
re-display. 
 
<---------------------------- display_periods ----------------------------->

The displayed parallelogram unit cell can be different from the actual
unit cell if you put an array called display_periods in the top of the
datafile, in addition to the regular periods. For a string model example,

   parameter shear = 1
   torus_filled
   periods
   4  0
   shear  4
   display_periods
   4 0
   0 4

This will always display a square, no matter how much the actual unit cell
is sheared. This feature works well for shears; it may not work nicely for
other kinds of deformation. Display_periods works better for the string
model than the soapfilm model. For the soapfilm model, it seems to do
horizontal shears best, but it can't cope with large shears, so if your
shear gets too large, I advise resetting your fundamental region to less
shear, say with the unshear command in unshear.cmd.

<------------------------------ display_text ------------------------------>

Main prompt command. Causes the display of simple text on the graphics
display. Currently implemented for OpenGL and PostScript graphics. Syntax: 
 
  text_id := display_text(x,y,height,string) 

The x,y coordinates of the start of the string are in window units, i.e.
the window coordinates run from (0,0) in the lower left to (1,1) in the
upper right. The "height" argument gives the height of the font in window
coordinates, so 0.04 is a reasonable value.  The return value should be 
saved in a variable in case you want to delete the text later with 
delete_text(text_id); even if you don't want to delete it, you must have 
something on the left of the assignment for syntax purposes. No font type 
or color implemented. Meant for captioning images, for example a timer in 
frames of a movie.  Example:

  framelabel := display_text(0.10,0.10,0.03,"Frame 1");
 
The font on the screen can look a bit rough sometimes, but postscript
output is smooth.
 
<-------------------------------- 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 three exceptions: dissolving an edge on a
facet in the string model, and dissolving a facet on one body or with both
adjacent bodies the same 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. Examples:

  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.


<----------------------------- dissolve_count ----------------------------->

Internal read-only variable. Sum of vertex_dissolve_count, edge_dissolve_count,
facet_dissolve_count, and body_dissolve_count. Kept for backwards 
compatibility.  Prints and resets to 0 at the end of a command execution, or
when flush_counts is done. Also reset by reset_counts.


<-------------------------- div_normal_curvature -------------------------->

Toggle to make sq_mean_curvature energy calculate the mean curvature by
the divergence of the normal vectors at the vertices of a facet.


<----------------------------------- do ----------------------------------->

Command syntax for post-test iteration loop. Syntax:

   DO command WHILE expr

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


<---------------------- dodecahedron symmetry group ----------------------->

The defined surface can be treated as the fundamental region of a larger
surface with a symmetry.  See "symmetry group".

"Dodecahedron" is the symmetry group of translations of hyperbolic 3 space tiled
with right-angled dodecahedra. The elements of the group are represented as
integers. There are 32 generators of the group so each generator is
represented by five bits. Under this scheme any element that is the
composition of up to five generators can be represented. If you want to use
this group, you'll have to check out the source code in dodecgroup.c, since
somebody else wrote this group and I don't feel like figuring it all out
right now.
Datafile declaration:

   Klein_metric
   symmetry_group "dodecahedron"


<------------------------------ dot_product ------------------------------->

Binary operator for vectors (1-dimensional arrays).  Used in infix
position.  Example:

  print vertex[1].__x dot_product vertex[2].__x

You can now also just use the * operator for dot product:

  print vertex[1].__x * vertex[2].__x


<---------------------------------- dump ---------------------------------->

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

  DUMP filename

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

See "no_dump" for suppressing dumping of particular variables.

<------------------------------ dump_memlist ------------------------------>

Main prompt command. Lists the currently allocated memory blocks. For my
own use in debugging memory problems. 


<-------------------------- dynamic load library -------------------------->

Many Evolver features, such as level set constraints, parametric
boundaries, named method integrands, and Riemannian metrics require
user-defined functions of a set of arguments. The expressions for these
functions are ordinarily stored as a parse tree and interpreted each time
needed, which can be much slower that evaluating compiled expressions.
There is a way to use a set of compiled functions specific to a datafile
through a mechanism known as dynamic loading. Here a library of functions
for a datafile is separately compiled, and then loaded at runtime when a
the datafile is loaded. Currently, the Evolver only implements a dynamic
loading mechanism found on many unix systems, whose presence can be tested
by looking for the existence of the file /usr/include/dlfcn.h. If it
exists, you can enable dynamic loading by including -DENABLE_DLL in the
CFLAGS line in the Makefile. On some systems, you may need to include -ldl
on the GRAPHLIB line also, to link Evolver with functions such as dlopen().

To create the library for a datafile, write a source file containing C
code for the desired functions, compile it, and link it into a shared
library. The function should be able to compute the value and the partial
derivatives of the function, and its second partials if you are going to
use any Hessian features. A sample source file for a 2-dimensional
datafile:


#define FUNC_VALUE  1
#define FUNC_DERIV  2
#define FUNC_SECOND 3
#define MAXCOORD 4   /* must be same as in Evolver!! */
#define REAL double  /* long double if Evolver compiled with -DLONGDOUBLE */
struct dstack { REAL value;
                REAL deriv[2*MAXCOORD];
                REAL second[2*MAXCOORD][2*MAXCOORD]; };

void func1 ( mode, x, s )
int mode; /* FUNC_VALUE, FUNC_DERIV, FUNC_SECOND */
REAL *x;  /* pointer to list of arguments */
struct dstack *s;  /* for return values */
{ REAL value;

  s->value = x[0] + x[1]*x[1];

  if ( mode == FUNC_VALUE ) return;

  /* first partials */
  s->deriv[0] = 1.0;
  s->deriv[1] = 2*x[1];

  if ( mode == FUNC_DERIV ) return;

  /* second partials */
  s->second[0][0] = 0.0;
  s->second[0][1] = 0.0;
  s->second[1][0] = 0.0;
  s->second[1][1] = 2.0;

  return;
}


Supposing the sourcefile name to be foo.c, compile and link on SGI systems
(IRIX 5.0.1 or above) with

cc -c foo.c
ld -shared foo.o -o foo.so

 Sun systems are the same, but with -s in place of -shared. For other
systems, consult the ld documentation for the option to make a shared
library or dynamic load library.
 To use the functions in a datafile, include a line at the top of the
datafile before any of the functions are used:

load_library "foo.so"

 The current directory and the EVOLVERPATH will be searched for the
library. Up to 10 libraries may be loaded. Afterwards, any of the functions
may be invoked just by using their name, without an explicit argument list
because the argument list is always implicit where these functions are
legal. Examples, supposing func2 is also defined with one argument:

constraint 1
formula: func1


boundary 1 parameters 2
x1: func2
x2: 3*func2 + sin(p1)

 It is up to you to make sure the number of arguments your function expects
is the same as the number implicit in the use of the function. You do not
need to explicitly declare your functions in the datafile. Any undefined
identifier is checked to see if it is a dynamically loaded function.
 NOTE: This implementation of dynamic loading is experimental, and the
interface described here may change in the future.


<----------------------------------- e ------------------------------------>

Single letter main command.  Extrapolates the total energy to infinite
refinement if at least two r commands have been done. Uses the last energy
values at three successive levels of refinement, and uses a power law fit
for the error. For best results, use only the r command to refine, and
iterate to complete convergence at each level of refinement. Synonym:
extrapolate.

Graphics mode command. Toggle showing all the facet edges vs. showing
just those that satisfy the current "show edges where ..." condition.


<--------------------------- e_constraint_list ---------------------------->

This read-only edge attribute gives access to the list of constraints an 
edge is on. e_constraint_list[1] is the number of constraints in the list,
followed by the numbers of the constraints. Note that for named
constraints, the internally assigned numbers are used.


<------------------------------ echo option ------------------------------->
<--------------------------------- option --------------------------------->

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

<---------------------------------- edge ---------------------------------->

In general, one of the basic geometric elements. As a keyword, it is used
in element generators. Synonym: edges.  Examples:
   list edges where on_constraint 2
   set edge[3] color red
   list facet[2].edge[2]

<----------------------------- edge boundary ------------------------------>

Edge read-write attribute. If an edge is on a parametric boundary, then
any edges and vertices generated from the edge will inherit the boundary.
By default, new vertex parameter values are calculated by extrapolating
from one end of the edge. This avoids wrap-around problems that would arise
from interpolating parameter values. But if the interp_bdry_param toggle is
on, then interpolation is used. The status of whether an edge is on a
boundary can be queried with the Boolean attribute on_boundary. Edges can
be unset from boundaries, and set on them (but care is needed to do this
properly). Examples:

  list edges where on_boundary 1
  unset edges boundary 2

<------------------------------- edge color ------------------------------->

Edge read-write attribute. Color for graphics. The default color is black.
Color may be set in the datafile, or with the set command. In geomview, the
edge color will show up only for edges satisfying the show edge condition,
and then they will have to compete with the edges geomview draws, unless
you turn off geomview's drawing of edges with "ae" in the geomview window.
Examples:

  set edge color red where length > 1
  show edge where color != black

<---------------------------- edge constraints ---------------------------->

Edge read-write attribute. An edge may be put on a level set constraint.
For such an edge, any vertices and edges generated by refining the edge
will inherit the constraint. An edge may be put on constraints in the edges
section of the datafile by listing the constraint numbers after the keyword
constraint on the line defining the edge. Putting an edge on a constraint
does not put its existing vertices on the constraint. In commands, the
status of an edge can be read with the "on_constraint" attribute. The
status can be changed with the set or unset commands. Examples:

  list edge where on_constraint 2
  set edge constraint 1 where id == 4 or id == 6
  unset edge constraint 3

<------------------------------ edge density ------------------------------>
<------------------------------ edge tension ------------------------------>

Edge read-write attribute. "Density" and "tension" are synonyms. Energy
per unit length of edge. Default 1 in string model, 0 in soapfilm model.
The tension may be modified in the datafile edges section by adding
"tension value" to the line defining the edge. The tension may be modified
with the set command. Examples:

  set edge tension .5 where id < 10
  loghistogram(edge,density)

<------------------------------ edge facets ------------------------------->

Edge read-only attribute. Generates facets attached to an edge, in order
around the edge when meaningful, with facet orientation agreeing with edge
orientation. Examples:

   list edge[2].facets
   foreach edge ee do print max(ee.facets,area)

<------------------------------ edge length ------------------------------->

Edge read-only attribute. Length of the edge. Examples:

 histogram(edge where on_constraint 1, length)
 print edge[3].length

<---------------------------- edge noncontent ----------------------------->

Edge read-write attribute. When set, indicates this facet should not 
be used in volume calculations in the soapfilm model or facet area
calculations in the string model. Useful, for example, if you want to have
edges be part of a body boundary for display purposes, but want to use
constraint integrands for greater accuracy in volume calculations. Example:

   set edge noncontent where on_constraint 1

<---------------------------- edge orientation ---------------------------->

Edge read-write attribute. Controls the sign of oriented integrals on an
edge. Value +1 or -1. Useful when triangulation manipulations create an
edge going the wrong way. Example:

  set edge[2] orientation -1

<------------------------------ edge tangent ------------------------------>

Edge read-only attribute. The components of the edge vector in the linear
model can be accessed as edge attributes x,y,z or x1,x2,x3,.... In a
command, the vector between edge endpoints is used in quadratic model or
lagrange model. But when used in an integral, the tangent is evaluated at
the Gaussian integration points. Not defined in the simplex model. Example
to list nearly vertical edges:

   list edges where z^2 > 10*(x^2 + y^2)

<------------------------------ edge valence ------------------------------>

Edge read-only attribute. The valence of an edge is the number of facets
adjacent to it. Examples:

  list edges where valence == 1
  refine edge where valence != 2

<----------------------------- edge vertices ------------------------------>

Edge read-only attribute. Acts as a generator for the two endpoints in the
linear and quadratic models, and for all vertices on an edge in the
Lagrange and simplex models. Example:

   list edge[2].vertices
   list edge ee where ee.vertex[1].on_constraint 1

<------------------------------- edge_area -------------------------------->

Named method. Description: For calculating the area of a body in the
string model. Implemented as the exact integral of -y dx over the edge.
Valid for torus model, but not general symmetry groups. You may have to set
the quantity volconst attribute in the torus model, since the area
calculation is ambiguous up to one torus area. 

Element: edge.
Parameters: none. 
Models: string; linear, quadratic, Lagrange. 
Ambient dimension: 2. 
Hessian: yes. 
Example datafile declaration:

quantity cell1_area fixed = 1.3 method edge_area

<------------------------------- edge_count ------------------------------->

Internal read-only variable. Number of edges in the total surface.

<--------------------------- edge_delete_count ---------------------------->

Internal read-only variable. Number of edges deleted by the delete command. 
This does not count the secondary edge deletions caused by deleting an edge. 
Prints and resets to 0 at the end of a command execution, or when flush_counts 
is done. Also reset by reset_counts.

<-------------------------- edge_dissolve_count --------------------------->

Internal read-only variable. Number of edges dissolved by dissolve command.
Prints and resets to 0 at the end of a command execution, or when flush_counts
is done. Also reset by reset_counts.

<------------------------------ edge_divide ------------------------------->

Main command, synonym of 'l' (lower-case 'L'). Subdivides long edges,
creating new facets as necessary. Syntax:

   edge_divide expr

You will be prompted for a cutoff edge length, if you don't give
a value with the command. Existing edges longer than the cutoff will be
divided once only. Newly created edges will not be divided. Hence there may
be some long edges left afterward. If you enter h, you will get a histogram
of edge lengths. If you hit RETURN with no value, nothing will be done. It
is much better to use the refine command r than to subdivide all edges.
This command does not respect the no_refine attribute.



<------------------------- edge_edge_knot_energy -------------------------->

Named method. Description: Between pairs of edges, energy is inverse
square power of distance between midpoints of edges. Can also be called
just edge_knot_energy. See also edge_knot_energy_normalizer. (by John
Sullivan) 

Element: edge. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

  quantity knotten energy method edge_edge_knot_energy global


<------------------------- edge_general_integral -------------------------->

Named method. Description: Integral of a scalar function of position and
tangent over an edge. The components of the tangent vector are represented
by continuing the coordinate indices. That is, in 3D the position
coordinates are x1,x2,x3 and the tangent components are x4,x5,x6. For
proper behavior, the integrand should be homogeneous of degree 1 in the
tangent components. Uses Gaussian quadrature of order integral_order_1D.

Element: edge. 
Parameters: scalar_integrand. 
Models: string, soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration: the edge length in 3D could be calculated
  with this quantity:

  quantity arclength energy method edge_general_integral
  scalar_integrand: sqrt(x4^2 + x5^2 + x6^2)

<------------------------- edge_k_vector_integral ------------------------->

Named method. Description: Integral of a simple (n-k)-vector over an
oriented k-dimensional simplicial edge in n-space. The vector integrand
lists the components of each of the k vectors sequentially. Evaluation is
done by forming a determinant whose first k rows are k vectors spanning the
edge, and last (n-k) rows are vectors of the integrand. 

Element: edge.
Parameters: k_vector_order, vector_integrand. 
Models: string, soapfilm; linear, quadratic, simplex. 
Ambient dimension: any. 
Hessian: yes. 
Orientable: yes. 
Example datafile declaration, for 3D edges of a 4D surface in 5D:

   quantity kvec energy method edge_k_vector_integral
   k_vector_order 3
   vector_integrand:
   q1: 0   // first vector
   q2: 0
   q3: 0
   q4: 0
   q5: x4
   q6: 0   // second vector
   q7: 0
   q8: 0
   q9: x3
   q10: 0

<---------------------------- edge_knot_energy ---------------------------->

Named method. Description: Between pairs of edges, energy is inverse
square power of distance between midpoints of edges. Can also be called
just edge_knot_energy. See also edge_knot_energy_normalizer. (by John
Sullivan) 

Element: edge. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity knotten energy method edge_edge_knot_energy global

<---------------------- edge_knot_energy_normalizer ----------------------->

Named method. Description: Calculates internal knot energy to normalize
singular divergence of integral of edge_edge_knot_energy. 

Element: edge.
Parameters: none. 
Models: string; linear. 
Ambient dimension: 3. 
Hessian: no.
Example datafile declaration:

  quantity knotten energy method edge_edge_knot_energy global
                          method edge_knot_energy_normalizer global


<------------------------------ edge_length ------------------------------->
<------------------------------ edge_tension ------------------------------>

Named method. Description: Length of edge. Quadratic or Lagrange model
uses Gaussian quadrature of order integral_order_1D. edge_length and
edge_tension are synonyms.  

Element: edge. 
Parameters: none.
Models: string, soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes.
Example datafile declaration:

  quantity len energy method edge_length global


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

The first edge is the surviving edge.

<-------------------------- edge_min_knot_energy -------------------------->

Named method. Description: Between pairs of edges, energy is inverse
square power of distance between closest points of edges:

    Energy = 1/d^2 * |e1||e2|

This should be roughly the same as edge_edge_knot_energy, but distances
are calculated from edge midpoints there. This is not a smooth function, so
we don't try to compute a gradient. DO NOT use as an energy; use just for
info_only quantities.
 
Element: edge. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: 3.
Hessian: no. 
Example datafile declaration:

  quantity eminknot info_only method edge_min_knot_energy global

<----------------------------- edge_order_key ----------------------------->

Integer edge attribute used by reorder_storage to determine the new
order of edges in storage.  See reorder_storage for details of use.


<---------------------------- e_partition_proc ---------------------------->

Internal edge attribute used when the multiprocessor option -pn is used.
Determines which thread owns an edge.

<--------------------------- e_partition_stage ---------------------------->

Internal edge attribute used when the multiprocessor option -pn is used.
Coordinates the sequencing of iteration over edges in certain operations
so different threads don't conflict and time-consuming locks are not
necessary.

<--------------------------- edge_pop_attribute --------------------------->

Edge integer attribute used by pop commands when kraynikpopedge mode is 
toggled on. Poppable edges look for adjacent facets of different 
edge_pop_attribute values to split off from the original edge; failing
that it reverts to the regular mode of popping the edge. This is meant
to give the user greater control on how edge popping is done. It is up
to the user to declare the edge_pop_attribute integer facet attribute
and assign values.

<----------------------------- edge_pop_count ----------------------------->

Internal read-only variable. Number of edges popd by pop edges, o, or O,
commands. Prints and resets to 0 at the end of a command execution, or when 
flush_counts is done. Also reset by reset_counts.

<--------------------------- edge_refine_count ---------------------------->

Internal read-only variable. Number of edges refined by refine edges command. 
Prints and resets to 0 at the end of a command execution, or when flush_counts 
is done. Also reset by reset_counts.

<-------------------------- edge_scalar_integral -------------------------->

Named method. Description: Integral of a scalar function over arclength.
Uses Gaussian quadrature of order integral_order_1D. 

Element: edge.
Parameters: scalar_integrand. 
Models: string, soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes.
Example datafile declaration:

  quantity edge_sint energy method edge_scalar_integral
  scalar_integrand: x^2 - 3*y + 4


<---------------------------- edge_torus_area ----------------------------->

Named method. Description: For 2D torus string model body area
calculations. Contains adjustments for torus wraps. You may have to set the
quantity volconst attribute in the torus model, since the area calculation
is ambiguous up to one torus area. 

Element: edge. 
Parameters: none. 
Models: torus; string; linear,quadratic,Lagrange. 
Ambient dimension: 2. 
Hessian: yes. 
Example datafile declaration:

  quantity cell_area fixed = 1.3 method edge_torus_area


<-------------------------- edge_vector_integral -------------------------->

Named method. Description: Integral of a vectorfield over an oriented
edge. Uses Gaussian quadrature of order integral_order_1D. 

Element: edge.
Parameters: vector_integrand. 
Models: string, soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes. 
Orientable: yes. 
Example datafile declaration:

   quantity edge_vint energy method edge_vector_integral
vector_integrand:
q1: 0
q2: 0
q3: z^2/2

<--------------------------------- edges ---------------------------------->

An edge is a one-dimensional geometric element. In the linear model, an
edge is an oriented line segment between a tail vertex and a head vertex.
In the quadratic model, an edge is defined by quadratic intepolation of two
endpoints and a midpoint. In the lagrange model, an edge is defined by the
appropriate order interpolation with the edge vertices. In the string
model, edges carry a default surface tension energy proportional to their
length. Edges may also carry energy by being on level set constraints in
the soapfilm model, or by having named quantity energies applied to them.
The edges of the original surface are defined in the edges section of the
datafile.
 Attributes:

 > id
 > oid
 > original
 > length
 > density or tension
 > fixed
 > constraints
 > on_constraint
 > e_constraint_list
 > boundary
 > on_boundary
 > wrap
 > color
 > noncontent
 > bare

 > no_refine
 > orientation
 > vertices
 > midv
 > facets
 > valence
 > backbody
 > frontbody
 > dihedral
 > tangent vector
 > quantities
 > on_quantity
 > on_method_instance
 > extra attributes


<----------------------------- edges_predicted ------------------------------>

Datafile keyword in the top section of the datafile that specifies the
initial allocation of edge structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the edge list grows or as 
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the "d" or "dump" commands, based on
the current number of edges.
Example:
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432


<----------------------------- edges section ------------------------------>

The datafile edge list follows the vertex list, and is started by the
keyword EDGES at the start of a line. It is followed by lines with one edge
specification per line in this format (linespliced here):

k v1 v2 [midv] [s1 s2 s3] [WRAP w] [FIXED] [BOUNDARY b] \
   [CONSTRAINTS c1 [c2 ...]] [TENSION constexpr] [COLOR n] \
     [BARE]  [quantityname ...] [methodname ...]

Here k is the edge number, with numbering following the same rules as for
vertices. v1 and v2 are the numbers of the tail and head vertices of the
edge. In the quadratic model, the edge midpoint may be listed as a third
vertex midv (otherwise a midpoint vertex will be created). In the torus
model, there must follow signs s1 s2 s3 indicating how the edge wraps
around each unit cell direction: + for once positive, * for none, and - for
once negative. In non-torus symmetry groups, each edge should have a WRAP
symmetry group element encoded as an integer. FIXED means that all vertices
and edges resulting from subdividing this edge will have the FIXED
attribute; it does not mean that the endpoints will be automatically fixed.
Likewise the BOUNDARY and CONSTRAINT attributes will be inherited by all
edges and vertices derived from this edge. If a constraint has energy or
content integrands, these will be done for this edge. IMPORTANT: If a
constraint number is given as negative, the edge energy and content
integrals will be done in the opposite orientation. In the string model,
the default tension is 1, and in the soapfilm model, the default tension is
0. However, edges may be given nonzero tension in the soapfilm model, and
they will contribute to the energy.

If the simplex model is in effect, edges are one less dimension than
facets and given by an ordered list of vertices. Only edges on constraints
with integrals need be listed.

The BARE attribute is just an instruction to the checking routines that
this ede is not supposed to have an adjacent facet in the soapfilm model,
so spurious warnings will not be generated. This is useful when you want to
show bare wires or outline fundamental domains.

An arbitrary number of named quantities or method instances may be listed.
These add method values for this element to the must have been declared in
the top section of the datafile. If the quantity or instance has
orientation-dependent methods, the name may be followed by a dash to
reverse the applied orientation.

The "list edges where ..." command prints the datafile format listing of edges.

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


<----------------------------- edgeswap_count ----------------------------->

Internal read-only variable. Number of edges swapped by edgeswap command.
Prints and resets to 0 at the end of a command execution,
or when flush_counts is done. Also reset by reset_counts.

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


<----------------------- eff_area_sq_mean_curvature ----------------------->

Named method. Description: Integral of squared mean curvature of a
surface, with a slightly different definition from sq_mean_curvature or
normal_sq_mean_curvature. The area around a vertex is taken to be the
magnitude of the gradient of the volume. This is less than the true area,
so makes a larger curvature. This also eliminates the spike instability,
since a spike has more area gradient but the same volume gradient. Letting
N be the volume gradient at vertex v,
   h = (1/2)(F/N)),
and
   E = h^2 A/3 =  (3/4)(F.F/N.N)A.
The facets of the surface must be consistently oriented for this to work,
since the evolver needs an `inside' and `outside' of the surface to
calculate the volume gradient. There are still possible instabilities where
some facets grow at the expense of others.

If the parameter or vertex attribute h_zero is defined, then the value per
vertex is
  E = (h-h_0)^2 A/3 = (3/4)(F.N/N.N-2h_0)^2A.
This does not reduce to the non-h_zero formula when h_zero has the value
zero, but is actually a pretty good formula in its own right (see
star_perp_sq_mean_curvature .

If the vertex is on one or several constraints, the F and N are projected
to the constraints, essentially making the constraints act as mirror
symmetry planes.

WARNING: For some extreme shapes, Evolver may have problems detecting
consistent local surface orientation. The assume_oriented toggle lets
Evolver assume that the facets have been defined with consistent local
orientation.

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: no. 
Example datafile declaration:

  quantity effsq energy method eff_area_sq_mean_curvature global

<----------------------------- effective area ----------------------------->

A type of mobility. Simple area normalization as described in
"area_normalization" paragraph isn't what's really wanted in certain
circumstances, since it has equal resistance for motion in all
directions, both parallel and normal to the surface. If a vertex
is a triple junction and migrating along the direction of one of
the edges, it shouldn't matter how long that edge is. Therefore,
if the effective area mode is in effect, the area associated with a vertex
is the area of its star projected normal to the force at the vertex. This
is a little more complicated calculation, but it is still local. S and M
are block diagonal matrices, with one block for each vertex (see mobility).
At a free edge not on any constraint, the force is tangent to the surface,
the resistance is zero, and the mobility is infinite. But this accurately
describes a popping soapfilm. Effective area can be toggled with the
effective_area toggle. Note that area normalization itself must still be
toggled with a or area_normalizaton.

<-------------------------- effective polyhedral -------------------------->

Approximate polyhedral curvature with effective area.
Polyhedral curvature does not make any distinction between motion parallel
and perpendicular to the surface. A better approximation is to count only
motion perpendicular to the surface. This can be done by projecting the
interpolated vectorfields normal to the facets before integrating their
scalar product. Now the rate of area decrease is equal to the rate
geometric volume is swept out, as opposed to the slightly flaky way one had
to calculate volume sweeping in the previous paragraph. Again S is a sparse
matrix with entries corresponding to each pair of vertices joined by an
edge, and M is its dense inverse. The effective area option may be toggled
with effective_area.

<----------------------------- effective_area ----------------------------->


Evolver toggle command. In area normalization, the resistance factor to
motion is taken to be only the projection of the vertex star area
perpendicular to the motion. If squared mean curvature is being calculated,
this projected area is used in calculating the curvature.


<--------------------------------- efixed --------------------------------->

Obsolete datafile attribute to make an edge fixed without fixing its
endpoints. Keyword retained just for compatibility with old dump files.

<------------------------------- eigen_neg -------------------------------->
<-------------------------------- eigenneg -------------------------------->

Internal read-only variable. Number of negative eigenvalues in
last Hessian factoring.  eigen_neg and eigenneg are synonyms.

<------------------------------- eigen_pos -------------------------------->
<-------------------------------- eigenpos -------------------------------->

Internal read-only variable. Number of positive eigenvalues in
last Hessian factoring.  eigen_pos and eigenpos are synonyms.

<------------------------------- eigen_zero ------------------------------->
<------------------------------- eigenzero -------------------------------->

Internal read-only variable. Number of zero eigenvalues in
last Hessian factoring.  eigen_zero and eigenzero are synonyms.


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

<------------------------------ eigenvalues ------------------------------->

Internal read-only array. Contains the list of eigenvalues
produced by the ritz command. Example:
   ritz(-1,10)
   print eigenvalues[2]

<----------------------------- element lists ------------------------------>

The datafile lists of geometric elements follow a general format. Each element 
is defined on one line. The first entry on a line is the element number.
Numbering need not be consecutive, and may omit numbers, but be aware that
internally elements will be renumbered in order. The original number in the
datafile is accessible as the original attribute of an element. After the
element number comes the basic defining data, followed by optional
attributes in arbitrary order. Besides the particular attributes for each
element type listed below, one may specify values for any extra attributes
defined earlier. The syntax is attribute name followed by the appropriate
number of values. Also an arbitrary number of named quantities or method
instances may be listed. These add method values for this element to the
named quantity. The named quantity or instance must have been declared in
the top section of the datafile.

<-------------------------- element orientation --------------------------->

Some methods, those that logically depend on the orientation of the
element, can be applied with a relative orientation. When applied to
individual elements in the datafile, a negative orientation is indicated by
a '-' after the instance name. When applied at runtime with the set
command, the orientation will be negative if the element is generated with
negative orientation, i.e. set body[1].facet method_instance qqq. The
methods currently implementing this feature are: edge_vector_integral,
string_gravity, facet_vector_integral, facet_2form_integral, facet_volume,
facet_torus_volume, simplex_vector_integral, simplex_k_vector_integral,
edge_k_vector_integral, gravity_method, and full_gravity_method.

See also "edge orientation" and "facet orientation".  

See the reverse_orientation command for reversing the orientation of 
selected edges or facets, and see the "orientation" help entry for use of
the "set" command for declaring orientation.

Beware that in reversing an orientation, oriented quantities may not change
as you expect, since the edge gets marked as reversed.  It may be necessary
to remove edges or facets from constraints or quantities, reverse them,
declare their orientation positive, and re-apply constraints and quantities.


<---------------------------- element_modulus ----------------------------->

A method instance may be declared to use a different modulus for each
element by specifying an element extra attribute to use for that purpose.
The extra attribute has to have already been declared. Example:

  define facet attribute mymod real
  quantity myquant energy method facet_area global element_modulus mymod

Of course, it is up to the user to properly initialize the values of the
extra attribute.


<------------------------------- ellipticE -------------------------------->

 ellipticE(x),ellipticK(x): Complete elliptic functions.

<------------------------------- ellipticK -------------------------------->

 ellipticE(x),ellipticK(x): Complete elliptic functions.

<---------------------------------- else ---------------------------------->

 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

<-------------------------------- energies -------------------------------->
<--------------------------------- energy --------------------------------->

The Evolver usually works by minimizing the total energy of the surface,
subject to constraints. This energy can have several components:
 > Surface tension
 > Gravitational potential energy
 > Constraint energy integrals
 > Named quantity energies
 > Convex constraint gap energy
 > Prescribed pressure energy
 > Compressibility energy
 > Crystalline energy
The read-only variable total_energy has the total energy of the surface.

<---------------------------- energy quantity ----------------------------->

Each named quantity is one of four types:
 > "energy" quantities which are added to the total energy of the surface;
 > "fixed" quantities that are constrained to a fixed target value (by
   Newton steps at each iteration); and
 > "conserved" quantities are like fixed, but the value is irrelevant. The
   quantity gradient is used to eliminate a degree of freedom in motion.
   Rarely used, but useful to eliminate rotational degree of freedom, for
   example. Will not work with optimizing parameters, since they do gradients
   by differences.
 > "info_only" quantities whose values are merely reported to the user.
   This type is initially set in a quantity's datafile declaration. A
   quantity can be toggled between fixed and info_only with the "fix
   quantityname" and "unfix quantityname" commands.

<--------------------------------- eprint --------------------------------->

Function that prints an expression and returns the value. Syntax: eprint
expr. Meant for debugging; probably an archaic leftover from when the
command language was not as developed. Example:
   print sum(facet, eprint area)
will print out all the facet areas and then the sum.

<------------------------------- equi_count ------------------------------->

Internal read-only variable. Number of edges flipped by the "u" or 
"equiangulate" commands.  Prints and resets to 0 at the end of a command 
execution, or when flush_counts is done. Also reset by reset_counts.

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

The number of edges flipped is available in the variable equi_count.

<----------------------------- equiangulation ----------------------------->
<----------------------------------- u ------------------------------------>

Main command. The command "u", called equiangulation, tries
to polish up the triangulation. In the soapfilm model, each edge that has
two neighboring facets (and hence is the diagonal of a quadrilateral) is
tested to see if switching the quadrilateral diagonal would make the
triangles more equiangular. For a plane triangulation, a fully
equiangulated triangulation is a Delaunay triangulation, but the test makes
sense for skew quadrilaterals in 3-space also. It may be necessary to
repeat the command several times to get complete equiangulation. The
edgeswap command can force flipping of prescribed edges.

In the simplex model, equiangulation works only for surface dimension 3.
There, two types of move are available when a face of a tetrahedron
violates the Delaunay void condition: replacing two tetrahedra with a
common face by three, or the reverse operation of replacing three
tetrahedra around a common edge by two, depending on how the condition is
violated. This command is inoperative in the string model.

The number of edges flipped is available in the variable equi_count.

For selective testing and flipping of edges, see the "equiangulate" command.

<---------------------------------- ergb ---------------------------------->

Edge attribute used for RGB colors.  See rgb_colors.

<----------------------------- error handling ----------------------------->

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

 > WARNING - Something has happened that you should know about, but Evolver
proceeds normally after printing the message.

 > SYNTAX ERROR - The parser has detected an error. Recent input up to the
detection of the error is printed, but the actual problem may be earlier.

 > DATAFILE ERROR - There is an error in the datafile being read in.
Evolver attempts to recover by skipping to the next recognizable part of
the datafile, but will abandon the datafile after 5 such errors. The
surface data that was read in is available for your inspection, but it
probably forms an inconsistent surface and you should not try to evolve it.

 > ERROR - This is an error encountered during the execution of a command.
The command is abandoned and Evolver returns to the main prompt. The
actions of the command are not undone.

 > FATAL ERROR - An error from which recovery is impossible. Evolver exits
immediately.


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


<-------------------------------- estimate -------------------------------->

Evolver toggle command. Activates estimation of energy decrease in each
gradient descent step (g command). For each "g" iteration, it prints the
estimated and actual change in energy. The estimate is computed by the
inner product of energy gradient with actual motion. Useful only for a
fixed scale factor much less than optimizing, so linear approximation is
good. The internal variable estimated_change records the estimated value.


<---------------------------- estimated_change ---------------------------->

Internal read-only variable. Estimated change of energy
during last iteration with estimate option in effect.

<---------------------------- Euclidean metric ---------------------------->

The default metric on the ambient space is the ordinary Euclidean metric.
There are no built-in units of measurement like meters or grams, so the
user should express all physical quantities in some consistent system of
units, such as MKS or cgs.

<------------------------- everything_quantities -------------------------->

Keyword in top section of the datafile. Causes all areas, volumes, etc. to
be converted to named quantities and methods. Equivalent to the command
line option -q, or the convert_to_quantities command.

<---------------------------- evolver_version ----------------------------->

If a datafile contains features present only after a certain version of
the Evolver, the datafile can contain a line of the form
   evolver_version "2.10"
This will generate a version error message if the current version is
earlier, or just a syntax error if run on an Evolver version earlier than
2.10.

Also, evolver_version is an internal read-only string variable, so one
can find the running version with "print evolver_version".


<------------------------------ EVOLVERPATH ------------------------------->

Evolver consults the system environment variable EVOLVERPATH for
a list of directories to search when it tries to open a file.
The format and setting of EVOLVERPATH depend on the system, but
is the same as the standard PATH environment variable.

 Unix C shell:
    setenv EVOLVERPATH /usr/you/evolver/fe:/usr/you/evolver/doc

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

 Windows:
    Open Control Panel/System/Advanced/Environment Variables. Click "New"
    under System Variables, entering EVOLVERPATH for the Variable name,
    and c:\evolver\fe;c:\evolver\doc for the Variable value.  You may
    add further paths of your own to this list if you wish.

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


<--------------------------- exit error option ---------------------------->
<--------------------------------- option --------------------------------->

Command line option -x : Causes Evolver to exit whenever a warning occurs.
Meant to be used when Evolver is run in a shell script.

<-------------------------- exit warning option --------------------------->
<--------------------------------- option --------------------------------->

Command line option -w : Causes Evolver to exit whenever a warning occurs.
Meant to be used when Evolver is run in a shell script.

<---------------------------------- exp ----------------------------------->

 log(x), exp(x) : Natural log, exponentiation base e.


<------------------------------ expressions ------------------------------->

Arithmetic expressions

Arithmetic expressions evaluate to real numbers. Boolean expressions are a
subclass, with zero as false and nonzero as true; true results evaluate as 1.
Ordinary algebraic notation is used.  Types of expressions:

  atomic values
  arithmetic operators
  boolean operators
  operator precedences
  math functions
  aggregate functions

<-------------------------------- 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 */ }

Actually, the regular "print" command does the same thing, so you can
forget aboutn exprint.

<---------------------------- extra attributes ---------------------------->

Geometric element read-write attributes. If extra attributes have been
defined in the datafile or with a define command, they can be accessed with
attribute syntax. Extra attribute values in the datafile can be initialized
for an element by adding the attribute name and value to the line defining
the element. Example:

  define vertex attribute newx real
  vertices
  1   2 0 0 newx 3

The command language can use the name with the same syntax as built-in
attributes, and can define extra attributes at run time:

  set vertex newx x
  define edge attribute vibel real[2]
  set edge[2] vibel[1] 3; set edge[2] vibel[2] 4
  print vertex[3].newx

The value of an extra attribute can also be calculated by user-supplied
code. The attribute definition is followed by the keyword "function" and
then the code in brackets. In the code, the keyword "self" is used to refer
to the element the attribute is being calculated for. Example: To implement
the lowest z value of a facet as an attribute:

   define facet attribute minz real function
    {self.minz := min(self.vertex,z);}

These attributes can also be indexed. Due to current parser limitations on
parsing executable code, this type of extra attribute definition cannot
occur in the top section of the datafile, although the non-function version
can to declare the attribute name, and the function part added in a
re-definition in the READ section of the datafile.

<--------------------------- extra declaration ---------------------------->

Extra attribute declarations.
It is possible for the user to define extra attributes for elements, which
may be single values or up to eight-dimensional arrays. If these attributes
are to be included in the datafile, then the top section of the datafile
must contain appropriate definitions. The definition syntax is the same as
used by the define runtime command:

 DEFINE elementtype ATTRIBUTE name type [dim]...

where elementtype is vertex, edge, facet, or body, name is an identifier
of your choice, type is REAL or INTEGER (internally, there is also a ULONG
unsigned long type also), and dim is an optional expression for the vector
dimension. 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. Extra attributes are inherited
by elements of the same type generated by subdivision. The type may be
followed by FUNCTION followed by a procedure in brackets to be evaluated
whenever the value of the attribute is read; in the formula, self may be
used to refer to the element in question to use its attributes, in
particular to at some point assign a value to the attribute. The print
command may be used to print attribute arrays or array slices in bracketed
form. Examples:
  define edge attribute charlie real
  define vertex attribute newx real[3]
  define facet attribute knots real[5][5][5]
  define edge attribute bbb real function { self.bbb := self.x+self.y }

WARNING: there is a syntax ambiguity if you mean to define a stand-alone
function in the top of the datafile and put it after an attribute
declaration. You should define stand-alone functions before attributes, or
separate them with some other kind of declaration.


<----------------------------- extra_boundary ----------------------------->
<-------------------------- extra_boundary_param -------------------------->

Interpolation requires that both endpoints of an edge be on the same
boundary, which cannot happen where edges on different boundaries meet. To
handle that case, it is possible to add extra boundary information to a
vertex by declaring two particular vertex extra attributes, extra_boundary
and extra_boundary_param:

  interp_bdry_param
  define vertex attribute extra_boundary integer
  define vertex attribute extra_boundary_param real[1]

Then declare attribute values on key vertices, for example

vertices
1    0.00  boundary 1   fixed extra_boundary 2 extra_boundary_param 2*pi

If the extra_boundary attribute is not set on a vertex when wanted,
Evolver will silently fall back on interpolation.


<------------------------------ extrapolate ------------------------------->

Main command. Same as 'e'.  Extrapolates total energy to infinite
refinement if at least two r commands have been done. Uses last energy
values at three successive levels of refinement, and uses a power law fit
for the error. For best results, use only the r command to refine, and
iterate to complete convergence at each level of refinement.


<----------------------------------- f ------------------------------------>

Single letter main command. Sets diffusion constant. Prints old and
prompts for new.  The diffusion constant can also be set by assigning
a value to the variable diffusion_constant.

<----------------------------------- F ------------------------------------>

Single letter main command. Toggle logging of commands in file. If
starting logging, you will be prompted for the name of a log file. Any
existing file of that name will be appended to. Logging stops automatically
when the surface is exited. Only correctly parsed commands are logged.
Output resulting from commands is not logged. Responses to interactive
single-letter commands are logged, but not responses to other interactive
commands.

<--------------------------- f_constraint_list ---------------------------->

This read-only attribute gives access to the list of constraints a facet
is on. f_constraint_list[1] is the number of constraints in the list,
followed by the numbers of the constraints. Note that for named
constraints, the internally assigned numbers are used.

<---------------------------------- face ---------------------------------->
<--------------------------------- faces ---------------------------------->
<----------------------------- faces section ------------------------------>

The datafile face list follows the edge list, and is started by the
keyword FACES at the start of a line. It is followed by lines with one
facets specification per line in this format:

  k   e1 e2 ...  [FIXED] [TENSION constexpr] [BOUNDARY b] \
  [CONSTRAINTS c1 [c2 ...]]     [NODISPLAY]   \
   [COLOR n]} [FRONTCOLOR n] [BACKCOLOR n] \
   [PHASE n] [quantityname ...] [methodname ...]

Here k is the face number, with numbering following the same rules as for
vertices. There follows a list of oriented edge numbers in counterclockwise
order around the face. A negative edge number means the opposite
orientation of the edge from that defined in the edge list. The head of the
last edge must be the tail of the first edge (except if you're being tricky
in the string model). There is no limit on the number of edges. The face
will be automatically subdivided into triangles if it has more than three
edges in the soapfilm model. The TENSION (synonym: DENSITY) value is the
energy per unit area (the surface tension) of the facet; the default is 1.
Density 0 facets exert no force, and can be useful to define volumes or in
displays. Fractional density is useful for prescribed contact angles.
NODISPLAY prevents the facet from being displayed. The COLOR attribute
applies to both sides of a facet; FRONTCOLOR applies to the positive side
(edges going counterclockwise) and BACKCOLOR to the negative side. The
PHASE number is used in the string model to determine the surface tension
of edges between facets of different phases, if phases are used.
If the simplex model is in effect, the edge list should be replaced by an
oriented list of vertex numbers.

An arbitrary number of named quantities or method instances may be listed.
These add method values for this element to the must have been declared in
the top section of the datafile. If the quantity or instance has
orientation-dependent methods, the name may be followed by a dash to
reverse the applied orientation.

The faces section is optional in the string model.

The "list facets" command prints the datafile format listing of facets.


<--------------------------------- facet ---------------------------------->

In general, one of the basic geometric elements.  In the soapfilm model,
a facet is defined as a closed loop of three edges.  In the string model,
a facet is a closed loop or a single open chain of edges.  As a keyword, 
"facets" is used in element generators. Synonym: facets.  Examples:
   list facets where area < 0.02
   set edge[2].facet color red

<------------------------------- facet area ------------------------------->

Facet read-only attribute. The area of the facet. Example:
    list facet where area < .1


<------------------------------ facet bodies ------------------------------>

Facet read-only attribute. Generates bodies around a facet, first the body
the facet is positive boundary of, then the body the facet is negative
boundary of, if they exist. "body" and "bodies" are synonymous. Example:

  list facet[3].bodies

See also "frontbody" and "backbody".


<----------------------------- facet boundary ----------------------------->

Facet read-write attribute. If a facet is on a parametric boundary, then
any facets, edges, and vertices generated from the facet will inherit the
boundary. By default, new vertex parameter values are calculated by
extrapolating from one vertex of the facet. This avoids wrap-around
problems that would arise from interpolating parameter values. But if the
interp_bdry_param toggle is on, then interpolation is used. The status of
whether a facet is on a boundary can be queried with the Boolean attribute
on_boundary. Facets can be unset from boundaries, and set on them (but care
is needed to do this properly). Examples:

  list facets where on_boundary 1
  unset facets boundary 2


<------------------------------ facet color ------------------------------->

Facet read-write attribute. Color of both sides of facet for graphics.
Default is white. Datafile example:
  Faces
  1   1 2 3 color red

 Command examples:
  list facets where color == red
  set facet[3] color green
  set facet color red where area > 2


<--------------------------- facet constraints ---------------------------->

Facet read-write attribute. Putting a facet on a constraint means that
every vertex, edge, or facet generated by refining the facet will inherit
that constraint. Setting a facet on a constraint does not set any of its
existing edges or vertices on the constraint. Facets may be put on
constraints in the datafile by listing the constraint numbers after the
keyword constraint on the line defining the facet, or with the set command.
They may be removed with the unset command. Examples:

  list facets where on_constraint 1
  set facet[2] constraint 2
  unset facet constraint 1


<----------------------------- facet density ------------------------------>
<----------------------------- facet tension ------------------------------>

Facet read-write attribute. Energy per unit area of facet; surface
tension. Default 0 in string model, 1 in soapfilm model. May be set in the
datafile by adding "tension value" to the line defining the facet. The
density is inherited by any facets generated by refining. "Tension" and
"density" are synonyms. Examples:

  set facet tension 3 where original == 1
  list facet where density < .4



<------------------------------ facet edges ------------------------------->

Facet read-only attribute. Generates edges around a facet, oriented as the
facet boundary. "edge" and "edges" are synonymous. In the string model, if
the edges of the facet do not make a closed loop, then the edges will be
listed in order starting from one end. If the given facet has negative
orientation, the edges will be listed accordingly. Example:
  list facet[3].edges
  list facet[-3].edge[2]
  set facet ff color red where ff.edge[3].length < 1


<---------------------------- facet noncontent ---------------------------->

Facet read-write attribute. When set, indicates this facet should not be
used in volume calculations. Useful, for example, if you want to have
facets be part of a body boundary for display purposes, but want to use
constraint integrands for greater accuracy in volume calculations. Example:

   set facet noncontent where on_constraint 1


<------------------------------ facet normal ------------------------------>

Facet read-only attribute. The components of the facet normal vector may
be referred to as x,y,z or x1,x2,x3,... in the linear model. Length is
equal to facet area. In quadratic model or lagrange model, only the three
facet corner vertices are used to calculate the normal. When used in
integrals, the normal is calculated at each integration points. Not defined
in simplex model.

The facet normal may be referred to as a vector attribute facet_normal,
as in taking a dot product:

    print facet[1].facet_normal * facet[2].facet_normal

<------------------------------ facet phase ------------------------------->

Facet read-write attribute. If there is a phasefile, this attribute
determines the edge tension of an edge between two facets in the string
model. Example:
   list facet where phase == 1


<----------------------------- facet valence ------------------------------>

Facet read-only attribute. The valence of a facet is the number of edges
(or vertices) that it contains. Most useful in the string model. Example:

  list facets where valence != 3


<----------------------------- facet vertices ----------------------------->

Facet read-only attribute. Generates vertices around a facet, oriented as
the facet boundary. "vertex" and "vertices" are synonymous. In the string
model, if the facet is not a closed loop of edges, the vertices will be
generated in order from one end. If the given facet has negative
orientation, then the vertices will be generated accordingly. Examples:
  list facet[3].vertex
  printf facet[2].vertex[1].id


<-------------------------- facet_2form_integral -------------------------->

Named method. Description: Integral of a 2-form over a facet. Meant for
ambient dimensions higher than 3. Uses Gaussian cubature of order
integral_order_2D. 

Element: facet. 
Parameters: form_integrand (components in lexicographic order). 
Models: soapfilm, simplex; linear, Lagrange. 
Ambient dimension: any. 
Hessian: yes. 
Orientable: yes. 
Example datafile declaration in 4D:

   quantity formex energy method facet_2form_integral
   form_integrand:
   q1: x2     // 12 component
   q2: 0      // 13 component
   q3: x4     // 14 component
   q4: 0      // 23 component
   q5: 0      // 24 component
   q6: x3*x2  // 34 component
   

<------------------------ facet_2form_sq_integral ------------------------->

Named method. Description: Integral of the square of a 2-form over a
facet. Meant for ambient dimensions higher than 3. Uses Gaussian cubature
of order integral_order_2D. 

Element: facet. 
Parameters: form_integrand (components in lexicographic order). 
Models: soapfilm; linear. 
Ambient dimension: any. 
Hessian: no. 
Orientable: no. 
Example datafile declaration in 4D: 
 
   space_dimension 4 
   // symplectic area 
   // Correspondence: z1 = (x1,x2)  z2 = (x3,x4) 
   #define DENOM ((x1^2+x2^2+x3^2+x4^2)^2) 
   quantity symplectic_sq energy method facet_2form_sq_integral global 
   form_integrand: 
   q1: -2*(x3^2 + x4^2)/DENOM    // dx1 wedge dx2 term 
   q2:  2*(x2*x3-x1*x4)/DENOM    // dx1 wedge dx3 term 
   q3:  2*(x1*x3+x2*x4)/DENOM    // dx1 wedge dx4 term 
   q4: -2*(x1*x3+x2*x4)/DENOM    // dx2 wedge dx3 term 
   q5:  2*(x2*x3-x1*x4)/DENOM    // dx2 wedge dx4 term 
   q6: -2*(x1^2 + x2^2)/DENOM    // dx3 wedge dx4 term 

 

<------------------------------- facet_area ------------------------------->
<----------------------------- facet_tension ------------------------------>

Named method. Description: Area of facet. Does not multiply by facet
density; density_facet_area does that. Quadratic model uses Gaussian
cubature of order integral_order_2D. Beware that this is an approximation
to the area, and if the facets in the quadratic or Lagrange model get too
distorted, it can be a bad approximation. Furthermore, facets can distort
themselves in seeking the lowest numerical area. By default, changing the
model to quadratic or Lagrange will set an appropriate integral_order_2D.

Element: facet. 
Parameters: none. 
Models: soapfilm, simplex; linear, quadratic, Lagrange.
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

   quantity farea energy method facet_area global


<------------------------------ facet_area_u ------------------------------>

Named method. Description: Area of facet. In quadratic model, it is an
upper bound of area, by the Schwarz Inequality. For the paranoid. Same as
facet_area in linear model. Sets integral_order_2D to 6, since it doesn't
work well with less. Using the density_facet_area_u name automatically
incorporates the facet tension, but facet_area_u doesn't. 

Element: facet.
Parameters: none. 
Models: soapfilm; linear, quadratic. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

   quantity area_u energy method facet_area_u global

<------------------------------ facet_colors ------------------------------>

Evolver toggle command. Enables coloring of facets in certain graphics
interfaces (e.g. xgraph). If off, facet color is white. Default on.


<------------------------------ facet_count ------------------------------->

Internal read-only variable. Number of facets in the current surface.

<----------------------------- facet_crosscut ----------------------------->

Function. In the string model, it subdivides a facet by constructing
a diagonal edge between given vertices.  The return value is the
id number of the new edge.  The new facet will be on the same body
as the old facet.  Syntax: 
   newedge := facet_crosscut(facet_id,tail_id,head_id)
   

<--------------------------- facet_delete_count --------------------------->

Internal read-only variable. Number of facets deleted
by delete command. Prints and resets to 0 at the end of a command
execution, or when flush_counts is done. Also reset by reset_counts.

<-------------------------- facet_dissolve_count -------------------------->

Internal read-only variable. Number of facets dissolved by dissolve
command. Prints and resets to 0 at the end of a command execution,
or when flush_counts is done. Also reset by reset_counts.

<------------------------------- facet_edge ------------------------------->
<------------------------------- facetedge -------------------------------->
<------------------------------ facet_edges ------------------------------->
<------------------------------- facetedges ------------------------------->

In general, a facetedge is an internal data structure representing the 
incidence of an edge and a facet. As a keyword, it can used in element 
generators in LIST commands. For gurus only. But it is the source of the 
standard "fe" extension I use for datafilenames, since in early versions of 
Evolver, the datafile had to explicitly list all the facetedges.
Synonyms: facetedges, facet_edge, facet_edges.

<------------------------- facet_general_integral ------------------------->

Named method. Description: Integral of a scalar function of position and
normal vector over a facet in 3D space. Uses Gaussian cubature of order
integral_order_2D. The components of the normal vector are represented by
continuing the coordinate indices. That is, in 3D the position coordinates
are x1,x2,x3 and the normal components are x4,x5,x6. For proper behavior,
the integrand should be homogeneous of degree 1 in the normal components.

Element: facet. 
Parameters: scalar_integrand. 
Models: soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: 3. 
Hessian: yes. 
Example: The facet area could be calculated with this quantity:

  quantity surfacearea energy method facet_general_integral
  scalar_integrand: sqrt(x4^2 + x5^2 + x6^2)


<------------------------- facet_general_hi_d_integral ------------------------->

Named method. Description: Integral of a scalar function of position and
normal vector over a 2D facet in any ambient dimension space. 
Uses Gaussian cubature of order integral_order_2D.  The 2D facet is represented
by a 2-vector.  The components of the 2-vector are named as xn, where the number
n ranges from  N+1 to N+N*(N+1)/2, continuing the coordinate indices. That is, 
in 4D the position coordinates are x1,x2,x3,x4 and the 2-vector components are
x5 = x1 wedge x2, x6 = x1 wedge x3, x7 = x1 wedge x4, x8 = x2 wedge x3, 
x9 = x2 wedge x4, and x10 = x3 wedge x4. For proper behavior,
the integrand should be homogeneous of degree 1 in the 2-form components.


Element: facet. 
Parameters: scalar_integrand. 
Models: soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes. 
Example: The facet area could be calculated with this quantity:

  space_dimension 4
  quantity surfacearea energy method facet_general_hi_d_integral
  scalar_integrand: sqrt(x5^2 + x6^2 + x7^2 + x8^2 + x9^2 + x10^2) )


<--------------------------- facet_knot_energy ---------------------------->

Named method. Description: Charge on vertex is proportional to area of
neighboring facets. Meant for knotted surfaces in 4D. Power law of
potential is adjustable via the global parameter `surface_knot_power'. See also
facet_knot_energy_fix. 

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear.
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   parameter knot_power  2     // the default
   quantity knotten energy method facet_knot_energy global


<------------------------- facet_knot_energy_fix -------------------------->

Named method. Description: Provides adjacent vertex correction to
facet_knot_energy. 

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear.
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

  parameter surface_knot_power  2     // the default
  quantity knotten energy method facet_knot_energy global
                          method facet_knot_energy_fix global


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

The merged facet will keep the number and attributes of the first facet.


<---------------------------- facet_order_key ----------------------------->

Integer facet attribute used by reorder_storage to determine the new
order of facets in storage.  See reorder_storage for details of use.


<----------------------------- facets_predicted ------------------------------>

Datafile keyword in the top section of the datafile that specifies the
initial allocation of facet structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the facet list grows or as 
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the "d" or "dump" commands, based on
the current number of facets.
Example:
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432


<-------------------------- facetedges_predicted --------------------------->

Datafile keyword in the top section of the datafile that specifies the
initial allocation of facetedge structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the facetedge list grows or as 
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the "d" or "dump" commands, based on
the current number of facetedges.
Example:
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432

<-------------------------- facetedge_order_key --------------------------->

Integer facetedge attribute used by reorder_storage to determine the new
order of facetedges in storage.  See reorder_storage for details of use.

<---------------------------- f_partition_proc ---------------------------->

Internal facet attribute used when the multiprocessor option -pn is used.
Determines which thread owns a facet.

<--------------------------- f_partition_stage ---------------------------->

Internal facet attribute used when the multiprocessor option -pn is used.
Coordinates the sequencing of iteration over facets in certain operations
so different threads don't conflict and time-consuming locks are not
necessary.

<--------------------------- facet_refine_count --------------------------->

Internal read-only variable. Number of facets refined by refine facets
command. Prints and resets to 0 at the end of a command execution, or when 
flush_counts is done. Also reset by reset_counts.


<------------------------- facet_scalar_integral -------------------------->

Named method. Description: Integral of a scalar function over facet area.
Uses Gaussian cubature of order integral_order_2D. 

Element: facet.
Parameters: scalar_integrand. 
Models: soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

   quantity fint energy method facet_scalar_integral global
   scalar_integrand: x^2+y^2


<--------------------------- facet_torus_volume --------------------------->

Named method. Description: For 3D soapfilm model, calculates body volume
integral for a facet, with corrections for edge wraps. You may have to set
the quantity volconst attribute in the torus model, since the volume
calculation is ambiguous up to one torus volume. 

Element: facet.
Parameters: none. 
Models: soapfilm; linear,quadratic,Lagrange. 
Ambient dimension: 3.
Hessian: yes. 
Orientable: yes. 
Example datafile declaration:

   quantity body_vol energy method facet_torus_volume


<------------------------- facet_vector_integral -------------------------->

Named method. Description: Integral of a vectorfield inner product with
the surface normal over a facet. The normal is the right-hand rule normal
of the facet as defined in the datafile. Uses Gaussian cubature of order
integral_order_2D. 

Element: facet. 
Parameters: vector_integrand. 
Models: soapfilm, simplex; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes.
Orientable: yes. 
Example datafile declaration, for volume equivalent:

   quantity fvint energy method facet_vector_integrand
   vector_integrand:
   q1: 0
   q2: 0
   q3: z


<------------------------------ facet_volume ------------------------------>

Named method. Description: Integral of z dx dy over an oriented facet.
Valid in the torus domain. Not valid for other symmetry groups. You may
have to set the quantity volconst attribute in the torus model, since the
volume calculation is ambiguous up to one torus volume. 

Element: facet.
Parameters: none. 
Models: soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: 3. 
Hessian: yes. 
Orientable: yes. 
Example datafile declaration:

   quantity vol fixed = 1.3 method facet_volume


<---------------------------- facetedge_count ----------------------------->

Internal read-only variable. Number of facetedges.

<--------------------------------- facets --------------------------------->

In the soapfilm model, a facet is an oriented triangle defined by a cycle
of three edges. In the linear model, a facet is a flat triangle. In the
quadratic model, the facet is a curved surface defined by quadratic
interpolation among the three facet corner vertices and the three edge
midpoints. In the Lagrange model, lagrange_order interpolation is done
among (lagrange_order+1)(lagrange_order+2)/2 vertices. Although individual
facets are oriented, there are no restrictions on the orientations of
adjacent facets. By default, a facet carries a surface tension energy equal
to its area.

In the string model, a facet is a chain of an arbitrary number of edges.
The chain need not be closed. Usually a facet is defined in the string
model in order to define a body, so the space dimension is 2 and the facet
is planar, one facet corresponding to a body. Facets carry no energy by
themselves.

In the simplex model, a facet is a simplex of dimension surface_dimension
defined by surface_dimension+1 vertices. The surface_dimension may be any
dimension less than or equal to the space_dimension. The simplex is
oriented according to the order of the vertices. By default, a simplex
carries a surface tension energy proportional to its volume.

Facets may carry additional energy by having named quantity energies
applied to them.

The facets of the original surface are defined in the faces section of the
datafile.

Attributes:

 > id
 > oid
 > original
 > area
 > fixed
 > constraints
 > on_constraint
 > constraint list
 > boundary
 > on_boundary
 > density or tension
 > color
 > frontcolor
 > backcolor
 > no_refine
 > noncontent

 > edges
 > vertices
 > bodies
 > frontbody
 > backbody
 > valence
 > normal vector
 > phase
 > quantities
 > on_quantity
 > on_method_instance
 > nodisplay
 > extra attributes


<--------------------------------- fbrgb ---------------------------------->

Facet extra attribute used for rgb colors used for facet backcolor.
See rgb_colors.


<------------------------------ file option ------------------------------->
<--------------------------------- option --------------------------------->

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

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


<------------------------------- fix_count -------------------------------->

Internal read-only variable. Number of elements fixed by fix
command. Prints and resets to 0 at the end of a command execution, or when
flush_counts is done. Also reset by reset_counts.

<--------------------------------- fixed ---------------------------------->

Attribute that can be applied to vertices, edges, facets, or named
quantities. See "fixed vertex", etc.

<------------------------------- fixed edge ------------------------------->

Edge read-write attribute. For an edge to be "fixed" means that any vertex
or edge created by refining the edge will inherit the "fixed" attribute.
Declaring an edge fixed in the datafile will also fix all vertices on the
edge. However, fixing an edge from the command prompt will not fix any
vertices. An edge may be declared fixed in the datafile edges section by
adding fixed to the line defining the edge. From the command prompt, one
can fix or unfix edges with the fix and unfix commands. Examples:
  fix edge where on_constraint 1
  list edges where fixed
  set edge color red where fixed
  unfix edge[3]


<------------------------------ fixed facet ------------------------------->

Facet read-write attribute. For a facet to be "fixed" means that any
vertex, edge, or facet created by refining a facet will inherit the fixed
attribute. Fixing a facet in the datafile or at the command prompt does not
fix any edges or vertices. A face may be declared fixed in the datafile by
putting fixed on the line defining the face, after the coordinates. From
the command prompt, one can fix or unfix facets with the fix and unfix
commands.  Examples:

  fix facet where on_constraint 1
  list facets where fixed
  set facet color red where fixed
  unfix facet[3]

<----------------------------- fixed quantity ----------------------------->

 Each named quantity is one of four types:
 > "energy" quantities which are added to the total energy of the surface;
 > "fixed" quantities that are constrained to a fixed target value (by
   Newton steps at each iteration); and
 > "conserved" quantities are like fixed, but the value is irrelevant. The
   quantity gradient is used to eliminate a degree of freedom in motion.
   Rarely used, but useful to eliminate rotational degree of freedom, for
   example. Will not work with optimizing parameters, since they do gradients
   by differences.
 > "info_only" quantities whose values are merely reported to the user.
   This type is initially set in a quantity's datafile declaration. A
   quantity can be toggled between fixed and info_only with the "fix
   quantityname" and "unfix quantityname" commands.

<------------------------------ fixed vertex ------------------------------>

Vertex read-write attribute. A fixed vertex will not move during iteration
(except to satisfy level set constraints) or other operations, except if
coordinates are explicitly changed by a "set vertices ..." command. A
vertex may be declared fixed in the datafile by putting fixed on the line
defining the vertex, after the coordinates. From the command prompt, one
can fix or unfix vertices with the fix and unfix commands. Examples:

  list vertex where fixed
  fix vertex where on_constraint 1
  unfix vertices where on_boundary 1


<----------------------- flip-rotate symmetry group ----------------------->

The defined surface can be treated as the fundamental region of a larger
surface with a symmetry.  See "symmetry group".

Flip_rotate is the cyclic symmetry group of rotations in the x-y plane with a
flip z -> -z on every odd rotation, where the order of the group is given
by the internal variable rotation_order, which had better be even. Note:
Since this group has points that are fixed under an even number of
rotations, some special precautions are necessary. Vertices on the rotation
axis must be labelled with the attribute "double_axial_point" in the
datafile. Edges out of an axial point must have the axial point at their
tail, and must have zero wrap. Facets including an axial point must have
the axial point at the tail of the first edge in the facet.
Datafile declaration:
  symmetry_group "flip_rotate"
  parameter rotate_order = 6

Group element encoding: An element is encoded as the power of the group
generator.


<--------------------------------- floor ---------------------------------->

 ceil(x),floor(x): Round up or down to integer.

<------------------------------ flush_counts ------------------------------>

Main prompt command. Causes the printing of various internal counters that
have become nonzero. The counters are:
    body_dissolve_count     notch_count
    edge_delete_count       pop_edge_to_tri_count
    edge_dissolve_count     pop_quad_to_quad_count
    edge_pop_count          pop_tri_to_edge_count 
    edge_refine_count       t1_edgeswap_count
    edgeswap_count          unfix_count 
    equi_count              vertex_dissolve_count 
    facet_delete_count      vertex_pop_count
    facet_dissolve_count    where_count 
    facet_refine_count 
    fix_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.


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


<-------------------------------- v_force --------------------------------->

Vertex read-only array attribute. This is an indexed attribute giving the
components of the force (negative energy gradient). 
Meant for debugging use. This is not directly used for the motion; 
see v_velocity.

<----------------------------- force_pos_def ------------------------------>

Toggle. If this is on during YSMP factoring of Hessian and the Hessian
turns up indefinite, something will be added to the diagonal element to
make it positive definite. Left over from some experiment probably.


<----------------------------- force_deletion ----------------------------->

Toggle.  In the soapfilm model, overrides the refusal of the
delete command to delete edges or facets when that would create 
two edges with the same endpoints.  Sometimes it is necessary to 
have such edges, for example in pinching off necks. But usually 
it is a bad idea.  Also see star_finagling.  Default is off.

<----------------------------- force_edgeswap ----------------------------->

Toggle.  Makes the "u" or "equiangulate" or "edgeswap" commands skip 
certain tests and do the swap anyway.  The skipped tests are: (1) the
two vertices of the flipped edge are distinct, (2) creating two facets
with the same vertices.  Meant only for rare cases when you really know
what you are doing.  You should not leave this toggle in the ON state;
turn it OFF after you have done the recalcitrant edge swap.


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



<----------------------------- form_integrand ----------------------------->

Certain named methods require an n-form integrand.  The syntax is
 FORM_INTEGRAND:
 Q1: expr
 Q2: expr
 Q3: expr
 ...

where the expressions are functions of the coordinates. Element
attributes of the appropriate type element may also be used. When used in
the facet_2form_integral method. The form components are listed in
lexicographic order, i.e. in 4D the six components 12,13,14,23,24,34 would
be listed as Q1 through Q6.

<------------------------------ form_factors ------------------------------>

A facet extra attribute vector used by several elastic energy named
methods: linear_elastic, neo_hookean, relaxed_elastic, relaxed_elastic_A,
SVK_elastic, and dirichlet_elastic.  The entries are the dot products of 
the sides of the relaxed facet. Due to symmetry, there are only three 
distinct dot products, so form_factors just has length 3.  The entries 
are {s11,s12,s22}, where s11 = dot(v2-v1,v2-v1), s12 = dot(v2-v1,v3-v1), 
and s22 = dot(v3-v1,v3-v1).  If form_factor is not defined by the user, 
it will be created by Evolver, and the initial facet shape will be assumed 
to be unstrained. 

<-------------------------------- formula --------------------------------->

Datafile keyword used in level set constraints to introduce the function
formula. Synonym: function

<----------------------------- free_discards ------------------------------>

Main prompt command. Frees deleted elements in internal storage.
Ordinarily, deleting elements does not free their memory for re-use until
the command completes, so that element iteration loops do not get
disrupted. If for some reason this behavior leads to excess memory usage or
some other problem, the user may use the free_discards command to free
element storage of deleted elements. Just be sure not to do this inside any
element iteration loop that might be affected. 
 
 
<---------------------------------- frgb ---------------------------------->

Facet array extra attribute for facet color used when rgb colors are used.
See rgb_colors.

<------------------------------- frontbody -------------------------------->

Facet read-write attribute. The id of the body of which the facet is on
the positively oriented boundary. Useful after creating a new body with the
new_body command. As a read attribute, the value is 0 if there is no such
body. Examples:

  newb := new_body; set facet frontbody newb where color == red
  print facet[2].frontbody

Frontbody also works for adding edges to a facet in the string model, but
the added edge must be attach to one end of the edge arc, or close the arc.

<------------------------------- frontcolor ------------------------------->

Facet read-write attribute. Color of positive side of facet for graphics.
Default is white. Datafile example:
  Faces
  1   1 2 3 frontcolor green backcolor red

 Command examples:
  list facets where frontcolor == red
  set facet[3] frontcolor green
  set facet frontcolor red where area > 2


<--------------------------- full_bounding_box ---------------------------->

Evolver toggle command. Causes bounding box in PostScript output to be the
full window, rather than the actual extent of the surface within the
window. Default off.


<-------------------------- full_gravity_method --------------------------->
<----------------------------- gravity_method ----------------------------->

Named method. Description: Gravitational energy, integral of p z^2/2 dxdy
over a facet, where p is the difference in adjacent body densities. Note: this
method uses the gravitational constant as the modulus if invoked as
full_gravity_method. Just gravity_method does not automatically use the
gravitational constant. 

Element: facet. 
Parameters: none. 
Models: soapfilm; linear, quadratic, Lagrange. 
Ambient dimension: 3. 
Hessian: yes. 
Orientable: yes.
Example datafile declaration:

  quantity grav energy modulus 980*8.5 method gravity_method


<-------------------------------- function -------------------------------->

Datafile keyword used in level set constraints to introduce the function
formula. Synonym: function

<-------------------------- function definition --------------------------->

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

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

This syntax works both in the top of the datafile and at runtime.
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.


<------------------------------- functions -------------------------------->

Usually stand-alone user-defined functions and procedures are defined in
the read section of the datafile, but sometimes it is necessary to define
them in the top section of the datafile so they may be used in other top
section declarations. It is possible to define them in the top section with
the same syntax as in the read section. Note this applies to the
parameter-passing variety of functions and procedures, denoted by the
leading keyword "function" or "procedure", and not command definitions like
"gg := {...}". WARNING: there is a syntax ambiguity if you mean to define a
stand-alone function in the top of the datafile and put it after an
attribute declaration. You should define stand-alone functions before
attributes, or separate them with some other kind of declaration.

<------------------------ function_quantity_sparse ------------------------>

Toggle command controlling whether sparse matrices are used in
evaluation of Hessians of quantities using functions of methods.
Default is off, but I recomment on if you are using a quantity
function applying to anything but a small number of elements.

<----------------------------------- g ------------------------------------>
<----------------------------------- go ----------------------------------->

Single letter main command. Do one iteration step. The output consists of
the number of iterations left (for people who wonder how close their 1000
iterations are to ending), the area and energy, and the scale factor. g is
commonly used with an iteration count, as in "g 100". The user can abort
repeated iterations by sending an interrupt to the process (SIGINT, to be
precise; CTRL-C or whatever on your keyboard). As a special dispensation to
lazy users, the syntax "gn" is equivalent to "g n". Synonym: go
See "iteration step" for a detailed explanation of what happens during
a 'g' step.


<----------------------------------- G ------------------------------------>

Single letter main command. Toggles gravity on or off. Gravity starts ON
if any body has a nonzero density; otherwise OFF. If followed by a value,
sets gravity to that value. Otherwise prints old value of gravitational
constant and prompts for new.  When used in numerical expressions, G
evaluates to the current value of the gravitational constant.


<------------------------ gap constant declaration ------------------------>

The initial value of the gap constant for gap energy may be set in the
datafile with the syntax

  GAP_CONSTANT value

The default value is 1. Synonym: spring_constant.


<------------------------------- gap energy ------------------------------->

Convex constraint can have what I call a gap energy.
Consider a soap film spanning a circular cylinder. The Evolver must
approximate this surface with a collection of facets. The straight edges of
these facets cannot conform to the curved wall, and hence the computed area
of the surface leaves out the gaps between the outer edges and the wall.
The Evolver will naturally try to minimize area by moving the outer
vertices around so the gaps increase, ultimately resulting in a surface
collapsed to a line. This is not good. Therefore there is provision for a
"gap energy" to discourage this. A level-set constraint may be declared
CONVEX in the datafile. For an edge on such a constraint, an energy is
calculated as
  E = k\left\Vert \vec S \times \vec Q \right\Vert / 6

where \vec S is the edge vector and \vec Q is the projection of the edge
on the tangent plane of the constraint at the tail vertex of the edge. The
constant k is a global constant called the "gap constant". A gap constant
of 1 gives the best approximation to the actual area of the gap. A larger
value minimizes gaps and gets vertices nicely spread out along a
constraint. You can set the value of k in the datafile or with the k
command.

The gap energy falls off quadratically as the surface is refined. That is,
refining once reduces the gap energy by a factor of four. You can see if
this energy has a significant effect on the surface by changing the gap
constant.

 Note: gap energy is effective only in the linear model.
 Example datafile: tankex.fe

As an alternative to gap energy, you should consider a system of "guide
lines", i.e. a plane level set constraint whose coefficients are
extra attributes of vertices.  This can keep the contact line vertices
evenly spaced without adding extra energy, and permitting Hessian
operations.

<------------------------------ gap_constant ------------------------------>

The initial value of the gap constant for gap energy may be set in the
datafile with the syntax
  GAP_CONSTANT value
The default value is 1. Synonym: spring_constant.
See "gap energy" for more.


<------------------------------- gap_energy ------------------------------->

Named method. Description: Implementation of gap energy, which is designed
to keep edges from short-cutting curved constraint surfaces. This method
serves the same purpose as declaring a constraint convex. Automatically
incorporates the gap_constant set in the datafile or by the k command.

Element: edge. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: no. 
Example datafile declaration:

   quantity gappy energy method gap_energy global

As an alternative to gap_energy, you should consider a system of "guide
lines", i.e. a plane level set constraint whose coefficients are
extra attributes of vertices.  This can keep the contact line vertices
evenly spaced without adding extra energy, and permitting Hessian
operations.


<------------------------------ gauss_bdry_e ------------------------------>

Edge extra attribute used by gauss_curvature_integral.

<------------------------------ gauss_bdry_v ------------------------------>

Vertex extra attribute used by gauss_curvature_integral.

<------------------------ gauss_curvature_integral ------------------------>

Named method. Description: This computes the total Gaussian curvature of a
surface with boundary. The Gaussian curvature of a polyhedral surface may
be defined at an interior vertex as the angle deficit of the adjacent
angles. But as is well-known, total Gaussian curvature can be computed
simply in terms of the boundary vertices, which is what is done here. The
total Gaussian curvature is implemented as the total geodesic curvature
around the boundary of the surface. The contribution of a boundary vertex is

  E =  (\sum_i \theta_i) - pi.

For reasons due to the Evolver's internal architecture, the sum is
actually broken up as a sum over facets, adding the vertex angle for each
facet vertex on the boundary and subtracting pi for each boundary edge. The
total over all boundary vertices is exactly equal to the total angle
deficit of all interior vertices plus 2*pi*chi, where chi is the Euler
characteristic of the surface. Boundary vertices are deemed to be those
that are fixed or on a parametric boundary. Alternately, one may define a
vertex extra attribute gauss_bdry_v and an edge extra attribute
gauss_bdry_e and set them nonzero on the relevant vertices and edges; this
overrides the fixed/boundary criterion. 

Element: facet. 
Parameters: none.
Models: soapfilm; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity gint energy method gauss_curvature_integral global


<---------------------------- gauss_curvature ----------------------------->

Datafile keyword that automatically creates an energy named quantity using
the method gauss_curvature_integral as a global method. May be followed in
the datafile with a modulus value.


<----------------------------- elastic_basis ------------------------------>

Facet extra attribute used by the general_linear_elastic named method.
See general_linear_elastic for details.

<----------------------------- elastic_coeff ------------------------------>

Facet extra attribute used by the general_linear_elastic named method.
See general_linear_elastic for details.

<------------------------- general_linear_elastic ------------------------->

Named method. Description: To calculate the nonisotropic linear elastic
strain energy energy for facets. Let A be the linear transformation from
the unstrained shape to the strained shape. Then the Cauchy-Green strain
tensor is C = (A^TA - I)/2. Let S_1 and S_2 be the sides of the unstrained
facet. Let W_1 and W_2 be the transformed facet sides. Let F be the Gram
matrix of strained facet. Define

    S = [ S_1 S_2 ],  Q = S^-1

    W = [ W_1 W_2 ] = AS

    F = W^TW = S^TA^TAS

 Then

    A^TA = Q^TFQ

    C = (Q^TFQ - I)/2

 The energy density is

    (1/2)C_ij K_ijkl C_kl

where K_ijkl is the full tensor of elastic constants. By using symmetries,
this can be reduced to

 (1/2) [ C_11 C_22 C_12 ]  [ E_1 E_3 E_4 ] [ C_11 ]
                           [ E_3 E_2 E_5 ] [ C_22 ]
                           [ E_4 E_5 E_6 ] [ C_12 ]

Each facet has extra attribute elastic_coeff of size 6 containing { E_1,
E_2, E_3, E_4, E_5, E_6 }, and extra attribute array elastic_basis of size
2x2 containing { {s11,s12},{s21,s22}}, which are the two sides of the
unstrained facet. Note that the E_i are defined with respect to the
original sides as defined by the form factors, so it is up to you to make
sure everything works out right. Test carefully!!! The elastic_coeff
attribute must be created and initialized by the user.
 
Element: facet. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: 3.
Hessian: yes. 
Example datafile declaration:

   define facet attribute elastic_basis real[2][2]
   define facet attribute elastic_coeff real[6]
   quantity genlastic energy method general_linear_elastic global


<---------------------------- generator_power ----------------------------->

Variable optionally used by the symmetry group "rotate" so that the angle of 
rotation is 2*pi*generator_power/rotation_order.  Default 1.  The variable
does not exist until the user assigns a value to it.

<------------------------------- generators ------------------------------->

Various commands can act on specified sets of elements, which are defined 
by "element generator" syntax.  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
 1. A multiple element generator, which can be
    A. An element type, vertex, edge, facet, facetedge, 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.
    B. A single element subelement. The implemented subelements are:
       of a vertex: edge, facet (in no particular order)
       i. of an edge: vertex (in tail, head order), facet (in geometric order)
      ii. of a facet: vertex, edge, body (all in order around the facet)
     iii. of a body: facet (in no particular order)
 2. A single element, which can be
    A. an element name of an active generator
    B. 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.
    C. 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)


<------------------------- genus2 symmetry group -------------------------->

The defined surface can be treated as the fundamental region of a larger
surface with a symmetry.  See "symmetry group".

genus2 is a symmetry group on the Klein model of hyperbolic space whose
quotient group is a genus 2 hyperbolic manifold. The fundamental region is
an octagon.

Datafile declaration:

   Klein_metric
   symmetry_group "genus2"

Group element encoding: There are 8 translation elements that translate
the fundamental region to one of its neighbors. Translating around a vertex
gives a circular string of the 8 elements. The group elements encoded are
substrings of the 8, with null string being the identity. Encoding is 4
bits for each element. See khyp.fe for an example.


<--------------------------- geometric elements --------------------------->

The surface is defined in terms of its geometric elements of each
dimension. Each element has its own set of attributes. Some may be set by
the user; others are set internally but may be queried by the user. It is
also possible to dynamically define extra attributes for any type of
element, which may be single values or vectors of values. Attribute values
can be specified in the datafile, and queried with commands.
Elements: vertices, edges, facets, bodies, facet-edges.

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

Excellent screen graphics on Unix systems can be done through the free 3D
viewing program geomview. Geomview can be started with the P command,
option 8. One caution: geomview does not deal well with object sizes below
1e-5, so displaying micron-size objects using MKS units is ill-advised.

Main prompt commands relevant to geomview:
   "geomview" or "P 8" to start geomview
   "P 9" to end geomview
   "geompipe" to pipe geomview input someplace else
   "geomview string" to send user commands to geomview
   "gv_binary" toggle to control interface mode
   "view_4D" to toggle sending 3D or 4D info to geomview
   "D" or "autodisplay" for toggling automatic redraw when the surface changes.
       Default is automatic redraw when geomview is started.


<---------------------------- geomview command ---------------------------->

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.

<---------------------------- geomview install ---------------------------->

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

<--------------------------------- global --------------------------------->

Named method instance or named quantity attribute indicating the
instance or quantity is to be applied to all geometric elements of
the proper type.  This can only be done in the datafile top. Example:

   quantity george info_only edge_length global


<----------------------------- global_method ------------------------------>

The methodlist version of the quantity definition may contain one or more
method instances. To incorporate a previously explicitly defined instance,
include METHOD instancename. GLOBAL_METHOD may be used instead of METHOD to
indicate the method applies to all elements of the appropriate type; it is
equivalent to using GLOBAL in the method definition. To instantiate a
method in the quantity definition, you essentially incorporate the instance
definition, but without an instance name. Example of a quantity with one
predefined method instance and one implicitly defined instance:

   method_instance qwerty method facet_scalar_integral
     scalar_integrand: x^2
   quantity foobar energy method qwerty method edge_scalar_integral
     scalar_integrand: y^3

Usually the second, implicit definition will be more convenient. Several
method instances may be included in one methodlist (up to a current limit
of 50), and their values are added together and multiplied by the quantity
modulus to get the quantity value. The FUNCTION methodexpr variant defines
the quantity as a function of previously defined method instances. Example:

   method_instance qwerty method facet_scalar_integral
     scalar_integrand: x^2
   quantity foobar energy function qwerty.value^3

Non-global quantities may be applied to elements individually by adding
the quantity name to the datafile line defining an element. They may also
be applied or unapplied at runtime with the set and unset commands.
Orientable methods can be applied with negative orientation in the datafile
by following the name with a dash. The orientation in a set command follows
the orientation the element is generated with.

Methods applying to different types of elements may be combined in one
quantity. If such a quantity is applied to an element, then all method
instances of that quantity of the appropriate type are applied to the
element. Original attachments of quantities are remembered, so if an edge
method is applied to a facet, then edges created from refining that facet
will inherit the edge method.


<-------------------------------- graphics -------------------------------->

Surface Evolver graphics consists of drawing edges and facets. There is a
single graphics driver routine which produces colored edges and facets in
3D and sends them to a set of display routines. There are three main sets
of display routines:
 > Native screen graphics, built-in Evolver graphics of various qualities
   on various platforms,
 > Interface to the Geomview 3D viewer, for Unix/Linux users without
   OpenGL/GLUT graphics compiled into Evolver,
 > PostScript files, for everybody wanting to make 2D images for
   publications, web sites, etc.

Internal Evolver state information relevant to graphics:
 > edge color
 > facet color, frontcolor, and backcolor
 > edge show expression
 > facet show expression
 > facet shading toggle
 > facet brightness
 > facet_colors toggle
 > view matrix
 > view transform expression
 > transforms toggle
 > torus model display mode: raw_cells, clipped, or connected
 > surface thickness
 > show_inner and show_outer toggles
 > background color
 > window_aspect_ratio variable

 Datafile features that are relevant to graphics are:
 > edge color
 > facet color, frontcolor, and backcolor
 > view transforms
 > view transform generators
 > viewing matrix

 Main prompt commands that are relevant to all graphics are:
 > show, showq, and show_expr for controlling which elements are displayed.
 > set edge color
 > set facet color, frontcolor, backcolor
 > transforms toggle
 > transform_expr
 > thickness
 > torus model display mode toggles: raw_cells, clipped, or connected
 > show_inner and show_outer toggles


<---------------------------- graphics actions ---------------------------->

There are many mouse and keyboard actions that can be performed in the
graphics window itself. Holding down and dragging the left mouse button
moves the surface continuously, and the clicking right mouse button picks
vertices, edges, and facets. Picked element id numbers are printed in the
console window. With the graphics window in the foreground, these keyboard
commands are active:

h Print a help screen on the console window.
r Rotate mode for left mouse button.
t Translate mode for left mouse button.
z Zoom mode for left mouse button (and use F to focus on particular
  vertex).
c Clockwise/counterclockwise spin mode for left mouse button.
+ Widen edges.
- Narrow edges.
l Activate clipping plane (lower-case L) in translation mode for 
    left mouse button.
L Deactivate clipping plane.
k Activate clipping plane rotation mode for left mouse button.
b Decrement edge front bias by .001.
B Increment edge front bias by .001 (to show edges more clearly).
R Reset the view.
m Center the image.
M Have the right mouse button bring up a menu instead of picking.
P Have the right mouse button do picking instead of menu (default).
p Toggle orthogonal/perspective projection.
s Toggle cross-eyed stereo.
e Toggle showing edges, regardless of "show edge" condition.
f Toggle showing facets obeying "show facet" condition or no facets.
F Move the rotate/zoom origin to the last picked vertex.
G Start another graphics window with independent camera.
o Toggle drawing a bounding box.
g Toggle Gourard (smooth) shading.
x Close the graphics window.
arrow keys Translate a bit.

And some more advanced commands most users will never use, but are listed
here for completeness:

H Print advanced help.
a Toggle using OpenGL element arrays.
i Toggle interleaved elements in OpenGL arrays.
I Toggle indexed OpenGL arrays.
S Toggle OpenGL triangle strips.
Y Toggle strip coloring (I was curious as to what OpenGL triangle strips
   would look like).
D Toggle using a display list.
Q Toggle printing drawing statistics.


<--------------------------- graphics commands ---------------------------->

When the native graphics display is invoked by the 's' command or the
various `show' commands, the Evolver enters graphics mode, with the prompt
`Graphics command: '. A graphics command is a string of letters followed by
RETURN. Each letter causes an action. Some commands may be preceded by an
integer count of how many repetitions to do. Example command: 15u2z, which
does 'u' 15 times and 'z' twice. Rotation commands may be preceded by a
real number giving the degrees of rotation; an integer will give a
repetition count with the default angle of 6 degrees. A real number is
indicated by including a decimal point.

The letter commands in graphics mode are:
 u    Rotate up 6 degrees.
 d    Rotate down 6 degrees
 r    Rotate right 6 degrees.
 l    Rotate left 6 degrees.
 c    Rotate clockwise 6 degrees.
 C    Rotate counterclockwise 6 degrees.
 z    Zoom by factor of 1.2.
 s    Shrink by factor of 1.2.
 arrow keys - Translate image.
 m    Center image.
 R    Reset viewing parameters.
 T    Toggle additional viewing transforms.
 e    Toggle facet edge drawing.
 B    Toggle display of boundary facets.
 v    Toggle ridge and valley coloring.
 w    Toggle facets with three vertices on constraints.
 b    Draw bounding box.
 +,- Increment, decrement fill color.
 H    Toggle hidden surface removal.
 t    Set clipping mode for torus.
 ?,h help (this display)
 x,q Exit to main menu.

See help topics on individual letters, "r", "l", etc., for more details.

<-------------------------- graphics_title -------------------------------->
<-------------------------- graphics_title2 ------------------------------->
<-------------------------- graphics_title3 ------------------------------->

Internal read-write string variable.  This is the title that is displayed 
on the Evolver graphics window.  The default value is the datafile name.  
Useful when you are simultaneously running various instances, and you want 
to tell which is running in which graphics window.  Just assigning a string 
to graphics_title automatically changes the title on the window.
There are also graphics_title2 and graphics_title3 variables if you
have a second or third graphics window.
	
<-------------------------------- gravity --------------------------------->

Evolver toggle command. Includes the gravitational energy of bodies with
density in total energy. The gravitational constant can be set in the top
of the datafile with "gravity_constant = value", or with the runtime
commandis "G value" or "gravity_constant := value".

<---------------------------- gravity_constant ---------------------------->

Internal read-write variable for the strength of gravity in gravitational
potential energy. The gravitational constant can be set in the top
of the datafile with "gravity_constant value", or with the runtime
commands "G value" or "gravity_constant := value".


<----------------------------- gravity energy ----------------------------->

If a body has a density, then that body contributes its gravitational
energy to the total. The acceleration of gravity G is under user control
with the G command. Letting \rho be the body density, the energy is defined
as

  E = \int\int\int_{body} G \rho  z  dV

but is calculated using the Divergence Theorem as

  E =  \int\int_{body surface} G\rho {z^2\over 2} \vec k \cdot \vec{dS}.

This integral is done over each facet that bounds a body. If a facet
bounds two bodies of different density, then the appropriate difference in
density is used. Facets lying in the z = 0 plane make no contribution, and
may be omitted if they are otherwise unneeded. Facets lying in constraints
may be omitted if their contributions to the gravitational energy are
contained in constraint energy integrals. In the string model, all this
happens in one lower dimension.

Example datafile: mound.fe

<---------------------------- gravity_constant ---------------------------->

Internal read-write variable. Value of the gravitational constant,
which can also be set by the G command.   The initial value of the
gravitational constant may be set in the top of the datafile with the syntax
  GRAVITY_CONSTANT value
The default value is 1.

<------------------------------ ps_gridflag ------------------------------->
<-------------------------------- gridflag -------------------------------->

Evolver toggle command. If toggled on, the postscript command will show
all edges of displayed facets, instead of just those satisfying the current
edge show condition. "gridflag" is an old name for "ps_gridflag".


<------------------------------- gv_binary -------------------------------->

Evolver toggle command. Toggles sending data to geomview in binary format,
which is faster than ascii. Default is binary on SGI, ascii on other
systems, since there have been problems with binary format on some systems.
Ascii is also useful for debugging.


<----------------------------------- h ------------------------------------>

Single letter main command. Prints a very primitive help message listing
common commands. "help" is much better, as it accesses the full HTML
documentation. Or best, use a separate HTML browser on html\evolver.htm 
in the Evolver distribution, or 
http://www.susqu.edu/brakke/evolver/html/evolver.htm.



<---------------------------- h_inverse_metric ---------------------------->

Toggle. Replaces force by Laplacian of force. For doing motion by
Laplacian of mean curvature.

<--------------------------------- h_zero --------------------------------->

Some physical surfaces have their lowest energy state when their
mean curvature is some nonzero value.  An example is a membrane
made of parallel stacked molecules which have one end bigger than
the other.  Their curvature energy is thus proportional to (h-h0)^2,
where h is the actual mean curvature and h0 is the equilibrium or
intrinsic mean curvature. Several of the squared mean curvature
named methods can use h0, either in the form of a variable h_zero
or a real-valued vertex attribute h_zero.  If the vertex attribute
exists, it takes precedence. 

Methods using h_zero:
  sq_mean_curv_cyl
  sq_mean_curvature
  eff_area_sq_mean_curvature
  normal_sq_mean_curvature
  star_normal_sq_mean_curvature
  star_perp_sq_mean_curvature
  sqcurve2_string

Methods not using h_zero:
  star_sq_mean_curvature
  star_eff_area_sq_mean_curvature
  sqcurve_string
  sqcurve_string_marked 
  sqcurve3_string
  circle_willmore

<---------------------------------- help ---------------------------------->

Main prompt command.  Prints what Evolver knows about an identifier
or keyword.  User-defined variables, named quantities, named methods,
named constraints, and element attributes are identified as such.
Information for syntax keywords comes from a file evhelp.txt in
the doc subdirectory of your Evolver installation, so that subdirectory
should be on your EVOLVERPATH environment variable.
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.

Graphics mode command: 'h' or '?' will print a brief help screen for
graphics mode commands.

<-------------------------------- 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.   If the surface
is too far from equilibrium, a hessian move can blow up.  For safer
hessian moves, see hessian_seek, which does a line search along the
direction of the hessian move for minimum energy.


<---------------------------- hessian caveats ----------------------------->

When not near enough to an equilibrium, incautious use of "hessian" can
wreck a surface. If you don't know what's going to happen, save the surface
first. Or use hessian_seek. Or use hessian_menu, where you can restore the
surface with option 7. Or set " check_increase", which will abort a hessian
iteration that would increase energy. But remember sometimes hessian should
increase energy, for example to satisfy a volume constraint or reach an
unstable equilibrium.

Not all energies have built-in Hessians. If Evolver complains about
lacking a Hessian for a particular energy, you will either have to forego
hessian or find a way to phrase your problem in terms of an energy with a
Hessian.

There are three methods of sparse matrix factoring built into Evolver:
YSMP (Yale Sparse Matrix Package), my own minimal degree algorithm, and
METIS recursive bisection. The ysmp and metis_factor toggles can be used to
control which is active. METIS is the best overall, particularly on large
surfaces, but requires a separate download and compilation of the METIS
library (but it's easy; see the installation instructions).


<----------------------------- hessian intro ------------------------------>

Consider a particular surface in a particular configuration X, and
consider a small perturbation Y added to X. Then the energy may be expanded
in a Taylor series:

   E(X+Y) = E_0 + G^T Y + 1/2 Y^T H Y + ...

Here the constant E_0 is the original energy, E_0 = E(X). G is the vector
of first derivatives, the gradient, which is a vector the same dimension as
Y or X (G^T is a 1-form, if you want to get technical). Here ^T denotes the
transpose. H is the square matrix of second derivatives, the Hessian. The
Hessian is automatically a symmetric matrix. The gradient G determines the
best linear approximation to the energy, and the Hessian H determines the
best quadratic approximation.

Positive definiteness. If the quadratic term 1/2 Y^T H Y is always
positive for any nonzero Y, then H is said to be positive definite. At an
equilibrium point, this means the point is a strict local minimum; this is
the multivariable version of the second derivative test for a minimum. If
the quadratic term is zero or positive, then H is positive semi-definite.
No conclusion can be drawn about being a local minimum, since third-order
terms may prevent that. If the quadratic term has positive and negative
values, then H is indefinite.

Constraints. If there are constraints on the surface, then the the
perturbation vector Y is required to be tangent to the feasible set in
configuration space. The curvature of the feasible set can have an effect
on H, but this is taken care of automatically by the Evolver. This effect
arises from the slight change in energy due to the projection back to the
feasible set after motion. This does not affect the gradient, but it does
affect the Hessian. In particular, if Q is the Hessian of a global
constraint and q is the Lagrange multiplier for the constraint, then the
adjusted energy Hessian is H - qQ. Therefore it is necessary to do a 'g'
step to calculate Lagrange multipliers before doing any Hessians when there
are global constraints.


<--------------------------- hessian iteration ---------------------------->

Or how to converge really really fast.
Suppose we assume the quadratic approximation to the surface energy is a
good one. Then we can find an equilibrium point by solving for motion Y
that makes the energy gradient zero. Recalling that G and H depend only on
X, the energy gradient as a function of Y is

          grad E = G^T + Y^T H.

So we want G^T + Y^T H = 0, or transposing,

           G + H Y = 0.

Solving for Y gives

            Y = - H^-1 G.

This is actually the Newton-Raphson Method applied to the gradient. The
Evolver's "hessian" command does this calculation and motion. It works best
when the surface is near an equilibrium point. It doesn't matter if the
equilibrium is a minimum, a saddle, or a maximum. However, nearness does
matter. Remember we are dealing with thousands of variables, and you don't
have to be very far away from an equilibrium for the equilibrium to not be
within the scope of the quadratic approximation. When it does work,
"hessian" will converge very quickly, 4 or 5 iterations at most.

Example: Start with the cube datafile cube.fe. Evolve with "r; g 5; r; g
5;". This gets very close to an equilibrium. Doing "hessian" a couple of
times gets to the equilibrium:

Enter command: hessian
  1. area:  4.85807791572284 energy:  4.85807791572284
Enter command: hessian
  1. area:  4.85807791158432 energy:  4.85807791158432
Enter command: hessian
  1. area:  4.85807791158431 energy:  4.85807791158431

So Hessian iteration converged in two steps. Furthermore, this is a local
minimum rather than a saddle point, since Evolver did not complain about a
non-positive definite Hessian.

NOTE: The hessian command will work with indefinite Hessians, as long as
there are no eigenvalues too close to zero. The warning about non-positive
definite is for your information; it is does not mean hessian has failed.


<----------------------------- hessian metric ----------------------------->

Hessian with metric.

One would expect that refining the surface would lead the eigenvalues to
converge to the eigenvalues for the smooth surface. But as the previous
section showed, refining caused the eigenvectors to all shrink by about a
factor of 4. This is no way to converge. The explanation is that so far we
have been looking at eigenvectors in slightly the wrong way. An eigenvector
is supposed to represent a mode of perturbation that is proportional to the
force. However, the response of a surface to a force need not be
numerically equal to the force. After all, forces and displacements are
different kinds of things. They have different units: displacement has
units of distance, and force has units of energy per distance. In other
words, displacement is a vector and force is a covector. Note that matrix
multiplication by the Hessian H turns a vector into a covector. In general,
to turn a vector into an equivalent covector, one needs an inner product,
or metric. So far we have been using the Euclidean inner product on
configuration space, but that is not the proper one to use if you want to
approximate smooth surfaces. The proper inner product of perturbations f
and g of a smooth surface is the integral over the surface of the pointwise
inner product:

           /
   <f,g> = | <f(x),g(x)> dA.
           /

In discrete terms, the inner product takes the form of a square matrix M
such that <Y,Z> = Y^T M Z for vectors Y,Z. We want this inner product to
approximate integration with respect to area. Having such an M, the
eigenvalue equation becomes

               H Q = q M Q.

Officially, Q is now called a "generalized eigenvector" and q is a
"generalized eigenvalue". But we will drop the "generalized". An intuitive
interpretation of this equation is as Newton's Law of Motion,
              Force = Mass * Acceleration
where HQ is the force, M is the mass, and qQ is the acceleration. In other
words, in an eigenmode, the acceleration is proportional to the
perturbation.

The Evolver command "linear_metric" includes M in the eigenvector
calculations. Two metrics are available. In the simplest, the "star
metric", M is a diagonal matrix, and the "mass" associated with each vertex
is 1/3 of the area of the adjacent facets (1/3 since each facet gets shared
among 3 vertices). The other, the "linear metric", extends functions from
vertices to facets by linear interpolation and integrates with respect to
area. By default, "linear_metric" uses a 50/50 mix of the two, which seems
to work best. See the more detailed discussion below in the eigenvalue
accuracy section. The fraction of linear metric can be set by assigning the
fraction to the internal variable linear_metric_mix. By default,
linear_metric_mix is 0.5. In quadratic mode, however, only the quadratic
interpolation metric is used, since the star metric restricts convergence
to order h^2 while the quadratic interpolation metric permits h^4
convergence.

Example: Run square.fe, and refine twice. Do "linear_metric" and
"ritz(0,10)".

Enter command: linear_metric
Using linear interpolation metric with Hessian.
Enter command: ritz(0,10)
Eigencounts:    0
  1.    2.036549240354335
  2.    4.959720306550875
  3.    4.959720306550875
  4.    7.764634143334637
  5.   10.098798069316683
  6.   10.499717069102575
  7.   12.274525789880887
  8.   12.274525789880890
  9.   15.7679634642721
 10.   16.7214142904405
Iterations: 127. Total eigenvalue changes in last iteration: 1.9602375e-014

 After refining again:

Enter command: ritz(0,10)
Eigencounts:    0
  1.    2.009974216370147
  2.    4.999499042685446
  3.    4.999499042685451
  4.    7.985384943789077
  5.   10.090156419079085
  6.   10.186524915471155
  7.   13.008227978344527
  8.   13.008227978344527
  9.   17.242998229925817
 10.   17.2429982299600
Iterations: 163. Total eigenvalue changes in last iteration: 1.9186042e-014

This looks much more convergent.

Using linear_metric does NOT change the inertia of the Hessian, by
Sylvester's Law of Inertia. So the moral of the story is that if you care
only about stability, you don't need to use linear_metric. If you do care
about the actual values of eigenvectors, and want them relatively
independent of your triangulation, then use linear_metric.


<-------------------------- hessian normal mode --------------------------->

The alert reader will have notice that in the examples so far there has
been only one degree of freedom per vertex, instead of the three one might
expect, since a vertex has three degrees of freedom to move in space. The
answer is that in Hessian activities, it is usually best to only allow
motion perpendicular to the surface, and suppress the two degrees of
freedom of motion of a vertex tangential to the surface. The reason is that
tangential motion changes the energy of the surface very little if at all,
leading to many small eigenvalues and a severely singular Hessian. For
example, run square.fe, refine twice, and do "hessian_normal off" to enable
all degrees of freedom. Now "eigenprobe 0" reveals 50 zero eigenvalues:

   Enter command: hessian_normal off
   hessian_normal OFF. (was on)
   Enter command: eigenprobe 0
   Eigencounts:    0

For a curved surface, the extra eigenvalues generally won't be zero, but
they will all be close to zero, both positive and negative, which can
really foul things up. The default value of hessian_normal is therefore the
ON state. The moral of the story is to always leave hessian normal on,
unless you really really know what you are doing.

On some surfaces, for example soap films with triple junctions and
tetrahedral points, there are vertices with no natural normal vector.
Evolver hessian_normal mode assigns those points normal subspaces instead,
so that vertices on a triple line can move in a two-dimensional normal
space perpendicular to the triple line, and tetrahedral points can move in
all three dimensions.

If you wish to run in hessian_normal mode but exempt particular vertices
from the restriction, you can "set" the vertices' no_hessian_normal
attribute, for example
   set vertex no_hessian_normal where z > 1.2

The reason for possible negative extra eigenvalues when hessian_normal is
off is that one rarely has the best possible vertex locations for a given
triangulation of a surface, even when its overall shape is very close to
optimal. Vertices always seem to want to slither sideways to save very very
small amounts of energy. The amount of energy saved this way is usually
much less than the error due to discrete approximation, so it is usually
advisable not to try to get the absolute best vertex positions.

There is one effect of hessian_normal that may be a little puzzling at
first. Many times a surface is known to have modes with zero eigenvalue;
translational or rotational modes, for example. Yet no zero eigenvalues are
reported. For example, with the cube eigenvalues found above,

Eigencounts:    0
  1.    0.001687468263013
  2.    0.001687468263013
  3.    0.001687468263013
  4.    0.2517282974725
  5.    0.2517282974731

One might expect 6 zero eigenvalues from three translational modes and
three rotational modes. But the rotational modes are eliminated by the
hessian_normal restriction. The three translational modes have eigenvalue
near 0, but not exactly 0, since normal motion can approximate the
translation of a cube, but not exactly. The effective translation results
from vertices moving in on one hemisphere and out on the other. This
distorts the triangulation, raising the energy, hence the positive
eigenvalue. This effect decreases with refinement.

There are times when the normal direction is not the direction one 
wants. If one knows the perturbation direction, one can use the 
hessian_special_normal feature to use that instead of the default normal.
Beware that hessian_special_normal also applies to the normal calculated by
the vertex_normal attribute and the normal used by regular vertex averaging.


<---------------------------- hessian tutorial ---------------------------->

For a tutorial on using the hessian and related commands, see
eigentut.htm in the doc subdirectory of the Evolver distribution, or
browse http://www.susqu.edu/brakke/evolver/html/eigentut.htm.

<------------------------------ hessian_diff ------------------------------>

Evolver toggle command. Toggles computing the hessian matrix by finite
differences. Used only for debugging, since it is very slow, and there
are some features it cannot handle.

<------------------------- hessian_double_normal -------------------------->

Evolver toggle command. When hessian_normal is also on, and the space
dimension is even, this toggle makes the normal vector components in the
last half of the dimensions copies of the components in the first half. Sounds
weird, huh? But it is useful in calculating the stability of cylindrically
symmetric surfaces using a string model in 4D.


<---------------------------- hessian_epsilon ----------------------------->

Internal read-write variable. This is the magnitude regarded as zero by
the hessian command when factoring the Hessian matrix. If a zero appears on
the diagonal at the pivot during factoring, a check is made to see if the
rest of the row is zero. If it is, then a 1 is placed on the diagonal; else
an error is reported.

<------------------------------ hessian_menu ------------------------------>

Main prompt command. Brings up a subsidiary command prompt 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,
with the hessian_menu help line and additional comments:
 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
    as 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. You can enter the eigenvector by its number in the
    list from the Z option. As a special bonus useful when there are multiple
    eigenvectors for an eigenvalue, you can enter the vector as a linear
    combination of eigenvectors, e.g. ``0.4 v1 + 1.3 v2 - 2.13 v3''.

 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.

 =. Subshell.
    Starts a command prompt while still in hessian_menu. You can do pretty
    much any command, but you should not do anything that changes the surface,
    thus invalidating the Hessian data. This is meant, for example, for
    creating a graphics file of an eigenvalue perturbation and then returning
    to the hessian_menu prompt. You exit the subshell with the "q" command.

 D. Dump Hessian to text file in Matlab sparse format.  Will prompt for 
    file name.  Includes Hessian, constraints, right side, metric, etc.
    for full external analysis.

 K. Dump Hessian to text file in Mathematica sparse format.  Will prompt for
    file name.  Includes Hessian, constraints, right side, metric, etc.
    for full external analysis.

 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.   After the 4 step, you could use "=" to go to a subcommand prompt
and dump the perturbed surface or make a PostScript file of it.

<----------------------------- hessian_normal ----------------------------->

Evolver toggle command. Constrains Hessian to move each vertex
perpendicular to the surface. This eliminates all the fiddly sideways
movement of vertices that makes convergence difficult. Perpendicular is
usually defined as the volume gradient, but at triple (and higher) junction
lines it is a subspace perpendicular to the line, and singular points where
several triple lines meet have full degrees of freedom. See
hessian_normal_one to alter this behavior.  Default is ON.

If you wish to run in hessian_normal mode but exempt particular vertices
from the restriction, you can "set" the vertices' no_hessian_normal
attribute, for example
   set vertex no_hessian_normal where z > 1.2


<--------------------------- hessian_normal_one --------------------------->

Evolver toggle command. If this and hessian_normal are on, then the normal
at any point will be one dimensional. This is meant for soap films with
Plateau borders, where there are triple junctions with tangent films.
Ordinary hessian_normal permits lateral movement of such triple junctions,
but hessian_normal_one does not. Valid only for string model in 2D and
soapfilm model in 3D. The normal vector is computed as the eigenvector of
the largest eigenvalue of the sum of the normal projection matrices of all
edges or facets adjoining a vertex.


<-------------------------- hessian_normal_perp --------------------------->

Evolver toggle command. If this is on, then the Hessian linear_metric uses
only the component of the normal perpendicular to the facet or edge. This
raises eigenvalues slightly.


<----------------------------- hessian_quiet ------------------------------>

Evolver toggle command. Toggles suppression of printing of information
during hessian calculations. Default is ON.


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


<-------------------------- hessian_slant_cutoff -------------------------->

Internal read-write variable. Makes Hessian commands treat vertices
whose normal vector is nearly perpendicular to constraints
as fixed. hessian_slant_cutoff is the cosine of angle. Works on vertices
with one degree of freedom in hessian_normal mode. Default value 0.


<------------------------- hessian_special_normal ------------------------->

Evolver toggle command. When hessian_normal is on, this toggles using a
special vectorfield for the direction of the perturbation, rather than the
usual surface normal. The vectorfield is specified in the
hessian_special_normal_vector section of the datafile header. Beware that
hessian_special_normal also applies to the normal calculated by the
vertex_normal attribute and the normal used by regular vertex averaging.

<--------------------- hessian_special_normal_vector ---------------------->

Evolver toggle command. When hessian_special_normal is on, hessian commands
use a special vectorfield for the direction of the perturbation, rather than
the usual surface normal. The vectorfield is specified in the top of the
datafile in the format

HESSIAN_SPECIAL_NORMAL_VECTOR
c1: expr
c2: expr
c3: expr

One can use vertex attributes in the expressions. Beware that
hessian_special_normal also applies to the normal calculated by the
vertex_normal attribute and the normal used by regular vertex averaging.

<-------------------------- hexadecimal numbers --------------------------->

The format for hexadecimal integers is to start with 0x, as in 0x12Af.
There is no bound on the size, but values too large for the internal
representation of integers will have their higher digits truncated.

<----------------------------- high_boundary ------------------------------>

Internal read-only variable giving the number of the highest
parametric boundary defined.  Remember that the name of a named
boundary is internally interpreted as a number, and that boundary
may be referred to by that number.   Useful in iterating through
all boundaries, for example

  for ( bnum := 1 ; bnum <= high_boundary ; bnum += 1 )
    if valid_boundary(bnum) then
       printf "Boundary %d has %d vertices on it\n",bnum,
          sum(vertex,on_boundary bnum);

<---------------------------- high_constraint ----------------------------->

Internal read-only variable giving the number of the highest
level-set constraint.  Remember that the name of a named
constraint is internally interpreted as a number, and that constraint
may be referred to by that number.   Useful in iterating through
all constraints, for example

  for ( cnum := 1 ; cnum <= high_constraint ; cnum += 1 )
    if valid_constraint(cnum) then
       printf "Constraint %d has %d vertices on it\n",cnum,
          sum(vertex,on_constraint cnum);

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

<------------------------------ history list ------------------------------>

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.

<----------------------------- hit_constraint ----------------------------->

Vertex read-only attribute. Boolean attribute for whether a vertex exactly
satisfies a given constraint. Particularly meant for vertices on one-sided
constraints. The full syntax of the attribute is "hit_constraint n" where n
is the number or name of the constraint. Examples:

   list vertex where hit_constraint 3
   print vertex[3].hit_constraint 1

<------------------------------- homothety -------------------------------->

Evolver toggle command. Adjust total volume of all bodies to fixed value
after each 'g' iteration by uniformly scaling entire surface.  The
total volume is in the read-write variable homothety_target, which
may also be set in the top of the datafile with the syntax

  HOMOTHETY_TARGET constexpr

<----------------------------- hooke2_energy ------------------------------>

Named method. Description: Same as hooke_energy, but each edge has an
equilibrium length extra attribute `hooke_size' (which the user need not
declare). If the user does not set hooke_size by the time the method is
first called, the value will default to the current length. Hooke_size is
not automatically adjusted by refining. It is the responsibility of the 
user to reset hooke_size after refining; you could re-define the 'r' command
   r :::= { 'r'; set vertex hooke_size hooke_size/2 }
to take care of it automatically.

The power of displacement used is given by the internal read-write variable 
hooke2_power, which has default value 2.   hooke2_power can be fractional
or negative.

Element: edge. 
Parameters: none. 
Models: linear. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

   parameter hooke2_power  2     // the default
   define edge attribute hooke_size real
   quantity slinky energy method hooke2_energy global
   ...
   read
   r; r; set edge hooke_size length

<------------------------------ hooke2_power ------------------------------>

Parameter used by the hooke2_energy method.  See hooke2_energy for details.
hooke2_power can be fractional or negative.

<------------------------------ hooke3_power ------------------------------>

Parameter used by the hooke3_energy method.  See hooke3_energy for details.
hooke3_power can be fractional or negative.

<---------------------------- frickenhaus_flag ---------------------------->

Toggle variable used by hooke3_energy.  See hooke3_energy for details.
If frickenhaus_flag is nonzero, then the energy is taken to be 0 if the 
edge length is less than the equilibrium length.

<----------------------------- hooke3_energy ------------------------------>

Named method. Description: Same as hooke2_energy, but uses an elastic
model instead of a spring. The energy is
    energy = 0.5*(length-hooke_size)^2/hooke_size.
The exponent can be altered from 2 by setting the parameter hooke3_power.
If the internal variable frickenhaus_flag is nonzero, then the energy
is taken to be 0 if the length is less than the equilibrium length.
hooke2_power can be fractional or negative.  It defaults to 2.

Element: edge. 
Parameters: none. 
Models: linear. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

   parameter hooke3_power  2     // the default
   quantity slinky energy method hooke3_energy global
   ...
   read
   r; r; set edge hooke_size length

<------------------------------ hooke_power ------------------------------->

Internal variable that specifies the exponent in the calculation of
the hooke_energy method.  Default value 2.  It can be negative or fractional.
See hooke_energy for more.

<------------------------------ hooke_energy ------------------------------>

Named method. Description: One would often like to require edges to have
fixed length. The total length of some set of edges may be constrained by
defining a fixed quantity. This is used to fix the total length of an
evolving knot, for example. But to have one constraint for each edge would
be impractical, since projecting to n constraints requires inverting an n x
n matrix. Instead there is a Hooke's Law energy available to encourage
edges to have equal length. Its form per edge is

   energy =  | L - L_0 |^p

where L is the edge length, L_0 is the equilibrium length, embodied as an
global variable `hooke_length', and the power p is an adjustable parameter 
`hooke_power', which can be negative or fractional. The default power is p = 2,
and the default equilibrium length is the average edge length in the initial 
datafile. You will want to adjust this, especially if you have a total length 
constaint. A high modulus will decrease the hooke component of the total 
energy, since the restoring force is linear in displacement and the energy is 
quadratic (when p=2). As an extra added bonus, a `hooke_power' of 0 will give
    energy = -\log|L-L_0|.
See hooke2_energy for individual edge equilibrium lengths. 

Element: edge.
Parameters: none. 
Models: string; linear. 
Ambient dimension: any. 
Hessian: yes.
Example datafile declaration:

   parameter hooke_length 0.3   // will apply to all edges
   parameter hooke_power  2     // the default
   quantity slinky energy method hooke_energy global

<------------------------------ hooke_length ------------------------------>

Internal read-write variable that specifies the equilibrium length
for the hooke_energy named method.  It is the responsibility of the
user to divide hooke_length by 2 when refining.

<------------------------------- hooke_size ------------------------------->

Edge extra attribute that specifies the equilibrium length for
that edge for the hooke2_energy and hooke3_energy methods.  If not
initialized by the user, its default value is the initial length of
the edge.  It is the responsibility of the user to reset hooke_size
after refining; you could re-define the 'r' command
   r :::= { 'r'; set vertex hooke_size hooke_size/2 }
to take care of it automatically.

<----------------------------------- i ------------------------------------>

Single letter main command. Prints miscellaneous information:
   Name of datafile
   Total energy
   Total area of facets
   Count of elements and memory usage
   Area normalization, if on
   LINEAR or QUADRATIC model
   Whether conjugate gradient on
   Order of numerical integration
   Scale factor value and option (fixed or optimizing)
   Diffusion option and diffusion constant value
   Gravity option and gravitational constant value
   Jiggling status and temperature
   Gap constant (for gap energy, if active)
   Ambient pressure (if ideal gas model in effect)


<----------------------------------- id ----------------------------------->

Geometric element read-only attribute. The id of an element is a positive
integer uniquely associated with that element. The Evolver will assign id's
to elements read from the datafile in the order they are read, unless the
-i command line option or keep_originals is in the top of the datafile, in
which case the datafile element number is the id. In either case, you can
access the datafile id with the original attribute. Examples:
   list vertex where id < 10
   set edge color red where id == 4 or id == 6 or id == 9
   foreach facet ff do { printf "%g  %g %g %g\n",ff.id,ff.edge[1].id,
      ff.edge[2].id,ff.edge[3].id }
See also the "oid" attribute, for a signed version of the id indicating
element orientation.


<------------------------- ideal gas declaration -------------------------->

A line in the top section of the datafile of the form

   PRESSURE constexpr

specifies that bodies are compressible and the ambient pressure is the
value of constexpr. The default is that bodies with given volume are not
compressible.

<------------------------------ identifiers ------------------------------->

Identifiers follow standard C rules (composed of alphanumeric characters
and '_' with the leading character not a digit) and must not be keywords.
Identifiers are used for macro names (in the datafile) and user-defined
variables and commands. Identifiers must have at least two characters,
since single characters can be confused with commands. To find out if a
name is already in use as a keyword or user-defined name interactively, use
help command. In scripts, one can use the is_defined function, which has
the syntax

 is_defined(stringexpr)

The stringexpr must be a quoted string or other string expression. The
return value is 0 if the name is undefined, 1 if defined. This function is
evaluated at run-time, but variables in the whole command are parsed before
the command is executed, so a command like if is_defined("newvar") then
newvar := 1 else newvar := 2 will give newvar the value 1 even if this is
its first appearance. A better way in scripts to test is to use the define
command to define the variable without initialization, and then test to see
if it has the default value, i.e. 0 for a numeric variable and a sizeof 0
for a string variable.


<---------------------------------- idiv ---------------------------------->

Integer divide. Rounds toward zero, then does integer division. Examples:
   "7 idiv 2" is 3; "-3.5 idiv 2.1" is -1; "-3 idiv 2" is -1.


<----------------------------------- if ----------------------------------->
<---------------------------------- then ---------------------------------->

Commands may be conditionally executed by the syntax

   IF expr THEN command

   IF expr THEN command ELSE command

where 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. Examples:

   if ( denom == 0 ) then return;
   if max(edges,length) > 0.02 then {r; g 100} else g 4;


<--------------------------- ignore_constraints --------------------------->
<------------------------------ ignore_fixed ------------------------------>

For squared curvature methods calculating at a boundary vertex,
the default calculation gives the proper curvature under the
assumption the surface is continued by reflection across the constraint.
This permits symmetric surfaces to be represented by one fundamental
region. If the edge of the surface is a fixed edge or on a 1-dimensional
boundary, then there is no way to calculate the curvature on a boundary
vertex from knowledge of neighboring facets. For example, the rings of
facets around the bases of a catenoid and a spherical cap may be identical.
Therefore curvature is calculated only at interior vertices, and when the
surface integral is done, area along the boundary is assigned to the
nearest interior vertex. However, including IGNORE_FIXED or
IGNORE_CONSTRAINTS in the method declaration will force the calculation of
energy even at fixed points or ignoring constraints respectively.

<--------------------------- immediate_autopop ---------------------------->

Toggle.  Modifies the autopop mode. Causes deletion of a short edge
or small facet immediately upon detection, before proceeding with further
detection of small edges or facets.  Original behavior was to do all
detection before any elimination, which could cause bad results if a 
lot of edges got short simultaneously. Default off for backward
compatibility, but you should probably turn it on.


<---------------------------------- imod ---------------------------------->

Integer arithmetic modulus, defined by

    x imod y = floor(x) - floor(floor(x)/floor(y))*floor(y)

<------------------------- implemented symmetries ------------------------->

The currently implemented symmetry groups are:
   torus - The underlying group for the torus model.
   rotate - Cyclic group of rotations in the x-y plane.
   flip_rotate - Cyclic group of rotations in the x-y plane with z -> -z
        with every odd rotation.
   cubocta - Full point group of a cube.
   xyz - The orientation-preserving subgroup of cubocta.
   genus2 - For a 2 dimensional genus 2 hyperbolic quotient space.
   dodecahedron - For a 3D hyperbolic quotient space with dodecahedral
        fundamental region.
   central_symmetry - Inversion through the origin, X -> -X.
   screw_symmetry - Screw motion along z axis.


<----------------------------- include files ------------------------------>

The standard C language method of including other files is available in
the datafile or files input with the "read" command. The file name must
be in double quotes. If the file is not in the current directory,
EVOLVERPATH will be searched. Includes may be nested to 10 deep.
Example:

        #include  "common.stuff"


<-------------------------- incompleteEllipticE --------------------------->

incompleteEllipticE(phi,m), incompleteEllipticF(phi,m): Incomplete elliptic
functions of parameters (phi,m); agrees with Mathematica definition.

<-------------------------- incompleteEllipticF --------------------------->

incompleteEllipticE(phi,m), incompleteEllipticF(phi,m): Incomplete elliptic
functions of parameters (phi,m); agrees with Mathematica definition.

<--------------------------------- index ---------------------------------->
<-------------------------------- inertia --------------------------------->

Index and inertia. The number of negative eigenvalues of H is called the
index of H. The triple of numbers of negative, zero, and positive
eigenvalues is called the inertia of H. One can also speak of the inertia
relative to a value c as the inertia of H-cI, i.e. the number of
eigenvalues less than c, equal to c, and greater than c. Sylvester's Law of
Inertia says that if P is a nonsingular matrix of the same dimension as H,
then the matrix

                        K = P H P^T

has the same inertia as H, although not the same eigenvalues. The Evolver
can factor a Hessian into a form

                        H = L D L^T

where L is a lower triangular matrix and D is diagonal. Hence the inertia
of H can be found by counting signs on the diagonal of D. Inertia relative
to c can be found by factoring H-cI.

The eigenvectors associated to a particular eigenvalue form a subspace,
whose dimension is called the "multiplicity" of the eigenvalue.


<---------------------------- indexed elements ---------------------------->

In aggregate commands or element generators, an element type name
referring to the whole set of an element type may be given an index
to generate just the one element with that id, for example:
  list vertex[3]
When the element type refers to a subelement of another element, then
the index refers to subelements in Evolver's internal order, for
example
  list edge ee where ee.vertex[1].z > 1.2

<------------------------------- info_only -------------------------------->

One of the types of named quantities, along with energy, fixed, and
conserved.  INFO_ONLY quantities whose values are merely reported to the user.
Info_only status may be set in the datafile declaration of the quantity,
for example,
   quantity george info_only method facet_area
or may be set at runtime with the "set" command:
   set george info_only


<----------------------------- initialization ----------------------------->

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

 1. Any previous surface has all memory deallocated. All user-defined
    variables and commands are deleted, including any currently executing
    commands.

 2. Internal variables are initialized to default values.

 3. The datafile is read in.

 4. In the soapfilm model, any nontriangular face is divided into triangles
    by creating a vertex in the center and making edges from the center to the
    vertices.

 5. In the soapfilm model, the order of facets around each edge is
    determined geometrically.

 6. Vertices are projected to any level set constraints.

 7. Checks as described for the C command are done.

 8. Initial areas, energies, and volumes are calculated.

 9. The viewing matrix is reset to center the object in the graphics window.


10. If any graphics are active, the new surface is drawn.

11. The main command prompt is started.

<--------------------------------- input ---------------------------------->

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.

<---------------------------- instance modulus ---------------------------->

Every method instance has a "modulus", which is multiplied times the basic
method value to give the instance value. A modulus of 0 causes the entire
instance calculation to be omitted whenever quantities are calculated. The
modulus may be set in the declaration in the top of the datafile or by 
assignment at runtime.
Example commands:
  print moment.modulus
  moment.modulus := 1.3

A method instance may be declared to use a different modulus for each
element by specifying an element extra attribute to use for that purpose.
The extra attribute has to have already been declared. Example:

   define facet attribute mymod real
   quantity myquant energy method facet_area global element_modulus mymod

Of course, it is up to the user to properly initialize the values of the
extra attribute.


<------------------------- instance_name modulus -------------------------->

Internal read-write variable. Modulus of a named method instance.
Examples, supposing a named method instance "george" exists:
   print george.modulus
   george.modulus := 4


<-------------------------- instance_name value --------------------------->

Internal read-only variable. Value of a named method instance.
Example, supposing a named method instance "george" exists:
   print george.value

<------------------------- insulating_knot_energy ------------------------->

Datafile keyword that automatically creates an energy named quantity using
the method uniform_knot_energy as a global method. May be followed in the
datafile with a modulus value.

<-------------------------------- integer --------------------------------->

One of the datatypes possible for extra attributes, function arguments,
function return values, and arrays.

<----------------------------- integral_order ----------------------------->

Internal read-write variable. Order of polynomial done by 1D and 2D
Gaussian integration. Much better to set 1D and 2D separately.
Synonym: integration_order

<--------------------------- integral_order_1d ---------------------------->

Internal read-write variable. Order of polynomial done
by 1D Gaussian integration. Synonym: integration_order_1D

<--------------------------- integral_order_2d ---------------------------->

Internal read-write variable. Order of polynomial done
by 2D Gaussian integration. Synonym: integration_order_2D

<--------------------------- integration_order ---------------------------->

Internal read-write variable. Order of polynomial done by
1D and 2D Gaussian integration. Much better to set 1D and 2D separately.
Synonym: integration_order

<-------------------------- integration_order_1d -------------------------->

Internal read-write variable. Order of polynomial done
by 1D Gaussian integration. Synonym: integration_order_1D

<-------------------------- integration_order_2d -------------------------->

Internal read-write variable. Order of polynomial done
by 2D Gaussian integration. Synonym: integration_order_2D

<--------------------------- internal variables --------------------------->

These are pre-defined names for some of Evolver's internal variables. They
may be used in the same way as user-defined variables, except the values of
read-only variables may not be changed by the user.

 > ambient_pressure_value
 > background
 > body_count
 > breakflag
 > body_dissolve_count
 > brightness
 > check_count
 > clock
 > constraint_tolerance
 > cpu_counter
 > datafilename
 > date_and_time
 > delete_count
 > dissolve_count
 > edge_count
 > edge_delete_count
 > edge_dissolve_count
 > edge_refine_count
 > edge_pop_count
 > edgeswap_count
 > eigenneg
 > eigenpos
 > eigenvalues
 > eigenzero

 > equi_count
 > estimated_change
 > facet_count
 > facetedge_count
 > facet_delete_count
 > facet_dissolve_count
 > fix_count
 > gravity_constant
 > hessian_epsilon
 > hessian_slant_cutoff
 > instance_name.modulus
 > instance_name.value
 > inverse_periods
 > integral_order
 > integral_order_1d
 > integral_order_2d
 > iteration_counter
 > jiggle_temperature
 > lagrange_order
 > last_eigenvalue
 > last_error
 > last_hessian_scale

 > linear_metric_mix
 > memory_arena
 > memory_used
 > notch_count
 > pickvnum
 > pickenum
 > pickfnum
 > pop_count
 > pop_edge_to_tri_count
 > pop_quad_to_quad_count
 > pop_tri_to_edge_count
 > quadratic_metric_mix
 > quantity_name.modulus
 > quantity_name.pressure
 > quantity_name.target
 > quantity_name.value
 > random
 > random_seed
 > refine_count
 > rotation_order
 > scale

 > scale_scale
 > scrollbuffersize
 > simplex_representation
 > space_dimension
 > surface_dimension
 > symmetry_group
 > t1_edgeswap_count
 > target_tolerance
 > temperature
 > thickness
 > torus
 > torus_periods
 > total_area
 > total_energy
 > total_length
 > total_time
 > transform_count
 > unfix_count
 > vertex_count
 > vertex_dissolve_count
 > vertex_pop_count
 > where_count
 > window_aspect_ratio


<------------------------ interp_bdry declaration ------------------------->

Interpolation of parameters:
To use interpolation instead of extrapolation in calculating the
parameters of edge midpoints during refining, use the keyword

   INTERP_BDRY_PARAM

in the top of the datafile.  This should be done only if there are no
periodic parameters.   There is also the runtime toggle command
interp_bdry_param.

<--------------------------- interp_bdry_param ---------------------------->

Evolver toggle command. For edges on parametric boundaries, calculate the
parameter values of new vertices (introduced by refining) by interpolating
parameter values, rather than extrapolating from one endpoint. Useful only
when parameters are not periodic.  Default off.


<----------------------------- interp_normals ----------------------------->

Evolver toggle command. Display using interpolated vertex normals for
shading for those graphics interfaces that support it.


<------------------------------- interrupts ------------------------------->

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

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


<---------------------------- inverse_periods ----------------------------->

inverse_periods[expr][expr] : Internal read-only variable. Inverse matrix
of the torus_periods matrix. Uses 1-based indexes. Useful for normalizing
vertex coordinates to period basis.

<------------------------------- is_defined ------------------------------->

Funcion to find out if a name is already in use as a keyword or
user-defined namer. Syntax:

 is_defined(stringexpr)

The stringexpr must be a quoted string or other string expression. The
return value is 0 if the name is undefined, 1 if defined. This function is
evaluated at run-time, but variables in the whole command are parsed before
the command is executed, so a command like

     if is_defined("newvar") then newvar := 1 else newvar := 2

will give newvar the value 1 even if this is its first appearance. A better
way in scripts to test is to use the define command to define the variable
without initialization, and then test to see if it has the default value,
i.e. 0 for a numeric variable and a sizeof 0 for a string variable. Example:
     qwerty := 4
     ...
     define qwerty
     if qwerty == 0 then { /* new */ } else { /* old */ }


<-------------------------------- itdebug --------------------------------->

Evolver toggle command. Prints some debugging information during a 'g'
step. For gurus only.


<----------------------------- iteration step ----------------------------->

Each 'g' command iteration does the following:
 1. Calculates the force vector at each vertex as the gradient of the total
    energy.
 2. Calculates the gradients at each vertex of constrained body volumes and
    named quantities. Also calculates the multiple of gradient motion needed to
    restore target values of the constraints.
 3. Projects the forces to be tangent to level set constraints, volume
    constraints (pressure is calculated here), and fixed quantity constraints.
 4. If any mobility options are in effect, the proper force to velocity
    conversion is done.
 5. If the normal_motion toggle is on, then velocities are projected to the
    surface normal.
 6. Does the conjugate gradient projection, if conjugate gradient is in
    effect.
 7. The current vertex positions are saved.
 8. If the optimizing mode is on, then trial motions are made to find the
    optimal scale factor.
 9. The scale factor is multiplied by the value of the scale_scale internal
    variable. (Useful only if you want to muck around with modifying the
    optimal scale factor for some strange reason.)
10. Each vertex is moved by the scale factor times the velocity, plus the
    volume and fixed quantity restoring motions. If runge_kutta is in effect,
    then a fourth-order Runge-Kutta step is done instead of a simple Euler
    step.
11. All level set constraints are enforced. Vertices violating an inequality
    or equality constraint are projected to the constraint (Newton's method).
    Several projection steps may be needed, until the violation is less that a
    certain tolerance or a certain number of steps are done (which generates a
    warning message). The default constraint tolerance is 1e-12, but it can be
    set with the CONSTRAINT_TOLERANCE option in the datafile, or setting the
    constraint_tolerance variable.
12. If jiggling is on, the surface is randomly perturbed.
13. If autopop or autochop are on, then the appropriate edge deletion or
    division is done.
14. New energies, volumes, and quantities are calculated.
15. If check_increase is on and the surface energy has increased, then the
    vertices are restored to their old values.
16. If estimating is on, then a linear estimate of the energy change is
    printed. This is calculated from the velocities, gradients, and scale
    factor.
17. The number of iterations left, the new area, energy, and scale factor
    are printed.
18. If a graphics display is active and set to autodisplay, then graphics
    are redrawn.


<--------------------------- iteration_counter ---------------------------->

Internal read-only variable. Loop count of the current loop in an iterated
command.  Example:

Enter command: { {print iteration_counter } 3 } 4
                   3
                   2
                   1
                   3
                   2
                   1
                   3
                   2
                   1
                   3
                   2
                   1

<----------------------------------- j ------------------------------------>

Single letter main command. Jiggles all vertices once. Meant to be used
for simulated annealing. Useful for shaking up surfaces that get in a rut,
especially crystalline integrands. Syntax:
   j  value
You will be prompted for a value, which is used as a scaling factor, if
you don't give a value with the command. Default value is the value of
the "jiggle_temperature" internal variable, which starts as 0.05. The
actual jiggle is a random displacement of each vertex independently with
a Gaussian distribution with deviation being the temperature times the
mean edge length.  See the "longj" command for a user-definable perturbation.


<----------------------------------- J ------------------------------------>

Single letter main command. Toggles jiggling on every iteration of the g
command. If jiggling gets turned on, prompts for temperature value. Default
temperature is the value of the jiggle_temperature internal variable.


<--------------------------------- jiggle --------------------------------->

Evolver toggle command. Toggles jiggling on every iteration.


<--------------------------- jiggle_temperature --------------------------->

Internal read-write variable. Current temperature for jiggling.

<-------------------------------- johndust -------------------------------->

Named method. Description: For all point pairs (meant to be on a sphere),

       energy = (pi - asin(d/2))/d,

where d is chord distance. For point packing problems on the sphere.

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: any.
Hessian: no. 
Example datafile declaration:

  constraint 1 formula: x^2+y^2+z^2 = 1
  quantity jms energy method johndust global


<----------------------------------- k ------------------------------------>

Single letter main command. Sets "gap constant" for gap energy for convex
constraints. Adds energy roughly proportional to area between edge and
boundary. You will be prompted for a value if you don't give a value on the
command line. Normal values are on the order of magnitude of unity. Value k
= 1 is closest to true area. Use 0 to eliminate the energy.

Graphics window key command.  Activates clipping plane in rotation mode.
"L" deactivates clipping mode; "l" (lowercase L) activates clipping plane
in translation mode.

<----------------------------------- K ------------------------------------>

Single letter main command. Finds skinny triangles whose smallest angle is
less than a specified cutoff. You will be prompted for a value if you don't
give a value on the command line. Such triangles will have their longest
edge subdivided. Should be followed with tiny edge removal 't' and
equiangulation 'u'.  By default, the long edge is subdivided at its 
midpoint, but if you do "k_altitude_mode on" then it will be subdivided 
at the foot of the altitude from the opposite vertex.


<------------------------------ k_altitude_mode ------------------------------>

Evolver toggle command.  When on, the 'K' command uses the altitude from a
vertex rather than the median to subdivide a skinny triangle. Default is OFF.

<------------------------------ k_form_order ------------------------------>

Some named methods, such as form_integrand, can handle a differential
form of arbitrary order, and the k_form_order attribute in the method
declaration specifies the order of the form.

<----------------------------- k_vector_order ----------------------------->

A parameter in simplex_k_vector_integral and edge_k_vector_integral 
methods that specifies the order of the k-vector involved.

<------------------------------ keep_macros ------------------------------->

The keyword keep_macros in the top of the datafile will keep macro
definitions active during runtime, until the next datafile is loaded.


<----------------------------- keep_originals ----------------------------->

The presence of the keyword

    keep_originals

in the top of the datafile has the same effect as the -i command line
option, which is to keep the id numbers of geometric elements internally
the same as in the datafile, instead of renumbering them in the order
they are read in.  However, the "addload" command does not obey this,
since it adds the new surface to an existing surface.


<-------------------------- Kelvin foam example --------------------------->
<------------------------------ twointor.fe ------------------------------->

Example: Torus partitioned into two cells (Kelvin's foam), twointor.fe

This example has a flat 3-torus (i.e. periodic boundary conditions)
divided into two bodies. The unit cell is a unit cube, and the surface has
the topology of Kelvin's partitioning of space into tetrakaidecahedra [TW],
which was the least area partitioning of space into equal volumes known
until recently [WP].

The datafile handles the wrapping of edges around the torus by specifying
for each direction whether an edge wraps positively (+), negatively (-), or
not at all (*).

Note the use of the keyword TORUS_FILLED in the datafile. This informs
Evolver that one of the volume constraints is redundant, preventing a
singular matrix when the time comes to enforce volume constraints. One
could use just TORUS and only put on one volume constraint.

The display of a surface in a torus can be done several ways. The
connected command (my favorite) makes each body show as a single unit. The
clipped command shows the surface clipped to the fundamental parallelpiped.
The raw_cells command shows the unedited surface.

The Weaire-Phelan structure [WP]. is in the datafile phelanc.fe. It has
area 0.3% less than Kelvin's.

The initial two-cell Kelvin shape. Note that due to periodidity, a single
vertex or edge may appear multiple times in the image.



// twointor.fe
// Two Kelvin tetrakaidecahedra in a torus.

TORUS_FILLED   // signals that domain is a torus and bodies fill it.

periods
1.000000 0.000000 0.000000
0.000000 1.000000 0.000000
0.000000 0.000000 1.000000

vertices // values from another program
1  0.499733 0.015302 0.792314
2  0.270081 0.015548 0.500199
3  0.026251 0.264043 0.500458
4  0.755123 0.015258 0.499302
5  0.026509 0.499036 0.794636
6  0.500631 0.015486 0.293622
7  0.025918 0.750639 0.499952
8  0.499627 0.251759 0.087858
9  0.256701 0.499113 0.087842
10 0.026281 0.500286 0.292918
11 0.500693 0.765009 0.086526
12 0.770240 0.499837 0.087382

edges // with wraps in axis directions, * no wrap, + pos wrap, - neg wrap
1    1 2  * * *
2    2 3  * * *
3    1 4  * * *
4    3 5  * * *
5    2 6  * * *
6    2 7  * - *
7    1 8  * * +
8    4 6  * * *
9    5 9  * * +
10   3 10 * * *
11   3 4  - * *
12   6 8  * * *
13   6 11 * - *
14   7 4  - + *
15   8 12 * * *
16   9 8  * * *
17   9 11 * * *
18   10 7 * * *
19   11 1 * + -
20   12 5 + * -
21   5 7  * * *
22  11 12 * * *
23  10 12 - * *
24   9 10 * * *

faces
1    1 2 4 9 16 -7
2    -2 5 12 -16 24 -10
3    -4 10 18 -21
4    7 15 20 -4 11 -3
5    -1 3 8 -5
6    6 14 -11 -2
7    5 13 -17 24 18 -6
8    -12 13 19 7
9    -16 17 22 -15
10   -10 11 8 12 15 -23
11   -21 9 17 19 1 6
12   -14 -18 23 -22 -13 -8
13   -24 -9 -20 -23
14   -19 22 20 21 14 -3

bodies
1    -1 -2 -3 -4 -5 9 7 11 -9 10 12 5 14 3 volume 0.500
2     2 -6 -7 8 -10 -12 -11 -13 1 13 -14 6 4 -8 volume 0.500


Doing some refining and iterating will show that the optimal shape is
curved a bit.

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


<------------------------ Klein hyperbolic metric ------------------------->

One special metric is available built-in. It is the Klein model of
hyperbolic space in n dimensions. The domain is the unit disk or sphere in
Euclidean coordinates. Including the keyword KLEIN_METRIC in the top
section of the datafile will invoke this metric. Lengths and areas are
calculated exactly, but as with other metrics you are on your own for
volumes and quantities.


<------------------------------- klein_area ------------------------------->

Named method. Description: Facet area in Klein hyperbolic 3D space model.
Does not depend on klein_metric being declared in the datafile. Vertices
should be inside the unit sphere. 

Element: facet. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration:

   quantity kleinarea energy method klein_area global


<------------------------------ klein_length ------------------------------>

Named method. Description: Edge length in Klein hyperbolic plane model.
Does not depend on klein_metric being declared. Vertices should be inside
unit sphere. 

Element: edge. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: 2. 
Hessian: no. 
Example datafile declaration:

   quantity kleinlen energy method klein_length global


<------------------------------ klein_metric ------------------------------>

A Riemannian metric on the ambient space may be declared in the top
section of the datafile with the syntax

METRIC
expr expr expr
expr expr expr
expr expr expr

 or

CONFORMAL_METRIC expr

 or

KLEIN_METRIC

The keyword METRIC is followed by the N^2 components of the metric tensor,
where N is the dimension of space. The components do not have to obey any
particular line layout; they may be all on one line, or each on its own
line, or any combination. It is up to the user to maintain symmetry. A
conformal metric is a scalar multiple of the identity matrix, and only the
multiple need be given. A conformal metric will run about twice as fast.
The Klein metric is a built-in metric for hyperbolic n-space modelled on
the unit disk or ball.


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


<------------------------------ knot_energy ------------------------------->

Named method.   Description: An electrostatic-type energy in which vertices
are endowed with equal charges.  Inverse power law of potential is adjustable
via the global parameter `knot_power', default value 2 (which is not 
electrostatic, but the knot theorists like it).  If the extra attribute 
`node_charge' is defined for vertices, then that value is used for
the vertex charge.  Use of this energy is not restricted to knots;
it has been used to embed complicated network graphs in space.

Element: vertex.
Parameters: none.
Models: string; linear.
Ambient dimension: any.
Hessian: yes.
Example datafile declaration:

  parameter knot_power  2     // the default
  quantity knotten energy method knot_energy global

<-------------------------- knot_local_thickness -------------------------->

Named method. Description: Calculates the radius of curvature at a vertex
of the circle containing the vertex and its two neighbor vertices. Meant to
investigate the radius at individual vertices. 

Element: vertex. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: 3. 
Gradient: no. 
Hessian: no.
Example datafile declaration: 
 
  quantity klocalthick info_only method knot_local_thickness global

<------------------------------- knot_power ------------------------------->

Internal read-write variable used as exponent on some term in
various knot energies.  Named methods using knot_power are:

 buck_knot_energy
 charge_gradient
 knot_energy
 knot_thickness_0
 knot_thickness_p
 knot_thickness_p2
 proj_knot_energy
 uniform_knot_energy
 uniform_knot_energy_normalizer
 uniform_knot_normalizer1
 uniform_knot_normalizer2

<----------------------------- knot_thickness ----------------------------->

Named method. Description: Calculates global radius of curvature at one
vertex v, as the minimum radius of circle containing the vertex and the
endpoints of any non-adjacent edge. Because of "min", this has no gradient,
so should be used in info_only quantities. 

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Gradient: no. 
Hessian: no.
Example datafile declaration: 
 
  quantity kthick info_only method knot_thickness global 

<---------------------------- knot_thickness2 ----------------------------->

Named method. Description: calculates global radius of curvature at one
vertex v, as the minimum radius of circle containing the vertex and the
neighbor vertices of any non-adjacent vertex. Because of "min", this has no
gradient, so should be used in info_only quantities. 

Element: vertex.
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Gradient: no.
Hessian: no. 
Example datafile declaration: 
 
  quantity kthick info_only method knot_thickness2 global 

 
<---------------------------- knot_thickness_0 ---------------------------->

Named method. Description: Calculates global radius of curvature at one
vertex, as Lp integral of radius of curvature of circle containing the
vertex and the endpoints of edges not adjacent to the vertex. Integrand
raised to -p power. The power p is taken from the global variable
knot_power. No factor of length in integral. This method has a gradient.

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3.
Hessian: no. 
Example datafile declaration: 
 
  quantity kthick info_only method knot_thickness_0 global 
 
<---------------------------- knot_thickness_p ---------------------------->

Named method. Description: purpose: calculates global radius of curvature
at one vertex v, as Lp integral of radius of curvature of v and endpoints
of nonadjacent edges. Includes factors of length at v and w. This method
has a gradient. The power p is taken from the global variable knot_power.

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3.
Hessian: no. 
Example datafile declaration: 
 
   quantity kthick info_only method knot_thickness_p global 

 
<--------------------------- knot_thickness_p2 ---------------------------->

Named method. Description: Calculates the global radius of curvature at
one vertex v, as Lp integral of r(v,w1,w2) over all vertices w. Here w1 and
w2 are the two neighbors of vertex w. Includes factors of length at v and
w. This has not been extended to allow open arcs (valence 1 vertices). This
method does have a gradient. The power p is taken from the global variable
knot_power. 

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration: 
 
   quantity kthick info_only method knot_thickness_p2 global 

 
<----------------------------- kraynikpopedge ----------------------------->

Main command toggle. Toggles edge-popping mode (in "O" or "pop" commands)
in which poppable edges look for adjacent facets of different
edge_pop_attribute values to split off from the original edge; failing
that it reverts to the regular mode of popping the edge. This is meant
to give the user greater control on how edge popping is done. It is up
to the user to declare the edge_pop_attribute integer facet attribute
and assign values.


<---------------------------- kraynikpopvertex ---------------------------->

Toggles 3D vertex popping mode in which a poppable vertex is examined to
see if it is a special configuration of six edges and 9 facets. If it is, a
special pop is done that is much nicer than the default pop.


<--------------------------------- kusner --------------------------------->

Evolver toggle command. Calculation of squared curvature by edge formula
rather than vertex formula.


<----------------------------------- l ------------------------------------>

 l (lower case L)

Single letter main command. Subdivides long edges, creating new facets as
necessary. You will be prompted for a cutoff edge length, if you don't give
a value with the command. Existing edges longer than the cutoff will be
divided once only. Newly created edges will not be divided. Hence there may
be some long edges left afterward. If you enter h, you will get a histogram
of edge lengths. If you hit RETURN with no value, nothing will be done. It
is much better to use the refine command r than to subdivide all edges. A
synonym for "l value" is "edge_divide value". This command does not respect
the no_refine attribute.

Graphics mode command. Rotate left. Rotates about vertical axis,
default 6 degrees.  Integer prefix specifies how many 6 degree rotations
to do; decimal prefix specifies degrees of rotation.
Example: `15l' does 90 degree rotation, `15.0l' does 15 degree rotation.

<------------------------------- labelflag -------------------------------->

Evolver toggle command. When on, the postscript command will print element
labels in the postscript file. Synonym for ps_labelflag.


<--------------------------------- labels --------------------------------->

Postscipt output option for numerically labelling elements with their id's.
One of the prompts of the "P 3" command is
  Do labels? (i for ids, o for originals) : 
which gives you a chance to put numeric labels on vertices, edges, and
facets, which is useful for debugging or modifying a datafile. Edge labels
are slightly displaced toward the head of the edge, and facet labels are
signed according to which side of the facet is visible. Choose 'i' or 'y'
for the current element id, or 'o' for the original element number. If you
don't want any labels, just hit RETURN. The postscript command uses the
ps_labelflag toggle to control this. The relative size of the labels can be
controlled with the ps_labelsize variable, whose default value is 3.0.

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


<----------------------------- Lagrange model ----------------------------->

The Evolver has a very limited implementation of higher-order elements. In
the Lagrange model of order n, each edge is defined by interpolation on n+1
vertices evenly spaced in the parameter domain, and each facet is defined
by interpolation on (n+1)(n+2)/2 vertices evenly spaced in a triangular
pattern in the parameter domain. That is, the elements are Lagrange
elements in the terminology of finite element analysis.

The Lagrange model is defined only for named quantities and methods, so
Evolver will automatically do convert_to_quantities when you invoke the
Lagrange model. The methods that currently accept the Lagrange model are
   vertex_scalar_integral
   edge_length
   edge_area
   edge_scalar_integral
   edge_vector_integral
   edge_general_integral
   facet_area
   facet_volume
   facet_vector_integral
   facet_scalar_integral
   facet_general_integral

A surface may be converted to an order n Lagrange model with the command
"lagrange n". This will convert linear or quadratic models to Lagrange, and
will convert between different order Lagrange models. The commands linear
and quadratic will convert Lagrange model back to the linear or quadratic
models.

No triangulation manipulations are available in the Lagrange model. No
refining, equiangulation, or anything. There is some vertex averaging, but
just internal to edges and facets. Use the linear or quadratic model to
establish your final triangulation, and just use the Lagrange model to get
extra precision.

The current order can be accessed through the read-only internal variable
lagrange_order. The Lagrange model can be dumped and reloaded.

As the Lagrange order is raised, calculations slow down rapidly. This is
not only due to the large number of points involved, but is also due to the
fact that the order of Gaussian integration is also raised.

Lagrange elements are normally plotted subdivided on their vertices, but
if the smooth_graph flag is on, they are plotted with 8-fold subdivision.

The toggle command bezier_basis toggle replaces the Lagrange interpolation
polynomials (which pass through the control points) with Bezier basis
polynomials (which do not pass through interior control points, but have
positive values, which guarantees the edge or facet is within the convex
hull of the control points). This is experimental at the moment, and not
all features such as graphing or refinement have been suitably adjusted.

<-------------------------- lagrange_multiplier --------------------------->

The syntax for defining a named quantity in the data file is:

 QUANTITY name  ENERGY|FIXED=value|CONSERVED|INFO_ONLY
    [LAGRANGE_MULTIPLIER constexpr] [TOLERANCE constexpr]
    [MODULUS constexpr] methodlist | FUNCTION methodexpr

For fixed quantities, the optional Lagrange multiplier value supplies the
initial value of the Lagrange multiplier (the "pressure" attribute of the
quantity). It is meant for dump files, so on reloading no iteration need be
done to have a valid Lagrange multiplier.

The "pressure" column of the "v" command output is the Lagrange multiplier
for constrained quantities.

<----------------------------- lagrange_order ----------------------------->

Internal read-only variable. Order of Lagrange model. Set
with the "lagrange n" command.

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

<------------------------ laplacian_mean_curvature ------------------------>

Named method. Description: Calculates the velocity of a vertex as the
Laplacian of the mean curvature of the surface, meant to model the
surface diffusion of atoms in sintering. The mean curvature at each vertex is 
calculated as a scalar, in the same way as for area_normalized area gradient, 
i.e. area gradient dotted with volume gradient, divided by the area of the
surrounding facets.  Then finite differences are used to calculate the
Laplacian of the mean curvature.  This calculates velocity only;
the energy is always 0.  This method should only be used with fixed 
scale in the 'g' command.

The relative speed of vertices can be controlled by the vertex 
attribute lmc_mobility, which the user should declare if wanted.
If the user wants to access the values of mean curvature the method
finds, the user should define the vertex scalar attribute lmc_mean_curvature.
This method conserves volume ideally, but you might want to put on volume
constraints anyway due to numerical inaccuracies.

Warning: This method should only be used with a fixed 'g' scale factor.
And for stability, the factor should be proportional to the fourth power of 
the shortest edge, since Laplacian of mean curvature is a fourth-derivative
operator, something like 0.001*length^4.  This can make for very slow
evolution for highly refined surfaces.

Element: vertex. 
Parameters: none. 
Models: string, soapfilm; linear. 
Ambient dimension: any.
Hessian: no. 
Example datafile declaration:

  area_method_name "null_area"
  define facet attribute lmc_mobility real
  define facet attribute lmc_mean_curvature real
  quantity lmc energy method laplacian_mean_curvature global


<------------------------------ lmc_mobility ------------------------------>

A vertex attribute used by the laplacian_mean_curvature named
method to control the relative velocity of a vertex.  See
laplacian_mean_curvature for more.

<--------------------------- lmc_mean_curvature --------------------------->

A vertex attribute used by the laplacian_mean_curvature named
method to record the mean curvature found at a vertex.  See
laplacian_mean_curvature for more.

<---------------------------- last_eigenvalue ----------------------------->

Internal read-only variable. Eigenvalue from last saddle or ritz
command.  For the full list of ritz eigenvalues, use the eigenvalues[]
array.

<------------------------------- last_error ------------------------------->

Internal read-write variable. Has error number of last error message.

<--------------------------- last_hessian_scale --------------------------->

Internal read-only variable. Stepsize from last hessian_seek command.

<------------------------------- LEBweight -------------------------------->

Facet extra attribute used to weight individual facets in the named 
methods linear_elastic_B, relaxed_elastic, and relaxed_elastic_A.

<--------------------------------- length --------------------------------->

Edge read-only attribute. Length of the edge. Examples:
   histogram(edge where on_constraint 1, length)
   print edge[3].length


<--------------------------- length_method_name --------------------------->

This item in the top of the datafile, length_method_name, specifies
the name of the pre-defined method to use as the method to compute
edge length in place of the default edge_length method. It is optional.
Developed so circular arcs can be used in two-dimensional foams. Current
reasonable methods are circular_arc_length and spherical_arc_length.
Usage implies converting to everything_quantities mode. Syntax:

  length_method_name quoted_method_name

For example,

  string
  space_dimension 2
  length_method_name "circular_arc_length"
  area_method_name "circular_arc_area"

<------------------------- level set constraints -------------------------->

A level-set constraint is a restriction of vertices to lie on the zero
level-set of a function. The formula may include any expressions whose
values are known to the Evolver, given the particular vertex. Most commonly
one just uses the coordinates (x,y,z) of the vertex, but one can use
variables, quantity values, or vertex extra attributes. Using a vertex
extra attribute is a good way to customize one formula to individual
vertices. For example, if there were a vertex extra attribute called zfix,
one could force vertices to individual z values with one constraint with
the formula z = zfix, after of course assigning proper values to zfix for
each vertex.

A level set constraint may have several roles:

 > Vertices may be required to lie on a constraint (equality constraint) or
   on one side (inequality constraint). A constraint may be declared GLOBAL,
   in which case it applies to all vertices. See mound.fe for an example.

 > A constraint may have an energy vectorfield associated with it that is
   integrated over edges lying in the constraint to give an energy. This is
   useful for specifying wall contact angles and for calculating gravitational
   energy. Integrals are not evaluated over edges that are FIXED. See mound.fe
   for an example. In the string model, the energy integrand is a single
   component evaluated on vertices on the constraint.

 > A constraint may have a content vectorfield associated with it that is
   integrated over edges lying in the constraint to give a volume contribution
   to a body whose boundary facets contain the edges. This is useful for
   getting correct volumes for bodies without completely surrounding them with
   otherwise useless facets. It is important to understand how the content is
   added to the body in order to get the signs right. The integral is
   evaluated along the positive direction of the edge. If the edge is
   positively oriented on a facet, and the facet is positively oriented on a
   body, then the integral is added to the body. This may wind up giving the
   opposite sign to the integrand from what you think may be natural.
   Integrals are not evaluated over edges that are FIXED. See tankex.fe for an
   example. In the string model, the content integrand is a single component
   evaluated on vertices on the constraint.

 > A constraint may be declared CONVEX, in which case edges in the
   constraint have an energy associated with them that is proportional to the
   area between the straight edge and the curved wall. This energy (referred
   to as "gap energy") is meant to compensate for the tendency for flat facets
   meeting a curved wall to minimize their area by lengthening some edges on
   the wall and shortening others, with the net effect of increasing the net
   gap between the edges and the wall. See tankex.fe for an example.

Level set constraints are declared in the top section of the datafile. They
may be applied to vertices, edges, or facets. Constraints are usually
applied to vertices and edges, as in mound.fe. Remember that you need to
apply a constraint to an edge to get that constraint to apply to vertices
created on that edge by refining. Sometimes one applies constraints to
facets, usually to get the facet to conform to a predetermined shape. Be
sure that the constraints applied to a vertex are linearly independent at
the vertex.

Constraints are usually applied in the datafile vertices, edges, and faces
sections, but they may also be set or removed with the set or unset
commands. Examples:
   set vertex[4] constraint 4
   unset edge constraint 1 where id < 10

It does not hurt to unset an element that isn't on the constraint. When a
vertex is set to a constraint, the vertex coordinates are immediately
projected to the constraint. Setting an edge on a constraint does not set
its vertices. Likewise for facets.


<----------------------------- lexical format ----------------------------->

For those who know about such things, the datafile and commands are read
with a lexical analyzer generated by the lex program. The specification is
in datafile.lex. Commands are further parsed by a yacc-generated parser.
In parsing an expression, the longest legal expression is used. This
permits coordinates to be specified by several consecutive expressions with
no special separators.


<----------------------------- line splicing ------------------------------>

The datafile and any file Evolver inputs with the "read" command are made up 
of text lines. Line breaks are significant. The next physical line can be 
spliced onto the current line by having \ be the last character of the current 
line. Line splicing is not effective in // comments. Blank lines and comment 
lines may be placed freely anywhere. The various combinations of CR and NL 
that various computer systems use are all recognized.

The most common use of line-splicing is in datafile lines that get overly
long.  Long commands should be enclosed in {  }, which is much more
convenient and reliable.


<--------------------------------- linear --------------------------------->

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


<------------------------------ linear model ------------------------------>

In the linear model, all edges and triangular facets are flat line
segments and triangles, respectively. For all calculations, an edge is
defined by its two endpoints, and a facet (in the soapfilm model) is
defined by its three vertices. This is the default. Quadratic or Lagrange
models may be changed to linear with the M 1 or linear commands. An
exception is if the spherical_arc_length method is used for
length_method_name in the string model, in which case edges are computed
and drawn on a sphere centered at the origin.

<----------------------------- linear_elastic ----------------------------->

Named method. Description: To calculate the isotropic linear elastic
strain energy energy for facets based on the Cauchy-Green strain matrix.
Let S be Gram matrix of unstrained facet (dots of sides). Let Q be the
inverse of S. Let F be Gram matrix of strained facet. Let C = (FQ-I)/2, the
Cauchy-Green strain tensor. Let v be Poisson ratio. Then energy density is

 (1/2/(1+v))(Tr(C^2) + v*(Tr C)^2/(1-(dim-1)*v))

Each facet has extra attribute poisson_ratio and extra attribute array
form_factors[3] = {s11,s12,s22}, which are the entries in S. That is, s11 =
dot(v2-v1,v2-v1), s12 = dot(v2-v1,v3-v1), and s22 = dot(v3-v1,v3-v1). If
form_factor is not defined by the user, it will be created by Evolver, and
the initial facet shape will be assumed to be unstrained. For a version of
this method that gives compression zero energy, see relaxed_elastic_A.

Element: facet. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3.
Hessian: yes. 
Example datafile declaration:

  quantity lastic energy method linear_elastic global


<---------------------------- linear_elastic_B ---------------------------->

Named method. Description: A variation of the linear_elastic method. To
calculate the linear elastic strain energy energy for facets based on the
Cauchy-Green strain matrix. Let S be Gram matrix of unstrained facet (dots
of sides). Let Q be the inverse of S. Let F be Gram matrix of strained
facet. Let C = (FQ-I)/2, the Cauchy-Green strain tensor. Let v be Poisson
ratio. Then energy density is

 (1/2/(1+v))(Tr(C^2) + v*(Tr C)^2/(1-(dim-1)*v))

Each facet has extra attribute poisson_ratio and each vertex has two extra
coordinates, the coordinates of the unstrained surface in a plane. Hence
the surface must be set up as five dimensional.  There can also be a
real-valued facet extra attribute LEBweight, which can be used to give
a per-facet weighting of the energy.  For a version of this
method that gives compression zero energy, see relaxed_elastic.
 
Element: facet. 
Parameters: none. 
Models: linear. 
Ambient dimension: 5.
Hessian: yes. 
Example datafile declaration:

  space_dimension 5
  quantity lastic energy method linear_elastic_B global


<----------------------------- linear_metric ------------------------------>

Evolver toggle command. Eigenvalues and eigenvectors of the Hessian are
defined with respect to a metric. This command toggles a metric that
imitates the smooth surface natural metric of L_2 integration on the
surface. Use with hessian_normal to get eigenvalues and eigenvectors
similar to those on smooth surfaces.

<--------------------------- linear_metric_mix ---------------------------->

Internal read-write variable. Fraction of linear interpolation in
Hessian metric.

<---------------------------------- 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" or other commands 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 bottomingo", "list procedures",
and "list topingo".


<---------------------------- 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 names all current user-defined commands,
procedures, and functions.


<------------------------------ list topinfo ------------------------------>

Main prompt command. Prints the first section of the datafile on the
screen. This is everything that would be before the vertices section
in a dump file.

<----------------------------- little_endian ------------------------------>

Evolver toggle command. Controls the order of bytes in binary_printf
numerical output. Little-endian is least significant byte first. To change
to big-endian, use big_endian, not "little_endian off".


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


<------------------------------ load_library ------------------------------>

To load a dynamic load library of compiled functions, the syntax is

 LOAD_LIBRARY "filename"

where the double-quoted filename is the library. The current directory and
the EVOLVERPATH will be searched for the library.  See "dynamic load library"
for more.

<--------------------------------- local ---------------------------------->

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.

<--------------------------- local_hooke_energy --------------------------->

Named method. Description: Energy of edges as springs with equilibrium
length being average of lengths of neighbor edges. Actually, the energy is
calculated per vertex,

 E = ({L_1 - L_2 \over L_1 + L_2})^2

where L_1 and L_2 are the lengths of the edges adjacent to the vertex.
Meant for loops of string. (by John Sullivan) 

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity slinky energy method local_hooke_energy global

<---------------------------- local_hooke_flag ---------------------------->

Variable that when set to nonzero prevents local_hooke_energy from
being evaluated at vertices with valence not equal to 2.

<---------------------------------- log ----------------------------------->

 log(x), exp(x) : Natural log, exponentiation base e.

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

<--------------------------------- LONGDOUBLE -------------------------------->
<--------------------------------- FLOAT128 -------------------------------->

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

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


<----------------------------------- M ------------------------------------>

Single letter main command. Syntax:

  M n

where n is the order of the model.  Sets model type to linear, quadratic,
or Lagrange depending on n.

<----------------------------------- m ------------------------------------>

Single letter main command. Toggles quadratic search for optimal global
motion scale factor. If search is toggled OFF, you will be prompted for a
fixed scale factor. If you give a value with the command, then you are
setting a fixed scale factor.

Graphics mode command. Center image in viewing window.

<--------------------------------- macros --------------------------------->

Macros are text substitutions done by replacing an identifier by a string
of characters before parsing. Macros are only defined in the datafile, and
do not work from the command prompt. Simple macros (no parameters) may be
defined as in C:

         #DEFINE  identifier  string

"identifier" must be an identifier without other special meaning to the
parser. "string" is the rest of the logical line, not including comments. It
will be substituted for identifier whenever identifier occurs as a token
subsequently. Substitutions are re-scanned. No checks for recursiveness are
made. There is a maximum length (currently 500 characters) on a macro
definition. Note: macro identifiers are separate tokens, so if "-M"
translates into "-2", this will be read as two tokens, not a signed number.
The keyword keep_macros in the datafile will keep macro definitions active
during runtime, until the next datafile is loaded.

<--------------------------- matrix_determinant --------------------------->

Syntax: det := matrix_determinant(A)

Built-in matrix determinant of a square array. Has function syntax, 
so it returns the value of the determinant. Example:

  Enter command: define aaa real[2][2]
  Enter command: aaa[1][1] := 2; aaa[1][2] := 3; aaa[2][1] := 4; aaa[2][2] := 5
  Enter command: print matrix_determinant(aaa)
                  -2

Also works on square 2D array attributes of elements.  Does not modify 
the array.

<----------------------------- matrix_inverse ----------------------------->

Main prompt function. For computing the inverse of a square matrix.
Currently applies only to global matrices, not element attribute matrices.
Syntax:

  retval := MATRIX_INVERSE(matrix1, matrix2)

Here matrix1 is the name of the original matrix, and matrix2 is the name
of the inverse matrix. They may be the same matrix to get an in-place
inverse.  The return value is 1 if the inversion is successful and
0 if matrix1 is singular.  Examples:
  define mata real[5][5]
  define matb real[5][5]
  ...  // fill in values of mata
  retval := matrix_inverse(mata,matb)
  retval := matrix_inverse(mata,mata)


<---------------------------- matrix_multiply ----------------------------->

Main prompt command. For computing the product of matrices. Currently
applies only to global matrices, not element attribute matrices. Syntax:

  MATRIX_MULTIPLY(matrix1, matrix2, matrix3)

Here matrix1 and matrix2 are the names of the multiplicands, and matrix3
is the name of the product matrix. The product matrix may be the same as
one (or both) of the multiplicands. The matrices can be one-dimensional or
two-dimensional, so you can do vector-matrix or matrix-vector
multiplication (but you can't do vector times vector). Examples:
  define mata real[5][5]
  define matb real[5][5]
  define matc real[5][5]
  ...  // fill in values of mata and matb
  matrix_multiply(mata,matb,matc)
  matrix_multiply(mata,mata,mata)

Obsolete now, since the * operator does matrix multiplication as well as
scalar multiplication.

<-------------------------------- MAXCOORD -------------------------------->

Internal constant governing the maximum dimension of ambient space.
By default, surfaces live in 3 dimensional space. However, the phrase
"SPACE_DIMENSION n" in the datafile header sets the dimension to n. This
means that all coordinates and vectors have n components. The only
restriction is that Evolver has to be compiled with the MAXCOORD macro
defined to be at least n in Makefile or in model.h. The default MAXCOORD is
4. Change MAXCOORD and recompile if you want more than four dimensions. The
actual space dimension can be accessed in commands through the read-only
variable space_dimension.

Graphics will display only the first three dimensions of spaces with more
than three dimensions, except for geomview, which has a four-dimensional
viewer built in (although its use is awkward now).

<-------------------------------- maximum --------------------------------->

 minimum(a,b), maximum(a,b): Extreme of two arguments.

<----------------------------- mean_curvature ----------------------------->

Vertex read-only attribute, available in the string and soapfilm model. 
The mean curvature is calculated as the magnitude of the gradient of area 
(or length in the string model) divided by the area (or length) associated 
with the vertex, which is one-third the area of the facets adjacent to the 
vertex (or one-half of the length of adjacent edges).  It is divided by 2 
in the soapfilm model to account for the "mean" part of the definition.  
The sign of the mean curvature is relative to the orientation of the first 
adjacent facet (or edge) Evolver finds. This calculation can be done even 
if the vertex is on a triple junction or other non-planar topology, even 
if it doesn't interpret well as mean curvature there.

<------------------------ mean_curvature_integral ------------------------->

Named method. Description: Integral of signed scalar mean curvature of a
2D surface. The computation is exact, in the sense that for a polyhedral
surface the mean curvature is concentrated on edges and singular there, but
the total mean curvature for an edge is the edge length times its dihedral
angle. 

Element: edge. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

  quantity mci energy method mean_curvature_integral

The method mean_curvature_integral_a does the same thing, but uses a
numerical formulation which may be better behaved.

There is an obsolete use of mean_curvature_integral in the top of the
datafile to indicate the integral of the mean curvature should be 
included as an energy, with syntax
  mean_curvature_integral: modulus
where modulus is the multiplier for the energy.  The modulus winds up
as the internal read-write variable mean_curvature_modulus.

<------------------------- mean_curvature_modulus ------------------------->

There is an obsolete use of mean_curvature_integral in the top of the
datafile to indicate the integral of the mean curvature should be 
included as an energy, with syntax
  mean_curvature_integral: modulus
where modulus is the multiplier for the energy.  The modulus winds up
as the internal read-write variable mean_curvature_modulus.

<----------------------- mean_curvature_integral_a ------------------------>

Named method. Description: Integral of signed scalar mean curvature of a
2D surface. The computation is exact, in the sense that for a polyhedral
surface the mean curvature is concentrated on edges and singular there, but
the total mean curvature for an edge is the edge length times its dihedral
angle. 

Element: edge. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity mci energy method mean_curvature_integral_a

The method mean_curvature_integral_a does the same thing as 
mean_curvature_integral, but uses a numerical formulation which may be
better behaved.

<------------------------------ sq_mean_mix ------------------------------->

User-defined variable used by the mix_sq_mean_curvature method to
determine the combination of mean curvature approximations used.

<-------------------------------- memdebug -------------------------------->

Evolver toggle command. When ON, the 'c' command prints full memory usage
statistics on some systems. Also, each allocation or freeing of memory is
printed. Causes heap checking to be done on some systems at each memory
operation.


<-------------------------- memory debug option --------------------------->
<--------------------------------- option --------------------------------->

Command line option -m : Turn memory debugging on at start of program.
Same effect as runtime memdebug command.

<------------------------------ memory_arena ------------------------------>

Internal read-only variable. Total memory allocated to the
program's heap. Available only on SGI and Win32 versions.

<------------------------------ memory_used ------------------------------->

Internal read-only variable. Total memory used in the
program's heap. Available only on SGI and Win32 versions.

<------------------------------ merit_factor ------------------------------>

If the keyword MERIT_FACTOR is present in the top of the datafile,
then the i command will print the ratio total_area^3/total_volume^2,
which measures the efficiency of area enclosing volume. A holdover
from the early days of trying to beat Kelvin's partition of space.

<--------------------------------- method --------------------------------->

A "method" is a way of calculating a scalar value from some particular
type of element (vertex, edge, facet, body), and used as a component
of a named quantity. Each method is implemented internally as a set of
functions for calculating the value and its gradient as a function of
vertex positions. The most common methods also have Hessian functions.
Methods are referred to by their names.

See "implemented methods" for a list of available methods. Adding a new
method involves writing C routines to calculate the value and the gradient
(and maybe the Hessian) as functions of vertex coordinates, adding the
function declarations to quantity.h, and adding a structure to the method
declaration array in quantity.c. All the other syntax for invoking it from
the datafile is already in place.


<---------------------- method instance declaration ----------------------->
<---------------------------- method_instance ----------------------------->

Method instances are usually defined as part of the definition of a named
quantity, but there are circumstances where a quantity is composed of
several method instances and the method instances need to be referred to
individually; perhaps the user wants to know the values of the individual
instances. The general syntax for defining an instance of a named method in
a datafile is:

  METHOD_INSTANCE name METHOD methodname [MODULUS constexpr]
   [ELEMENT_MODULUS attrname]  [GLOBAL] [parameters]

Here, name is a user-assigned name for referring to this particular
instance. methodname is one of the pre-defined methods in Evolver. The
modulus value multiplies the method value to give the instance value. The
default modulus is 1. Individual elements may be given multipliers by
specifying an extra attribute attrname for the type of element; the
attribute must have been defined earlier. GLOBAL makes the method apply to
all elements of the appropriate type. Non-global instances may be applied
to elements individually by adding the instance name to the datafile line
defining an element. They may also be applied or unapplied at runtime with
the set and unset commands. Orientable methods can be applied with negative
orientation in the datafile by following the name with a dash. The
orientation in a set command follows the orientation the element is
generated with.

Each method may have various parameters to specialize it to an instance.
Currently the only parameters specified are:

 SCALAR_INTEGRAND: expr 

where expr is a scalar function of coordinates
(and of tangent or normal vector components in edge_general_integral or
facet_general_integral). Element attributes of the appropriate type element
may also be used.

 VECTOR_INTEGRAND:
 Q1: expr
 Q2: expr
 Q3: expr

where the expressions are functions of the coordinates. Element
attributes of the appropriate type element may also be used.

 FORM_INTEGRAND:
 Q1: expr
 Q2: expr
 Q3: expr
 ...
 
where the expressions are functions of the coordinates. Element
attributes of the appropriate type element may also be used. When used in
the facet_2form_integral method. The form components are listed in
lexicographic order, i.e. in 4D the six components 12,13,14,23,24,34 would
be listed as Q1 through Q6.

 PARAMETER_1 constexpr 

for specifying miscellaneous numeric parameters to certain methods.

 K_FORM_ORDER constexpr 

for methods that use differential k-forms, this specifies the value of k. 
Should occur before FORM_INTEGRAND when needed.


<---------------------------- method instances ---------------------------->

A "method instance" is the sum of a particular method applied to a
particular set of geometric elements. Some methods (like facet_area) are
completely self-contained. Others (like facet_vector_integral) require the
user to specify some further information. For these, each instance has a
specification of this further information. Method instances are defined in
the datafile, and may either be unnamed parts of named quantity definitions
or separate named method instances for inclusion in named quantities. The
separate named version is useful if you want to inspect instance values for
the whole surface or individual elements.

An instance total value can be referred to as "instancename.value" in 
commands. The instance name itself may be used as an element attribute. 
For example, supposing there is an instance named moment, which applies to 
facets. Then typical commands would be
  print moment.value
  print facet[3].moment
  list facet where moment > 0.1

Every method instance has a "modulus", which is multiplied times the basic
method value to give the instance value. A modulus of 0 causes the entire
instance calculation to be omitted whenever quantities are calculated. The
modulus may be set in the datafile or by assignment.
Example commands:
  print moment.modulus
  moment.modulus := 1.3

A method instance may be declared to use a different modulus for each
element by specifying an element extra attribute to use for that purpose.
The extra attribute has to have already been declared. Example:

  define facet attribute mymod real
  quantity myquant energy method facet_area global element_modulus mymod

Of course, it is up to the user to properly initialize the values of the
extra attribute.



<---------------------- method_instances_predicted -------------------------->

Datafile keyword in the top section of the datafile that specifies the
initial allocation of method instance structures.  Optional.  The purpose is 
to prevent repeated reallocation of memory as the instance list grows.
Not significant if there are only a few method instances,  but there are
times when there can be thousands of instances, such as when 
"everything_quantities" is used with a large foam. Automatically put in
dump files by the "d" or "dump" commands, based on the current number of 
method instances. This declaration obviously should come before any quantities
are defined.
Example:
    vertices_predicted 30748
    edges_predicted    92166
    facets_predicted   61446
    bodies_predicted    2048 
    facetedges_predicted  184320
    method_instances_predicted   4098
    quantities_predicted   2050

<--------------------------------- metis ---------------------------------->

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.


<------------------------------ metis_factor ------------------------------>

Evolver toggle command.
Computes and uses an ordering for Hessian factoring using the METIS
library of Karypis and Kumar, if this library has been compiled into
the Evolver.

<----------------------------- metis_readjust ----------------------------->

Main prompt command for MPI Evolver.  Does a repartition of the surface
among the tasks, but using a METIS partitioning algorithm in a way that 
is supposed to be based on the current partition rather than repartioning 
from scratch. Syntax:
   metis_readjust n
where n is the desired number of partitions; n must be between
1 and mpi_maxtask.

<--------------------------------- metric --------------------------------->

For length and area to make sense, the ambient space must be endowed
with a metric.  The Evolver offers several choices, but keep in mind
that they are only used to calculate default length and area.  Other
quantities that depend on the metric, such as volume, are up to the
user to put in by hand with named quantities.  All displaying is done
as if the metric is Euclidean.   Available metrics:

  Euclidean metric (default)
  Riemannian metric
  Conformal metric
  Klein hyperbolic metric

<--------------------------- metric declaration --------------------------->

A Riemannian metric on the ambient space may be declared in the
top section of the datafile with the syntax

  METRIC
  expr expr expr
  expr expr expr
  expr expr expr

or

  CONFORMAL_METRIC expr

or

  KLEIN_METRIC

The keyword METRIC is followed by the N^2 components of the metric tensor,
where N is the dimension of space. The components do not have to obey any
particular line layout; they may be all on one line, or each on its own
line, or any combination. It is up to the user to maintain symmetry. A
conformal metric is a scalar multiple of the identity matrix, and only the
multiple need be given. A conformal metric will run about twice as fast.
The Klein metric is a built-in metric for hyperbolic n-space modelled on
the unit disk or ball.


<--------------------------- metric_conversion ---------------------------->
<----------------------------- metric_convert ----------------------------->

Evolver toggle command. If a Riemannian metric is defined, whether to use
the metric to do gradient form to vector conversions. Synonym:
metric_conversion.

<--------------------------- metric_edge_length --------------------------->

Named method. Description: In the string model with a Riemannian metric,
this is the length of an edge. 

Element: edge. 
Parameters: none. 
Models: string, soapfilm, simplex; linear,Lagrange. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

  string
  space_dimension 2
  metric
  1+x^2 y
  y   1+y^2
  quantity mel energy method metric_edge_length global


<--------------------------- metric_facet_area ---------------------------->

Named method. Description: For a Riemannian metric, this is the area of a
facet. 

Element: edge. 
Parameters: none. 
Models: soapfilm, simplex; linear,Lagrange.
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

   metric
   1+x^2 0 z
   0 1+y^2 0
   z 0 1+z^2
   quantity mfa energy method metric_facet_area global


<-------------------------------- mid_edge -------------------------------->

Vertex read-only attribute. True (1) if the vertex is on an edge but not
an endpoint. Relevant in the quadratic model or Lagrange model. Example:

   list edge[23].vertex vv where vv.mid_edge


<------------------------------- mid_facet -------------------------------->

Vertex read-only attribute. True (1) if the vertex is an interior control
point of a facet in the Lagrange model. Example:

   list facet[23].vertex vv where vv.mid_facet


<---------------------------------- midv ---------------------------------->

Edge read-only attribute. In the quadratic model, gives the id of the
midpoint vertex of an edge. Example:
  print edge[23].midv

<--------------------------- mindeg_debug_level --------------------------->

Internal read-write variable controlling verbosity of messages during
Hessian sparse matrix factoring when my own minimal degree algorithm
is in effect (ysmp off). 0 for no messages, 7 for most.  Special 
value of -1 toggles graphical display of stages of factorization;
sets all edges between non-eliminated vertices to red, others to black.  
Pauses for user response.  For my own use, not users.

<----------------------------- mindeg_margin ------------------------------>

Internal read-write variable controlling how high to go above minimum 
degree in seeking good elimination when my own minimal degree Hessian
factoring algorithm is in effect (ysmp off).  Default 5. For my use,
not users.

<------------------------- mindeg_min_region_size ------------------------->

Internal read-write variable controlling smallest size region desired
when my own minimal degree Hessian factoring algorithm is in effect 
(ysmp off); smaller regions will be merged with parent node. Default 0.
For my use, not users. 


<-------------------------------- minimum --------------------------------->

minimum(a,b),maximum(a,b): Extreme of two arguments.


<------------------------- mix_sq_mean_curvature -------------------------->

Named method. Description: Integral of squared mean curvature of a
surface, with a slightly different definition from sq_mean_curvature or
eff_area_sq_mean_curvature or normal_sq_mean_curvature.
It uses a linear combination of two formulas for the mean curvature:

  h = ((F dot F)/(N dotF)*sq_mean_mix + (F dot F)/(N dot F)*(1-sq_mean_mix))/2

  E = h^2*A/3

Here F is the force vector, i.e. the area gradient vector, and N is the 
unit normal, defined by the volume gradient.  sq_mean_mix is a user variable
that controls the combination; its default value is zero. WARNING: For some
extreme shapes, Evolver may have problems detecting consistent local surface
orientation. The assume_oriented toggle lets Evolver assume that the facets
have been defined with consistent local orientation.

If the parameter or vertex attribute h_zero is defined, then the value per
vertex is

  E = (h-h_0)^2*A/3 

If the vertex is on one or several constraints, the F and N are projected
to the constraints, essentially making the constraints act as mirror
symmetry planes.

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: no. 
Example datafile declaration:

  parameter sq_mean_mix = 0.5
  quantity mixsq energy method mix_sq_mean_curvature global


<-------------------------------- mobility -------------------------------->

There is a choice to be made in the conversion of the forces on vertices
into velocities of vertices. Technically, force is the gradient of energy,
hence a covector on the manifold of all possible configurations. In the
Evolver representations of surfaces, that global covector can be
represented as a covector at each vertex. The velocity is a global vector,
which is represented as a vector at each vertex. Conversion from the global
covector to the global vector requires multiplication by a metric tensor,
i.e. singling out a particular inner product on global vectors and
covectors. The tensor converting from force to velocity is the mobility
tensor, represented as the mobility matrix M in some coordinate system. Its
inverse, converting from velocity to force, is the resistance tensor S =
M^{-1}. The same inner product has to be used in projecting the velocity
tangent to the constraints, whether they be level set constraints on
vertices or constraints on body volumes or quantity integrals. There are
several choices implemented in the Evolver, corresponding to several
different physical pictures of how the medium resists the motion of the
surface through it:
 unit mobility
 area normalization
 area normalization with effective area
 approximate polyhedral curvature
 user-defined mobility

<-------------------------- mobility declaration -------------------------->
<---------------------------- mobility_tensor ----------------------------->

A mobility matrix may be defined in the top section of the datafile by the
syntax

MOBILITY_TENSOR
expr expr expr
expr expr expr
expr expr expr

 or

MOBILITY expr

The first form gives the full mobility matrix, and the second form gives
the matrix as a scalar multiple of the identity matrix. The formulas are
evaluated at each vertex at each iteration, and so formulas may depend on
vertex position and any vertex attributes.  The velocity of a vertex
is calculated as velocity = mobility x force.


<---------------------------------- mod ----------------------------------->

%, mod: Real arithmetic modulus, x % y = x - floor(x/y)*y.


<--------------------------------- models --------------------------------->

The Surface Evolver can handle several different models of surfaces.
See "linear model", "quadratic model", or "lagrange model" for different
orders of polynomial representation, and 
"string model", "soapfilm model", or "simplex model" for different 
combinatorial types.

<-------------------------------- modulus --------------------------------->

A keyword that is an attribute of a named quantity or a method instance,
which is a multiplier for the calculated value.  Default value is 1. 
It can be set initially in a quantity (or method_instance) declaration 

    quantity bopeep energy modulus 23 method hooke_energy

or by run-time assignment:

    bopeep.modulus := 12


<----------------------------- mound example ------------------------------>

Example: Mound with gravity.

This example is a mound of liquid sitting on a tabletop with gravity
acting on it. The contact angle between the drop surface and the tabletop
is adjustable, to simulate the different degrees to which the liquid wets
the table. This example illustrates macros, variables, constraints with
energy, and omitting faces from body surfaces.

The drop starts as a cube with one face (face 6 of the cube example) on
the tabletop (the z = 0 plane). The most straightforward way to specify a
contact angle is to declare face 6 to be constrained to stay on the
tabletop and give it a surface tension different than the default of 1. But
this leads to problems described below. The way the contact angle is
handled instead is to omit face 6 and give the edges around face 6 an
energy integrand that results in the same energy we would get if we did
include face 6. If we let the interface energy density for face 6 be T,
then we want a vectorfield w such that

        /             /
        |  T k . dS = | w . dl
        / face 6      / bdry of face 6

So by Green's Theorem, all we need is curl w = Tk, and I will use w = -Tyi. 
Here i j k are the standard unit basis vectors. In practice, I don't think 
about Green's Theorem as such; I just write down a line integral that
sums up strips of surface.

I have chosen to parameterize the contact angle as the angle in degrees
between the table and the surface on the interior of the drop. This angle
can be adjusted by assigning a new value to the variable "angle" at
runtime. I could have made WALLT the parameter directly, but then I
wouldn't have had an excuse to show a macro.

Here is the datafile mound.fe:

// mound.fe
// Evolver data for drop of prescribed volume sitting on plane with gravity.
// Contact angle with plane can be varied.

PARAMETER angle = 90    // interior angle between plane and surface, degrees

gravity_constant 0  // start with gravity off

#define WALLT  (-cos(angle*pi/180))  // virtual tension of facet on plane

constraint 1   /* the table top */
formula: x3 = 0
energy:  // for contact angle
e1: -(WALLT*y)
e2: 0
e3: 0

vertices
1   0.0  0.0 0.0  constraint 1  /* 4 vertices on plane */
2   1.0  0.0 0.0  constraint 1
3   1.0  1.0 0.0  constraint 1
4   0.0  1.0 0.0  constraint 1
5   0.0  0.0 1.0
6   1.0  0.0 1.0
7   1.0  1.0 1.0
8   0.0  1.0 1.0
9   2.0  2.0 0.0  fixed   /* for table top */
10  2.0 -1.0 0.0  fixed
11 -1.0 -1.0 0.0  fixed
12 -1.0  2.0 0.0  fixed

edges  /* given by endpoints and attribute */
1   1 2    constraint 1 /* 4 edges on plane */
2   2 3    constraint 1
3   3 4    constraint 1
4   4 1    constraint 1
5   5 6
6   6 7
7   7 8
8   8 5
9   1 5
10  2 6
11  3 7
12  4 8
13  9 10   fixed  /* for table top */
14 10 11   fixed
15 11 12   fixed
16 12  9   fixed

faces  /* given by oriented edge loop */
1   1 10 -5  -9
2   2 11 -6 -10
3   3 12 -7 -11
4   4  9 -8 -12
5   5  6  7   8
7  13 14 15  16  density 0 fixed /* table top for display */

bodies  /* one body, defined by its oriented faces */
1   1 2 3 4 5   volume 1  density 1

read
re := refine edges where on_constraint 1

// end of datafile


The mound itself was basically copied from cube.fe, but with face 6
deleted. The reason for this is that face 6 is not needed, and would
actually get in the way. It is not needed for the volume calculation since
it would always be at z = 0 and thus not contribute to the surface integral
for volume. The bottom edges of the side faces are constrained to lie in
the plane z = 0, so face 6 is not needed to keep them from catastrophically
shrivelling up. We could have handled the contact angle by including face 6
with a surface tension equal to the interface energy density between the
liquid and surface, but that can cause problems if the edges around face 6
try to migrate inward. After refinement a couple of times, interior
vertices of the original face 6 have no forces acting on them, so they
don't move. Hence it would be tough for face 6 to shrink when its outer
vertices ran up against its inner vertices. The tabletop face, face 7, is
entirely extraneous to the calculations. Its only purpose is to make a nice
display. You could remove it and all its vertices and edges without
affecting the shape of the mound. It's constraint 1 that is the tabletop as
far as the mound is concerned. To see what happens with the bottom face
present, load moundB.fe and do "run".

Now run Evolver on mound.fe. The command "re" defined at the end of the
datafile is good to use first in order to refine some edges that need it.
Refine and iterate a while. You should get a nice mound. It's not a
hemisphere, since gravity is on by default with G = 1. If you use the G
command to set "G 0" and iterate a while, you get a hemisphere. Try
changing the contact angle, to 45 degrees (with the command "angle := 45"}
or 135 degrees for example. You can also play with gravity. Set "G 10" to
get a flattened drop, or "G -5" to get a drop hanging from the ceiling. "G
-10" will cause the drop to try to break loose, but it can't, since its
vertices are still constrained.

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


<---------------------------------- MPI ----------------------------------->

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

<------------------------------ MPI commands ------------------------------>
 
All user commands are entered into the master task and executed by the
master task. Some commands (listed below) have been modified to execute in
parallel across all tasks in a coordinated way. The rest will just execute
on the master task. 

Variables exist independently on each task; they are not automatically
synchonized. 

Special MPI version commands: 
task_exec n,string : Have task n execute the string as a command. Any
aggregate commands execute across all local and imported elements. 

<---------------------------- MPI compilation ----------------------------->

All regular Evolver files, but not metis.c, along with the mpi*.c files
(except mpi_sparse.c, for now) should be compiled with these manifest
constants defined in the compiler command in your makefile: 
 
   MPI_EVOLVER 
   TASK_ID_BITS=22 
   LONG_ID 

The resulting object files should be linked with the appropriate MPI
library. The same executable is used for the master and slave tasks. Note:
the variables nproc and procs_requested you might find in variable.c have
nothing whatsoever to do with MPI; do not change them. 

If you want to easily repartition the surface among the tasks, it is
advisable to link in the PARMETIS and METIS libraries, which can be found
here. In this case, you should also define these manifest constants in
compiling: 
 
   METIS 
   PARMETIS 

<----------------------------- MPI datafiles ------------------------------>
 
There are several ways to set up the datafiles: 

1. Use the same regular Evolver datafile for each task. Then the entire
surface is allocated to task 1 (the first slave task), but all tasks read
the same header information. The surface can be reallocated among the slave
tasks with the "repartition" command described below. 
 
2. Have all the surface in one datafile, but with the various elements
labelled with the task they are allocated to. The labelling is done by
appending "@n" to each element number, where n is the task number. One
advantage of this type of datafile is that it can be read by the regular
Surface Evolver, which just ignores the "@n" labels. For example: 
 
Vertices 
1@4    0.0000000000    0.0000000000    1.0000000000  fixed 
2@1    2.0000000000    0.0000000000    0.0000000000  fixed 
3@2    2.0000000000    2.0000000000    1.0000000000  fixed 
4@3    0.0000000000    2.0000000000    0.0000000000  fixed 
... 
Edges 
1@4   1@4 546@4  fixed 
2@1   2@1 547@1  fixed 
3@2   3@2 548@2  fixed 
4@3   4@3 549@3  fixed 
... 
Faces 
1@4   -3139@4 -3137@4 -3138@4 
2@1   -3142@1 -3140@1 -3141@1 
3@2   -3145@2 -3143@2 -3144@2 
4@3   -3148@3 -3146@3 -3147@3 
... 
Bodies 
1@1  362@3 384@3 383@3 382@2 381@3 ... 

3. Have distinct datafiles for each task. The datafile structure is the same
as in method 2, but elements not allocated to a particular task are
omitted. It is legal to have the same element numbers used on different
tasks; that is, vertex 23@2 is an entirely distinct element from vertex
23@4. Each datafile should have identical header info. 
 
In any case, only the master task reads material in the "read" section at
the bottom of the datafile. Slave tasks do NOT read the "read" section.
This is so that the master task has complete control, and the same file can
be read by all tasks. If slave tasks need to do initialization, the master
task should instruct it with one of the methods described below. 
 

<------------------------------ MPI Evolver ------------------------------->

MPI Surface Evolver - Experimental version of Surface Evolver
that distributes a surface among multiple processors and machines.
See:
MPI Overview
MPI Compilation
MPI Datafiles
MPI Invocation
MPI Execution of commands
MPI Graphics

<------------------------------ MPI graphics ------------------------------>

There are two ways to get screen graphics with MPI Evolver: 
 
1. Use the regular screen graphics on a task. This will display on the same
machine as the task is executing on. Most useful when executing a few tasks
all on one machine for testing purposes. Use the "showq" command to avoid
going into the graphics prompt. For example, 

    parallel_exec "showq" 

to see all the pieces. 
 
2. Use the screen graphics on the master task, and have it import data from
other tasks. I've only tested this for the OpenGL graphics. First, start
graphics in the master task with 's'. This will show the task 1 part of the
surface by default. The task to display may be chosen in the graphics
display by hitting 'M' for menu mode, then using the right mouse key to
display the main menu, then going to the MPI task submenu near the bottom,
and picking the task you want. 
 
The 'y' key toggles showing of the thick corona, if it is present. 

<----------------------------- MPI invocation ----------------------------->
 
However you invoke MPI tasks, each task (master and slave) should have the
name of a datafile on its command line. The datafiles can be different for
each task, or the same one, as described above. If the datafile name
contains "%d", then that will be automatically replaced by the task number
to form the actual datafile name (actually, any version of the C printf %d
format can be used, e.g. %03d to guarantee 3 digits for the task number).
This permits a single MPI command line to load different datafiles on
different tasks. Each task's datafile must be accessible from the machine
it runs on. The master task, task 0, should be run on the machine being
used as the console. 
 

<------------------------------ MPI overview ------------------------------>

MPI (Message Passing Interface) is a protocol for passing messages between
multiple processes, usually on different machines. The MPI version of the
Surface Evolver can execute Evolver on multiple processors on multiple
machines, all working on the same surface, with one machine controlling the
others. It is assumed the user is familiar with MPI, and has MPI installed.

MPI Evolver is still early in development, and still does not do things
necessary for production use. In particular, it does not do topology
changes safely. Anybody using MPI Evolver at this point is doing so just
because they like playing with new toys.
 
MPI Evolver is organized to run task 0 as the master task that interacts
with the user through the command line interface, and a set of slave tasks.
Each slave task is a full version of the Evolver, except it receives its
commands from the master task and there is synchronization of data between
the tasks at key points. Each slave task has a piece of the whole surface,
but the master task does not. Vertices, edges, and facets are allocated
among the slave tasks, but all tasks (including the master task) know about
all bodies (for now, at least). 
 
The surface on each task is divided into "native" elements, that belong to
the task, and "corona" elements copied from other tasks. There are three
levels of corona state currently implemented: 
Level 0: No corona elements. This is the state immediately after the
datafiles are read in, but ordinarily the user never sees it. 
Level 1: Corona vertices and edges of native facets are present. This
suffices for calculation of ordinary surface tension evolution, and is the
default state the user sees after loading. 
Level 2: All corona edges and facets adjacent to native vertices are
present, along with their vertices. This state is needed for certain
energies like squared mean curvature that need more extensive information
around a vertex. In the OpenGL graphics display, the key 'y' toggles
showing the level 2 corona. 
 
 
<------------------------------- mpi_debug -------------------------------->

Main prompt command that toggles the printing of trace messages
by MPI activity in MPI Evolver.  Don't do this.

<------------------------------ mpi_maxtask ------------------------------->

MPI Evolver read-only variable. Highest task number, so task 
numbers run from 0 to mpi_maxtask.  Since task 0 does not have
a piece of the surface, mpi_maxtask is also the number of pieces
the surface can be divided into. 

<-------------------------------- mpi_task -------------------------------->

MPI Evolver read-only element attribute, whose value is which task 
this element belongs to. For example, if you wanted to see which 
vertices task 5 imports from task 2, you could say 
 
         task_exec 5,"list vertex where mpi_task == 2" 

 
<------------------------- multiprocessor option -------------------------->
<--------------------------------- option --------------------------------->

Command line option -pn : Forces use of n processes for an Evolver
compiled in multi-processor mode. n may be larger or smaller than the
physically available number of processors. The default is 1. This option
should be regarded as experimental; there is still too much overhead for
it to be useful usually.

<----------------------------------- N ------------------------------------>

Single letter main command. Set all body target volumes to current actual
volumes.

<----------------------------------- n ------------------------------------>

Single letter main command. Notching ridges and valleys. Finds edges that
have two adjacent facets, and those facets' normals make an angle greater
than some cutoff angle. You will be prompted for the cutoff angle (radians)
if you don't give a value with the command. Qualifying edges will have the
adjacent facets subdivided by putting a new vertex in the center. Should
follow with equiangulation. In the string model, it will refine edges next
to vertices with angle between edges (parallel orientation) exceeding the
given value. Optionally takes cutoff angle on command line.

<----------------------------- named methods ------------------------------>

A "method" is a way of calculating a scalar value from some particular
type of element (vertex, edge, facet, body). Each method is implemented
internally as a set of functions for calculating the value and its gradient
as a function of vertex positions. The most common methods also have
Hessian functions. Methods are referred to by their names.

See "Implemented methods" for a list of available methods. Adding a new
method involves writing C routines to calculate the value and the gradient
(and maybe the Hessian) as functions of vertex coordinates, adding the
function declarations to quantity.h, and adding a structure to the method
declaration array in quantity.c. All the other syntax for invoking it from
the datafile is already in place.


<---------------------------- named quantities ---------------------------->

A "named quantity" is the sum total of various method instances, although
usually just one instance is involved. The instances need not apply to the
same type of element; for example, both facet and edge integrals may be
needed to define a volume quantity. Each named quantity is one of four
types:
 1. "energy" quantities which are added to the total energy of the surface;
 2. "fixed" quantities that are constrained to a fixed target value (by
    Newton steps at each iteration); and
 3. "conserved" quantities are like fixed, but the value is irrelevant. The
    quantity gradient is used to eliminate a degree of freedom in motion.
    Rarely used, but useful to eliminate rotational degree of freedom, for
    example. Will not work with optimizing parameters, since they do gradients
    by differences.
 4. "info_only" quantities whose values are merely reported to the user.
    This type is initially set in a quantity's datafile declaration. A quantity
    can be toggled between fixed and info_only with the "fix quantityname" 
    and "unfix quantityname" commands.

The value of a quantity may be displayed with the A or v commands, or as
an expression "quantityname.value". Furthermore, using the quantity name as
an element attribute evaluates to the sum of all the applicable component
instance values on that element. For example, supposing there is a quantity
named vol, one could do
  print vol.value
  print facet[2].vol
  histogram(facet,vol)

Each quantity has a "modulus", which is just a scalar multiplier for the
sum of all instance values. A modulus of 0 will turn off calculation of all
the instances. The modulus can be set in the datafile declaration, or by 
assignment:
   quantityname.modulus := 1.2

Each fixed quantity has a target value, to which the Evolver attempts to
constraint the quantity value. Each time an iteration is done ( g command
or the various Hessian commands), Newton's Method is used to project the
surface to the constrained values. The target value can be displayed with
the A or v commands, or as "quantityname.target". It can be changed by 
assignment. Example:
  print qname.target
  qname.target := 3.12

A quantity can have a constant value added to it, similar to the body
attribute volconst. This quantity attribute is also called volconst. It is
useful for adding in known values of say integrals that are omitted from
the actual calculation. It can be set in the quantity's datafile
definition, or by an assignment command.

Each fixed quantity has a Lagrange multiplier associated to it. The
Lagrange multiplier of a constraint is the rate of energy change with
respect to the constraint target value. For a volume constraint, the
Lagrange multiplier is just the pressure. Lagrange multipliers are
calculated whenever an iteration step is done. They may be displayed with
the v command in the "pressure" column, or as an expression
"quantityname.pressure".

A fixed quantity can have a tolerance attribute, which is used to judge
convergence. A surface is deemed converged when the sum of all ratios of
quantity discrepancies to tolerances is less than 1. This sum also includes
bodies of fixed volume. If the tolerance is not set or is negative, the
value of the variable target_tolerance is used, which has a default value
of 0.0001.

The sample datafile column.fe contains some examples of named quantities
and instances.

It is planned that eventually all energies and global constraints will be
converted to named quantity system. However, existing syntax will remain
valid wherever possible. Starting Evolver with the -q option will do this
conversion now.

Some methods, those that logically depend on the orientation of the
element, can be applied with a relative orientation. When applied to
individual elements in the datafile, a negative orientation is indicated by
a '-' after the instance name. When applied at runtime with the set
command, the orientation will be negative if the element is generated with
negative orientation, i.e. set body[1].facet method_instance qqq. The
methods currently implementing this feature are: edge_vector_integral,
string_gravity, facet_vector_integral, facet_2form_integral, facet_volume,
facet_torus_volume, simplex_vector_integral, simplex_k_vector_integral,
edge_k_vector_integral, gravity_method, and full_gravity_method.



<------------------------ named quantities option ------------------------->
<--------------------------------- option --------------------------------->

Command line option -q : Convert everything to named quantities internally.
There are a few things for which no quantities exist yet; they will produce
error messages.


<----------------------- named quantity declaration ----------------------->

The syntax for defining a named quantity in the datafile is:

 QUANTITY name   ENERGY|FIXED=value|CONSERVED|INFO_ONLY 
    [LAGRANGE_MULTIPLIER constexpr] [TOLERANCE constexpr]  
    [MODULUS constexpr] methodlist | FUNCTION methodexpr

 Here name is an identifier assigned by the user in order to refer to the
quantity. Any quantities must be declared to be one of three types:
 > ENERGY quantities are added to the overall energy of the surface;
 > FIXED quantities that are constrained to a fixed target value;
 > CONSERVED quantities are like FIXED in that the motion is projected to
   conserve the quantity, but the actual value is not projected to a given
   value.
 > INFO_ONLY quantities whose values are merely reported to the user.

For fixed quantities, the optional Lagrange multiplier value supplies the
initial value of the Lagrange multiplier (the "pressure" attribute of the
quantity). It is meant for dump files, so on reloading no iteration need be
done to have a valid Lagrange multiplier.

For fixed quantities, the tolerance attribute is used to judge
convergence. A surface is deemed converged when the sum of all ratios of
quantity discrepancies to tolerances is less than 1. This sum also includes
bodies of fixed volume. If the tolerance is not set or is negative, the
value of the variable target_tolerance is used, which has a default value
of 0.0001.

Each quantity has a modulus, which is just a scalar multiplier of the
whole quantity. A modulus of 0 will turn off an energy quantity. The
default modulus is 1.

The methodlist version of the quantity definition may contain one or more
method instances. To incorporate a previously explicitly defined instance,
include METHOD instancename. GLOBAL_METHOD may be used instead of METHOD to
indicate the method applies to all elements of the appropriate type; it is
equivalent to using GLOBAL in the method definition. To instantiate a
method in the quantity definition, you essentially incorporate the instance
definition, but without an instance name. Example of a quantity with one
predefined method instance and one implicitly defined instance:
   method_instance qwerty method facet_scalar_integral
     scalar_integrand: x^2
   quantity foobar energy method qwerty method edge_scalar_integral
     scalar_integrand: y^3

Usually the second, implicit definition will be more convenient. Several
method instances may be included in one methodlist (up to a current limit
of 50), and their values are added together and multiplied by the quantity
modulus to get the quantity value. The FUNCTION methodexpr variant defines
the quantity as a function of previously defined method instances. Example:

   method_instance qwerty method facet_scalar_integral
     scalar_integrand: x^2
   quantity foobar energy function qwerty^3


Non-global quantities may be applied to elements individually by adding
the quantity name to the datafile line defining an element. They may also
be applied or unapplied at runtime with the set and unset commands.
Orientable methods can be applied with negative orientation in the datafile
by following the name with a dash. The orientation in a set command follows
the orientation the element is generated with.

Methods applying to different types of elements may be combined in one
quantity. If such a quantity is applied to an element, then all method
instances of that quantity of the appropriate type are applied to the
element. Original attachments of quantities are remembered, soIf an edge
method is applied to a facet, then edges created from refining that facet
will inherit the edge method.

<------------------------------ neo_hookean ------------------------------->
<------------------------------- neo_lambda ------------------------------->
<--------------------------------- neo_mu --------------------------------->

Named method. Contributed by Prof. Rabah Bouzidi. I don't seem to have the
compact formula for this one. Needs neo_lambda, neo_mu, and form_factors.

Element: facet. 
Parameters: none. 
Models: linear. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration: 
 
   quantity bender energy method neo_hookean global 


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


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



<------------------------- no autoconvert option -------------------------->
<--------------------------------- option --------------------------------->

Command line option -a- :
Do not enable automatic conversion to named methods and quantities mode when a
situation requiring it arises; prompt instead.


<------------------------- no renumbering option -------------------------->
<--------------------------------- option --------------------------------->

command line option -i :
Keeps elements numbers as listed in the datafile, instead
of renumbering them consecutively.  The same effect can be achieved
by putting the keyword keep_originals in the top of the datafile.


<------------------------------- no_dump ------------------------------->

Variable boolean attribute.  When set, it prevents the value of a variable
from being written out by the "dump" or "d" commands.  Useful with the
"replace_load" and "add_load" commands when reloading dumps of the current
file and you want to preserve variable values that would otherwise be
overwritten by loading the dump file, which has variables declared in
the top of the datafile by default.  "no_dump" variables are instead
written in the "read" section of the dump file, so the dump file will
load as a stand-alone file  Works on global variables and
arrays.  Syntax (run-time commands; not in top of datafile):
   variable.no_dump on
   variable.no_dump off
The no_dump declaration must come after the variable exists.
Example:
   frame := 1;
   frame.no_dump;
   dump "temp.dmp";
   frame := 2;
   replace_load "temp.dmp"


<------------------------------- no_display ------------------------------->
<------------------------------- nodisplay -------------------------------->

Facet read-write attribute.  When set, suppresses the display of the
facet in graphics.  Can be set in the datafile by adding "no_display"
to the line defining the facet. Can also be manipulated by the set
and unset commands. Nodisplay is a synonym.
Example:

   set facet nodisplay where color != red

<----------------------------- no_hessian_normal ----------------------------->

If you wish to run in hessian_normal mode but exempt particular vertices
from the restriction, you can "set" the vertices' no_hessian_normal
attribute, for example
   set vertex no_hessian_normal where z > 1.2


<------------------------------- no_refine -------------------------------->

Edge and facet read-write Boolean attribute. An edge with the "no_refine"
attribute will not be refined by the r command. This is useful for avoiding
needless refining of lines or planes that are used only for display. Giving
a facet the no_refine attribute has no effect except that edges created
within the facet by refining will inherit the no_refine attribute. So to
avoid refinement of a plane, all edges and facets in the plane must be
given the no_refine attribute. The no_refine attribute may be specified on
the datafile line for an edge or facet, or the set command may be used.
Examples:
  set edge no_refine where fixed
  unset edge[2] no_refine
  list edge where no_refine
  print edge[3].no_refine

<------------------------------ no_transform ------------------------------->

Edge and facet read-write Boolean attribute. An edge or facet with the 
"no_transform" attribute will not be duplicated by the view_transform
mechanism; only the original element will occur.  For example, you might
have edges that form a display of coordinate axes, which you would not want
duplicated.
Example:
   set edge no_transform where valence == 0


<------------------------------ node_charge ------------------------------->

An extra attribute used by the knot_energy named method.

<------------------------------- noncontent ------------------------------->

Edge read-write attribute. When set, indicates this facet should not be
used in volume calculations in the soapfilm model or facet area
calculations in the string model. Useful, for example, if you want to have
edges be part of a body boundary for display purposes, but want to use
constraint integrands for greater accuracy in volume calculations. Example:

   set edge noncontent where on_constraint 1 

<------------------------------ nonnegative ------------------------------->

Level set constraint attribute that vertices on the constraint are
confined to nonnegative values of the constraint.  See "constraint
declaration" for syntax, and "one-sided constraints" for semantics.
Example datafile declaration:
  constraint floorcon nonnegative
  formula: z = 0
This would keep any vertices it was applied to above z = 0, since in 
this context the = is interpreted as >.  Actually, Evolver interprets
= here as - (of low precedence), and the constraint is that the resulting 
expression is nonnegative.

The type of a constraint can be queried at runtime as an expression
     is_constraint[number].nonnegative
or   is_constraint[name].nonnegative
which has value 1 if the constraint is nonnegative, else the value is 0.
"number" may be an expression; "name" is the unquoted name of the
constraint, if it has one.
Example:
     print is_constraint[floorcon].nonnegative
  
Also see hit_constraint for detecting vertices that run into the constraint.

<------------------------------ nonpositive ------------------------------->

Level set constraint attribute that vertices on the constraint are
confined to nonpositive values of the constraint.  See "constraint
declaration" for syntax, and "one-sided constraints" for semantics.
Example datafile declaration:
  constraint topcon nonpositive
  formula: z = 2
This would keep any vertices it was applied to below z = 2, since in 
this context the = is interpreted as <.  Actually, Evolver interprets
= here as - (of low precedence), and the constraint is that the resulting 
expression is nonpositive.

The type of a constraint can be queried at runtime as an expression
     is_constraint[number].nonpositive
or   is_constraint[name].nonpositive
which has value 1 if the constraint is nonpositive, else the value is 0.
"number" may be an expression; "name" is the unquoted name of the
constraint, if it has one.
Example:
     print is_constraint[floorcon].nonpositive

Also see hit_constraint for detecting vertices that run into the constraint.
  

<-------------------------------- nonwall --------------------------------->

Level set constraint attribute. NONWALL indicates this constraint is
to be ignored in vertex and edge popping.  Also, it is used by the various
star_sq_mean_curvature methods to indicate constraints that should not
be taken into account in detecting mirror planes that vertices are on.
Example constraint declaration:
  constraint sphere_con nonwall
  formula: x^2 + y^2 = rad^2

<---------------------------- normal_curvature ---------------------------->

Evolver toggle command. Calculation of squared curvature by taking area of
vertex to be the component of the volume gradient parallel to the mean
curvature vector.  This applies to the sqcurve vertex attribute and
the old-style specification of squared mean curvature energy by
the keyword squared_curvature.


<----------------------------- normal_motion ------------------------------>

Evolver toggle command. Projects motion to surface normal, defined as the
volume gradient. May be useful with squared curvature if vertices tend to
slither sideways into ugly patterns.


<------------------------ normal_sq_mean_curvature ------------------------>

Named method. Description: Integral of squared mean curvature of a
surface, with a slightly different definition from sq_mean_curvature or
eff_area_sq_mean_curvature. To alleviate the instability of
eff_area_sq_mean_curvature, normal_sq_mean_curvature considers the area
around the vertex to be the component of the volume gradient parallel to
the mean curvature vector, rather than the magnitude of the volume
gradient. Thus

  h = (1/2)(F dot F)/(N dot F)

  E = h^2A/3 = (3/4)(F dot F/N do t F)^2 A.

This is still not perfect, but is a lot better. WARNING: For some extreme
shapes, Evolver may have problems detecting consistent local surface
orientation. The assume_oriented toggle lets Evolver assume that the facets
have been defined with consistent local orientation.

If the parameter or vertex attribute h_zero is defined, then the value per
vertex is

  E = (h-h_0)^2 A/3 = (3/4)(F dot F/N dot F - 2h_0)^2A

If the vertex is on one or several constraints, the F and N are projected
to the constraints, essentially making the constraints act as mirror
symmetry planes.

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: no. 
Example datafile declaration:

  quantity nsq energy method normal_sq_mean_curvature global


<--------------------------------- 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 the command

    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.

<------------------------------ notch_count ------------------------------->

Internal read-only variable. Number of edges notched in last
notch command.   Prints and resets to 0 at the end of a command
execution, or when flush_counts is done. Also reset by reset_counts.

<------------------------------- null_area -------------------------------->

Named method. Description: Simply returns 0 for any facet.  Useful
with area_method_name when you don't want area as energy, but you still 
want to assign facets tension.

Element: edge. 
Parameters: none. 
Models: any.
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

  area_method_name "null_area"


<------------------------------ null_length ------------------------------->

Named method. Description: Simply returns 0 for any edge.  Useful
in the string model with length_method_name when you don't want edge 
energy, but you still want to assign edges tension.

Element: edge. 
Parameters: none. 
Models: any.
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

  length_method_name "null_length"

<-------------------------------- numbers --------------------------------->

Constant values may be in any of the usual forms. This includes integers,
fixed point, and scientific notation such as
      2    -3    .5    23.    5e-10    +0.7D2

Hexadecimal integers starting with 0x, as in 0x12Af, are also accepted, as
are binary numbers such as 11001b, indicated by a trailing 'b'. Color names
are interpreted as integers.

<----------------------------------- O ------------------------------------>

Single letter main command. Pop non-minimal edges. Scans for edges with
more than three facets attached. Splits such edges into triple-facet edges.
Splits propagate along a multiple edge until they run into some obstacle.
This command is meant for surfaces that have equal tension on all facets.
Also tries to pop edges on walls properly. For finer control on which edges
to try, use the pop command. Try octa.fe for an example.

<----------------------------------- o ------------------------------------>

Single letter main command. Pop non-minimal vertices. This command scans
the surface for vertices that don't have the topologies of one of the three
minimal tangent cones that are legal in soap films (plane, triple edge,
tetrahedral point). These are "popped" to proper local topologies. The
algorithm is to replace the vertex with a sphere. The facets into the
original vertex are truncated at the sphere surface. The sphere is divided
into cells by those facets, and the largest cell is deleted, which
preserves the topology of the complement of the surface. A special case is
two cones meeting at a vertex; if the cones are broad enough, they will be
merged, otherwise they will be split. In case of merging cones, if both
cone interiors are defined to be part of the same body, then no facet is
placed across the neck created by the merger; if they are different bodies
or no bodies, a facet will be placed across the neck. Only vertices in the
interior of a surface, not fixed or on constraints or boundaries, are
tested. Try popstr.fe and octa.fe for examples.


<---------------------------------- oid ----------------------------------->

Geometric element read-only attribute. The oid of an element is the
"oriented id" of an element as used in an expression. It is the id number
signed according to whether the use of the element is with the same or
opposite orientation as the way it is stored. Example: to get an edge list
for a facet as in the datafile, use oid instead of id:

   foreach facet ff do { printf "%g  %g %g %g\n",ff.id,ff.edge[1].oid,
      ff.edge[2].oid,ff.edge[3].oid }

<-------------------------------- old_area -------------------------------->

Evolver toggle command. In the string model with area normalization, at a
triple vertex Evolver normally tries to calculate the motion so that Von
Neumann's Law will be obeyed, that is, the rate of area change is
proportional to the number of sides of a cell. If old_area is ON, then
motion is calculated simply by dividing force by star area.

<--------------------------- old_force_ribiere ---------------------------->

Vertex extra attribute used internally by conjugate gradient mode.

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

<---------------------------- on_assign_call ------------------------------>

A procedure may be designated to be called whenever the value of the
variable is changed.  The syntax in the top of the datafile is

      PARAMETER identifier = expr ON_ASSIGN_CALL procedure_name

The purpose of this feature is to permit side-effects of changing
a variable value.  The value is a procedure without arguments, and can only
be assigned in the top of the datafile.  However, the procedure itself may
be redefined at will.  Example (in the top of the datafile):

  procedure tester();
  parameter aaa = 4
  parameter bbb = 5 on_assign_call tester
  procedure tester() { aaa := bbb; }

Note that there is a declaration of "tester" first, so Evolver recognizes
"tester" as a procedure name during the declaration of "bbb".  But the full
declaration of "tester" may be in the top of the datafile or in the "read"
section of the datafile.


<------------------------------ on_boundary ------------------------------->

Vertex, edge, or facet read-only attribute.
The status of whether an element is on a boundary can be queried with the
Boolean attribute on_boundary. Elements can be unset from boundaries, but
not set on them (since parameter values would be unknown). Examples:

  list vertex where on_boundary 1
  unset vertex boundary 2

<----------------------------- on_constraint ------------------------------>

Vertex, edge, or facet read-only attribute. Boolean attribute for whether
an element is on a given constraint. The full syntax of the attribute is
"on_constraint n" where n is the number of the constraint. Examples:

   list edge where on_constraint 3
   print vertex[3].on_constraint 1


<--------------------------- on_method_instance --------------------------->

Vertex, edge, or facet read-only attribute. Boolean attribute for whether
an element contributes to a given named method instance. The full syntax of
the attribute is "on_method_instance instancename". Examples:

   list facet where on_method_instance  center_of_mass_x_edges
   print vertex[3].on_method_instance blue_area_1

<------------------------------ on_quantity ------------------------------->

Vertex, edge, or facet read-only attribute. Boolean attribute for whether
an element contributes to a given named quantity. Actually, it tests
whether the element is on any of the method instances comprising a
quantity. The full syntax of the attribute is "on_quantity quantityname".
Examples:

   list facet where on_quantity  center_of_mass_x
   print vertex[3].on_quantity blue_area

<------------------------- one-sided constraints -------------------------->

If a level set constraint is declared NONNEGATIVE or NONPOSITIVE in the
datafile, the vertices subject to the constraint must stay in that part of
the domain of the level set function. It is usually unwise to give edge
integrals to edges on one-sided constraints, or to declare them CONVEX.
Whether a vertex exactly satisfies the constraint may be queried with the
vertex hit_constraint attribute. The 'g' iteration step will check for a
vertex wanting to leave a one-sided constraint it has hit, but hessian
commands do not; therefore it is wise to intersperse 'g' with hessian or
hessian_seek when there are one-sided constraints involved. Example:
Suppose one wanted to keep a bubble inside a spherical tank of radius 5.
Then one would define the constraint in the datafile
constraint 1 nonpositive
formula: x^2 + y^2 + z^2 = 25

For purposes of evaluating nonnegativity or nonpositivity, all terms are
shifted to the left side of the formula. One would then apply this
constraint to all vertices, edges, and facets of the bubble surface.

If you define the real-valued vertex extra attribute one_sided_lagrange, the
Lagrange multipliers for vertices hitting one-sided constraints will
be recorded.  one_sided_lagrange may be defined as an array.  If a vertex
hits more constraints than the size of one_sided_lagrange, then the 
first ones that fit will be recorded.

<--------------------------- one_sided_lagrange --------------------------->

If you define the real-valued vertex extra attribute one_sided_lagrange, the
Lagrange multipliers for vertices hitting one-sided constraints will
be recorded.  one_sided_lagrange may be defined as an array.  If a vertex
hits more constraints than the size of one_sided_lagrange, then the 
first ones that fit will be recorded.

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


<-------------------------------- opacity --------------------------------->

Facet attribute for transparency. Syntax: 
   set facet opacity value where condition
where value is between 0 (clear) and 1 (opaque).  Screen graphics will
show transparency, but PostScript output will not.  Hitting the letter 'O'
key in the graphics window will toggle transparency, if the opacity
attribute has been assigned values.  Showing transparency properly requires 
sorting the facets back to front, so graphics will be slower if there are 
many facets. 

<--------------------------------- OpenGL --------------------------------->

Ideally, you have a version of the Evolver that uses OpenGL/GLUT for its
screen graphics. OpenGL is standard on Mac OSX, most unix systems, and
Microsoft Windows. Tbe graphics display is invoked with the 's' command,
which leaves you at the graphics prompt, which you should quit 'q' right
away since graphics commands are better given in the graphics window. There
are many mouse and keyboard actions that can be performed in the graphics
window itself. Holding down and dragging the left mouse button moves the
surface continuously, and the clicking right mouse button picks vertices,
edges, and facets. Picked element id numbers are printed in the console
window. With the graphics window in the foreground, these keyboard commands
are active:

h Print a help screen on the console window.
r Rotate mode for left mouse button.
t Translate mode for left mouse button.
z Zoom mode for left mouse button (and use F to focus on particular vertex).
c Clockwise/counterclockwise spin mode for left mouse button.
k Active clipping plane in rotate mode.
l (lower case L) Active clipping plane in translate mode.
L Deactivate clipping plane.
+ Widen edges.
- Narrow edges.
b Decrement edge front bias by .001.
B Increment edge front bias by .001 (to show edges more clearly).
R Reset the view.
m Center the image.
M Have the right mouse button bring up a menu instead of picking.
P Have the right mouse button do picking instead of menu (default).
p Toggle orthogonal/perspective projection.
s Toggle cross-eyed stereo.
e Toggle showing edges, regardless of "show edge" condition.
f Toggle showing facets obeying "show facet" condition or no facets.
F Move the rotate/zoom origin to the last picked vertex.
G Start another graphics window with independent camera.
o Toggle drawing a bounding box.
g Toggle Gourard (smooth) shading.
x Close the graphics window.
arrow keys Translate a bit.
And some more advanced commands most users will never use, but are listed
here for completeness:
H Print advanced help.
a Toggle using OpenGL element arrays.
i Toggle interleaved elements in OpenGL arrays.
I Toggle indexed OpenGL arrays.
S Toggle OpenGL triangle strips.
Y Toggle strip coloring (I was curious as to what OpenGL triangle strips
would look like).
D Toggle using a display list.
Q Toggle printing drawing statistics.

<------------------------------- operators -------------------------------->

These are the arithmetic operators that may appear in expressions:

 +,-,*,/: Usual real arithmetic. NOTE: A '+' or '-' preceded by whitespace
          and followed by a number is taken to be a signed number. 
          Thus "3 - 5" and "3-5" are single expressions, but "3 -5" is not. 
          This is for convenience in separating multiple expressions listed 
          on the same line for vertex coordinates, metric components, etc. 
          in the datafile.

 idiv : Integer divide. Rounds toward zero, then does integer division. Ex:
        7 idiv 2 is 3; -3.5 idiv 2.1 is -1; -3 idiv 2 is -1.

 %, mod: Real arithmetic modulus, x % y = x - floor(x/y)*y.

 imod: Integer arithmetic modulus, defined as
           x imod y = floor(x) - floor(floor(x)/floor(y))*floor(y).

 (,): Parentheses for grouping and functional notation.

 ^,**: Raise to real power.

 ? : : Conditional expression, as in the C language. x ? y : z evaluates to
       y if x is nonzero and to z if x is zero.

++,--  C-style pre- and post-increment and decrement commands.  These work only
       on single variables and only as stand-alone commands, as in "for"
       loops for example:
           for ( inx := 1 ; inx <= 10 ; inx++ )


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

<-------------------------- optimising_parameter -------------------------->
<-------------------------- optimizing_parameter -------------------------->

A variable may be made subject to optimization during iteration or hessian
commands with the datafile declaration

  OPTIMIZING_PARAMETER identifier=constexpr PDELTA=constexpr PSCALE=constexpr

Such a variable joins the vertex coordinates as an independent variable
during optimization. However, it differs from a coordinate in that
gradients with respect to it are calculated numerically, rather than
analytically. Thus it may be used anywhere a variable is permitted.
Hessians with optimizing parameters are implemented. The optional pdelta
value is the parameter difference to use in finite differences; the default
value is 0.0001. The optional pscale value is a multiplier for the
parameter's motion, to do "impedance matching" of the parameter to the
surface energy. These attributes may be set on any parameter, for potential
use as an optimizing parameter. At runtime, a parameter may be toggled to
be optimizing or not with the FIX and UNFIX commands. That is, fix radius
would make the radius variable non-optimizing (fixed value). Also, the
pdelta and pscale attributes may be accessed at runtime, as in

   height.pscale := 2*height.pscale

"Optimising_parameter" is a synonym.


<---------------------------- optimizing scale ---------------------------->

In using gradient descent to seek a minimum energy, one finds a direction
of motion and does a line search along that direction to find the minimum
energy. Evolver will do that in optimizing scale mode. The line search
consists of halving or doubling the current scale factor until an energy
minimum is bracketed; then quadratic interpolation is used to estimate the
optimum scale. Optimizing scale is the default; it also may be turned on
with the m command or the optimizing command.

For safety, there is an upper bound to the scale; it defaults to 1 but may
be changed with the optimizing command. There is also a lower bound; if
Evolver gets a scale below 1e-12 of the scale bound when attempting to find
a minimum, it gives up and just uses scale 0. Scale 0 is not a null
operation since it still projects to constraints, if they are not exactly
satisfied.

In general, a good scale factor depends on the type of energy being
minimized and the level of refinement. However, for minimizing area, when
the triangulation is well-behaved and area normalization is off, the best
scale factor is usually around 0.2, independent of refinement. In
optimizing mode, a scale factor getting small, say below 0.01, indicates
triangulation problems. Too large a fixed scale factor will show up as
total energy increasing. If you have motion by area normalization ON use a
small scale factor, like 0.001, until you get a feel for what works.

If check_increase is toggled on, then the motion is not done if it would
increase energy. But be aware that energy sometimes may have to increase in
order to satisfy constraints.


<-------------------------------- options --------------------------------->

Command line options:

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

  evolver [-ffilename] [options] [datafile] 

Options:
 [-a-] [-d] [-e] [-i] [-m] [-pn] [-q] [-Q] [-w] [-x] [-y]

The current directory and EVOLVERPATH will be searched for datafile. If the
datafile is not found, then a new search with extension .fe is done.
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. If the datafile still not found, or the datafile is not
given on the command line, then the user will be prompted. For information
on individual options, see "option -a" etc.


<------------------------------ orientation ------------------------------->

Facet and edge read-write attribute. Controls the sign of oriented integrals 
on a facet or edge. Value +1 or -1. Useful when triangulation manipulations 
create a facet with an undesired orientation. Example:

   set facet[123] orientation -1

Note that this is different from the "reverse_orientation" command, which
physically changes vertex order.

<-------------------------------- original -------------------------------->

Geometric element read-only attribute. For elements read from the
datafile, this is the number given to the element in the datafile, which
may be overridden by an explicit original attribute value in the datafile
line defining the element. The value is inherited by all elements of the
same type that result from subdivision. For elements otherwise generated at
run time, the original attribute value is -1. Example: to show which facets
descended from face 1 in the datafile:

   set facet color red where original == 1

<----------------------------------- p ------------------------------------>

Single letter main command. Sets ambient pressure in ideal gas model. If
you don't give a value with the command, you will be prompted. A large
value gives more incompressible bodies.

<----------------------------------- P ------------------------------------>

Single letter main command. Produce graphics output files. "P" is for
"picture". This brings up a menu, unless you give the menu option on the
command line. For the 2D graphics options, the view is the same as seen
with the s command. For options that output to a file, you will be prompted
for a filename. Some other possible options you may be asked:

Display raw cells, connected bodies or clipped cells? (0,1,2) : If you are
doing torus model, you will be asked for a display option, unless you have
already set one.

Do normal interpolation? : Some formats are capable of doing interpolation
between vertex normals for smoother shading, and you will be asked if you
want to do that.

Do inner, outer, or all surfaces? (i,o,a) : When bodies are present, there
is an option to plot the inner surfaces(adjacent to two bodies), outer
surfaces (adjacent to 0 or 1 bodies), or all surfaces of the bodies.

Do body colors? : This gives you a chance to color the bodies differently.
If you do, the current colormap file will be used to color the bodies
according to id number. This scheme is a relict of early days of the
Evolver, and it is suggested that you use the color, frontcolor and
backcolor facet attributes instead.

Enter name of colormap file: : If there is no current colormap file, you
will be prompted. The colormap file has the format of RGB values, one set
per line, values between 0 and 1. (This map may not be effective on all
devices.)

Thicken? (n | y [thickness(0.001)]) : You may also be asked if you want
thickening. If you do, each facet will be recorded twice, with opposite
orientations, with vertices moved from their original positions by the
thickening distance (which the option lets you enter) in the normal
direction. The normal used at each vertex is the same as used for normal
interpolation, so all the facets around a planar vertex will have that
vertex moved the same amount. Triple junctions will be separated.
Thickening is good for rendering programs that insist on consistently
oriented surfaces, or that have problems with show-through of the backside
of a surface. Choosing 'y' or 'n' will reset the thicken toggle. If you
answer 'y', you can optionally specify the thickness, which defaults to the
value of the thickness internal variable.

The menu choices for types of output are:
1. Pixar file : For Pixar format. Actually same format as option 2.
2. OOGL file : This is a file in a file format used by geomview, which is
   Object Oriented Graphics Language. Suitable for direct input into geomview.
3. PostScript file : Generates a PostScript file.
4. Triangle file : A private format file, just listing data. Not much use
   any more.
5. Softimage file : Output file in Softimage format.
8. Start simultaneous geomview : If you have the geomview package
   installed, this command will start geomview and display the current
   surface. Changes to the surface are automatically displayed unless
   autodisplay is toggled off.
9. End simultaneous geomview : Terminates any geomview program or pipe.
A. Start OOGL pipe. : Geomview uses a pipe interface at the moment. This
   starts a named pipe with geomview output, but without invoking geomview.
   You will be told the name of the pipe, and it is up to you to start a pipe
   reader. Evolver blocks until a pipe reader is started. This is useful for
   having a second instance of Evolver feed a second surface to geomview by
   having geomview load the pipe. Also good for checking exactly what Evolver
   is sending to geomview. The geompipe command does the same thing. Terminate
   the pipe with "P 9". Note that only one geomview output at a time is
   possible, so you can't have a geomview display and separate pipe active at
   the same time.
B. End OOGL pipe. : Same as option 9.

<----------------------------------- p1 ----------------------------------->
<----------------------------------- p2 ----------------------------------->

P1 and p2 are the names of the parameters of a vertex on a parametric
boundary. P1 is used for a 1-parameter boundary, and p1 and p2 for
a 2-parameter boundary.  And p3 is available for a 3-parameter boundary.
Examples:
    vertex[1].p1 := 1.2
    print vertex[2].p1

<----------------------------- parallel_exec ------------------------------>

Main prompt command in MPI Evolver. Causes each slave task to execute 
the string. Syntax:
   parallel_exec string
where string may be a double-quoted string or a string variable.
In individual tasks, any aggregate commands such as "sum" execute 
across all local and imported elements. 

<------------------------------- parameter -------------------------------->
<------------------------------- parameters ------------------------------->

Refers to either a "parametric boundary" parameter, or a user-defined
variable.  In the latter case, a variable can be declared in the
top of the datafile with the syntax

   parameter pname = value

where "pname" is the name of the variable and "value" is a numeric
expression involving known variables.  The initial value is required.
See also "optimizing_parameter".


<---------------------------- parameter scale ----------------------------->
<--------------------------------- pscale --------------------------------->

Optimizing paramater attribute, used as a multiplier for the
parameter's motion, to do "impedance matching" of the parameter to the
surface energy. Default value is 1.  The pscale attribute may be set
in the datafile parameter declaration, for example

  optimizing_parameter height = 1.5  pscale = 10.0

and accessed at runtime with the usual attribute syntax, as in

  height.pscale := 2*height.pscale


<---------------------------- parameter values ---------------------------->

Vertex read-write attribute. Vertices on parametric boundaries are located
according to the parameter values. Parameters are referred to as p1,p2,...
Usually only p1 is used, since one-parameter curves used as boundary wires
are most common. Such vertices in the original surface have their parameter
values given in the vertices section of the datafile instead of their
coordinates. Vertex parameters may be read or modified with the command
language. Example:

  foreach vertex do printf "%g %f\n",id,p1
  set vertex[1] p1 1.2


<----------------------------- parameter_file ----------------------------->

In the top section of the datafile, a variable can be initialized with a
set of values in a file with the syntax

  PARAMETER name PARAMETER_FILE string

I forget exactly how it is all supposed to work.

<------------------------------ parameter_1 ------------------------------->

A generic parameter used by a couple of named methods.

<------------------------- parametric boundaries -------------------------->
<-------------------------- parametric boundary --------------------------->

Parametric "boundary" curves and surfaces
Vertex locations may be given in terms of parameters on a parameterized
curve or surface. Such curves or surfaces are called "boundaries" in
Evolver terminology, since they are usually used as boundary curves of
surfaces, for example a soap film on a wire loop could have the wire
implemented as a boundary. Vertices, edges, and facets may be deemed to lie
in a boundary. For a vertex, this means that the fundamental parameters of
the vertex are the parameters of the boundary, and its coordinates are
calculated from these. Vertices on boundaries may move during iteration,
unless declared fixed. See cat.fe for an example.

Boundaries are defined in the top section of the datafile. Vertices on
boundaries are listed in the datafile with their parameter values instead
of their coordinates, with "boundary n" appended to each such vertex
definition. Edges and faces on boundaries are defined as usual, but with
"boundary n" appended to each definition. So the datafile has lines like
these:

boundary 1 parameters 1
x1:  cos(p1)
x2:  sin(p1)
x3:  0.75
...
Vertices
1   0.0  boundary 1
2   pi/3 boundary 1
...
Edges
1   1 2 boundary 1
...


Putting an edge on a boundary means that vertices created on that edge will
be on the boundary. An edge on a boundary must have at least one endpoint
on the boundary, for use in extrapolating the boundary parameters of any
created vertices. Extrapolating instead of interpolating midpoint
parameters solves the problem of wrap-arounds on a boundary such as a
circle or cylinder. However if you do want interpolation, you can use the
keyword INTERP_BDRY_PARAM in the top of the datafile, or use the toggle
command interp_bdry_param. Interpolation requires that both endpoints of an
edge be on the same boundary, which cannot happen where edges on different
boundaries meet. To handle that case, it is possible to add extra boundary
information to a vertex by declaring two particular vertex extra
attributes, extra_boundary and extra_boundary_param:

  interp_bdry_param
  define vertex attribute extra_boundary integer
  define vertex attribute extra_boundary_param real[1]

Then declare attribute values on key vertices, for example

   vertices
   1    0.00  boundary 1   fixed extra_boundary 2 extra_boundary_param 2*pi

If the extra_boundary attribute is not set on a vertex when wanted,
Evolver will silently fall back on interpolation.

Putting a face on a boundary means that all edges and vertices created
from refining the face will be on the boundary. In this case, the boundary
should have two parameters (or whatever the dimension of the surface is).
This is good for getting a surface to conform to a known parametric shape.
Edges on boundaries have energy and content integrals like level-set
constraints edges, but they are internally implemented as. named
quantities.

Whether an element is on a particular boundary can be queried with the
on_boundary Boolean attribute. Elements can be removed from boundaries with
the unset command, but they cannot be set on boundaries. A typical use of
unset is to define an initial surface using a 2-parameter boundary, refine
a couple of times, then unset. Examples:
  list vertex where on_boundary 2
  unset vertex boundary 1 where on_boundary 1
  unset edge boundary 1
  unset facet boundary 1

It does not hurt to unset an element not on the boundary.
Vertex parameters can be accessed in expressions as the attribute p1 (and
p2,... for further parameters). Vertex parameters can be changed with the
set command. Example:
  print vertex[5].p1
  set vertex p1 p1+.1 where id < 4
  vertex[2].p1 := 3

It is not an error to access the parameters of a vertex not on a boundary
as long as some vertex is on a boundary (so that space is allocated in the
vertex structure for parameters).

A general guideline is to use constraints for two-dimensional walls and
boundaries for one-dimensional wires. If you are using a boundary wire, you
can probably declare the vertices and edges on the boundary to be FIXED.
Then the boundary becomes just a guide for refining the boundary edges.

NOTE: A vertex on a boundary cannot also have constraints.


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


<--------------------------------- pdelta --------------------------------->

Optimizing parameter attribute, used for the magnitude of change in
numerical differencing to find the gradient with respect to the paramter.
This should be small enough that the surface stays in the linear change
regime when the variabls is changed by pdelta.  Default value 0.0001.  
May be set in the parameter's datafile declaration, for example

   optimizing_parameter height = 0.01 pdelta = 0.000001

and accessed at runtime with the usual attribute syntax:

   height.pdelta := 1e-5


<-------------------------------- periods --------------------------------->

If periodic boundary conditions are used (the torus model) , the period
vectors of the fundamental unit cell parallelpiped may be defined in the
top section of the datafile. Default is the unit cube. The syntax is the
keyword PERIODS followed by expressions for the components of each period
vector:

  PERIODS
  expr expr expr
  expr expr expr
  expr expr expr

The size of this matrix depends on the space dimension. Variables may be
used in the expressions, so the fundamental domain may be changed
interactively by assigning new values to the variables. Be sure to give a
recalc command whenever you change such a variable, in order to get the
period matrix re-evaluated.

<-------------------------- permanent assignment -------------------------->

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.


<-------------------------------- permload -------------------------------->

Deprecated.  See replace_load.

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.


<--------------------------------- phase ---------------------------------->
<--------------------------- phase declaration ---------------------------->
<------------------------------- phasefile -------------------------------->

To declare that the surface tension of an edge or facet depends on the
phases of its adjacent facets or bodies, the top section of the datafile
should contain a line of the form

 PHASEFILE "filename"

The information is read from an ASCII file, whose name is given in a
double-quoted string. The first line of the file has the number of
different phases. Each line after consists of two phase numbers and the
surface tension between them. Lines not starting with a pair of numbers are
taken to be comments. If a pair of phases is not mentioned, the surface
tension between them is taken to be 1.0. Facets in the string model or
bodies in the soapfilm model can be labelled with phases with the PHASE n
phrase in the datafile.

<----------------------------------- pi ----------------------------------->

Mathematical constant, ratio of circle circumference to radius.


<-------------------------------- pickenum -------------------------------->

Internal read-write variable. Number of last edge picked in geomview.

<-------------------------------- pickfnum -------------------------------->

Internal read-write variable. Number of last facet picked in geomview.

<-------------------------------- picking --------------------------------->

One of the big advantages of using geomview or the OpenGL version is that
you can pick vertices, edges, and facets in the geomview window by
right-mouse-clicking, and the id numbers of the picked objects will be
printed in the main window. Be careful when picking; it does not always
work as you might hope. It may be necessary to zoom in on the surface to
get a clear shot at the element you want. Be wary when the element returned
is 1; that seems to be a common response when Evolver is confused as to
what element was picked. Also, Evolver polls geomview for pick results only
when at a prompt awaiting user input.

Picked vertex, edge, and facet numbers are stored in the internal
variables pickvnum, pickenum, and pickfnum, respectively. The 'F' key
command on the graphics window sets the rotation and scaling center to the
pickvnum vertex. Pickvnum is settable with ordinary assignment commands, so
the user can zoom in on any vertex desired.

Note: Since vertices are not drawn individually, Evolver reports a vertex
as picked only when two edges with a common vertex are simultaneously
picked. Therefore a vertex at the end of a single edge cannot be picked.

<-------------------------------- pickvnum -------------------------------->

Internal read-write variable. Number of last vertex picked in geomview.

<-------------------------------- pinning --------------------------------->

Evolver toggle command. Check for vertices that can't move because
adjacent vertices are not on same constraint when they could be. Obscure.


<--------------------------------- piping --------------------------------->

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

<----------------------------- poisson_ratio ------------------------------>

Facet extra attribute used by various elastic named methods:
linear_elastic, linear_elastic_B, neo_hookean, relaxed_elastic, 
relaxed_elastic_A, relaxed_elastic_B, SVK_elastic, and dirichlet_elastic.  
This is the two-dimensional isotropic poisson ratio.

<-------------------------- polyhedral curvature -------------------------->

A type of mobility. Following a suggestion of Gerhard Dzuik and Alfred
Schmidt, the inner product of global vectors is taken to be the integral of
the scalar product of their linear interpolations over the facets (or edges
in the string model). This has the advantage that the rate of area decrease
of the surface is equal to the rate volume is swept out by the surface,
which is a characteristic of motion by mean curvature. A big disadvantage
is that the matrices M and S are no longer local (see mobility). S is a
sparse matrix with entries corresponding to each pair of vertices joined by
an edge, and M is its dense inverse. Approximate polyhedral curvature can
be toggled with the approx_curv toggle command.

<---------------------------------- 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. The pop_enjoin toggle forces joining cones to be popped by
widening the vertex into a neck. Examples:

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

Under some circumstances, popping a vertex can leave two regions 
connected by a tunnel; if the septum_flag toggle is on, it will 
force a  surface to be placed across the tunnel.

<------------------------------- pop_count -------------------------------->

Internal read-only variable. Sum of vertex_pop_count and
edge_pop_count. Kept for backwards compatibility.

<------------------------------ pop_disjoin ------------------------------->

Evolver toggle command. Changes the behavior of popping edges and vertices
to act like merging Plateau borders, i.e. produce disjoined films instead
of films joined with cross-facets. In the edge case, if four facets meet
along an edge and two opposite bodies are the same body, then popping the
edge will join the bodies if pop_disjoin is in effect. In the vertex case,
if the vertex has one body as an annulus around it, then the vertex will be
separated into two vertices so the annulus becomes a continuous disk. This
is all done regardless of the angles at which facets meet. Applies to pop,
o, and O commands.


<------------------------------- pop_enjoin ------------------------------->

Evolver toggle command. Changes the behavior of popping vertices in the
soapfilm model so that when two distinct cones are detected meeting at a
common vertex, the popping result is a widening of the cone vertex into a
neck rather than a disjoining of the cones. meet. Applies to pop and o
commands. 
 
<---------------------------- 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_edge_to_tri_count -------------------------->

Internal read-only variable. Number of edges flipped to triangles by the
pop_edge_to_tri command. Prints and resets to 0 at the end of a command
execution, or when flush_counts is done. Also reset by reset_counts.

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

Internal read-only variable. Number of quadrilaterals flipped by the
pop_quad_to_quad command. Prints and resets to 0 at the end of a command
execution, or when flush_counts is done. Also reset by reset_counts.

<------------------------------ pop_to_edge ------------------------------->

Evolver toggle command.  The non-minimal cone over a triangular prism
frame can pop in two ways. If this toggle is on, then popping to an edge
rather that a facet will be done. Default off.


<------------------------------ pop_to_face ------------------------------->

Evolver toggle command. The non-minimal cone over a triangular prism frame
can pop in two ways. If this toggle is on, then popping to a facet rather
that an edge will be done. Default off.


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


<------------------------- pop_tri_to_edge_count -------------------------->

Internal read-only variable. Number of triangles flipped to edges by the
pop_tri_to_edge command. Prints and resets to 0 at the end of a command
execution, or when flush_counts is done. Also reset by reset_counts.

<------------------------------ fgagfa_coeff ------------------------------>
<------------------------------ gfa_2_coeff ------------------------------->
<------------------------------ gfaafg_coeff ------------------------------>
<------------------------------ gfagfa_coeff ------------------------------>
<------------------------------- gga_coeff -------------------------------->

Internal variable used by the pos_area_hess method.  See pos_area_hess.

<----------------------------- pos_area_hess ------------------------------>

Named method. Description: Same as the facet_area method, but the Hessian
can be adjusted various ways by setting the variables fgagfa_coeff,
gfa_2_coeff, gfagfa_coeff, and gfaafg_coeff. This will make sense if you
look at the Dirichlet section of the Technical Reference chapter of the
printed manual. The default values of the coefficients are -1, 1, -1, and 0
respectively. 

Element: facet. 
Parameters: none. 
Models: linear. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

   quantity parea energy method pos_area_hess global

<------------------------------ post_project ------------------------------>

Evolver toggle command. Introduces extra projections to volume and fixed
quantity constraints each g iteration. If convergence fails after 10
iterations, you will get a warning message, repeated iterations will stop,
and the internal variable iteration_counter will be negative.


<------------------------------- postscript ------------------------------->

The Surface Evolver can generate PostScript files by either the postscript
command or the P command option 3, or just "P 3". The image is the same one
shown with the native screen graphics, so one should use the s command and
graphics mode commands to get the image looking as desired. The variable
brightness can be used to set the median gray level. The PostScript image
is put into an 8 inch square at the lower left of the page.

With the P command, you will be prompted for options.
Show grid lines? : This is asked if you are graphing a 2D surface. If you
reply 'y', all triangle edges will be plotted. If 'n', only special edges
will be plotted (triple junctions, borders, etc.; this can be controlled
with the show edges command). Default 'n'. The postscript command uses the
ps_gridflag toggle to control this.

Do colors? : If you reply 'y', edges and facets will be plotted with their
color attributes and shading (if activated). If 'n', then all edges are
plotted as black, and all facets as white with shading. Default 'n'. The
postscript command uses the ps_colorflag toggle to control this.

Do crossings? : This is asked if the surface is 1-dimensional (the string
model) and the dimension of space is at least 3. If you reply 'y', a 3D
effect will be created by plotting edges back to front, with each edge
plotted first as a thick white line and then as a thin black line. This
creates a broken back line and continuous foreground line at each crossing.
Default 'n'. The postscript command uses the ps_crossingflag toggle to control
this.

Do labels? (i for ids, o for originals) : This PostScript P 3 command
subprompt gives you a chance to put numeric labels on vertices, edges, and
facets, which is useful for debugging or modifying a datafile. Edge labels
are slightly displaced toward the head of the edge, and facet labels are
signed according to which side of the facet is visible. Choose 'i' or 'y'
for the current element id, or 'o' for the original element number. If you
don't want any labels, just hit RETURN. The postscript command uses the
ps_labelflag toggle to control this. The relative size of the labels can be
controlled with the ps_labelsize variable, whose default value is 3.0.

Enter file name (.ps will be added): : Give the name of the PostScript
output file. A ".ps" extension will be added if ".ps" or ".eps" is missing.
Not a good idea to just hit RETURN, since that will produce the file ".ps".


The linewidth of PostScript edges may be controlled by the user. Widths
are relative to the image size, which is 3 units square. If the real-valued
edge extra attribute ps_linewidth is defined, that value is used as the
edge width. Otherwise some internal read-write variables are consulted for
various types of edges, in order:
 ps_stringwidth - edges in the string model, default 0.004
 ps_bareedgewidth - "bare" edges, no adjacent facets, default 0.005
 ps_fixededgewidth - "fixed" edges, default 0.004
 ps_conedgewidth - edges on constraints or boundaries, default 0.004
 ps_tripleedgewidth - edges with three or more adjacent facets, default 0.003
 ps_gridedgewidth - other edges, default 0.002

The bounding box listed in the PostScript file is normally the actual
extent of the surface in the window (i.e. the bounding box is never bigger
than the window, but may be smaller). The full_bounding_box toggle will
force the bounding box to be the full window. This is useful in controlling
the image size while making a series of images of different views or
evolution stages of a surface.


<--------------------------- postscript command --------------------------->

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, ps_gridflag, ps_crossingflag, and labelflag toggles.
full_bounding_box toggles.

See "postscript" for more.

<---------------------------------- pow ----------------------------------->

 pow(x,y) : Raise x to real power y; x may be negative if y is an integer.

<------------------------------- precedence ------------------------------->
<----------------------------- associativity ------------------------------>

Here is the order of operator precedence, listed from high to low with
equal precedence on same line, with associativity.

Operator            Associativity
^,**               left associative
unary -            right associative
*,/,%,IMOD,IDIV    left associative
+,-                left associative
on_boundary
on_constraint
hit_constraint
on_quantity
on_method_instance nonassociative
==,>,<,>=,<=,!=    right associative
NOT, !             right associative
AND, &&            left associative
OR, ||             left associative
? :                left associative
=                  left associative

<-------------------------------- pressure -------------------------------->

Usually means an attribute of fixed-volume bodies or fixed named quantities 
that is actually the Lagrange multiplier for the constraint, as printed
by the "v" command. As a body attribute in the datafile, it establishes 
fixed pressure for the body.  Also used rarely in the top section of the 
datafile to establish the "ideal gas model"; see "ideal gas declaration".


<---------------------------- pressure energy ----------------------------->

Each body with a prescribed pressure P contributes energy E = PV. where V
is the actual volume of the body. This can be used to generate surfaces of
prescribed mean curvature, since mean curvature is proportional to
pressure. Pressure can be prescribed in the bodies section of the datafile,
and can be changed with the b command, or by assigning a value to the
pressure attribute of a body.

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


<------------------------------- profiling -------------------------------->
<---------------------------- print profiling ----------------------------->
<---------------------------- reset_profiling ----------------------------->

Expression Evaluation Profiling
 
On systems where Evolver has cpu_counter available and Evolver has been
compiled with the manifest constant PROF_EVALS defined, the expression
evaluator inside Evolver keeps track of the clock cycles elapsed during
each expression evaluation. These expressions include procedures,
functions, constraint and boundary formulas, content integrands, energy
integrands, quantity integrands, etc; everything that prints out as code in
a dump file. The "print profiling" command will print the accumulated CPU
cycles so far for each type of expression. The times are inclusive of any
child functions or procedures. An example, from mound.fe after running
"gogo": 
 
Enter command: print profiling 
Inclusive profiling counts: 
                      Name            CPU Cycles 
                              re           1,952,792 
                            gogo         125,201,889 
                           gogo2                   0 
                           gogo3                   0 
                           gogo4                   0 
                           gogo5                   0 
 
Constraint expressions 
                    Constraint  Formula Cycles   Energy Cycles  Content Cycles 
                             1         877,047       2,337,727               0 

Note that hard-coded evaluations of area, volume, etc. do not show up
here, except for their effect on overall elapsed time. 

The command reset_profiling will set all the cycle values back to 0. 

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


<-------------------------- procedure definition -------------------------->

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.


<---------------------------- proj_knot_energy ---------------------------->

Named method. Description: This energy is due to Gregory Buck. It tries to
eliminate the need for a normalization term by projecting the energy to the
normal to the curve. Its form is

   E_{e_1e_2} = {L_1L_2 \cos^p\theta\over |x_1 - x_2|^p}

where x_1,x_2 are the midpoints of the edges and \theta is the angle
between the normal plane of edge e_1 and the vector x_1 - x_2. The default
power is 2. Power law of potential is adjustable via the global parameter
`knot_power'. 

Element: edge. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

  parameter knot_power  2     // the default
  quantity knotten energy method proj_knot_energy global


<---------------------------- ps_bareedgewidth ---------------------------->

Internal read-write variable for width of bare edges in PostScript output.
The linewidth of PostScript edges may be controlled by the user. Widths
are relative to the image size, which is 3 units square. If the real-valued
edge extra attribute ps_linewidth is defined, that value is used as the
edge width. Otherwise some internal read-write variables are consulted for
various types of edges, in order:
 ps_stringwidth - edges in the string model, default 0.004
 ps_bareedgewidth - "bare" edges, no adjacent facets, default 0.005
 ps_fixededgewidth - "fixed" edges, default 0.004
 ps_conedgewidth - edges on constraints or boundaries, default 0.004
 ps_tripleedgewidth - edges with three or more adjacent facets, default
0.003
 ps_gridedgewidth - other edges, default 0.002


<------------------------------ ps_cmykflag ------------------------------>

Evolver toggle command. When on, the postscript command will use CMYK
colors instead of RGB in the file it creates. 


<------------------------------ ps_colorflag ------------------------------>
<------------------------------ pscolorflag ------------------------------->

Evolver toggle command. When on, the postscript command will do color.

<---------------------------- ps_conedgewidth ----------------------------->

Internal read-write variable for width of constraint edges in PostScript output.
The linewidth of PostScript edges may be controlled by the user. Widths
are relative to the image size, which is 3 units square. If the real-valued
edge extra attribute ps_linewidth is defined, that value is used as the
edge width. Otherwise some internal read-write variables are consulted for
various types of edges, in order:
 ps_stringwidth - edges in the string model, default 0.004
 ps_bareedgewidth - "bare" edges, no adjacent facets, default 0.005
 ps_fixededgewidth - "fixed" edges, default 0.004
 ps_conedgewidth - edges on constraints or boundaries, default 0.004
 ps_tripleedgewidth - edges with three or more adjacent facets, default
0.003
 ps_gridedgewidth - other edges, default 0.002

<--------------------------- ps_fixededgewidth ---------------------------->

Internal read-write variable for width of fixed edges in PostScript output.
The linewidth of PostScript edges may be controlled by the user. Widths
are relative to the image size, which is 3 units square. If the real-valued
edge extra attribute ps_linewidth is defined, that value is used as the
edge width. Otherwise some internal read-write variables are consulted for
various types of edges, in order:
 ps_stringwidth - edges in the string model, default 0.004
 ps_bareedgewidth - "bare" edges, no adjacent facets, default 0.005
 ps_fixededgewidth - "fixed" edges, default 0.004
 ps_conedgewidth - edges on constraints or boundaries, default 0.004
 ps_tripleedgewidth - edges with three or more adjacent facets, default
0.003
 ps_gridedgewidth - other edges, default 0.002


<---------------------------- ps_gridedgewidth ---------------------------->

Internal read-write variable for width of ordinary edges in PostScript output.
The linewidth of PostScript edges may be controlled by the user. Widths
are relative to the image size, which is 3 units square. If the real-valued
edge extra attribute ps_linewidth is defined, that value is used as the
edge width. Otherwise some internal read-write variables are consulted for
various types of edges, in order:
 ps_stringwidth - edges in the string model, default 0.004
 ps_bareedgewidth - "bare" edges, no adjacent facets, default 0.005
 ps_fixededgewidth - "fixed" edges, default 0.004
 ps_conedgewidth - edges on constraints or boundaries, default 0.004
 ps_tripleedgewidth - edges with three or more adjacent facets, default
0.003
 ps_gridedgewidth - other edges, default 0.002


<------------------------------ ps_labelflag ------------------------------>

Evolver toggle command. When on, the postscript command will print element
labels in the postscript file. Synonym for labelflag.

<------------------------------ ps_labelsize ------------------------------>

Internal read-write variable for the relative size of element labels
in PostScript output. Default value is 3.0, for historical reasons.


<------------------------------ ps_linewidth ------------------------------>

Edge extra attribute that if defined is used as the edge thickness
in PostScript graphics.  Value is relative to image size; values
around 0.003 are reasonable.

<----------------------------- ps_stringwidth ----------------------------->

Internal read-write variable for width of string model edges in
PostScript output. Default value 0.004.

<--------------------------- ps_tripleedgewidth --------------------------->

Internal read-write variable for width of triple edges in PostScript output.
The linewidth of PostScript edges may be controlled by the user. Widths
are relative to the image size, which is 3 units square. If the real-valued
edge extra attribute ps_linewidth is defined, that value is used as the
edge width. Otherwise some internal read-write variables are consulted for
various types of edges, in order:
 ps_stringwidth - edges in the string model, default 0.004
 ps_bareedgewidth - "bare" edges, no adjacent facets, default 0.005
 ps_fixededgewidth - "fixed" edges, default 0.004
 ps_conedgewidth - edges on constraints or boundaries, default 0.004
 ps_tripleedgewidth - edges with three or more adjacent facets, default
0.003
 ps_gridedgewidth - other edges, default 0.002


<-------------------------------- p_force --------------------------------->

Read-only attribute of optimizing variables.  This scalar gives the gradient
of energy with respect to the variable, before any corrections for constraints.
Example:
   g
   print height.p_force

<-------------------------------- p_velocity --------------------------------->

Read-only attribute of optimizing variables.  This scalar gives the rate of
change of the optimizing variable with respect to the scale in the "g" step.
Example:
   g
   print height.p_velocity

<----------------------------------- Q ------------------------------------>

Single letter main command. Report current values of user-defined
method instances and named quantities.  If the show_all_quantities toggle
is on, then internal quantities and method instances are also shown.
This is particularly informative if convert_to_quantities has been done
(same as -q command line option), since then internal values such as
constraint integrals are in the form of method instances.


<----------------------------------- q ------------------------------------>

Single letter main command. Syntax:
    q
    q value
Alone, "q" brings up a prompt to enter a new datafile.  At this prompt,
hitting the Enter key will return to the current surface, another "q" will 
exit Evolver, and anything else will be taken to be the name of a new datafile.
When "quit" is followed by a value, Evolver exits immediately, and uses
the value as the exit code, which is useful when running Evolver in a
script or from some other program.  Quitting Evolver automatically closes 
any graphics windows, and does not save anything. Same as "quit" command. 
"quit", "bye", and "exit" are synonyms.

q,x: Graphics mode command. Exit from graphics mode, and return to main
command mode.


<------------------------------- quadratic -------------------------------->

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


<------------------------- quadratic declaration -------------------------->

To declare that the datafile lists a surface in the quadratic model, the
top section of the datafile should contain the line

  QUADRATIC

The only effect on datafile syntax is that the edge section may list edge
midpoint vertices.


<---------------------------- quadratic model ----------------------------->

By default, edges and facets are linear. But it is possible to represent
edges as quadratic curves and facets as quadratic patches by using the
quadratic model. Each edge is endowed with a midpoint vertex. Most features
are implemented for the quadratic representation, but some named quantity
methods are not available, such as those involving curvature.
A special case is circular arc mode, which is effective in quadratic mode
in the string model with the circular_arc_length method used for
length_method_name. Then edges are calculated and drawn as exact circular
arcs through their three vertices.
 The quadratic model can be invoked by putting the QUADRATIC keyword in the
top section of the datafile or by using the quadratic or M 2 commands.

<-------------------------- quadratic_metric_mix -------------------------->

Internal read-write variable. Fraction of linear interpolation in
Hessian metric in the quadratic model. Not very useful.

<---------------------------- quantities_only ----------------------------->

Evolver toggle command. Inactivates all energies except named quantities.
Meant for programmer's debugging use.


<---------------------- quantities_predicted -------------------------->

Datafile keyword in the top section of the datafile that specifies the
initial allocation of named quantity structures.  Optional.  The purpose is 
to prevent repeated reallocation of memory as the quantity list grows.
Not significant if there are only a few quantities,  but there are
times when there can be thousands of quantities, such as when 
"everything_quantities" is used with a large foam. Automatically put in
dump files by the "d" or "dump" commands, based on the current number of 
quantities.  This declaration obviously should come before any quantities
are defined. 
Example:
    vertices_predicted 30748
    edges_predicted    92166
    facets_predicted   61446
    bodies_predicted    2048 
    facetedges_predicted  184320
    method_instances_predicted   4098
    quantities_predicted   2050

<-------------------------------- quantity -------------------------------->

There is a systematic scheme of calculating global quantities such as
area, volume, and surface integrals that supplements and can replace
the original ad hoc scheme in the Evolver. Briefly, a "method" is a built-in
function for calculating a value for a particular type of geometric element,
and a "named quantity" is a combination of instances of methods.
See the ringblob datafile for an example. The original ad hoc calculations
are still the default where they exist, but all new quantities are being
added in the named quantity scheme. Some new features will work only with
named quantities. To convert everything to named quantities, start Evolver
with the -q option or use the convert_to_quantities command. This has not
been made the default since named quantities can be slower than the originals.
The sample datafiles qcube.fe, qmound.fe, and ringblob.fe contains some
examples of named quantities and instances. The first two are quantity
versions of cube.fe and mound.fe. These illustrate the most general and
useful methods, namely facet_vector_integral, facet_scalar_integral, and
edge_vector_integral, rather than the faster but more specialized methods
such as facet_area. My advice is that the user stick to the old implicit
methods for area, volume, and gravitational energy, and use named
quantities only for specialized circumstances.


<--------------------------- quantity attribute --------------------------->

Geometric element read-only attribute. Named quantities and method
instances can be applied to geometric elements either in the datafile (by
adding the quantity or method name to the line defining an element) or with
the "set" command. Nonglobal quantities or methods can be unset for
individual elements. The values for individual elements can be accessed
using attribute syntax. Examples: Suppose there is a named quantity
"xmoment" that can be evaluated for facets. Then one could give commands

   foreach facet do printf "%g %f\n",id,xmoment
   list facet where xmoment > 4
   set facet quantity xmoment where original == 1
   unset facet quantity xmoment


<---------------------- quantity Lagrange multiplier ---------------------->
<--------------------------- quantity pressure ---------------------------->

Each "fixed" quantity has a Lagrange multiplier associated to it. The
Lagrange multiplier of a constraint is the rate of energy change with
respect to the constraint target value. For a volume constraint, the
Lagrange multiplier is just the pressure. Lagrange multipliers are
calculated whenever an iteration step is done. They may be displayed with
the v command in the "pressure" column, or as an expression
"quantityname.pressure".


<---------------------------- quantity modulus ---------------------------->

Each quantity has a "modulus", which is just a scalar multiplier for the
sum of all instance values. A modulus of 0 will turn off calculation of all
the instances. The modulus can be set in the datafile declaration, or by 
assignment:
   quantityname.modulus := 1.2


<---------------------------- quantity target ----------------------------->

Each "fixed" quantity has a target value, to which the Evolver attempts to
constraint the quantity value. Each time an iteration is done ( g command
or the various Hessian commands), Newton's Method is used to project the
surface to the constrained values. The target value can be displayed with
the A or v commands, or as "quantityname.target". It can be changed by 
assignment. Example:
  print qname.target
  qname.target := 3.12


<--------------------------- quantity tolerance --------------------------->

A fixed quantity can have a tolerance attribute, which is used to judge
convergence. A surface is deemed converged when the sum of all ratios of
quantity discrepancies to tolerances is less than 1. This sum also includes
bodies of fixed volume. If the tolerance is not set or is negative, the
value of the variable target_tolerance is used, which has a default value
of 0.0001.   The sample datafile column.fe contains some examples of named
quantities and instances.


<----------------------------- quantity value ----------------------------->

The value of a namee quantity may be displayed with the A or v commands, or as
an expression "quantityname.value". Furthermore, using the quantity name as
an element attribute evaluates to the sum of all the applicable component
instance values on that element. For example, supposing there is a quantity
named vol, one could do
  print vol.value
  print facet[2].vol
  histogram(facet,vol)


<--------------------------- quantity volconst ---------------------------->

 A quantity can have a constant value added to it, similar to the body
attribute volconst. This quantity attribute is also called volconst. It is
useful for adding in known values of say integrals that are omitted from
the actual calculation. It can be set in the quantity's datafile
definition, or by an assignment command.

<-------------------------- quarter_turn_period --------------------------->

User-defined variable used by the quarter_turn symmetry group.
See "quarter_turn" for more.

<------------------------------ quarter_turn ------------------------------>

Symmetry group.  3D torus with quarter turn in identification of top 
and bottom. x and y periods taken to be 1. z period is the user-defined 
variable quarter_turn_period.  Generators x,y,z. x and y as in regular 
torus mode. z is vertical translation with quarter turn: (x,y,z)->(-y,x,z).
Relations: x z = z y^-1,   y z = z x
Numerical representation: as in torus, for powers of x,y,z
with generators applied in that order.

<--------------------------------- quiet ---------------------------------->

Evolver toggle command. Suppresses all normal output messages
automatically generated by commands. Good while running scripts, or for
loading datafiles with long read sections. Explicit output from print,
printf, and list commands will still appear, as will prompts for user
input. Applies to redirected output as well as console output. An error or
user interrupting a command (i.e. with CTRL-C) will turn QUIET off, for
sanity.

<-------------------------------- quietgo --------------------------------->

Evolver toggle command. Suppresses g iteration step output, but permits
other messages.


<------------------------------- quietload -------------------------------->

Evolver toggle command. Suppresses echoing of files being read in. This
applies to the read section at the end of the datafile and any files read
in with the read command. This toggle does not get reset at the start of a
new datafile. This toggle can be set with the -Q command line option, to
suppress echoing in the first datafile loaded. Default is OFF.


<---------------------------- quietload option ---------------------------->
<--------------------------------- option --------------------------------->

Command line option -Q : Suppresses echoing of read section of datafile,
and of files input with the read command; same as quietload toggle.


<---------------------------- quotient spaces ----------------------------->

Symmetry groups and quotient spaces.
As a generalization of the torus model, you may declare the domain to be
the quotient space of R^n with respect to some symmetry group. Several
built-in groups are available, and ambitious users can compile C code into
Evolver to define group operations. Group elements are represented by
integers attached to edges (like the wrap specifications in the torus model
at runtime). You define the integer representation of the group elements.
See the file quotient.c for an example. See khyp.c and khyp.fe for a more
intricate example modelling an octagon in Klein hyperbolic space identified
into a genus 2 surface.

The datafile requires the keyword SYMMETRY_GROUP followed by the name for
the group in quotes. Edges that wrap have their group element specified in
the datafile by the phrase "wrap n", where n is the number of the group
element. The wrap values are accessible at run time with the wrap attribute
of edges. The group operations are accessible by the functions
wrap_inverse(w) and wrap_compose( w1,w2).

Using any Hessian commands with any symmetry group (other than the
built-in torus model) will cause automatic converting to named quantities
(with the " convert_to_quantities" command, since only named quantity
Hessian evaluation routines have the proper symmetry transformation of the
Hessian programmed in.

Volumes of bodies might not be calculated correctly with a symmetry group.
The volume calculation only knows about the built-in torus model. For other
symmetry groups, if you declare a body, it will use the Euclidean volume
calculation. It is up to you to design an alternate volume calculation
using named quantities and methods.

The currently implemented symmetry groups are:
   torus - The underlying group for the torus model.
   rotate - Cyclic group of rotations in the x-y plane.
   flip_rotate - Cyclic group of rotations in the x-y plane with z -> -z
         with every odd rotation.
   cubocta - Full point group of a cube.
   xyz - The orientation-preserving subgroup of cubocta.
   genus2 - For a 2 dimensional genus 2 hyperbolic quotient space.
   dodecahedron - For a 3D hyperbolic quotient space with dodecahedral
         fundamental region.
   central_symmetry - Inversion through the origin, X -> -X.
   screw_symmetry - Screw motion along z axis.


<----------------------------------- r ------------------------------------>

Single letter main command. Refines the triangulation. Edges are divided
in two, and facets are divided into four facets with inherited attributes.
Reports the number of element structures and amount of memory used by those
structures.  Edges and facets with the no_refine attribute set are not
refined.

Graphics mode command. Rotate right. Rotates about vertical axis,
default 6 degrees.  Integer prefix indicates how many 6 degree rotations
to do, and decimal prefix indicates angle of rotation.
Examples: `15r' does 90 degree rotation, `15.0r' does 15 degree rotation.


<----------------------------------- R ------------------------------------>

Graphics mode command. Reset viewing angles to original defaults and
rescale the image to fit the viewing window.

<--------------------------------- random --------------------------------->

Internal read-only variable. Random number between 0 and 1 that is
different every time the variable is evaluated.  Assign a value to
the random_seed variable to initialize the random number generator
to a known state.

<------------------------------ random_seed ------------------------------->

Internal read-write variable. Seed for random number generator, used when
the "random" variable is evaluated, in jiggling, and in finding random initial
vectors in various Hessian eigenvector algorithms. Defaults to 1 at start
of datafile.  Assigning a value to random_seed initializes the random
number generator to a known state.

<------------------------------- raw_cells -------------------------------->

Evolver toggle command. Sets torus model display for plain, unwrapped
facets. Not an on-off toggle; 3-way toggle with "clipped" and "connected".
Default is unset, so Evolver prompts the user when graphics are first 
displayed.  The setting persists when loading a new surface.  But loading 
a torus model when a non-torus model is currently displayed will not prompt.


<--------------------------- raw_vertex_average --------------------------->

Main prompt command. Does vertex averaging on selected vertices without
conserving volume on each side of surface, as vertex_average does. Will
only average vertices with those of like type of constraints. Doesn't
move vertices on boundaries.  See "rawest_vertex_average" for averaging
without any restrictions.  Having the "verbose" toggle on will print
messages. Syntax:

  RAW_VERTEX_AVERAGE generator

Example:

  raw_vertex_average vertex where valence == 6

<------------------------- 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.  See "vertex_average"
and "raw_vertex_average" for more restricted averaging. Having the "verbose"
toggle on will print messages. Syntax:

   RAWEST_VERTEX_AVERAGE generator

Example:

   rawest_vertex_average vertex[3]

<-------------------------------- 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. See "V" and "rawv" for more
restricted averaging.


<---------------------------------- 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.  See also "V"
and "rawestv".

<------------------------------ raw_velocity ------------------------------>

Internal vertex read-only attribute used when one-sided level-set constraints
are present, so the Lagrange multipliers for said constraints can be 
calculated.  This is the velocity before any projection to volume or 
level-set constraints.  Not of interest to the ordinary user.

<---------------------------------- 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.  Echoing of input may be
suppressed with the "quietload" toggle. Example:
   read "zebra.cmd"

<------------------------------ read section ------------------------------>

The final section of the datafile may contain commands. These commands are
read and executed immediately, just as if they had been entered at the
command prompt. Encountering the keyword READ in the datafile causes the
Evolver to switch from datafile mode to command mode and read the rest of
the datafile as command input. This feature is useful for automatic
initialization of the surface with refining, iteration, defining your own
commands, etc. The READ section is optional. Example:

  bodies
  1   1 2 3 4 5 6 volume 1

  read

  // automatically do this when datafile is loaded
  refine edge where on_constraint 1

  // typical evolution
  gogo := { g 5; r; g 10; r; g 20 }

The "list bottominfo" command prints the READ section that would be printed
in a dump file.

<---------------------------------- real ---------------------------------->

Possible type for user-defined variables, arrays, functions, and
extra attributes.  Example declarations, which work both in the top
of the datafile and at runtime:

  define george real
  define my_array real[3][4]
  define edge attribute charlie real
  define vertex attribute newx real[3]
  define facet attribute knots real[5][5][5]
  define edge attribute bbb real function { self.bbb := self.x+self.y }

<------------------------ reasonable scale factor ------------------------->

Trouble in evolving is usually signaled by a small scale, which means
there is some obstacle to evolution. Of course, that means you have to know
what a reasonable scale is, and that depends on the type of energy you are
using and how refined your surface si. In normal evolution, the size of the
scale is set by the development of small-scale roughness in the surface.
Combined with a little dimensional analysis, that leads to the conclusion
that the scale should vary as L^2-q, where L is the typical edge length and
the units of energy are length^q. The dimensional analysis goes like this:
Let D be the perturbation of one vertex away from an equilibrium surface.
In general, energy is quadratic around an equibrium, so

  E = D^2L^q-2

So the gradient of energy at the vertex is

  grad E = 2 D L^q-2

The motion is the scale times the gradient, which we want proportional to D, so

 scale * grad E = scale * 2 D L^q-2 = D

So scale is on the order of L ^2-q.
Some examples of dimensional dependence of scale factor:
 Energy                    Energy dimension      Scale            Example file
 Area of soapfilm                L^2              L^0                quad.fe
 Length of string                L^1              L^1              flower.fe
 String squared curvature        L^-1             L^3            elastic8.fe
 Surface squared mean curvature  L^0              L^2              sqcube.fe
In particular, the scale for area evolution is independent of refinement,
but for most other energies the scale decreases with refinement.
Another common influence on the scale for area evolution is the surface
tension. Doing a liquid solder simulation in a system of units where the
surface tension of facets is assigned a value 470, say, means that all
calculated gradients are multiplied by 470, so the scale decreases by a
factor of 470 to get the same geometric motion. Thus you should set
scale_limit to be the inverse of the surface tension.


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


<------------------------------ redefinition ------------------------------>

Single letter redefinition:
It is possible to reassign a single letter to your own command by the
syntax

 letter :::= command

but this should only be used in special circumstances, such as redefining
'r' to do additional actions along with refinement. The standard meaning
can be restored with a null assignment:

 letter :::=

Use single quotes around the letter to get the standard meaning, i.e. 'r'
will do a standard refine when r has been redefined. Redefinitions are
cleared when a new surface is loaded. Be careful when using redefined
commands in defining other commands. Redefinition is effective on execution
of the redefinition command, not on parsing. Redefinition is not
retroactive to uses in previously defined commands, but restoring the
standard meaning is retroactive. Examples:

   V :::= { fix vertex[5]; 'V'; unfix vertex[5] }
   r :::= { divisions := divisions * 2;
            hooke_length := hooke_length/2; 'r' }


<------------------------------ redirection ------------------------------->

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

To overwrite a possibly existing file, the output of a command can be 
redirected with the symbol '>>>'. Syntax:

   command >>> stringexpr

Redirection with just `>' is not available due to the use of `>' as an
comparison operator.

Standard redirection does not apply to error messages, including 
output done with "errprintf", on the assumption that the user wants
them visible on the screen while a script runs.  However, error
messages can be redirected using ">>2" and ">>>2".  The "2" comes
from the fact that in popular operating systems the standard
error output is internally file number 2.  Redirection of error
messages could be useful for example in saving the output of the
"C" or "chack" commands.

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.

Examples:

   { {g 10; u } 20 } >> "logfile"
   printf "Step: %d  Energy: %f\n",step,total_energy >> "output.txt"
   list facets | "more"


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


<------------------------------ refine_count ------------------------------>

Internal read-only variable. Number of elements refined in
last refine command.   Prints and resets to 0 at the end of a command
execution, or when flush_counts is done. Also reset by reset_counts.

<---------------------------- relaxed_elastic ----------------------------->
<---------------------------- relaxed_elastic1 ---------------------------->
<---------------------------- relaxed_elastic2 ---------------------------->

Named method. Description: A variation of the linear_elastic method.
Calculates the linear elastic strain energy energy for facets based on the
Cauchy-Green strain matrix, with compression counting for zero energy,
simulating, say, plastic film. The effect is to permit wrinkling. Let S be
Gram matrix of unstrained facet (dots of sides). Let Q be the inverse of S.
Let F be Gram matrix of strained facet. Let C = (FQ-I)/2, the Cauchy-Green
strain tensor. Let v be Poisson ratio. Then energy density is

   (1/2/(1+v))(Tr(C^2) + v*(Tr C)^2/(1-(dim-1)*v))

Each facet has extra attribute poisson_ratio and each vertex has two extra
coordinates, the coordinates of the unstrained surface in a plane. Hence
the surface must be set up as five dimensional. The compression is detected
by doing an eigenvalue analysis of the strain tensor, and discarding any
negative eigenvalues. The eigenvalues may be separately accessed by the
relaxed_elastic1 (lower eigenvalue) and relaxed_elastic2 (higher
eigenvalue) methods, which are meant to be used in info_only mode. For a
sample datafile, see mylarcube.fe.  There can also be a real-valued facet 
extra attribute LEBweight, which can be used to give a per-facet weighting 
of the energy.  For a version of relaxed elastic energy using only three 
ambient dimensions but an additional facet form_factor array facet attribute, 
see relaxed_elastic_A.

Element: facet. 
Parameters: none. 
Models: linear. 
Ambient dimension: 5.
Hessian: yes. 
Example datafile declaration:

  space_dimension 5
  quantity lastic energy method relaxed_elastic global
  quantity lastic_lo info_only method relaxed_elastic1 global
  quantity lastic_hi info_only method relaxed_elastic2 global

<--------------------------- relaxed_elastic_A ---------------------------->
<--------------------------- relaxed_elastic1_A --------------------------->
<--------------------------- relaxed_elastic2_A --------------------------->

Named method. Description: Calculates the linear elastic strain energy
energy for facets based on the Cauchy-Green strain matrix, with compression
counting for zero energy, simulating, say, plastic film. The effect is to
permit wrinkling. Let S be the Gram matrix of unstrained facet (dots of
sides). Let Q be the inverse of S. Let F be Gram matrix of strained facet.
Let C = (FQ-I)/2, the Cauchy-Green strain tensor. Let v be Poisson ratio.
Then the energy is

 (1/2/(1+v))(Tr(C^2) + v*(Tr C)^2/(1-(dim-1)*v))

Each facet has extra attribute poisson_ratio and extra attribute array
form_factors[3] = {s11,s12,s22}, which are the entries in S. That is, s11 =
dot(v2-v1,v2-v1), s12 = dot(v2-v1,v3-v1), and s22 = dot(v3-v1,v3-v1). If
form_factor is not defined by the user, it will be created by Evolver, and
the initial facet shape will be assumed to be unstrained. The compression
is detected by doing an eigenvalue analysis of the strain tensor, and
discarding any negative eigenvalues. Facets which are stressed in one or
two dimensions can be separately counted by the relaxed_elastic1_A (one
stress direction, and one wrinkle direction) and relaxed_elastic2_A (two
stressed directions) methods, which are meant to be used in info_only mode.
There can also be a real-valued facet extra attribute LEBweight, which 
can be used to give a per-facet weighting of the energy.  

For a sample datafile, see mylarcube.fe.  For a version of relaxed elastic
energy that uses two extra ambient dimensions instead of form_factors,
see relaxed_elastic.  For a version of this method that
gives compression positive energy, see linear_elastic.

Element: facet.
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: yes.
Example datafile declaration:

   quantity lastic energy method relaxed_elastic_A global


<------------------------------ 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!  Also see reorder_storage.

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


<------------------------------ repartition ------------------------------->

Main prompt command. In the MPI version of Evolver, this command
re-distributes the elements of the surface according to the task 
numbers set in respective element attributes that are declared thus: 
 
           define vertex attribute v_newpart integer[2] 
           define edge   attribute e_newpart integer[2] 
           define facet  attribute f_newpart integer[2] 
           define facetedge attribute fe_newpart integer[2] 
           define body  attribute b_newpart integer[2] 
  
Probably a good idea just to include the above lines in any MPI Evolver
datafile. The user sets the first component of each; the second is for
internal use. For example, assuming you have Metis linked into your 
Evolver:

mpi_equalize := { 
  // set new partition numbers 
  metis mpi_maxtask; 
  parallel_exec "set vertex v_newpart[1] vpart+1"; 
  parallel_exec "set edge e_newpart[1] epart+1"; 
  parallel_exec "set facet f_newpart[1] fpart+1"; 
  parallel_exec "set body b_newpart[1] 0"; 
  parallel_exec "set facetedge fe fe_newpart[1] fe.facet[1].fpart";  
  repartition; 
}  

<------------------------------ replace_load --------------------------------->

Main prompt command.
Replaces the current surface with a new surface from a datafile without a 
total re-initialization.  Syntax:
   replace_load  filename
where filename is a double-quoted string or a string variable.  The
replace_load command actually dissolves all the elements of the current
surface and then does the addload command to read in the desired datafile.
Thus only the top section and the elements of the new file are read in;
the "read" section of the new datafile is not read.   All variables,
constraints, quantities, and commands from the original file are remembered,
although they may be re-initialized in the top of the new datafile.  This
command can be used in loops to repeatedly evolve a surface under different
conditions, for example
    run := { printf "Height     Energy\n" >>> "results.txt";
             for ( htvar := 1.0 ; htvar <= 2.0 ; htvar += 0.1 )
             { replace_load datafilename;
               height := htvar;
               gogo;
               printf "%f     %f\n",height,total_energy >> "results.txt";
             }
           }
It is necessary that htvar NOT appear in the top of the datafile, so that
it does not get re-initialized when replace_load is done.  You can set the 
no_dump property of a variable to prevent it from being dumped in the
top of the datafile; it will be dumped in the bottom section instead.
Example (as commands, not in the top of the datafile):
  htvar := 2.3
  htvar.no_dump on

Replace_load is meant as a replacement for permload, which I have never 
been able to get to work right.
 
<------------------------------ 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,
 > 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.

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


<-------------------------- reverse_orientation --------------------------->

Main prompt command. For reversing the orientation of sets of edges or
facets. Syntax:

   REVERSE_ORIENTATION generator

Reverses the internal orientation of selected edges or facets, as if they
had been entered in the datafile with the opposite orientation. Useful, for
example, when edges come in contact with a constraint and you want to get
them all oriented in the same direction. Relative orientations of
constraint and quantity integrals change to compensate, so energy, volumes,
etc. should be the same after the command, but it would be wise to check in
your application. Examples:

   reverse_orientation edge[7]
   reverse_orientation facets where backbody != 0

Note that this is different from setting the "orientation" attribute of
an element.  Doing reverse_orientation of an element will also reverse
the "orientation" attribute, so oriented integrals are the same before
and after.  So beware that after reverse_orientation, oriented quantities 
may not change as you expect.  It may be necessary to remove edges or 
facets from constraints or quantities, reverse them, declare their 
orientation positive, and re-apply constraints and quantities.

<------------------------------- rgb_colors ------------------------------->

Evolver toggle command. Toggles graphics to use user-specified
red-green-blue components of color for elements rather than the "color"
attribute indexing the pre-defined 16-color palette. The individual element
rgb values are in element extra attributes: ergb for edges, frgb for
facets, and fbrgb for facet backcolor. It is up to the user to define these
attributes; if they are not defined, then they are not used and do not take
up space. If frgb is defined but not fbrgb, then frgb is used for both
front and back color. The attributes are type real of dimension 3 or 4; if 4
dimensional, the fourth component is passed to the graphics system as the
alpha value, but probably won't have any effect. The value range is 0 to 1.
Be sure to initialize the rgb attributes, or else you will get an all-black
surface. The attribute definitions to use are:

   define edge attribute ergb real[3]
   define facet attribute frgb real[3]
   define facet attribute fbrgb real[3]

<-------------------------------- ribiere --------------------------------->

Evolver toggle command. Makes the conjugate gradient method use the
Polak-Ribiere version instead of Fletcher-Reeves. (The toggle doesn't turn
on conjugate gradient.) Polak-Ribiere seems to recover much better from
stalling. Ribiere is the default mode.


<--------------------------- Riemannian metric ---------------------------->

The ambient space can be endowed with a general Riemannian metric by
putting the keyword METRIC in the datafile followed by the elements of the
metric tensor. Only one coordinate patch is allowed, but the quotient space
feature makes this quite flexible. Edges and facets are linear in
coordinates, they are not geodesic. The metric is used solely to calculate
lengths and areas. It is not used for volume. To get a volume constraint on
a body, you will have to define your own named quantity constraint. See
quadm.fe for an example of a metric.   Syntax:

METRIC
expr expr expr
expr expr expr
expr expr expr

<-------------------------------- ringblob -------------------------------->

Example: Ring around rotating rod

This example consists of a ring of liquid forming a torus around a rod
rotating along its long axis (z axis) in weightlessness. The liquid has
controllable contact angle with the rod. The interesting question is the
stability of the ring as the spin increases.

The effect of the rotation is incorporated in the energy through an
integral using the Divergence Theorem:

        ///
  E = - ||| (1/2) p r^2 w^2 dV
        ///B  


        //
    = - ||       (1/2) p w^2 (x^2+y^2) z k . dA
        //bdry B

where B is the region of the liquid, r is radius from the axis, p is the
fluid density and w is the angular velocity. Note the energy is negative,
because spin makes the liquid want to move outward. This has to be
countered by surface tension forces holding the liquid on the rod. If p is
negative, then one has a toroidal bubble in a rotating liquid, and high
spin stabilizes the torus. The spin energy is put in the datafile using the
named quantity syntax (see below). "centrip" is a user-chosen name for the
quantity, "energy" declares that this quantity is part of the total energy,
"global_method" says that the following method is to be applied to the
whole surface, "facet_vector_integral" is the pre-defined name of the
method that integrates vector fields over facets, and "vector_integrand"
introduces the components of the vectorfield.

The rod surface is defined to be constraint 1 with equation x^2 + y^2 =
R^2, where R is the radius of the rod. The contact energy of the liquid
with the rod is taken care of with an edge integral over the edges where
the liquid surface meets the rod:

      //                          /                  /
  E = || -T cos(a) dA = -T cos(a) |  z ds = T cos(a) | (z/R)(yi - xj).ds
      //S                         /bdry S            / bdry S

Here S is the rod surface not included as facets in bdry B, T is the
surface tension of the free surface, and a is the internal contact angle. A
more intuitive way to arrive at this integral is to think in cylindrical
coordinates and imagine the replaced surface of the rod between the contact
line and z = 0 to be divided into thin vertical strips of height z and
width R dtheta. The energy of a strip is -T cos(a) z R dtheta. Converting
back to Cartesian coordinates, dtheta = (x dy - y dx)/(x^2 + y^2), so

                 //                                   //
  E =  -T cos(a) || z R (x dy - y dx)/R^2 = -T cos(a) || (z/R)(x dy - y dx)
                 //                                   //


Constraint 2 is a horizontal symmetry plane. By assuming symmetry, we only
have to do half the work.

Constraint 3 is a one-sided constraint that keeps the liquid outside the
rod. Merely having boundary edges on the rod with constraint 1 is not
enough in case the contact angle is near 180 degrees and the liquid volume
is large. Constraint 3 may be put on any vertices, edges, or faces likely
to try to invade the rod. However, it should be noted that if you put
constraint 3 on only some vertices and edges, equiangulation will be
prevented between facets having different constraints.
 Constraint 4 is a device to keep the vertices on the rod surface evenly
spaced. Edges on curved constraints often tend to become very uneven, since
long edges short-cutting the curve can save energy. Hence the need for a
way to keep the vertices evenly spread circumferentially, but free to move
vertically. One way to do that is with another constraint with level sets
being vertical planes through the z axis at evenly spaced angles.
Constraint 4 uses the real modulus function with arctangent to create a
periodic constraint. Each refinement, the parameters need to be halved to
cut the period in half. This is done by redefining the "r" refinement
command at the end of the datafile. Note that autorecalc is temporarily
turned off to prevent projecting vertices to the constraint when it is in
an invalid state. Also note the pi/6 offset to avoid the discontinuity in
the modulus function. pi/6 was cleverly chosen so that all refinements
would also avoid the discontinuity.

One way of detecting stability is to perturb the torus and seeing if it
evolves back to equilibrium. The datafile defines a command

    perturb := set vertex y y+.01 where not on_constraint 1

This sets the y coordinate of each vertex to y+.01. This command is
defined in the "read" section at the end of the datafile, where you can put
whatever commands you want to execute immediately after the datafile is
loaded. To detect small perturbations, and get numerical values for the
size of perturbations, the y moment of the liquid is calculated in the
named quantity "ymoment". It is not part of the energy, as indicated by the
info_only keyword. You can see the value with the `v' command.

A better way to check stability is to examine the eigenvalues of the
Hessian matrix. First, evolve normally to reasonably near an equilibrium.
Then use the hessian command several times to converge exactly to the
equilibrium. Then use the command "ritz(0,5)" to display the 5 eigenvalues
of the Hessian nearest 0. By gradually raising the spin and tracking the
lowest eigenvalue, one can detect the onset of instability, where the
lowest eigenvalue becomes 0. Note that the datafile toggles on
hessian_normal so that the Hessian only considers perturbations normal to
the surface.

The initial ringblob skeleton, with vertices and edges numbered. Taking
advantage of symmetry, just the top half is represented.



// ringblob.fe

// Toroidal liquid ring on a rotating rod in weightlessness.
// Half of full torus
// Using second periodic constraint surface intersecting rod to
// confine vertices on rod to vertical motion.

// Important note to user: Use only the 'rr' command defined at
// the end of this file to do refinement.  This is due to the
// nature of constraint 4 below.

// This permits drawing both halves of the ring
view_transforms 1
1 0 0 0
0 1 0 0
0 0 -1 0
0 0 0 1

// Basic parameters.  These may be adjusted at runtime with the
// 'A' command.  Only spin is being adjusted in these experiments.
parameter rodr = 1  // rod radius
parameter spin = 0.0 // angular velocity
parameter angle = 30 // internal contact angle with rod
parameter tens = 1   // surface tension of free surface
#define rode (-tens*cos(angle*pi/180))  // liquid-rod contact energy
parameter dens = 1  // density of liquid, negative for bubble

// spin centripetal energy
quantity centrip energy global_method facet_vector_integral
vector_integrand:
q1: 0
q2: 0
q3: -0.5*dens*spin*spin*(x^2+y^2)*z

// y moment, for detecting instability
quantity ymoment info_only global_method facet_vector_integral
vector_integrand:
q1: 0
q2: 0
q3: y*z

// Constraint for vertices and edges confined to rod surface,
// with integral for blob area on rod
constraint 1
formula: x^2 + y^2 = rodr^2
energy:
e1: -rode*z*y/rodr
e2: rode*z*x/rodr
e3: 0

// Horizontal symmetry plane
constraint 2
formula: z = 0

// Rod surface as one-sided constraint, to keep stuff from caving in
// Can be added to vertices, edges, facets that try to cave in
constraint 3 nonnegative
formula: x^2 + y^2 = rodr^2

// Constraint to force vertices on rod to move only vertically.
// Expressed in periodic form, so one constraint fits arbitrarily
// many vertices. Note offset to pi/6 to avoid difficulties with
// modulus discontinuity at 0.
parameter pp = pi/2    /* to be halved each refinement */
parameter qq = pi/6    /* to be halved each refinement */
constraint 4
formula:  (atan2(y,x)+pi/6) % pp = qq

//initial dimensions
#define ht 2
#define wd 3

vertices
1  0   -wd 0  constraints 2    // equatorial vertices
2  wd    0 0  constraints 2
3  0    wd 0  constraints 2
4  -wd   0 0  constraint 2
5  0   -wd ht                 // upper outer corners
6  wd    0 ht
7  0    wd ht
8  -wd   0 ht
9  0 -rodr ht constraints 1,4   // vertices on rod
10 rodr  0 ht constraints 1,4
11 0  rodr ht constraints 1,4
12 -rodr  0 ht constraints 1,4

edges
1   1 2 constraint 2  // equatorial edges
2   2 3 constraint 2
3   3 4 constraint 2
4   4 1 constraint 2
5   5 6               // upper outer edges
6   6 7
7   7 8
8   8 5
9   9  10 constraint 1,4   // edges on rod
10  10 11 constraint 1,4
11  11 12 constraint 1,4
12  12  9 constraint 1,4
13   1  5        // vertical outer edges
14   2  6
15   3  7
16   4  8
17   5  9        // cutting up top face
18   6 10
19   7 11
20   8 12

faces  /* given by oriented edge loop */
1   1 14 -5 -13 tension tens // side faces
2   2 15 -6 -14 tension tens  // Remember you can't change facet tension
3   3 16 -7 -15 tension tens  // dynamically just by changing tens; you have
4   4 13 -8 -16 tension tens  // to do "tens := 2; set facet tension tens"
5   5 18 -9 -17 tension tens  // top faces
6   6 19 -10 -18 tension tens
7   7 20 -11 -19 tension tens
8   8 17 -12 -20 tension tens

bodies  /* one body, defined by its oriented faces */
1   1 2 3 4 5 6 7 8  volume 25.28

read  // some initializations
transforms off     // just show fundamental region to start with

// special refinement command redefinition
r :::= { autorecalc off;  pp := pp/2; qq := qq % pp; 'r'; autorecalc on; }

// a slight perturbation, to check stability
perturb := set vertex y y+.01 where not on_constraint 1

hessian_normal // to make Hessian well-behaved
linear_metric  // to normalize eigenvalues


<---------------------------------- 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. 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. The first eigenvalue is subsequently available
in the last_eigenvalue internal variable. The full list of eigenvalues
produced is subsequently available in the eigenvalues[] array. Example: To
get the lowest 5 eigenvalues of a Hessian you know is positive definite:

   ritz(0,5)

<--------------------------------- rotate --------------------------------->

See "graphics commands". Or "rotate symmetry group".

<-------------------------- rotate_lights --------------------------------->

Evolver toggle command.  When ON, this makes the lights rotate with the
object in the graphics display.  Default OFF.

<------------------------- rotate symmetry group -------------------------->

This is the cyclic symmetry group of rotations in the x-y plane, where the
order of the group is given by the internal variable rotation_order (default
value 4). There is also an internal variable generator_power (default 1)
such that the angle of rotation is 2*pi*generator_power/rotation_order.

Note:
Since this group has fixed points, some special precautions are necessary.
Vertices on the rotation axis must be labelled with the attribute
axial_point in the datafile. Edges out of an axial point must have the
axial point at their tail, and must have zero wrap. Facets including an
axial point must have the axial point at the tail of the first edge in the
facet.
Example datafile declaration:
  symmetry_group "rotate"
  parameter rotate_order = 6

Group element encoding: An element is encoded as the power of the group
generator.


<----------------------------- rotation_order ----------------------------->

Internal read-write variable. Order of rotation group for
symmetry groups rotate and flip_rotate.

<------------------------------ runge_kutta ------------------------------->

Evolver toggle command. Use Runge-Kutta method in a g iteration step
(fixed scale factor only).

<----------------------------------- s ------------------------------------>

Single letter main command. Shows the surface with screen graphics. Goes
into the graphics command mode. Torus model surfaces have display options
you will be asked for the first time. The graphics window may be closed
with the close_show command.

Graphics mode command. Shrink. Contracts image by factor, default 1.2.
arrow keys : Graphics mode command. Move image in appropriate direction.
May be prefixed by a real number, which is multiple of thirds of screen
width to move. Default move is 1/12 screen width. May not work on all
terminals.


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


<---------------------------- scalar_integrand ---------------------------->

One of the possible types of supplementary information needed for
named methods such as vertex_scalar_integral, edge_scalar_integral,
facet_scalar_integral, edge_general_integral, and facet_general_integral.
The syntax consists of appending a scalar_integrand definition to
a quantity or method declaration. Example:

   quantity facet_weight energy method facet_scalar_integral
   scalar_integrand:  G*rho*z

<--------------------------------- scale ---------------------------------->

Internal read-write variable. Current scale factor for multiplying
the vertex velocity to get the motion in the 'g' command.

<------------------------------ scale factor ------------------------------>

In the 'g' command, once a direction of motion is found, the direction
must be multiplied by a scale factor to compute the actual motion. If
one interprets the direction of motion as a velocity (as in motion by
mean curvature), then the scale factor becomes a time step. The scale
factor may be fixed with the "m" command, or it may be in "optimizing"
mode. The default is to start in optimizing mode.  Set scale_limit
to set an upper bound on the scale factor.

<------------------------------ scale_limit ------------------------------->

To set an upper bound of valueon the gradient descent scale factor,
include the line

   SCALE_LIMIT value

in the top section of the datafile. The upper bound can be changed at
runtime with the m command, or by setting the scale_limit variable. If
surface tension is the main energy, the scale_limit should be set to the
inverse of the surface tension.


<------------------------------ scale_scale ------------------------------->

Internal read-write variable. Multiplier for the scale factor used in
the 'g' command.  Useful in optimizing scale mode if you only want to
move a fraction of the optimum scale for better linearity, or force
greater than optimum motion in hopes of accelerated convergence.
Default value 1.

<---------------------------- screen graphics ----------------------------->

The Surface Evolver has the ability to produce its own screen graphics
directly. The Windows version has nice OpenGL/GLUT graphics, which should
also be available on any Unix/Linux/Mac OSX system. The Mac OS 9 version
has some simple graphics, and there is a primitive X-windows graphics
module for Unix/Linux systems that for some reason can't do OpenGL. Those
compiling unix versions must link in the appropriate graphics module.

Screen graphics appear in their own window but can be controlled by typing
graphics commands at the "graphics command: " prompt in the main window.
OpenGL graphics can also be controlled by mouse and keyboard actions in the
graphics window.

Main prompt commands relevant to screen graphics:
  "s" or "show" for starting screen graphics and entering graphics command mode
  "close_show" for ending screen graphics
  "D" or "autodisplay" for toggling automatic redraw when the surface changes.
         Default is automatic redraw.
  "transform_expr" for showing multiple transforms of a surface.
  "show edges" and "show facets" for showing subsets of elements.

The native screen graphics view is controlled by a view transformation
matrix, which may be specified in the datafile, and which is dumped by the
d or list topinfo commands. The view matrix may be changed with graphics
mode commands. The view matrix elements may be read or set at runtime by
view_matrix[i][j], where the indices start at 1. In particular, one can
write command scripts to save and reload particular view matrices; see
saveview.cmd in the distribution package. The view matrix does not affect
geomview.

The display consists entirely of facets and edges. Special edges (fixed
edges, boundary edges, constraint edges, triple edges, bare edges) are
always shown, unless you make their color CLEAR. The individual facet edges
can be toggled with the graphics mode command `e'.

<------------------------------ screw_height ------------------------------>

Internal variable used by the screw_symmetry symmetry group.  
See "screw_symmetry".

<------------------------------ screw_angle ------------------------------->

Internal variable used by the screw_symmetry symmetry group.  
See "screw_symmetry".

<----------------------------- screw_symmetry ----------------------------->

This is the symmetry group of screw motions along the z axis. The global
parameter screw_height is the translation distance (default 1), and the
global parameter screw_angle is the rotation angle in degrees (default 0).
Datafile declaration:

  parameter screw_height = 4.0
  parameter screw_angle  = 180.0
  symmetry_group "screw_symmetry"

Group element encoding: the integer value is the power of the group
generator.


<---------------------------- scrollbuffersize ---------------------------->

Internal read-write variable. The command window scroll buffer size
on Windows machines. Meant for non-NT Windows that don't have
menu properties option for this.

<---------------------------------- self ---------------------------------->

Name of parent element in extra attribute functions.
Example declaration:
  define edge attribute bbb real function { self.bbb := self.x+self.y }

<------------------------------ self_similar ------------------------------>

Evolver toggle command. If squared mean curvature energy is being used,
this scales the velocity toward a self-similar motion.   Applies only
when the old top-of-datafile "squared_curvature" declaration is used,
or the sqcurve named method. The global read-write variable self_sim_coeff 
is used as a multiplier.

<----------------------------- self_sim_coeff ----------------------------->

Global read-write variable used as magnitude coefficent when
self_similar is toggled on.

<------------------------------ septum_flag ------------------------------->

Evolver toggle command.  Under some circumstances, popping a vertex 
can leave two regions connected by a tunnel; if the septum_flag toggle 
is on, it will force a  surface to be placed across the tunnel.

<---------------------------------- set ----------------------------------->

Main prompt command. For setting element attributes to values and other
miscellaneous things. Syntax:

 SET elementtype [name] attrib expr1 where expr2
 SET elementtype attrib expr1 where expr2
 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
form 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
 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".


<-------------------------------- shading --------------------------------->

Evolver toggle command. Toggles facet shading in certain graphics
interfaces (xgraph, psgraph). Darkness of facet depends on angle of normal
from vertical, simulating a light source above surface. Default is ON.


<--------------------------------- 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.  Used alone, it starts the native graphics display
and changes to graphics command mode (use "showq" to start graphics without
changing to graphics command mode).  Also, 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 internally: 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

As an edge or facet attribute, "show" is a Boolean read-only
attribute giving the current status of the edge or facet, for
example, to report the number of edges being shown, do

   print sum(edge,show)

<-------------------------- show_all_edges --------------------------->

Evolver toggle command. Controls the showing of all edges in the graphics
window, regardless of the current "show edges ..." condition.  Same as
the 'e' key in the graphics window.

<-------------------------- show_all_quantities --------------------------->

Evolver toggle command. By default, only explicitly user-defined named
quantities are shown by the Q or v commands. If show_all_quantities is on,
then all internal quantities created by the command line option -q or by
doing convert_to_quantities are also shown.

<--------------------------- show_bounding_box ---------------------------->

Evolver toggle command.  Controls showing the bounding box in graphics.
Corresponds to the "o" key in the graphics window and the "b" command
at the graphics prompt.  Its advantage is that it lets a script set
the bounding box state to a definite value.

<------------------------------- 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 for edges or facets.
Good for use in the "read" section of the datafile for controlling which
elements will be displayed without automatically starting a display.
Examples:
 show_expr facets where color == red
 show_expr edges where 1
 show_expr edges where color != black

<------------------------------- show_inner ------------------------------->

Evolver toggle command. Display interior facets, those on 2 bodies.

<-------------------------------- show_off -------------------------------->

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


<------------------------------- show_outer ------------------------------->

Evolver toggle command. Display outer facets, those on 0 or 1 body.

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

<-------------------------------- show_vol -------------------------------->

Main prompt command. Synonym for 'v'.  Shows target volume, actual volume, and
pressure of each body. Also shows named quantities. Pressures are really
the Lagrange multipliers. Pressures are computed before an iteration, so
the reported values are essentially are one iteration behind.

<--------------------------------- showq ---------------------------------->

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

<--------------------------------- shrink --------------------------------->

Graphics mode command 's'. Shrink. Contracts image by factor, default 1.2.
arrow keys : Graphics mode command. Move image in appropriate direction.
May be prefixed by a real number, which is multiple of thirds of screen
width to move. Default move is 1/12 screen width. May not work on all
terminals.

<---------------------- simon_knot_energy_normalizer ---------------------->

Named method. Description: Another normalization of edge_knot_energy,
which I don't feel like deciphering right now. 

Element: edge. 
Parameters: none. 
Models: string linear. 
Ambient dimension: 3.
Hessian: no. 
Example datafile declaration:

   quantity kenergy energy method edge_knotenergy global
                           method simon_knot_energy_normalizer global

<-------------------------- simplex declaration --------------------------->

To declare that the datafile lists a surface in the simplex model, the top
section ot the datafile should contain the line

  SIMPLEX_REPRESENTATION

The main effect on the datafile is that faces are defined by oriented
vertex lists rather than edge lists.

<----------------------------- simplex model ------------------------------>

The simplex model enables the representation of arbitrary dimension
surfaces, but many Evolver features are not available with it. Here each
facet is represented as an oriented list of k+1 vertices, where k is the
dimension of the surface. Edges may be specified as k-1 dimensional
simplices, but they are used only to compute constraint and named quantity
integrals; a complete list of edges is not needed. Bodies are specified as
lists of oriented facets.

The datafile must have the keyword SIMPLEX_REPRESENTATION in the top
section, and the phrase 'SURFACE_DIMENSION k' if k isn't 2. k = 1 and k = 2
are allowed, but not very useful in comparison to the string or soapfilm
models. If the domain is not 3-dimensional, then 'SPACE_DIMENSION n' must
also be included. The datafile edges section is optional. Each facet should
list k+1 vertex numbers. Non-simplicial facets are not allowed. See the
sample datafile simplex3.fe.

Most features are not implemented. The quadratic model is not allowed, but
the Lagrange model is. Vertices may be FIXED. Constraints are allowed, with
energy integrands. Several basic named quantity methods work. No torus
model or symmetry groups. No changing of surface topology or combinatorics
is allowed except global refining with the r command. Refining subdivides
each simplex 1-edge, with the edge midpoint inheriting the common
attributes of the edge endpoints. Refining will increase the number of
facets by a factor of 2^k.

<----------------------- simplex_k_vector_integral ------------------------>

Named method. Description: Integral of a simple (n-k)-vector over an
oriented k-dimensional simplicial facet in n-space. The vector integrand
lists the components of each of the k vectors sequentially. Evaluation is
done by forming a determinant whose first k rows are k vectors spanning the
facet, and last (n-k) rows are vectors of the integrand. 

Element: facet.
Parameters: k_vector_order, vector_integrand. 
Models: simplex; linear. 
Ambient dimension: any. 
Hessian: yes. 
Orientable: yes. 
Example datafile declaration, for 3D surface in 5D:

   quantity kvec energy method simplex_k_vector_integral
   k_vector_order 3
   vector_integrand:
   q1: 0   // first vector
   q2: 0
   q3: 0
   q4: 0
   q5: x4
   q6: 0   // second vector
   q7: 0
   q8: 0
   q9: x3
   q10: 0


<------------------------- simplex_representation ------------------------->

Internal read-only variable. Whether the simplex model is in effect.

<----------------------------- simplex_to_fe ------------------------------>

Main prompt command. Converts a simplex model surface to a string or
soapfilm model surface. Only works for dimension 1 or 2 surfaces, but works
in any ambient dimension. 
 
<------------------------ simplex_vector_integral ------------------------->

Named method. Description: Integral of a vectorfield over a
(n-1)-dimensional simplicial facet in n-space. Vectorfield is dotted with
normal of facet; actually the side vectors of the simplex and the integrand
vector are formed into a determinant. 

Element: facet. 
Parameters: vector_integrand. 
Models: simplex; linear. 
Ambient dimension: any. 
Hessian: no.
Orientable: yes. 
Example datafile declaration, for 4-volume under a 3D surface in 4D:

   quantity xvint energy method simplex_vector_integral
   vector_integrand:
   q1: 0
   q2: 0
   q3: 0
   q4: x4

<---------------------------------- sin ----------------------------------->

sin(x),cos(x),tan(x): Trig functions, argument in radians.

<---------------------------- sin_knot_energy ----------------------------->

Named method. Description: Another weird way to calculate a nonsingular
energy between midpoints of pairs of edges. (by John Sullivan) 

Element: edge. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity knotten energy method sin_knot_energy global


<----------------------------- single letter ------------------------------>

Single letter main commands

The oldest and most commonly used Surface Evolver commands are just single
letters. Case is significant for these. Single letters are always
interpreted as commands, so you may not use single letters for variable
names. Single letter commands may be redefined.

 Single letter commands may be summarized in five groups:
   Reporting:
     C Run consistency checks.
     c Report count of elements.
     e Extrapolate.
     i Information on status.
     v Report volumes.
     v List extra attributes.
     z Do curvature test.
   Model characteristics:
     A Display and set variables and various parameters.
     a Toggle area normalization
     b Set body pressures.
     f Set diffusion constant.
     G Set gravity.
     J Toggle jiggling on every move.
     k Set boundary gap constant.
     M Toggle linear/quadratic model.
     m Toggle fixed motion scale.
     p Set ambient pressure.
     Q Report or set quantities.
     U Toggle conjugate gradient method.
     W Homothety toggle.
   Surface modification
     g Go one iteration step. Often followed by a repetition count.
     j Jiggle once.
     K Skinny triangle long edge divide.
     l Subdivide long edges.
     N Set target volumes to actual.
     n Notch ridges and valleys.
     O Pop non-minimal edges.
     o Pop non-minimal vertices.
     r Refine triangulation.
     t Remove tiny edges.
     u Equiangulate.
     V Vertex averaging.
     w Weed out small triangles.
     y Torus duplication.
     Z Zoom in on vertex.
   Output:
     D Toggle display every iteration.
     d Dump surface to datafile.
     P Graphics output (geomview, Postscript, etc.).
     s Screen display (native graphics).
   Miscellaneous:
     F Toggle command logging.
     H,h,? Help screen.
     q,x Exit.


<---------------------------------- sinh ---------------------------------->

 sinh(x),cosh(x),tanh(x): Hyperbolic functions.

<--------------------------------- sizeof --------------------------------->

Returns the number of entries in an array or array extra attribute. Can
also be applied to a string or string variable to get the number of
characters in the string. Syntax:

  SIZEOF(name)
  SIZEOF(string)

where in the first form, name is the name of the array or extra attribute, 
not in quotes.
Example:
  Enter command: define aa real[3][4]
  Enter command: print sizeof(aa)
                    12
  Enter command: print sizeof(datafilename)
                     6

<------------------------------ slice_coeff ------------------------------->

Internal vector used by slice_view command.  See "slice_view".

<------------------------------- slice_view ------------------------------->

Main prompt command that toggles displaying a cross-section
of the surface. The slice is defined by a plane of the form 
ax + by + cz = d. The coefficients a,b,c,d are stored in the array 
slice_coeff[] (which the user does not have to create). To use 
slice_view, first set the coefficients and then use the slice_view 
toggle. For example, to get a vertical slice parallel to the x
and y axes and a little in front of them: 
 
   slice_coeff[1] := 1; 
   slice_coeff[2] := 0; 
   slice_coeff[3] := 0; 
   slice_coeff[4] ;= .2; 
   slice_view; 

Evolver initializes slice_coeff[] with a vertical plane through
the middle of the surface, so you can do just "slice_view".
The cross-section will be in the form of line segments of the same color
as the facets they are sections of. With OpenGL graphics, the slice plane
can be varied interactively by hitting the 'l' key (lower case 'L')
in the graphics window and dragging the mouse horizontally.  The 'k' key
will make mouse dragging change the orientation of the slice plane.
Hit 'r' or  'c' or 't' to get back to another mouse mode.  The 'L' key
will end slice_view.
 
Slice view works separately, and after, torus model viewing modes such as
clipped and connected, so it is no problem to have them together. 
In case slice_view and clip_view are both in effect, slice_view operates
instead of clip_view. 
 

<------------------------------ smooth_graph ------------------------------>

Evolver toggle command.
In string quadratic and Lagrange model, causes edges to be plotted with
many subdivisions for smooth look. In soapfilm Lagrange model, causes edges
and facets to be plotted with 8-fold subdivision rather than Lagrange order
subdivision. Is not implemented in quadratic soapfilm model. Default off.


<-------------------------------- soapfilm -------------------------------->

The default dimension of the surface is 2. If not, it must be declared in
the top section of the datafile. For a 1-dimensional surface (the string
model), simply include the line
 STRING
The default dimension 2 soapfilm model is equivalent to using
 SOAPFILM
In general, the line
 SURFACE_DIMENSION n
defines the surface to have dimension n. Dimension over 2 is valid only in
the simplex model. The surface dimension may be accessed at runtime through
the read-only variable surface_dimension.


<----------------------------- soapfilm model ----------------------------->

The term "soapfilm model" means that the dimension of the surface is 2.
This is the default model. The surface is subdivided into triangular
facets, and the default energy is surface area. Edges are defined by their
vertices. Facets are defined by an oriented list of three edges, which must
form a closed loop. However, faces in the datafile may have more than three
edges, since they are automatically refined into facets when loaded. In
official Evolver-speak, a "face" is what appears in the datafile, and a
"facet" is the triangle in the internal Evolver representation of the
surface. Bodies are defined by a set of oriented facets, which need not
form the complete boundary of the body, for example if part of the boundary
is on a constraint.

Internally, the surface is held together by a set of structures called
"facet-edges". There is one such structure for each incidence of an edge on
a facet. There is a doubly linked list of facet-edges around each facet, so
edges can be traversed in order, and there is a doubly-linked list around
each edge, so the facets around an edge can be traversed in geometric
order. Evolver figures out the geometric order from the geometric data in
the datafile. If geometric order does not make sense, as when the space
dimension is 4 or more, then the order is random.

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

<------------------------------ sobolev_seek ------------------------------>

Main prompt command.  Does a variable-step energy-minimizing search along
teh sobolev direction; see "sobolev".

<------------------------------ sobolev_area ------------------------------>

Named method. Description: Same as the facet_tension method, but the
Hessian is modified to be guaranteed positive definite, after the scheme of
Renka and Neuberger. [RN]. Hence the hessian command always works, but
final convergence may be slow (no faster than regular iteration) since it
is only an approximate Hessian. Also see the sobolev command.

Element: facet. 
Parameters: none. 
Models: linear. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

   quantity sobarea energy method sobolev_area global

<------------------------------ sobolev_mode ------------------------------>

Evolver toggle command. When the facet_area method is being used to
calculate areas in hessian commands, this toggles using an approximate
facet_area hessian that is positive definite. This permits hessian
iteration to make big steps in a far-from-minimal surface without fear of
blowing up. However, since it is only an approximate hessian, final
convergence to the minimum can be slow. Linear model only. Does
convert_to_quantities implicitly. Another variant of this is triggered by
dirichlet_mode.

<---------------------------- space dimension ----------------------------->

By default, surfaces live in 3 dimensional space. However, the phrase
"SPACE_DIMENSION n" in the datafile header sets the dimension to n. This
means that all coordinates and vectors have n components. The only
restriction is that Evolver has to be compiled with the MAXCOORD macro
defined to be at least n in Makefile or in model.h. The default MAXCOORD is 4. 
Change MAXCOORD and recompile if you want more than four dimensions. The
actual space dimension can be accessed in commands through the read-only
variable space_dimension.

Graphics will display only the first three dimensions of spaces with more
than three dimensions, except for geomview, which has a four-dimensional
viewer built in (although its use is awkward now).

<---------------------- space dimension declaration ----------------------->

The default dimension of space is 3. Otherwise it must be declared in the
top section of the datafile, with syntax

  SPACE_DIMENSION n

The dimension must be at most the value of MAXCOORD in model.h, which is 4
in the distributed version. The space dimension may be accessed at runtime
through the read-only variable space_dimension.


<---------------------------- space_dimension ----------------------------->

Internal read-only variable. Dimension of ambient space.  Can only be set
in the top section of the datafile with the syntax

    space_dimension n

Default is dimension 3.


<--------------------------- sparse_constraints --------------------------->

Evolver toggle command. Toggles using sparse matrix techniques to
accumulate and handle body and quantity gradients in iteration and hessian
commands. Now the default.

<--------------------------- surface_cos_power ---------------------------->

Internal variable used by sphere_knot_energy method.  See sphere_knot_energy
for details.

<--------------------------- sphere_knot_energy --------------------------->

Named method. Description: This is the 2D surface version of the circle
energy. Its most general form is

  E_{f_1f_2} = { A_1A_2(1 - \cos\alpha)^p \over |x_1 - x_2|^q},

where A_1,A_2 are the facet areas, x_1,x_2 are the barycenters of the
facets, and \alpha is the angle between f_1 and the sphere through x_1
tangent to f2 at x_2. The energy is conformally invariant for p = 1 and q =
4. For p=0 and q=1, one gets electrostatic energy for a uniform charge
density. Note that facet self-energies are not included. For electrostatic
energy, this is approximately 2.8A^{3/2} per facet.

The powers p and q are Evolver variables surface_knot_power and
surface_cos_power respectively. The defaults are p=1 and q=4. 

Element: facet. Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   parameter surface_knot_power  1     // the default
   parameter surface_cos_power  4     // the default
   quantity knotten energy method sphere_knot_energy global


<-------------------------- spherical_arc_area_n -------------------------->

Named method. Description: Area on a sphere between an edge (considered as
a great circle arc) and the north (or south) pole. This is an exact
calculation in the linear model. Meant for calculating the areas of facets
in the string model with the string network confined to a sphere of
arbitrary radius centered at the origin. There are two versions of this
method, since calculation of facet areas by means of edges necessarily has
a singularity somewhere on the sphere. Spherical_arc_area_n has its
singularity at the south pole, and spherical_arc_area_s has its singularity
at the north pole. Thus spherical_arc_area_s will work accurately for
facets not including the north pole in there interiors; a facet including
the north pole will have its area calculated as the negative complement of
its true area, so a body defined using it could get the correct area by
using a volconst of a whole sphere area. If the singular pole falls on an
edge or vertex, then results are unpredictable. With these caveats, these
methods are suitable for use with the area_method_name feature for
substituting the default edge area method. If you do a facet as an explicit
quantity, you are responsible for applying or unapplying the quantity after
topology changes!! 

Element: edge. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Orientable: yes. 
Hessian: yes. 
Example datafile declaration:

   parameter rad = 2
   constraint 1
   formula: x^2 + y^2 + z^2 = rad^2
   area_method_name "spherical_arc_area_n"

<-------------------------- spherical_arc_area_s -------------------------->

Named method. Description: Area on a sphere between an edge (considered as
a great circle arc) and the north (or south) pole. This is an exact
calculation in the linear model. Meant for calculating the areas of facets
in the string model with the string network confined to a sphere of
arbitrary radius centered at the origin. There are two versions of this
method, since calculation of facet areas by means of edges necessarily has
a singularity somewhere on the sphere. Spherical_arc_area_n has its
singularity at the south pole, and spherical_arc_area_s has its singularity
at the north pole. Thus spherical_arc_area_s will work accurately for
facets not including the north pole in there interiors; a facet including
the north pole will have its area calculated as the negative complement of
its true area, so a body defined using it could get the correct area by
using a volconst of a whole sphere area. If the singular pole falls on an
edge or vertex, then results are unpredictable. With these caveats, these
methods are suitable for use with the area_method_name feature for
substituting the default edge area method. If you do a facet as an explicit
quantity, you are responsible for applying or unapplying the quantity after
topology changes!! 

Element: edge. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Orientable: yes. 
Hessian: yes. 
Example datafile declaration:

   parameter rad = 2
   constraint 1
   formula: x^2 + y^2 + z^2 = rad^2
   area_method_name "spherical_arc_area_s"

<-------------------------- spherical_arc_length -------------------------->

Named method. Description: Edge length, modelling the edge as a spherical
great circle arc between its two endpoints, which are assumed to lie on an
arbitrary radius sphere centered at the origin. This method is meant for
modelling string networks on spheres, and is suitable for use with the
length_method_name feature for substituting the default edge length
calculation method. Note that this method is an exact spherical calculation
in the linear model, so there is no need to refine edges or use higher
order models for accuracy. Edges are graphed as spherical arcs (actually,
lots of segments). 

Element: edge. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: yes. 
Example datafile declaration:

   parameter rad = 2
   constraint 1
   formula: x^2 + y^2 + z^2 = rad^2
   length_method_name "spherical_arc_length"


<----------------------------- spherical_area ----------------------------->

Named method. Description: Area of the facet projected to unit sphere. The
vertices of the facet are assumed to be on the unit sphere. 

Element: facet.
Parameters: none. 
Models: linear. 
Ambient dimension: any. 
Hessian: no.
Example datafile declaration:

   constraint 1  formula: x^2 + y^2 + z^2 = 1
   quantity spharea energy method spherical_area global


<------------------------- spinning ring example -------------------------->

Example: Ring around rotating rod

This example consists of a ring of liquid forming a torus around a rod
rotating along its long axis (z axis) in weightlessness. The liquid has
controllable contact angle with the rod. The interesting question is the
stability of the ring as the spin increases.

The effect of the rotation is incorporated in the energy through an
integral using the Divergence Theorem:

        ///
  E = - ||| (1/2) p r^2 w^2 dV
        ///B  

        //
    = - ||       (1/2) p w^2 (x^2+y^2) z k . dA
        //bdry B

where B is the region of the liquid, r is radius from the axis, p is the
fluid density and w is the angular velocity. Note the energy is negative,
because spin makes the liquid want to move outward. This has to be
countered by surface tension forces holding the liquid on the rod. If p is
negative, then one has a toroidal bubble in a rotating liquid, and high
spin stabilizes the torus. The spin energy is put in the datafile using the
named quantity syntax (see below). "centrip" is a user-chosen name for the
quantity, "energy" declares that this quantity is part of the total energy,
"global_method" says that the following method is to be applied to the
whole surface, "facet_vector_integral" is the pre-defined name of the
method that integrates vector fields over facets, and "vector_integrand"
introduces the components of the vectorfield.

The rod surface is defined to be constraint 1 with equation x^2 + y^2 =
R^2, where R is the radius of the rod. The contact energy of the liquid
with the rod is taken care of with an edge integral over the edges where
the liquid surface meets the rod:

      //                          /                  /
  E = || -T cos(a) dA = -T cos(a) |  z ds = T cos(a) | (z/R)(yi - xj).ds
      //S                         /bdry S            / bdry S

Here S is the rod surface not included as facets in bdry B, T is the
surface tension of the free surface, and a is the internal contact angle. A
more intuitive way to arrive at this integral is to think in cylindrical
coordinates and imagine the replaced surface of the rod between the contact
line and z = 0 to be divided into thin vertical strips of height z and
width R dtheta. The energy of a strip is -T cos(a) z R dtheta. Converting
back to Cartesian coordinates, dtheta = (x dy - y dx)/(x^2 + y^2), so

                 //                                   //
  E =  -T cos(a) || z R (x dy - y dx)/R^2 = -T cos(a) || (z/R)(x dy - y dx)
                 //                                   //

Constraint 2 is a horizontal symmetry plane. By assuming symmetry, we only
have to do half the work.

Constraint 3 is a one-sided constraint that keeps the liquid outside the
rod. Merely having boundary edges on the rod with constraint 1 is not
enough in case the contact angle is near 180 degrees and the liquid volume
is large. Constraint 3 may be put on any vertices, edges, or faces likely
to try to invade the rod. However, it should be noted that if you put
constraint 3 on only some vertices and edges, equiangulation will be
prevented between facets having different constraints.

Constraint 4 is a device to keep the vertices on the rod surface evenly
spaced. Edges on curved constraints often tend to become very uneven, since
long edges short-cutting the curve can save energy. Hence the need for a
way to keep the vertices evenly spread circumferentially, but free to move
vertically. One way to do that is with another constraint with level sets
being vertical planes through the z axis at evenly spaced angles.
Constraint 4 uses the real modulus function with arctangent to create a
periodic constraint. Each refinement, the parameters need to be halved to
cut the period in half. This is done by redefining the "r" refinement
command at the end of the datafile. Note that autorecalc is temporarily
turned off to prevent projecting vertices to the constraint when it is in
an invalid state. Also note the pi/6 offset to avoid the discontinuity in
the modulus function. pi/6 was cleverly chosen so that all refinements
would also avoid the discontinuity.

One way of detecting stability is to perturb the torus and seeing if it
evolves back to equilibrium. The datafile defines a command

    perturb := set vertex y y+.01 where not on_constraint 1

This sets the y coordinate of each vertex to y+.01. This command is
defined in the "read" section at the end of the datafile, where you can put
whatever commands you want to execute immediately after the datafile is
loaded. To detect small perturbations, and get numerical values for the
size of perturbations, the y moment of the liquid is calculated in the
named quantity "ymoment". It is not part of the energy, as indicated by the
info_only keyword. You can see the value with the `v' command.

A better way to check stability is to examine the eigenvalues of the
Hessian matrix. First, evolve normally to reasonably near an equilibrium.
Then use the hessian command several times to converge exactly to the
equilibrium. Then use the command "ritz(0,5)" to display the 5 eigenvalues
of the Hessian nearest 0. By gradually raising the spin and tracking the
lowest eigenvalue, one can detect the onset of instability, where the
lowest eigenvalue becomes 0. Note that the datafile toggles on
hessian_normal so that the Hessian only considers perturbations normal to
the surface.

The initial ringblob skeleton, with vertices and edges numbered. Taking
advantage of symmetry, just the top half is represented.



// ringblob.fe

// Toroidal liquid ring on a rotating rod in weightlessness.
// Half of full torus
// Using second periodic constraint surface intersecting rod to
// confine vertices on rod to vertical motion.

// Important note to user: Use only the 'rr' command defined at
// the end of this file to do refinement.  This is due to the
// nature of constraint 4 below.

// This permits drawing both halves of the ring
view_transforms 1
1 0 0 0
0 1 0 0
0 0 -1 0
0 0 0 1

// Basic parameters.  These may be adjusted at runtime with the
// 'A' command.  Only spin is being adjusted in these experiments.
parameter rodr = 1  // rod radius
parameter spin = 0.0 // angular velocity
parameter angle = 30 // internal contact angle with rod
parameter tens = 1   // surface tension of free surface
#define rode (-tens*cos(angle*pi/180))  // liquid-rod contact energy
parameter dens = 1  // density of liquid, negative for bubble

// spin centripetal energy
quantity centrip energy global_method facet_vector_integral
vector_integrand:
q1: 0
q2: 0
q3: -0.5*dens*spin*spin*(x^2+y^2)*z

// y moment, for detecting instability
quantity ymoment info_only global_method facet_vector_integral
vector_integrand:
q1: 0
q2: 0
q3: y*z

// Constraint for vertices and edges confined to rod surface,
// with integral for blob area on rod
constraint 1
formula: x^2 + y^2 = rodr^2
energy:
e1: -rode*z*y/rodr
e2: rode*z*x/rodr
e3: 0

// Horizontal symmetry plane
constraint 2
formula: z = 0

// Rod surface as one-sided constraint, to keep stuff from caving in
// Can be added to vertices, edges, facets that try to cave in
constraint 3 nonnegative
formula: x^2 + y^2 = rodr^2

// Expressed in periodic form, so one constraint fits arbitrarily
// many vertices. Note offset to pi/6 to avoid difficulties with
// modulus discontinuity at 0.
parameter pp = pi/2    /* to be halved each refinement */
parameter qq = pi/6    /* to be halved each refinement */
constraint 4
formula:  (atan2(y,x)+pi/6) % pp = qq

//initial dimensions
#define ht 2
#define wd 3

vertices
1  0   -wd 0  constraints 2    // equatorial vertices
2  wd    0 0  constraints 2
3  0    wd 0  constraints 2
4  -wd   0 0  constraint 2
5  0   -wd ht                 // upper outer corners
6  wd    0 ht
7  0    wd ht
8  -wd   0 ht
9  0 -rodr ht constraints 1,4   // vertices on rod
10 rodr  0 ht constraints 1,4
11 0  rodr ht constraints 1,4
12 -rodr  0 ht constraints 1,4

edges
1   1 2 constraint 2  // equatorial edges
2   2 3 constraint 2
3   3 4 constraint 2
4   4 1 constraint 2
5   5 6               // upper outer edges
6   6 7
7   7 8
8   8 5
9   9  10 constraint 1,4   // edges on rod
10  10 11 constraint 1,4
11  11 12 constraint 1,4
12  12  9 constraint 1,4
13   1  5        // vertical outer edges
14   2  6
15   3  7
16   4  8
17   5  9        // cutting up top face
18   6 10
19   7 11
20   8 12

faces  /* given by oriented edge loop */
1   1 14 -5 -13 tension tens // side faces
2   2 15 -6 -14 tension tens  // Remember you can't change facet tension
3   3 16 -7 -15 tension tens  // dynamically just by changing tens; you have
4   4 13 -8 -16 tension tens  // to do "tens := 2; set facet tension tens"
5   5 18 -9 -17 tension tens  // top faces
6   6 19 -10 -18 tension tens
7   7 20 -11 -19 tension tens
8   8 17 -12 -20 tension tens

bodies  /* one body, defined by its oriented faces */
1   1 2 3 4 5 6 7 8  volume 25.28

read  // some initializations
transforms off     // just show fundamental region to start with

// special refinement command redefinition
r :::= { autorecalc off;  pp := pp/2; qq := qq % pp; 'r'; autorecalc on; }

// a slight perturbation, to check stability
perturb := set vertex y y+.01 where not on_constraint 1

hessian_normal // to make Hessian well-behaved
linear_metric  // to normalize eigenvalues

<---------------------------- spring_constant ----------------------------->

See "gap_constant".

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

<--------------------------- sq_gauss_curvature --------------------------->

Named method. Description: Computes the integral of the squared Gaussian
curvature. At each vertex, the Gaussian curvature is calculated as the
angle defect divided by one third of the total area of the adjacent facets.
This is then squared and weighted with one third of the area of the
adjacent facets. This method works only on closed surfaces with no
singularities due to the way it calculates the angle defect. 

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity sqg energy method sq_gauss_curvature global

<-------------------------- sq_gaussian_curv_cyl -------------------------->

Named method. Description: Integral of the squared gaussian curvature of a
surface of revolution. The generating curve is set up in the string model,
and this method applied to its vertices. The axis of rotation is the x-axis.

Element: vertex. 
Models: string; linear. 
Ambient dimension: 2. 
Hessian: yes.
Example datafile declaration: 
 
   quantity sqgausscyl energy method sq_gaussian_curv_cyl global 

<---------------------------- sq_mean_curv_cyl ---------------------------->

Named method. Description: Integral of the squared mean curvature of a
surface of revolution. The generating curve is set up in the string model,
and this method applied to its vertices. The axis of rotation is the x-axis.
This method will do intrinsic curvature by means either of a global
variable h_zero or a real-valued vertex attribute h_zero. 

Element: vertex.
Models: linear string. 
Ambient dimension: 2. 
Hessian: yes. 
Example datafile declaration: 
 
   define vertex attribute h_zero real 
   quantity sqcyl energy method sq_mean_curv_cyl global 

<------------------------------ sq_mean_curv ------------------------------>
<-------------------------------- sqcurve --------------------------------->
Squared mean curvature

Vertex read-only attribute. SQCURVE is the squared mean curvature at a vertex, 
calculated by the same formula as used in the sq_mean_curvature named method.  
In particular, the formula is affected by the normal_curvature toggle, which 
should be on if you want this to be the square of the value reported by the 
mean_curvature attribute.  Also accommodates the h_zero parameter. 


<--------------------------- sq_mean_curvature ---------------------------->

Named method.
Description: Integral of squared mean curvature of a surface. There are
several methods implemented for calculating the integral of the squared
mean curvature of a surface. The older methods sq_mean_curvature,
eff_area_sq_mean_curvature, and normal_sq_mean_curvature, are now
deprecated, since they don't have Hessians and the newer methods
star_sq_mean_curvature, star_eff_area_sq_mean_curvature,
star_normal_sq_mean_curvature, and my current favorite
star_perp_sq_mean_curvature, do have Hessians and can now handle incomplete
facet stars around vertices. But read the following for general remarks on
squared curvature also.

The integral of squared mean curvature in the soapfilm model is calculated
for this method as follows: Each vertex v has a star of facets around it of
area A. The force F due to surface tension on the vertex is the gradient of
area, Since each facet has 3 vertices, the area associated with v is A/3.
Hence the average mean curvature at v is
   h = (1/2)(F/(A/3)),
where the 1/2 factor comes from the "mean" part of "mean curvature". This
vertex's contribution to the total integral is then
E = h^2A/3 = (3/4)F^2/A.

Philosophical note: The squared mean curvature on a triangulated surface
is technically infinite, so some kind of approximation scheme is needed.
The alternative to locating curvature at vertices is to locate it on the
edges, where it really is, and average it over the neighboring facets. But
this has the problem that a least area triangulated surface would have
nonzero squared curvature, whereas in the vertex formulation it would have
zero squared curvature.

Practical note: The above definition of squared mean curvature seems in
practice to be subject to instablities. One is that sharp corners grow
sharper rather than smoothing out. Another is that some facets want to get
very large at the expense of their neighbors. Hence a couple of alternate
definitions have been added.

Curvature at boundary: If the edge of the surface is a free boundary on a
constraint, then the above calculation gives the proper curvature under the
assumption the surface is continued by reflection across the constraint.
This permits symmetric surfaces to be represented by one fundamental
region. If the edge of the surface is a fixed edge or on a 1-dimensional
boundary, then there is no way to calculate the curvature on a boundary
vertex from knowledge of neighboring facets. For example, the rings of
facets around the bases of a catenoid and a spherical cap may be identical.
Therefore curvature is calculated only at interior vertices, and when the
surface integral is done, area along the boundary is assigned to the
nearest interior vertex. However, including IGNORE_FIXED or
IGNORE_CONSTRAINTS in the method declaration will force the calculation of
energy even at fixed points or ignoring constraints respectively.

If the parameter or vertex attribute h_zero is defined, then the value per
vertex is the same as for the following method, eff_area_sq_mean_curvature.

Element: vertex. 
Parameters: IGNORE_CONSTRAINTS, IGNORE_FIXED. 
Models: soapfilm; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

   quantity sqc energy method sq_mean_curvature global

<------------------------------ sq_mean_mix ------------------------------->

User-defined variable used by the mix_sq_mean_curvature method to
determine the combination of mean curvature approximations used.


<----------------------------- sqcurve_string ----------------------------->

Named method. Description: Integral of squared curvature in string model.
Assumes two edges per vertex, so don't use with triple points. Value zero
at endpoint of curve. Calue is calculated as if the exterior angle at the
vertex is evenly spread over the adjacent half-edges. More precisely, if s1
and s2 are the adjacent edge lengths and t is the exterior angle, value =
4*(1 - cos(t))/(s1+s2). Other powers of the curvature can be specified by
using the parameter parameter_1 in the instance definition.  If parameter_1
is not present, then the internal read-write variable curvature_power is
used, which defaults to 2.

Element: vertex. 
Parameters: parameter_1. 
Models: string; linear. 
Ambient dimension: any. 
Hessian: yes (but only for power 2). 
Example datafile declaration:

  quantity sq energy method sqcurve_string global
  parameter_1 3

<-------------------------- sqcurve_string_mark --------------------------->

Edge attribute used by the sqcurve_string_marked method.  
See "sqcurve_string_marked".

<------------------------- sqcurve_string_marked -------------------------->

Named method. Description: Integral of squared curvature in string model.
Same as sqcurve_string, but only "marked" edges are used, so the topology
of edges can be more complicated than a loop or curve. The marking is done
by declaring an integer-valued edge attribute named sqcurve_string_mark and
setting it to the proper bit value pattern for those edges you want to be 
involved, two at each vertex to which this method is applied. Value zero at
vertex with not two marked edges.  Different instances of this method
can use parameter_2 to specify a bit in sqcurve_string_mark to use in case
multiple instances are using overlapping edges.  If parameter_2 is not used,
any nonzero sqcurve_string_mark will activate an edge. 

The method value is calculated as if the exterior angle at the vertex is 
evenly spread over the adjacent half-edges. More precisely, if s1 and s2 
are the adjacent edge lengths and t is the exterior angle, 
value = 4*(1 - cos(t))/(s1+s2). Other powers of the curvature can be
specified by using the parameter parameter_1 in the instance definition.

Element: vertex. 
Parameters: parameter_1: the power of the curvature. 
            parameter_2: power of 2 used to match bit in sqcurve_string_mark
Models: string; linear. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration: 
 
   define edge attribute sqcurve_string_mark integer 
   quantity sqmark energy method sqcurve_string_marked 

<---------------------------- sqcurve2_string ----------------------------->

Named method. Description: Integral of squared curvature in string model,
but with an intrinsic curvature. The intrinsic curvature is specified by a
global variable h_zero, or real-valued vertex attribute named h_zero.

The value zero at endpoint of curve. The value is calculated as if the
exterior angle at the vertex is evenly spread over the adjacent half-edges.
More precisely, if s1 and s2 are the adjacent edge lengths, h0 is the
intrinsic curvature, and t is the exterior angle, then value =
(sin(t)/((s1+s2)/2)-h0)^2.  T

Element: vertex. 
Models: linear. 
Ambient dimension: 2 
Hessian: no. 
Example datafile declaration: 
 
define vertex attribute h_zero real 
quantity sq2 energy method sqcurve2_string global 


<---------------------------- sqcurve3_string ----------------------------->

Named method. Description: Same as sqcurve_string, but uses a slightly
different formula to encourage equal length edges The value zero at
endpoint of curve. The value is calculated as if the exterior angle at the
vertex is evenly spread over the adjacent half-edges. More precisely, if s1
and s2 are the adjacent edge lengths, h0 is the intrinsic curvature, and t
is the exterior angle, value = 2*(1 - cos(t))*(1/s1+1/s2). 

Element: vertex.
Models: string; linear. 
Ambient dimension: any 
Hessian: yes. 
Example datafile declaration: 
 
   quantity sq3 energy method sqcurve3_string global 

<-------------------------------- sqgauss --------------------------------->
<-------------------------- square_gauss_modulus -------------------------->
<----------------------- squared_gaussian_curvature ----------------------->

To add an energy of squared Gaussian curvature, include a line in the top
of the datafile

  SQUARED_GAUSSIAN_CURVATURE modulus

The modulus is a multiplier for the energy, and is available at runtime
in the read-write variable square_gauss_modulus. Synonyms:
square_gaussian_curvature, sqgauss


<---------------------------------- sqr ----------------------------------->

 sqr(x) : Square.

<---------------------------------- sqrt ---------------------------------->

 sqrt(x) : Square root. Argument must be nonnegative.

<---------------------------- sq_torsion ---------------------------->

Named method. Integral of squared torsion for curves.
The torsion is approximated by looking at triples of adjacent
edges; if A,B,C are the edge vectors, then the sin of the angle the
osculating plane twists by (from AxB to BxC) is
       [A,B,C] |B|
  S =  -----------
       |AxB| |BxC|
(This is analogous to t = [T,T',T'']/k^2, where T is the tangent
vector and k is the curvature.  I'm using [A,B,C] as notation for
cross product.)  Then the torsion is

   t = arcsin(S)/|B|
   
and the integral of the square of the torsion is

   t^2 |B| = arcsin(S)^2/|B|

This function assumes the edges in each component are consistently oriented.
Since this method is meant to be used on boundary wires of surfaces, it
uses a "sq_torsion_mark" attribute on edges to tell which edges are to be
included.  Example top of datafile declaration:

  define edge attribute sq_torsion_mark integer
  quantity sqtor energy method sq_torsion

Then mark the edges you want included, for example using quad.fe

edges
1   1  2 constraints 1,2 sq_torsion_mark 1 quantity sqtor
2   2  3 constraints 1,2 sq_torsion_mark 1 quantity sqtor
3   3  4 constraints 1,2 sq_torsion_mark 1 quantity sqtor
4   4  1 constraints 1,2 sq_torsion_mark 1 quantity sqtor

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3.
Hessian: no. 


<---------------------------- square_curvature ---------------------------->

To add an energy of squared mean curvature, include a line in the top of
the datafile

  SQUARED_CURVATURE modulus

The modulus is a multiplier for the energy. This is the original squared
mean curvature energy; later versions are in the squared curvature named
methods.


<----------------------- square_gaussian_curvature ------------------------>

To add an energy of squared Gaussian curvature, include a line in the top
of the datafile

  SQUARED_GAUSSIAN_CURVATURE modulus

The modulus is a multiplier for the energy. Synonyms:
square_gaussian_curvature, sqgauss


<--------------------------- squared_curvature ---------------------------->
<-------------------------- sq_curvature_modulus -------------------------->


To add an energy of squared mean curvature, include a line in the top of
the datafile

  SQUARED_CURVATURE modulus

The modulus is a multiplier for the energy, and is available as a
read-write variable at runtime. This is the original squared mean 
curvature energy; later versions are in the squared curvature named
methods.

In the string model, the internal read-write variable curvature_power
can be used to control the power of the curvature.


<---------------------------- squared_gradient ---------------------------->

Evolver toggle command. In hessian_seek, use minimizing the square of the
gradient of the energy as the objective rather than minimizing the energy.

<------------------------------- stability -------------------------------->

The timestep of a 'g' iteration should not be so large as to amplify
perturbations of the surface. Short wavelength perturbations are most prone
to amplification. This section contains a sketch of the stability
characteristics of the various mobility modes, enough to let the user
relate the maximum timestep to the minimum facet or edge size. Two examples
are discussed: a zigzag string and a nearly flat surface with equilateral
triangulation. Effective area is not included, as it is an insignificant
correction for nearly flat surfaces. The general moral of this section is
that the maximum time step in iteration is limited by the length of the
shortest edge or the area of the smallest facet, except in one case.


<----------------------------- stability_test ----------------------------->

Command to find largest eigenvalue of mobility matrix. Don't really recall
what this was for.

<-------------------- star_eff_area_sq_mean_curvature --------------------->

Named method. Description: Integral of squared mean curvature over a
surface. This is a different implementation of eff_area_sq_mean_curvature,
and it has a Hessian. 

This method no longer requires a complete circle of vertices around a vertex; 
boundary edges are treated as if they are on mirror symmetry planes, which is 
usually true.  Level-set constraints that should not be counted as mirror 
planes should be given the attribute "nonwall" in there declaration in the 
top of the datafile.

The positive orientation of the surface is determined by the positive 
orientation of the first facet of the vertex's internal facet list. This 
method does not use the h_zero parameter.

The curvature calculation works in any dimension space. If for some reason
the space has an ambient dimension greater than 3, and you want to restrict
the calculation of curvature to the first three coordinates, the toggle
"calculate_in_3d" will do that.

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

  quantity seffsq energy method star_eff_area_sq_mean_curvature global

<----------------------------- star_finagling ----------------------------->

Toggle. In the soapfilm model, the delete command for edges or facets normally
will not do the deletion if it would result in the creation of two edges
with the same endpoints.  Some simple configurations that cause this are
detected and handled automatically, namely a "star" configuration in
which there are three facets forming a triangle adjacent to the edge
being deleted.  Such a star is automatically removed by deleting one of
its internal edges before deleting the original edge.  But sometimes
there are more complicated configurations that such unstarring won't
handle, and then Evolver will not delete the edge unless the force_deletion 
toggle is on.  An alternative is to first refine the edges that would have 
the common endpoints, and this is what the star_finagling toggle enables.  
Default off.


<-------------------------- star_gauss_curvature -------------------------->

Named method. Computes the angle deficit around vertices to which this
method is applied. The angle deficit is 2*pi minus the sum of all the
adjacent angles of facets. No compensation is made for vertices on the
boundary of a surface; you just get big deficits there. Deficits are
counted as positive, following the convention for gaussian curvature.

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: no. 
Example datafile declaration:

 quantity total_deficit energy method star_gauss_curvature global

<--------------------- star_normal_sq_mean_curvature ---------------------->

Named method. Description: Integral of squared mean curvature over a
surface. This is a different implementation of normal_sq_mean_curvature
which is more suitable for parallel calculation and has a Hessian. 

This method no longer requires a complete circle of vertices around a vertex; 
boundary edges are treated as if they are on mirror symmetry planes, which is 
usually true.  Level-set constraints that should not be counted as mirror 
planes should be given the attribute "nonwall" in there declaration in the 
top of the datafile.

The positive orientation of the surface is determined by the positive 
orientation of the first facet of the vertex's internal facet
list. This method can use the h_zero parameter or vertex attribute for
prescribed mean curvature.

The curvature calculation works in any dimension space. If for some reason
the space has an ambient dimension greater than 3, and you want to restrict
the calculation of curvature to the first three coordinates, the toggle
"calculate_in_3d" will do that.

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

 quantity stnsq energy method star_normal_sq_mean_curvature global

<---------------------- star_perp_sq_mean_curvature ----------------------->

Named method. Description: Integral of squared mean curvature over a
surface. This is my current favorite implementation of squared mean
curvature. It is an implementation specifically designed to agree with the
mean curvature computed as the gradient of area when normal motion is on
(either the normal_motion toggle for 'g' iteration, or Hessian with
hessian_normal). Thus if you get zero squared mean curvature with this
method, then switch to area energy, the hessian will report exact
convergence. Likewise if you do prescribed curvature and then convert to
area minimization with a volume constraint. This method has a Hessian. This
method does not require a complete circle of vertices around a vertex;
boundary edges are treated as if they are on mirror symmetry planes, which
is usually true. This method can use the h_zero parameter or vertex
attribute for prescribed mean curvature. The actual formula for the energy
at a vertex is

  h = (1/2)(F dot N/N dot N)

  E = (h-h_0)^2 A/3 = (3/4)(F dot N/N dot N - 2h_0)^2A

where F is the area gradient at the vertex, N is the volume gradient, and
A is the area of the adjacent facets. If the vertex is on one or several
constraints, the F and N are projected to the constraints, essentially
making the constraints act as mirror symmetry planes.

This method no longer requires a complete circle of vertices around a vertex; 
boundary edges are treated as if they are on mirror symmetry planes, which is 
usually true.  Level-set constraints that should not be counted as mirror 
planes should be given the attribute "nonwall" in there declaration in the 
top of the datafile.

The positive orientation of the surface is determined by the positive 
orientation of the first facet of the vertex's internal facet
list. This method can use the h_zero parameter or vertex attribute for
prescribed mean curvature.

The curvature calculation works in any dimension space. If for some reason
the space has an ambient dimension greater than 3, and you want to restrict
the calculation of curvature to the first three coordinates, the toggle
"calculate_in_3d" will do that.

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

  quantity stnsq energy method star_perp_sq_mean_curvature global

<------------------------- star_sq_mean_curvature ------------------------->

Named method. Description: Integral of squared mean curvature over a
surface. This is a different implementation of sq_mean_curvature, and it
has a Hessian. 

This method no longer requires a complete circle of vertices around a vertex; 
boundary edges are treated as if they are on mirror symmetry planes, which is 
usually true.  Level-set constraints that should not be counted as mirror 
planes should be given the attribute "nonwall" in there declaration in the 
top of the datafile.

The positive orientation of the surface is determined by the positive 
orientation of the first facet of the vertex's internal facet
list. 

This method does NOT do prescribed mean curvature with the h_zero parameter.

Element: vertex. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: any.
Hessian: yes. 
Example datafile declaration:

  quantity starsq energy method star_sq_mean_curvature global


<-------------------------------- stokes2d -------------------------------->
<------------------------------ stokes_type ------------------------------->
<---------------------------- stokes_velocity ----------------------------->

stokes2d
Named method. Description: Square of the Laplacian of z viewed as a
function of (x,y). Meant for the calculation of two-dimensional Stokes flow
of a fluid (i.e. slow steady-state flow where inertia is not significant)
by having the Evolver surface be the graph of the velocity potential and
minimizing the viscous dissipation, which is the square of the Laplacian of
z. Boundary conditions are handled by declaring a vertex attribute
"stokes_type" of type integer, and assigning each boundary vertex one of
these values:
   0 - vertex is not on a wall; treat as if on a mirror symmetry plane.
   1 - vertex is on a slip wall.
   2 = vertex is on a nonslip wall; normal derivative of potential is zero.

Boundary values of z should be set to constants between 0 and 1 on various
sections of boundary that represent walls. 

Element: vertex. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: yes. 
Example datafile declaration:

   quantity dissip energy method stokes2d global

Note: Evolver creates a vertex attribute stokes_velocity for internal use.

<--------------------------- stokes2d_laplacian --------------------------->

Named method. Description: The Laplacian of z viewed as a function of
(x,y). This is auxiliary to the stokes2d method. It is the same Laplacian,
unsquared, with the same boundary rules. Meant for calculating pressures
and such after stokes2d energy has been minimized. 

Element: vertex.
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: yes.
Example datafile declaration:

   quantity laplac info_only method stokes2d_laplacian global

<---------------------------- stress_integral ----------------------------->

Named method. Description: Hmm. Looks like this one calculates integrals
of components of a stress tensor. The scalar_integrand value is set as an
integer standing for which component to do (a kludge). See the function
stress_integral in method3.c for details. Does not have a gradient, so
should be used for just info_only quantities. 

Element: facet. 
Parameters: scalar_integrand. 
Models: linear. 
Ambient dimension: 3. 
Hessian: no.
Example datafile declaration:

  quantity stressy info_only method stress_integral global
  scalar_integrand: 3

<--------------------------------- string --------------------------------->

See "stringexpr" or "string model" for different uses of "string".

<------------------------------ string model ------------------------------>

The term "string model" means that the surface is one-dimensional. The
datafile must have the keyword "STRING" or "SURFACE_DIMENSION 1" in its top
section. Edges are defined in terms of their vertices, and facets by a list
of boundary edges. Facets are not divided into triangles, and may have any
number of edges. The edges of a facet need not form a closed loop, for
example if the facet is partly bounded by a constraint. A body is defined
by associating one facet to it, and the volume of the body is the area of
the facet. The default energy is edge length.

<------------------------- string_curve_tolerance ------------------------->

Internal read-write variable.
In the quadratic model, the smoothness of graphing of curved quadratic
edges can be controlled with the internal variable string_curve_tolerance,
which is the desired angle in degrees between successive graphed segments
making up the edge. 

<----------------------------- string_gravity ----------------------------->

Named method. Description: To calculate the gravitational potential energy
of a body in the string model. Uses differences in body densities. Does not
use gravitational constant G as modulus (unless invoked as internal
quantity by convert_to_quantities). 

Element: edge. 
Parameters: none.
Models: string; linear, quadratic, lagrange. 
Ambient dimension: 2. 
Hessian: yes. 
Orientable: yes. 
Example datafile declaration:

   quantity cell_grav energy modulus 980*8.5 method string_gravity


<------------------------------- stringexpr ------------------------------->

String expressions:
A string expression evaluates to a string of characters. At present, the
only ways to produce strings are:
 1. double-quoted string literals, e.g. "this is a string". The following
    standard C escape sequences are recognized:
     \n newline
     \r carriage return
     \t tab
     \b backspace
     \q double-quote mark
     \c the character c elsewise
    In DOS, MS-Windows, or Windows NT paths, use / as the directory separator,
    since \ is an escape character. DOS and Windows have always accepted / as a
    directory separator.
 2. successive double-quoted strings, which are concatenated into one string
    when read.
 3. string variables, either internal like datafilename, or user-defined.
 4. output from sprintf.
Examples:
  print  "Hello World!\n";
  printf "This is a" " concatenated format string.\n";
  print datafilename;
  dump sprintf"file%04d.dmp",dumpnumber;

<------------------------------- subcommand ------------------------------->

Main prompt command. Invokes a subsidiary command interpreter. Useful if
you want to pause in the middle of a script to give the user the chance to
enter commands. A subcommand interpreter gives the prompt "Subcommand: "
instead of "Enter command: ". Subcommands may be nested several deep, in which
case the prompt will display the subcommand level. To exit a subcommand
prompt, use q, quit, or exit. Note: The abort command will return to the prompt
on the same subcommand level. 
 
<---------------------------- suppress_warning ---------------------------->
<--------------------------- unsuppress_warning --------------------------->

Suppress_warning
Datafile keyword instructing Evolver not to print a certain warning.
Syntax: 
 
  SUPPRESS_WARNING number 

where number is the number of the warning. Meant to suppress irritating
warning messages that you know are irrelevant. Warnings can be restored
with the syntax 
 
  UNSUPPRESS_WARNING number 

 
<--------------------------- surface_knot_power --------------------------->

Internal read-write variable used in the facet_knot_energy  and
sphere_knot_energy named methods as the exponent of the denominator.

 
<--------------------- surface dimension declaration ---------------------->

The default dimension of the surface is 2. If not, it must be declared in
the top section of the datafile. For a 1-dimensional surface (the string
model), simply include the line

 STRING

The default dimension 2 soapfilm model is equivalent to using

 SOAPFILM

In general, the line

 SURFACE_DIMENSION n

defines the surface to have dimension n. Dimension over 2 is valid only in
the simplex model. The surface dimension may be accessed at runtime through
the read-only variable surface_dimension.


<---------------------------- surface tension ----------------------------->

Soap films and interfaces between different fluids have an energy content
proportional to their area. Hence they shrink to minimize energy. The
energy per unit area can also be regarded as a surface tension, or force
per unit length. Each facet has a surface tension, which is 1 unless the
datafile specifies otherwise (see TENSION attribute for faces). Different
facets may have different surface tensions. Facet tensions may be changed
interactively with the set facet tension ... command. The contribution to
the total energy is the sum of all the facet areas times their respective
surface tensions. The surface tension of a facet may also be specified as
depending on the phases of the bodies it separates. In the string model,
the tension resides on edges instead of facets.
 Example datafile: cube.fe

<--------------------------- surface_dimension ---------------------------->

Internal read-only variable. Dimension of surface.  Can only be set in
the top section of the datafile.  Syntax:

   string    // for surface_dimension 1
   soapfilm  // for surface_dimension 2, the default
   surface_dimension n   // for simplex model  

<----------------------------- surface_energy ----------------------------->

An obsolete way of including vector surface energy integrals in the
datafile. The present method is to use a named quantity with the
facet_vector_integral method.

<------------------------------ SVK_elastic ------------------------------->
<------------------------------- SVK_alpha -------------------------------->
<------------------------------- SVK_lambda ------------------------------->
<--------------------------------- SVK_mu --------------------------------->
<------------------------------- SVK_theta -------------------------------->
SVK_elastic
Named method. Description: SVK (Saint-Venant - Kirchhoff) potential. The
facet energy is 
  lambda/2*(tr(E))^2+mu*(E:E) - (3 lambda + 2 mu) * alpha*theta*tr(E) 
where E=(C-I)/2 is the Green-Lagrange Strain tensor, theta = T-T0 is the
temperature deviation, and alpha is the thermal dilation coefficient. 
Needs real-valued facet attributes SVK_alpha, SVK_mu, SVK_lambda, and
SVK_theta. Also needs the facet attribute form_factors, decribed in
linear_elastic. Written by Dr. Rabah Bouzidi. 

Element: facet. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: yes. 
Example datafile declaration: 
 
   define facet attribute SVK_alpha real 
   define facet attribute SVK_lambda real 
   define facet attribute SVK_mu real 
   define facet attribute SVK_theta real 
   define facet attribute form_factors real[3] 
   quantity svk energy method SVK_elastic  global 

 
<------------------------------ swap_colors ------------------------------->

A view transform attribute used to switch facet front and back colors,
depending on the transformation.  See "view_transforms" and
"view_transform_generators".

<--------------------------- symmetric_content ---------------------------->

The datafile keyword SYMMETRIC_CONTENT triggers the use of an alternate
surface integral for calculating body volumes, namely the vectorfield
(x,y,z)/3. It is useful if unmodelled sides of a body are radial from the
origin, or if constraint content integrals (which is evaluated by an
approximation) lead to asymmetric results on what should be a symmetric
surface.  Does not apply to gravitational potential energy; you may want
to write your own named quantity to do a symmetric version of gravity.

<------------------------------- symmetries ------------------------------->

There are many interesting problems dealing with symmetric surfaces. A
natural way to deal with a symmetric surface is to compute with only one
fundamental domain of the symmetry, and use special boundary conditions.
Some symmetries, such as mirror symmetries, can be handled with normal
Evolver features. For example, a mirror can be implemented as a planar
level set constraint. But symmetries such as translational or rotational
symmetry require some built-in features. In any case, multiple copies of
the fundamental domain may be displayed with the view_transforms command.
 No symmetry (default)
 Torus model (translational symmetry)
 Symmetry groups (general symmetry)

<-------------------------- symmetry declaration -------------------------->

To declare that the domain is the quotient space of a symmetry group, the
top section of the datafile must contain a line of the form

   SYMMETRY_GROUP "name"

"name" is a double-quoted name that is matched against the list of defined
symmetry groups. See "symmetry groups".


<---------------------------- symmetry groups ----------------------------->

As a generalization of the torus model, you may declare the domain to be
the quotient space of R^n with respect to some symmetry group. Several
built-in groups are available, and ambitious users can compile C code into
Evolver to define group operations. Group elements are represented by
integers attached to edges (like the wrap specifications in the torus model
at runtime). You define the integer representation of the group elements.
See the file quotient.c for an example. See khyp.c and khyp.fe for a more
intricate example modelling an octagon in Klein hyperbolic space identified
into a genus 2 surface.

The datafile requires the keyword SYMMETRY_GROUP followed by the name for
the group in quotes. Edges that wrap have their group element specified in
the datafile by the phrase "wrap n", where n is the number of the group
element. The wrap values are accessible at run time with the wrap attribute
of edges. The group operations are accessible by the functions
wrap_inverse(w) and wrap_compose( w1,w2).

Using any Hessian commands with any symmetry group (other than the
built-in torus model) will cause automatic converting to named quantities
(with the " convert_to_quantities" command, since only named quantity
Hessian evaluation routines have the proper symmetry transformation of the
Hessian programmed in.

Volumes of bodies might not be calculated correctly with a symmetry group.
The volume calculation only knows about the built-in torus model. For other
symmetry groups, if you declare a body, it will use the Euclidean volume
calculation. It is up to you to design an alternate volume calculation
using named quantities and methods.

The currently implemented symmetry groups are:
   torus - The underlying group for the torus model.
   rotate - Cyclic group of rotations in the x-y plane.
   flip_rotate - Cyclic group of rotations in the x-y plane with z -> -z
      with every odd rotation.
   cubocta - Full point group of a cube.
   xyz - The orientation-preserving subgroup of cubocta.
   genus2 - For a 2 dimensional genus 2 hyperbolic quotient space.
   dodecahedron - For a 3D hyperbolic quotient space with dodecahedral
      fundamental region.
   central_symmetry - Inversion through the origin, X -> -X.
   screw_symmetry - Screw motion along z axis.

<----------------------------- symmetry_group ----------------------------->

Internal read-only variable. Whether any symmetry group is active (Boolean).

<--------------------------------- system --------------------------------->

Main prompt command. For executing an external 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.


<----------------------------------- t ------------------------------------>

Single letter main command. Eliminates tiny edges and their adjacent
facets. You will be prompted for a cutoff edge length if you don't give a
value with the command. If you enter h, you will get an edge length
histogram. If you hit RETURN without a value, nothing will happen. Some
edges may not be eliminable due to being FIXED or endpoints having
different attrtibutes from the edge.

Graphics mode command. Reset mode of displaying torus model. Choice of
raw unit cell, clipped unit cell, or connected bodies.


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


<--------------------------- t1_edgeswap_count ---------------------------->

Internal read-only variable. Number of edges swapped by the t1_edgeswap
command. Prints and resets to 0 at the end of a command execution, or
when flush_counts is done. Also reset by reset_counts.

<---------------------------------- tag ----------------------------------->

Defunct built-in element attribute, from the days before Evolver
had user-definable extra attributes.  It has now been removed.  If you
load an old datafile that uses "tag", you will get an error.  The easiest
remedy is to define an integer attribute named "tag" on the type of element
needed, for example
    define facet attribute tag integer

<---------------------------------- tan ----------------------------------->

 sin(x),cos(x),tan(x): Trig functions, argument in radians.

<---------------------------------- tanh ---------------------------------->

 sinh(x),cosh(x),tanh(x): Hyperbolic functions.

<--------------------------------- target --------------------------------->

Body read-write attribute. The target volume of a volume constraint. May
be set in the datafile, by the b command, or the set command. A volume
constraint may be removed by the unset, or with the b command. Command
examples:
  set body[1] target 23
  unset body target where id == 2
  print body[2].target



<---------------------------- target_tolerance ---------------------------->

Internal read-write variable. When volume constraints or named quantity 
constraints are enforced, Newton's method is repeated until the total 
deviation from target values is less than target_tolerance.
Default value 1e-4.

<------------------------------- task_exec -------------------------------->

Main prompt command for MPI Evolver.  Causes a particular task to
execute the string as a command. Syntax:
   task_exec n,string
where n is the task number (between 1 and mpi_maxtask) and string
is any string expression, such as a double-quoted string or a
string variable.  Any aggregate commands such as "sum" execute 
across all local and imported elements. 


<------------------------------ temperature ------------------------------->

Datafile top section keyword.
Specifies amplitude for "j" or "jiggle" command.  Sets the internal
read-write variable "jiggle_temperature".

<-------------------------------- tension --------------------------------->

Edge read-write attribute. Energy per unit length of edge; line
tension. Default 1 in string model, 0 in soapfilm model. May be set in the
datafile by adding "tension expr" to the line defining an edge. The
density is inherited by any facets generated by refining. "Tension" and
"density" are synonyms. Examples:

  set edge tension 3 where original == 1
  list edge where density < .4

Facet read-write attribute. Energy per unit area of facet; surface
tension. Default 0 in string model, 1 in soapfilm model. May be set in the
datafile by adding "tension value" to the line defining the facet. The
density is inherited by any facets generated by refining. "Tension" and
"density" are synonyms. Examples:

  set facet tension 3 where original == 1
  list facet where density < .4


<------------------------------ tetra_point ------------------------------->

Vertex read-write attribute. For telling Evolver six films meet at this
vertex. Used when effective_area is on to adjust motion of vertex by making
the effective area around the vertex 1/sqrt(6) of actual.

<-------------------------------- thicken --------------------------------->

Evolver toggle command. Whether to display differently colored sides of a
facet separated by thickness. Default off. This helps prevent weird striping
due to limited resolution of depth buffers. But seems obsolete now;
graphics routines automatically do this whether the toggle is off or on.


<------------------------------- thickness -------------------------------->

Internal read-only variable. Thickness for thickened surfaces
in graphics output in P command. Used when facet frontcolor and backcolor
are different. Default value 0.001 times the maximum linear dimension of
the surface. If you get backside color showing through, increase the
thickness.   The "thicken" toggle enables this, and is on by default.

<------------------------------- this_task -------------------------------->

MPI Evolver read-only variable. Task number of the task, from 
0 (the master task) to mpi_maxtask.

<---------------------------- toggle commands ----------------------------->
<----------------------------------- on ----------------------------------->
<---------------------------------- off ----------------------------------->

There are a large number of Surface Evolver features that can be turned on
or off with simple "toggle" commands. The general syntax is "togglename ON"
or "togglename OFF", with just "togglename" being a synonym for "togglename
ON". The toggle names below have brief descriptions of their actions in the
ON state. Toggles will usually print their previous state. A togglename
used in an arithmetic expression is the current value of the toggle, 0 for
OFF and 1 for ON. The current value of a toggle may be found by "print
togglename".

All toggles (except quietload) are reset when a surface is loaded. Default
values are OFF unless otherwise noted.

Full-word toggle commands are not to be confused with various
single-letter toggle commands, which always change the state. All
single-letter toggles have full word toggle equivalents.

<------------------------------- tolerance -------------------------------->

As a keyword, "tolerance" refers to a fixed quantity attribute that is
used as the criterion for convergence. Uses target_tolerance as the default
value.


<-------------------------------- topinfo --------------------------------->

Top section of the datafile. "list topinfo" prints the first section of
the datafile on the screen. This is everything before the vertices section.

<--------------------------------- torus ---------------------------------->

Internal read-only variable. Whether the torus model is in effect.
(Boolean).

<--------------------------- torus declaration ---------------------------->

To declare periodic boundary conditions (i.e. make the domain a flat
torus), include in the top section of the datafile the line

  TORUS

All space dimensions will be periodic, with the period vectors given in
the periods declaration. If the domain is completely filled by bodies with
prescribed volumes, then the line

  TORUS_FILLED

should be used instead to prevent degenerate volume constraints.
Also see "periods".

<----------------------------- torus display ------------------------------>

There are several commands for ways of displaying a torus surface:

 raw_cells - Graph the facets as they are, without clipping. The first
             vertex of a facet is used as the basepoint for any unwrapping 
             of other vertices needed.

 connected - Each body's facets are unwrapped in the torus, so the body
             appears in one connected piece. Nicest option, but won't 
             show facets not on bodies.

 clipped - Shows the unit cell specified in the datafile. Facets are
           clipped on the parallelpiped faces.  Also see display_periods
           and display_origin for more control of "clipped" mode.


<------------------------------ torus model ------------------------------->

The Evolver can take as its domain a flat torus with an arbitrary
parallelpiped as its unit cell, i.e. the domain is a parallelpiped with its
opposite faces identified. This is indicated by the TORUS keyword in the
datafile. The defining basis vectors of the parallelpiped are given in the
TORUS_PERIODS entry of the datafile. See twointor.fe for an example.

Vertex coordinates are given as Euclidean coordinates within the unit
cell, not as linear combinations of the period vectors. The coordinates
need not lie within the parallelpiped, as the exact shape of the unit cell
is somewhat arbitrary.

The way the surface wraps around in the torus is given by saying how the
edges cross the faces of the unit cell. In the datafile edges section, each
edge has one symbol per dimension indicating how the edge vector crosses
each identified pair of faces, and how the vector between the endpoints
needs to be adjusted to get the true edge vector:
 * does not cross face
 + crosses in same direction as basis vector, so basis vector added to edge
      vector
 - crosses in opposite direction, so basis vector subtracted from edge
      vector. Wraps are automatically maintained by the various triangulation
      manipulation operations.
 There are several commands for ways of displaying a torus surface:
 raw_cells - Graph the facets as they are, without clipping. The first
      vertex of a facet is used as the basepoint for any unwrapping of other
      vertices needed.
 connected - Each body's facets are unwrapped in the torus, so the body
      appears in one connected piece. Nicest option, but won't show facets 
      not on bodies.
 clipped - Shows the unit cell specified in the datafile. Facets are
      clipped on the parallelpiped faces.

A few features are not available with the torus model, such as gravity and
the simplex model. (Actually, you could put them in, but they will not take
into account the torus model.)

Volumes and volume constraints are available. However, if the torus is
completely partitioned into bodies of prescribed volume, then the volumes
must add up to the volume of the unit cell and the TORUS_FILLED keyword
must be given in the datafile. Or just don't prescribe the volume of one
body.

Volumes are somewhat ambiguous. The volume calculation method is accurate
only to one torus volume, so it is possible that a body whose volume is
positive gets its volume calculated as negative. Evolver adjusts volumes
after changes to be as continuous as possible with the previous volumes as
possible, or with target volumes when available. You can also set a body's
volconst attribute if you don't like the Evolver's actions.

Level set constraints can be used in the torus model, but be cautious when
using them as mirror symmetry planes with volumes. The torus volume
algorithm does not cope well with such partial surfaces. If you must, then
use y=const symmetry planes rather than x=const, and use the -q option or
do convert_to_quantities. Double-check that your volumes are turning out
correctly; use volconst if necessary.

Display_periods:The displayed parallelogram unit cell can be different
from the actual unit cell if you put an array called display_periods in the
top of the datafile, in addition to the regular periods. For a string model
example,
   parameter shear = 1
   torus_filled
   periods
   4  0
   shear  4
   display_periods
   4 0
   0 4

This will always display a square, no matter how much the actual unit cell
is sheared. This feature works well for shears; it may not work nicely for
other kinds of deformation. Display_periods works better for the string
model than the soapfilm model. For the soapfilm model, it seems to do
horizontal shears best, but it can't cope with large shears, so if your
shear gets too large, I advise resetting your fundamental region to less
shear, say with the unshear command in unshear.cmd.

<----------------------------- torus periods ------------------------------>

If periodic boundary conditions are used (the torus model) , the period
vectors of the fundamental unit cell parallelpiped may be defined in the
top section of the datafile. Default is the unit cube. The syntax is the
keyword PERIODS followed by expressions for the components of each period
vector:

PERIODS
expr expr expr
expr expr expr
expr expr expr

The size of this matrix depends on the space dimension. Variables may be
used in the expressions, so the fundamental domain may be changed
interactively by assigning new values to the variables. Be sure to give a
recalc command whenever you change such a variable, in order to get the
period matrix re-evaluated.

<-------------------------- torus symmetry group -------------------------->

This is the underlying symmetry for the torus model. Although the torus
model has a number of special features built in to the Evolver, it can also
be accessed through the general symmetry group interface. The torus group
is the group on n-dimensional Euclidean space generated by n independent
vectors, called the period vectors. The torus group uses the torus periods
listed in the datafile.
Datafile declaration:

   symmetry_group "torus"

Group element encoding: The 32-bit code word is divided into 6-bit fields,
one field for the wrap in each dimension, with low bits for the first
dimension. Hence the maximum space dimension is 5. Within each bitfield, 1
codes for positive wrap and 011111 codes for negative wrap. The coding is
actually a 2's complement 5-bit integer, so higher wraps could be
represented.


<------------------------------ torus_filled ------------------------------>

Whether Evolver should treat one "fixed" body volume as not fixed, for the
purpose of avoiding redundant constraints in the case of a torus space
being completely filled with bodies of fixed volume, for example a
periodic foam. The top section of the datafile may contain a line

TORUS_FILLED

and there is also a "torus_filled" runtime toggle command.

<----------------------------- torus_periods ------------------------------>

torus_periods[expr][expr] : Internal read-only variable. Current values of
the period vectors in the torus model. Torus_periods[i][j] is component j
of vector i. Uses 1 based indexes. For changing the torus_periods, define
the periods in the datafile with variables, and alter the variables.
Note that just "PERIODS" is used to declare the torus period matrix
in the top of the datafile:

  PERIODS
  expr expr expr
  expr expr expr
  expr expr expr

<------------------------------- total_area ------------------------------->

Internal read-only variable. Total area of the surface in soapfilm or 
simplex models.  Beware that this is not continuously updated with every
change in the surface, but rather upon return to the command prompt.  If 
a script needs the current total_area recalculated, it should do the 
"recalc" command before using total_area.

<------------------------------ total_energy ------------------------------>

Internal read-only variable. Total energy of the surface. Beware that this 
is not continuously updated with every change in the surface, but rather 
upon return to the command prompt.  If a script needs the current total_energy:
recalculated, it should do the "recalc" command before using total_energy.

<------------------------------ total_length ------------------------------>

Internal read-only variable. Total length of the edges in
the string model.

<------------------------------- total_time ------------------------------->

Internal read-only variable. Elapsed evolution time in the
form of the sum of all the scale factors of 'g' steps.

<---------------------------- transform_count ----------------------------->

Internal read-only variable. Number of image transforms
active, as generated by the transform_expr command.

<---------------------------- 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}.
   !a     Generates set {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. The "!" character suppresses the identity matrix in
the set of matrices generated so far. Examples:

  transform_expr "3(a|b|c)"    //all products of 3 or fewer generators
  transform_expr "abcd"  // generates 16 transforms
  transform_expr "!a!a!a!"  // one copy shown, transformed three times

All duplicate transforms are removed (see view_transforms_use_unique_point
for more on uniqueness of transforms), 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


<------------------------------- transforms ------------------------------->

Evolver toggle command. Toggles graphing multiple images of the surface,
according to the view transforms defined in the datafile, or according to
the current transform expression applied to the view transform generators
defined in the datafile.


<------------------------------ triple_point ------------------------------>

Vertex read-write attribute. For telling Evolver three films meet at this
vertex. Used when effective_area is on to adjust motion of vertex by making
the effective area around the vertex 1/sqrt(3) of actual.

<------------------------- true_average_crossings ------------------------->

Named method. Description: Calculates the average crossing number of an
edge with respect to all other edges, averaged over all projections. Knot
stuff. No gradient, so use just in info_only quantities. 

Element: edge.
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: no.
Example datafile declaration:

  quantity true_cross info_only method true_average_crossings global

<------------------------------ true_writhe ------------------------------->

Named method. Description: For calculating the writhe of a link or knot.
No gradient, so use just in info_only quantities. 

Element: edge.
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: no.
Example datafile declaration:

quantity twrithe info_only method true_average_crossings global

<--------------------------------- twist ---------------------------------->

Named method. Description: Another average crossing number calculation. No
gradient, so use just in info_only quantities. 

Element: edge. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration:

  quantity twister info_only method twist global

<-------------------------------- twointor -------------------------------->

Example: Torus partitioned into two cells (Kelvin's foam)

This example has a flat 3-torus (i.e. periodic boundary conditions)
divided into two bodies. The unit cell is a unit cube, and the surface has
the topology of Kelvin's partitioning of space into tetrakaidecahedra [TW],
which was the least area partitioning of space into equal volumes known
until recently [WP].

The datafile handles the wrapping of edges around the torus by specifying
for each direction whether an edge wraps positively (+), negatively (-), or
not at all (*).

Note the use of the keyword TORUS_FILLED in the datafile. This informs
Evolver that one of the volume constraints is redundant, preventing a
singular matrix when the time comes to enforce volume constraints. One
could use just TORUS and only put on one volume constraint.

The display of a surface in a torus can be done several ways. The
connected command (my favorite) makes each body show as a single unit. The
clipped command shows the surface clipped to the fundamental parallelpiped.
The raw_cells command shows the unedited surface.

The Weaire-Phelan structure [WP]. is in the datafile phelanc.fe. It has
area 0.3% less than Kelvin's.


// twointor.fe
// Two Kelvin tetrakaidecahedra in a torus.

TORUS_FILLED   // signals that domain is a torus and bodies fill it.

periods
1.000000 0.000000 0.000000
0.000000 1.000000 0.000000
0.000000 0.000000 1.000000

vertices // values from another program
1  0.499733 0.015302 0.792314
2  0.270081 0.015548 0.500199
3  0.026251 0.264043 0.500458
4  0.755123 0.015258 0.499302
5  0.026509 0.499036 0.794636
6  0.500631 0.015486 0.293622
7  0.025918 0.750639 0.499952
8  0.499627 0.251759 0.087858
9  0.256701 0.499113 0.087842
10 0.026281 0.500286 0.292918
11 0.500693 0.765009 0.086526
12 0.770240 0.499837 0.087382

edges // with wraps in axis directions
1    1 2  * * *
2    2 3  * * *
3    1 4  * * *
4    3 5  * * *
5    2 6  * * *
6    2 7  * - *
7    1 8  * * +
8    4 6  * * *
9    5 9  * * +
10   3 10 * * *
11   3 4  - * *
12   6 8  * * *
13   6 11 * - *
14   7 4  - + *
15   8 12 * * *
16   9 8  * * *
17   9 11 * * *
18   10 7 * * *
19   11 1 * + -
20   12 5 + * -
21   5 7  * * *
22  11 12 * * *
23  10 12 - * *
24   9 10 * * *

faces
1    1 2 4 9 16 -7
2    -2 5 12 -16 24 -10
3    -4 10 18 -21
4    7 15 20 -4 11 -3
5    -1 3 8 -5
6    6 14 -11 -2
7    5 13 -17 24 18 -6
8    -12 13 19 7
9    -16 17 22 -15
10   -10 11 8 12 15 -23
11   -21 9 17 19 1 6
12   -14 -18 23 -22 -13 -8
13   -24 -9 -20 -23
14   -19 22 20 21 14 -3

bodies
1    -1 -2 -3 -4 -5 9 7 11 -9 10 12 5 14 3 volume 0.500
2     2 -6 -7 8 -10 -12 -11 -13 1 13 -14 6 4 -8 volume 0.500

// end of datafile

Doing some refining and iterating will show that the optimal shape is
curved a bit.

<----------------------------------- U ------------------------------------>

Single letter main command. This toggles conjugate gradient mode, which
will usually give faster convergence to the minimum energy than the default
gradient descent mode. The only difference is that motion is along the
conjugate gradient direction. The scale factor should be in optimizing
mode. The conjugate gradient history vector is reset after every surface
modification, such as refinement or equiangulation. After large changes
(say, to volume), run without conjugate gradient a few steps to restore
sanity.


<----------------------------------- u ------------------------------------>

Single letter main command. This command, called "equiangulation", tries
to polish up the triangulation. In the soapfilm model, each edge that has
two neighboring facets (and hence is the diagonal of a quadrilateral) is
tested to see if switching the quadrilateral diagonal would make the
triangles more equiangular. For a plane triangulation, a fully
equiangulated triangulation is a Delaunay triangulation, but the test makes
sense for skew quadrilaterals in 3-space also. It may be necessary to
repeat the command several times to get complete equiangulation. The
edgeswap command can force flipping of prescribed edges.

In the simplex model, equiangulation works only for surface dimension 3.
There, two types of move are available when a face of a tetrahedron
violates the Delaunay void condition: replacing two tetrahedra with a
common face by three, or the reverse operation of replacing three
tetrahedra around a common edge by two, depending on how the condition is
violated. This command is inoperative in the string model.

Graphics mode command. Tip up. Rotates image about horizontal axis,
default 6 degrees.  Integer prefix indicates how many 6 degree rotations
to do; decimal prefix indicates angle of tip in degrees.
Example: `15u' does 90 degree rotation, `15.0u' does 15 degree rotation.


<--------------------------------- unfix ---------------------------------->

Main prompt command. Removes the FIXED attribute from a set of elements,
or change a parameter to an optimizing paramater, or change a
named quantity to info_only mode.

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.  Example:

  unfix quantityname


<------------------------------ unfix_count ------------------------------->

Internal read-only variable. Number of elements unfixed by the unfix command. 
Prints and resets to 0 at the end of a command execution, or when flush_counts 
is done. Also reset by reset_counts.

<-------------------------- uniform_knot_energy --------------------------->

Named method. Description: A knot energy where vertex charge is
proportional to neighboring edge length. This simulates an electrostatic
charge uniformly distributed along a wire. Inverse power law of potential
is adjustable via the global parameter `knot_power' (default 2). 

Element: vertex. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: any. 
Hessian: no. 
Example datafile declaration:

  parameter knot_power  2     // the default
  quantity knotten energy method uniform_knot_energy global


<--------------------- uniform_knot_energy_normalizer --------------------->

Named method. Description: Supposed to approximate the part of
uniform_knot_energy that is singular in the continuous limit. 

Element: vertex. 
Parameters: knot_power. 
Models: string; linear. 
Ambient dimension: any. 
Hessian: no.
Example datafile declaration:

  parameter knot_power  2     // the default
  quantity knottenorm energy method uniform_knot_energy global
                             method uniform_knot_energy_normalizer global


<------------------------ uniform_knot_normalizer1 ------------------------>

Named method. Description: Calculates internal knot energy to normalize
singular divergence of integral of uniform_knot_energy. Actually a synonym
for uniform_knot_energy_normalizer. No gradient. 

Element: vertex.
Parameters: none. 
Models: string; linear. 
Ambient dimension: 3. 
Hessian: no.
Example datafile declaration:

  parameter knot_power  2     // the default
  quantity knottenorm energy method uniform_knot_energy global
                             method uniform_knot_energy_normalizer1 global

<------------------------ uniform_knot_normalizer2 ------------------------>

Named method. Description: Calculates internal knot energy to normalize
singular divergence of integral of uniform_knot_energy a different way from
uniform_knot_energy_normalizer. 

Element: edge. 
Parameters: none. 
Models: string; linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration:

  parameter knot_power  2     // the default
  quantity knottenorm energy method uniform_knot_energy global
                             method uniform_knot_energy_normalizer2 global

<----------------------------- unit mobility ------------------------------>

The default mobility, in which the vertex velocity is equal to the force.
The physical interpretation of this is that there is a resistance to motion of
each vertex through the medium proportional to its velocity, but not for
the edges. This does not approximate motion by mean curvature, but it is
very easy to calculate.


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


<--------------------------- unstable surfaces ---------------------------->

Detecting the onset of instability and evolving unstable surfaces.

The Hessian features can be used to detect the onset of instability as
some parameter changes, and even evolve unstable equilibrium surfaces.

Instability detection is done by watching eigenvalues with the ritz
command. As an example, consider a ring of liquid outside a cylinder, with
the volume increasing until the symmetric ring becomes unstable. This is
set up in the datafile catbody.fe, which is just cat.fe with a body defined
from the facets. Run catbody.fe with this initial evolution:
  u
  g 5
  r
  g 5
  body[1].target := 2
  g 5
  r
  body[1].target := 3
  g 5
  hessian
  hessian
  linear_metric
  ritz(0,5)

This gives eigenvalues

Eigencounts:    0
  1.    0.398411128930840
  2.    0.398411128930842
  3.    1.905446082321839
  4.    1.905446082321843
  5.    4.4342055632012

Note we are still in a stable, positive definite situation, but the lowest
eigenvalues are near enough to zero that we need to take care in increasing
the volume. Try an increment of 0.1:

  body[1].target += 0.1
  g 5
  hessian
  hessian
  ritz(0,5)
Eigencounts:    0
  1.    0.287925880010193
  2.    0.287925880010195
  3.    1.775425717998147
  4.    1.775425717998151
  5.    4.2705109310529

A little linear interpolation suggests try an increment of 0.3:

  body[1].target += 0.3
  g 5
  hessian
  hessian
  hessian
  ritz(0,5)
Eigencounts:    0
  1.    0.001364051154697
  2.    0.0013640511547
  3.    1.4344757227809
  4.    1.4344757227809
  5.    3.8350719808531

So we are now very very close to the critical volume. In view of the
coarse triangulation here, it is probably not worth the trouble to narrow
down the critical volume further, but rather refine and repeat the process.
But for now keep this surface running for the next paragraph.

Evolving into unstable territory Typically these are surfaces with just a
few unstable modes. The idea is to get close to the desired equilibrium and
use "hessian" to reach it. Regular 'g' gradient descent iteration should
not be used. To change the surface, i.e. to follow an equilibrium curve
through a phase diagram, make small changes to the control parameter and
use a couple of hessian iterations to reconverge each time. Particular care
is needed near bifurcation points, because of the several equilibrium
curves that meet. When approaching a bifurcation point, try to jump over it
so there is no ambiguity as to which curve you are following. The approach
to a bifurcation point can be detected by watching eigenvalues. An
eigenvalue crosses 0 when a surface introduces new modes of instability.

Example: Catbody.fe, continued. With catbody.fe in the nearly-critical
state found above, increase the body volume by steps of .1 and run hessian
a couple of times each step:

 body[1].target += .1
 hessian
 hessian
 hessian
 hessian
 body[1].target += .1
 hessian
 hessian
 hessian
 hessian
 body[1].target += .1
 hessian
 hessian
 hessian
 hessian

So hessian alone is enough to evolve with, as long as you stay near enough
to the equilibrium.

Other methods for evolving unstable surfaces:

Using symmetry. If the unstable surface is more symmetric than the
stable surfaces, then enforcing symmetry can remove the unstable modes. For
example, a surface of revolution could be retricted to just a 90 degree
wedge between two perpendicular mirror planes (level-set constraints), with
90 degree contact angles on the planes.

Using volume constraints. Recall that in general every constraint
removes one degree of freedom in the configuration space. Hence a volume
constraint has the potential to remove one unstable mode. For example,
unstable catenoids can be made stable by adding a volume constraint and
adjusting the volume until the pressure is 0.


<----------------------------- user functions ----------------------------->

User-defined functions can be defined in C in userfunc.c. They are meant
for situations where expression interpretation is too slow, or functions
such as elliptic integrals are wanted. Currently, they are automatically
functions of the coordinates. Do not give any arguments in the expression;
for example "(usr1 + usr3)/usr10".

<------------------------- user-defined mobility -------------------------->

The user may define a mobility tensor in the datafile. There is a scalar
form with the keyword MOBILITY and a tensor form with MOBILITY_TENSOR. When
in effect, this mobility is multiplied times the velocity to give a new
velocity. This happens after any of the previous mobilities of this section
have been applied and before projection to constraints. The formulas
defining the mobility may include adjustable parameters, permitting the
mobility to be adjusted during runtime. The formulas are evaluated at each
vertex at each iteration, and so formulas may depend on vertex position and
any vertex attributes.

<---------------------------------- usr ----------------------------------->

usr1, usr2, etc. : user-defined functions; see "user functions".

<--------------------------------- utest ---------------------------------->

Main prompt commnad. Runs a test to see if triangulation is Delaunay.
Meant for higher dimensions and simplex model.

<----------------------------------- v ------------------------------------>

Single letter main command. Shows target volume, actual volume, and
pressure of each body. Also shows named quantities. Pressures are really
the Lagrange multipliers. Pressures are computed before an iteration, so
the reported values are essentially are one iteration behind. Synonym:
show_vol

Graphics mode command. Toggles showing of convex and concave edges in
different colors. "v" stands for "valleys".

<----------------------------------- V ------------------------------------>

Single letter main command. Vertex averaging. For each vertex, computes
new position as area-weighted average of centroids of adjacent facets. Only
adjacent facets with the same constraints and boundaries are used.
Preserves volumes, at least to first order. See the rawv command for vertex
averaging without volume preservation, and rawestv for ignoring likeness of
constraints. Vertices on triple edges are averaged only with adjacent
vertices on the triple edge, and then only if there are exactly two
neighboring triple edge vertices. Fixed vertices do not move. Vertices on
constraints are projected back onto their constraints. The computation of
new vertex positions are all done before any vertex is moved. For
sequential movement applied to a subset of vertices, see the vertex_average
command.

<--------------------------- v_constraint_list ---------------------------->

Internal vertex read-only attribute. List of constraints a vertex
is on. v_constraint_list[1] is the number of constraints in the list,
followed by the numbers of the constraints. Note that for named
constraints, the internally assigned numbers are used.

<-------------------------------- valence --------------------------------->

An attribute of a vertex, which is the number of incident edges, or an
attribute of an edge, which is the number of incident facets, or an
attribute of a facet, which is the number of edges on the facet.
Example:
   refine edge where valence == 1 and length > 0.05

<----------------------------- valid_boundary ----------------------------->

Boolean function.  Returns 1 or 0 depending on whether a parametric
boundary with the given number exists (note that the name of a 
named boundary is internally interpreted as a number).  Syntax:

    VALID_BOUNDARY(expression)

One use is in looping through all parametric boundaries, in conjunction
with the high_boundary internal variable.  For example,

  for ( bnum := 1 ; bnum <= high_boundary ; bnum += 1 )
    if valid_boundary(bnum) then
       printf "Boundary %d has %d vertices on it\n",bnum,
          sum(vertex,on_boundary bnum);

<---------------------------- valid_constraint ---------------------------->

Boolean function.  Returns 1 or 0 depending on whether a level-set
constraint with the given number exists (note that the name of a 
named constraint is internally interpreted as a number).  Syntax:

    VALID_CONSTRAINT(expression)

One use is in looping through all level-set constraints, in conjunction
with the high_constraint internal variable.  For example,

  for ( cnum := 1 ; cnum <= high_constraint ; cnum += 1 )
    if valid_constraint(cnum) then
       printf "Constraint %d has %d vertices on it\n",cnum,
          sum(vertex,on_constraint cnum);

<----------------------------- valid_element ------------------------------>

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


<--------------------------------- value ---------------------------------->

The value of a quantity may be displayed with the A or v commands, or as
an expression "quantityname.value". Furthermore, using the quantity name as
an element attribute evaluates to the sum of all the applicable component
instance values on that element. For example, supposing there is a quantity
named vol, one could do
  print vol.value
  print facet[2].vol
  histogram(facet,vol)

<------------------------ value_of_constraint ----------------------------->

Built-in vertex constraint.  Evaluates the formula of the given
level-set constraint at the coordinates of the vertex.  Examples:
     print  vertex[5].value_of_constraint 1
     list vertex where value_of_constraint topcon > 0.5

      

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

<------------------------------- variables -------------------------------->

The Evolver command language has its own version of the user-defined
variables common to most programming languages. Variables are typed
according to the types of the values assigned to them: numeric or string.
Users may define numeric variables either by variable declarations in the
datafile, or both types by assigning a value to an identifier in a command.
A variable may be subjected to optimization by declaring it an
optimizing_parameter in the datafile.


<---------------------------- vector_integrand ---------------------------->

Additional attribute of some named methods, such as edge_vector_integral
and facet_vector_integral.  The following syntax is added to the
quantity or method declaration:

 VECTOR_INTEGRAND:
 Q1: expr
 Q2: expr
 Q3: expr

where the expressions may use space coordinates and element attributes,
besides any global values.


<------------------------------- v_velocity ------------------------------->

Internal vertex read-only attribute. This is an indexed attribute giving the
components of the vector used for vertex motion in the 'g' command. The
motion of a vertex is the scale factor times this vector. The velocity
vector is calculated from the force vector by applying area normalization,
mobilty, projecting to constraints, etc. Also, if a vertex is on a boundary, 
the velocity is projected back to parameters.


<-------------------------------- verbose --------------------------------->

Evolver toggle command. Toggles printing of progress messages during
surface modification commands such as refine, delete, notch, edgeswap, o,
O, c.

<-------------------------------- version --------------------------------->

If a datafile contains features present only after a certain version of
the Evolver, the datafile can contain a line of the form
    evolver_version "2.10"
This will generate a version error message if the current version is
earlier, or just a syntax error if run on an Evolver version earlier than
2.10.


<--------------------------------- vertex --------------------------------->

One of the basic geometric elements. As a keyword, it is used in element
generators.


<---------------------------- vertex boundary ----------------------------->

Vertex, edge, or facet read-only attribute.
The status of whether an element is on a boundary can be queried with the
Boolean attribute on_boundary. Elements can be unset from boundaries, but
not set on them (since parameter values would be unknown). Examples:

  list vertex where on_boundary 1
  unset vertex boundary 2

<------------------------------ vertex edges ------------------------------>

Vertex read-only attribute. Generates edges attached to a vertex, oriented
so vertex is the edge tail. The edges are in no particular order. Examples:

  list vertex[3].edges
  foreach vertex vv do { foreach vv.edge do print id }

Always use "vertexspec.edges" to generate vertex edges; using "edges" with an
implicit element, as in "foreach vertex do list edges" will list all edges
in the surface over and over again.

<----------------------------- vertex facets ------------------------------>

Vertex read-only attribute. Generates facets attached to a vertex, with
positive facet orientation. The facets are in no particular order.
Examples:

  list vertex[3].facets
  foreach vertex vv do { foreach vv.facet do print id }

Always use "vertexspec.facets" to generate vertex facets; using "facets" with
an implicit element, as in "foreach vertex do list facets" will list all
facets in the surface over and over again.

<----------------------------- vertex valence ----------------------------->

Vertex read-only attribute. The valence of a vertex is defined to be the
number of edges it is a member of. Example:

  list vertices where valence == 6
  histogram(vertex,valence)

<----------------------------- 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
See also "raw_vertex_average" and "rawest_vertex_average" for less
restricted averaging.


<------------------------------ vertex_count ------------------------------>

Internal read-only variable. Number of vertices.

<------------------------- vertex_dissolve_count -------------------------->

Internal read-only variable. Number of vertices dissolved by the dissolve
command. Prints and resets to 0 at the end of a command execution, or when
flush_counts is done. Also reset by reset_counts.

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

The first vertex is the surviving vertex.

<---------------------------- vertex_order_key ---------------------------->

Integer vertex attribute used by reorder_storage to determine the new
order of vertexs in storage.  See reorder_storage for details of use.

<--------------------------- vertices_predicted --------------------------->

Datafile keyword in the top section of the datafile that specifies the
initial allocation of vertex structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the vertex list grows or as 
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the "d" or "dump" commands, based on
the current number of vertices.
Example:
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432

<---------------------------- v_partition_proc ---------------------------->

Internal vertex attribute used when the multiprocessor option -pn is used.
Determines which thread owns a vertex.

<--------------------------- v_partition_stage ---------------------------->

Internal vertex attribute used when the multiprocessor option -pn is used.
Coordinates the sequencing of iteration over vertex in certain operations
so different threads don't conflict and time-consuming locks are not
necessary.

<---------------------------- vertex_pop_count ---------------------------->

Internal read-only variable. Number of vertices popped by "pop" or 'o' command.
Prints and resets to 0 at the end of a command execution, or when flush_counts
is executed. Also reset by reset_counts.

<------------------------- vertex_scalar_integral ------------------------->

Named method. Description: Function value at a vertex. This actually
produces a sum over vertices, but as a mathematician, I think of a sum over
vertices as a point-weighted integral. 

Element: vertex. 
Parameters: scalar_integrand. 
Models: string, soapfilm, simplex; linear, quadratic, Lagrange. 
Ambient dimension: any. 
Hessian: yes. 
Example datafile declaration:

  quantity point_value energy method vertex_scalar_integral
  scalar_integrand: x^2 + y^2 - 2x + 3

<------------------------------ vertexnormal ------------------------------>
<----------------------------- vertex_normal ------------------------------>

Vertex read-only attribute. This is an indexed attribute consisting of the
components of a normal to the surface at a vertex, normalized to unit
length. This is the same normal as used in hessian_normal mode. For most
vertices in the soapfilm model, the normal is the number average of the
unit normals of the surrounding facets. Along triple edges and such where
hessian_normal has a multi-dimensional normal plane, the vertex_normal is
the first basis vector of the normal plane. Example: To print the normal
components of vertex 3:

 print vertex[3].vertex_normal[1];
 print vertex[3].vertex_normal[2];
 print vertex[3].vertex_normal[3];

The vertex_normal vector can also be printed as an array:
 print vertex[3].vertex_normal

vertexnormal and vertex_normal are synonyms.

<-------------------------------- vertices -------------------------------->

A vertex is a point in space. The coordinates of the vertices are the
parameters that determine the location of the surface. It is the
coordinates that are changed when the surface evolves. A vertex carries no
default energy, but may have energy by being on a level set constraint in
the string model, or by having a named quantity energy applied to it. The
vertices of the original surface are defined in the vertices section of the
datafile.

 Attributes:

 > id
 > original
 > coordinates
 > parameter values
 > fixed
 > constraints
 > on_constraint
 > hit_constraint
 > v_constraint_list
 > boundary
 > on_boundary
 > bare
 > edges
 > facets

 > valence
 > quantities
 > on_quantity
 > on_method_instance
 > mid_edgedihedral
 > mid_facet
 > square mean curvature
 > axial_point
 > triple_point
 > tetra_point
 > vertex_normal
 > force
 > velocity
 > extra attributes


<---------------------------- vertices section ---------------------------->

The datafile vertex list is started by the keyword VERTICES at the start
of a line. It is followed by lines with one vertex specification per line.
If the vertex is not on a parametric boundary, the syntax is

  k   x y ... [FIXED] [CONSTRAINT c1 c2 ...]  [BARE]
              [quantityname ...] [methodname ...]

The syntax for a vertex on a parametric boundary is

  k p1 [p2 ...]  BOUNDARY b [FIXED] [BARE] [quantityname ...]
     [methodname ...]

Here k is the vertex number, a positive integer. Vertices do not need to
be listed in order, and there may be gaps in the numbering. However, if
they are not in consecutive order, then the numbering in dump files will be
different. x y ... are constant expressions for coordinates. In the
parametric boundary format, the boundary parameter values are given instead
of the coordinates. If FIXED is given, then the vertex never moves, except
possibly for an initial projection to constraints. If CONSTRAINT is given,
then one or more constraint numbers must follow. You can list as many
constraints as you want, as long as those that apply exactly at any time
are consistent and independent. The given coordinates need not lie exactly
on the constraints; they will be projected onto them. A vertex on a
parametric boundary cannot also be on a constraint.

The BARE attribute is just an instruction to the checking routines that
this vertex is not supposed to have an adjacent facet in the soapfilm
model, so spurious warnings will not be generated. This is useful when you
want to show bare wires or outline fundamental domains.
An arbitrary number of named quantities or method instances may be listed.
These add method values for this element to the named quantity. The named
quantity or instance must have been declared in the top section of the
datafile.

The "list vertices" command prints the datafile format listing of vertices.

<---------------------------- view generators ----------------------------->

Listing all the view transforms is tedious and inflexible. An alternative
is to list just a few matrices that can generate transforms. See the
transform_expr command for instructions on entering the expression that
generates the actual transforms. Special Note: in the torus model, the
period translations are automatically added to the end of the list. So in
the torus model, these are always available, even if you don't have
view_transform_generators in the datafile. Syntax in the top of the
datafile:

VIEW_TRANSFORM_GENERATORS n
SWAP_COLORS
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
    ...

The number of matrices follows the keyword VIEW_TRANSFORM_GENERATORS. Each
matrix is in homogeneous coordinates, with translation in the last column.
The size of each matrix is one more than the space dimension. Individual
matrices need no special separation; Evolver just goes on an expression
reading frenzy until it has all the numbers it wants. If SWAP_COLORS is
present, facet frontcolor and backcolor will be swapped when this matrix is
applied. The internal variable transform_count records the number of
transforms, and the transform matrices are accessible at runtime as a
three-dimensional matrix view_transforms[][][].


<------------------------------ view matrix ------------------------------->

The native screen graphics view is controlled by a view transformation
matrix, which may be specified in the datafile, and which is dumped by the
d or list topinfo commands. The view matrix may be changed with graphics
mode commands. The view matrix elements may be read or set at runtime by
view_matrix[i][j], where the indices start at 1. In particular, one can
write command scripts to save and reload particular view matrices; see
saveview.cmd in the distribution package. The view matrix does not affect
geomview.

The display consists entirely of facets and edges. Special edges (fixed
edges, boundary edges, constraint edges, triple edges, bare edges) are
always shown, unless you make their color CLEAR. The individual facet edges
can be toggled with the graphics mode command `e'.


<---------------------------- view transforms ----------------------------->

For the display of several transformations of the surface simultaneously,
a number of viewing transformation matrices may be given in the top section
of the datafile:

VIEW_TRANSFORMS n
COLOR color
SWAP_COLORS
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
    ...

The transforms apply to all graphics, internal and external, and are prior
to the viewing matrix for internal graphics. The identity transform is
always done, so it does not need to be specified. The number of matrices
follows the keyword VIEW_TRANSFORMS. Each matrix is in homogeneous
coordinates, with translation in the last column. The size of each matrix
is one more than the space dimension. Individual matrices need no special
separation; Evolver just goes on an expression reading frenzy until it has
all the numbers it wants. Each matrix may be preceded by an optional color
that applies to facets transformed by that matrix. The color applies to one
transform only; it does not continue until the next color specification. If
SWAP_COLORS is present instead, facet frontcolor and backcolor will be
swapped when this matrix is applied. Transforms may be activated or
deactivated interactively with the transforms toggle. The internal variable
transform_count records the number of transforms, and the transform
matrices are accessible at runtime as a three-dimensional matrix
view_transforms[][][]. View transform generators are a more sophisticated
way to control view transforms.

<-------------------------------- view_4d --------------------------------->

Evolver toggle command. Toggles sending 4D information to geomview.


<------------------------------ view_matrix ------------------------------->

The top section of the datafile may contain an initial viewing matrix:

VIEW_MATRIX
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr

The matrix is in homogeneous coordinates with translations in the last
column. The size of the matrix is one more than the space dimension. This
matrix will be part of all dump files, so the view can be saved between
sessions. This matrix is used and set by native screen graphics ('s'
command) and only applies to internal graphics (Postscript, Xwindows, etc.)
but not external graphics (geomview). The elements may be read or set at
runtime by view_matrix[i][j], where the indices start at 1. In particular,
one can write command scripts to save and reload particular view matrices;
see saveview.cmd in the distribution package.

<----------------------- view_transform_generators ------------------------>

Listing all the view transforms is tedious and inflexible. An alternative
is to list just a few matrices that can generate transforms. See the
transform_expr command for instructions on entering the expression that
generates the actual transforms. Special Note: in the torus model, the
period translations are automatically added to the end of the list. So in
the torus model, these are always available, even if you don't have
view_transform_generators in the datafile. Syntax in the top of the
datafile:

VIEW_TRANSFORM_GENERATORS n
SWAP_COLORS
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
    ...

The number of matrices follows the keyword VIEW_TRANSFORM_GENERATORS. Each
matrix is in homogeneous coordinates, with translation in the last column.
The size of each matrix is one more than the space dimension. Individual
matrices need no special separation; Evolver just goes on an expression
reading frenzy until it has all the numbers it wants. If SWAP_COLORS is
present, facet frontcolor and backcolor will be swapped when this matrix is
applied. The internal variable transform_count records the number of
transforms, and the transform matrices are accessible at runtime as a
three-dimensional matrix view_transforms[][][].


<---------------------------- view_transforms ----------------------------->

For the display of several transformations of the surface simultaneously,
a number of viewing transformation matrices may be given in the top section
of the datafile:

VIEW_TRANSFORMS n
COLOR color
SWAP_COLORS
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
  constexpr constexpr constexpr constexpr
    ...

The transforms apply to all graphics, internal and external, and are prior
to the viewing matrix for internal graphics. The identity transform is
always done, so it does not need to be specified. The number of matrices
follows the keyword VIEW_TRANSFORMS. Each matrix is in homogeneous
coordinates, with translation in the last column. The size of each matrix
is one more than the space dimension. Individual matrices need no special
separation; Evolver just goes on an expression reading frenzy until it has
all the numbers it wants. Each matrix may be preceded by an optional color
that applies to facets transformed by that matrix. The color applies to one
transform only; it does not continue until the next color specification. If
SWAP_COLORS is present instead, facet frontcolor and backcolor will be
swapped when this matrix is applied. Transforms may be activated or
deactivated interactively with the transforms toggle. The internal variable
transform_count records the number of transforms, and the transform
matrices are accessible at runtime as a three-dimensional matrix
view_transforms[][][]. View transform generators are a more sophisticated
way to control view transforms.

<------------------------- view_transform_parity -------------------------->

view_transform_parity[]
Internal read-only array that contains 0 or 1 for transforms that don't
or do swap front and back colors.  The order of transforms is the same
as for view_transforms[][][].

<----------------------- view_transform_swap_colors ----------------------->

view_transform_swap_colors[]
Internal read-only array that contains 0 or 1 for transforms that don't
or do swap front and back colors.  The order of transforms is the same
as for view_transforms[][][]. For my debugging purposes.


<-------------------- view_transforms_use_unique_point -------------------->
<---------------------- view_transforms_unique_point ---------------------->

When view transforms are generated with transform_expr, Evolver weeds out 
duplicate transforms.  By default, "duplicate" means the same transform 
matrix, but there are circumstances where different transform matrices carry 
the surface to the same spot. view_transforms_use_unique_point toggle enables 
a mode whereby two transform matrices are deemed identical if they transform 
the point given by the vector view_transforms_unique_point[] to the same 
image point.  The standard use is to make view_transforms_unique_point[] a 
vertex on the surface being transformed, for example


   view_transforms_unique_point := vertex[5].__x;
   view_transforms_use_unique_point on;
   transform_expr "abababa";

The vector view_transforms_unique_point[] is pre-defined, so the use does not
need to define it.

<---------------------------- visibility_debug ---------------------------->

Evolver toggle command, which causes printing of verbose information
when visibility_test is on; don't use it. 
 

<---------------------------- visibility_test ----------------------------->

Evolver toggle command. Toggles an occluded-triangle test for graphics
output that uses the Painter's Algorithm to produce 2D output (PostScript,
Xwindows). This can greatly reduce the size of a PostScript file, but
inspect the output since the implementation of the algorithm may have
flaws.

<-------------------------------- volconst -------------------------------->

Body read-write attribute. A constant added to the calculated volume.
Useful for correcting for omitted parts of body boundaries. Also used
internally as a correction in the torus model , which will use the target
volume to calculate volconst internally. In the torus model, the target
volume should be set within 1/12 of a torus volume of the actual volume for
each body, so the correct volconst can be computed. Each volconst will be
adjusted proportionately when the volume of a fundamental torus domain is
change by changing the period formulas. Volconst can be set in the datafile
bodies section, or interactively by the set command or by assignment.
Examples:
  print body[1].volconst
  set body[2] volconst 1.2
  body[2].volconst := 1.2

It is best to avoid using volconst except in the torus model. Rather, use
edge content integrals so that the proper adjustments will be made if the
boundary of the surface is moved, or rebody is done.

Named quantities can also have a volconst value.

<-------------------------------- volfixed -------------------------------->

Body read-only attribute. Value is 1 if the volume of the body is fixed, 0
if not.


<----------------------------- volgrads_every ----------------------------->

Evolver toggle command. Toggles recalculating volume constraint gradients
every projection step during constraint enforcement. Good for stiff
problems.

<--------------------------------- volume --------------------------------->

Body read-only attribute. Actual volume of a body. This is the sum of
three parts, in the soapfilm model:
 1. An integral over the facets bounding the body. This is \int z dx dy
    normally, but \int (x dy dz + y dz dx + z dx dy)/3 if SYMMETRIC_CONTENT is
    in effect.
 2. Any constraint content edge integrals applying to the body.
 3. The body's volconst attribute.

In the string model, the parts are
 1. An integral over the edges bounding the body's facet. This is \int -y dx.
 2. Any constraint content vertex integrals applying to the body.
 3. The body's volconst attribute.

Body volumes can be displayed with the v command, or with standard
attribute syntax. Example:
  print body[1].volume
  foreach body where volume > 2 do print id


<--------------------------- volume_method_name --------------------------->

This top-of-datafile item, volume_method_name, specifies the name of the
pre-defined method to use as the method to compute body volumes in place
of the default edge_area method in the string model or facet_volume method
in the soapfilm model. It is optional. Developed so circular arcs can be
used in two-dimensional foams. Synonymous with area_method_name in the string
model. Usage implies converting to everything_quantities mode. Syntax:

    volume_method_name quoted_method_name

For example,

   string
   space_dimension 2
   volume_method_name "circular_arc_area"

<----------------------------------- W ------------------------------------>

Single letter main command. Toggles homothety. If homothety ON, then after
every iteration, the surface is scaled up so that the total volume of all
bodies is 1. Meant to be used on surfaces without any blowup constraints of
any kind, to see the limiting shape as surface collapses to a point.



<----------------------------------- w ------------------------------------>

Single letter main command. Tries to weed out small triangles. You will be
prompted for the cutoff area value if you don't give a value with the
command. If you enter h, you will get a histogram of areas to guide you. If
you hit RETURN with no value, nothing will be done. Some small triangles
may not be eliminable due to constraints or other such obstacles. The
action is to eliminate an edge on the triangle, eliminating several facets
in the process. Edges will be tried for elimination in shortest to longest
order. WARNING: Although checks are made to see if it is reasonable to
eliminate an edge, it is predicated on facets being relatively small. If
you tell it to eliminate all below area 5, Evolver may eliminate your
entire surface without compunction.

Graphics mode command. Toggles display of facets entirely on
constraints. For a one-sided constraint, applies to facets whose vertices
all hit the constraint. "w" stands for "wall".

<---------------------------- warning_messages ---------------------------->

To print warning messages that have been emitted during reading of the
datafile but have scrolled off the top of your screen, you may use the
command "print warning_messages".

<--------------------------------- where ---------------------------------->

Clause in element generators to specify a subset of elements.
Examples:
   list facet where color == red
   foreach edge ee where ee.length < .3 do list ee.vertex
   print max(edge where on_constraint 1, length)

<------------------------------ where_count ------------------------------->

Internal read-only variable. Number of items satisfying last "where"
condition. Prints and resets to 0 at the end of a command execution,
or when flush_counts is done. Also reset by reset_counts.

<-------------------------------- whereami -------------------------------->

Debug prompt command that prints a stack trace showing the sequence 
of function or procedure calls made to reach the current spot. 
See "breakpoint".

<--------------------------------- while ---------------------------------->

Command syntax for pre-test iteration loop. Syntax:

  WHILE expr DO command

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

<------------------------------- whitespace ------------------------------->

In the datafile, whitespace consists of spaces, tabs, commas, colons, and
semicolons. So it's fine if you want to use commas to separate coordinate
values, and colons to prettify constraint definitions. In commands,
whitespace consists of spaces and tabs. CTRL-Z is also whitespace, for the
benefit of files imported from DOS.


<-------------------------- window_aspect_ratio --------------------------->

Internal read-write variable. The ratio of the the vertical to horizontal
dimensions of the display window. If set, this locks the aspect ratio to
the given value. The window may be resized with the mouse, but the
aspect ratio will stay the same. The unset value of window_aspect_ratio
is 0; setting window_aspect_ratio to 0 will unlock the aspect ratio.
Applies also to the PostScript bounding box, if full_bounding_box is on.
Currently implemented only in Evolver with GLUT graphics.
Caveat: the window doesn't always fully follow the mouse; just keep trying.


<---------------------------------- wrap ---------------------------------->

Edge read-write attribute. When a symmetry group is in effect (such as the
torus model) and an edge crosses the boundary of a fundamental domain, the
edge is labelled with the group element that moves the edge head vertex to
its proper position relative to the tail vertex. The label is internally
encoded as an integer, the encoding peculiar to each symmetry group. Edge
wrappings are set in the datafile. The torus model has its own peculiar
wrap representation in the datafile: * for no wrap, + for positive wrap,
and - for negative wrap. Wraps are maintained automatically by Evolver
during surface manipulations. The numeric edge wrap values can be queried
with attribute syntax. Example:

  list edge where wrap != 0

Unfortunately, the torus model wraps come out rather opaquely, since one
cannot print hex. The torus wrap number is the sum of numbers for the
individual directions: +x = 1; -x = 31; +y = 64; -y = 1984; +z = 4096; -z =
127040. Caution: even though this attribute can be written by the user at
runtime, only gurus should try it.


<------------------------------ wrap_compose ------------------------------>

wrap_compose(w1,w2) : Function returning the symmetry group code for the
composition of symmetry group elements w1, w2. Useful only if a
symmetry group has been declared in the datafile.

<------------------------------ wrap_inverse ------------------------------>

wrap_inverse(w) :  Function returning the symmetry group numerical code
for the inverse of symmetry group element w. Useful only if a symmetry
group has been declared in the datafile.

<------------------------------ 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.   Useful for re-setting vertices in torus model that get too
far outside the unit cell.

<--------------------------------- writhe --------------------------------->

Named method. Description: An average crossing number calculation. This
one does have a gradient. Suggested by Hermann Gluck. Programmed by John
Sullivan. Between pairs of edges, energy is inverse cube power of distance
between midpoints of edges, times triple product of edge vectors and
distance vector.

     E = 1/d^3 * (e1,e2,d)

Element: edge. 
Parameters: none. 
Models: linear. 
Ambient dimension: 3.
Hessian: no. 
Example datafile declaration:

  quantity writhy energy method writhe global


<--------------------------------- wulff ---------------------------------->

To declare that surface area energy should be calculated with a
crystalline integrand, the top section of the datafile should contain a
line of the form

 WULFF "filename"

The double-quoted filename (with path) refers to a file giving the Wulff
vectors of the integrand. The format of the file is one Wulff vector per
line with its components in ASCII decimal format separated by spaces. The
first blank line ends the specification. Some special integrands can be
used by giving a special name in place of the file name. Currently, these
are "hemisphere" for a Wulff shape that is an upper unit hemisphere, and
"lens" for two unit spherical caps of thickness 1/2 glued together on a
horizontal plane. These two don't need separate files.

<------------------------------- hemisphere ------------------------------->
<---------------------------------- hemi ---------------------------------->
<---------------------------------- lens ---------------------------------->

One of the special types of Wulff energy.  See "wulff".

<------------------------------ wulff_energy ------------------------------>

Named method. Description: Method version of wulff energy. If Wulff
filename is not given in top section of datafile, then the user will be
prompted for it. 

Element: facet. 
Parameters: none. 
Models: soapfilm; linear. 
Ambient dimension: 3. 
Hessian: no. 
Example datafile declaration:

   wulff "crystal.wlf"
   quantity wolf energy method wulff_energy global


<----------------------------------- X ------------------------------------>

Single letter main command. List the current extra attributes, including
name, dimension, type, size in bytes, and offset within the element
structure. Some internal attributes are also listed, whose names begin with
a double underscore.


<----------------------------------- x ------------------------------------>

Single letter main command. Same as q. Exit Evolver, or start new surface.

Graphics mode command. Exit from graphics mode, and return to main
command mode.

Vertex attribute.  Alone, the first coordinate of the vertex.  With index,
the indexed coordinate.  For treating coordinates as a single vector,
use the vertex attribute __x.

Edge attribute.  Alone, the first component of the edge vector.  With index,
the indexed component.  For treating the edge vector as a single vector,
use the edge attribute edge_vector.

Facet attribute.  Alone, the first component of the facet normal vector
(normalized so length is equal to facet area).  With index, the indexed 
component.  For treating the facet normal as a single vector,
use the facet attribute facet_normal.

<----------------------------------- x1 ----------------------------------->
<----------------------------------- x2 ----------------------------------->
<----------------------------------- x3 ----------------------------------->
<----------------------------------- x4 ----------------------------------->
<----------------------------------- x5 ----------------------------------->
<----------------------------------- x6 ----------------------------------->
<----------------------------------- x7 ----------------------------------->
<----------------------------------- x8 ----------------------------------->

Vertex attribute, alternate notation for x[n] or __x[n].
x1 is x, x2 is y, x3 is z.

Edge attribute, alternate notation for x[n] or edge_vector[n].

Facet attribute, alternate notation for x[n] or facet_normal[n].

<--------------------------- xyz symmetry group --------------------------->

The orientation-preserving subgroup of cubocta. Same representation.

<----------------------------------- y ------------------------------------>

Single letter main command. Torus duplication. In torus model, prompts for
a period number (1,2, or 3) and then doubles the torus unit cell in that
direction. Useful for extending simple configurations into more extensive
ones.

Vertex attribute.  The second coordinate of the vertex.  For treating 
coordinates as a single vector, use the vertex attribute __x.

Edge attribute. The second component of the edge vector.  For treating 
the edge vector as a single vector, use the edge attribute edge_vector.

Facet attribute.  The second component of the facet normal vector
(normalized so length is equal to facet area).  For treating the 
facet normal as a single vector, use the edge attribute facet_normal.

<---------------------------------- ysmp ---------------------------------->

Evolver toggle command. Toggles between Yale Sparse Matrix Package
routines for factoring hessians, and my own minimal degree factoring.
Default is YSMP off.


<----------------------------------- z ------------------------------------>

Single letter main command. Do curvature test on QUADRATIC model. Supposed
to be useful if you're seeking a surface with monotone mean curvature.
Currently checks angle of creases along edges and samples curvature on
facet interiors. Orientation is with respect the way facets were originally
defined. Deprecated.

Graphics mode command. Zoom. Expands image by factor, default 1.2.
Examples: `z' zooms by 1.2, `2z' zooms by 1.44, '2.0z' zooms by 2.

Vertex attribute.  The third coordinate of the vertex.  For treating 
coordinates as a single vector, use the vertex attribute __x.

Edge attribute. The third component of the edge vector.  For treating 
the edge vector as a single vector, use the edge attribute edge_vector.

Facet attribute.  The third component of the facet normal vector
(normalized so length is equal to facet area).  For treating the 
facet normal as a single vector, use the edge attribute facet_normal.


<----------------------------------- Z ------------------------------------>

Single letter main command. Zooms in on a vertex. Asks for vertex number
and radius. Number is as given in vertex list in datafile. Beware that
vertex numbers change in a dump (but correct current zoom vertex number
will be recorded in dump). Eliminates all elements outside radius distance
from vertex 1. New edges at the radius are made FIXED. Meant to investigate
tangent cones and intricate behavior, for example, where wire goes through
surface in the overhand knot surface. Zooming is only implemented for
surfaces without bodies.

<------------------------------ zener_coeff ------------------------------->

See "zener_drag".

<------------------------------- zener_drag ------------------------------->

Evolver toggle command. Toggles Zener drag feature, in which the velocity
of the surface is reduced by a magnitude given by the variable zener_coeff,
and the velocity is set to zero if it is smaller than zener_coeff.

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


<------------------------------ zoom_radius ------------------------------->

Datafile keyword setting the current zoom radius. Used in dump files after
a zoom command has been given.  See "Z".


<------------------------------ zoom_vertex ------------------------------->

Datafile keyword setting the current zoom vertex. Used in dump files after
a zoom command has been given.  See "Z".