Conceptual model

Conceptual Model — Asia–Europe Container Shipping Throughput

This document defines the system being modelled, the entities and resources, the events and state, and — kept deliberately separate — which assumptions are derived from the supplied data and which are introduced modelling choices. It closes with the model’s limitations.

The implementation is a genuine SimPy discrete-event simulation (container_sim/simulation.py); nothing here is a spreadsheet average.

1. System boundary

In scope. The liner service that lifts laden containers from two Asian origin ports (Shanghai CNSHA, Singapore SGSIN), sails them along a directed maritime network to the primary European import port (Rotterdam NLRTM), discharges them, and returns the vessels empty (ballast) to reload. The horizon is a 180-day planning window.

Objective (the thing we measure). Total TEU discharged at Rotterdam over the horizon, and the rate at which it is delivered.

Out of scope / boundary conditions.

• Hamburg (DEHAM) is a reachable secondary port but not the delivery objective; the service never calls there. It is a distractor sink and is excluded from routing.
• Cargo demand is treated as unlimited: a vessel always finds a full load at its origin (the operator’s objective is to maximise TEU to Rotterdam, so the binding limits are ships and ports, not cargo availability).
• Backhaul (Europe→Asia cargo) is out of scope; the return leg is ballast.

2. Entities

The fleet for a scenario is the first vessel_count rows of vessels.csv (file order alternates SGSIN/CNSHA home ports, so any prefix is a balanced split: 4/4, 6/6, 10/10).

3. Resources (the contended capacity)

A leg is treated as a contended chokepoint only if its capacity is below a threshold (100); in this network only the canal qualifies. Everything coded 999 is open water and modelled as a transit delay with no queue.

Handling rate. A port advertises berth_count and crane_count. Cranes are modelled as evenly pre-assigned to berths, so one berthed vessel is worked at (crane_count / berth_count) × moves_per_hour_per_crane TEU/h and up to berth_count vessels are served in parallel. The terminal’s aggregate discharge capacity is therefore exactly crane_count × moves_per_hour_per_crane, and cranes are never double-counted. At Rotterdam this is 4 × 28 = 112 TEU/h on the single berth (≈ 89 h to discharge 10 000 TEU).

4. Events

Per voyage, the model emits (and logs) these events:

LOAD_START → DEPART_ORIGIN → [CANAL_ENTER → CANAL_EXIT]* → ARRIVE_DEST → DISCHARGE_START → DELIVER → [canal on return]* → ARRIVE_HOME.

DELIVER carries the TEU discharged; summing DELIVER.teu over the event log reconstructs delivered throughput exactly (verified for every scenario).

5. State

• Per vessel: position in its life-cycle, laden/ballast, current TEU on board, cycle start time.
• Per resource: number of units in use / queued (SimPy-managed).
• Per replication (accumulated): list of deliveries (time, TEU), anchorage waits, origin waits, completed cycle times, and busy-hours per port and per canal leg (used to derive utilisation).

6. Routing and dispatching logic

• Routing = shortest time on the directed graph. Each leg’s free-flow time is distance_nm / min(service_speed × speed_factor, leg_max_speed). Dijkstra finds the least-time path and is recomputed per scenario, so a closed leg simply disappears. At baseline the Suez path beats the Cape path; when the canal is closed the Cape path (IOX→CAPE→WAFR→NLRTM, +3 200 nm) becomes shortest.
• Fail-clear. If no origin→Rotterdam (or return) path exists — e.g. the canal is closed and the Cape reroute is forbidden — the model raises RouteError and the scenario is recorded as failed with a reason, never as a low number.
• Dispatching = return to home port (baseline.yaml). Each vessel repeatedly serves its own origin; the tie-breaker (shortest_expected_cycle_time) is moot because each vessel has a single home port.

7. Stochasticity, seeds, and the transient

• Leg times: multiplicative lognormal noise with unit mean and cv = 0.10 (leg_time_noise_cv), applied to every leg traversal.
• Handling times: truncated normal about the mean TEU / rate, cv = 0.10, floored at 0.1 h (truncation essentially never binds at this cv).
• Seeds / reproducibility: each vessel draws from its own stream seeded by (base_random_seed, replication, vessel_index). Re-running a replication is bit-identical (python -m container_sim verify). Because all scenarios share the baseline seed, the same vessel sees the same noise across scenarios — common random numbers, which reduces the variance of scenario differences.
• Transient handling. All vessels start empty at their home port at t = 0 (a cold start). The pipeline is empty until the first vessels transit (~day 28), so we report (a) total TEU over the full horizon (what the operator receives) and (b) a post-warmup rate teu_per_day (deliveries after day 14, the scenario warmup_days) and a fully-ramped second-half rate teu_per_day_second_half. The second-half rate is the cleanest steady-state estimate.

