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|/|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: / = | dA. / In discrete terms, the inner product takes the form of a square matrix M such that = 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".