File: datafile.htm

package info (click to toggle)
evolver 2.70+ds-4
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 17,148 kB
  • sloc: ansic: 127,395; makefile: 209; sh: 98
file content (1685 lines) | stat: -rw-r--r-- 75,499 bytes parent folder | download | duplicates (2)
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
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
<!DOCTYPE HTML>
<html><head><TITLE>Surface Evolver Documentation - Datafile format</title>
<link rel="stylesheet" type="text/css" href="evdoc-style.css" />
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" >
</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#doc-top">Back to top of Surface Evolver documentation.</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="index.htm">Index.</a>

<h1> Evolver datafile format </h1>

             The initial configuration of the surface is read
         from an ASCII datafile.  See the <a href="cube.htm">cube</a>
         or <a href="mound.htm">mound</a> examples for samples.
         The datafile is organized into six parts:
<ul>
         <li> <a href="#datafile-header">Definitions and options</a>
         <li> <a href="#vertices-section">Vertices</a>
         <li> <a href="#edges-section">Edges</a>
         <li> <a href="#faces-section">Faces</a>
         <li> <a href="#bodies-section">Bodies</a>
         <li> <a href="#read-section">Initial commands</a>
</ul>
General datafile topics:
<ul>
<li><a href="syntax.htm">General syntax </a> (for datafiles and commands)
<li><a href="#include-files">Include files</a>
<li><a href="#macros">Macros</a>
</ul>
         In the syntax descriptions below, keywords will be in
         upper case.  <i>constexpr</i> means a constant expression,
         and <i>expr</i> means any expression. <i>n</i> or <i>k</i> means an integer,
         which may be signed if it is being used as an oriented
         element label.
         Square brackets denote optional items. '|' means 'or'.


<p>
<b>NOTE:</b> 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 <code>3*width</code>, then
changing the value of the variable <code>width</code> at runtime will not
affect the vertex.  If you are not clear on which interpretation applies in
a certain spot, <a href="commands.htm#dump">dump</a> the datafile and
look at the spot to see if a formula or number was dumped.
<hr>
<a   id="include-files"></a><h2>Include files</h2>
	The standard C language method of including other files is
	available.  The file name must be in double quotes.  If the file is
	not in the current directory, 
<a href="install.htm#EVOLVERPATH">EVOLVERPATH</a> will be searched.
	Includes may be nested to 10 deep.
	Example:<pre>
	#include  "common.stuff"
</pre>
<hr>
<a   id="macros"></a><h2>Macros</h2>
Macros are text substitutions done by replacing an identifier by
a string of characters before parsing.  Macros are only defined
in the datafile, and do not work from the command prompt.
         Simple macros (no parameters) may be defined as in C:
<pre>         #DEFINE  <em>identifier  string</em>
</pre>
       <em>identifier</em> must be an identifier without 
         other special meaning to the parser.
         <em>string</em> is the rest of the logical line, not including
         comments.  It will be
         substituted for <em>identifier</em> whenever <em>identifier</em> 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.
<a   id="keep_macros"></a>
        The keyword <code>keep_macros</code> in the datafile will keep macro
         definitions active during runtime, until the next datafile is
         loaded.


<hr>
<hr>

<a   id="datafile-header"></a> <h2>Datafile top section</h2>

The datafile begins with optional definitions and specifications.
These are definitions that need to be made before the geometric
elements are defined, or for which command syntax is lacking or 
awkward.  Other initializations can be made at the
end of the datafile in the <a href="#read-section">read</a> section
using the command language.
         Each line starts with a keyword.  The order is immaterial,
         except for the usual rule that items must be defined before use.
         None of these are required if you are willing to accept various
defaults.  They are listed here in rough order of frequency of use; those
in the first column you should know, those in the second column you might never
use in a lifetime.
<table> 
<tr ><td style="vertical-align:text-top">
<ul>
<li><a href="#datafile-variables">Variables</a>
<li><a href="#constraint-decl">Level set constraints</a>
<li><a href="#boundary-decl">Parametric boundaries</a>
<li><a href="#named-quantity-decl">Named quantities</a>
<li><a href="#method-instance-decl">Named method instances</a>
<li><a href="#surface-dimension-decl">Surface dimension</a>
<li><a href="#space-dimension-decl">Space dimension</a>
<li><a href="#extra-decl">Extra attributes </a>
<li><a href="#quadratic-decl">Quadratic model</a>
<li><a href="#gravity_constant-decl">Gravity constant </a> 
<li><a href="#torus-declaration">Torus model</a>
<li><a href="#torus_filled-decl">Torus_filled</a>
<li><a href="#torus-periods">Torus periods</a>
<li><a href="#viewing-matrix">Viewing matrix</a> 
<li><a href="#view-transforms">View transforms</a>
<li><a href="#view-generators">View transform generators</a>
<li><a href="#scale_limit">Scale_limit</a>
<li><a href="#functions">Functions and procedures</a>
<li><a href="#optimizing_parameter">Optimizing Parameters</a>
<li><a href="#gap-constant-decl">Gap constant </a>
<li><a href="#symmetric_content">Symmetric content</a>
<li><a href="#keep_originals">Keep original ids</a>

</ul></td> <td><ul>
<li><a href="#squared_curvature">Squared mean curvature</a>
<li><a href="#constraint_tolerance-decl">Constraint tolerance</a>
<li><a href="#version">Version</a>
<li><a href="#metric-decl">Metric </a> 
<li><a href="#simplex-decl">Simplex model </a>
<li><a href="#symmetry-decl">Symmetry group</a>
<li><a href="#length_method_name">Length method</a>
<li><a href="#area_method_name">Area method</a>
<li><a href="#volume_method_name">Volume method</a>
<li><a href="#hessian_special_normal_vector">Hessian special normal vector</a>
<li><a href="#wulff-decl">Crystalline integrands</a>
<li><a href="#diffusion-decl">Diffusion</a>
<li><a href="#phase-decl">Phase file </a>
<li><a href="#ideal-gas-decl">Ideal gas model</a>
<li><a href="#interp_bdry-decl">Interpolation of boundary parameters</a>
<li><a href="#mobility-decl">Mobility </a>
<li><a href="#merit_factor">Merit factor</a>
<li><a href="#sqgauss">Squared Gaussian curvature</a>
<li><a href="#zoom_vertex">Zoom_vertex</a>
<li><a href="#zoom_radius">Zoom_radius</a>
<li><a href="#load_library">Dynamic load library </a>
<li><a href="#suppress_warning">Suppressing warnings </a>
<li><a href="#vertices_predicted">vertices_predicted</a>
<li><a href="#edges_predicted">edges_predicted</a>
<li><a href="#facets_predicted">facets_predicted</a>
<li><a href="#facetedges_predicted">facetedges_predicted</a>
<li><a href="#bodies_predicted">bodies_predicted</a>
<li><a href="#quantities_predicted">quantities_predicted</a>
<li><a href="#method_instances_predicted">method_instances_predicted</a>
</ul></td> </tr></table>