8. Assumptions — data-derived vs introduced

8a. Derived directly from the supplied data

• Network topology, leg distances, per-leg speed limits, leg capacities and closed flags (sea_legs.csv + scenario leg_overrides).
• Vessel capacity (10 000 TEU), service speed (19 kn), laden/ballast factors (1.00), per-vessel availability, and home ports (vessels.csv).
• Berth counts, crane counts, moves/h/crane (berths.csv + berth_overrides).
• Horizon (180 d), replications (30), base seed (20260603), warmup (14 d), load ports, delivery port, routing flags, and noise cv (scenario YAML).

8b. Introduced modelling choices (with justification)

1. Vessels always sail full (10 000 TEU loaded, 10 000 discharged). The brief’s objective is to maximise TEU to Rotterdam with unlimited export demand, so the constraint is capacity, not cargo.
2. One move ≈ one TEU (stated in the B_RTM metadata) — discharge time = TEU / (cranes × moves/h).
3. Even crane-to-berth split (Section 3). Makes Rotterdam exact (112 TEU/h); at origins it splits 5 cranes over 3 berths. Aggregate port capacity is exact.
4. Capacity-constrained leg ⇔ capacity < 100 ⇒ only the canal is a queueing resource; open water is a pure delay.
5. Discharge-only destination; the return leg is ballast (factors are 1.0, so ballast speed equals laden speed here).
6. Availability → inter-voyage maintenance downtime calibrated so long-run availability equals the stated value: downtime = cycle_time × (1−A)/A (zero for A = 1).
7. Cold start at home ports at t = 0 (Section 7).
8. Draft is ignored — no leg or port in the data carries a depth limit, so the max_draft_m column is non-binding (a deliberate distractor; documented, not used).
9. The two canal directions are modelled as two independent directed resources (mirroring the two L06 rows) rather than one shared channel; at ~3 % utilisation the distinction is immaterial.

9. Limitations

• Cold-start synchronisation. Starting all vessels together produces a visible “staircase” in the cumulative-delivery curve (clustered arrivals) and a pipeline fill (~28 d) longer than the 14-day warmup. We mitigate by reporting the second-half steady-state rate; a staggered/random initial phase would smooth this but is not specified by the data.
• Low throughput variance. Delivered TEU is quantised in whole 10 000-TEU loads; at the specified cv = 0.10 the count of completed voyages is robust, so the total_teu confidence intervals are tight while cycle-time and anchorage-wait intervals are wider. This is a finding (throughput here is constraint-limited, not noise-limited), not a missing source of randomness.
• Origin dwell is conservative. The even crane-split gives a slow per-ship origin load (~7.8 d); origins nonetheless stay at 26–29 % utilisation, far from binding, so this does not affect any conclusion. Rotterdam — the binding resource — is exact under any crane-allocation convention because it has one berth.
• Unmodelled real-world stochastics (weather closures, demand seasonality, unplanned breakdowns beyond the stated availability) are out of scope; the model reflects only the variability the brief specifies.

README

Asia–Europe Container Shipping Throughput — SimPy Model

A discrete-event simulation (SimPy) of a liner service moving containers from Shanghai and Singapore to Rotterdam, used to answer the operator’s seven decision questions. The model derives routes and travel times from the directed network, treats the Suez Canal and the discharge berths as contended resources, runs 30 seeded replications per scenario, and reports throughput with 95 % confidence intervals.

Headline: the binding constraint is Rotterdam’s single discharge berth, not the canal and not the fleet. Expanding the canal is a near-no-op (+0.5 %); adding ships saturates the berth (diminishing returns, 20-day anchorage waits); adding one more crane-equipped berth at Rotterdam raises throughput +14 % with the same fleet and is the precondition for any fleet growth.

1. Install and run

Requires Python 3.10+ and the standard scientific stack.

pip install -r requirements.txt          # simpy, numpy, pandas, scipy, pyyaml, networkx, matplotlib

