Custom Flow Statistics in AnyLogic Refinery Simulation

       First year of using the Exporter the Agent of the Petroleum Refining Library in real refinery simulation projects with one of our customers showed that custom flow statistics in AnyLogic refinery simulation are often required for detailed production analysis. The statistics covered the main components involved in refinery flow movement, including Source, Process Unit, and Tank Farm. By collecting flow data from these components, the statistics provided a comprehensive view of how material moved through the refinery—from feedstock supply and processing to storage and subsequent transfer—giving users a complete picture of flow movement across the refinery.

For example, a report may show:
       Diesel fuel — 100,000 t
This total may include several output streams:
       Diesel fuel to the tank farm — 85,000 t
       Non-conforming diesel fuel — 10,000 t
       Diesel fuel to reprocessing — 5,000 t

       To address this requirement, the Exporter was extended with custom rows that can add detailed product statistics at different positions in the report. During the second year of practical use, one of our clients identified a new requirement: the same detailed flow breakdown was needed directly within the AnyLogic refinery model, rather than only in custom Excel reports.

The Problem of Tracking Product Flows

       In a refinery model, the destination of a product is often determined downstream from the component that generates the flow. For example, a process unit may produce a diesel fuel stream that is subsequently divided by a separator into several destinations. This type of output flow analysis is required to determine how the product is distributed across the refinery. The total output of the process unit therefore does not provide the required flow breakdown.The statistics must obtain the actual flow from the component or logic that performs the routing. In Java, hard-coding this logic for every additional statistic would duplicate flow calculations and make the model harder to maintain. The solution is to decouple what flow should be measured from how that flow is obtained.

FlowProvider and FlowSupplier

       To make custom flow statistics reusable, the Petroleum Refining Library introduces two Java functional interfaces, FlowProvider and FlowSupplier. FlowProvider is used when the required flow is available directly from an AnyLogic Fluid Library component in the refinery simulation model. FlowSupplier provides greater flexibility by allowing the flow value to be calculated using a custom function. For example, a custom statistic can obtain a flow from a specific output or calculate the total flow directed to a particular destination. This separates flow data acquisition from refinery reporting. The Exporter does not need to know how a flow is calculated—it only requests the value from the configured provider or supplier.

One Source of Flow Statistics

       The main advantage of this approach is that custom flow statistics are no longer limited to the Excel reporting layer. They become reusable data sources that can be accessed by different parts of the refinery simulation model. A custom statistic can be defined once and then used by both the Exporter and the model's standard statistics. The same flow source provides the value in both cases, eliminating separate calculations for the model and the report. This creates a single source of truth for custom flow statistics and keeps the statistics displayed in the model consistent with the values generated during Excel export. For example, if diesel fuel is divided into several output streams, the model can define these flows once:
        - diesel fuel sent to the tank farm;
        - non-conforming diesel fuel;
        - diesel fuel sent for reprocessing.
       The same definitions can then be used to display the breakdown in the model and include it in the Excel report. This creates a single source of truth for custom flow statistics and keeps the model statistics and exported reports consistent.

Defining a Custom Flow Source

       A custom flow source can be defined either by referencing an existing AnyLogic Fluid Library component or by providing a custom calculation. When the required flow is available directly from a model component, it can be supplied through
       For example, a flow can be provided directly:
FlowProvider flowProvider = getFlow(fluidBlock);
       When the value must be calculated using custom model logic, FlowSupplier can be implemented with a lambda expression or method reference:
FlowSupplier flowSupplier = () -> calculateDieselFlow();
       The statistic only requests the current value from the configured flow source. It does not need to know how that value is obtained.

Benefits for Model Development

       Using FlowProvider and FlowSupplier also simplifies model development. Flow acquisition remains in the component that owns the flow, while the Exporter is responsible only for collecting and reporting the value. This reduces duplicated code, keeps the model structure clean, and makes custom statistics easier to maintain and reuse.

       This provides several practical benefits:
       Less duplicated code — flow calculations are defined once.
       Cleaner model structure — statistics are separated from flow-routing logic.
       Easier maintenance — changing a flow source does not require rewriting the reporting logic.
       Reusable statistics — the same flow definition can be used in different reports and model components.
       Consistent results — the model and Excel reports use the same flow data.
       As a result, the Exporter becomes not only a reporting component, but also a reusable interface for accessing detailed flow statistics throughout the refinery simulation model.

