Port Digital Twin Architecture for Container Terminals: Berth Planning, Yard Optimization, Crane Telemetry and TOS Integration

A container terminal can show 65 percent berth utilisation on its monthly report and still keep ships waiting at anchor for a day, as the illustrative simulation later in this article shows. The berths are not the bottleneck; the quay cranes, the yard and the trucks feeding them are. Most dashboards cannot see that, because they report each resource in isolation. A port digital twin that models berths, cranes and yard together, fed by live operational data, can.

This matters in 2026 because the data contracts are finally settling. DCSA published Port Call Standard 2.0 in December 2025 with forecast move counts for berth planning. BSI published PAS 4000, a terminal information model sponsored by TIC 4.0, in February 2026. Telemetry from cranes, gates and vessels is no longer the hard part.

You will leave with a layered reference architecture, a terminal operating system integration pattern, a crane-telemetry event model, worked yard rehandle numbers, a runnable SimPy model with real output, KPI definitions and a failure-mode list.

What this covers: sources and standards, the reference architecture, berth allocation and quay crane scheduling, crane telemetry, yard optimization maths, discrete-event simulation, sync cadence, KPIs and what goes wrong.

Context and Background

Container terminals have been running optimisation for decades, mostly inside the terminal operating system (TOS). The TOS is the system of record for vessel stowage, yard inventory, equipment dispatch and gate transactions. Commercial products such as Navis N4, Tideworks, CyberLogitec OPUS and Kalmar’s offerings, plus in-house systems at large operators, dominate this layer. Their planning modules handle berth scheduling, yard allocation and equipment dispatch, usually with rule-based heuristics tuned by planners.

Operations research has studied the same problems in depth. Bierwirth and Meisel’s survey of berth allocation and quay crane scheduling problems, published in the European Journal of Operational Research in 2010 (vol. 202, issue 3), and their follow-up survey in 2015 (vol. 244, issue 3), catalogue hundreds of models. Imai, Nishimura and Papadimitriou formulated the dynamic berth allocation problem in Transportation Research Part B in 2001. Kim and Park published an influential quay crane scheduling method in EJOR in 2004. Very little of this literature runs inside a live terminal with calibrated, real-time inputs.

Port digital twin programmes do exist, but most work at port-authority scale rather than inside a terminal. The Port of Rotterdam described a digital twin built on sensor networks and a data lake as early as 2019, with goals ranging from port-process optimisation to autonomous shipping. Hamburg Port Authority received about EUR 520,000 in federal IHATEC II funding, announced in December 2022, for a digital-twin-based planning tool called HafenplanZen. Singapore’s Maritime and Port Authority (MPA) launched a Maritime Digital Twin in 2025, described as a test-before-you-deploy sandbox that combines vessel data, weather and simulation models. PSA’s Tuas Port, which PSA calls the world’s largest fully automated container terminal, had 14 operational berths in August 2026. PSA’s press release does not describe a terminal digital twin, so I make no claim about one.

My thesis is narrower than those programmes: inside the terminal fence, a port digital twin earns its keep by modelling the coupling between berth, crane and yard capacity, and by measuring its own forecast error. The 3D scene is optional. If you have read our warehouse digital twin architecture, the pattern will feel familiar. The physics, standards and economics differ sharply, though.

The standards picture is busy. The IMO Convention on Facilitation of International Maritime Traffic (FAL) made maritime single windows mandatory from 1 January 2024, according to the IMO’s FAL briefing. That covers ship-to-authority reporting, not terminal operations, but it pushes port communities toward digital port-call data.

Port Digital Twin Reference Architecture

Direct answer: A port digital twin for a container terminal is a calibrated, stochastic model of berths, quay cranes, horizontal transport, yard blocks and gates. It ingests TOS jobs, crane PLC telemetry, OCR gate reads, AIS positions and carrier port-call data into canonical events. It keeps a current snapshot and runs optimisation and simulation to forecast waiting time, crane productivity and truck turn time.

