Surface Evolver Documentation - Geometric elements

# Surface Evolver Documentation

Back to top of Surface Evolver documentation. Index.

# Geometric elements

The surface is defined in terms of its geometric elements of each dimension. Each element has its own set of attributes. Some may be set by the user; others are set internally but may be queried by the user. It is also possible to dynamically define extra attributes for any type of element, which may be single values or vectors of values. Attribute values can be specified in the datafile, and queried with commands.

Elements: vertices, edges, facets, bodies, facet-edges.

## Vertices

A vertex is a point in space. The coordinates of the vertices are the parameters that determine the location of the surface. It is the coordinates that are changed when the surface evolves. A vertex carries no default energy, but may have energy by being on a level set constraint in the string model, or by having a named quantity energy applied to it. The vertices of the original surface are defined in the vertices section of the datafile.

Attributes:

id original coordinates parameter values fixed constraints on_constraint hit_constraint __v_constraint_list boundary on_boundary bare edges facets | valence quantities on_quantity on_method_instance mid_edgedihedral mid_facet square mean curvature axial_point triple_point tetra_point vertexnormal __force __velocity extra attributes

## Edges

An edge is a one-dimensional geometric element. In the linear model, an edge is an oriented line segment between a tail vertex and a head vertex. In the quadratic model, an edge is defined by quadratic intepolation of two endpoints and a midpoint. In the lagrange model, an edge is defined by the appropriate order interpolation with the edge vertices. In the string model, edges carry a default surface tension energy proportional to their length. Edges may also carry energy by being on level set constraints in the soapfilm model, or by having named quantity energies applied to them. The edges of the original surface are defined in the edges section of the datafile.

Attributes:

id oid original length density or tension fixed constraints on_constraint __e_constraint_list boundary on_boundary wrap color noncontent bare | no_refine orientation vertices midv facets valence backbody frontbody dihedral tangent vector quantities on_quantity on_method_instance extra attributes

## Facets

In the soapfilm model, a facet is an oriented triangle defined by a cycle of three edges. In the linear model, a facet is a flat triangle. In the quadratic model, the facet is a curved surface defined by quadratic interpolation among the three facet corner vertices and the three edge midpoints. In the Lagrange model, lagrange_order interpolation is done among (lagrange_order+1)(lagrange_order+2)/2 vertices. Although individual facets are oriented, there are no restrictions on the orientations of adjacent facets. By default, a facet carries a surface tension energy equal to its area.

In the string model, a facet is a chain of an arbitrary number of edges. The chain need not be closed. Usually a facet is defined in the string model in order to define a body, so the space dimension is 2 and the facet is planar, one facet corresponding to a body. Facets carry no energy by themselves.

In the simplex model, a facet is a simplex of dimension surface_dimension defined by surface_dimension+1 vertices. The surface_dimension may be any dimension less than or equal to the space_dimension. The simplex is oriented according to the order of the vertices. By default, a simplex carries a surface tension energy proportional to its volume.

Facets may carry additional energy by having named quantity energies applied to them.

The facets of the original surface are defined in the faces section of the datafile.

Attributes:

id oid original area fixed constraints on_constraint constraint list boundary on_boundary density or tension color frontcolor backcolor no_refine noncontent | edges vertices bodies frontbody backbody valence normal vector phase quantities on_quantity on_method_instance nodisplay extra attributes

## Bodies

A body is a full-dimensional region of space. Bodies are not triangulated. Rather, they are determined by their boundary facets (or edges in 2D). These facets are used for calculating body volume and gravitational energy. Only those facets needed for correct calculation need be given. In the string model, usually a body corresponds to one facet. Bodies of the original surface are defined in the bodies section of the datafile.

Attributes:

facets id density volume target volfixed | actual_volumet volconst pressure phase extra attributes

## Facetedges

A facetedge is a pairing of a facet and one of its edges, with orientation such that the edge orientation is consistent with the facet orientation. Facetedges are used internally by Evolver, and are seldom of interest to the user. They carry no energy. The C command will sometimes refer to facetedges if the surface is inconsistent. "Facetedge" can be used as an element generator. The attributes available are id, edge, facet, and extra attributes.

