Source in Refinery Simulation: Complete Guide to Feedstock Planning, Flow Control, and Statistics

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

What Is the Source Component in Refinery Simulation?

       The Petroleum Refining Library Source component in refinery simulation represents the upstream supply. of crude oil, natural gas, unstable gas condensate, and other hydrocarbon feedstocks entering a refinery or processing facility. In the Petroleum Refining Library (PRL) for AnyLogic, Source connects feedstock supply plans with continuous material flows throughout the refinery model. Unlike a generic flow generator, the Petroleum Refining Library Source component is designed specifically for refinery feedstock planning and refinery feedstock simulation. It supports daily and monthly production plans, database-driven planning, multiple feedstock sources, continuous flow generation, and flow smoothing between planning periods. In a typical refinery logistics simulation, the feedstock flow can be represented on figure.

       Source can also adapt feedstock flows during simulation. Runtime control allows engineers to set and restore flow limits for individual Source elements or the combined Source output. Source also provides production performance monitoring. Its SourceStatistics API covers current output, production plans, historical planned and actual values, and source/product identification. Therefore, Source provides a complete interface between feedstock planning and refinery operations:

Plan → Flow → Control → Statistics

       The following sections explain Source configuration, production planning, flow smoothing, runtime control, statistics, and integration with refinery logistics and Digital Twin models.
Interactive Example Available!
See Petroleum Refining Library Source in action!
Launch the interactive AnyLogic Cloud model and experiment with sources
Let's go!

Source Configuration and Structure

       A Source can contain multiple source elements representing different feedstock streams or supply sources. These elements can be grouped, connected to separate product outputs, or merged into a single combined output depending on the refinery model configuration. Source configuration determines how these elements are identified, how production plans are loaded, how flows are generated, and how the component interacts with the rest of the simulation model.
       The main configuration properties include:
  • sourceGroupId — groups Source elements using the corresponding database identifier;
  • sourceGroupLabel — defines the displayed Source group label;
  • dailyPlanningMode — selects daily or monthly production planning;
  • sourcePlansFromMainTable — specifies the database table used to load Source plans;
  • enableFlowSmoothing — enables smoothing between monthly planning periods;
  • enableStatisticsSaving — enables storage of Source statistics;
  • unlimitedPlanning — enables Source to operate without database-driven production plans;
  • outputFlows — defines Source output flows;
  • connectAfterStart — allows output connections to be established after model startup.
       This configuration separates the main responsibilities of Source: feedstock identification, production planning, flow generation, output routing, and performance data collection.

Source Output Configuration
       Source supports two basic output configurations: multiple product-specific outputs or a single combined output.
This allows the same Source architecture to represent both independent feedstock streams and systems where several sources are combined before entering the downstream refinery logistics network.

See details: Source Control in Refinery Simulation: Runtime Flow Management

Production Planning with Source

       The Source component in refinery simulation supports both daily and monthly refinery production planning. Planning data can be loaded from a database and converted into continuous feedstock flows for the simulation. The planning mode is controlled by dailyPlanningMode. Source can also load plans from the configured planning table, while unlimitedPlanning provides an alternative mode in which database-driven planning is ignored. For example, daily and monthly production plans can be used to simulate crude oil and condensate deliveries, while unlimited planning can be used to model fuel gas supplies for refinery own needs, assuming that the required gas is always available in sufficient quantities. Production planning therefore defines the expected feedstock supply, while Source translates that plan into the actual flow used by the refinery model:

Production plan → Source → Target flow

       Plan execution can then be evaluated by comparing actual Source output with the configured plan. Source Statistics provides plan values, completion ratios, and completion statuses for both daily and monthly planning. For monthly plans, Source can additionally apply flow smoothing at the boundaries between planning periods. This prevents artificial flow discontinuities while maintaining the planned delivery volumes. This makes Source suitable for modeling feedstock supply where production planning, production scheduling, and continuous refinery operation must remain synchronized.

Flow Generation from Production Plans

       Once a production plan is loaded, Source converts the planned feedstock volume into a continuous material flow used by the refinery simulation. This step connects planning data with the dynamic behavior of downstream pipelines, tank farms, and process units. he resulting flow represents the feedstock supply rate required to execute the production plan. The actual Source output can then be monitored against the planned volume using Source Statistics. For monthly planning, a direct change from one calculated flow rate to another can create an artificial discontinuity at the boundary between two months.
       The resulting flow can then interact with the rest of the refinery feedstock supply chain, including pipelines, tank farms, and downstream processing units.