<hr>

<a   id="datafile-variables"></a><h2>Definitions of variables</h2>
<a   id="on_assign_call"> </a>
Variables may be defined in the datafile top section with this syntax:
<pre>
      PARAMETER <em>identifier</em> = <em>constexpr</em>
</pre>
             This declares <em>identifier</em> to be a variable
              with the given initial value. The value may
              be changed at runtime with the 
<a href="single.htm#A">A</a> command, or by 
<a href="commands.htm#assignment">assignment</a>.  Variables
              may be used in any subsequent expression or constant expression.
	     Changing variables defined here
	     results in automatic recalculation of 
	     the surface when
<a href="toggle.htm#autorecalc">autorecalc</a> is been toggled on.
	     Hence only variables needed in other top section declarations
	     should be defined here.

<p>
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
<pre>
      PARAMETER <em>identifier</em> = <em>constexpr</em> ON_ASSIGN_CALL <em>procedure_name</em>
</pre>
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):
<pre>
  procedure tester();
  parameter aaa = 4
  parameter bbb = 5 on_assign_call tester
  procedure tester() { aaa := bbb; }
</pre>
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.

<hr>
<a   id="nonpositive"></a>
<a   id="nonnegative"></a>
<a   id="nonwall"></a>
<a   id="constraint-decl"></a><h2>Level set constraint declarations</h2>
The format for declaring a 
<a href="constrnt.htm#level-set-constraints">level set constraint</a>
 in the top section of the datafile is
<pre>
CONSTRAINT <em>n</em> [GLOBAL] [CONVEX] [NONNEGATIVE] [NONPOSITIVE] [NONWALL] [CONTENT_RANK <em>n</em>]
FORMULA FUNCTION  <em>expr</em>
[ENERGY:
 E1: <em>expr</em>
 E2: <em>expr</em>
 E3: <em>expr</em>]
[CONTENT:
 C1: <em>expr</em>
 C2: <em>expr</em>
 C3: <em>expr</em>]
</pre>
You may use <code>EQUATION</code> or <code>FUNCTION</code> as synonyms for <code>FORMULA</code>.
   This defines constraint number <em>n</em>, where <em>n</em> is a
   positive integer.  The optional
   keyword <code>GLOBAL</code> means the constraint automatically applies to all
   vertices (but not automatically to edges or faces).  <code>GLOBAL</code>
   constraints count in the number limit.  If <code>CONVEX</code> is given,
   then an additional <a href="energies.htm#gap-energy">gap energy</a>
   is attributed to edges on the
   constraint to prevent them from trying to short-circuit a convex
   boundary.  <code>NONWALL</code> 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 <code>NONNEGATIVE</code> or <code>NONPOSITIVE</code> is given, then this is
   a <a href="constrnt.htm#one-sided-constraints">one-sided constraint</a>, and
  all vertices will be forced to conform appropriately to the
   constraint at each iteration.  The <code>FORMULA</code> 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 '&gt;' or '&lt;' to indicate inequalities; use
   <code>NONNEGATIVE</code> or <code>NONPOSITIVE</code>. 
   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
<pre>
    variable :=  expr, expr
</pre>
   The value of the expression is the value of the second expression.

<p>               
   The optional <code>ENERGY</code> section signifies that vertices or edges on the
                constraint are deemed to have an energy.  
                In the 
<a href="model.htm#soapfilm-model">soapfilm model</a>,
 the next lines give
                components of a vectorfield that will be integrated
                along each edge on the constraint.  In the 
<a href="model.htm#string-model">string model</a>, 
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
     <a href="energies.htm#gravity-energy">gravitational potential energy</a>
 due to omitted facets.
		Integrals are now also evaluated on <code>fixed</code> edges, which
is a change from earlier versions of Evolver.
<p>
The optional <code>CONTENT</code> section signifies that vertices 
(<a href="model.htm#string-model">string model</a> ) or
      edges (<a href="model.htm#soapfilm-model">soapfilm model</a>) 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.
 
<p>
<hr>
<a   id="boundary-decl"></a><h2>Parameterized boundary declaration</h2>
A parameterized boundary may be declared in the top section of the
datafile with the syntax
<pre>
BOUNDARY <em>n</em> PARAMETERS <em>k</em> [CONVEX] 
X1: <em>expr</em> 
X2: <em>expr</em>
X3: <em>expr</em>
</pre>

   This defines boundary number <em>n</em>, where <em>n</em> is a positive
   integer and <em>k</em> is the 
                number of parameters.  If <code>CONVEX</code> is
                given, then an additional 
<a href="energies.htm#gap-energy">gap energy</a> 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 <code>P1</code> and maybe <code>P2</code>, <code>P3</code>,....
See the <a href="catenoid.htm">catenoid example</a>.
  Energy and
                content integrals for boundaries are implemented, with 
		the same syntax as for <a href="#constraint-decl">
		level set constraints</a>.


<hr><h2><a   id="named-quantity-decl">Named quantities</a></h2>
<a   id="lagrange_multiplier"></a>
The syntax for defining a  <a   id="info_only"></a>
<a href="quants.htm#named-quantities">named quantity</a> in the data file is:
<p><pre> QUANTITY <i>name</i>   ENERGY|FIXED=<i>value</i>|CONSERVED|INFO_ONLY [LAGRANGE_MULTIPLIER <i>constexpr</i>]
[TOLERANCE <i>constexpr</i>]  [MODULUS <i>constexpr</i>] <i>methodlist</i> | FUNCTION <i>methodexpr</i>
</pre>
<p>
Here <i>name</i> 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:
<ul>
<li><code>ENERGY</code> quantities are added to the overall
energy of the surface; 
<li><code>FIXED</code> quantities that are constrained to a
fixed target <i>value</i>;
<li><code>CONSERVED</code> 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.
<li><code>INFO_ONLY</code> quantities whose values are merely reported to the user.
</ul>
For fixed quantities, the optional Lagrange multiplier value supplies
the initial value of the Lagrange multiplier (the "pressure" attribute
of the quantity).  It is meant for dump
files, so on reloading no iteration need be done to have a valid
Lagrange multiplier.
<p>
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.
<p>
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.

<a   id="global_method"></a>
The <i>methodlist</i> version of the quantity definition may  
contain one or more <a href="quants.htm#method-instances">method instances</a>. 
To incorporate a previously explicitly defined instance, include
<code>METHOD</code> <i>instancename</i>.  <code>GLOBAL_METHOD</code> may be used
instead of <code>METHOD</code> to indicate the method applies to all elements
of the appropriate type; it is equivalent to using <code>GLOBAL</code> in
the method definition.
To instantiate a method in the quantity definition, 
you essentially
incorporate the <a href="#method-instance-decl">instance definition</a>, 
but without an instance name.  Example of a quantity with one predefined
method instance and one implicitly defined instance:
<pre>   method_instance qwerty method facet_scalar_integral
     scalar_integrand: x^2
   quantity foobar energy method qwerty method edge_scalar_integral
     scalar_integrand: y^3
