This modifier evaluates a user-defined mathematical expression for every particle and assigns the results to a particle property. It can be used to assign new properties to particles or to modify existing properties.
The math formula specified by the user can depend on existing particle properties or global parameters such as the simulation box size or animation time. The list of available input variables that can be referenced in the formula is displayed in the lower panel.
OVITO differentiates between standard particle properties and custom particle properties.
The properties of the former type have specific meanings to OVITO (e.g. Position
or Particle Identifier
) while custom properties
have arbitrary, user-defined names (e.g. MyPropertyA
) and the stored data is not interpreted by OVITO in any way.
The Compute property modifier allows you to create or modify both types of particle properties. If you use the
modifier to assign values to certain standard properties such as Position
, Color
, or Radius
,
it will immediately affect the visual appearance of particles (see this example).
The list of all standard properties known to OVITO can be found in the Output property drop-down list. If you want to create a custom particle property, simply enter a name of your choice into the text field. Note that property names in OVITO are case-sensitive.
Some particle properties (e.g. Position
or Color
) are vector quantities, which consist of multiple components per particle. If you want to use the Compute property
modifier to assign values to such a vector property, then you'll have to enter multiple math expressions, one for each vector component.
Note that the modifier does not allow you to create custom properties with multiple vector components.
If the particle property that you are computing already exists, then the existing values will be overwritten with the new ones computed by the modifier. The Compute only for selected particles option, however, makes it possible to restrict the assignment to a subset of particles and preserve the existing property values for unselected particles. If the computed property did not exist before, then unselected particles will be assigned the default value 0 if this option is active.
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
compute the values of the Transparency
particle property:
(ReducedPosition.Z > 0.5) ? 0.7 : 0.0
For more demanding computation or analysis tasks, which cannot be accomplished with static expressions, please consider using the Python script modifier, which lets you write a modification function in a procedural programming language.
By default the property value computed for a particle can only depend on other properties of the same particle (or global quantities). The Include neighbor terms options allows to also include nearby particles within a certain cutoff radius of the central particle when computing its property value. If this option is active, the final property value P(i) of a central particle i is computed as
The first term, F(i), is the first user-defined function, which gets evaluated once for the central particle. The second term consists of contributions from all neighbors within the cutoff radius R_{c}. The contributions are given by a second function, G(j), which is evaluated for every neighbor particle j. The user-defined function G(j) is entered into the input field Neighbor expression, and it may only depend on properties of the current neighbor, its distance from the central particle, and on global parameters.
This allows you to perform advanced computions that take into account the local neighborhood of particles. For example, we can average a particle property 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, which is queried in this example to normalize the resulting property value.
We could even weight the contributions from different neighbors based on their distance from the central particle by incorporating the Distance
dynamic variable in the function G(j). For example, these expressions compute the potential energy according to a Lennard-Jones potential:
F(i) := 0 G(j) := 4 * (Distance^-12 - Distance^-6)
Here, no contribution is coming from the central particle.
Specifies the output property that receives the values computed by the modifier. You can either create a new property by entering a user-defined name in the field, or pick one of the standard properties from the drop-down list.
Restricts the evaluation of the math expression and the assignment of results to the subset of selected particles. This option is useful if you want to selectively overwrite the property values of certain particles.
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 created from float literals, variables, or functions using the following operators in the given order of precedence:
Operator | Description |
---|---|
(...) | expressions in parentheses are evaluated first |
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 | comparison between A and B (result is either 0 or 1) |
A && B | logical AND operator: result is 1 if A and B differ from 0, else 0 |
A || B | logical OR operator: result is 1 if A or B differ from 0, else 0 |
A ? B : C | If 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 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. 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. |
Our aim is to compute the linear velocity of each
particle based on the components v_{x},
v_{y}, and v_{z} 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.
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 can 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. With the
formula
Selection ? 1.5 : 1.0
we assign a radius that depends on the selection state of each particle, which can be either 1 or 0. That is, the above radius expression will evaluate to 1.5 for selected particles, and to 1.0 for unselected particles.