Source Statistics in Refinery Simulation

Source Series:
       1. Source in Refinery Simulation: Complete Guide to Feedstock Planning, Flow Control, and Statistics
       2. Crude Oil Supply Chain Simulation: How Can Feedstock Deliveries to Refineries Be Simulated?
       3. Flow Smoothing in Digital Twin Simulation: Converting Source Plans into Continuous Flows
       4. Source Statistics in Refinery Simulation
       5. Source Control in Refinery Simulation: Runtime Flow Management

See also:
       Simulation of FeedStock Deliveries from Oil and Gas Fields

       Source Statistics in refinery simulation provide a structured way to monitor Source output, evaluate production plan execution, and analyze historical production flow data in petroleum refining and oil and gas simulation models. The Petroleum Refining Library provides these capabilities through the SourceStatistics API, supporting daily and monthly production planning, current production monitoring, and historical performance analysis in AnyLogic refinery simulation models.
       The SourceStatistics API is organized into four main components:

• Output — provides access to connected fluid blocks and valves and retrieves flow or mass values for individual source items through getFlowBySourceId(). The returned value depends on the requested measurement type and whether cumulative mass or mass produced during the current planning period is required.
• PlanCompletion — provides production plan execution metrics through getCurrentPeriod() and getMonthly(). Its nested Execution class exposes primary and secondary plan values, actual production, completion ratios, completion statuses, unfulfilled plan mass, and shortfall against the plan expected by the current simulation time.
• Database — provides historical planned and actual production data. Its methods support aggregation by model-time-step range, calendar month, and date range, as well as retrieval of time-series values as maps. When statistics saving is enabled, actual history is available in every planning mode. In unlimited planning, primary and secondary plan values are stored as NULL.
• Properties — provides source metadata, including source item identifiers through getSourceIds() and product identifiers through getProductIdBySourceId().

       Together, these components provide the data needed for refinery production monitoring, production plan execution analysis, historical reporting, time-series analysis, and operational dashboards. Engineers can compare actual production against planned values, evaluate plan completion, identify production shortfalls, and analyze source performance over time.
       Source Statistics can be used to monitor feedstock output and production performance within a broader refinery logistics model. A practical application of these concepts is presented in the Crude Oil Supply Chain Simulation solution, which demonstrates how feedstock deliveries, pipelines, tank farms, and refinery operations can be modeled as an integrated system.
       While production performance metrics show how a Source behaves during simulation, Source Control in Refinery Simulation explains how its flow limits can be managed dynamically during model execution. The FlowProvider architecture provides a unified interface for accessing flow information across compatible refinery simulation components.

       The Output component uses connected fluid blocks and valves to calculate and format output statistics. The total from getFlow() sums measurements from the connected output blocks. hasFlow() checks whether the resulting mass flow is positive.
With deferred connection (connectAfterStart = true), the current implementation creates the output statistics before assigning the new output array. If the previous array was empty, getFlow() can return 0 and hasFlow() can return false even after the outputs are connected.

       These metrics support refinery production monitoring and material flow analysis, including mass and mass-flow measurements for individual Source items. They help engineers evaluate feedstock deliveries and production throughput in interconnected oil and gas facilities. The Crude Oil Supply Chain Simulation article explores these flows across pipelines, tank farms, and refinery processing units. The FlowProvider abstract classes defines a common API for flow statistics in AnyLogic refinery models.

             PlanCompletion Statistics provide production performance metrics for evaluating how closely actual Source output follows the configured production plan in refinery simulation. The API supports both daily and monthly production planning and provides plan values, plan completion ratios, and completion statuses. These metrics help engineers evaluate actual vs planned production and identify deviations in refinery production plan execution. Production plan execution can also be coordinated through request-based production planning, where downstream requirements and operational information influence upstream production decisions.
       In refinery simulation, production plan execution is closely connected with the conversion of planned volumes into continuous operating flows. The relationship between production planning, flow smoothing, and downstream simulation behavior is discussed in Flow Smoothing for Digital Twin Simulation.
             The Execution class provides access to primary and secondary plan values, actual production, completion ratios and statuses, as well as unfulfilled and unaccepted mass for individual Source items. The getCurrentPeriod() and getMonthly() methods provide access to the corresponding execution statistics.
