# Surface Evolver Documentation

Back to top of Surface Evolver documentation. Index.

# Miscellaneous terms

This file provides some entries for various keywords that are not used as name pointers elsewhere for ambiguity, incredible obscurity, or some other reason.

### Alice

A keyword for a special purpose command not documented.

### Area

As a keyword, area is a read-only attribute of a facet.

### Area_fixed

An obsolete way of declaring the total area of the surface fixed in the datafile. Synonym: fixed_area. The preferred way of doing this now is to define a fixed named quantity in the datafile, such as
`quantity the_area fixed = 2.3 global_method facet_area`
This permits all the named quantity features to be used.

### Attribute

As a keyword, "attribute" is used in the define command for element extra attributes.

### Bare

As a keyword, "bare" is a vertex attribute or an edge attribute set by the user that tells the Evolver not to expect the vertex or edge to be attached to a facet.

### Body

A body is a three dimensional geometric element. As a command keyword, "body" is an element name in element generators, either as the main element type, or as a subelement of a facet.

### Burchard

A keyword for a special purpose command not documented.

### Color

As a keyword, "color" is an attribute of edges and facets. For the permitted values, see colors.

### Conducting_knot_energy

Datafile keyword that automatically creates an energy named quantity using the method knot_energy as a global method. May be followed in the datafile with a modulus value.

### Insulating_knot_energy

Datafile keyword that automatically creates an energy named quantity using the method uniform_knot_energy as a global method. May be followed in the datafile with a modulus value.

### Constraint

"Constraint" can be used in a general sense, but as a keyword it refers to level set constraints. "Constraint" and "constraints" are interchangeable.

### Content

"Content" is used to mean volume (or area, in the string model) in constraint integrals.

### Convex

A keyword used in declaring a constraint in the datafile that causes a gap energy to be included. The idea is to prevent straight edges and facets from short-cutting curved constraints with big gaps.

### Density

A keyword referring either to the gravitational density of a body, or to the surface tension of a facet, or to the linear tension of an edge. In the latter two cases, "density" is synonymous with "tension".

### Edge

In general, one of the basic geometric elements. As a keyword, it is used in element generators. Synonym: edges.

### Efixed

Obsolete datafile attribute to make an edge fixed without fixing its endpoints. Keyword retained just for compatibility with old dump files.

### Eprint

Function that prints an expression and returns the value. Syntax: eprint expr. Meant for debugging; probably an archaic leftover from when the command language was not as developed. Example: `print sum(facet, eprint area)` will print out all the facet areas and then the sum.

### Facet

> In general, one of the basic geometric elements. In the soapfilm model, it is a triangle defined by its three oriented edges. In the string model, it is a connected sequence of edges of arbitrary number. In the simplex model, it is a simplex of dimension given by the surface_dimension item in the top of the datafile, and is defined by its vertices.

### Fixed

Attribute that can be applied to vertices, edges, facets, or named quantities.

### Formula

Datafile keyword used in level set constraints to introduce the function formula. Synonym: function

### Gauss_curvature

Datafile keyword that automatically creates an energy named quantity using the method gauss_curvature_integral as a global method. May be followed in the datafile with a modulus value.

### Tolerance

As a keyword, "tolerance" refers to a fixed quantity attribute that is used as the criterion for convergence. Uses target_tolerance as the default value.

### Div_normal_curvature

Toggle to make sq_mean_curvature energy calculate the mean curvature by the divergence of the normal vectors at the vertices of a facet.

### Force_pos_def

Toggle. If this is on during YSMP factoring of Hessian and the Hessian turns up indefinite, something will be added to the diagonal element to make it positive definite. Left over from some experiment probably.

### H_inverse_metric

Toggle. Replaces force by Laplacian of force. For doing motion by Laplacian of mean curvature.

### Modulus

A keyword that is an attribute of a named quantity or a method instance, which is a multiplier for the calculated value.

### Opacity