# from this submission directory:
python -m container_sim run               # run all scenarios -> results.csv, summary.json, event_log.csv
python -m container_sim verify            # reproducibility + event-log reconstruction self-tests
python -m container_sim figures           # render the 5 figures in figures/

# optional subset:
python -m container_sim run --scenarios baseline,canal_closed

The full run is deterministic and takes ≈ 1 second on a laptop (210 replications).

2. Routing and dispatching logic

• Routing — shortest time, derived from the graph. Every leg’s free-flow time is distance_nm / min(vessel_service_speed × speed_factor, leg_max_speed). Dijkstra (NetworkX) finds the least-time path from each origin to Rotterdam and back, and is recomputed for every scenario, so closing a leg removes it.
  • Baseline path: …→ IOX → BAB → Suez Canal → GIB → NLRTM (Suez beats Cape).
  • Canal closed: the Cape path IOX → CAPE → WAFR → NLRTM (+3 200 nm) becomes shortest and is used automatically.
• Fail-clear. If no path exists (canal closed and Cape forbidden/closed), the model raises RouteError and the scenario is recorded as failed with a reason — never as a misleadingly low throughput. (Verified: see verify and the limitation note below.)
• Dispatching — return to home port. Each vessel repeatedly loads full at its own origin, delivers to Rotterdam, and returns empty (ballast) to reload. The Suez Canal (capacity 3) is a shared convoy-slot resource held during transit; Rotterdam’s berth (capacity 1) is the discharge resource vessels queue for.

3. Key results

30 replications/scenario, 180-day horizon. total_teu = TEU discharged at Rotterdam over the horizon; vs base = ratio to baseline.

⭐ rotterdam_upgrade is my own added scenario (Section 5, Q7).

Resource utilisation at baseline (the bottleneck fingerprint):

Figures in figures/: topology.png, throughput_transient.png, fleet_saturation.png, bottleneck_utilisation.png, scenario_comparison.png.

4. Answers to the operator’s decision questions

Q1 — Baseline throughput & uncertainty. ≈ 315 000 TEU over 180 days (95 % CI 312 435–318 231, n = 30), i.e. about 31.5 full vessel-voyages. Sustained steady-state rate ≈ 1 970 TEU/day (second-half; ≈ 1 900 TEU/day counting from the 14-day warmup, which is depressed by the empty-pipeline ramp — first deliveries land ~day 28; see throughput_transient.png). The CI is tight because delivered TEU is quantised in whole 10 000-TEU loads and the completed-voyage count is robust to the specified transit/handling noise — the variability shows up in cycle time and anchorage wait, not in the count.

Q2 — Where is the binding constraint? Rotterdam’s discharge operation — one berth worked by 4 cranes (112 TEU/h, ≈ 89 h per ship). The evidence is from the model, not the labels:

• It is by far the most-utilised resource (65 % vs origins 26–29 % vs canal 3 %).
• Degrading it (port_slowdown) cuts throughput 27 % — the largest swing.
• Saturating it (fleet_large) collapses marginal returns and explodes the anchorage queue (below).
• Relieving it (rotterdam_upgrade) raises throughput 14 % with the same fleet. The famous chokepoint — the Suez Canal — is nearly idle (3 %) and is not the constraint. Reading the labels would mislead; the utilisation evidence is decisive.

Q3 — Does adding ships help, or does it saturate? It saturates. As the fleet grows 8 → 12 → 20:

• Marginal delivered TEU per added vessel falls 21 667 → 11 000.
• TEU per vessel falls 28 583 → 26 278 → 20 167 (ships get less productive).
• Mean anchorage wait rises 84 h → 157 h → 482 h — at 20 ships each vessel idles ~20 days per round trip waiting for the single berth.
• Cycle time stretches 61.6 → 66.0 → 83.2 days; RTM berth utilisation climbs 0.48 → 0.65 → 0.84. Throughput still rises (+28 % at 20 ships) but the extra ships largely queue; the fleet is running into the discharge berth (fleet_saturation.png).

Q4 — Would expanding the canal help? No — essentially no effect (+0.5 %, within noise). The canal is only ~3 % utilised at baseline, so it is not the binding resource. Adding slots (3 → 12) and speeding transit drops canal utilisation further (3.3 % → 0.5 %) and shaves a few hours off a ~25-day transit, but the Rotterdam berth — untouched — still gates the system. Canal spend buys almost nothing here.

