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

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 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. Data sources can be grouped into three categories: Reduction, Temporal, and External. Each category and data source are discussed below.

Reduction

A reduction is an operation that takes a collection of values and combines them into a single representative value, such as a sum, mean, minimum, or maximum. It effectively collapses many data points into one aggregate result. 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, or mean dissipation rate in the impeller zone). If no child geometry is defined, the reduction is applied across the full domain.

Fluid: Fluid data sources support 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 at each fluid voxel.
Particles: Particle data sources support reductions over particle properties (e.g., particle size, species concentration, etc.) inside a child geometry or across the domain. Custom UDFs may be used to define the quantity being reduced for each particle.
Interfaces: Interface data sources support reductions performed along VOF interfaces (e.g., velocity, area, shear stress) inside a child geometry or across the domain. Custom UDFs may be used to define the quantity being reduced along the interface.
Static Body: Static body data sources support reductions performed on static body variables (e.g., pressure, total wall shear stress, collision statistics) inside a child geometry or across the entire static body surface. Custom UDFs may be used to define the quantity being reduced along the static body surface.
Moving Body: Moving body data sources support reductions performed on moving body surfaces (e.g., shear stress, erosion, collision statistics) inside a child geometry or across the entire moving body surface. Custom UDFs may be used to define the quantity being reduced along the moving body surface.

Temporal

Temporal data sources provide access to values that evolve over the course of the simulation. These sources expose the current simulation time, time‐evolving statistics written by the solver, and live probe signals. Unlike reductions, temporal data does not aggregate spatial fields. Rather, these values reflect how the system changes with time.

Time: Time data sources provide the global variable with direct access to the current simulation time. This value is fixed by the solver and cannot be modified.
Stats Value: Stats value data sources provide the global variable with direct access to output data written to the statistics files. These quantities are provided as-is and cannot be altered with a UDF.
Probe: Probe data sources provide the global variable with direct access to simulation probe output. 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.

External

External data sources provide values that originate outside of the core simulation fields or temporal signals. These sources allow global variables to reference existing model properties, receive values written directly from user-defined scripts, or be defined within Global Scripts. This category enables integration with model parameters, custom logic, and external datasets.

Property Link: This 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.
Global Script Variable: No data source is assigned. The value of this global variable is expected to be defined or updated within a Global Script. If no script writes to it during runtime, the variable simply retains its initial value and behaves as a fixed constant.
CSV File: This reads values from an external CSV file. This enables runtime coupling with external datasets or software, such as using experimental profiles or external controller signals to inform the simulation trajectory.

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