Add Static Body Variable¶

Introduction¶

Static body variables are values defined along solid surfaces and used to characterize how fluids and particles interact with those boundaries. They are especially useful for describing particle–wall interactions, strain rates, energy dissipation, and other near-wall physics that feed directly into surface reactions or engineering metrics. For example, particle collisions with walls can be used to predict wear and erosion rates, strain rate distributions can help evaluate cleaning effectiveness, and projected fluxes are often applied when modeling surface heat or mass transfer processes.

All static body variables are stored on the voxels adjacent to the solid surface. The triangular mesh representing the surface is used only as a projection target for visualization and export. This means the variables themselves are computed at the lattice level, but projected back onto the geometry for interpretation and analysis.

When considering particle collision–based static body variables, results may be reported either as instantaneous statistics (reset at each time step) or as accumulated quantities (summed over time). Instantaneous collisions are useful for cases where each impact is treated as independent, while accumulation is valuable for modeling cumulative physics such as wear, erosion, or material loss.

The quality of the triangular mesh does not affect the accuracy of the underlying calculation (since values are tied to voxels), but it does influence the precision and level of detail with which results are represented. Large triangles spread voxel data across broader surface areas, potentially smoothing out local variations. To obtain a faithful projection, the triangle size on the surface mesh should be comparable to the lattice spacing, ensuring that near-wall details are neither exaggerated nor lost.

When defining static body variables in UDFs, users have access to surface normal information and may sample fluid properties at a user-defined offset from the wall (for example, 1 mm into the fluid) before projecting them back to the surface. Projection itself can be configured as a conservative mapping which preserves integral balances, or as a smoothed interpolation which provides clearer gradients for visualization.

Access¶

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

Property Grid¶

`General`¶

Template

Static body variables are defined using one of three template types which determine how the variable is calculated and updated during the simulation.

Surface UDF

A UDF is provided to calculate the surface variable directly. The UDF may draw on local fluid conditions or other custom variables. Because surface variables are stored on voxels adjacent to the wall and then projected onto the surface mesh, you must also specify a projection algorithm. The projection defines how the voxel-level values are mapped to the triangular mesh for visualization and export, either through a conservative mapping that preserves integrals or an interpolation that provides smoother gradients.

Data Type

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

Scalar: This computes a single-valued output for each triangle. The calculation UDF must return one floating-point value to represent this property.
Vector: This 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.

Surface Transfer

The Surface Transfer setting determines how values defined in the adjacent fluid voxels are mapped back onto the triangular surface mesh. Choosing the appropriate transfer method depends on whether preserving integral balances or improving visualization detail is more important for the application. Two projection algorithms are available.

Conservative Mapping: This ensures that integrated quantities (e.g., fluxes or forces) are preserved exactly when projected.
Interpolative Mapping: This smooths values across the mesh to provide clearer gradients for visualization, at the cost of strict conservation.

Interpolation Distance

meters | The Interpolation Distance specifies how far into the fluid domain the solver samples local field values before projecting them back to the surface. For example, setting this to 1 mm instructs the solver to retrieve properties such as velocity, strain, or species concentration 1 mm away from the wall and then project those results onto the adjacent triangles. This is useful when modeling processes (e.g., heat or mass transfer) that require a representative offset into the bulk fluid.

Static Body Variable UDF

depends | This UDF defines the custom variable to be computed along the static body surface. If the Data Type is set to scalar, one output must be defined within the UDF: a floating-point variable named {sv}, where {sv} is the dynamic name of the surface variable. If the Data Type is set to vector, the thee components of the vector must be defined individually as {sv}_x, {sv}_y and {sv}_z. This is a local UDF, calculated on a voxel-by-voxel basis using the local fluid properties. The UDF is only applied along the cells touching the solid surface.

Download Sample File: Static Body Variable

Particle Surface Collision

A UDF is executed each time a particle collides with the solid surface. In this mode, the UDF serves as the kernel that defines the collision statistic for a single event, and you must also specify a calculation type, a reduction type, and the collision UDF.

The calculation type determines whether results are reported as instantaneous (reset at each time step) or accumulated over time. The reduction type determines how multiple simultaneous collision events are aggregated (e.g., minimum, maximum, or sum). The collision UDF defines the per-interaction value, which is then passed through the reduction logic and assigned to the variable.

This mode is commonly used to model surface processes such as erosion, wear, deposition, or energy transfer from particle impacts. Mechanically speaking, the Particle Collision UDF defines what is calculated during each particle-wall impact, the Reduction determines how results from multiple collisions are combined, and the Calculation defines how those results evolve over time—whether instantaneously, cumulatively, or normalized per surface area.

Calculation

The Calculation setting describes how collision events are tracked over time. Three modes are available.

Instantaneous: This reports collisions occurring during the current time step only, without retaining history. This is useful when collisions are independent and have no lasting effect.
Accumulated: This tracks the cumulative number or magnitude of collisions over the course of the simulation. This is valuable for studying long-term processes such as wear or material loss.
Accumulated per Area: This normalizes the accumulated collisions by the surface area of the wall, providing a measure of collision density per unit area. This is often used when comparing collision intensities across surfaces of different sizes.

Reduction

The Reduction setting determines how multiple simultaneous collisions at a given surface location are collapsed into a single value for the variable.

Min: This stores the minimum collision statistic.
Max: This stores the maximum collision statistic.
Sum: This aggregates the contributions from all collisions in that time step. When a particle collides with only one surface element, all three reductions produce the same result. For multiple collisions, the reduction defines how they are combined into one representative value.

Particle Collision Set

This field specifies which particle set is considered when evaluating collisions. By selecting from previously defined particle families, users can restrict collision statistics to only those particle types that are physically relevant.

Particle Collision UDF

depends | This UDF defines the kernel of the calculation executed for each interaction between a particle and the moving body. One output must be defined within the UDF: a floating-point variable named value. This is a local UDF, calculated on a individual collision basis using the local fluid and particle properties.

Download Sample File: Static Body Particle Collision

Surface Reaction Variable

No UDF is defined for this variable. Instead, its value is computed and updated automatically as part of surface reactions. This option is especially useful when a surface variable functions as an intermediate quantity within a reaction mechanism; for example, tracking adsorbed species or reaction extents on catalytic surfaces.

Surface Transfer

Conservative Mapping: This ensures that integrated quantities (e.g., fluxes or forces) are preserved exactly when projected.
Interpolative Mapping: This smooths values across the mesh to provide clearer gradients for visualization, at the cost of strict conservation.

Interpolation Distance

Initial Value

depends | The Initial Value defines the starting value assigned to the surface variable before runtime calculations begin. By default, this is set to zero, but it may be specified as a nonzero baseline to seed more complex workflows. For scalar variables, a single initial value is provided. For vector-valued surface variables, three components (x, y, z) must be specified. These values establish the initial condition of the variable before UDF calculations, collision statistics, or surface reactions update it during the simulation.

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

Location¶

The Add Static Body Variable tool is found on the following context-specific toolbars:

wall Static Body

Static Body Variable Toolbar¶

Context-Specific Toolbar Forms	Description
Help	The Help command launches the M-Star reference documentation in your web browser.

For a full description of each option, see Context-Specific Toolbar selections.