# Element attributes

Below is a list of possible element attributes. The first few apply to all types of elements. Then come those applying specifically to vertices, edges, facets, and bodies. See Geometric elements for lists of attributes for each type element.

# Attributes for all types of elements

## id

Geometric element read-only attribute. The id of an element is a positive integer uniquely associated with that element. The Evolver will assign id's to elements read from the datafile in the order they are read, unless the -i command line option or `keep_originals` is in the top of the datafile, in which case the datafile element number is the id. In either case, you can access the datafile id with the original attribute. Examples:

       list vertex where id < 10
       set edge color red where id == 4 or id == 6 or id == 9
       foreach facet ff do { printf "%g  %g %g %g\n",ff.id,ff.edge[1].id,
          ff.edge[2].id,ff.edge[3].id }

## oid

Geometric element read-only attribute. The oid of an element is the "oriented id" of an element as used in an expression. It is the id number signed according to whether the use of the element is with the same or opposite orientation as the way it is stored. Example: to get an edge list for a facet as in the datafile, use oid instead of id:

       foreach facet ff do { printf "%g  %g %g %g\n",ff.id,ff.edge[1].oid,
          ff.edge[2].oid,ff.edge[3].oid }

## on_constraint

Vertex, edge, or facet read-only attribute. Boolean attribute for whether an element is on a given constraint. The full syntax of the attribute is "`on_constraint` n" where n is the number of the constraint. Examples:

       list edge where on_constraint 3
       print vertex[3].on_constraint 1

## on_boundary

Vertex, edge, or facet read-only attribute. The status of whether an element is on a boundary can be queried with the Boolean attribute on_boundary. Elements can be unset from boundaries, but not set on them (since parameter values would be unknown). Examples:

      list vertex where on_boundary 1
      unset vertex boundary 2

## on_quantity

Vertex, edge, or facet read-only attribute. Boolean attribute for whether an element contributes to a given named quantity. Actually, it tests whether the element is on any of the method instances comprising a quantity. The full syntax of the attribute is "`on_quantity` quantityname". Examples:

       list facet where on_quantity  center_of_mass_x
       print vertex[3].on_quantity blue_area

## on_method_instance

Vertex, edge, or facet read-only attribute. Boolean attribute for whether an element contributes to a given named method instance. The full syntax of the attribute is "`on_method_instance` instancename". Examples:

       list facet where on_method_instance  center_of_mass_x_edges
       print vertex[3].on_method_instance blue_area_1

## original

Geometric element read-only attribute. For elements read from the datafile, this is the number given to the element in the datafile, which may be overridden by an explicit original attribute value in the datafile line defining the element. The value is inherited by all elements of the same type that result from subdivision. For elements otherwise generated at run time, the original attribute value is -1. Example: to show which facets descended from face 1 in the datafile:

       set facet color red where original == 1

## Named quantities as attributes

Geometric element read-only attribute. Named quantities and method instances can be applied to geomtric elements either in the datafile (by adding the quantity or method name to the line defining an element) or with the set command. Nonglobal quantities or methods can be unset for individual elements. The values for individual elements can be accessed using attribute syntax. Examples: Suppose there is a named quantity "xmoment" that can be evaluated for facets. Then one could give commands

       foreach facet do printf "%g %f\n",id,xmoment
       list facet where xmoment > 4
       set facet quantity xmoment where original == 1
       unset facet quantity xmoment

## Extra attributes

Geometric element read-write attributes. If extra attributes have been defined in the datafile or with a define command, they can be accessed with attribute syntax. Extra attribute values in the datafile can be initialized for an element by adding the attribute name and value to the line defining the element. Example:

      define vertex attribute oldx real
      vertices
      1   2 0 0 oldx 3

The command language can use the name with the same syntax as built-in attributes, and can define extra attributes at run time:

      set vertex oldx x
      define edge attribute vibel real[2]
      set edge[2] vibel[1] 3; set edge[2] vibel[2] 4
      print vertex[3].oldx