Figure 1: Six-layer container terminal digital twin. Sources publish events, ingestion normalises them into canonical moves, the state store keeps snapshot and history, the optimiser proposes berth and crane plans, the simulation engine stress-tests them, and the planner workbench approves what flows back to the TOS.

Read the figure top-down. Five source families feed one ingestion layer. The TOS supplies vessel visits, stowage-derived work queues, yard inventory and gate transactions. Crane programmable logic controllers (PLCs) and crane management systems (CMS) supply spreader, hoist and trolley signals. Optical character recognition (OCR) gate portals supply container and truck identifiers with images. Automatic Identification System (AIS) receivers and carrier port-call messages supply vessel positions and estimated times of arrival (ETAs). Real-time location systems (RTLS) and GNSS supply positions of straddle carriers, automated guided vehicles (AGVs) and internal trucks.

Ingestion turns all of that into one event vocabulary. The state store holds history, the current snapshot and master data such as quay geometry, crane outreach limits and yard block layouts. The optimiser and the simulation engine both read from the snapshot. Only the planner workbench writes back to the TOS, and only after a human approves.

Source systems and the standards each one speaks

Each source has its own protocol and its own idea of truth. Getting these mappings right is most of the integration effort.

Between terminal and shipping line, UN/EDIFACT messages still carry the operational load. The Ship Message Design Group (SMDG) maintains the implementation guides. BAPLIE describes the bay plan, meaning what sits in which slot on the vessel. MOVINS carries stowage instructions. COPRAR is the loading or discharge order, and COARRI confirms what was actually discharged and loaded. CODECO confirms gate-in and gate-out events. SMDG lists COPRAR, COARRI, COPARN and CODECO at version 2.1.3 on directory D.00B, with older 1.6.2 guides on D.95B. For a twin, COARRI and CODECO are ground truth for vessel and gate moves. BAPLIE gives the work content before the ship arrives.

The Digital Container Shipping Association (DCSA) is pushing APIs alongside EDI. Its Port Call Standard 2.0, announced on 18 December 2025, supersedes the Just-in-Time Port Call 1.2 Beta standard. DCSA says 2.0 simplifies the API structure and adds forecast units to move or restow, which users had flagged as missing for berth planning. DCSA Track & Trace 3.0.0, announced in early October 2026, adds IoT and reefer events to the shipment, transport and equipment events of version 2.2.0. DCSA says it goes to members first, with public release planned for the second half of 2027.

AIS follows ITU-R Recommendation M.1371-5. Per the US Coast Guard Navigation Center, Class A transponders send position reports (message types 1, 2 and 3) every 2 to 10 seconds underway and every 3 minutes at anchor. Static and voyage data, including the crew-entered destination and ETA, travel in message type 5 every 6 minutes. The crew-entered ETA is notoriously stale, so treat it as a weak prior, not a measurement.

Inside the terminal, crane and equipment data has historically been vendor-specific. TIC 4.0, the Terminal Industry Committee 4.0, has spent several years defining a semantic vocabulary for cargo-handling equipment and processes. BSI published PAS 4000 on 23 February 2026, sponsored by TIC 4.0. It defines semantic elements, including subject, concept, observed property and payload, so that a statement such as “this crane’s spreader is locked” means the same thing in any messaging protocol. Release 2026.019 of the TIC 4.0 definitions adds an Equivalent Moves Per Hour (EMPH) KPI that normalises quay crane productivity by crane size. Adopting this vocabulary in your canonical event model is cheap insurance against vendor lock-in.

The canonical event model: moves, not messages

The core design decision is the event vocabulary. I recommend one central fact, the container move, plus a few supporting events. A move has a container identifier, a from-position, a to-position, a handling equipment identifier, an event time, an ingestion time and a TOS work-instruction reference. Positions use one location grammar for vessel slots (bay, row, tier), yard slots (block, bay, row, tier), transfer points and gate lanes.

