Global Variables¶

Introduction¶

Global variables are single-valued quantities that act as a nexus for data exchange in M-Star CFD. Unlike voxel, particle, or surface variables that live at specific spatial locations, global variables reduce information into a single value that can be defined, updated, and reused anywhere in the solver. They are incredibly flexible—a global variable might represent a simple time-dependent expression, the average particle size in a control volume, a velocity signal from a probe, or even a value streamed in from an external CSV file.

What makes global variables powerful is that they can both pull data in from across the solver (fluids, particles, bodies, probes, interfaces, properties, external sources) and push data back out into other parts of the code. They can be used inside local UDFs, system UDFs, and controllers; they can appear in custom constitutive models (e.g., viscosity, reaction kinetics); and they can be exported to files or used to update parameters in real time. In this way, they serve as the bridge between local physics and system-level logic.

Global variables often work by performing reductions. For example, fluid or particle properties can be sampled inside a child geometry and collapsed into a mean, minimum, maximum, or sum, giving a single value that describes the region. Similarly, interface data, static or moving body quantities, and collision statistics can be reduced into domain- or surface-wide metrics. But global variables are not limited to solver-driven physics; they can also be defined from probes, which feed runtime data directly into the solver, or from external properties and files, enabling coupling with design parameters, optimization schemes, or experimental datasets.

In short, global variables form the central handshake point of M-Star CFD. They unify runtime data, internal model properties, reductions, probes, and external signals into single values that can be used everywhere—from low-level UDF calculations to high-level optimization loops.

Property Grid¶

`General`¶

Initial Value

The Initial Value defines the starting value assigned to the global variable before any runtime calculations or data updates occur. By default, this is set to zero, but it can be specified as a different baseline when appropriate; for example, to seed optimization routines, initialize control signals, or represent a known starting condition.

For global variables defined through reductions (fluid, particles, interfaces, bodies), the initial value serves as the placeholder until the first reduction is performed. For variables linked to probes, time, or stats values, the initial value is quickly replaced once the simulation begins but may still be important for establishing consistency during early time steps. For external sources such as PropertyLink or CsvFile, the initial value acts as a fallback in case the property or file value is unavailable at initialization.

Because global variables can be used anywhere in the solver (in UDFs, system controllers, or optimization schemes), specifying a meaningful initial value can help prevent undefined behavior or unexpected transients at the start of a simulation.

Data Source

The Data Source field determines where the global variable retrieves its value.

Local Reductions

Fluid

Reductions over fluid-field properties (velocity, pressure, strain rate, dissipation, etc.) inside a child geometry or across the domain. Custom UDFs may be used to define the quantity being reduced.

Particles

Reductions over particle properties within a geometry. Supports filtering by particle set, allowing statistics such as mean particle size, cumulative volume fraction, or particle counts.

Interfaces

Reductions performed along fluid interfaces (e.g., liquid–gas boundaries). Useful for quantities like interfacial area, fluxes, or UDF-defined custom interface metrics.

A child geometry can optionally be assigned to the global variable involving local reductions. If specified, the reduction will only operate over the voxels contained within the child geometry, allowing you to focus on a region of interest (e.g., maximum velocity inside a draft tube, mean dissipation rate in the impeller zone). If no child geometry is defined, the reduction is applied across all the full domain.

Probe Data

Probe: Connects directly to simulation probes. Unlike Time or StatsValue, probe data can be manipulated by a UDF at runtime before being stored as a global variable. This allows probe signals to be transformed into new control signals or intermediate variables.

Temporal and Statistical Data

Time: Direct access to the current simulation time. This value is fixed by the solver and cannot be modified.
Stats Value: Reads values written to the statistics file and makes them available at runtime. These quantities are provided as-is and cannot be altered with a UDF.

Body-Based Reductions

Static Body: Reductions performed on static body variables (e.g., total wall shear stress, collision statistics, or fluxes integrated across stationary surfaces).
Moving Body: Reductions performed on moving body variables (e.g., cumulative erosion on an impeller, relative velocity distributions across rotating surfaces).

Property and External Links

Property Link: Links to a property already defined in the model tree. For example, an impeller diameter or vessel volume can be referenced as a global variable, allowing that property to be reused in UDFs or system controllers.
CSV File: Reads values from an external CSV file. This enables runtime coupling with external datasets or software, such as using experimental profiles or optimization signals to inform the simulation trajectory.

None: No data source is defined. The global variable must then be explicitly defined via a UDF or initialized manually.

`Advanced`¶

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.

Global Variable Toolbar¶

Context-Specific Toolbar Forms	Description
Add Geometry	The Add Geometry form adds child geometry by importing from external CAD files, extracting from external CAD assemblies, or defining internally using built-in parametric geometry.
Move	The Move form enables three-dimensional rigid body transform of object through free drag or point-to-point snapping.
Rotate	The Rotate form enables three-dimensional rotation of geometry.
Scale	The Scale form enables volumetric scaling of a geometry about a set anchor point.
Mate	The Mate form allows surface-to-surface mating and alignment.
Add Fill Point	The Add Fill Point tool selects which space will initially be 3D-filled with a liquid.
Help	The Help command launches the M-Star reference documentation in your web browser.