</pre>
<p>
Usually the second, implicit definition will be more convenient.
Several method instances may be included in one <i>methodlist</i>
(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 <code>FUNCTION</code> <i>methodexpr</i> variant
 defines the quantity as a function of 
previously defined method instances.  Example:
<pre>   method_instance qwerty method facet_scalar_integral
     scalar_integrand: x^2
   quantity foobar energy function qwerty^3
</pre>
<p>
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
<a href="commands.htm#set">set</a> and 
<a href="commands.htm#unset">unset</a> 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.

<p>
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.

<hr>
<a   id="scalar_integrand"></a>
<a   id="vector_integrand"></a>
<a   id="form_integrand"></a>
<a   id="k_form_order"></a>
<a   id="parameter_1"></a>
<a   id="global"></a>
<h2>
<a   id="method_instance"></a>
<a   id="method-instance-decl">Named method instances declaration</a></h2>
<a href="quants.htm#method-instances">Method instances</a>
 are usually defined as part of the 
<a href="#named-quantity-decl">definition</a>
of a <a href="quants.htm#named-quantities">named quantity</a>, 
but there are circumstances where a quantity
is composed of several method instances and the method instances
need to be referred to individually; perhaps the user wants to
know the values of the individual instances. 
The general syntax for defining an instance of a named method in
a datafile is:
<pre>  METHOD_INSTANCE <i>name</i> METHOD <i>methodname</i> [MODULUS <i>constexpr</i>] 
   [ELEMENT_MODULUS <i>attrname</i>]  [GLOBAL] [<i>parameters</i>]
</pre> 
Here, <i>name</i> is a user-assigned name for referring to this
particular instance. <i>methodname</i> is one of the 
<a href="quants.htm#methods">pre-defined methods</a> 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
<a href="elements.htm#extra-attributes">extra attribute</a>
<i>attrname</i> for the type of element; the attribute must have been
defined earlier.
 <code>GLOBAL</code> 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
<a href="commands.htm#set">set</a> and 
<a href="commands.htm#unset">unset</a> 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
<pre> set facet[123] orientation -1 </pre>

<p>
 Each method may have various parameters to specialize
 it to an instance.  Currently the only parameters  specified are:
<dl><dt> <code>SCALAR_INTEGRAND: <i>expr</i> </code></dt>
<dd> where <i>expr</i> is a scalar function of coordinates
(and of tangent or normal vector components in 
<a href="quants.htm#edge_general_integral">edge_general_integral</a>
or <a href="quants.htm#facet_general_integral">facet_general_integral</a>).
 Element attributes of the appropriate type
element may also be used.<p></dd>
<dt><code>
VECTOR_INTEGRAND:  <br>
Q1: <i>expr</i> <br>
Q2: <i>expr</i> <br>
Q3: <i>expr</i> <br> </code></dt>
<dd> where the expressions are functions of the coordinates.
 Element attributes of the appropriate type
element may also be used.<p></dd>
<dt><code>
FORM_INTEGRAND: <br>
Q1: <i>expr</i> <br>
Q2: <i>expr</i> <br>
Q3: <i>expr</i> <br>
...<br></code></dt>
<dd> where the expressions are functions of the coordinates.
 Element attributes of the appropriate type
element may also be used. When used in the 
<a href="quants.htm#facet_2form_integral">facet_2form_integral</a> method.
The form components are listed in lexicographic order,
i.e. in 4D the six components 12,13,14,23,24,34 would be listed
as <code>Q1</code> through <code>Q6</code>.<p></dd>
<dt><code>PARAMETER_1 <i>constexpr</i></code></dt>
<dd> For specifying miscellaneous numeric parameters to 
certain methods.<p></dd>
<dt><code>K_FORM_ORDER <i>constexpr</i></code></dt>
<dd>For methods that use differential k-forms, this specifies the value of k.
Should occur before <code>FORM_INTEGRAND</code> when needed.</dd>
</dl>
<hr>

<a   id="string"></a>
<a   id="soapfilm"></a>
<a   id="surface-dimension-decl"></a><h2>Surface dimension</h2>
The default dimension of the surface is 2.  If not, it must be declared in the 
top section of the datafile. For a 1-dimensional surface (the
<a href="model.htm#string-model">string model</a>), simply include the line
<pre> STRING
</pre>
The default dimension 2 <a href="model.htm#soapfilm-model">soapfilm model</a>
is equivalent to using
<pre> SOAPFILM
</pre>
In general, the line   
<pre> SURFACE_DIMENSION <i>n</i>
</pre>
defines the surface to have dimension <i>n</i>.
 Dimension over 2 is valid only in the 
<a href="model.htm#simplex-model">simplex model</a>.
The surface dimension may be accessed at runtime through the read-only variable 
<a href="syntax.htm#surface_dimension">surface_dimension</a>.

<hr>
<a   id="space-dimension-decl"></a><h2>Space dimension</h2>
The default dimension of space is 3. Otherwise it must be declared
in the top section of the datafile, with syntax
<pre>SPACE_DIMENSION <em>n</em>
</pre>
The dimension must be at most the value of MAXCOORD in
model.h, which is 4 in the distributed version.  
The space dimension may be accessed at runtime through the read-only variable 
<a href="syntax.htm#space_dimension">space_dimension</a>.

<hr>
<a   id="extra-decl"></a><h2>Extra attribute declarations</h2>
<a   id="integer"></a>
<a   id="real"></a>
<a   id="ulong"></a>
<a   id="self"></a>
It is possible for the user to define 
<a href="elements.htm#extra-attributes">extra attributes</a> for elements,
which may be single values or up to eight-dimensional arrays.
  If these attributes are to
be included in the datafile, then the top section of the datafile
must contain appropriate definitions.  The definition syntax is
the same as used by the <a href="commands.htm#define">define</a> runtime
command:
<pre> DEFINE <em>elementtype</em> ATTRIBUTE <em>name</em> <em>type</em> [<em>dim</em>]...
</pre>
where <em>elementtype</em> is  <code>vertex</code>, <code>edge</code>, <code>facet</code>,
 or <code>body</code>, <em>name</em>
is an identifier of your choice, <em>type</em> is <code>REAL</code> or
<code>INTEGER</code>  (internally, there is also a <code>ULONG</code> unsigned
long type also),
and <em>dim</em> 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 <em>type</em> may be followed by <code>FUNCTION</code>
 followed by a procedure in brackets to be
evaluated whenever the value of the attribute is read; in the formula,
<code>self</code> 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 <a href="commands.htm#print">print</a> command may be used to print
attribute arrays or array slices in bracketed form.
 Examples:
<pre>  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 }
</pre>
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.

<hr>
<a   id="quadratic-decl"></a><h2>Quadratic declaration</h2>
To declare that the datafile lists a surface in the 
<a href="model.htm#quadratic-model">quadratic model</a>,
the top section of the datafile should contain the line
<pre>
QUADRATIC
</pre>
The only effect on datafile syntax is that the 
<a href="#edges-section">edge section</a> may
list edge midpoint vertices. 