With unlimitedPlanning = true, plan execution metrics such as plan values, completion ratios, and statuses throw IllegalStateException when queried.

       Historical Statistics store primary plan, actual, and secondary plan values for individual source items. The public query methods retrieve primary plan or actual values; historical secondary plan values are not currently exposed through the Database API. When statistics saving is enabled (enableStatisticsSaving = true), SourceStatistics maintains historical production data and time-series production data that can be queried by simulation time, date range, or month. This enables historical flow analysis, production reporting, and comparison of planned and actual refinery production over time.
In unlimited planning mode (unlimitedPlanning = true), actual production is still recorded when statistics saving is enabled. Both plan columns contain NULL, so there is no historical plan series for that mode.

Source Properties provide basic metadata for identifying Source items and their associated products in an AnyLogic refinery simulation. The API allows applications to retrieve configured source IDs and map each Source item to its associated product, linking production flow data to specific refinery products.

Source Statistics support the entire refinery simulation lifecycle, from model debugging and production monitoring to plan execution analysis and historical reporting. The four functional groups of SourceStatistics—Output, PlanCompletion, Database, and Properties—enable engineers to analyze Source output, compare actual and planned production, track plan completion, and retrieve historical production data. These capabilities are particularly useful for monitoring variable feedstock supply and evaluating its impact on downstream refinery operations, as discussed in our guide to crude oil supply chain simulation.

Source performance monitoring becomes particularly valuable when feedstock production is part of an integrated refinery supply chain. The Crude Oil Supply Chain Simulation solution demonstrates how crude oil supply, transportation, storage, and refinery operations can be modeled as an interconnected system.

Source Statistics provide a consistent API for monitoring Source output, evaluating production plan execution, and analyzing historical performance in refinery simulation. The four statistics groups—Output, PlanCompletion, Database, and Properties—support operational monitoring, production planning analysis, and historical data retrieval. By combining actual output, planned production, and historical data, SourceStatistics helps engineers monitor refinery production, assess plan completion, and develop reporting and analytical applications.

1. What are Source Statistics in refinery simulation and production monitoring?
Source Statistics provide production performance metrics for monitoring Source output, evaluating production plan execution, and analyzing historical production data through the SourceStatistics API in refinery simulation.

2. What statistics are available for a Source?
SourceStatistics provides four functional groups: Output, PlanCompletion, Database, and Properties. They cover output monitoring, production planning, historical data retrieval, and Source item and product identification.

3. How can I get the total Source output?
Use getFlow(MeasurementType measType) to sum the measurements from connected output blocks in tons or tons per hour. See the deferred connection caveat under Output Statistics.

4. Can Source Statistics provide output for an individual Source item?
Yes. getFlowBySourceId() returns the output flow for a specific Source item and supports cumulative mass, incremental mass, and flow-rate measurements.

5. Does SourceStatistics support daily and monthly production planning in refinery simulation?
Yes. The PlanCompletion API provides plan values, completion ratios, and statuses for daily and monthly planning. These queries throw IllegalStateException in unlimited planning mode.

6. How can I check production plan completion?
Use getCompletionRatio(int sourceId) to retrieve the completion ratio for a specific Source item through the relevant Execution instance. Use getStatus(int sourceId) to retrieve its corresponding PlanCompletionStatus.

7. Can Source Statistics store historical production data from a refinery simulation?
Yes. With statistics saving enabled, SourceStatistics stores actual production by Source item. It also stores plan values for daily and monthly planning. In unlimited planning mode, both plan columns contain NULL.

8. Can historical Source data be queried by date or month?
Yes. Historical data can be retrieved by simulation-time range, calendar month, YearMonth, or date range. The API also supports retrieving all stored values ordered by simulation time.

9. How can I identify the product associated with a Source item?
Use getProductIdBySourceId(int sourceId) to retrieve the associated product identifier. Use getSourceIds() to retrieve the identifiers of all Source items.

10. What are Source Statistics used for in refinery production monitoring?
Source Statistics support production monitoring, plan execution analysis, historical production reporting, product identification, model debugging, and analytical applications in AnyLogic refinery simulation models.