NXW2.1P03 - High-Fidelity Digital Twin for Container Terminals

A detailed and extensive Digital Twin for modeling container terminal operations based on Discrete-Event Simulation, battery (dis)charge equations and optimal pilling techniques, completely implemented in Python by the Team. The tool enables terminal planners, port authorities, and researchers to configure scenarios, simulate integrated quayside, yardside, and landside flows, compare up to five operational scenarios, evaluate KPIs with replications and confidence intervals, and test resilience under crane failures, battery constraints, gate capacity limits, rail operations, and adverse weather disruptions.

  • Main Gain(s): Better terminal resilience under disruptions, Reduction of vessel waiting time, Improved equipment utilization, Improved energy analysis for electric horizontal transport, Support for data-driven terminal planning

  • Use Case(s): Use of historical data from Terminal XXI of Port of Sines. Allows real-time adaptation to current data, but also default parameters if data is not available. Configurable scenario-based simulation using default parameters, API data, or uploaded CSV operational data for vessel, truck, and train schedules.

  • Start TRL: 2 - (evidences)

  • Final TRL: 6 - (evidences)

  • Main Contributions: (theoretics) A. Khan, E. Rocha; (implementation) A. Khan; (integration) E. Rocha

Main Features

  • Fully configurable web-based Discrete-Event Simulation tool for container terminal operations
  • End-to-end simulation of import and export container flows from vessel anchorage to inland departure by truck or train
  • Scenario comparison for up to five operational configurations, each with multiple statistical replications
  • KPI dashboards with 95% confidence intervals and detailed KPI distribution plots
  • CSV upload support for vessel, truck, and train schedules
  • Berth allocation using a FIFO Best-Fit strategy over a continuous quay space
  • Dynamic resource allocation for quay cranes and horizontal transport vehicles using user-defined lookup tables
  • Configurable priority rules for vessel, train, and truck operations competing for shared resources
  • Three disruption models: random quay crane failures, moves-based failures, and environmental disruption of quay and yard cranes
  • Physics-based battery energy model for electric horizontal transport units, including state-of-charge management and charging logic
  • Analysis tabs for quay cranes, horizontal transport vehicles, yard cranes, cargo flows, and detailed KPIs

Videos

Container Terminal Simulation Tool (demonstration of human configurations and KPI visualization without real-time data)

Product Development Context

Container terminals face increasing pressure to handle larger vessels, reduce turnaround times, and meet stricter environmental targets. These goals require coordinated planning across quay cranes, horizontal transport, yard cranes, gates, trucks, and trains. Existing simulation models are often calibrated for a single terminal case and usually focus on only one operational area, such as quayside, yardside, or landside processes. This limits their transferability and reduces their usefulness for testing integrated operational decisions. This product addresses these limitations by providing a configurable simulation model with a graphical interface. It allows users to model a container terminal as an integrated system, observe how decisions in one area affect the rest of the terminal, and test operational changes before making costly physical or organizational modifications.

Product Definition and Benefits for Users

The product is a web-based Discrete-Event Simulation (DES) tool for container terminal operations. It is developed in Python using the Salabim DES engine and deployed as an interactive Streamlit web application. The tool simulates the movement of import and export containers through the full terminal process: vessel arrival at anchorage, berth allocation, quay crane discharge and loading, horizontal transport between quay and yard blocks, yard crane stacking and retrieval, truck collection, and train loading. A central design principle is full configurability. Users can modify crane speeds, fleet sizes, failure rates, battery parameters, gate capacities, modal split, priorities, and resource allocation rules directly through the interface without writing code. The main benefits for users are:

  • Fully configurable operation: all model parameters can be adapted to a specific terminal context.
  • Scenario comparison with replications: up to five scenarios can be compared side by side using multiple statistical replications.
  • Real data support: vessel, truck, and train schedules can be uploaded through CSV files.
  • Energy analysis: electricity consumption per TEU can be estimated for battery-electric horizontal transport fleets.
  • Disruption testing: users can test resilience under random crane failures, wear-based failures, and adverse weather events.
  • Automatic results: KPI values and charts update automatically once the simulation run is complete.

Product Characterization – Technical Specs

1. Frontend