The value of an extra attribute can also be calculated by user-supplied code. The attribute definition is followed by the keyword "function" and then the code in brackets. In the code, the keyword "self" is used to refer to the element the attribute is being calculated for. Example: To implement the lowest z value of a facet as an attribute:

     define facet attribute minz real function
    	 {self.minz := min(self.vertex,z);}

These attributes can also be indexed. Due to current parser limitations on parsing executable code, this type of extra attribute definition cannot occur in the top section of the datafile, although the non-function version can to declare the attribute name, and the function part added in a re-definition in the READ section of the datafile.

# Vertex-specific attributes

## Vertex coordinates

Vertex read-write attribute. The coordinates of a vertex are its location in space. By default, these are Euclidean coordinates, but they may represent any coordinate system if the user defines appropriate length, area, volume, etc. integrals. But graphics always treat the coordinates as Euclidean. The individual coordinates may be referred to as x,y,z,w or x1,x2,x3,... In the vertices section of the datafile, vertices of the original surface have their coordinates given unless they are on a parametric boundary. Vertices on parametric boundaries have their coordinates calculated from their parameter values. Coordinates may be read or modified with the command language. Examples:

      foreach vertex do printf "%g  %f %f %f\n",id,x,y,z
      set vertex z z+.1*x

## Vertex parameters

Vertex read-write attribute. Vertices on parametric boundaries are located according to the parameter values. Parameters are referred to as p1,p2,... Usually only p1 is used, since one-parameter curves used as boundary wires are most common. Such vertices in the original surface have their parameter values given in the vertices section of the datafile instead of their coordinates. Vertex parameters may be read or modified with the command language. Example:

      foreach vertex do printf "%g %f\n",id,p1
      set vertex[1] p1 1.2

## Fixed vertices

Vertex read-write attribute. A fixed vertex will not move during iteration (except to satisfy level set constraints) or other operations, except if coordinates are explicitly changed by a "set vertices ..." command. A vertex may be declared fixed in the datafile by putting `fixed` on the line defining the vertex, after the coordinates. From the command prompt, one can fix or unfix vertices with the fix and unfix commands. Examples:

      list vertex where fixed
      fix vertex where on_constraint 1
      unfix vertices where on_boundary 1

## Vertex constraints

Vertex read-write attribute. A level-set constraint is a restriction of vertices to lie on the zero level-set of a function. A constraint declared NONNEGATIVE in the datafile forces a vertex to have a nonnegative value of the function. A NONPOSITIVE constraint forces a vertex to have a nonpositive value of the function. A constraint may be declared GLOBAL, in which case it applies to all vertices. A vertex may be put on a constraint in the vertices section of the datafile by listing the constraint numbers after the keyword "`constraint`". See mound.fe for an example. In commands, the status of a vertex can be read with the on_constraint and hit_constraint attributes. The status can be changed with the set or unset commands. Examples:

      list vertex where on_constraint 2
      set vertex constraint 1 where id == 4 or id == 6
      unset vertex constraint 3

## Hit_constraint

Vertex read-only attribute. Boolean attribute for whether a vertex exactly satisfies a given constraint. Particularly meant for vertices on one-sided constraints. The full syntax of the attribute is "`hit_constraint` n" where n is the number or name of the constraint. Examples:

       list vertex where hit_constraint 3
       print vertex[3].hit_constraint 1

## __v_constraint_list

This read-only attribute gives access to the list of constraints a vertex is on. __v_constraint_list[1] is the number of constraints in the list, followed by the numbers of the constraints. Note that for named constraints, the internally assigned numbers are used.

## Bare vertex

Vertex read-write attribute. Declaring a vertex "bare" says that a vertex does not have an adjacent edge (string model) or an adjacent facet (soapfilm model). Useful in avoiding warning messages. A vertex may be declared bare in the vertices section of the datafile by adding the keyword `bare` to the line defining the vertex. Example:

       list vertex where bare