Using Custom Flow Statistics in Refinery Reports

       For example, if the refinery report contains a Diesel fuel output of 100,000 t, the additional statistics can break this value down into the actual routing destinations: 85,000 t transferred to the tank farm, 10,000 t classified as non-conforming, and 5,000 t sent to reprocessing. These rows are not calculated by the exporter itself. Instead, each row receives an AdditionalRowValueSupplier that accesses the corresponding flow-routing logic of the Diesel Fuel Production Unit (DFPH) and returns the actual flow value.
       The following Java code fragment demonstrates how this mechanism works in practice. It shows how detailed product-level flow statistics are created and connected to the corresponding flow-routing logic of the Diesel Fuel Production Unit.
private void addDfphDieselDetailRows() {

    final int indentLevel = 4;
    final int productId = Products.DIESEL_FUEL.getProductId();

    mainAgent.resultsExporter.addAdditionalRow(
            new AdditionalRowExportTotalOutput(
                    "To tank farm",
                    indentLevel,
                    DFPH,
                    productId,
                    measType -> getValue(fEnter_TankFarm_Diesel, measType));

    mainAgent.resultsExporter.addAdditionalRow(
            new AdditionalRowExportTotalOutput(
                    "Non-conforming",
                    indentLevel,
                    DFPH,
                    productId,
                    measType -> getValue(fEnter_NonConf_Diesel, measType));

    mainAgent.resultsExporter.addAdditionalRow(
            new AdditionalRowExportTotalOutput(
                    "To reprocessing",
                    indentLevel,
                    DFPH,
                    productId,
                    measType -> getValue(fEnter_Reprocessing_Diesel, measType));
}

Practical Results

       The introduction of FlowProvider and FlowSupplier turned custom flow statistics into reusable data sources within the refinery simulation model. The same flow definition can now be used by both the AnyLogic model and the Exporter, ensuring that displayed and exported statistics remain consistent. At the same time, flow acquisition is separated from report generation, eliminating separate periodic calculations and duplicated logic.

Conclusion

       The evolution of the Petroleum Refining Library Exporter was driven by a practical requirement: standard product totals were not enough to describe complex refinery flow routing. Custom rows extended Excel reporting, while FlowProvider and FlowSupplier made the same simulation statistics available directly in the refinery model. As a result, detailed product routing can be defined once and consistently used for both model statistics and Excel reports.

This custom flow statistics capability will be available in Petroleum Refining Library version 2.2.5

FAQ

1. What is the purpose of custom flow statistics in the Petroleum Refining Library Exporter?
Custom flow statistics allow a standard product total to be broken down into individual flows or destinations. For example, total diesel fuel output can be separated into product sent to a tank farm, non-conforming product, and product sent for reprocessing.

2. Why are standard Exporter statistics sometimes insufficient?
Standard statistics typically provide aggregated input and output values. In a refinery model, however, one product stream can be divided between several downstream destinations, so additional flow-level details may be required.

3. What is FlowProvider used for?
FlowProvider provides access to a flow value from an existing AnyLogic component. It allows the Exporter or another statistics component to obtain the required flow without duplicating the flow calculation logic.

4. What is FlowSupplier used for?
FlowSupplier allows the flow value to be calculated using a custom Java function, lambda expression, or method reference. It is useful when the required statistic cannot be obtained directly from a single model component.

5. What is the difference between FlowProvider and FlowSupplier?
FlowProvider is suitable when the required flow already exists as a value provided by a model component. FlowSupplier is more flexible and can calculate or combine flow values using custom model logic.

6. Can the same custom flow statistic be used in the model and in an Excel report?
Yes. The same flow source can be used by both the model and the Exporter, keeping displayed and exported values consistent.

7. Does each report require a separate flow calculation?
No. The same flow definition can be reused across statistics and reports.

8. Can custom statistics be used for complex product routing?
Yes. This approach is particularly useful when a product flow passes through separators, mixers, tank farms, or other components that determine its final destination.

9. Do functional interfaces simplify model maintenance?
Yes. They separate flow acquisition from reporting and reduce duplicated calculation logic.

10. Can custom flow statistics be added to existing Exporter reports?
Yes. Custom flow statistics can be added as additional rows and placed in the appropriate sections of the Exporter report, including alongside standard product statistics.