NOTE: Usually a formula can occur anyplace a number is legal (except element numbers, constraint numbers, etc). Some formulas are stored as formulas and re-evaluated at each use; examples include constraint, boundary, and quantity formulas. Others, such as vertex coordinates, are evaluated when the datafile is read, and only the numeric value stored. Thus if a user defines a vertex coordinate as 3*width, then changing the value of the variable width at runtime will not affect the vertex. If you are not clear on which interpretation applies in a certain spot, dump the datafile and look at the spot to see if a formula or number was dumped.
#include "common.stuff"
#DEFINE identifier stringidentifier 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.
PARAMETER identifier = constexprThis declares identifier to be a variable with the given initial value. The value may be changed at runtime with the A command, or by assignment. Variables may be used in any subsequent expression or constant expression. Changing variables defined here results in automatic recalculation of the surface when autorecalc is been toggled on. Hence only variables needed in other top section declarations should be defined here.
CONSTRAINT n [GLOBAL] [CONVEX] [NONNEGATIVE] [NONPOSITIVE] [NONWALL] FORMULA FUNCTION expr [ENERGY: E1: expr E2: expr E3: expr] [CONTENT: C1: expr C2: expr C3: expr]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, exprThe 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.
BOUNDARY n PARAMETERS k [CONVEX] X1: expr X2: expr X3: exprThis 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. Energy and content integrals for boundaries are implemented, with the same syntax as for level set constraints.
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:
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.
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:
STRINGThe default dimension 2 soapfilm model is equivalent to using
SOAPFILMIn general, the line
SURFACE_DIMENSION ndefines 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.
SPACE_DIMENSION nThe 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.
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 oldx 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.
QUADRATICThe only effect on datafile syntax is that the edge section may list edge midpoint vertices.
GRAVITY_CONSTANT valueThe default value is 1.
TORUSAll 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_FILLEDshould be used instead to prevent degenerate volume constraints.
PERIODS expr expr expr expr expr expr expr expr exprThe 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.
VIEW_MATRIX constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexpr constexprThe 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_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_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[][][].
SCALE_LIMIT valuein 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.
OPTIMIZING_PARAMETER identifier = constexpr PDELTA = constexpr PSCALE = constexprSuch 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.
GAP_CONSTANT valueThe default value is 1. Synonym: spring_constant.
keep_originalsin the top of the datafile has the same effect as the -i command line option, which is to keep the id numbers internally the same as in the datafile, instead of renumbering them in the order they are read in.
CONSTRAINT_TOLERANCE const_exprSets the value of the internal variable constraint_tolerance.
SYMMETRY_GROUP "name""name" is a double-quoted name that is matched against the list of defined symmetry groups.
length_method_name quoted_method_nameFor example,
string space_dimension 2 length_method_name "circular_arc_length"
area_method_name quoted_method_nameFor example,
string space_dimension 2 area_method_name "circular_arc_area"
volume_method_name quoted_method_nameFor example,
string space_dimension 2 volume_method_name "circular_arc_area"
HESSIAN_SPECIAL_NORMAL_VECTOR c1: expr c2: expr c3: exprOne can use vertex attributes in the expressions. Beware that hessian_special_normal also applies to the normal calculated by the vertexnormal attribute and the normal used by regular vertex averaging.
SIMPLEX_REPRESENTATIONThe main effect on the datafile is that faces are defined by oriented vertex lists rather than edge lists.
LOAD_LIBRARY "filename"where the double-quoted filename is the library. The current directory and the EVOLVERPATH will be searched for the library.
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.
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.
PRESSURE constexprspecifies that bodies are compressible and the ambient pressure is the value of constexpr. The default is that bodies with given volume are not compressible.
INTERP_BDRY_PARAMThis should be done only if there are no periodic parameters.
MOBILITY_TENSOR expr expr expr expr expr expr expr expr expror
MOBILITY exprThe 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.
METRIC expr expr expr expr expr expr expr expr expror
CONFORMAL_METRIC expror
KLEIN_METRICThe 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.
SQUARED_CURVATURE modulusThe modulus is a multiplier for the energy, and is available at runtime in the read-write variable sq_curvature_modulus. This is the original squared mean curvature energy; later versions are in the squared curvature named methods.
In the string model, the power of the curvature is controlled by the internal read-write variable curvature_power.
SQUARED_GAUSSIAN_CURVATURE modulusThe modulus is a multiplier for the energy. Synonyms: square_gaussian_curvature, sqgauss
SUPPRESS_WARNING numberwhere 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
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.
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 command prints the datafile format listing of edges.
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.
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 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.