## Mid_edge

Vertex read-only attribute. True (1) if the vertex is on an edge but not an endpoint. Relevant in the quadratic model or Lagrange model. Example:

       list edge[23].vertex vv where vv.mid_edge

## Mid_facet

Vertex read-only attribute. True (1) if the vertex is an interior control point of a facet in the Lagrange model. Example:

       list facet[23].vertex vv where vv.mid_facet

## Vertex edges

Vertex read-only attribute. Generates edges attached to a vertex, oriented so vertex is the edge tail. The edges are in no particular order. Examples:

      list vertex[3].edges
      foreach vertex vv do { foreach vv.edge do print id }

Always use "`.edges`" to generate vertex edges; using "edges" with an implicit element, as in "`foreach vertex do list edges`" will list all edges in the surface over and over again.

## Vertex facets

Vertex read-only attribute. Generates facets attached to a vertex, with positive facet orientation. The facets are in no particular order. Examples:

      list vertex[3].facets
      foreach vertex vv do { foreach vv.facet do print id }

Always use "`.facets`" to generate vertex facets; using "facets" with an implicit element, as in "`foreach vertex do list facets`" will list all facets in the surface over and over again.

## Vertex valence

Vertex read-only attribute. The valence of a vertex is defined to be the number of edges it is a member of. Example:

      list vertices where valence == 6
      histogram(vertex,valence)

## axial_point

Vertex read-write attribute. Certain symmetry groups (e.g. cubocta or rotate) have axes of rotation that are invariant under some non-identity group element. A vertex on such an axis must be labeled in the datafile with the attribute `axial_point`, since these vertices pose special problems for the wrap algorithms. If you are only using a subgroup of the full group, then you only need to label vertices on the axes of the subgroup. The net wrap around a facet containing an axial point need not be the identity. Edges out of an axial point must have the axial point at their tail, and must have zero wrap. Facets including an axial point must have the axial point at the tail of the first edge in the facet. It is your responsibility to use constraints to guarantee the vertex remains on the axis.

## Triple_point

Vertex read-write attribute. For telling Evolver three films meet at this vertex. Used when effective_area is on to adjust motion of vertex by making the effective area around the vertex 1/sqrt(3) of actual.

## Tetra_point

Vertex read-write attribute. For telling Evolver six films meet at this vertex. Used when effective_area is on to adjust motion of vertex by making the effective area around the vertex 1/sqrt(6) of actual.

## vertexnormal

Vertex read-only attribute. This is an indexed attribute consisting of the components of a normal to the surface at a vertex, normalized to unit length. This is the same normal as used in hessian_normal mode. For most vertices in the soapfilm model, the normal is the number average of the unit normals of the surrounding facets. Along triple edges and such where hessian_normal has a multi-dimensional normal plane, the vertexnormal is the first basis vector of the normal plane. Example: To print the normal components of vertex 3:

     print vertex[3].vertexnormal[1];
     print vertex[3].vertexnormal[2];
     print vertex[3].vertexnormal[3];

The vertexnormal can also be printed as an array:

     print vertex[3].vertexnormal

## dihedral

vertex read-only attribute in the string model. This is the angle from straightness of two edges at a vertex. If there are less than two edges, the value is 0. If two or more edges, the value is 2*asin(F/2), where F is the magnitude of the net force on the vertex, assuming each edge has tension 1. Upper limit clamped to pi.

## Squared mean curvature

Geometric element read-only attribute. SQCURVE is the squared mean curvature at a vertex. Valid only if squared mean curvature is part of the energy or in a quantity (but not the star versions of the squared mean curvature methods).

## __force

Vertex read-only attribute. This is an indexed attribute giving the components of the force (negative energy gradient as projected to constraints). Meant for debugging use. This is not directly used for the motion; see __velocity.

## __velocity

Vertex read-only attribute. This is an indexed attribute giving the components of the vector used for vertex motion in the 'g' command. The motion of a vertex is the scale factor times this vector. The velocity vector is calculated from the force vector by applying area normalization, mobilty, etc. Also, if a vertex is on a boundary, the velocity is projected back to parameters.

