Documentation for Petroleum Refining Library
1 INTRODUCTION
1.1 What is Petroleum Refining Library?
Petroleum Refining Library (PRL) is an additional palette library for Anylogic (www.anylogic.com). It is based on Anylogic Fluid Library and helps to build a different kind of imitation models for Oil & Gas industry.Like Anylogic, Petroleum Refining Library fully supports Java.
Petroleum Refining Library includes PRL API (7zip archive).
Base Petroleum Refining Library features:
• building a different kind of imitation models like “digital twins” in Oil & Gas industry;
• performing an accurate “balance” calculations of incoming flows and resulting products;
• make detailed optimization flows calculations within Oil & Gas refining;
• taking into account all unique features of specific Oil & Gas companies for maximum accurate forecasting;
• setting and solving any tasks of the current processing management in Oil & Gas industry.
Editions of Petroleum Refining Library:
• free edition – “free to try” version with limited performance and license;
• commercial edition – high-performance version of Petroleum Refining Library with business-friendly license;
• advanced commercial edition – commercial edition of Petroleum Refining Library with full source library code.
Free Edition of Petroleum Refining Library has a corresponding warning on every page, and has a limit on model time duration (max 45 days). Commercial Edition is a heavily optimized version of Petroleum Refining Library, containing all library components without any restrictions.
There is also an advanced commercial Petroleum Refining Library license, under which you’ll receive full source code.
More detailed information is available in our Knowledge and Solutions sections.
1.2 Petroleum Refining Library license
The Petroleum Refining Library free edition is distributed under a license that favors non-commercial usage and operates under a "free to try" principle.
The Petroleum Refining Library commercial edition and advanced commercial edition are distributed under a license that is friendly to commercial users. A copy of the commercial license can be found here
1.3 Documentation license
This reference manual is licensed under BSD-like documentation license:
Copyright 2025 by Petroleum Refining project. All rights reserved.
THIS DOCUMENTATION IS PROVIDED BY THE PETROLEUM REFINING PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE PRL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.4 About this manual
This manual provides general information about Petroleum Refining Library. It contains a description of every PRL agent and some examples. To know more, please visit our knowledge and solution sections, or YouTube channel.
On our website you can also found a Java API that describes all available Petroleum Refining Library functions.
1.5 Acknowledgements
Petroleum Refining Library was not possible without contributions of the following open-source projects:
• ojAlgo – mixed Integer Linear Programming (MILP) solver. ojAlgo solves pure linear, (mixed) integer/binary models;
You MUST add these libraries to your Anylogic model before using PRL. Working versions of these libraries are always located in the \lib\ subfolder
2 PETROLEUM REFINING LIBRARY STRUCTURE
2.1 Petroleum Refining Library structure
The PrlConstants class contains final static constants for PRL. Full description can be found in PRL API.
All PRL agents extend from the PrlObject agent. They can be divided into two categories: agents with interface (such as ProcessUnit or Accumulative Tank Farm), which extend from PrlGUIObject (PrlGUIObject extends from PrlObject), and agents without interface (such as Source or Separator), which extend directly from PrlObject. All PRL agents have an inner Constants class (accessed via the public constant variable) that contains local additional Agent settings.
Many agents also contain an inner AgentNameStatistics class (accessed via the public statistics variable) to access various statistical indicators (input or output flow rates, flows mass, etc.). Full description can be found in PRL API.
Some agents also contains inner agents. For example, Source agent contains an inner SourceElement agent for modeling incoming flow from a single source (oil or gas field), ProcessUnit agent contains an inner ProcessUnitLine agent for working with the single line.
Some parameters values can be set in *.ini files. The name of each *.ini file and it’s location are formed according to the following rule: the directory name and the name of the file, created by the agent class name (for example:
BaseConstant.INI_DIRECTORY_PATH + Source.class.getSimpleName() + “.ini”
will search *.ini file in: “\Ini\Source.ini”). To access a specific agent in the *.ini file, create a section with its system name (in square brackets). For example: [sourceAgent1].Source is an advanced container that allows to create various types of entry flows (oil, unstable natural gas liquid, etc.). Source agents enable to set daily or monthly flow plans from the attached database, facilitate flow smoothing for monthly values, and provide many other functions |
Process Unit is an agent, that allows for the configuration of the flow-splitting process by various types of processing plants in the Oil & Gas industry (such as rectification, catalytic reforming, etc.). The ProcessUnit agent contains a wide variety of settings that enable the establishment of basic operating conditions for almost any kind ProcessUnit in Oil & Gas |
Flowing Tank Farm is an advanced park agent that extends all Tank Farm agent properties. Flowing Tank Farm is characterized by continuous inflows and outflows that fill and unload some parallel connected tank (called "maps"), Flowing Tank Farm is usually used for "smoothing" outgoing flow products |
Accumulative Tank Farm is advanced park agent, that extends all Tank Farm agent properties. Accumulative Tank Farm contains many options, which are necessary for "cumulative" tank farms. This agent implements procedures of accumulation, passportization (compounding), and shipment of products. In addition, Accumulative Tank Farm contains built-in mechanisms for tracking product shipment plan with the ShipmentNode agent |
Shipment Node is an agent that allows to set plans for pumping products and monitor the degree of their implementation during modeling. This agent contains a variety of settings that allow to create different options for pumping products (daily, monthly) etc. |
Control makes effective request management possible because it contains Java interface elements that enable configuring different request-processing rules. It also supports a recording mode for capturing user-made menu configuration changes and a player mode for reproducing these changes automatically on the next application startup |
Exporter periodically exports simulation results during model runtime. Collects output data and writes it to external targets such as Excel files or database systems at a specified frequency |
Separator Light is an advanced separator (split) agent that allows to split the input flow into two outputs. In comparison with the AnyLogic FluidSplit, this agent enables to direct the entire flow to ONLY ONE output, set the input flow speed limit, and implement many other functions |
Mixer Light is an advanced mixer (merge) agent that allows to combine two entry flows into one exit flow. In comparison with the AnyLogic FluidMerge, this agent enables to set an exit flow speed limit, and implement many other functions |
Separator is an advanced separator (split) agent that allows for splitting an incoming flow into any number of exits. In comparison with the AnyLogic FluidSplit, this agent allows for directing the entire flow to ONLY ONE output, setting as many exits as the user wants, establishing a user-defined separation factor, entering a speed limit, and implement many other functions |
Mixer is an advanced mixing (merging) agent that allows for merging of any number of input flows into one output. In comparison with the AnyLogic FluidMerge, this agent allows users to set as many input flows as desired, establishes an input speed limit, and implement many other functions |
Product Mixer is an advanced product mixing agent, that allows for the optimal mixing of input flows and product additives to create a desired product (such as petrol, kerosene, etc.). It is known that the creation of most products is accompanied by a number of requirements (such as octane number, sulfur content, saturated vapor pressure, aromatics, etc.). This agent takes these requirements into account and mixes incoming flows in an optimal way to ensure their simultaneous fulfillment |
Optimizer is an agent, that allows to set up and solve different kinds of linear programming (LP) problems (for example, splitting the input flow between Process Units and Process Units lines with the objective of minimizing residuals). |
Flow Quota is an agent that allow to set periodic plans for pumping products. For example, set a plan for the maximum monthly (or daily) pumping. Required to account for the maximum capacity of the pumping equipment |
Loading Rack controls the loading of refined products into railway tanks/trucks at a loading rack, managing train schedules, loading operations, wagon assignments, product quantities, supply/removal durations, passportization, and overseeing the state machine for the loading workflow (supply/load/remove) |
Dispose is an agent, that allows to calculate the amount of disposed flows. In comparison with AnyLogic FluidDispose, this agent enables the collection of the same type of flows into one agent, saves the necessary statistics, and destroys them (for example, collecting all gas flows per flare) |
Season Event triggers the event when the simulation season change |
Flow Discrepancy represents a flow discrepancy controller. Tracks discrepancy values for a specified flow and optionally terminates the calculation when a critical discrepancy threshold is exceeded |
In addition to the described components, the library contains a large number of auxiliary classes and utilities designed to simplify model development, reduce boilerplate code, improve configuration flexibility, and support integration, visualization, data processing, and simulation workflow management. |
PRL API can be download here (7zip archive)