Petroleum Refining Library Exporter: Configuration, Reporting and API

       Exporter Series:
       1 Export Simulation Results to XLSX: Complete Guide
       2 Source Exporter in AnyLogic: Export Source Statistics to Excel
       3 Process Unit Statistics Export to Excel in AnyLogic
       4 Tank Farm Statistics Export to Excel in AnyLogic
       5 How to Add Custom Rows to an AnyLogic Exporter Report
       6 Petroleum Refining Library Exporter: Configuration, Reporting and API

       The Petroleum Refining Library Exporter provides a centralized way to collect AnyLogic simulation results and generate structured XLSX reports from Petroleum Refining Library models. It can be configured to control which model objects are included in the export, how they are ordered, how frequently reports are generated, and which parts of the standard report structure are displayed. The Exporter also provides a programmatic API for extending the standard reporting functionality. This includes adding custom export rows, overriding product names, and triggering XLSX export directly from Java code. The Exporter generates an XLSX-based Excel simulation report that can be customized using an existing template.

       To use the Exporter, add the Results Exporter agent from the Petroleum Refining Library palette to the AnyLogic model. The agent can also be referred to simply as Exporter. Only one Exporter can be placed in a model. The Exporter is designed to provide a single reporting and export point for the simulation model. Adding more than one Exporter to the same model results in an error. After adding the Exporter, its configuration can be adjusted directly through its properties. The useIniSettings property determines whether the Exporter uses configuration settings loaded from an INI file.

      The isEnabled property controls whether the Exporter performs its reporting operations. When set to false, report generation is disabled. This can reduce simulation runtime when reporting is not required. When reporting is not required, disabling the Exporter prevents report generation and can reduce the execution time of simulation runs. This is particularly useful when running a model repeatedly for testing, calibration, or optimization, where generating an XLSX report for every run may be unnecessary.
      The exportFrequency property defines the interval at which the Exporter records a new export step. The available frequencies are hours, days, months, and years. The supported frequency options are: Hours, Days, Months, Years. This setting determines the time interval between export steps and therefore the temporal resolution of the resulting report. The exportToXlsx property controls whether the Exporter generates an XLSX report. When disabled, XLSX export is not performed.

     The reportName property defines the base name of the generated report. Reports are created in the model's Results folder.
Each generated report uses the configured reportName followed by the date and time. The generated filename consists of the configured report name followed by the date and time, allowing reports from different simulation runs to be stored separately.

     The Exporter can create a report from an existing XLSX template. To use an XLSX template, place it in the Template subfolder of the Exporter's folder. If a template is available, the Exporter uses it as the basis for the generated report and creates a copy containing the simulation results. If the Template folder is empty, the report is created without a predefined template.
This approach makes it possible to control the visual structure and formatting of the resulting Excel report without changing the Exporter's export logic.

     The onAfterInitialize event is executed after the Exporter has been initialized and can be used to perform additional initialization logic. This event can be used when additional initialization logic needs to be performed after the Exporter has been initialized.

       The Exporter allows you to control which types of Petroleum Refining Library objects are included in the generated report. This provides control over the scope of the exported simulation results without requiring changes to the model logic.
The current Exporter supports three main object types:

• Sources
• Process Units
• Tank Farms

Each category can be enabled or disabled independently.

       The includeSources property determines whether Source objects are included in the export. When enabled, the corresponding Source statistics are included in the generated report. When disabled, Source data is excluded from the export. For more information, see the guide to Source statistics export in AnyLogic.

       The includeProcessUnits property controls the export of Process Unit statistics. This allows a model to generate reports containing process-unit results only when those results are relevant to the particular simulation run or reporting task. For more information, see the guide to Process Unit statistics export in AnyLogic.

       The includeTankFarms property determines whether Tank Farm statistics are included in the report. This is particularly useful for models where storage statistics are required for some reporting scenarios but not for others. For more information, see the guide to exporting Tank Farm statistics in AnyLogic.

       The Exporter provides two properties for controlling which Petroleum Refining Library objects appear in the report and in what order: sortedPrlObjects and excludedPrlObjects.

       The sortedPrlObjects property contains an array of PRL objects that defines their order in the generated report.