# Edge-specific attributes

## Length

Edge read-only attribute. Length of the edge. Examples:

     histogram(edge where on_constraint 1, length)
     print edge[3].length

## Edge density or tension

Edge read-write attribute. "Density" and "tension" are synonyms. Energy per unit length of edge. Default 1 in string model, 0 in soapfilm model. The tension may be modified in the datafile edges section by adding "`tension` value" to the line defining the edge. The tension may be modified with the set command. Examples:

      set edge tension .5 where id < 10
      loghistogram(edge,density)

## Fixed edge

Edge read-write attribute. For an edge to be "fixed" means that any vertex or edge created by refining the edge will inherit the "fixed" attribute. Declaring an edge fixed in the datafile will also fix all vertices on the edge. However, fixing an edge from the command prompt will not fix any vertices. An edge may be declared fixed in the datafile edges section by adding `fixed` to the line defining the edge. From the command prompt, one can fix or unfix edges with the fix and unfix commands. Examples:

      fix edge where on_constraint 1
      list edges where fixed
      set edge color red where fixed
      unfix edge[3]

## Edge constraints

Edge read-write attribute. An edge may be put on a level set constraint. For such an edge, any vertices and edges generated by refining the edge will inherit the constraint. An edge may be put on constraints in the edges section of the datafile by listing the constraint numbers after the keyword `constraint` on the line defining the edge. Putting an edge on a constraint does not put its existing vertices on the constraint. In commands, the status of an edge can be read with the "on_constraint" attribute. The status can be changed with the set or unset commands. Examples:

      list edge where on_constraint 2
      set edge constraint 1 where id == 4 or id == 6
      unset edge constraint 3

## __e_constraint_list

This read-only attribute gives access to the list of constraints an edge is on. __e_constraint_list[1] is the number of constraints in the list, followed by the numbers of the constraints. Note that for named constraints, the internally assigned numbers are used.

## Edge boundary

Edge read-write attribute. If an edge is on a parametric boundary, then any edges and vertices generated from the edge will inherit the boundary. By default, new vertex parameter values are calculated by extrapolating from one end of the edge. This avoids wrap-around problems that would arise from interpolating parameter values. But if the interp_bdry_param toggle is on, then interpolation is used. The status of whether an edge is on a boundary can be queried with the Boolean attribute on_boundary. Edges can be unset from boundaries, and set on them (but care is needed to do this properly). Examples:

      list edges where on_boundary 1
      unset edges boundary 2

## Edge wrap

Edge read-write attribute. When a symmetry group is in effect (such as the torus model) and an edge crosses the boundary of a fundamental domain, the edge is labelled with the group element that moves the edge head vertex to its proper position relative to the tail vertex. The label is internally encoded as an integer, the encoding peculiar to each symmetry group. Edge wrappings are set in the datafile. The torus model has its own peculiar wrap representation in the datafile: `*` for no wrap, `+` for positive wrap, and `-` for negative wrap. Wraps are maintained automatically by Evolver during surface manipulations. The numeric edge wrap values can be queried with attribute syntax. Example:

      list edge where wrap != 0

Unfortunately, the torus model wraps come out rather opaquely, since one cannot print hex. The torus wrap number is the sum of numbers for the individual directions: +x = 1; -x = 31; +y = 64; -y = 1984; +z = 4096; -z = 127040. Caution: even though this attribute can be written by the user at runtime, only gurus should try it.

## Edge color

Edge read-write attribute. Color for graphics. The default color is black. Color may be set in the datafile, or with the set command. In geomview, the edge color will show up only for edges satisfying the show edge condition, and then they will have to compete with the edges geomview draws, unless you turn off geomview's drawing of edges with "ae" in the geomview window. Examples:

      set edge color red where length > 1
      show edge where color != black

## Noncontent