Supporting events cover what moves cannot: VesselArrivedAnchorage, AllFast, FirstLift, LastLift, LinesOff, EquipmentStateChanged, DelayStarted, DelayEnded, GateTransaction, TruckPositionObserved and PlanChanged. PlanChanged matters more than it looks. When planners re-sequence a work queue, the twin must record the old and new plan so it can later separate plan error from execution error.

Every event carries two timestamps. Crane edge gateways buffer during network drops, OCR portals batch images and TOS confirmations lag reality. Order by event time, apply a watermark before closing a window, and keep the ingestion time for diagnosing pipeline lag. Our deep dive on event-time alignment and late-arriving data in digital twins covers watermark sizing in detail.

Optimiser plus simulator, not optimiser versus simulator

Berth allocation and crane assignment are optimisation problems; uncertainty is a simulation problem. A port digital twin needs both. The optimiser proposes a small set of candidate plans, typically three to ten. The discrete-event simulation (DES) engine then runs each candidate through a few hundred stochastic replications with fitted distributions for arrival deviation, crane cycle time and truck supply. The result is a distribution of outcomes per plan, not a single number.

This split exists because deterministic optimisers are brittle. A plan that is optimal when every ship arrives on time and every crane hits its nominal rate can fail badly when one ship is six hours late. Simulation exposes that fragility. The decision rule then becomes something like “minimise expected weighted waiting time, subject to the 90th-percentile berth overrun staying under four hours.” If you are still choosing between a pure simulation model and a live twin, our digital twin versus simulation architecture decision guide lays out the criteria.

Deeper Analysis: Berth Allocation, Crane Telemetry and Yard Optimization in the Twin

This section walks through the four engines that make a container terminal digital twin useful: berth allocation, crane telemetry, yard optimization and simulation. Each one has a mechanism you can test and a number you can check.

Berth allocation and quay crane scheduling as the twin sees them

The berth allocation problem (BAP) assigns each vessel a berthing position and a berthing time. In the continuous variant, the quay is a line and a ship can moor anywhere it fits. In the discrete variant, the quay is split into fixed berths. The dynamic version, formulated by Imai and colleagues in 2001, lets ships arrive during the planning horizon rather than all being present at the start. A typical objective minimises weighted service time, which is waiting plus handling, with weights reflecting service contracts or vessel priority.

The quay crane assignment and scheduling problems sit on top. Assignment decides how many cranes each ship gets over time. Scheduling decides which crane works which bay, in which order, without cranes crossing on the shared rail and while keeping safety clearance. Bierwirth and Meisel’s surveys show how tightly coupled these are. Handling time depends on crane count, and crane count depends on what the neighbouring ships need.

The twin changes this problem in two ways. First, it supplies inputs as distributions rather than point values. Arrival time is no longer a published ETA but a predicted distribution, built from AIS track, carrier port-call messages and the vessel’s own history of punctuality. Handling time is not “moves divided by nominal rate” but a distribution fitted from crane telemetry for that vessel class, that crane pool and that hatch-cover configuration.

Second, it closes the loop in time. When an inbound vessel’s predicted ETA moves by more than a threshold, the twin re-solves and alerts the planner. It does not wait for the next planning meeting. Figure 2 shows the exchange.

Figure 2: Berth allocation loop in a just-in-time port call. The carrier sends ETA and move forecasts, AIS supplies continuous positions, the twin predicts arrival and handling time, the planner commits a plan in the TOS, and ETA drift triggers a re-plan.

The sequence starts with the carrier’s port-call message carrying ETA and, under DCSA Port Call 2.0, forecast moves. AIS adds positions every few seconds. The twin turns those into an arrival prediction and a handling-time prediction, then offers the planner a few berth windows with their risk. Once committed, the TOS or port community system sends a requested time of arrival back. The IMO’s Just In Time Arrival Guide describes this exchange of requested and confirmed times as a way to let ships slow-steam rather than hurry up and wait.

A practical solver approach is a rolling-horizon heuristic, not an exact mixed-integer programme over a month. Re-solve a 72-hour window every time a material event arrives, fix decisions inside the next few hours, and leave the rest flexible. Exact MIP formulations from the literature are useful for benchmarking the heuristic offline, not for running every five minutes.