<hr>
<a   id="gravity_constant-decl"></a><h2>Gravity constant declaration</h2>
The initial value of the 
<a href="energies.htm#gravity-energy">gravitational constant</a>
may be set in the datafile with the syntax
<pre>  GRAVITY_CONSTANT <i>value</i> </pre>
The default value is 1.

<hr>
<a   id="torus-declaration"></a><h2>Torus model declaration</h2>
<a   id="torus_filled-decl"></a>
To declare periodic boundary conditions (i.e. make the domain a flat
<a href="model.htm#torus-model">torus</a>), 
include in the top section of the datafile the line
<pre>
TORUS
</pre>
All space dimensions will be periodic, with the period vectors given
in the <a href="#torus-periods">periods</a> declaration.  
If the domain is completely filled by bodies with prescribed volumes,
then the line
<pre>
TORUS_FILLED
</pre>
should be used instead to prevent degenerate volume constraints.
<hr>
<a   id="periods"></a>
<a   id="torus-periods"></a><h2>Torus periods</h2>
If periodic boundary conditions are used
(the <a href="model.htm#torus-model">torus model</a>) ,
the period vectors of the fundamental unit cell parallelpiped
may be defined in the top section of the datafile. Default is the unit cube. 
The syntax
is the keyword <code>PERIODS</code> followed by expressions for the components
of each period vector:
<pre>PERIODS 
<em>expr expr expr</em>
<em>expr expr expr</em>
<em>expr expr expr</em>
</pre>
The size of this matrix depends on the space dimension.  
		 Variables may be used in the expressions,
                 so the fundamental domain may be changed interactively
		 by assigning new values to the variables.  Be sure to 
		 give a 
<a href="commands.htm#recalc">recalc</a> command whenever you change such a
		 variable, in order to get the period matrix
		 re-evaluated.
<hr>


<a   id="view_matrix"></a>
<a   id="viewing-matrix"></a><h2>Viewing matrix</h2>
The top section of the datafile may contain an initial 
<a href="graphics.htm#view-matrix">viewing matrix</a>:
<pre>
VIEW_MATRIX
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
</pre>
The matrix is in homogeneous
 coordinates with translations in the last column.
 The size of the matrix is one more than the space dimension.
 This matrix will be part of all dump files, so the view
 can be saved between sessions.  This matrix is used and set
 by native screen graphics ('s' command) and only applies
 to internal graphics (Postscript, Xwindows, etc.) but
 not external graphics (geomview).  The elements may be
 read or set at runtime by <code>view_matrix[i][j]</code>, where
 the indices start at 1.  In particular, one can write
 command scripts to save and reload particular view matrices;
 see <code>saveview.cmd</code> in the distribution package.
<hr>

<a   id="swap_colors"></a>
<a   id="view_transforms"></a>
<a   id="view-transforms"></a> <h2>View transforms</h2>
  For the display of several transformations of the surface
   simultaneously, a number of viewing transformation matrices
   may be given in the top section of the datafile:
<pre>
VIEW_TRANSFORMS <em>n</em> 
COLOR <em>color</em>
SWAP_COLORS
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
    ...
</pre>
     The transforms apply to all graphics, internal
   and external, and are prior to the  
<a href="graphics.htm#view-matrix">viewing matrix</a> for internal graphics. 
   The identity transform is always done, so
   it does not need to be specified. 
 The number of matrices
   follows the keyword <code>VIEW_TRANSFORMS</code>.  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 <a href="syntax.htm#colors">color</a>
 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 
<a href="toggle.htm#transforms">transforms</a> toggle.
    The internal variable <code>transform_count</code> records the number
    of transforms, and
   the transform matrices are accessible at runtime as a three-dimensional
   matrix view_transforms[][][].
   <a href="#view-generators">View transform generators</a> are
    a more sophisticated way to control
   view transforms.
<hr>
<a   id="view_transform_generators"></a>
<a   id="view-generators"></a><h2>View transform generators</h2>
  Listing all the <a href="#view-transforms">view transforms</a> is tedious
  and inflexible.  An alternative is to list just a few matrices that
  can generate transforms.  See the 
<a href="commands.htm#transform_expr">transform_expr</a> command for 
  instructions on entering the expression that generates the actual
  transforms. Special Note: in the <a href="model.htm#torus-model">torus model</a>,
 the period translations
  are automatically added to the end of the list. So in the torus model,
  these are always available, even if you don't have 
  view_transform_generators in the datafile.  Syntax in the top of
  the datafile:
<pre>
VIEW_TRANSFORM_GENERATORS <em>n</em> 
SWAP_COLORS
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
<em>  constexpr constexpr constexpr constexpr</em>
    ...
</pre>
 The number of matrices
   follows the keyword <code>VIEW_TRANSFORM_GENERATORS</code>.  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 <code>transform_count</code> records the number
    of transforms, and
   the transform matrices are accessible at runtime as a three-dimensional
   matrix view_transforms[][][].

<hr>
<a   id="scale_limit"></a><h2>Scale limit</h2>
To set an upper bound of <i>value</i>on the gradient descent
<a href="iterate.htm#scale-factor">scale factor</a>,
include the line
<pre>
   SCALE_LIMIT <i>value</i>
</pre>
in the top section of the datafile.  The upper bound can be changed
at runtime with the <a href="single.htm#m">m</a> command, or by
setting the <code>scale_limit</code> variable.  If surface tension is
the main energy, the scale_limit should be set to the inverse of
the surface tension.

<hr> 
<a   id="functions"></a><h2>Functions and procedures</h2>
Usually stand-alone user-defined 
<a href="commands.htm#function-definition">functions</a> 
and 
<a href="commands.htm#procedure-definition">procedures</a> 
are defined
in the <a href="datafile.htm#read-section">read section</a> of the
datafile, but sometimes it is necessary to define them in the top section
of the datafile so they may be used in other top section declarations.
It is possible to define them in the top section with the same syntax
as in the read section.  Note this applies to the parameter-passing
variety of functions and procedures, denoted by the leading keyword
"function" or "procedure", and not command definitions like "gg := {...}".
WARNING: there is a syntax ambiguity if you mean to define a stand-alone
function in the top of the datafile and put it after an attribute 
declaration.  You should define stand-alone functions before attributes,
or separate them with some other kind of declaration.

<hr>
<a   id="optimizing_parameter"></a> <a   id="optimising_parameter"></a> 
  <a id="pdelta"></a> <a   id="pscale"></a> 
<a id="p_force"></a> <a id="p_velocity"> </a>
<a   id="parameter-scale"></a>
<h2>Optimizing parameter</h2>
A variable may be made subject to optimization during 
<a href="iterate.htm#iteration-step">iteration</a>
or <a href="commands.htm#hessian-command">hessian</a> commands
with the datafile declaration
<pre>
      OPTIMIZING_PARAMETER <em>identifier</em> = <em>constexpr</em> PDELTA = <em>constexpr</em> PSCALE = <em>constexpr</em>
