1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901

<!DOCTYPE HTML>
<html><head><TITLE>Surface Evolver Documentation  Mathematical model</title>
<link rel="stylesheet" type="text/css" href="evdocstyle.css" />
<meta httpequiv="ContentType" content="text/html;charset=utf8" >
</head>
<BODY>
<!NewPage>
<h1 class="center">
<a href="http://www.susqu.edu/brakke/evolver/evolver.htm" class="comic">
Surface Evolver</a> Documentation</h1>
<a href="evolver.htm#doctop">Back to top of Surface Evolver documentation.</a>
<a href="index.htm">Index.</a>
<a id="models"></a>
<h1> Surface models. </h1>
The Surface Evolver can handle several different models of
surfaces. In fact, there are several different categories
of models regarding different features, so
one variety of each category is active. However, some combinations are
<a href="#incompatiblemodels">incompatible</a>.
<h3>Model categories:</h3>
<ul>
<li><a href="#combinatorics">Surface representation</a>
<ul>
<li><a href="#stringmodel">String model</a>
<li><a href="#soapfilmmodel">Soapfilm model</a> (default)
<li><a href="#simplexmodel">Simplex model</a>
</ul>
<li><a href="#elementrepresentation">Representation of surface elements</a>
<ul>
<li><a href="#linearmodel">Linear model</a> (default)
<li><a href="#quadraticmodel">Quadratic model</a>
<li><a href="#Lagrangemodel">Lagrange model</a>
</ul>
<li><a href="#spacedimension">Ambient space dimension</a> (default 3)
<li><a href="#symmetries">Symmetries</a>
<ul>
<li><a href="#defaultsymmetry">No symmetry</a> (default)
<li><a href="#torusmodel">Torus model</a>
<li><a href="#symmetrygroups">Symmetry groups</a>
</ul>
<li><a href="#metric">Metric</a>
<ul>
<li><a href="#Euclideanmetric">Euclidean metric</a> (default)
<li><a href="#Riemannianmetric">Riemannian metric</a>
<li><a href="#conformalmetric">Conformal metric</a>
<li><a href="#Kleinhyperbolicmetric">Klein hyperbolic metric</a>
</ul>
<li><a href="#mobility">Mobility</a>
<ul>
<li><a href="#unitmobility">Unit mobility</a> (default)
<li><a href="#areanormalization">Areaweighted mobility</a>
<li><a href="#userdefinedmobility">Userdefined mobility</a>
</ul>
</ul>
<hr>
<a id="incompatiblemodels"></a><h2>Incompatible models</h2>
The following combinations of <a href="#models">surface models</a>
are incompatible:
<ul>
<li> <a href="#simplexmodel">Simplex model</a> and
<a href="#torusmodel">torus model</a> or other <a href="#symmetrygroups">
symmetry group</a>. This is because the simplex model does not have
the necessary edges to carry the symmetry wraps.
</ul>
<hr>
<hr>
<a id="combinatorics"></a><h2>Surface representation and combinatorics
</h2>
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.
<ul>
<li><a href="#stringmodel">String model</a> for dimension 1 surface.
<li><a href="#soapfilmmodel">Soapfilm model</a> (default) for dimension 2 surface.
<li><a href="#simplexmodel">Simplex model</a> for dimension 3 or higher surface.
</ul>
<hr>
<a id="stringmodel"></a><h2>String model</h2>
The term "string model" means that the surface is onedimensional.
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.
<hr>
<a id="soapfilmmodel"></a><h2>Soapfilm model</h2>
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 Evolverspeak, 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.
<p>
Internally, the surface is held together by a set of structures called
"facetedges". There is one such structure for each incidence of an
edge on a facet. There is a doubly linked list of facetedges around each
facet, so edges can be traversed in order, and there is a doublylinked
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.
<hr>
<a id="simplexmodel"></a><h2>Simplex model</h2>
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 k1 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.
<p>
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 <a href="#stringmodel">string</a> or <a href="#soapfilmmodel">
soapfilm</a> models.
If the domain is not 3dimensional, then 'SPACE_DIMENSION n'
must also be included.
The datafile edges section is optional. Each
facet should list k+1 vertex numbers. Nonsimplicial facets are
not allowed. See the sample datafile simplex3.fe.
<p>
Most features are not implemented.
The <a href="#quadraticmodel">quadratic model</a> is not allowed,
but the <a href="#Lagrangemodel">Lagrange model</a> is.
Vertices may be FIXED.
Constraints are allowed, with energy integrands.
Several basic named quantity methods work.
No <a href="#torusmodel">torus model</a>
or <a href="#symmetrygroups">symmetry groups</a>.
No changing of surface topology or combinatorics is allowed except
global refining with the
<a href="single.htm#r">r</a> command.
Refining subdivides each simplex 1edge, 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.
<hr>
<hr>
<a id="elementrepresentation"></a><h2>Representation of surface elements</h2>
A surface is represented by a finite element method, where each element
is a simplex. The simplest types of elements are just straight line segments
and flat triangles. These combine to represent a piecewise linear surface,
for which calculated quantities generally have an error of order h^2 compared
to the ideal smooth surface, where h is the linear size of an element.
Various ways of representing more accurate curved elements exist, and
Evolver implements a couple of versions of what are called "Lagrange elements".
<ul>
<li><a href="#linearmodel">Linear model</a> (default)
<li><a href="#quadraticmodel">Quadratic model</a>
<li><a href="#Lagrangemodel">Lagrange model</a>
</ul>
<hr>
<a id="linearmodel"></a><h2>Linear model</h2>
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 <a href="#soapfilmmodel">
soapfilm model</a>) is defined by its three vertices. This is the
default. Quadratic or Lagrange models may be changed to linear
with the <a href="single.htm#M">M 1</a> or <a href="commands.htm#linear">
linear</a> commands. An exception is if the
<a href="quants.htm#spherical_arc_length">spherical_arc_length</a>
method is used for <a href="datafile.htm#length_method_name">length_method_name
</a> in the <a href="#stringmodel">string model</a>, in which case edges
are computed and drawn on a sphere centered at the origin.
<hr>
<a id="quadraticmodel"></a><h2>Quadratic model</h2>
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.
<p>
A special case is circular arc mode, which is effective in quadratic mode
in the string model with the <a href="quants.htm#circular_arc_length">
circular_arc_length</a> method used for
<a href="datafile.htm#length_method_name">length_method_name</a>.
Then edges are calculated and drawn as exact circular arcs through
their three vertices.
<p> The smoothness of graphing of curved quadratic edges can be
controlled with the internal variable
<a href="syntax.htm#string_curve_tolerance"><code>string_curve_tolerance</code></a>,
which is the desired angle in degrees between successive graphed segments
making up the edge.
<p>
The quadratic model can be invoked by putting the
<a href="datafile.htm#quadraticdecl">QUADRATIC</a> keyword
in the top section of the datafile or
by using the <a href="commands.htm#quadratic">quadratic</a> or
<a href="single.htm#M">M 2</a> commands.
<hr>
<a id="Lagrangemodel"></a><h2>Lagrange model</h2>
The Evolver has a very limited implementation of higherorder
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.
<p>
The Lagrange model is defined only for
<a href="quants.htm">named quantities and methods</a>,
so Evolver will automatically do
<a href="commands.htm#convert_to_quantities">
<code>convert_to_quantities</code></a> when you invoke the Lagrange model.
The methods that currently accept the Lagrange model are
<ul>
<li> <a href="quants.htm#vertex_scalar_integral">vertex_scalar_integral</a>
<li> <a href="quants.htm#edge_length">edge_length</a>
<li> <a href="quants.htm#edge_area">edge_area</a>
<li> <a href="quants.htm#edge_scalar_integral">edge_scalar_integral</a>
<li> <a href="quants.htm#edge_vector_integral">edge_vector_integral</a>
<li> <a href="quants.htm#edge_general_integral">edge_general_integral</a>
<li> <a href="quants.htm#facet_area">facet_area</a>
<li> <a href="quants.htm#facet_volume">facet_volume</a>
<li> <a href="quants.htm#facet_vector_integral">facet_vector_integral</a>
<li> <a href="quants.htm#facet_scalar_integral">facet_scalar_integral</a>
<li> <a href="quants.htm#facet_general_integral">facet_general_integral</a>
</ul>
A surface may be converted to an order n
Lagrange model with the command "lagrange n". This will convert
<a href="model.htm#linearmodel">linear</a>
or <a href="model.htm#quadraticmodel">quadratic models</a>
to Lagrange, and will convert between
different order Lagrange models. The commands
<a href="commands.htm#linear">linear</a> and
<a href="commands.htm#quadratic">quadratic</a> will
convert Lagrange model back to the linear or quadratic models.
<p>
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.
<p>
The current order can be accessed through the readonly internal
variable <a href="syntax.htm#lagrange_order">lagrange_order</a>.
The Lagrange model can be <a href="commands.htm#dump">dumped</a> and reloaded.
<p>
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.
<p>
Lagrange elements are normally plotted subdivided on their
vertices, but if the <a href="toggle.htm#smooth_graph">smooth_graph</a>
flag is on, they are plotted with 8fold subdivision.
<p>
The toggle command <a href="toggle.htm#bezier_basis">bezier_basis</a>
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.
<hr>
<hr>
<a id="spacedimension"></a><h2>Space dimension</h2>
<a id="MAXCOORD"></a>
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 readonly variable
<a href="syntax.htm#space_dimension">space_dimension</a>.
Graphics will display only the first three dimensions of spaces
with more than three dimensions, except for geomview, which
has a fourdimensional viewer built in (although its use is
awkward now).
<hr>
<hr>
<a id="metric"></a><h2>Metric</h2>
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 <a href="quants.htm">named quantities</a>.
All displaying is done as if the metric is Euclidean.
<ul>
<li><a href="#Euclideanmetric">Euclidean metric</a> (default)
<li><a href="#Riemannianmetric">Riemannian metric</a>
<li><a href="#conformalmetric">Conformal metric</a>
<li><a href="#Kleinhyperbolicmetric">Klein hyperbolic metric</a>
</ul>
<hr>
<a id="Euclideanmetric"></a> <h2>Euclidean metric</h2>
The default metric on the ambient space is the ordinary Euclidean
metric. There are no builtin 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.
<hr>
<a id="Riemannianmetric"></a><h2>Riemannian metric</h2>
The ambient space can be endowed with a general Riemannian metric
by putting the keyword METRIC
in the <a href="datafile.htm#metricdecl">datafile</a> followed
by the elements of the metric tensor.
Only one coordinate
patch is allowed, but the <a href="#quotientspaces">quotient space</a>
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
<a href="quants.htm#fixedquantity">named quantity constraint</a>.
See quadm.fe for an example of a metric.
<hr>
<a id="conformalmetric"></a><h2>Conformal metric</h2>
The ambient space can be endowed with a conformal Riemannian metric
by putting the keyword CONFORMAL_METRIC
in the <a href="datafile.htm#metricdecl">datafile</a> 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
<a href="quants.htm#fixedquantity">named quantity constraint</a>.
See quadm.fe for an example of a metric.
<hr>
<a id="Kleinhyperbolicmetric"></a><h2>Klein hyperbolic metric</h2>
One special metric is available builtin. 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.
<hr>
<hr>
<a id="symmetries"></a><h2>Symmetries</h2>
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 builtin
features. In any case, multiple copies of the fundamental domain may be displayed
with the <a href="datafile.htm#viewtransforms">view_transforms</a> command.
<ul>
<li><a href="#defaultsymmetry">No symmetry</a> (default)
<li><a href="#torusmodel">Torus model</a> (translational symmetry)
<li><a href="#symmetrygroups">Symmetry groups</a> (general symmetry)
</ul>
<hr>
<a id="defaultsymmetry"></a><h2>No symmetry</h2>
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.
<hr>
<a id="torusmodel"></a> <h2>Torus model</h2>
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
<a href="datafile.htm#torusdeclaration">TORUS</a> keyword
in the datafile. The defining basis vectors of the parallelpiped
are given in the
<a href="datafile.htm#torusperiods">TORUS_PERIODS</a>
entry of the datafile.
See <a href="twointor.htm">twointor.fe</a> for an example.
<p>
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.
<p>
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
<a href="datafile.htm#edgessection">edges section</a>,
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:
<table>
<tr> <td> * </td><td> does not cross face </td></tr>
<tr> <td> + </td><td> crosses in same direction as basis vector,
so basis vector added to edge vector </td></tr>
<tr> <td>  </td><td> crosses in opposite direction, so basis
vector subtracted from edge vector. </td></tr>
</table>
Wraps are automatically maintained by the various
triangulation manipulation operations.
<p>
<a id="torusdisplay"></a>
There are several commands for ways of displaying a torus surface:<br>
<a href="toggle.htm#raw_cells">raw_cells</a>
 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.