Crane telemetry: deriving moves and delays from PLC signals

Quay crane productivity is the terminal’s heartbeat, and the TOS often measures it badly. TOS move confirmations arrive when a clerk or automation confirms the job. That may be seconds or minutes after the box actually landed. Delays are often captured by hand, with free-text reasons, if at all. Crane PLC signals fix both problems.

Figure 3: Crane telemetry pipeline. PLC signals pass through an edge gateway into a move state machine, which is joined with TOS work instructions to produce confirmed moves, while gaps between moves are classified as delays for KPI calculation.

The building blocks are a handful of signals most ship-to-shore (STS) cranes already expose: twistlock locked and unlocked, spreader landed, load-cell weight, hoist position and trolley position. An edge gateway timestamps and buffers them, then forwards them over OPC UA, MQTT or the vendor’s CMS interface. A state machine reconstructs each cycle: unlocked and landed, locked, lifted, travelling, landed, unlocked. One full cycle is one move, with an exact event time and a measured weight.

The join with the TOS is where identity comes from. The crane knows a box moved from a vessel slot to a transfer point, but not which box. The TOS work instruction knows which box was planned for that crane and position. Joining on crane, approximate time and position gives a confirmed move with both physical and logical truth. Unmatched cycles are signals in themselves. They usually mean a hatch cover, a restow or a TOS confirmation error.

Gaps between cycles become delays. A classifier labels them using context: no truck under the crane (horizontal transport starvation), hatch-cover handling, crane breakdown from the CMS alarm stream, shift change or lashing. This is where the port digital twin starts paying for itself. A gross crane rate of 25 moves per hour tells you little. Knowing that 18 percent of crane time went to waiting for trucks tells you to fix the yard and transport side, not to buy cranes. That 18 percent is an illustrative figure, not a benchmark.

Yard optimization: worked rehandle arithmetic

The yard is where container terminal efficiency quietly leaks. A rehandle, also called a shuffle or unproductive move, happens when a container must be moved to reach one beneath it. Every rehandle costs yard crane time and, at the vessel, can starve a quay crane.

The core decision is stacking: where to put each arriving box so that it can leave with few rehandles. The ideal is to stack boxes in reverse departure order, with the earliest leaver on top. The obstacle is information. Import boxes leave when a trucker arrives, which the terminal learns late. Export boxes leave in stowage sequence, which is only fixed when the stowage plan is final.

The port digital twin’s contribution is a dwell-time and departure prediction per box, fed by booking data, truck appointments, customs status and history. To show why accuracy matters, here is a small Monte Carlo model. It is deliberately simple, and its numbers are illustrative, not measurements from any terminal.

import random

def rehandles(stack_order):
    """stack_order: true retrieval ranks from bottom to top. Blocking boxes are
    relocated to another stack (counted once) when a box below them is needed."""
    stack, moves = list(stack_order), 0
    for target in sorted(stack_order):
        if target not in stack:
            continue                      # already relocated earlier, retrieved elsewhere
        idx = stack.index(target)
        moves += len(stack) - idx - 1     # boxes above must be moved first
        stack = stack[:idx]               # target leaves, blockers relocated
    return moves

def trial(height, noise_h, rng):
    true_dep = [rng.uniform(0, 120) for _ in range(height)]     # departure hour
    predicted = [d + rng.gauss(0, noise_h) for d in true_dep]
    rank = {i: r for r, i in enumerate(sorted(range(height), key=lambda i: true_dep[i]))}
    # stack so predicted-earliest is on top: bottom = latest predicted
    order = sorted(range(height), key=lambda i: -predicted[i])
    return rehandles([rank[i] for i in order])

