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 = 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.
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 = constexpr 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.
CONSTRAINT n [GLOBAL] [CONVEX] [NONNEGATIVE] [NONPOSITIVE] [NONWALL] [CONTENT_RANK n] 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, and the various ``star'' squared mean
curvature methods will not regard this constraint as a mirror plane.
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.
The constraint attribute content_rank is 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.
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:
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 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 method 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 of individual elements
may be set at runtime with the "set" command, for example
set facet[123] orientation -1
Each method may have various parameters to specialize it to an instance. Currently the only parameters specified are:
SCALAR_INTEGRAND: expr
VECTOR_INTEGRAND:
Q1: expr
Q2: expr
Q3: expr
FORM_INTEGRAND:
Q1: expr
Q2: expr
Q3: expr
...
Q1 through Q6.PARAMETER_1 constexprK_FORM_ORDER constexprFORM_INTEGRAND when needed.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 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.
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 followed by expressions for the components
of each period vector:
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 = 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.pscaleAt runtime, one may use the p_force attribute of the variable to find the rate of change of energy with respect to the variable before constraint corrections, and the p_velocity attribute to find the rate of change of the variable with respect to the scale factor of the 'g' command. Example:
g
print height.p_velocity
"Optimising_parameter" is a synonym.
GAP_CONSTANT valueThe default value is 1. Synonym: spring_constant.
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.
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.
evolver_version "2.10"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, 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_nameFor example,
string space_dimension 2 length_method_name "circular_arc_length"
area_method_name, specifies
the name of the pre-defined method to use 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.
Syntax:
area_method_name quoted_method_nameFor example,
string space_dimension 2 area_method_name "circular_arc_area"
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_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 vertex_normal 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.
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.
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.
MERIT_FACTOR is present, 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.
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, and is available at runtime in the read-write variable square_gauss_modulus. Synonyms: 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
vertices_predicted 3074
edges_predicted 9216
facets_predicted 6144
bodies_predicted 1
facetedges_predicted 18432
vertices_predicted 3074
edges_predicted 9216
facets_predicted 6144
bodies_predicted 1
facetedges_predicted 18432
vertices_predicted 3074
edges_predicted 9216
facets_predicted 6144
bodies_predicted 1
facetedges_predicted 18432
vertices_predicted 3074
edges_predicted 9216
facets_predicted 6144
bodies_predicted 1
facetedges_predicted 18432
vertices_predicted 3074
edges_predicted 9216
facets_predicted 6144
bodies_predicted 1
facetedges_predicted 18432
vertices_predicted 30748
edges_predicted 92166
facets_predicted 61446
bodies_predicted 2048
facetedges_predicted 184320
method_instances_predicted 4098
quantities_predicted 2050
vertices_predicted 30748
edges_predicted 92166
facets_predicted 61446
bodies_predicted 2048
facetedges_predicted 184320
method_instances_predicted 4098
quantities_predicted 2050
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.
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 command prints the datafile format listing of edges.
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.
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.
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.