Add Particle Variable¶

Particle variables are quantities assigned to individual particles rather than to lattice sites. Unlike voxel variables, which are fixed to the computational grid, particle variables are carried with each particle as it moves through the domain. Their values are updated and transported along with the particle trajectory.

Download Sample File: Particle Variable

In this example, we track the time-evolution of the accumulated stress experienced by individual particles as they move through the agitated vessel. Each particle’s trajectory integrates the local stress it encounters, producing a cumulative measure that mimics the mechanical damage cells would undergo under similar conditions. We then examine the distribution of accumulated stress values across the particle population. At early times, the distribution is narrow, since few particles have had sufficient exposure to high-stress regions. As time progresses, particles that repeatedly pass through the high-shear zones near the impeller accumulate larger stresses, causing the distribution to broaden and shift toward higher values. This analysis not only highlights how different particles experience heterogeneous stress histories, but also provides a framework to quantify potential cell damage risks in mixing systems by linking local hydrodynamic stresses to particle-based cumulative exposure.

Particle variables are computed using user-defined functions (UDFs), which evaluate properties on a per-particle basis. These UDFs can access both instantaneous particle properties—such as position, velocity, diameter, temperature, or species composition—and local fluid properties surrounding the particle, including shear rate, species concentrations, or turbulent dissipation rates. By combining particle-resolved data with surrounding fluid conditions, particle variables can represent highly customized behaviors tied to the motion and environment of each particle.

Particle variables can be defined as scalar or vector-valued quantities. Scalar particle variables represent a single floating-point value per particle, while vector particle variables define three independent components that move with the particle.

Because particle variables are attached to particles rather than the lattice, they are ideal for tracking particle-resolved histories, such as accumulated shear exposure, number of collisions, internal reaction extents, temperature evolution, or localized residence times. These variables can also be referenced by other UDFs, integrated into particle-based reactions, or exported for downstream analysis and validation.

Access¶

When you select Add Particle Variable on any particle context-specific toolbar, a new child geometry is formed and the property grid below will launch.

Property Grid¶

`General`¶

Template

Particle variables are defined using one of the three template styles:

UDF

A user-defined function is used to calculate the particle variable directly. The UDF may depend on instantaneous particle properties, local fluid conditions, or other custom variables.

Data Type

The Data Type setting determines whether the particle variable represents a scalar or a vector quantity. For variables defined using the UDF, this choice must be explicitly specified.

Scalar: Computes a single-valued output for each particle. The calculation UDF must return one floating-point value to represent this property, which is then stored and transported with the particle as it moves through the domain.
Vector: Computes a three-component directional output for each particle. In this case, the calculation UDF must explicitly define all three components of the vector within the function. These components move with the particle and evolve over time.

Particle Variable UDF

user-defined units | This UDF defines the custom variable to be computed for each particle. If the Data Type is set to scalar, one output must be defined within the UDF: a floating-point variable named {pv}_p, where {pv} is the dynamic name of the particle variable. If the Data Type is set to vector, the thee components of the vector must be defined individually as {pv}_x, {pv}_y and {pv}_z. The units on the output variable depend on the UDF expression. This is a local UDF, calculated on a particle-by-particle basis using the local particle/fluid properties.

Download Sample File: Particle Variable

This calculation defines how a particle variable is computed and updated during the simulation. A UDF user-supplied code snippet written in C-style syntax that allows you to define custom calculations based on instantaneous particle properties, surrounding fluid properties, or other custom variables.

For particle variables defined using the UDF template, the UDF is evaluated independently for each particle in the system. The calculation operates on the particle’s instantaneous state—such as position, velocity, temperature, species composition, or diameter—and may also query the local fluid conditions around the particle, including velocity gradients, concentrations, or turbulence measures. This per-particle evaluation allows you to define properties that move and evolve with the particle rather than being tied to any fixed location in the lattice.

Depending on the Data Type, the UDF may produce:

Scalar outputs, where the UDF returns a single floating-point value per particle.

Vector outputs, where the UDF must explicitly define three components (x, y, and z) per particle, representing a full directional quantity that travels with the particle.

Particle Reaction Variable

No UDF is defined for this variable. Instead, its value is assigned as part of an on-particle reaction. This can be useful for characterizing intermediate variables within complex intraparticle reactions.

Data Type

The Data Type setting determines whether the particle variable represents a scalar or a vector quantity. For variables defined using the UDF, this choice must be explicitly specified.

Scalar: Computes a single-valued output for each particle. The calculation UDF must return one floating-point value to represent this property, which is then stored and transported with the particle as it moves through the domain.
Vector: Computes a three-component directional output for each particle. In this case, the calculation UDF must explicitly define all three components of the vector within the function. These components move with the particle and evolve over time.

