# Compute property

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.

## Output property

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.

## Vector properties

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.

## Conditional assignments

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.

## Including neighbor particles

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 Rc. 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.

## Parameters

Output property

  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.

Compute only for selected particles

  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.

## 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 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.

## 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.

## 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 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.