Flow Smoothing Between Planning Periods

       When monthly production plans are converted directly into continuous flows, a change in the planned volume can produce an abrupt change in Source flow at the boundary between two months. In a refinery simulation, such discontinuities may create unrealistic operating conditions for downstream equipment. Source provides flow smoothing to create a gradual transition between adjacent monthly planning periods while preserving the planned delivery volumes. The feature is enabled with enableFlowSmoothing. The concept is:

Monthly plan A → Transition → Monthly plan B

       This is particularly useful in refinery Digital Twin models, where feedstock flows should represent realistic operating behavior.rather than instantaneous changes caused only by a change in planning data. Flow smoothing is therefore an important part of the Source workflow when monthly production planning is used and continuous feedstock behavior is required.

See details: Flow Smoothing in Digital Twin Simulation: Converting Source Plans into Continuous Flows

Source Flow Connections

       The connect() method establishes connections between Source elements and external fluid flows. Connections can be configured for separate product-specific outputs or a single combined output.
       Source supports two connection configurations:
  • Multiple output flows — each Source element is connected to an output corresponding to its product.
  • Single output flow — flows from all Source elements are merged into one combined stream.
       The connection can also be deferred until after model startup using connectAfterStart. This is useful when Source outputs need to be established later in the simulation initialization sequence. This gives Source flexibility to represent both independent feedstock streams and combined feedstock supply within a refinery logistics model.

See details: Source Control in Refinery Simulation: Runtime Flow Management

Runtime Source Flow Control

       Refinery operating conditions can change during simulation, requiring feedstock flow rates to be adjusted without changing the model structure. The Source runtime control API provides this capability by allowing flow limits to be changed while the simulation is running.
       Source supports two control levels:
  • Individual Source element — setElementSpeedLimit() limits the flow of a specific feedstock stream.
  • Combined Source output — setSpeedLimit() limits the total flow when multiple Source elements are merged into one output.
       The limits can also be queried and restored using the corresponding get... and reset... methods. This allows Source to represent changing feedstock production rates, transportation constraints, or refinery operating conditions during a simulation run without modifying the underlying model structure.

See details: Source Control in Refinery Simulation: Runtime Flow Management

Source Events and Callbacks

       Source provides event callbacks for initialization and runtime flow changes:
  • onBeforeInitialize() — called before Source initialization.
  • onAfterInitialize() — called after Source initialization.
  • onSpeedChange(Map newSpeedBySourceId) — triggered when the speed of a Source element changes. The event provides the updated speed for each affected source element in tons per hour.
onSpeedChange() is particularly useful for event-driven refinery flow control. It is triggered with zero atomic delay, allowing downstream logic to respond immediately to a Source flow-rate change without periodically polling the current speed.
This creates a simple integration pattern:

Source flow change → onSpeedChange() → downstream control logic

       Such event-driven integration is useful when changes in feedstock supply must immediately affect pipelines, tank farms, production logic, or other refinery simulation components.

See details: Source Control in Refinery Simulation: Runtime Flow Management

Source Statistics and Production Monitoring

       Source provides built-in production performance monitoring through the SourceStatistics API, allowing engineers to evaluate actual feedstock output against production plans. For a detailed discussion of Source performance metrics and production plan execution, see Source Performance Metrics in Refinery Simulation. It allows the simulation model to track current output, evaluate production plan execution, and analyze historical feedstock flows.
       The statistics are organized into four functional groups:
  • Output — current total and source-level flow;
  • Plan — planned values, plan completion, and completion status;
  • Database — historical planned and actual values;
  • Properties — Source and product identification.
       For example, getTotalFlow() returns total Source output, while getFlowBySourceId() provides flow information for an individual Source element. These methods support cumulative mass, incremental mass, and flow-rate measurements. Plan statistics can be used to compare actual vs. planned production and evaluate production plan execution.When statistics saving is enabled, historical planned and actual values can also be queried by simulation-time range, date range, or month. This supports production reporting, plan execution analysis, time-series analysis, and operational dashboards.

See details: Source Statistics in Refinery Simulation