When objects are specified in this array, the Exporter processes them according to the order in which they are listed. This allows the report structure to follow the logical organization of the simulation model rather than relying only on the default object order.
For example, a refinery model may contain several Process Units and Tank Farms. By specifying these objects in sortedPrlObjects, you can place the most important units first and arrange the report according to the desired reporting sequence.

       The excludedPrlObjects property contains the PRL objects that should not be included in the report. This can be useful when a model contains objects that are required for the simulation but are not relevant to a particular reporting task. Instead of changing the model itself, you can simply exclude those objects from the Exporter configuration.

       The exportTrigger event is automatically called each time the Exporter records a new export step. The exportTrigger event is automatically called each time the Exporter records a new export step. Custom rows can be implemented using AbstractAdditionalRowExport. See Add Custom Rows to the Exporter for details. It can be used to add additional statistics or custom rows to that export step. It can be used to provide additional statistics or other custom data that should be included in the generated report. For example, custom statistics can be registered through the AbstractAdditionalRowExport mechanism described in the dedicated article about adding custom rows to the Exporter. The exportTrigger is therefore useful when the standard Source, Process Unit, and Tank Farm statistics are not sufficient for a particular reporting requirement. It allows additional reporting logic to be executed as part of the Exporter's regular export cycle.

       The Exporter includes an internal Constants class that controls the structure and presentation of the standard report. It allows you to customize standard report labels and control which report sections are included. For example, the labels for Input, Production output, Product Shipment, Process Unit, Tank Farm, Loss, and GON can be customized. The class also controls the visibility of standard sections such as the timeline, total input and output, losses, GON, and residual structures. The configuration can be customized programmatically using ConstantBuilder, without modifying the Exporter's core logic.

       The Exporter provides several public methods that can be used to extend or control the export process directly from the simulation model's Java code. The addAdditionalRow(AbstractAdditionalRowExport additionalRow) method registers an additional row for XLSX export. The AbstractAdditionalRowExport implementation defines where and how the row is added. If null is passed, no action is performed. The overrideProductName(PrlObject prlObject, int productId, String newProductName) method allows you to replace the product name displayed in exported statistics. It supports Source, ProcessUnit, and TankFarm objects and stores the specified name for subsequent reporting. Finally, writeToExcel() explicitly starts the XLSX export. The method first checks exportToXlsx. If XLSX export is disabled, it returns false. Otherwise, it initializes the XLSX exporter, loads the configured template, exports the model data, and saves the resulting report. The method returns true after the export is completed.

       The Petroleum Refining Library Exporter provides a centralized reporting layer for AnyLogic simulation models. It combines configurable export frequency, object selection, report ordering, XLSX templates, and report structure customization in a single component. The Exporter can also be extended through its Java API, allowing developers to add custom statistics, override product names, and control XLSX export programmatically. This makes the Exporter suitable for both standard simulation reporting and custom reporting workflows in refinery and oil and gas simulation models.

1. How many Exporter agents can be added to one AnyLogic model?
Only one Exporter can be placed in a model. Adding multiple Exporter agents results in an error.

2. Can the Exporter be disabled?
Yes. Set isEnabled to false to disable report generation. This can reduce simulation runtime when reporting is not required.

3. Where are generated reports saved?
Reports are created in the Results folder. Each report receives the configured reportName followed by the date and time.

4. Can the Exporter use an Excel template?
Yes. An XLSX template can be placed in the Exporter's Template folder. The Exporter uses this template as the basis for the generated report.

5. Which Petroleum Refining Library objects can currently be exported?
The Exporter currently supports Sources, Process Units, and Tank Farms. Each category can be included or excluded independently.

6. Can I control the order of objects in the report?
Yes. The sortedPrlObjects property allows you to specify the order in which PRL objects are presented in the report.

7. Can individual objects be excluded from the report?
Yes. Objects can be specified in excludedPrlObjects to prevent them from being included in the export.

8. What is the purpose of the exportTrigger event?
exportTrigger is called when a new export step is recorded. It can be used to add additional statistics or custom rows to the export.

9. Can the standard report structure be customized?
Yes. The internal Constants class allows you to customize standard report labels and control the visibility of standard report sections.

10. Can I add my own rows to the exported report?
Yes. The addAdditionalRow() method allows an AbstractAdditionalRowExport implementation to be registered for XLSX export.

11. Can product names be changed only in the exported report?
Yes. The overrideProductName() method allows a custom product name to be specified for a Source, Process Unit, or Tank Farm without changing the model object's product itself.

12. Can XLSX export be started directly from Java code?
Yes. The writeToExcel() method explicitly starts the XLSX export and returns true when the export is performed.