Edge read-write attribute. When set, indicates this facet should not be used in volume calculations in the soapfilm model or facet area calculations in the string model. Useful, for example, if you want to have edges be part of a body boundary for display purposes, but want to use constraint integrands for greater accuracy in volume calculations. Example:

       set edge noncontent where on_constraint 1

## Bare edge

Edge read-write attribute. Declaring an edge "bare" indicates that an edge does not have an adjacent facet (soapfilm model). Best declared in the datafile, by adding the keyword `bare` to the line defining an edge. Useful in avoiding warning messages. Bare edges are useful to show wires, frameworks, outlines, etc. in graphics. Example:

      list edge where bare

## No_refine

Edge and facet read-write Boolean attribute. An edge with the "no_refine" attribute will not be refined by the r command. This is useful for avoiding needless refining of lines or planes that are used only for display. Giving a facet the no_refine attribute has no effect except that edges created within the facet by refining will inherit the no_refine attribute. So to avoid refinement of a plane, all edges and facets in the plane must be given the no_refine attribute. The no_refine attribute may be specified on the datafile line for an edge or facet, or the set command may be used. Examples:

      set edge no_refine where fixed
      unset edge[2] no_refine
      list edge where no_refine
      print edge[3].no_refine

## Edge orientation

Edge read-write attribute. Controls the sign of oriented integrals on an edge. Value +1 or -1. Useful when triangulation manipulations create an edge going the wrong way. Example:

      set edge[2] orientation -1

## Edge vertices

Edge read-only attribute. Acts as a generator for the two endpoints in the linear and quadratic models, and for all vertices on an edge in the Lagrange and simplex models. Example:

       list edge[2].vertices
       list edge ee where ee.vertex[1].on_constraint 1

## Edge midv

Edge read-only attribute. In the quadratic model, gives the id of the midpoint vertex of an edge. Example:

      print edge[23].midv

## Edge facets

Edge read-only attribute. Generates facets attached to an edge, in order around the edge when meaningful, with facet orientation agreeing with edge orientation. Examples:

       list edge[2].facets
       foreach edge ee do print max(ee.facets,area)

## Edge valence

Edge read-only attribute. The valence of an edge is the number of facets adjacent to it. Examples:

      list edges where valence == 1
      refine edge where valence != 2

## Dihedral

Edge read-only attribute. The angle in radians between the normals of two facets on an edge. Zero if there are not exactly two facets. This attribute is not stored, but recalculated each time it is used. If there are not exactly two facets on the edge, the value is 0.

## Edge tangent

Edge read-only attribute. The components of the edge vector in the linear model can be accessed as edge attributes x,y,z or x1,x2,x3,.... In a command, the vector between edge endpoints is used in quadratic model or lagrange model. But when used in an integral, the tangent is evaluated at the Gaussian integration points. Not defined in the simplex model. Example to list nearly vertical edges:

       list edges where z^2 > 10*(x^2 + y^2)

# Facet-specific attributes

## Facet area

Facet read-only attribute. The area of the facet. Example:

      list facet where area < .1

## Fixed facet

Facet read-write attribute. For a facet to be "fixed" means that any vertex, edge, or facet created by refining a facet will inherit the fixed attribute. Fixing a facet in the datafile or at the command prompt does not fix any edges or vertices. A face may be declared fixed in the datafile by putting `fixed` on the line defining the face, after the coordinates. From the command prompt, one can fix or unfix facets with the fix and unfix commands.

## Facet tension or density

Facet read-write attribute. Energy per unit area of facet; surface tension. Default 0 in string model, 1 in soapfilm model. May be set in the datafile by adding "`tension` value" to the line defining the facet. The density is inherited by any facets generated by refining. "Tension" and "density" are synonyms. Examples:

      set facet tension 3 where original == 1
      list facet where density < .4

## Facet constraints

Facet read-write attribute. Putting a facet on a constraint means that every vertex, edge, or facet generated by refining the facet will inherit that constraint. Setting a facet on a constraint does not set any of its existing edges or vertices on the constraint. Facets may be put on constraints in the datafile by listing the constraint numbers after the keyword `constraint` on the line defining the facet, or with the set command. They may be removed with the unset command. Examples:

      list facets where on_constraint 1
      set facet[2] constraint 2
      unset facet constraint 1

