#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 = constexpr
This 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.
OPTIMIZING_PARAMETER identifier = constexpr PDELTA = constexpr SCALE = 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 scale 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).
"Optimising_parameter" is a synonym. Note: the natural scale factor for
gradient descent with optimizing parameters may be much different than
without, and the evolution may be awkward when far from equilibrium.
Therefore, parameters have a "scale" attribute that multiplies the
parameter change. It may set in the datafile.
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.
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.
SYMMETRY_GROUP "name""name" is a double-quoted name that is matched against the list of defined symmetry groups.
QUADRATICThe only effect on datafile syntax is that the edge section may list edge midpoint vertices.
SIMPLEX_REPRESENTATIONThe main effect on the datafile is that faces are defined by oriented vertex lists rather than edge lists.
DEFINE elementtype ATTRIBUTE name type dimwhere 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. Examples:
define edge attribute charlie real define vertex attribute oldx real[3]
SCALE_LIMIT valuein the top section of the datafile. The upper bound can be changed at runtime with the m command.
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.
CONSTRAINT n [GLOBAL] [CONVEX] [NONNEGATIVE] [NONPOSITIVE] 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 an integer between 0 and MAXCONSTR (currently 127). 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. 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.
Warning: These integrals are evaluated only for edges which are on the constraints and both of whose endpoints are on the constraints. It is a bad idea to put any of these integrals on one-sided constraints, as both endpoints must actually hit the constraint to count.
CONSTRAINT_TOLERANCE const_exprSets the value of the internal variable constraint_tolerance.
GRAVITY_CONSTANT valueThe default value is 1.
GAP_CONSTANT valueThe default value is 1. Synonym: spring_constant.
BOUNDARY n PARAMETERS k [CONVEX] X1: expr X2: expr X3: exprThis defines boundary number n, where n is an integer between 1 and MAXBDRY (currently 20) 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 a . level set constraint.
INTERP_BDRY_PARAMThis should be done only if there are no periodic parameters.
QUANTITY name ENERGY | FIXED value | INFO_ONLY [LAGRANGE_MULTIPLIER constexpr] [TOLERANCE constexpr] [MODULUS constexpri] 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]
[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.
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:
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.
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.
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 at runtime by view_matrix[i][j], where the indices start at 1.
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.
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.
SQUARED_CURVATURE modulusThe modulus is a multiplier for the energy. This is the original squared mean curvature energy; later versions are in the squared curvature named methods.
SQUARED_GAUSSIAN_CURVATURE modulusThe modulus is a multiplier for the energy. Synonyms: square_gaussian_curvature, sqgauss
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.
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.
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.
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.