8.0
general documentation
Face and cell mesh-defined properties and selection

Element groups

The mesh entities may be referenced by the user during the mesh creation. These references may then be used to mark out some mesh entities according to the need (specification of boundary conditions, pressure drop zones, ...). The references are generally of one of the two following types:

  • A color is an integer possibly associated with boundary faces and volume elements by the mesh generator. Depending on the tool, this concept may have different names, which code_saturne interprets as colors. Most tools allow only one color per face or element.
    • I-deas uses a color number with a default of 7 (green) for elements, be they volume elements or boundary elements. Color 11 (red) is used for for vertices, but vertex properties are ignored by code_saturne.
    • Simail used the equivalent notions of "reference" for element faces, and "subdomain" for volume elements. By default, element faces were assigned no reference (0), and volume elements domain 1.
    • Gmsh uses "physical property" numbers.
    • EnSight has no similar notion, but if several parts are present in an EnSight 6 file, or several parts are present and vertex ids are given in an Ensight Gold file, the part number is interpreted as a color number by the Preprocessor.
    • The MED 2.3 model allowed integer "attributes" in addition to groups.
  • Named groups of mesh entities may also be used with most current mesh generators or formats. In some cases, a given cell or face may belong to multiple groups (as some tools allow new groups to be defined by boolean operations on existing groups).
    • I-deas assigns a group number with each group, but by default, this number is just a counter. Only the group name is considered by code_saturne (so that elements belonging to two groups with identical names and different numbers are considered as belonging to the same group).
    • CGNS allows both for named boundary conditions and mesh sections. If present, boundary condition names are interpreted as group names, and groups may also be defined based on element section or zone names using additional Preprocessor options (-grp-cel or -grp-fac followed by section or zone).
    • In the MED format and Salome platform, mesh groups are the main user-level concept to reference elements.
    • In current Gmsh versions, physical entities are interpreted as groups by code_saturne

Element selection criteria

Using the GUI or high-levels mesh element selections in user-defined functions, selection criteria allow defining a selection of mesh entities (usually cells, boundary faces, or interior faces) in a simple and consistent manner.

Typically, a selection criteria is simply a string containing the required group names (or color numbers for older formats), possibly combined using boolean expressions. Simple geometric criteria are also available.

A few examples are given below:

ENTRY
1 or 7
all[]
3.1 >= z >= -2 or not (15 or entry)
range[04, 13, attribute]
sphere[0, 0, 0, 2] and (not no_group[])

Strings such as group names containing white-space or having names similar to reserved operators may be protected using "escape characters".

Note that for defining a string in Fortran, double quotes are easier to use, as they do not conflict with Fortran's single quotes delimiting a string. In C, the converse is true. Also, in C, to define a string such as \plane, the string \\plane must be used, as the first \ character is used by the compiler itself. Using the GUI, either notation is easy. More complex examples of strings with protected strings are given here:

"First entry" or Wall\ or\ sym entry or \plane or "noone's output"

The following operators and syntaxes are allowed (fully capitalized versions of keywords are also allowed, but mixed upper-case/lower-case versions are not):

Escape characters
protect next character only \
protect string ‘'string’<br/> "string"`
Basic operators
priority ( )
not not ! !=
and and & &&
or or | || , ;
xor xor ^
General functions
select all all[]
entities having no group or color no_group[]
select a range of groups or colors range[ first, last]
range[ first, last, group]
range[ first, last, attribute]

For the range operator, first and last values are inclusive. For attribute (color) numbers, natural integer value ordering is used, while for group names, alphabetical ordering is used. Note also that in the bizarre (not recommended) case in which a mesh would contain for example both a color number 15 and a group named "15", using range[15, 15, group] or range[15, 15, attribute] could be used to distinguish the two.

Geometric functions are also available. The coordinates considered are those of the cell or face centres. Normals are of course usable only for face selections, not cell selections.

