Global Script¶

Introduction¶

A Global Script is a self-contained C-style routine that executes at runtime and can freely read from and write to all global script variables. It has access to global constants and the full library of built-in functions, and may define intermediate variables that are used only inside the script. Global scripts are implemented as System UDFs, meaning they are compiled and evaluated by the same expression engine as other UDF-based components in M-Star. This makes them the most flexible runtime element for implementing logic that cannot be expressed easily through standard controllers or filters.

Global scripts are often used to encode multi-step operating procedures, rule-based controls, or complex mathematical updates. They behave like small, embedded programs that execute in the solver at each step (or at a specified interval), allowing the user to orchestrate variable evolution, perform conditional actions, or compute derived quantities.

Because they can directly manipulate any global variable, global scripts are well suited for tasks such as sequencing charge/ramp/hold steps, implementing safety interlocks, running phased feed strategies, or coordinating changes in operating conditions in response to sensor-like signals.

Property Grid¶

Script

A Global Script is a flexible, C-style routine that runs at runtime and can access all global variables, constants, and functions to implement custom logic beyond standard controllers or filters. Launch the Global Script Editor to define the script.

This is a system UDF that can be used to edit the values of global variables. At a minimum, the script must define a function named timestep. For convenience, this function is pre-defined in the script editor when a new custom script is added to the model. The timestep function is a void function with the current simulation time t and the simulation time step dt as input variables. It is evaluated once per simulation step and can be used to update global variables. Note that, as a void function, the timestep function does not return a value. Assignments are made directly to the global variables within the function body. Within this function, you can access any of the global variables, as well as functions from the built-in math library and user-defined Lookup Tables.

Global variables may always be referenced within a Global Script; however, only variables whose Data Source is set to Global Script Variable should be modified within the Global Script. Variables linked to existing model properties (e.g., via Property Link or CSV Files) are one-way bindings—the value is imported from the model tree but cannot be written back. Likewise, reduction-based global variables (Fluid, Particle, Static Body, Interface, Stats Value, etc.) represent derived solver outputs and therefore should be treated as read-only. Overwriting any of these values will break their relationship to the underlying model and lead to inconsistent behavior. In short, use all global variables as inputs, but only update those explicitly defined with Data Source set to Global Script Variable.

In the example below, a global script is used to reduce instantaneous drug substance concentration data predicted at four probe locations to a single coefficient of variation. The probe locations are shown in red. We present the time evolution of the species concentration at each probe, as well as the time evolution of the reduced COV value. This approach is commonly used in multi-probe experimental systems to concentrate measurements into one representative number for the whole system. The script reads the probe concentrations from their global variables, computes the mean and standard deviation, and writes the coefficient of variation to another global variable for logging or downstream use.

Download Sample File: Global Script

Note

Locally defined subroutines are scoped to the current global script and can only be accessed by the time step function defined within it.

Global Script Editor¶

The Global Scripts Editor is launched by pressing the purple edit button () in the property grid.

Components¶

The components of the Global Script Editor are presented below.

Title Bar: This title indicates the window is the Global Script Editor.
Toolbar: These action buttons are used to close the editor and perform a syntax/output check on the UDF. OK saves the code script and closes the form. Cancel closes the form without saving the code script. Check Code performs a syntax check on the UDF script and computes the output based on the test values provided. The result of this syntax check, as well as the output values, are viewed in the Reporting Log.
Script Editor: This field is where the UDF script is entered. System variable expressions are written in the C-programing language. All predefined input variables, user-defined lookup tables, and built-in math functions available for use in the script are listed in the Global Variables and Built-in Functions panel.
Reporting Log: This panel reports the results of the syntax check (Check Code). These errors must be corrected for the UDF to execute.
Status Bar: This panel identifies the cursor location within the global script editor.
Search Bar: This field is to search for a built-in function. Press enter to execute the search.
Global Variables and Built-in Functions: These are the global variables and built-in functions that can be evoked when writing the script.

Function Format¶

In addition to the required timestep function, the global script can also invoke locally defined subroutines. These subroutines can be called from multiple locations within the script. Within the Global Script Editor, a notional script is defined as:

// the solver executes this function every time step
void timestep(double t, double dt)
{


    /* Step 1: compute the mean */
    double mean = computeFourMean(bottomProbeConc,baffleProbeConc,topProbeConc,topSideProbeConc);

    /* Step 2: compute sample standard deviation */
    double var = ((bottomProbeConc - mean) * (bottomProbeConc - mean) +
          (baffleProbeConc - mean) * (baffleProbeConc - mean) +
          (topProbeConc - mean) * (topProbeConc - mean) +
           (topSideProbeConc - mean) * (topSideProbeConc - mean)  ) / (4.0 - 1.0);

    double stdev = sqrt(var);

    /* Step 3: compute coefficient of variation */
    probeCOV=0;
    if(mean>0){
        double cv = stdev / mean;      /* ratio form */
        probeCOV = cv * 100;  /* as percentage */
    }
}

float computeFourMean(float value_1, float value_2, float value_3, float value_4){
    float sum=value_1+value_2+value_3;
    float mean=sum/4.0;
    return mean;

}

Variable Types¶

The fundamental variable types are float, int, and bool. It is necessary to understand the difference between these variable types to avoid improper rounding or truncation.

A float variable represents continuous physical quantities like velocity and pressure, providing the necessary decimal precision for accurate property representations. This type defines a single precision floating point variable. The values range from \(±10^{−38}\) to \(±10^{38}\), with approximately 7 decimal digits of precision.

An int variable manages discrete aspects, such as mesh indices, iteration counts, and zone IDs. Values range from -2,147,483,648 to 2,147,483,647.

A bool (Boolean) variable implements a conditional logic (true/false), enabling checks and control flow within the UDF—ending the simulation when a specific condition is achieved, for example. Additionally, Boolean operations (e.g., <, >, ==, !=) are used within if statements to compare values and determine the execution path, making these comparisons essential for conditional logic.

UDFs can also contain double precision floating-point variables, which store 14 decimal digits of precision. These double-precision variables should only be used when the code is operating in double precision mode.

Tip

Be careful with how integers and floating-point values interact. Integer division (int/int) always truncates, so if you want a real quotient, you must promote at least one operand to a floating type.
Floating-point numbers cannot represent many decimal values exactly, so avoid testing equality directly. Instead, compare within a small tolerance.

Built-in Functions¶

The built-in functions available for use within the Function Library are the same as those available for System UDFs, are based on the C++ Math library.

Global Script Toolbar¶

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

For a full description of each selection on the Context-Specific Toolbar, see Toolbar Selections.