Compute property

This modifier evaluates a user-defined mathematical formula for every particle and assigns the computed results to an output particle property. It can be used to give particles new properties or to modify the values of existing properties.

The user-defined formula that determines the output value can include references to input properties and global parameters such as the simulation box size or animation time. All available input variables, which may be used within the formula, are listed in the bottom panel of the modifier. Furthermore, the Compute property modifier can be used to perform mathematical computations that involve terms from neighboring particles, e.g. for performing spatial averaging of per-particle property values.

The output property

As described in the introduction on particle properties, certain properties have a particular meaning to the program as their values control the visual appearance of particles. Thus, if you set or modify the values of such properties with the Compute property modifier, it will affect the particle visualization accordingly. For instance, you can use the modifier to replace the values of the Position particle property and move particles around or set the Color property to give particles a computed color.

Alternatively, you can use the modifier to assign user-defined properties to particles. For that, simply enter the desired name for the new property into the Output property field. Note that property names in OVITO are always case-sensitive. All standard property names defined by the program can be found in the drop-down list box.

Vector properties

Some particle properties such as Position or Color possess multiple components per particle. In such cases you'll have to enter a separate math expression for each vector component of the property. Note that, in the current program version, the modifier does not allow you to create user-defined properties having multiple components per particle.

Selective and conditional property assignment

If the selected output particle property already exists, then the existing values of the property will be overwritten with the new ones computed by the modifier. The Compute only for selected particles option, however, let you restrict the assignment to a subset of of particles and preserve the existing property values for unselected particles. In case the computed property did not exist before and this option is activated, the unselected particles will be assigned the default property value 0.

Furthermore, the ternary operator ?: (see table below) allows you to make use of simple if-else conditions. For example, to make all particles in the upper half of the simulation box semi-transparent and the particles in the lower half fully opaque, use the following conditional expression to set the values of the Transparency particle property:

(ReducedPosition.Z > 0.5) ? 0.7 : 0.0

For more complex computation or analysis tasks, which cannot be accomplished with static expressions like this, please consider using the Python script modifier instead, which lets you write custom modification functions in a procedural programming language.

Including neighbor particles

By default, the property value computed for a particle can only depend on other properties of the same particle (and global quantities). The Include neighbor terms options of the modifier allows you to also include nearby particles within a certain range around the central particle in the computation. If this option is enabled, the output property value P(i) of a central particle i is computed as

The first term, F(i), refers to the regular user-defined function, which gets evaluated once for the central particle. The second term consists of contributions from all neighbors within the cutoff radius Rc. The contributions are given by a second function, G(j), which is evaluated for every neighbor particle j. This user-defined function G(j) is entered into the input field labeled Neighbor expression, and it may only depend on properties of the current neighbor, its distance from the central particle, and on global parameters.

The neighbor term option allows you to perform advanced computations that involve the local neighborhood of each particle. For example, we can use this to average some existing particle property ("InputProperty") over a spherical volume around each particle by using the following expressions:

F(i) := InputProperty / (NumNeighbors+1)
G(j) := InputProperty / (NumNeighbors+1)

Note that NumNeighbors is a dynamic variable provided by the modifier, which is used in this example to normalize the resulting property value. We could have even weighted the contributions from different neighbors according to their distance from the central particle by incorporating the Distance dynamic variable in the function G(j). To give another example, the following expressions let modifier compute the potential energy of each particle according to a Lennard-Jones function:

F(i) := 0
G(j) := 4 * (Distance^-12 - Distance^-6)

In this case, no contribution is coming from the central particle itself.

Expression syntax

The expression syntax supported by the modifier is very similar to the one of the C programming language. Variable names and function names are case-sensitive. Arithmetic expressions can be composed from constant values, input variables and math functions using the following operators in the given order of precedence:

(...)expressions in parentheses are evaluated first
A^Bexponentiation (A raised to the power B)
A*B, A/Bmultiplication and division
A+B, A-Baddition and subtraction
A==B, A!=B, A<B, A<=B, A>B, A>=Bcomparison between A and B (result is either 0 or 1)
A && Blogical AND operator: result is 1 if A and B differ from 0, else 0
A || Blogical OR operator: result is 1 if A or B differ from 0, else 0
A ? B : CIf A differs from 0 (i.e. is true), the resulting value of this expression is B, else C.

The expression parser supports the following functions:

Function nameDescription
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. This function is documented 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 parameter values.
min(A,B,...)Returns the minimum of all parameter 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 value.
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.

Additional example 1

Our aim is to compute the linear velocity of each particle based on the components vx, vy, and vz of their velocity vectors. For this, we create a new user-defined property with the name "Speed". The following formula is entered into the expression field:

sqrt(Velocity.X^2 + Velocity.Y^2 + Velocity.Z^2)

Here we reference the X, Y, and Z components of the standard Velocity particle property, which must be present in the input dataset. The computed linear velocity property can subsequently be used, for instance, to color particles with the Color Coding modifier.

Additional example 2

The Compute property modifier can also be used to set particle properties which are not accessible by other means. One such example is the per-particle radius: Let us assume we have already selected a subset of particles that we want to give a different size. We may use the Compute property modifier to set the value of the Radius particle property, which determines the per-particle display radii. The selection state of particles is given by the Selection property. The conditional formula

Selection ? 1.5 : 1.0

assigns a radius value depending on each particle's selection state, which can be either 1 or 0. That is, the above expression will evaluate to 1.5 for selected particles, and to 1.0 for unselected particles.

See also

ComputePropertyModifier (Python API)