rng = random.Random(7)
N = 20000
for h in (4, 5, 6):
    rand = sum(rehandles(rng.sample(range(h), h)) for _ in range(N)) / N
    row = [f"tiers={h} random={rand/h:.2f}"]
    for noise in (48, 24, 8):
        r = sum(trial(h, noise, rng) for _ in range(N)) / N
        row.append(f"noise{noise}h={r/h:.2f}")
    print("  ".join(row), "(rehandles per retrieved box)")

Output on Python 3 with the seed shown:

tiers=4 random=0.48  noise48h=0.33  noise24h=0.23  noise8h=0.10 (rehandles per retrieved box)
tiers=5 random=0.54  noise48h=0.39  noise24h=0.28  noise8h=0.13 (rehandles per retrieved box)
tiers=6 random=0.59  noise48h=0.44  noise24h=0.33  noise8h=0.16 (rehandles per retrieved box)

The model assumes departures spread uniformly over five days, one stack at a time, and blockers relocated once to another stack. Real yards are messier. The direction of the result is robust, though. With random stacking in five-tier stacks, roughly one box in two causes a rehandle. With a departure predictor accurate to about a day, that falls by about half. With an eight-hour predictor, it falls by about three-quarters.

Turn that into yard crane hours. Suppose, illustratively, a terminal retrieves 4,000 import boxes a day from five-tier blocks and a rehandle takes 90 seconds of yard crane time. At 0.54 rehandles per box, that is about 2,160 rehandles, or 54 crane-hours a day. At 0.28, it drops to about 1,120 rehandles, or 28 crane-hours. The saving is roughly one yard crane running around the clock. Whether that is worth a prediction model depends on your crane count and labour costs, which only your data can answer.

Tier height is the other lever, and it is a trade-off. Higher stacks hold more boxes per ground slot but cost more rehandles, as the random column shows. A twin can evaluate stacking-height policies per block against forecast yard occupancy rather than fixing one height for the whole terminal.

Discrete-event simulation: a runnable berth and crane model

Analytical queueing models break down quickly here because berths and cranes are coupled resources. A ship needs a berth and a crane gang at the same time, and its handling time depends on how many cranes it gets. Discrete-event simulation handles that coupling naturally. The model below uses SimPy 4.1.2, the current release on PyPI, published on 24 May 2026. It models three discrete berths and a shared pool of quay cranes.

import random, statistics as st
import simpy

# Illustrative parameters -- replace with values fitted from your TOS history
BERTHS = 3                 # discrete berth positions on the quay
SIM_DAYS = 28
MEAN_INTERARRIVAL_H = 11.0  # vessel arrivals, exponential
MOVES = (900, 2600)        # container moves per call, uniform range
GCR_MEAN = 28.0            # gross crane rate, moves per crane-hour
GCR_CV = 0.35              # variability of per-move cycle time
OVERHEAD_H = 2.5           # mooring, lashing, gangway, unmooring

def cranes_for(moves):
    return 2 if moves < 1400 else 3 if moves < 2100 else 4

def crane_work(env, moves, rng):
    """One quay crane working its share of a vessel's moves."""
    mean_s = 3600.0 / GCR_MEAN
    shape = 1 / GCR_CV ** 2                  # gamma shape from coefficient of variation
    for _ in range(moves):
        yield env.timeout(rng.gammavariate(shape, mean_s / shape) / 3600.0)