</pre>
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, <code>fix radius</code>
         would make the radius variable non-optimizing (fixed value).
Also, the pdelta and pscale attributes may be accessed at runtime, as in
<pre>
height.pscale := 2*height.pscale
</pre>
At 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:
<pre>
    g
    print height.p_velocity
</pre>
<p>
 "Optimising_parameter" is a synonym.

<hr>
<a   id="gap_constant"></a>
<a   id="spring_constant"></a>
<a   id="gap-constant-decl"></a><h2>Gap constant declaration</h2>
The initial value of the gap constant for 
<a href="energies.htm#gap-energy">gap energy</a> may be set
in the datafile with the syntax
<pre>  GAP_CONSTANT <i>value</i> </pre>
The default value is 1. Synonym: spring_constant.

<hr>
<a   id="symmetric_content"></a><h2>Symmetric content</h2>
The datafile keyword <code>SYMMETRIC_CONTENT</code> 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.

<hr>
<a   id="keep_originals"></a><h2>Keep original ids</h2>
The presence of the keyword
<pre>
keep_originals
</pre>
in 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.

<hr>
<a   id="evolver_version"></a>
<a   id="version"></a><h2>Version</h2>

If a datafile contains features present only after a certain version of
the Evolver, the datafile can contain a line of the form <br>
<code> evolver_version "2.10"</code><br>
This will generate a version error message if the current version is earlier,
or just a syntax error if run on an Evolver version earlier than 2.10.

<hr>









<a   id="constraint_tolerance-decl"></a><h2>Constraint tolerance</h2>
This is datafile declaration of the tolerance within which a vertex is deemed to satisfy a
<a href="constrnt.htm#level-set-constraints">level-set constraint</a>. 
 Default is 1e-12.  Syntax:
<pre>  CONSTRAINT_TOLERANCE <i>const_expr</i> </pre>
Sets the value of the internal variable 
<a href="syntax.htm#constraint_tolerance">constraint_tolerance</a>.

<hr>
<a   id="symmetry-decl"></a><h2>Symmetry group declaration</h2>
To declare that the domain is the quotient space of a 
<a href="model.htm#symmetry-groups">symmetry group</a>, the
top section of the datafile must contain a line of the form
<pre>
SYMMETRY_GROUP "<em>name</em>" 
</pre>  "<em>name</em>" is a double-quoted name that is matched 
against the list of 
<a href="model.htm#implemented-symmetries">defined symmetry groups</a>.


<hr>
<a   id="length_method_name"></a><h2>Length method</h2>
 This item, <code>length_method_name</code>, specifies
the name of the pre-defined method to use as the
method to compute edge length in place of the default 
<a href="quants.htm#edge_length">edge_length</a> method.
It is optional. Developed so circular arcs can be
used in two-dimensional foams.  Current reasonable methods
are <a href="quants.htm#circular_arc_length">circular_arc_length</a>
and <a href="quants.htm#spherical_arc_length">spherical_arc_length</a>.
Usage implies converting to <a href="#everything_quantities">
everything_quantities</a> mode.
Syntax: 
<pre>
length_method_name <em>quoted_method_name</em>
</pre>
For example,
<pre>
string
space_dimension 2
length_method_name "circular_arc_length"
</pre>

<hr>
<a   id="area_method_name"></a><h2>Area method</h2>
 This item, <code>area_method_name</code>, specifies
the name of the pre-defined method to use as the
method to compute facet areas in place of the default 
<a href="quants.htm#edge_area">edge_area</a> method in the string model
or <a href="quants.htm#facet_area">facet_area</a> method in the 
soapfilm model.  It is optional. Developed so circular arcs can be
used in two-dimensional foams.  Current reasonable methods
are <a href="quants.htm#circular_arc_area">circular_arc_area</a>
and <a href="quants.htm#spherical_arc_area_n">spherical_arc_area</a>.
 Synonymous with <a href="#volume_method_name">
volume_method_name</a> in the string model.
Usage implies converting to <a href="#everything_quantities">
everything_quantities</a> mode.
 Syntax: 
<pre>
area_method_name <em>quoted_method_name</em>
</pre>
For example,
<pre>
string
space_dimension 2
area_method_name "circular_arc_area"
</pre>

<hr>
<a   id="volume_method_name"></a><h2>Volume method</h2>
 This item, <code>volume_method_name</code>, specifies
the name of the pre-defined method to use as the
method to compute body volumes in place of the default 
<a href="quants.htm#edge_area">edge_area</a> method in the string model
or <a href="quants.htm#facet_volume">facet_volume</a> method in the 
soapfilm model.  It is optional. Developed so circular arcs can be
used in two-dimensional foams.  Synonymous with <a href="#area_method_name">
area_method_name</a> in the string model.
Usage implies converting to <a href="#everything_quantities">
everything_quantities</a> mode.
 Syntax: 
<pre>
volume_method_name <em>quoted_method_name</em>
</pre>
For example,
<pre>
string
space_dimension 2
volume_method_name "circular_arc_area"
</pre>

<hr>
<a   id="hessian_special_normal_vector"></a><h2>Hessian special normal vector</h2>

When <a href="toggle.htm#hessian_special_normal">hessian_special_normal</a>
is on, hessian commands use  
a special vectorfield for the direction of the perturbation, rather
than the usual surface normal.  The vectorfield is specified in the
format
<pre>
HESSIAN_SPECIAL_NORMAL_VECTOR
c1: <em>expr</em>
c2: <em>expr</em>
c3: <em>expr</em>
</pre>
One can use vertex attributes in the expressions.  Beware that
hessian_special_normal also applies to the normal calculated by
the  <a href="elements.htm#vertex_normal">vertex_normal</a> attribute and the normal
 used by regular <a href="commands.htm#vertex_average">vertex averaging</a>. 
<hr>
<a   id="simplex-decl"></a><h2>Simplex model declaration</h2>
To declare that the datafile lists a surface in the 
<a href="model.htm#simplex-model">simplex model</a>,
the top section ot the datafile should contain the line
<pre>
SIMPLEX_REPRESENTATION
</pre>
The main effect on the datafile is that 
<a href="#faces-section">faces</a> are defined by oriented
vertex lists rather than edge lists.

<hr>
<a   id="diffusion-decl"></a><h2>Diffusion</h2>

The Evolver can simulate the real-life phenomenon of gas diffusion between
neighboring bubbles. This diffusion is driven by the pressure difference
across a surface. This is invoked by the keyword DIFFUSION in the first
part of the datafile, followed by the value of the diffusion constant,
which is the internal variable diffusion_coeff. 
<pre>
    DIFFUSION 0.1
</pre>
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.
<p>
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.
<p>
Diffusion can be toggled at runtime with the "diffusion" toggle command.
<p>