If your particle variable is based on DEM particles, the following selection will launch:

Particle-Particle Collision

For particle variables, the Collision template defines quantities that are updated whenever a particle undergoes a collision with one or more neighboring particles. Unlike voxel- or particle-based UDFs that operate continuously, collision-driven variables are evaluated only at the moment of particle–particle contact.

A UDF provides the kernel that specifies how each individual collision contributes to the particle variable. This UDF can incorporate local particle properties (e.g., velocity, diameter, orientation) and surrounding fluid conditions to describe the outcome of a collision. The UDF produces values for each interaction, which are then combined using the reduction logic described below.

In this framework, the UDF provides the kernel for a single collision event, while the reduction type, calculation type, and interval govern how those per-event results are aggregated into the final particle variable. Together, these settings allow users to represent both instantaneous collision responses and long-term cumulative effects, depending on the physics of interest.

When using the Collision template, several options must be defined:

Reduction Type

Determines how results from multiple simultaneous interactions collapse into a single scalar value for the particle. For particle variables defined using the Collision template, the Data Type is fixed and defaults to Scalar. Because collision-driven variables are evaluated per-event and combined using a reduction type, vector-valued outputs are not supported in this mode. Three reduction modes are available:

Min: Stores the minimum value across all interactions in the time step.
Max: Stores the maximum value across all interactions.
Sum: Computes the sum of contributions from all interactions.

For interactions involving only a single collision partner, all three reductions produce the same result. For interactions involving two or more particles, the reduction choice distinguishes how multiple events are aggregated.

Calculation Type

Determines whether collision results are accumulated over time or reset at each time step. Two options are available:

Accumulated: The variable retains contributions from all previous collisions, building a history over the course of the simulation. This mode is useful for predicting cumulative physics such as wear, material transfer, or energy deposition.
Instantaneous: The variable is reset at each time step, and only collisions in the current step are reported. This mode is suited for properties where each collision is physically independent of prior events.

Calculation Interval

Specifies how often collision-driven updates are evaluated. Shorter intervals capture more detail but may increase computational cost, while longer intervals reduce overhead but may smooth out high-frequency events. The Compute Frequency (see Advanced section below) option takes precedence over this variable.

Collision Statistic: Defines the particular metric computed during a collision event, as determined by the UDF. Examples include relative velocity, energy dissipation, contact force, or material exchange.

Particle Collision UDF: user-defined units | This UDF defines the custom value to be computed for each particle-particle interaction. One output must be defined within the UDF: a floating-point variable named value. This UDF is evaluated for each pair-wise particle-particle interaction. These sets of results are then reduced (see Reduction Type above) to compute a single particle variable. The units on the output variable depend on the UDF expression. This is a  local UDF, calculated on a particle-by-particle basis using the local particle/fluid properties.

Download Sample File: Collision Statistic

Initial Value

The Initial Value defines the starting value assigned to the particle variable before any runtime calculations begin. For most custom particle variables, this is typically left at zero, but it can be set to a different baseline when appropriate—for example, to initialize particle temperature, concentration, or another property with a known starting condition.

If the Data Type is set to Scalar, a single initial value is specified. If the Data Type is set to Vector, the GUI requests three initial components corresponding to the x-, y-, and z-directions. These values establish the initial state of each component prior to being updated by the UDF or other runtime processes.

For particle variables defined using the Collision template, the data type is fixed to Scalar, and the Initial Value represents the starting baseline used before any collision-driven updates are applied.

`Advanced`¶

The Advanced settings provide additional controls over how custom variables are displayed, reported, and integrated into the simulation framework.

Display Name Override

This setting controls how the variable name appears in the GUI and exported results. These overrides do not affect the internal computation but allow you to customize presentation for clarity during downstream analysis.

Display Unit Override

This setting controls how the variable units appears in the GUI and exported results. These overrides do not affect the internal computation but allow you to customize presentation for clarity during downstream analysis.

Compute Frequency

This setting controls whether the variable is available exclusively for reporting and post-processing or whether it can also be referenced elsewhere in the simulation as an intermediate variable.

Output Only: The variable is computed only at output intervals when data is written to files or visualizations. Because the solver skips calculating the variable at every time step, this mode can make the simulation more efficient, especially when working with computationally expensive UDFs or large particle sets. However, the variable cannot be referenced by other UDFs, expressions, or solver-driven calculations since it is not continuously available.
Every Time Step: The variable becomes fully integrated into the solver and can be used as an input to other calculations. For example, a voxel variable could feed directly into custom viscosity models, reaction kinetics expressions, transport closures, or additional derived variables defined elsewhere in the code.