def vessel(env, name, berths, qc_pool, rng, log):
    arrive = env.now
    moves = rng.randint(*MOVES)
    k = cranes_for(moves)
    with berths.request() as berth:
        yield berth
        yield qc_pool.get(k)                 # wait until k cranes are free
        start = env.now
        yield env.timeout(OVERHEAD_H / 2)
        share = [moves // k + (1 if i < moves % k else 0) for i in range(k)]
        yield env.all_of([env.process(crane_work(env, s, rng)) for s in share])
        yield qc_pool.put(k)
        yield env.timeout(OVERHEAD_H / 2)
        log.append(dict(wait=start - arrive, at_berth=env.now - start,
                        moves=moves, cranes=k))

def source(env, berths, qc_pool, rng, log):
    i = 0
    while True:
        yield env.timeout(rng.expovariate(1 / MEAN_INTERARRIVAL_H))
        i += 1
        env.process(vessel(env, f"V{i}", berths, qc_pool, rng, log))

def run(n_cranes, seed):
    rng = random.Random(seed)
    env = simpy.Environment()
    berths = simpy.Resource(env, capacity=BERTHS)
    qc_pool = simpy.Container(env, capacity=n_cranes, init=n_cranes)
    log = []
    env.process(source(env, berths, qc_pool, rng, log))
    env.run(until=SIM_DAYS * 24)
    waits = sorted(v["wait"] for v in log)
    berth_hours = sum(v["at_berth"] for v in log)
    return dict(
        calls=len(log),
        mean_wait=st.mean(waits),
        p90_wait=waits[int(0.9 * len(waits))],
        berth_util=berth_hours / (BERTHS * SIM_DAYS * 24),
        berth_prod=sum(v["moves"] for v in log) / berth_hours,
    )

if __name__ == "__main__":
    for n in (8, 9, 10):
        reps = [run(n, seed) for seed in range(30)]
        agg = {k: st.mean(r[k] for r in reps) for k in reps[0]}
        print(f"QCs={n:2d} calls={agg['calls']:.0f} mean_wait_h={agg['mean_wait']:.1f} "
              f"p90_wait_h={agg['p90_wait']:.1f} berth_util={agg['berth_util']:.0%} "
              f"berth_moves_per_h={agg['berth_prod']:.0f}")

Every parameter is illustrative. Arrivals are Poisson, with a mean of one vessel every 11 hours. Each call has 900 to 2,600 moves and receives two to four cranes depending on size. Per-move cycle times are gamma-distributed around a mean gross crane rate of 28 moves per crane-hour. A ship holds its berth while waiting for cranes, which is realistic: once moored, it occupies quay length whether or not it is being worked. Output on SimPy 4.1.2, averaged over 30 replications of 28 days:

QCs= 8 calls=57 mean_wait_h=22.5 p90_wait_h=52.3 berth_util=66% berth_moves_per_h=75
QCs= 9 calls=58 mean_wait_h=16.9 p90_wait_h=39.2 berth_util=68% berth_moves_per_h=74
QCs=10 calls=58 mean_wait_h=7.7 p90_wait_h=21.9 berth_util=67% berth_moves_per_h=75

Here berth_util counts only time a ship is being worked, and mean_wait_h counts time from arrival until cranes are assigned. The result is the opening paradox in numbers. Productive berth utilisation stays near two-thirds in every scenario, so a berth-only dashboard says capacity is fine. Yet with eight cranes, ships wait almost a day on average and over two days at the 90th percentile. Two more cranes, or the same effect from redeploying cranes faster between berths, cut mean waiting by about two-thirds. The binding constraint is the crane pool, not quay length.

Three cautions apply. First, 30 replications of 28 days give stable means but wide tails; report confidence intervals before acting. Second, the model starts empty, so the first days understate congestion; production models discard a warm-up period. Third, crane assignment here is greedy and first-come-first-served, so a real berth plan would do better. That is the point of pairing it with an optimiser.

KPIs the twin must compute consistently

KPI definitions vary between terminals, carriers and consultants. That is why TIC 4.0 is standardising them, and why your twin must pin them down in code.

KPI	Common definition	Primary source in the twin
Gross crane rate (GCR)	Moves divided by crane working time, from first to last lift, including operational delays	Crane state machine plus TOS moves
Net crane rate	Moves divided by crane time excluding delays not attributable to the crane	Delay classifier output
Berth productivity	Moves divided by time at berth, usually all-fast to lines-off	AIS or mooring events plus moves
Vessel waiting time	Anchorage arrival to all-fast, minus waiting the carrier requested	AIS geofences plus port-call data
Truck turn time	Gate-in to gate-out at the OCR portals	OCR gate events, CODECO
Rehandle ratio	Unproductive yard moves divided by productive yard moves	Yard crane moves joined with TOS
EMPH	TIC 4.0 KPI normalising STS productivity to a reference crane size	Crane master data plus moves

Each row uses the most direct physical source available, with the TOS as fallback and reconciliation partner. Store the definition version with each computed value. When finance and operations argue about last quarter’s GCR, you need to show which formula produced it.

Sync cadence: match it to the decision

Not every layer of a port digital twin needs real time. Crane state for delay classification needs second-level resolution at the edge, but the twin can consume aggregated cycles. Berth re-planning needs updates whenever an ETA moves materially, which in practice means AIS-driven predictions refreshed every few minutes. Yard stacking decisions happen per box at gate-in, so departure predictions must be ready when the truck reaches the OCR portal. Tactical studies, such as adding cranes or changing stacking height, need only historical extracts. Faster sync than the decision requires adds cost and inconsistency without improving outcomes.

Trade-offs, Gotchas, and What Goes Wrong

The biggest risk in a port digital twin is not a wrong model. It is a confidently wrong model that someone acts on. Figure 4 shows the guardrail loop I recommend before any recommendation reaches the TOS.

Figure 4: Write-back guardrail. A twin recommendation passes a snapshot freshness check and a feasibility check before planner review. Approved plans go to the TOS, outcomes are observed and scored, and forecast error drives recalibration. Failed checks fall back to the TOS plan with an alert.

TOS integration is the long pole. Most TOS products were not built to publish events. Teams end up with a mix of vendor APIs, EDI copies, database change data capture and scheduled exports. Change data capture on a TOS database is powerful but fragile, because schema changes during upgrades silently break it. Negotiate a supported integration path with the TOS vendor early. Budget more time for it than for the simulation model.

Stale snapshots produce plausible nonsense. If the gate feed drops for 20 minutes, the yard snapshot looks normal but is wrong. The simulation will run happily and produce a clean forecast. Every snapshot must carry per-source freshness and completeness, and the twin must refuse to recommend when a critical source is stale. That is the first diamond in Figure 4.

ETA data is biased, not just noisy. Crew-entered AIS ETAs often lag reality, and some carriers systematically report optimistic ETAs. A naive model averaging these will be wrong in a consistent direction. Fit a correction per carrier or service, and prefer track-based predictions once a vessel is within a few hours.

Crane telemetry is easy to misread. Twistlock signals bounce, load cells drift and hatch-cover lifts look like container moves. Without the TOS join, your move count will be wrong by a few percent. That is enough to distort GCR comparisons between cranes or shifts. Validate the state machine against manual counts on sample shifts before trusting any productivity number.

Optimisers ignore unwritten rules. Planners know that a given crane is unreliable in high wind, that a certain carrier needs a specific berth for its gangway, or that two services must not overlap. If these constraints are not encoded, the optimiser proposes infeasible plans and planners stop trusting the tool within weeks. Capture rejection reasons in the workbench and turn them into constraints.

Calibration drift is silent. A port digital twin ages faster than its dashboards suggest. Crane rates change after maintenance, new vessel classes have different hatch layouts, and yard layouts change. A model fitted last year can drift without anyone noticing. Score every forecast against actuals, track error by horizon, and trigger recalibration when error crosses a threshold. Our guide to digital twin verification, validation and uncertainty quantification covers the method.

Cyber and safety boundaries are real. Crane PLCs sit in operational technology networks. Read telemetry through a one-way path or a hardened gateway in an industrial DMZ, never by opening the PLC network to the analytics cloud. The twin should never write directly to crane control systems.

Practical Recommendations

Start with measurement, not optimisation. A port digital twin that reports true crane productivity, delay causes and vessel waiting time, all from physical signals, delivers value within months. It also builds the data foundation and credibility that optimisation needs later. Teams that start with a berth optimiser on top of unreliable TOS data usually stall.

Pick one decision to improve first. Berth re-planning on ETA drift is a good candidate because the inputs are external and the benefit is visible. Yard stacking is a good second candidate because the rehandle arithmetic above makes the business case easy to quantify. Keep the 3D visual layer for last, if at all. For a large terminal, a tiled 3D scene is a solved problem, as our post on large-scale digital twin visualization shows. It does not answer the operational question.

Treat standards as your interface contract. Model moves and equipment states using the TIC 4.0 and PAS 4000 vocabulary, and consume vessel calls through DCSA Port Call where carriers support it. You will swap TOS products, crane vendors and analytics platforms over a twin’s life; the vocabulary should outlast them.

A starting checklist:

Define the canonical move event, location grammar and two-timestamp rule before writing any pipeline.
Agree a supported TOS integration path with the vendor in writing.
Build the crane state machine and validate it against manual counts.
Publish GCR, net rate, berth productivity, waiting time and truck turn time with versioned definitions.
Fit arrival, handling-time and dwell distributions from at least several months of history.
Run the simulation in shadow mode and score forecasts for weeks before any write-back.
Add freshness checks and a planner approval step for every recommendation.

Frequently Asked Questions

What is a port digital twin?

A port digital twin is a virtual model of a port or terminal that is continuously updated with operational data and can be run forward to predict outcomes. At port-authority scale, it often covers vessel traffic, nautical services and infrastructure. Inside a container terminal, it models berths, quay cranes, horizontal transport, yard blocks and gates. Its value comes from answering forward-looking questions, such as how long a ship will wait or how many cranes a call needs, with quantified uncertainty. A 3D visual model without live data and forecasting is not a twin.

How does a container terminal digital twin integrate with the TOS?

The TOS remains the system of record and execution. The twin reads vessel visits, work instructions, yard inventory and gate transactions through vendor APIs, EDI copies such as COARRI and CODECO, change data capture or scheduled exports. It converts them into canonical move events with event timestamps. Integration should start read-only. Writing recommendations back, such as a revised berth plan, should go through a supported vendor interface, after freshness and feasibility checks and planner approval. Direct database writes into a TOS are an anti-pattern.

What is the berth allocation problem?

The berth allocation problem assigns each arriving vessel a berthing position and time along the quay, usually to minimise total waiting and handling time. It comes in discrete versions, with fixed berths, and continuous versions, where ships can moor anywhere along the quay line. The dynamic version allows ships to arrive during the planning horizon. It is closely coupled with quay crane assignment and scheduling, because handling time depends on how many cranes a ship receives. Bierwirth and Meisel’s 2010 and 2015 surveys in the European Journal of Operational Research are standard references.

How does yard optimization reduce rehandles?

Rehandles happen when a container must be moved to reach one beneath it. Yard optimization reduces them by stacking boxes so that early leavers sit on top. The difficulty is knowing departure times, especially for imports collected by truck. A digital twin predicts dwell and departure from bookings, truck appointments, customs status and history. In the illustrative Monte Carlo model in this article, a departure predictor with about one day of error roughly halves rehandles compared with random stacking. Results in a real yard depend on block layout and data quality.

Which KPIs should a port digital twin track?

The core set is gross crane rate, net crane rate, berth productivity, vessel waiting time, truck turn time and the yard rehandle ratio. Definitions vary between terminals, so encode each formula in code and store its version with every value. Derive crane KPIs from PLC telemetry joined with TOS moves rather than from TOS confirmations alone, because confirmation timing can lag reality. TIC 4.0 is publishing standard KPI definitions, including Equivalent Moves Per Hour, which normalises quay crane productivity by crane size.

Is SimPy suitable for a container terminal simulation?

SimPy is a mature, process-based discrete-event simulation library for Python, and version 4.1.2 was released in May 2026. It suits lean operational models of berths, crane pools and yard flows that run inside a data platform, are version-controlled and are unit-tested. It has no built-in animation, equipment libraries or experiment manager, so detailed engineering studies often use commercial simulation suites. Many teams combine both: commercial tools for design, and SimPy-style code models for daily forecasting inside the twin.

Container Terminal Digital Twin Architecture: Berth Planning, Yard Optimization, Crane Telemetry and TOS Integration (2026)