Q5 — Sensitivity to destination discharge productivity. Very high. Halving Rotterdam’s crane rate (28 → 16 moves/h, port_slowdown) cuts throughput 27 % (315 k → 229 k), drives berth utilisation to 0.83 and the anchorage wait to 568 h. Throughput moves almost one-for-one with discharge capacity — the clearest confirmation that the discharge operation is the lever.

Q6 — Operational impact of losing the canal. ≈ −14 % (315 k → 270 k, 0.86×). The service reroutes automatically via the Cape of Good Hope (+3 200 nm each way), lengthening the cycle 66 → 78 days, cutting voyages and per-vessel delivery (26 278 → 22 528 TEU). The model does not fail, because a valid alternative exists; it only fails clearly if the Cape route is also unavailable.

Q7 — Single recommended intervention. Add a second crane-equipped deep-sea discharge berth at Rotterdam (my rotterdam_upgrade scenario: berths 1 → 2, cranes 4 → 8, fleet unchanged at 12). Evidence:

• +14.2 % throughput (315 k → 360 k) with the same ships.
• Anchorage wait collapses 157 h → 30 h; per-ship productivity rises 26 278 → 30 000 TEU (the opposite of what adding ships does).
• It is the precondition for fleet growth: with one berth, extra ships merely queue (Q3); doubling discharge capacity roughly doubles the system ceiling, so berth expansion is what makes a later fleet increase pay off. Compared with the alternatives, this beats buying 8 ships (far more capital for +28 % but each ship idles ~20 days/voyage) and dwarfs a canal upgrade (+0.5 %).

5. Output file schema

All machine-readable files use clear, conventional names — no bespoke key needed.

results.csv — one row per (scenario, replication)

summary.json — scenario-level summary + cross-scenario analysis

{
  "generated_with": "container_sim 1.0.0",
  "scenarios": {
    "<id>": {
      "scenario_id", "description", "horizon_days", "warmup_days",
      "replications", "base_random_seed", "fleet_size", "route_type",
      "deliver_to", "status",                       // "ok" or "failed" (+ "reason")
      "metrics": { "<metric>": {mean, std, sem, ci95_low, ci95_high, n}, ... }
    }, ...
  },
  "analysis": {
    "throughput_ratio_vs_baseline": { "<id>": ratio, ... },
    "fleet_marginal_teu_per_vessel": [ {from, to, delta_vessels, delta_teu, marginal_teu_per_added_vessel}, ... ],
    "teu_per_vessel_by_fleet": {...}, "anchorage_wait_h_by_fleet": {...},
    "baseline_utilisation": {...}
  }
}

Metrics carrying a 95 % CI: total_teu, teu_per_day, teu_per_day_second_half, teu_per_vessel, deliveries, mean_cycle_time_days, mean_anchorage_wait_h, mean_origin_wait_h, rtm_berth_util, util_L06_CANAL_NB, util_L06_CANAL_SB. CIs are Student-t with n−1 degrees of freedom.

event_log.csv — auditable vessel-movement trace

One row per important event, sufficient to audit movements and reconstruct delivered throughput: sum of teu over rows where event_type == "DELIVER", grouped by (scenario_id, replication), equals that replication’s total_teu (verified exactly for all scenarios).

6. Reproducibility, validation, limitations

• Reproducible: per-vessel RNG streams seeded (base_seed, replication, vessel_index); python -m container_sim verify confirms bit-identical reruns, seed independence, and event-log reconstruction. Common random numbers (shared base seed) reduce the variance of scenario comparisons.
• Warmup / transient: cold start (all vessels at home, t = 0). The pipeline fills by ~day 28, beyond the 14-day warmup_days, so we report total TEU (full horizon) and a fully-ramped second-half rate. The cumulative curve (throughput_transient.png) shows a “staircase” from synchronised first departures — a cold-start artifact, not a steady-state feature.
• Crane model: cranes split evenly across berths (aggregate port capacity exact; Rotterdam exact at 112 TEU/h). This makes origin loads conservatively slow, but origins stay at 26–29 % utilisation — non-binding — so conclusions are unaffected.
• Scope: unlimited export demand (ships always full), discharge-only destination, no backhaul, Hamburg unused (distractor), draft non-binding (no depth limits in the data). See conceptual_model.md §8–9 for the full list and the data-derived vs introduced split.