Facet attribute for transparency on some geomview systems. Syntax: `set facet opacity` value where value is between 0 and 1. Actually, this just sets a global variable for all facets simultaneously. The value is passed to geomview in the alpha slot of the color.

### Parameter

Refers to either a parametric boundary parameter, or a user-defined variable.

### Parameter_file

In the top section of the datafile, a variable can be initialized with a set of values in a file with the syntax

    PARAMETER name PARAMETER_FILE string

I forget exactly how it is all supposed to work.

### Pressure

Usually means an attribute of fixed-volume bodies or fixed named quantities that is actually the Lagrange multiplier for the constraint. As body attribute in the datafile, establishes fixed pressure for the body. Also used rarely in the top section of the datafile to establish the ideal gas model.

### Surface_energy

An obsolete way of including vector surface energy integrals in the datafile. The present method is to use a named quantity with the facet_vector_integral method.

### Total

An obsolete syntax for the value of a named quantity (e.g. my_quant) is "total my_quant". The present syntax is "my_quant.value".

### Valence

An attribute of a vertex, which is the number of incident edges, or an attribute of an edge, which is the number of incident facets, or an attribute of a facet, which is the number of edges on the facet.

### Vertex

One of the basic geometric elements. As a keyword, it is used in element generators.

### Utest

Runs a test to see if triangulation is Delaunay. Meant for higher dimensions and simplex model.

### Stability_test

Command to find largest eigenvalue of mobility matrix. Don't really recall what this was for.

### Tag

An obsolete facet attribute, once used to associate an arbitrary value with a facet. Now superseded by extra attributes.

## Dynamic load libraries.

This feature hasn't been used much, but documentation is included here for completeness. Many Evolver features, such as level set constraints, parametric boundaries, named method integrands, and Riemannian metrics require user-defined functions of a set of arguments. The expressions for these functions are ordinarily stored as a parse tree and interpreted each time needed, which can be much slower that evaluating compiled expressions. There is a way to use a set of compiled functions specific to a datafile through a mechanism known as dynamic loading. Here a library of functions for a datafile is separately compiled, and then loaded at runtime when a the datafile is loaded. Currently, the Evolver only implements a dynamic loading mechanism found on many unix systems, whose presence can be tested by looking for the existence of the file /usr/include/dlfcn.h. If it exists, you can enable dynamic loading by including -DENABLE_DLL in the CFLAGS line in the Makefile. On some systems, you may need to include -ldl on the GRAPHLIB line also, to link Evolver with functions such as dlopen(). To create the library for a datafile, write a source file containing C code for the desired functions, compile it, and link it into a shared library. The function should be able to compute the value and the partial derivatives of the function, and its second partials if you are going to use any Hessian features. A sample source file for a 2-dimensional datafile:

    #define FUNC_VALUE  1
    #define FUNC_DERIV  2
    #define FUNC_SECOND 3
    #define MAXCOORD 4   /* must be same as in Evolver!! */
    #define REAL double  /* long double if Evolver compiled with -DLONGDOUBLE */
    struct dstack { REAL value;
    		REAL deriv[2*MAXCOORD];
                    REAL second[2*MAXCOORD][2*MAXCOORD]; };

    void func1 ( mode, x, s )
    int mode; /* FUNC_VALUE, FUNC_DERIV, FUNC_SECOND */
    REAL *x;  /* pointer to list of arguments */
    struct dstack *s;  /* for return values */
    { REAL value;

      s->value = x[0] + x[1]*x[1];

      if ( mode == FUNC_VALUE ) return;

      /* first partials */
      s->deriv[0] = 1.0;
      s->deriv[1] = 2*x[1];

      if ( mode == FUNC_DERIV ) return;

      /* second partials */
      s->second[0][0] = 0.0;
      s->second[0][1] = 0.0;
      s->second[1][0] = 0.0;
      s->second[1][1] = 2.0;

      return;
    }

Supposing the sourcefile name to be foo.c, compile and link on SGI systems (IRIX 5.0.1 or above) with

    cc -c foo.c
    ld -shared foo.o -o foo.so