<hr>
<a   id="load_library"></a><h2>Dynamic load library</h2>
To load a <a href="misc.htm#dynamic-load-library">dynamic library</a>
 of compiled functions, the syntax is 
<pre>
 LOAD_LIBRARY "<em>filename</em>"
</pre>
where the double-quoted filename is the library.  The current
directory and the <a href="install.htm#EVOLVERPATH">EVOLVERPATH</a>
will be searched for the library.

<hr>
<a   id="wulff"></a> <a   id="hemisphere"></a> <a   id="lens"></a>
<a   id="wulff-decl"></a><h2>Crystalline integrands</h2>
To declare that surface area energy should be calculated with
a crystalline integrand, the top section of the datafile should
contain a line of the form
<pre>
 WULFF "<em>filename</em>"
</pre>

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.
<hr>
<a   id="phasefile"></a>
<a   id="phase"></a>
<a   id="phase-decl"></a><h2>Phase file declaration</h2>
To declare that the 
<a href="energies.htm#surface-tension">surface tension</a>
 of an edge or facet depends on
the phases of its adjacent 
<a href="elements.htm#phase,-facet">facets</a> or 
<a href="elements.htm#phase,-body">bodies</a>, the top section of the datafile
should contain a line of the form
<pre>
 PHASEFILE "<em>filename</em>" 
</pre>
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 <code>PHASE</code> <i>n</i> phrase
in the datafile.
<hr>
<a   id="ideal-gas-decl"></a><h2>Ideal gas model</h2>
A line in the top section of the datafile of the form
<pre>
PRESSURE <em>constexpr</em>
</pre>

specifies that bodies are compressible
     and the ambient pressure is the value of <em>constexpr</em>.
       The default is that bodies with given volume
              are not compressible.
<hr>
<a   id="interp_bdry-decl"></a><h2>Interpolation of parameters</h2>
To use interpolation instead of extrapolation in calculating the 
<a href="constrnt.htm#parametric-boundaries">parameters</a>
 of edge midpoints during refining, use the keyword
<pre>   INTERP_BDRY_PARAM
</pre>
This should be done only if there are no periodic parameters.

<hr>
<a   id="everything_quantities"></a><h2>Everything_quantities</h2>
Keyword in top section of the datafile.  Causes all areas, volumes,
etc. to be converted to named quantities and methods. Equivalent
to the command line <a href="general.htm#options">option -q</a>,
or the <a href="commands.htm#convert_to_quantities">
convert_to_quantities</a> command.
<hr>
<a   id="mobility_tensor"></a>
<a   id="mobility-decl"></a><h2>Mobility declaration</h2>
A <a href="model.htm#mobility">mobility</a>
 matrix may be defined in the top section of the datafile
by the syntax
<pre>
MOBILITY_TENSOR
<em>expr expr expr</em>
<em>expr expr expr</em>
<em>expr expr expr</em>
</pre>               
or
<pre>
MOBILITY <em>expr</em>
</pre>
The first form gives the full mobility matrix, and the second form
gives the matrix as a scalar multiple of the identity matrix.
The formulas are evaluated at each vertex at each iteration, and 
so formulas may depend on vertex position and any vertex attributes.
<hr>
<a   id="conformal_metric"></a>
<a   id="klein_metric"></a>
<a   id="metric-decl"></a><h2>Metric declaration</h2>
A <a href="model.htm#Riemannian-metric">Riemannian metric</a>
 on the ambient space may be declared in the
top section of the datafile with the syntax
<pre>METRIC
<em>expr expr expr</em>
<em>expr expr expr</em>
<em>expr expr expr</em>
</pre>               
or
<pre>
CONFORMAL_METRIC <em>expr</em>
</pre>
or
<pre>
KLEIN_METRIC
</pre>
The keyword <code>METRIC</code> 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 
<a href="model.htm#conformal-metric">conformal metric</a> 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 <a href="model.htm#Klein-hyperbolic-metric">Klein metric</a>
 is a built-in metric for hyperbolic
	      n-space modelled on the unit disk or ball.

<hr>
<a   id="merit_factor"></a> <h2>Merit factor</h2>
If the keyword <code>MERIT_FACTOR</code> is present, then the
<a href="single.htm#i">i</a> 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.
<hr>


<a   id="square_curvature"></a> <a   id="curvature_power"></a>
<a   id="square_gauss_modulus"></a>
<a   id="squared_curvature"></a><h2>Squared mean curvature</h2>

To add an energy of squared mean curvature, include a line in the
top of the datafile
<pre>  SQUARED_CURVATURE modulus
</pre>
The 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.
<p>
In the string model, the power of the curvature is controlled by
the internal read-write variable curvature_power.
<hr>
<a   id="sqgauss"></a>
<a   id="square_gaussian_curvature"></a>
<a   id="squared_gaussian_curvature"></a><h2>Squared Gaussian curvature</h2>

To add an energy of squared Gaussian curvature, include a line in the
top of the datafile
<pre>  SQUARED_GAUSSIAN_CURVATURE modulus
</pre>
The modulus is a multiplier for the energy, and is available at runtime
in the read-write variable square_gauss_modulus. Synonyms:
Synonyms: <code>square_gaussian_curvature</code>, <code>sqgauss</code>

<hr>
<a   id="zoom_vertex"></a><h2>Zoom_vertex</h2>
Datafile keyword setting the current <a href="commands.htm#zoom">zoom</a>
vertex.  Used in dump files after a zoom command has been given.

<hr>
<a   id="zoom_radius"></a><h2>Zoom_radius</h2>
Datafile keyword setting the current <a href="commands.htm#zoom">zoom</a>
radius.  Used in dump files after a zoom command has been given.


<hr>
<a   id="unsuppress_warning"></a>
<a   id="suppress_warning"></a><h2>Suppress_warning</h2>
Datafile keyword instructing Evolver not to print a certain warning.
Syntax:
<pre>
  SUPPRESS_WARNING <em>number</em>
</pre>
where <em>number</em> is the number of the warning.  Meant to suppress
irritating warning messages that you know are irrelevant.  Warnings
can be restored with the syntax
<pre>
  UNSUPPRESS_WARNING <em>number</em>
</pre>

<hr>
<a   id="vertices_predicted"></a><h2>Vertices_predicted</h2>
Datafile keyword in the top section of the datafile that specifies the
initial allocation of vertex structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the vertex list grows or as
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the <a href="single.htm">d</a> or
 <a href="commands.htm">dump</a> commands, based on
the current number of vertices.
Example:
<pre>
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432
</pre>


<hr>
<a   id="edges_predicted"></a><h2>Edges_predicted</h2>
Datafile keyword in the top section of the datafile that specifies the
initial allocation of edge structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the edge list grows or as
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the <a href="single.htm">d</a> or
 <a href="commands.htm">dump</a> commands, based on
the current number of edges.
Example:
<pre>
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432
</pre>

