Histogram

Histogram statistics record the time-evolution of the distribution when a Histogram feature is enabled. The range and bin resolution are defined by the Histogram feature in the model tree. This output produces a tab-separated ASCII .txt file named Histogram_{DynamicName}.txt, where the dynamic name matches the feature name in the Model Tree.

The output file contains columns corresponding to the bin center values defined by the histogram configuration. Each bin represents a range of the underlying variable, and the values stored in each column correspond to the accumulated quantity within that bin interval. Unlike the Histogram Cumulative, these values represent a non-cumulative distribution, meaning each bin contains only the quantity that falls within its specific range. The sum of all bin values equals the grand total reported in the summary statistics. Each row in the output file corresponds to a new statistics output time and is appended at the Statistics Output Write Interval.

This data can be interpreted as a Probability Distribution Function (PDF). The magnitude of each bin indicates how much of the sampled domain lies within that range of the variable. Peaks in the histogram identify the most common values, while wider spreads indicate greater variability in the system. To visualize the data, the bin center values (first row) should be plotted on the x-axis, and the corresponding bin values (later rows) should be plotted on the y-axis. In this representation, the x-axis gives the variable value, and the y-axis gives the amount of the domain falling within each interval.

Statistics Table

The index table below shows the statistics that will appear in the Histogram output file. Within this table, each statistic corresponds to a column in the output table which evolves with the time column. The units described are user-defined histogram units.

Tip

Users sometimes interpret histogram bin values as cumulative quantities. However, each bin represents only the amount within that interval, not the total below it. To determine cumulative behavior (e.g., “What fraction of the system is below a threshold?”), the cumulative histogram (CDF) output should be used instead.

Statistics	Units	Details	When Appears
Time	s	simulation time
Binned Total	Dimensionless	total weight of items that fall within the histogram range
Grand Total	Dimensionless	total weight of all items, including both items that fall within the histogram range and those that do not
Lower Unbinned Total	Dimensionless	total weight of items that are below the histogram range start value
Maximum	[dynamic]	maximum value, including values outside histogram range
Mean	[dynamic]	mean value, including values outside histogram range, this is calculated directly from the data and not based on the histogram
Minimum	[dynamic]	minimum value, including values outside histogram range
Number of NaNs	Dimensionless	total number of items that have non-finite values
Upper Unbinned Total	Dimensionless	total weight of items that are above the histogram range end value
Values	Dimensionless	histogram values

Usage and Interpretation

Histogram statistics provide a time-resolved view of the distribution of a variable across the domain or within the associated child geometry. Each output row represents a snapshot in time, where the columns correspond to predefined bin ranges and contain the amount of the domain falling within each interval. This data can be interpreted as a probability distribution function (PDF), where peaks identify the most common values and the spread indicates the degree of variability or heterogeneity in the system. The Mean, Minimum, and Maximum values provide global context (including values outside the histogram range), while the Binned Total, Lower/Upper Unbinned Totals, and Grand Total quantify how much of the domain is captured within or outside the specified range.

In practice, histogram outputs are used to assess mixing quality, detect segregation, and evaluate the distribution of key variables such as concentration, shear rate, or temperature. By plotting bin center values on the x-axis and bin values on the y-axis, users can visualize how the system transitions from narrow, localized distributions (e.g., poor mixing or initial conditions) to broader or more uniform distributions over time. It is important to note that each bin represents only the quantity within its interval (non-cumulative). Cumulative behavior, such as determining the fraction of the system below a threshold, should instead be evaluated using the Histogram Cumulative (CDF) Output.