<br>
<a href="toggle.htm#connected">connected</a>  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. <br>
<a href="toggle.htm#clipped">clipped</a>  Shows the unit cell specified in the
datafile. Facets are clipped on the parallelpiped
faces.
<p>
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.)
<p>
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.
<p>
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.
<p>
<a href="constrnt.htm#levelsetconstraints">Level set constraints</a>
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 <a href="general.htm#options">q option</a>
or do <a href="commands.htm#convert_to_quantities">
<b>convert_to_quantities</b></a>. Doublecheck
that your volumes are turning out correctly; use volconst
if necessary.
<p>
<a id="display_periods"></a>
<b>Display_periods:</b> The displayed parallelogram unit cell can be
different from the actual unit cell if you
put an array called <code>display_periods</code> in the top of the datafile,
in addition to the regular periods. For a string model example,
<pre> parameter shear = 1
torus_filled
periods
4 0
shear 4
display_periods
4 0
0 4 </pre>
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 <code>unshear</code> command in
<code>unshear.cmd</code>.
<p>
<b><a id="display_origin"> Display_origin: </a></b>
For a torus mode surface,
if clipped mode is in effect, the center of the clip box is
set with the <code>display_origin[]</code> 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
<pre>
display_origin <em>x y z</em>
</pre> where <em>x y z</em> are the coordinates for the
desired center of the clip box. At runtime, the
array elements may be changed as normal:
<pre> display_origin[2] := 0.5
</pre>
Changing display_origin will automatically cause the
graphics to redisplay.
<hr>
<a id="quotientspaces"></a>
<a id="symmetrygroups"></a><h2>Symmetry groups and quotient spaces</h2>
As a generalization of the
<a href="#torusmodel">torus model</a>, you may declare
the domain to be the quotient space of R^n with respect to
some symmetry group. Several builtin 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.
<p>
The datafile requires the keyword
<a href="datafile.htm#symmetrydecl">SYMMETRY_GROUP</a>
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 <code>wrap</code> attribute of edges.
The group operations are accessible by the functions
<code>wrap_inverse(w)</code> and <code>wrap_compose( w1,w2)</code>.
<p>
Using any Hessian commands with any symmetry group
(other than the builtin torus model) will cause automatic
converting to named quantities (with the
"<a href="commands.htm#convert_to_quantities">
convert_to_quantities</a>" command,
since only named quantity Hessian evaluation routines have the proper
symmetry transformation of the Hessian programmed in.
<p>
Volumes of bodies might not be calculated correctly with a
symmetry group. The volume calculation only knows about
the builtin 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.
<a id="implementedsymmetries"></a>
<p> The currently implemented symmetry groups are:
<ul>
<li> <a href="#torussymmetrygroup"><code>torus</code></a>
 The underlying group for the <a href="#torusmodel">torus model</a>.
<li> <a href="#rotatesymmetrygroup"><code>rotate</code></a>
 Cyclic group of rotations in the xy plane.
<li> <a href="#fliprotatesymmetrygroup"><code>flip_rotate</code></a>
 Cyclic group of rotations in the xy plane with z mapping to z with every
odd rotation.
<li> <a href="#cubocta"><code>cubocta</code></a>
 Full point group of a cube.
<li> <a href="#cubelat"><code>cubelat</code></a>
 Full point group of a unit cubic lattice.
<li> <a href="#xyzsymmetrygroup"><code>xyz</code></a>
 The orientationpreserving subgroup of <a href="#cubocta">cubocta</a>.
<li> <a href="#genus2symmetrygroup"><code>genus2</code></a>
 For a 2 dimensional genus 2 hyperbolic quotient space.
<li> <a href="#dodecahedronsymmetrygroup"><code>dodecahedron</code></a>
 For a 3D hyperbolic quotient space with dodecahedral fundamental region.
<li> <a href="#central_symmetry"><code>central_symmetry</code></a>
 Inversion through the origin, X mapping to X.
<li> <a href="#screw_symmetry"><code>screw_symmetry</code></a>
 Screw motion along z axis.
<li> <a href="#quarter_turn"><code>quarter_turn</code></a>
</ul>
<hr> <a id="torussymmetrygroup"></a><h3><code>TORUS</code> symmetry group</h3>
This is the underlying
<a href="#symmetrygroups">symmetry</a> for the
<a href="#torusmodel">torus model</a>.
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 <i>n</i>dimensional Euclidean space
generated by <i>n</i> independent vectors, called the period vectors.
The torus group uses the <a href="datafile.htm#torusperiods"> torus
periods</a> listed in the datafile.
<p>
<b>Datafile declaration:</b> <code>symmetry_group "torus"</code>
<p>
<b>Group element encoding:</b>
The 32bit code word is divided into 6bit 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 5bit integer,
so higher wraps could be represented.
<a id="generator_power"></a>
<hr>
<a id="rotatesymmetrygroup"></a><h3><code>ROTATE</code> symmetry group </h3>
This is the cyclic
<a href="#symmetrygroups">symmetry group</a>
of rotations in the xy plane, where the order
of the group is given by the internal variable
<a href="syntax.htm#rotation_order">rotation_order</a> (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.
<b>Note:</b> Since this group has fixed points, some special precautions
are necessary. Vertices on the rotation axis must be labelled with
the attribute <a href="elements.htm#axial_point">axial_point</a> 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.
<p>
<b>Datafile declaration:</b><pre> symmetry_group "rotate"
parameter rotation_order = 6 </pre>
<p>
<b>Group element encoding:</b> An element is encoded as the power of
the group generator.
<hr> <a id="fliprotatesymmetrygroup"></a><h3><code>FLIP_ROTATE</code> symmetry group </h3>
This is the cyclic
<a href="#symmetrygroups">symmetry group</a>
of rotations in the xy plane with a flip
z mapping to z on every odd rotation, where the order
of the group is given by the internal variable
<a href="syntax.htm#rotation_order">rotation_order</a>, which had better
be even.
<b>Note:</b> 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 "<code>double_axial_point</code>" 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.
<p>
<b>Datafile declaration:</b><pre> symmetry_group "flip_rotate"
parameter rotation_order = 6 </pre>
<p>
<b>Group element encoding:</b> An element is encoded as the power of
the group generator.
<hr>
<a id="cubelat"></a>
<a id="cubelatsymmetrygroup"></a><h3><code>CUBELAT</code> symmetry group </h3>
This is the full
<a href="#symmetrygroups">symmetry group</a>
of the unit cubic lattice.
<p><b>Datafile declaration:</b> <code>symmetry_group "cubelat"</code>
<p><b>Group element encoding:</b>
wrap & {1,2,4} gives the sign
changes for x,y,z respectively; (wrap&24)/8 is the power of the (xyz)
permutation cycle;
(wrap&32)/32 tells whether to then swap x,y. Thus wrap&63 is the
same as for the cubocta symmetry group.
Then wrap/64 is a torus wrap as in the torus symmetry group:
three sixbit signed fields for translation in each coordinate.
Translation is to be applied after other operations.
<hr>
<a id="cubocta"></a>
<a id="cuboctasymmetrygroup"></a><h3><code>CUBOCTA</code> symmetry group </h3>
This is the full
<a href="#symmetrygroups">symmetry group</a>
of the cube. It can be viewed as all
permutations and sign changes of (x,y,z).
<p><b>Datafile declaration:</b> <code>symmetry_group "cubocta"</code>
<p><b>Group element encoding:</b> wrap & {1,2,4} gives the sign
changes for x,y,z respectively; (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)
<hr> <a id="xyzsymmetrygroup"></a><h3><code>XYZ</code> symmetry group </h3>
The orientationpreserving subgroup of <a href="#cuboctasymmetrygroup">
cubocta</a>. Same representation.
<hr> <a id="genus2symmetrygroup"></a><h3><code>GENUS2</code> symmetry group </h3>
This is a symmetry group on the
<a href="model.htm#Kleinhyperbolicmetric">Klein model</a> of hyperbolic space whose
quotient group is a genus 2 hyperbolic manifold. The fundamental region
is an octagon.
<p><b>Datafile declaration:</b> <pre>
Klein_metric
symmetry_group "genus2" </pre>
<b>Group element encoding:</b>
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.
<hr> <a id="dodecahedronsymmetrygroup"></a><h3><code>DODECAHEDRON</code> symmetry group </h3>
This is the
<a href="#symmetrygroups">symmetry group</a> of translations of
hyperbolic 3 space tiled with rightangled 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.
<p><b>Datafile declaration:</b> <pre>
Klein_metric
symmetry_group "dodecahedron" </pre>
<hr> <a id="central_symmetry"></a><h3><code>CENTRAL_SYMMETRY</code> symmetry group </h3>
This is the order 2
<a href="#symmetrygroups">symmetry group</a> of inversion through the origin,
X maps to X.
<p><b>Datafile declaration:</b> <pre>
symmetry_group "central_symmetry" </pre>
<b>Group element encoding:</b> 0 for identity, 1 for inversion.
<a id="screw_height"></a><a id="screw_angle"></a>
<hr> <a id="screw_symmetry"></a><h3><code>SCREW_SYMMETRY</code> symmetry group </h3>
This is the
<a href="#symmetrygroups">symmetry group</a> of screw motions along the z axis.
The global parameter <code>screw_height</code> is the translation distance (default 1), and
the global parameter <code>screw_angle</code> is the rotation angle in degrees (default 0).
<p><b>Datafile declaration:</b> <pre>
parameter screw_height = 4.0
parameter screw_angle = 180.0
symmetry_group "screw_symmetry"
</pre>
<b>Group element encoding:</b> the integer value is the power of the group generator.
<a id="quarter_turn_period"></a>
<a id="quarter_turn"></a>
<hr>
<h3>quarter_turn</h3>
<a href="#symmetrygroups">Symmetry group</a>
3D torus with quarter turn in identification of top
and bottom. x and y periods taken to be 1. z period is the userdefined
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).
<br>
Relations: x z = z y^1, y z = z x
<br>
Numerical representation: as in the
<a href="#torussymmetrygroup">torus symmetry group</a>, for powers of x,y,z
with generators applied in that order.
<hr>
<hr>
<a id="mobility"></a><h2>Mobility</h2>
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:
<ul>
<li> <a href="#unitmobility">unit mobility</a>
<li> <a href="#areanormalization">area normalization</a>
<li> area normalization with <a href="#effectivearea">effective area</a>
<li> <a href="#polyhedralcurvature">approximate polyhedral curvature</a>
<li> <a href="#userdefinedmobility">userdefined mobility</a>
</ul>
<hr>
<a id="unitmobility"></a> <h2>Unit mobility</h2>
This is the default <a href="#mobility">mobility</a>, in which the velocity is equal to the
force. Hence M and S are the identity matrices in standard
coordinates. 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.
<hr>
<a id="areanormalization"></a><h2>Area normalization</h2>
A type of <a href="#mobility">mobility</a>.
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 scheme counts the
area of a vertex equal to 1/3 of the area of the star of
facets around it (or 1/2 the area of the star of edges in the
string model). This is easy to calculate, since it is a local
calculation for each vertex. S and M are diagonal matrices
(see <a href="#mobility">mobility</a>).
The result is that motion = force/area, which is a much better
approximation to motion by mean curvature than the default
of motion = force.
Area normalization can be toggled with the
<a href="single.htm#a">a</a> command or the
<a href="toggle.htm#area_normalization">area_normalizaton</a> toggle.
<hr>
<a id="effectivearea"></a> <h2> Area normalization with effective area</h2>
A type of <a href="#mobility">mobility</a>.
Simple area normalization as described in the previous paragraph
isn't what's really wanted in certain circumstances. 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 <a href="#mobility">mobility</a>).
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 <a href="toggle.htm#effective_area">
effective_area</a> toggle. Note that area normalization itself must
still be toggled with <a href="single.htm#a">a</a> or
<a href="toggle.htm#area_normalization">area_normalizaton</a>.
<hr>
<a id="polyhedralcurvature"></a><h2> Approximate polyhedral curvature</h2>
A type of <a href="#mobility">mobility</a>.
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 <a href="#mobility">mobility</a>).
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 <a href="toggle.htm#approximate_curvature">approx_curv</a> toggle command.
<hr>
<a id="effectivepolyhedral"></a>
<h2> Approximate polyhedral curvature with effective area.
</h2>
<a href="#polyhedralcurvature">Polyhedral curvature</a>
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
<a href="toggle.htm#effective_area">effective_area</a>.
<hr>
<a id="userdefinedmobility"></a><h2>Userdefined mobility</h2>
The user may define a
<a href="#mobility">mobility</a> tensor in the
<a href="datafile.htm#mobilitydecl">datafile</a>.
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.
<hr>
<a href="evolver.htm#doctop">Back to top of Surface Evolver documentation.</a>
<a href="index.htm">Index.</a>
</body>
</html>
