|
|
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.
g 10; r; g 10; u
myc := { print 5;
g 10;
if qwer < foo then print 3 else { print 2; print 4; };
aa := 23
}
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"
}
g 10
U 2
{ g 20; u; V; u } 20
myc := { g 20; V }; myc 10
quantityname.modulus := expr quantityname.target := expr quantityname.volconst := expr
instancename.modulus := expr
identifier := commandThe shortest complete command on the right side is used. Thus "gg := g 10; u" would give gg the same value as "gg := g 10". It is wise to use braces to enclose the command on the right side so the parser can tell it's a command and not an expression. Also multiline commands then don't need linesplicing. Do not try to redefine single-letter commands this way; use :::=. Example:
gg := {g 10; u}
identifier := expr identifier := stringexprIf 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
command >> stringexprThe output of a command can be redirected to a file with the symbol '>>>'. This overwrites an existing file. Syntax:
command >>> stringexprRedirection with `>' is not available due to the use of `>' as an comparison operator. The output of a command can be piped to a system command using the unix-style pipe symbol `|'. Syntax:
command | stringexprThe stringexpr is interpreted as a system command.
On systems (such as DOS, Windows, and Macs) without true piping, the string is interpreted as a filename, so output goes directly to a file instead of a command, replacing any old contents. Examples:
list facets | "more"
list vertices | "tee vlist" ; g 10 | "tee g.out"
{ {g 10; u } 20 } >> "logfile"
{foreach facet do print area} | "cat >areafile"
IF expr THEN command IF expr THEN command ELSE commandexpr is true if nonzero. Parentheses around expr are not needed, but do not hurt. Do not use a semicolon to end the first command. Example:
if max(edges,length) > 0.02 then {r; g 100} else g 4
WHILE expr DO commandexpr is true if nonzero. Parentheses around expr are not needed, but do not hurt. Example:
count := 0
while count < 10 do { g 10; u; print total_energy; count := count + 1 }
DO command WHILE exprexpr is true if nonzero. Parentheses around expr are not needed, but do not hurt. Example:
do { oldenergy := total_energy; g 10 }
while (oldenergy-total_energy < 1e-6)
FOREACH generator DO commandExamples:
foreach vertex do print x^2 + y^2 + z^2
foreach edge ee where ee.dihedral > .4 do {
printf "id %g\n",id;
foreach ee.vertex do printf " %g %g %g\n",x,y,z;
}
BREAK BREAK nThe first form exits the innermost current loop. The second form exits n loops. Note: Commands with repetition counts do not qualify as loops. Example:
foreach vertex do { print x; if y < 0 then break; print z }
CONTINUE CONTINUE nThe 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;
}
}
if ( acc < 1.e-10 ) then return;
elementgen name where exprelementgen may be
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)
AREAWEED exprSame as 'w' command, except does not need interactive response. Also same as "delete facets where area < expr". Examples:
areaweed 0.001 areaweed 2*min(facet,area)
CHDIR stringexprIn MS-Windows, use a front slash '/' or a double backslash '\\' instead of a single backslash as the path character. Example:
chdir "/usr/smith/project"
DEFINE elementtype ATTRIBUTE name REAL|INTEGER [dim]where elementtype is vertex, edge, facet, or body; name is an identifier of your choice; and [dim] is an optional expression for the vector dimension (with the brackets). There is no practical distinction between real and integer types at the moment, since everything is stored internally as reals. But there may be more datatypes added in the future. It is not an error to redefine an attribute that already exists, as long as the definition is the same. Extra attributes are inherited by elements of the same type generated by subdivision. Examples:
define edge attribute charlie real define vertex attribute oldx real[3]It is also possible to use DEFINE to declare a variable without giving it an initial value. This is primarily a mechanism to be sure a variable is defined before use, without overwriting an existing value. If the variable is new, the initial value is zero or the null string. Syntax:
DEFINE name REAL|INTEGER|STRING}
DELETE generatorDeletes edges by shrinking the edge to zero length (as in the tiny edge weed command t) and facets by eliminating one edge of the facet. Facet edges will be tried for elimination in shortest to longest order. Edges will not be deleted if both endpoints are fixed, or both endpoints have different constraints or boundaries from the edge. DELETE maintains the continuity and connectedness of the surface, as opposed to DISSOLVE. Example:
delete facets where area < 0.0001
DISSOLVE generatorThe effect is the same as if the line for the element were erased from a datafile. Hence no element will be dissolved that is used by a higher dimensional element. (There are two exceptions: dissolving an edge on a facet in the string model, and dissolving a facet on a body in the soapfilm model.) Thus "dissolve edges; dissolve vertices" is safe because only unused edges and vertices will be dissolved. No error messages are generated by doing this. Good for poking holes in a surface. Example:
dissolve facets where original == 2; dissolve edges; dissolve verticesThus "dissolve edges; dissolve vertices" is safe because only unused edges and vertices will be dissolved. No error messages are generated by doing this.
DUMP filenameThe filename is a string. With no filename, dumps to the default dump file, which is the current datafile name with ".dmp" extension. Same as the 'd' command, except 'd' requires a response from the user for the filename. Examples:
dump "foo.dmp" dump sprintf "%s.%g.dmp",datafilename,counter
EDGESWAP edgegeneratorIf 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:
edgeswap edge[22] edgeswap edge where color == red
EDGEWEED exprSame as 't' command, except does not need interactive response. Same as "delete edge where length < expr".
EIGENPROBE expr EIGENPROBE(expr,expr)The first form prints the number of eigenvalues of the energy Hessian that are less than, equal to, and greater than expr. It is OK to use an exact eigenvalue (like 0, often) for the value, but not really recommended. Useful for probing stability. Second form will further do inverse power iteration to find an eigenvector. The second argument is the limit on the number of iterations. The eigenvalue will be stored in the last_eigenvalue internal variable, and the eigenvector can be used by the move command. The direction of the eigenvector is chosen to be downhill in energy, if the energy gradient is nonzero.
FIX generatorExample:
fix vertices where on_constraint 2Can also convert a parameter from optimizing to non-optimizing. Example:
fix radiusCan also convert a named quantity from info_only to fixed. See also unfix.
geompipe stringexprThe 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 stringexprwill send a command to an already started geomview. This string must be in the geomview command language, for which consult the geomview documentation.
help keywordThe keyword need not be in quotes, unless there are embedded blanks. After printing the help section exactly matching the keyword, a list of related terms is printed. These are just the keywords containing your keyword as a substring.
For help to work, the directory containing the Evolver HTML files must be in the EVOLVERPATH environment variable.
The built-in browser is in no way a complete substitute for using a full-fledged browser such as Netscape or Mosaic.
HESSIAN_SEEK maxscalewhere maxscale is an optional upper bound for the distance to seek. The default maxscale is 1, which corresponds to a plain hessian step. The seek will look both ways along the direction, and will test down to 1e-6 of the maxscale before giving up and returning a scale of 0. This command is meant to be used when the surface is far enough away from equilibrium that the plain hessian command is unreliable, as hessian_seek guarantees an energy decrease, if it moves at all.
HISTOGRAM(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))
LAGRANGE nwhere n is the lagrange_order, which is between 1 and some built-in maximum (currently 8). This command can also convert between Lagrange models of different orders. Note that lagrange 1 gives the Lagrange model of order 1, which has a different internal representation than the linear model. Likewise, lagrange 2 does not give the quadratic model.
LANCZOS 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.
LIST generatorOn unix systems, piping to more can be used for long displays. Examples:
list edges where id <= 12 list vertices | "more" list vertices where x < 1 and y > 2 and z >= 3 | "tee vfile"
LOAD filenameTerminates the current surface and loads a new datafile. The filename is the datafile name, and can be either a quoted string or a string variable. This completely re-initializes everything, including the command interpreter. In particular, the currently executing command ends. Useful only as the last command in a script.
LOGFILE stringexprStarts recording all input and output to the file specified by stringexpr, which must be a quoted string or a string variable or expression. Appends to an existing file. To end logging, use logfile off.
METIS n KMETIS n
MOVE exprMoves 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.
newid := NEW_VERTEX(expr, expr,...)Examples:
newid := new_vertex(0,0,1) newid := new_vertex(pi/2,0,max(vertex,x))
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;
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;
newid := NEW_BODYThe body is created with no facets. Use the set facet frontbody and set facet backbody commands to install the body's facets. The new body has the same default properties as if it had been created in the datafile with no attributes, so you will need to explicitly add any attributes you want, such as density or target volume. Example:
newb := new_body set facet frontbody newb where color == red
NOTCH exprNotches all edges with dihedral angle greater than given value. Same as 'n' command, or
foreach edge ee where ee.dihedral > expr do refine ee.facetNotching is done by adding a vertex in the middle of adjacent facets. Should be followed by equiangulation.
OMETIS n // n is smallest partition size OMETIS // defaults to n = 100
OPTIMIZE expr
POSTSCRIPT stringexprThe string gives the name of the file; a .ps extension will be appended if it is missing. It is the same as the P option 3 command, except that there are no interactive responses needed. Output options are controlled by the pscolorflag, gridflag, crossingflag, and labelflag toggles.
PRINT expr PRINT stringexpr PRINT commandnamePRINT expr can also be used inside an expression, where it prints the expression and evaluates to the value of its expression. Examples:
print datafilename
print max(edge,length)
print max(vertex, print (x^2+y^2+z^2) )
gg := {list vertex where id < 10; g 5}
print gg
PRINTF string,expr,expr,...Prints to standard output using the standard C sprintf function. Only string and real-valued numeric expressions are valid, so the format string should use only %s, %f and %g formats. Do not use %d format for things like element id's, because these are automatically converted to reals in expressions; use %g to print integral values. The format string can be a string variable or a quoted string. Example:
printf "This is %s with total energy %f\n",datafilename,total_energy
RAWEST_VERTEX_AVERAGE generatorExample:
rawest_vertex_average vertex[3]
RAW_VERTEX_AVERAGE generatorExample:
raw_vertex_average vertex where valence == 6
READ filenameThe filename can be either a quoted string or a string variable. The effect is as if the file were typed in at the keyboard. Hence main commands, responses to commands, and graphics mode commands can be included. Read commands may be nested. On the occurence of an error, input reverts to the original standard input. Example:
read "zebra.cmd"
REFINE generatorSubdivides the generated edges or facets. Subdivides edges by putting a vertex in the middle of each edge, and splitting neighboring facets in two in the soapfilm model. It is the same action as the long edge subdivide command (command l). Facets will be subdivided by putting a vertex in the center and creating edges out to the old vertices. It is strongly suggested that you follow this with equiangulation to nicen up the triangulation. Edge refinement is better than facet refinement as facet refinement can leave long edges even after equiangulation. Example:
refine edges where not fixed and length > .1
RITZ(expr,expr)Applies powers of inverse shifted Hessian to a random subspace to calculate eigenvalues near the shift value. First argument is the shift. Second argument is the dimension of the subspace. Prints out eigenvalues as they converge to machine accuracy. The first eigenvalue is subsequently available in the last_eigenvalue internal variable. This may happen slowly, so you can interrupt it by hitting whatever your interrupt key is, such as CTRL-C, and the current values of the remaining eigenvalues will be printed out. Good for examining multiplicities of eigenvalues. It is legal to shift to an exact eigenvalue, but not wise, as they will not be printed. See the Hessian tutorial for more. Example: To get the lowest 5 eigenvalues of a Hessian you know is positive definite:
ritz(0,5)
define vertex attribute vertex_order_key real
define edge attribute edge_order_key real
define facet attribute facet_order_key real
define body attribute body_order_key real
define facetedge attribute facetedge_order_key real
reorder := {
set vertex vertex_order_key x+y+z;
set edge ee edge_order_key min(ee.vertex,vertex_order_key);
set facetedge fe facetedge_order_key fe.edge[1].edge_order_key;
set facet ff facet_order_key min(ff.vertex,vertex_order_key);
set body bb body_order_key min(bb.facet,facet_order_key);
reorder_storage;
}
SADDLE exprwill limit the step size to expr. The motion vector is available afterwards through the move command.
SET elementtype [name] attrib expr1 where expr2 SET elementtype.attrib expr1 where expr2 SET name attrib expr SET name.attrib expr SET quantityname attrib expr SET instancename attrib exprThe first two forms set the value of the attribute attrib to the value expr1 for all elements of the given type that satisfy expr2. elementtype can be vertex, edge, facet, or body, or any element generator without a where clause. The optional name refers to the element under consideration, and can be used in expr1 and expr2 to refer to attributes of that element. Even without name, attributes of the element can be referred to if the references are not nested in element generators in expr1 or expr2. The next two forms can be used inside an element generator which defines name. When name is not used, a '.' can be used, for those who like that sort of thing. SET can change the following attributes: constraint, coordinates, density, orientation, non-global named quantity or named method, user-defined extra attributes, body target volume, body volconst, fixed, frontbody, backbody, pressure, color, frontcolor, backcolor, and opacity (for the appropriate type elements). Fixed, named quantity, and named method attributes are just toggled on; they do not need the first expr. For constraint, the expr is the constraint number. Examples:
set facets density 0.3 where original == 2 set vertices x 3*x where id < 5 // multiplies x coordinate by 3 set body target 5 where id == 1 // sets body 1 target volume to 5 set vertices constraint 1 where id == 4 set facet color clear where original < 5 foreach facet ff do set ff color red define vertex attribute weight real; set vertex weight 3 set vertex quantity my_quantity set vertex[1].facet color redNote 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
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.valuerather than set myquant target value. Also see unset.
show edges where expr show facets where exprThe default is to show all facets, and to show all special edges: fixed edges, constraint edges, boundary edges, and edges without exactly two adjacent facets. The defaults can be restored with "show facets" and "show edges". Some graphics modules (like geomview) can show edges of facets on their own initiative. This is separate from the edge show criterion here; to show the colors of edges, the edges must satisfy the criterion. Show causes graphics to be redrawn. If a graphics display is not active, show will start screen graphics. Show_expr is the same as show in setting the show expressions, except it does not start graphics. Show alone will just start screen graphics. Examples:
show facets where color == red show edges where 1 show edges where color != black
show_trans "rrdd5z"
SPRINTF stringexpr,expr,expr,...Example:
dumpname := SPRINTF "file%04g.dmp",counter
SYSTEM stringexprInvokes a subshell to execute the given command, on systems where this is possible. Command must be a quoted string or a string variable. Will wait for command to finish before resuming.
TRANSFORM_DEPTH nwhere n is the maximum number of generators to multiply together. This will toggle immediate showing of transforms, if they are not already being shown.
| a | Generates set {I,a}. |
| AB | Generates all ordered products of pairs from A and B. |
| nA | Generates all n-fold ordered products. |
| A|B | Generates union of sets A and B. |
| (A) | Grouping; generates same set as A. |
transform_expr "3(a|b|c)" //all products of 3 or fewer generators transform_expr "abcd" // generates 16 transformsAll duplicate transforms are removed, so the growth of the sets does not get out of hand. Note the identity transform is always included. The letter denoting a single generator may be upper or lower case. The order of generators is the same as in the datafile. In the torus model, transforms along the three period vectors are always added to the end of the list of generators given in the datafile. If 26 generators are not enough for somebody, let me know. The current value of the expression may be accessed as a string variable, and the number of transformations generated can be accessed as transform_count. For example,
print transform_expr print transform_count
UNFIX generatorExample:
unfix vertices where on_constraint 2Can also convert a parameter from non-optimizing to optimizing. Example:
unfix radiusCan also convert a named quantity from fixed to info_only.
UNSET elements [name] attrib where clauseUnsettable attributes are fixed (vertices, edges, or facets) , body target volume, body pressure, body gravitational density, non-global named quantities, non-global named methods, level-set constraints, parametric boundary. frontbody, or backbody. A use for the last is to use a boundary or constraint to define an initial curve or surface, refine to get a decent triangulation, then use "unset vertices boundary 1" and "unset edges boundary 1" to free the curve or surface to evolve. The form "unset facet bodies ..." is also available to disassociate given facets from their bodies. Examples:
unset body[1] target unset vertices constraint 1; unset edges constraint 1
VERTEX_AVERAGE vertex_generatorThe action is the same as the V command, except that each new vertex position is calculated sequentially, instead of simultaneously, and an arbitrary subset of vertices may be specified. Fixed vertices do not move. Examples:
vertex_average vertex[2] vertex_average vertex where id < 10 vertex_average vertex vv where max(vv.facet,color==red) == 1
wrap_vertex(vexpr,wexpr)In a symmetry group model, transforms the coordinates of vertex number vexpr by symmetry group element wexpr and adjusts wraps of adjacent edges accordingly.
ZOOM integer exprZooms in on vertex whose id is the given integer, with radius the given expr. Same as the 'Z' command, but not interactive.