## __f_constraint_list

This read-only attribute gives access to the list of constraints a facet is on. __f_constraint_list[1] is the number of constraints in the list, followed by the numbers of the constraints. Note that for named constraints, the internally assigned numbers are used.

## Facet boundary

Facet read-write attribute. If a facet is on a parametric boundary, then any facets, edges, and vertices generated from the facet will inherit the boundary. By default, new vertex parameter values are calculated by extrapolating from one vertex of the facet. This avoids wrap-around problems that would arise from interpolating parameter values. But if the interp_bdry_param toggle is on, then interpolation is used. The status of whether a facet is on a boundary can be queried with the Boolean attribute on_boundary. Facets can be unset from boundaries, and set on them (but care is needed to do this properly). Examples:

      list facets where on_boundary 1
      unset facets boundary 2

## Facet color

Facet read-write attribute. Color of both sides of facet for graphics. Default is white. Datafile example:

      Faces
      1   1 2 3 color red

Command examples:

      list facets where color == red
      set facet[3] color green
      set facet color red where area > 2

## Frontcolor

Facet read-write attribute. Color of positive side of facet for graphics. Default is white. Datafile example:

      Faces
      1   1 2 3 frontcolor green backcolor red

Command examples:

      list facets where frontcolor == red
      set facet[3] frontcolor green
      set facet frontcolor red where area > 2

## Backcolor

Facet read-write attribute. Color of negative side of facet for graphics. Default is white. Set also when the "color" attribute is set. Datafile example:

      Faces
      1   1 2 3 frontcolor green backcolor red

Command examples:

      list facets where backcolor == red
      set facet[3] backcolor green
      set facet backcolor red where area > 2

## Facet vertices

Facet read-only attribute. Generates vertices around a facet, oriented as the facet boundary. "vertex" and "vertices" are synonymous. In the string model, if the facet is not a closed loop of edges, the vertices will be generated in order from one end. If the given facet has negative orientation, then the vertices will be generated accordingly. Example:

      list facet[3].vertex

## Facet edges

Facet read-only attribute. Generates edges around a facet, oriented as the facet boundary. "edge" and "edges" are synonymous. In the string model, if the edges of the facet do not make a closed loop, then the edges will be listed in order starting from one end. If the given facet has negative orientation, the edges will be listed accordingly. Example:

      list facet[3].edges
      list facet[-3].edges

## Facet bodies

Facet read-only attribute. Generates bodies around a facet, first the body the facet is positive boundary of, then the body the facet is negative boundary of, if they exist. "body" and "bodies" are synonymous. Example:

    list facet[3].bodies

## Frontbody

Facet read-write attribute. The id of the body of which the facet is on the positively oriented boundary. Useful after creating a new body with the new_body command. As a read attribute, the value is 0 if there is no such body. Examples:

      newb := new_body; set facet frontbody newb where color == red
      print facet[2].frontbody

Frontbody also works for adding edges to a facet in the string model, but the added edge must be attach to one end of the edge arc, or close the arc.

## Backbody

Facet read-write attribute. The id of the body of which the facet is on the negatively oriented boundary. Useful after creating a new body with the new_body command. As a read attribute, the value is 0 if there is no such body. Examples:

      newb := new_body; set facet[1] frontbody newb;
      set facet backbody newb where id == 2 or id == 4;
      print facet[4].backbody

Backbody also works for adding edges to a facet in the string model, but the added edge must be attach to one end of the edge arc, or close the arc.

## Facet valence

Facet read-only attribute. The valence of a facet is the number of edges (or vertices) that it contains. Most useful in the string model. Example:

      list facets where valence != 3

## Nodisplay

Facet read-write attribute. When set, suppresses the display of the facet in graphics. Can be set in the datafile by adding `nodisplay` to the line defining the facet. Can also be manipulated by the set and unset commands. `No_display` is a synonym provided since that's what I kept typing in. Example:

       set facet nodisplay where color != red