Sun systems are the same, but with -s in place of -shared. For other systems, consult the ld documentation for the option to make a shared library or dynamic load library.

To use the functions in a datafile, include a line at the top of the datafile before any of the functions are used:

    load_library "foo.so"

The current directory and the EVOLVERPATH will be searched for the library. Up to 10 libraries may be loaded. Afterwards, any of the functions may be invoked just by using their name, without an explicit argument list because the argument list is always implicit where these functions are legal. Examples, supposing func2 is also defined with one argument:

    constraint 1
    formula: func1

    boundary 1 parameters 2
    x1: func2
    x2: 3*func2 + sin(p1)

It is up to you to make sure the number of arguments your function expects is the same as the number implicit in the use of the function. You do not need to explicitly declare your functions in the datafile. Any undefined identifier is checked to see if it is a dynamically loaded function.

NOTE: This implementation of dynamic loading is experimental, and the interface described here may change in the future.

### __bhead_index

A body attribute used internally by Hessian routines.

### __vhead_index

A vertex attribute used internally by Hessian routines.

### form_factors

A facet extra attribute vector used by several elastic energy named methods: linear_elastic, neo_hookean, relaxed_elastic, relaxed_elastic_A, SVK_elastic, and dirichlet_elastic. The entries are the dot products of the sides of the relaxed facet. Due to symmetry, there are only three distinct dot products, so form_factors just has length 3. The entries are {s11,s12,s22}, where s11 = dot(v2-v1,v2-v1), s12 = dot(v2-v1,v3-v1), and s22 = dot(v3-v1,v3-v1). If form_factor is not defined by the user, it will be created by Evolver, and the initial facet shape will be assumed to be unstrained.

### poisson_ratio

Facet extra attribute used by various elastic named methods: linear_elastic, linear_elastic_B, neo_hookean, relaxed_elastic, relaxed_elastic_A, SVK_elastic, and dirichlet_elastic. This is the two-dimensional isotropic poisson ratio.

Some physical surfaces have their lowest energy state when their mean curvature is some nonzero value. An example is a membrane made of parallel stacked molecules which have one end bigger than the other. Their curvature energy is thus proportional to (h-h0)^2, where h is the actual mean curvature and h0 is the equilibrium or intrinsic mean curvature. Several of the squared mean curvature named methods can use h0, either in the form of a variable h_zero or a real-valued vertex attribute h_zero. If the vertex attribute exists, it takes precedence. Methods using h_zero:

- sq_mean_curv_cyl
- sq_mean_curvature
- eff_area_sq_mean_curvature
- normal_sq_mean_curvature
- star_normal_sq_mean_curvature
- star_perp_sq_mean_curvature
- sqcurve2_string

Methods not using h_zero:

- star_sq_mean_curvature
- star_eff_area_sq_mean_curvature
- sqcurve_string
- sqcurve_string_marked
- sqcurve3_string
- circle_willmore

### knot_power

Internal read-write variable used as exponent on some term in various knot energies. Named methods using knot_power are:

- buck_knot_energy
- charge_gradient
- facet_knot_energy
- facet_knot_energy_fix
- knot_energy
- knot_thickness_0
- knot_thickness_p
- knot_thickness_p2
- proj_knot_energy
- sphere_knot_energy
- uniform_knot_energy
- uniform_knot_energy_normalizer
- uniform_knot_normalizer1
- uniform_knot_normalizer2

### surface_knot_power

Internal read-write variable used in the facet_knot_energy and sphere_knot_energy named methods as the exponent of the denominator.

### LEBweight>

Facet extra attribute used to weight individual facets in the named methods linear_elastic_B, named methods relaxed_elastic, named methods relaxed_elastic_A,

### old_force_ribiere

Vertex extra attribute used internally by conjugate gradient mode.

### parameter_1

A generic parameter used by a couple of named methods.

Back to top of Surface Evolver documentation. Index.