Geometric functions
face normals normal[ x, y, z, epsilon]
normal[ x, y, z, epsilon = epsilon]
plane, ax + by + cz + d = 0 form plane[ a, b, c, d, epsilon]
plane[ a, b, c, d, epsilon = epsilon]
plane[ a, b, c, d, inside]
plane[ a, b, c, d, outside]
plane, normal + point in plane form plane[ *nx, ny, nz, x, y, z, epsilon*]
plane[ *nx, ny, nz, x, y, z,* epsilon = epsilon]
plane[ *nx, ny, nz, x, y, z,* inside]
plane[ *nx, ny, nz, x, y, z,* outside]
box, extents (axis-aligned) form box[ *xmin, ymin, zmin, xmax, ymax, zmax*]
box, origin + axes form box[ *x0, y0, z0, dx1, dy1, dy1, dx2, dy2, dz2, dx3, dy3, dz3*]
cylinder cylinder[ *x0, y0, z0, x1, y1, z1, radius*]
sphere sphere[ x, y, z, radius]
inequalities >, <, >=, <= associated with x, y, z or X, Y, Z keywords and coordinate value
*xmin* <= x *xmax* type syntax is allowed

All selection criteria used are maintained in a list, so that re-interpreting a criterion already encountered (such as at the previous time step) is avoided. Lists of entities corresponding to a criteria containing no geometric functions are also saved in a compact manner, so re-using a previously used selection should be very fast. For criteria containing geometric functions, the full list of corresponding entities is not maintained, so each entity must be compared to the criterion at each time step. Heavy use of many selection criteria containing geometric functions may thus lead to reduced performance.

Using selection criteria in user code

In order to use selection criteria in C and Fortran user subroutines, a collection of utility subroutines is provided.

for example:

Selection criteria in Fortran

This section explains how to define surface or volume sections, in the form of lists lstelt of nlelt elements (internal faces, boundary faces or cells). For each type of element, the user calls the appropriate Fortran subroutine:

Several examples of possible selections are given here:

  • call getfbr("Face_1, Face_2", nlelt, lstelt) selects boundary faces in groups Face_1 or Face_2,
  • call getfac("4", nlelt, lstelt) selects internal faces of color 4,
  • call getfac("not(4)", nlelt, lstelt) selects internal faces which have a different color than 4,
  • call getfac("range[in_04, in_08]", nlelt, lstelt) selects internal faces with group names between in_04 and in_08 (in lexicographical order),
  • call getcel("1 or 2", nlelt, lstelt) selects cells with colors 1 or 2,
  • call getfbr("wall and y > 0", nlelt, lstelt) selects boundary faces of group wall which have the coordinate Y > 0,
  • call getfac("normal[1, 0, 0, 0.0001]", nlelt, lstelt) selects internal faces which have a normal direction to the vector (1,0,0),
  • call getcel("all[]", nlelt, lstelt) selects all cells.

The user may then use a loop on the selected elements. For instance, in the subroutine cs_user_boundary_y_conditions used to impose boundary conditions, let us consider the boundary faces of color number 2 and which have the coordinate X <= 0.01 (so that ‘call getfbr('2 and x <= 0.01’, nlelt,lstelt)); we can do a loop (do ilelt = 1, nlelt) and obtainifac = lstelt(ilelt)`.

Selection criteria in C

In C, the equivalent functions are:

More examples are available in the User examples section.

Volume and boundary zones

Though selection criteria can and should be used directly in mesh preprocessing operations and in some postprocessing subset extractions, for regions with a specific meaning, it is preferable to build zones.

In most cases, zones can be mapped directly to mesh regions and groups, but can be defined in a more complex manner using selection criteria.

Once built, boundary and volume zones can be used to quickly access all matching elements, as they maintain lists of corresponding elements.

The GUI naturally builds and associates zones for boundary and volume conditions. The cs_user_zones user-defined functions (from cs_user_zones.c) can be used to build such zones.