<hr>
<a   id="facets_predicted"></a><h2>Facets_predicted</h2>
Datafile keyword in the top section of the datafile that specifies the
initial allocation of facet structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the facet list grows or as
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the <a href="single.htm">d</a> or
 <a href="commands.htm">dump</a> commands, based on
the current number of facets.
Example:
<pre>
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432
</pre>

<hr>
<a   id="bodies_predicted"></a><h2>Bodies_predicted</h2>
Datafile keyword in the top section of the datafile that specifies the
initial allocation of body structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the facet list grows or as
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the <a href="single.htm">d</a> or
 <a href="commands.htm">dump</a> commands, based on
the current number of bodies.
Example:
<pre>
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432
</pre>


<hr>
<a   id="facetedges_predicted"></a><h2>Facetedges_predicted</h2>
Datafile keyword in the top section of the datafile that specifies the
initial allocation of facetedge structures.  Optional.  The purpose is to
prevent repeated reallocation of memory as the facetedge list grows or as
the surface evolves.  Should be faster, and prevents memory fragmentation.
Automatically put in dump files by the <a href="single.htm">d</a> or
 <a href="commands.htm">dump</a> commands, based on
the current number of facetedges.
Example:
<pre>
    vertices_predicted 3074
    edges_predicted    9216
    facets_predicted   6144
    bodies_predicted      1
    facetedges_predicted  18432
</pre>

<hr>
<a   id="quantities_predicted"></a><h2>Quantities_predicted</h2>
Datafile keyword in the top section of the datafile that specifies the
initial allocation of named quantity structures.  Optional.  The purpose is
to prevent repeated reallocation of memory as the quantity list grows.
Not significant if there are only a few quantities,  but there are
times when there can be thousands of quantities, such as when
"everything_quantities" is used with a large foam. Automatically put in
dump files by the "d" or "dump" commands, based on the current number of
quantities.  This declaration obviously should come before any quantities
are defined.
Example:
<pre>
    vertices_predicted 30748
    edges_predicted    92166
    facets_predicted   61446
    bodies_predicted    2048
    facetedges_predicted  184320
    method_instances_predicted   4098
    quantities_predicted   2050
</pre>

<hr>
<a   id="method_instances_predicted"></a><h2>Method_instances_predicted</h2>

Datafile keyword in the top section of the datafile that specifies the
initial allocation of method instance structures.  Optional.  The purpose is
to prevent repeated reallocation of memory as the instance list grows.
Not significant if there are only a few method instances,  but there are
times when there can be thousands of instances, such as when
"everything_quantities" is used with a large foam. Automatically put in
dump files by the "d" or "dump" commands, based on the current number of
method instances. This declaration obviously should come before any quantities
are defined.
Example:
<pre>
    vertices_predicted 30748
    edges_predicted    92166
    facets_predicted   61446
    bodies_predicted    2048
    facetedges_predicted  184320
    method_instances_predicted   4098
    quantities_predicted   2050
</pre>


<hr>
<hr>
<a   id="element-lists"></a><h2>Element lists</h2>

The lists of geometric elements follow a general format.  Each element
is defined on one line.  The first entry on a line is the element number.
Numbering need not be consecutive, and may omit numbers, but be aware
that internally elements will be renumbered in order.  The original number
in the datafile is accessible as the 
<a href="elements.htm#original">original</a> attribute of an element.
After the element number comes the basic defining data, followed by
optional attributes in arbitrary order.  Besides the particular attributes
for each element type listed below, one may specify values for any
<a href="elements.htm#extra-attributes">extra attributes</a>
 defined earlier.  The syntax is attribute name followed
by the appropriate number of values. 
Also an arbitrary number of 
<a href="quants.htm#named-quantities">named quantities</a> or
<a href="quants.htm#method-instances">method instances</a> 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. 
<hr>
<a   id="vertices-section"></a><h2>Vertex list</h2>

    The datafile vertex list is started by the keyword <code>VERTICES</code> at
              the start of a line. It is followed by lines with
              one vertex specification per line. If the vertex is
              not on a 
<a href="constrnt.htm#parametric-boundaries">parametric boundary</a>, the syntax is
<pre>
<em>k   x y ...</em> [FIXED] [CONSTRAINT <em>c1 c2 ...</em>]  [BARE]
            [<em>quantityname ...</em>] [<em>methodname ...</em>]
</pre>
The syntax for a vertex on a 
<a href="constrnt.htm#parametric-boundaries">parametric boundary</a> is
<pre>
<em>k p1 [p2 ...] </em> BOUNDARY <em>b</em> [FIXED] [BARE] [<em>quantityname ...</em>] 
   [<em>methodname ...</em>] 
</pre>
          Here <em>k</em> 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.
              <em>x y ...</em> are constant expressions 
              for coordinates.
              In the parametric boundary format, the boundary parameter
              values are given instead of the coordinates. 
           If <a href="elements.htm#fixed,-vertex"><code>FIXED</code></a> is given,
              then the vertex never moves, except possibly for an
              initial projection to constraints. If <code>CONSTRAINT</code> is 
              given, then one or more 
<a href="constrnt.htm#level-set-constraints">constraint</a> 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.
<p>
	      The  <a href="elements.htm#bare,-vertex"><code>BARE</code></a>
 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.
<p>An arbitrary number of 
<a href="quants.htm#named-quantities">named quantities</a>
 or <a href="quants.htm#method-instances">method instances</a> may
	      be listed.  These add method values for this element to the
	      named quantity.  The named quantity or instance
	      must have been
<a href="#named-quantity-decl">declared</a> in the top section of the datafile. 
<p>
The <a href="commands.htm#list">list</a>
<a href="commands.htm#list"> vertices</a> command
prints the datafile format listing of vertices.
<hr>

<a   id="edges-section"></a><h2>Edge list</h2>
              The datafile edge list follows the vertex list,
              and is started by the keyword <code>EDGES</code> at the 
              start of a line.  It is followed by lines with one
              edge specification per line in this format (linespliced here):
<pre>
<em>k v1 v2 [midv] [s1 s2 s3]</em> [WRAP <em>w</em>] [FIXED] [BOUNDARY <em>b</em>] \
   [CONSTRAINTS <em>c1 [c2 ...]</em>] [TENSION <em>constexpr</em>] [COLOR <em>n</em>] \
     [BARE]  [<em>quantityname ...</em>] [<em>methodname ...</em>] 
</pre>

Here <em>k</em> is the edge number, with numbering following the same
rules as for vertices.  <em>v1</em> and <em>v2</em> are the numbers of
the tail and head vertices of the edge.  In the 
<a href="model.htm#quadratic-model">quadratic model</a>, the
edge midpoint may be listed as a third vertex <em>midv</em> (otherwise a
midpoint vertex will be created).  In the 
<a href="model.htm#torus-model">torus model</a>, there must
follow signs <em>s1 s2 s3</em> indicating how the edge
wraps around each unit cell direction: + for once
positive, * for none, and - for once negative.  In non-torus
<a href="model.htm#symmetry-groups">symmetry groups</a>, each edge 
should have a <code>WRAP</code> symmetry group element encoded as an integer.
<a href="elements.htm#fixed,-edge"><code>FIXED</code></a> means that
all vertices and edges resulting from subdividing this edge will have
the <code>FIXED</code> attribute; it does not mean that the
endpoints will be automatically fixed.  Likewise the  
<a href="constrnt.htm#parametric-boundaries"><code>BOUNDARY</code></a> and 
<a href="constrnt.htm#level-set-constraints"><code>CONSTRAINT</code></a>
 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 