The frontend is built with Streamlit and organized into seven tabs. All model parameters are editable directly through the interface, without requiring code or external configuration files. The main tabs are:

  • Scenario Settings: configure parameters for up to five scenarios, set priorities and resource allocation tables, upload CSV data, and run or reset simulations.
  • KPIs: view 10 summary KPI bar charts with 95% confidence interval bands across scenarios.
  • Detailed KPIs: compare more than 25 KPIs using interactive box plots across replications.
  • Quay Crane Analysis: inspect per-crane utilization, productivity heatmaps, gross gang hours, net gang hours, waiting time, downtime, and availability.
  • HT Analysis: analyze per-vehicle utilization, cycle times, gang hours, energy consumption, and charging behavior.
  • Yard Crane Analysis: compare utilization and productive versus standby time for import and export yard cranes.
  • Cargo Flow Analysis: analyze import/export throughput, truck/train modal share, gate-out volume, and rail loading volume. For example, to compare two horizontal transport fleet sizes, the user sets Scenario 1 to 14 vehicles and Scenario 2 to 18 vehicles in the Scenario Settings tab, defines the number of replications, and runs the model. Results can then be explored through HT heatmaps and KPI box plots.

2. Backend

The backend is implemented in Python using the Salabim discrete-event simulation library. The simulation is fully event-driven: entities activate, passivate, and resume in response to simulation events. The time unit is minutes, and the simulation clock can anchor to real datetime values when a vessel schedule CSV is uploaded. The main backend components are:

  • Simulation Engine: event-driven Salabim model controlling all terminal processes.
  • Vessels: manage anchorage queuing, berth occupancy, import discharge, export loading, and departure.
  • Quay Cranes: handle quayside container moves while tracking gross gang hours, net gang hours, and move counts.
  • Horizontal Transport: moves containers between quayside, yardside, and railside while tracking cycle time and waiting time.
  • Yard Cranes: handle import stacking, export retrieval for vessels, import retrieval for trucks, and import retrieval for trains.
  • Trucks: model gate-in, travel to yard block, container collection, and gate-out.
  • Trains: occupy rail tracks, wait for required import containers, and depart once loading is complete.
  • Resource Allocation: dedicated allocator components read user-defined lookup tables and dynamically request cranes and horizontal transport vehicles from shared pools. The main languages and libraries are Python 3, Salabim, Streamlit, Plotly, Pandas, NumPy, and SciPy.

Product Testing, Validation and Evaluation

The simulation logic was verified using controlled testing procedures. Trace-based checking was performed with Salabim trace output to follow individual entities step by step and confirm correct vessel berthing, departure order, container movement, crane allocation, crane release, and horizontal transport charging behavior. Edge cases were also tested, including a vessel arriving when the quay is fully occupied, an HT battery dropping below the threshold mid-job, a quay crane failing mid-lift while carrying a container, and a train arriving when all rail tracks are occupied. KPI values were cross-checked manually for a small controlled run using known inputs and simulation monitor data. No discrepancies were found. Priority rules were also verified to confirm that the correct entity is served first when vessel, train, and truck operations compete for shared resources. The default parameter values are illustrative only and were selected to generate plausible terminal behavior for demonstration purposes. Since real terminal data was not available during development, no formal calibration or statistical validation against real terminal KPI benchmarks has yet been completed. Calibration and validation against operational data are planned for a future phase.

Product’s Internal and External Limitations/Restrictions

Internal limitations

  • Export containers are assumed to be already positioned in the yard before vessel arrival, so inland export delivery is not modelled.
  • Yard cranes retrieve and stack containers randomly within blocks; stacking tier, bay assignment, and container re-handling are not modelled.
  • All containers are treated as equivalent TEU units, without differentiation for reefer, out-of-gauge, or hazardous cargo.
  • Horizontal transport routing and internal terminal traffic are not explicitly simulated; travel time is estimated from user-defined distance matrices.

External limitations

  • Default parameters are illustrative only and should not be used for operational planning unless replaced with real terminal data.
  • CSV files for vessel, truck, and train schedules must follow the required column names and data types; otherwise, they are rejected and stochastic generators are used.
  • Results are stored in browser session memory and are lost if the page is refreshed or the session times out.
  • Large simulations with many replications, long durations, or large fleets can take several minutes to run.