Expression selection — OVITO User Manual 3.16.0 documentation

# Expression selection

This modifier allows you to select particles, bonds, or other data elements based on user-defined criteria, using a Boolean expression. The modifier evaluates the expression for each input element, selecting those for which the Boolean expression returns a non-zero result (true). All other elements, for which the expression evaluates to zero (false), are deselected.

The Boolean expression can include references to both local properties and global quantities, such as the simulation cell size or the current timestep number. This flexibility allows for dynamic selection of elements based on properties like position, type, energy, or combinations of these. The lower panel of the modifier’s user interface displays a list of input variables that can be included in the expression, as shown in the accompanying screenshot.

Expressions can include comparison operators (e.g., `==`, `!=`, `>=`), logical operators (AND and OR, represented as `&&` and `||`), arithmetic calculations and math functions:

    ParticleType == 1 && Position.Z > 2.5

## Expression syntax

The syntax for expressions is similar to the C programming language. You can build arithmetic expressions using float literals, variables, or functions, combined with operators.

Attention

The expression parser of OVITO is case-sensitive. This means that variable names must be spelled exactly as they appear in the list of available input variables. Spaces in property names are simply left out in the corresponding variable names. For example, the particle property Particle Type is accessible as the variable `ParticleType` in the expression. Other invalid characters in property names are replaced by underscores in the variable names.

Operators are evaluated in the following precedence:

Operator | Description
--- | ---
`(...)` | Parentheses for explicit precedence
`A^B` | Exponentiation (A raised to the power B)
`A*B`, `A/B` | Multiplication and division
`A+B`, `A-B` | Addition and subtraction
`A==B`, `A!=B`, `A<B`, `A<=B`, `A>B`, `A>=B` | Comparisons between A and B (yielding either 0 or 1)
`A && B` | Logical AND: True if both A and B are non-zero
`A || B` | Logical OR: True if A, B, or both are non-zero
`A ? B : C` | Conditional (ternary) operator: If A differs from 0, yields B, else C

OVITO’s expression parser supports the following functions:

Function name | Description
--- | ---
`abs(A)` | Absolute value of A. If A is negative, returns -A, otherwise returns A.
`acos(A)` | Arc-cosine of A. Returns the angle, measured in radians, whose cosine is A.
`acosh(A)` | Same as `acos()` but for hyperbolic cosine.
`asin(A)` | Arc-sine of A. Returns the angle, measured in radians, whose sine is A.
`asinh(A)` | Same as `asin()` but for hyperbolic sine.
`atan(A)` | Arc-tangent of A. Returns the angle, measured in radians, whose tangent is A.
`atan2(Y,X)` | Two argument variant of the arctangent function. Returns the angle, measured in radians. See here.
`atanh(A)` | Same as `atan()` but for hyperbolic tangent.
`avg(A,B,...)` | Returns the average of all arguments.
`cos(A)` | Cosine of A. Returns the cosine of the angle A, where A is measured in radians.
`cosh(A)` | Same as `cos()` but for hyperbolic cosine.
`exp(A)` | Exponential of A. Returns the value of e raised to the power A where e is the base of the natural logarithm, i.e. the non-repeating value approximately equal to 2.71828182846.
`fmod(A,B)` | Returns the floating-point remainder of A/B (rounded towards zero).
`rint(A)` | Rounds A to the closest integer. 0.5 is rounded to 1.
`ln(A)` | Natural (base e) logarithm of A.
`log10(A)` | Base 10 logarithm of A.
`log2(A)` | Base 2 logarithm of A.
`max(A,B,...)` | Returns the maximum of all values.
`min(A,B,...)` | Returns the minimum of all values.
`sign(A)` | Returns: 1 if A is positive; -1 if A is negative; 0 if A is zero.
`sin(A)` | Sine of A. Returns the sine of the angle A, where A is measured in radians.
`sinh(A)` | Same as `sin()` but for hyperbolic sine.
`sqrt(A)` | Square root of A.
`sum(A,B,...)` | Returns the sum of all parameter values.
`tan(A)` | Tangent of A. Returns the tangent of the angle A, where A is measured in radians.

The parser supports the following constants in expressions:

Constant name | Description
--- | ---
`pi` | Pi (3.14159…)
`inf` | Infinity (∞)

## Type names in expressions

Added in version 3.12.0.

Particle types and bond types are represented by unique numeric identifiers in OVITO, i.e., the `ParticleType` variable evaluates to an integer value uniquely identifying the type of the current particle. The same applies to other typed properties in OVITO such as the Structure Type property.

Each type may have a human-readable name associated with it, e.g., the numeric type 1 may be named “Cu”. You can use these type names in expressions, e.g., `ParticleType == "Cu"`, where the type name is enclosed in double quotes.

There may be cases where multiple numeric types are associated with the same name, e.g., both types 2 and 3 may be named “Ni”, because there are two different kinds of “nickel” atoms in the simulation. In such cases, only the `==` and `!=` comparison operators are allowed. The expression parser performs an implicit expansion for you:

    ParticleType == "Ni"    -->    ParticleType == 2 || ParticleType == 3

    ParticleType != "Ni"    -->    ParticleType != 2 && ParticleType != 3