<a href="model.htm#string-model">string model</a>, 
the default tension is 1, and in the 
<a href="model.htm#soapfilm-model">soapfilm model</a>, the default
tension is 0.  However, edges may be given nonzero tension in the
soapfilm model, and they will contribute to the energy.
<p>
 If the <a href="model.htm#simplex-model">simplex model</a>
 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.
<p>
     The <a href="elements.htm#bare,-edge"><code>BARE</code></a>
 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.

<p>An arbitrary number of 
<a href="quants.htm#named-quantities">named quantities</a>
 or <a href="quants.htm#method-instances">method instances</a> may
	      be listed.  These add method values for this element to the
	      must have been
<a href="#named-quantity-decl">declared</a> 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.
<p>
The <a href="commands.htm#list">list</a>
<a href="commands.htm#list">edges</a> command
prints the datafile format listing of edges.
<hr>

<a   id="faces-section"></a><a   id="face"></a><a   id="faces"></a>  
<h2>   Face list</h2>

       The datafile face list follows the edge list, 
       and is started by the keyword <code>FACES</code> at the 
       start of a line.  It is followed by lines with one
         facets specification per line in this format:
<pre>
  <em>k   e1 e2 ...</em>  [FIXED] [TENSION <em>constexpr</em>] [BOUNDARY <em>b</em>] \
  [CONSTRAINTS <em>c1 [c2 ...]</em>]     [NODISPLAY]   \
   [COLOR <em>n</em>]} [FRONTCOLOR <em>n</em>] [BACKCOLOR <em>n</em>] \
   [PHASE <em>n</em>] [<em>quantityname</em> ...] [<em>methodname</em> ...] 
</pre>
              Here <em>k</em> is the face number, with numbering following the 
              same rules as for 
<a href="#vertices-section">vertices</a>. 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 
<a href="model.htm#string-model">string model</a>).
              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 
<a href="model.htm#soapfilm-model">soapfilm model</a>.
              The 
<a href="elements.htm#density,-facet"><code>TENSION</code></a>
 (synonym: <code>DENSITY</code>) 
value is the energy per unit area
              (the <a href="energies.htm#surface-tension">surface tension</a>)
 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.
              <a href="elements.htm#nodisplay"><code>NODISPLAY</code></a>
prevents the facet from being displayed.
	      The  <a href="elements.htm#color,-facet"><code>COLOR</code></a>
 attribute applies to both sides of a facet;
	      <a href="elements.htm#frontcolor"><code>FRONTCOLOR</code></a>
 applies to the positive side (edges
	      going counterclockwise) and 
<a href="elements.htm#backcolor"><code>BACKCOLOR</code></a> to the 
	      negative side.
              The <a href="elements.htm#phase,-facet"><code>PHASE</code></a> 
number is used in the <a href="model.htm#string-model">string model</a>
              to determine the surface tension of edges between facets
              of different phases, if phases are used.
<p>
              If the <a href="model.htm#simplex-model">simplex model</a>
 is in effect, the edge list should
              be replaced by an oriented list of vertex numbers.

<p>An arbitrary number of 
<a href="quants.htm#named-quantities">named quantities</a>
 or <a href="quants.htm#method-instances">method instances</a> may
	      be listed.  These add method values for this element to the
	      must have been
<a href="#named-quantity-decl">declared</a> 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.
<p>
              The faces section is optional in the 
<a href="model.htm#string-model">string model</a>.

<p>
The <a href="commands.htm#list">list</a>
<a href="commands.htm#list">facets</a> command
prints the datafile format listing of facets.
<hr>


<a   id="bodies-section"></a><h2> Body list</h2>

              The datafile body list follows the face list, and 
              is started by the keyword <code>BODIES</code> at the
              start of a line.  It is followed by lines with one
              body specification per line in this format:
<pre>
<em>k  f1 f2 f3 ....</em> [VOLUME <em>constexpr</em>] [VOLCONST <em>constexpr</em>] [ACTUAL_VOLUME <em>constexpr</em>] \
[PRESSURE <em>p</em>] [DENSITY <em>constexpr</em>] [PHASE <em></em>] 
</pre>

              Here <em>k</em> is the body number, 
              and <em>f1 f2 f3 ...</em> 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 
              <code>VOLUME</code> value <em>constexpr</em> means the body has a 
<a href="elements.htm#target-volume">volume constraint</a>,
              unless the
<a href="datafile.htm#ideal-gas-decl">ideal gas model</a>
 is in effect, in which case <em>constexpr</em>
              is the volume at the ambient pressure. 
              <a href="elements.htm#body-volconst"><code>VOLCONST</code></a>
 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 <a href="model.htm#torus-model">torus model</a>.
<code>ACTUAL_VOLUME</code> 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 <code>PRESSURE</code> value means
              that the body is deemed to have a constant internal
              <a href="elements.htm#pressure,-body">pressure</a>;
 this is useful for prescribed mean
              curvature problems.  It is incompatible with
              prescribed volume.  Giving a 
<a href="elements.htm#density,-body"><code>DENSITY</code></a> value means
              that 
<a href="energies.htm#gravity-energy">gravitational potential energy</a>
  will be included. 
<p>
              To endow a facet with <code>VOLUME</code>, <code>PRESSURE</code>, 
or <code>DENSITY</code>
         attributes in the <a href="model.htm#string-model">string model</a>,
 define a body with just the one facet.
<p>
              The 
<a href="elements.htm#phase,-body"><code>PHASE</code></a>
 number is used in the <a href="model.htm#soapfilm-model">soapfilm model</a>
    to determine the <a href="energies.htm#surface-tension">surface tension</a>
 of facets between bodies of different phases, if phases are used.
<p>
              The <code>BODIES</code> section is optional.
<p>
The <a href="commands.htm#list">list</a>
<a href="commands.htm#list">bodies</a> command
prints the datafile format listing of bodies.
<hr>
<a   id="read-section"></a><h2> READ section</h2>
  The final section of the datafile may contain commands.
  These commands are read and executed immediately, just as
  if they had been entered at the command prompt.
       Encountering the keyword  <code>READ</code> 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 <code>READ</code> section is optional.
Example:
<pre>  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 }

</pre>
The <a href="commands.htm#bottominfo">list bottominfo</a> command
prints the <code>READ</code> section that would be printed in a dump file.
<hr>
<a href="evolver.htm#doc-top">Back to top of Surface Evolver documentation.</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="index.htm">Index.</a>
</body>
</html>