Source Integration in Refinery Simulation and Digital Twins

       Source is typically used as the upstream feedstock boundary of an integrated refinery logistics and oil and gas simulation model. Its outputs can be connected to pipelines, tank farms, blending systems, and downstream process units, allowing planned feedstock supply to propagate through the refinery model. This is particularly important in crude oil supply chain simulation, where multiple feedstock sources may have different production volumes, products, and operating conditions. Crude oil, condensate, natural gas, and other streams may have different production volumes, products, and operating conditions, while the downstream system determines how these flows are transported, stored, blended, and processed. Source statistics can then be used to evaluate how upstream supply affects downstream operations by comparing actual output with production plans and analyzing historical flow data.
       A typical integrated model can therefore be represented as:

Feedstock Sources → Source → Pipelines → Tank Farms → Refinery Units

       Within a Digital Twin, this structure allows changes in feedstock supply to be reflected in the simulated refinery system and evaluated together with transportation, storage, and processing constraints.

Conclusion

       Source provides a unified modeling layer between upstream feedstock planning and downstream refinery operations. It supports refinery feedstock management through production planning, continuous flow generation, flow smoothing, output routing, runtime flow control, and production performance monitoring.
       By combining these capabilities, Source can represent both simple feedstock inputs and complex supply scenarios involving multiple sources, pipelines, tank farms, and refinery process units. Production plans define the expected supply, runtime control represents changing operating conditions, and Source Statistics provides the data required to evaluate actual performance against the plan. The complete Source workflow can be summarized as:

Plan → Generate Flow → Smooth → Connect → Control → Monitor → Analyze

       This makes Source a core component for refinery feedstock simulation, crude oil supply chain simulation, refinery production planning, logistics modeling, and AnyLogic-based Digital Twin applications.

FAQ

1. What is the Source component in refinery simulation?
Source represents the upstream supply of crude oil, natural gas, unstable gas condensate, and other hydrocarbon feedstocks entering a refinery or processing facility. It connects production and supply plans with continuous material flows in the simulation.

2. What types of feedstock can Source simulate?
Source can represent crude oil, natural gas, unstable gas condensate, and other hydrocarbon feedstock streams supplied to refinery and gas processing facilities.

3. Does Source support daily and monthly production planning?
Yes. Source supports both daily and monthly production plans and can load plans from configured database tables.

4. Can Source convert production plans into continuous flows?
Yes. Source converts planned feedstock volumes into continuous flow rates used by the dynamic refinery simulation.

5. What is flow smoothing in Source?
Flow smoothing creates gradual transitions between adjacent monthly planning periods, helping avoid artificial flow discontinuities in the simulation.

6. Can Source handle multiple feedstock streams?
Yes. Multiple Source elements can represent different feedstock streams. They can either remain as separate product-specific outputs or be merged into a single combined output.

7. Can Source outputs be connected after model startup?
Yes. Output connections can be deferred until after startup using the appropriate Source configuration.

8. Can Source flow rates be changed during simulation?
Yes. The Source runtime API allows flow limits to be changed during simulation for individual Source elements or for a combined Source output.

9. Can I control individual Source elements separately?
Yes. setElementSpeedLimit() allows a maximum flow rate to be specified for an individual Source element.

10. Can I limit the total Source output?
Yes. setSpeedLimit() sets the maximum total output flow when multiple Source flows are combined.

11. How can the model respond to a Source flow-rate change?
The onSpeedChange() event is triggered when a Source element changes speed. It provides the updated speeds with zero atomic delay, allowing downstream logic to respond immediately.

12. What Source statistics are available?
SourceStatistics provides four main groups: Output, Plan, Database, and Properties. These cover current output, production plans, historical data, and Source/product identification.

13. Can Source compare actual production with the production plan?
Yes. Plan Statistics provide plan values, completion ratios, and completion statuses for evaluating production plan execution.

14. Can Source store historical production data?
Yes. When statistics saving is enabled, Source can store planned, actual, and secondary plan values for individual Source elements.

15. How can historical Source data be queried?
Historical data can be retrieved by simulation-time range, calendar month, YearMonth, date range, or as the complete stored time series.

16. Can Source be used in refinery Digital Twin models?
Yes. Source can connect feedstock planning with continuous flows, runtime control, logistics, and production monitoring, making it suitable for refinery Digital Twin and crude oil supply chain simulation models.

17. What is the typical Source workflow in refinery simulation?
The typical workflow is:
Plan → Generate Flow → Smooth → Connect → Control → Monitor → Analyze
This allows Source to represent the complete lifecycle of refinery feedstock supply from production planning to operational performance analysis.