## Orientation

Facet read-write attribute. Controls the sign of oriented integrals on a facet. Value +1 or -1. Useful when triangulation manipulations create a facet with an undesired orientation. Example:

       set facet[123] orientation -1

## Noncontent

Facet read-write attribute. When set, indicates this facet should not be used in volume calculations. Useful, for example, if you want to have facets be part of a body boundary for display purposes, but want to use constraint integrands for greater accuracy in volume calculations. Example:

       set facet noncontent where on_constraint 1

## Phase

Facet read-write attribute. If there is a phasefile, this attribute determines the edge tension of an edge between two facets in the string model. Example:

       list facet where phase == 1

## Facet normal vector

Facet read-only attribute. The components of the facet normal vector may be referred to as x,y,z or x1,x2,x3,... in the linear model. Length is equal to facet area. In quadratic model or lagrange model, only the three facet corner vertices are used to calculate the normal. When used in integrals, the normal is calculated at each integration points. Not defined in simplex model.

# Body-specific attributes

## Body facets

Body read-only attribute. Generates facets bounding a body, with proper facet orientation with respect to the body. Example:

      list body[1].facets

## Body density

Body read-write attribute. Density used for gravitational potential energy. It can be set in the bodies section of the datafile, or with the set command, or by assignment. Command examples:

      print body[2].density
      set body density 3
      body[2].density := 5

## Body volume

Body read-only attribute. Actual volume of a body. This is the sum of three parts, in the soapfilm model:

- An integral over the facets bounding the body. This is \int z dx dy normally, but \int (x dy dz + y dz dx + z dx dy)/3 if SYMMETRIC_CONTENT is in effect.
- Any constraint content edge integrals applying to the body.
- The body's volconst attribute.

In the string model, the parts are

- An integral over the edges bounding the body's facet. This is \int -y dx.
- Any constraint content vertex integrals applying to the body.
- The body's volconst attribute.

Body volumes can be displayed with the v command, or with standard attribute syntax. Example:

      print body[1].volume
      foreach body where volume > 2 do print id

## Body target

Body read-write attribute. The target volume of a volume constraint. May be set in the datafile, by the b command, or the set command. A volume constraint may be removed by the unset, or with the b command. Command examples:

       set body[1] target 23
      unset body target where id == 2
      print body[2].target

## Volfixed

Body read-only attribute. Value is 1 if the volume of the body is fixed, 0 if not.

## Body volconst

Body read-write attribute. A constant added to the calculated volume. Useful for correcting for omitted parts of body boundaries. Also used internally as a correction in the torus model , which will use the target volume to calculate volconst internally. In the torus model, the target volume should be set within 1/12 of a torus volume of the actual volume for each body, so the correct volconst can be computed. Each volconst will be adjusted proportionately when the volume of a fundamental torus domain is change by changing the period formulas. Volconst can be set in the datafile bodies section, or interactively by the set command or by assignment. Examples:

      print body[1].volconst
      set body[2] volconst 1.2
      body[2].volconst := 1.2

It is best to avoid using volconst except in the torus model. Rather, use edge content integrals so that the proper adjustments will be made if the boundary of the surface is moved, or rebody is done.

## Actual_volume

Body datafile attribute. Actual_volume is a number that can be specified in the datafile definition of a body 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.

## Body pressure

Body read-write attribute. If a body has a prescribed volume, this is a read-only attribute, which is the Lagrange multiplier for the volume constraint. If a body is given a prescribed pressure, then there is an energy term equal to pressure times volume. A body cannot have a prescribed volume and a prescribed pressure at the same time. Prescribed volume or pressure can be set in the bodies section of the datafile. If pressure is prescribed, then the value can be changed interactively with the b command, the set command, or by assignment. Examples:

      print body[2].pressure
      body[2].pressure := 1.3
      set body[2] pressure 1.3

## Body phase

Body read-write attribute. For determining facet tension in soapfilm model, if a phase file is used.

Back to top of Surface Evolver documentation. Index.