References to nonexistent type names, i.e., names with no corresponding numeric value, are implicitly replaced with the special value `inf`:

    ParticleType == "undefined"    -->    ParticleType == inf

This expression evaluates to false for any numeric particle type.

Attention

The type names are case-sensitive. For example, the type name `"Cu"` is not the same as `"cu"`.

Note

If there are multiple typed properties, each defining a type with the same name but different numeric IDs, the expression parser will attempt to resolve the ambiguity based on the context. For example, in the expressions `ParticleType == "alpha"` and `StructureType == "alpha"`, the left-hand side of the expression helps determine the user’s intent. The parser can replace `"alpha"` with the right numeric type ID for that particle property. However, there are cases where such a resolution is impossible. Then the expression parser will raise an error.

The regular expression `=~` operator (see below) also works with typed properties and matches against the human-readable type name. For example, the following expression selects all particles whose type is named `Cu` or `Fe`:

    ParticleType =~ /^(Cu|Fe)$/

## String properties in expressions

Added in version 3.16.0.

Starting with OVITO 3.16.0, properties of string data type, e.g. the Atom Name property read from molecular structure files, can be used in expressions. String properties support equality (`==`) and inequality (`!=`) comparisons with a string literal or another string property:

    AtomName == "O1"

    AtomName != "C2"

    MyStringProperty == AnotherStringProperty

Comparisons are case-sensitive.

Attention

String properties can only be used in equality (`==`), inequality (`!=`), and regex match (`=~`) comparisons. They cannot be used in arithmetic expressions or with ordered comparison operators (`<`, `>`, `<=`, `>=`).

### Regular expression matching

In addition to equality comparisons, string properties and typed properties can be matched against a regular expression using the `=~` operator. The pattern is written between two `/` delimiters (Perl-style), and the expression evaluates to 1 (true) if the pattern matches anywhere within the string value, or 0 (false) otherwise:

    AtomName =~ /^O/

This selects all elements whose Atom Name starts with the letter `O`. To match the complete string from start to end, use `^` and `$` anchors:

    AtomName =~ /^O1$/

An optional `i` modifier after the closing `/` makes the match case-insensitive:

    AtomName =~ /^o/i

The following expression selects particles whose Atom Name matches either `N1` or `N2` (i.e., starts with `N` followed by a digit):

    AtomName =~ /^N[12]$/

## Selection of bonds

In bond selection mode, the modifier makes the properties of the current bond available as normal expression variables. In addition, properties of the two particles connected by the bond can be accessed by prepending `@1.` or `@2.` to the particle property name. For example, the following expression selects bonds that connect two particles of different type and whose length exceeds a threshold value of 2.8:

    @1.ParticleType != @2.ParticleType && BondLength > 2.8

Note that a bond’s direction is arbitrary. It either points from particle A to particle B, or vice versa. Accordingly, `@1.` and `@2.` alike can refer to either one of the two particles. More complex expressions may thus be necessary to account for the two possibilities:

    (@1.ParticleType == "H" && @2.ParticleType == "C") || (@2.ParticleType == "H" && @1.ParticleType == "C")

## Additional expression examples

Select all particles in the upper half of the simulation box:

    ReducedPosition.Z > 0.5

Select particles within a cylindrical region of radius 10, centered at the simulation origin and extending infinitely in the Z direction:

    sqrt(Position.X*Position.X + Position.Y*Position.Y) <= 10

Select all particles within a spherical region of radius 8.5 around the simulation cell center, i.e., at reduced coordinates (0.5, 0.5, 0.5):

    ((ReducedPosition.X - 0.5) * CellSize.X)^2 +
    ((ReducedPosition.Y - 0.5) * CellSize.Y)^2 +
    ((ReducedPosition.Z - 0.5) * CellSize.Z)^2   <= 8.5 ^ 2

Given some existing selection of particles (represented by a non-zero `Selection` property), filter the set to include only those with a positive charge:

    Selection && Charge > 0

## Additional selection tools in OVITO

Select type modifier:

  Use this modifier to select particles based on just their type. It is a more user-friendly alternative to the Expression selection modifier.

Compute property modifier:

  Allows you to directly set the `Selection` property of particles based on a user-defined expression. Thus, it may also be used to create a particle selection by setting the `Selection` property to 1 for selected particles and 0 for unselected particles. In contrast to the Expression selection modifier, the Compute property modifier has the option to include neighboring particles, up to some user-defined cutoff distance, in the selection process. For example, you can select particles based on whether they are surrounded by a certain number or certain kind of neighbors.

Match Molecule modifier:

  Available as an extension for OVITO Pro, it allows you to create selections in bonded (molecular) systems using query expressions. These selection expressions are based on a simplified version of the SMILES language and let you select atoms, bonds, or sections of a molecule based on their chemical environment.

Python script modifier:

  Use custom Python functions in OVITO Pro to implement complex selection logic. The Python interface provides useful spatial queries, e.g., cutoff-based neighbor searches, k-nearest neighbor searches, or point-in-region tests.

See also

`ovito.modifiers.ExpressionSelectionModifier` (Python API)