Technical Specifications¶

Performance benchmarks, storage requirements, and technical specifications for the Nautical Graph Toolkit v0.1.5.

Test Configuration¶

• Hardware: AMD Strix Halo, 128 GB unified memory (16 GB RAM allocation for PostgreSQL)
• OS: Ubuntu 24.04 (Linux)
• Backends Tested: PostgreSQL 16+ with PostGIS, GeoPackage
• NGT Version: 0.1.5
• Routes: Los Angeles–San Francisco, LA West Coast, Key West Arrival, Miami Arrival, Galveston Arrival
• Data Sources: enc_west (US West Coast), all_enc (full US coverage)

Note on SpatiaLite: SpatiaLite backend currently supports import workflow and base graph creation. GeoPackage is recommended for most use cases due to superior performance and wider compatibility. Further SpatiaLite development is under consideration as technical difficulties are resolved.

Pipeline Overview¶

The v0.1.5 maritime workflow consists of 4 sequential stages:

Edge Count Convention: All edge counts in this document are undirected (as reported by the pipeline). Directed edge count is 2× undirected, created during Stage 3 (Weighting). Pathfinding operates on directed edges.

Interactive Visualization: See docs/notebooks/performance_metrics.ipynb for interactive Plotly charts of the same benchmark data.

Full Pipeline Performance¶

Based on 50 complete workflow runs from scripts/benchmarks/MaritimeWorkflowPerformanceMetrics.csv. Representative runs selected across the full edge count range. Values are medians of repeated runs at similar scales where applicable.

Pipeline Overview by Scale¶

6 additional runs with incomplete pipelines (missing weighting or pathfinding data) are excluded from the 56 total rows in the CSV.

Weighting & Enrichment — Backend Comparison¶

Weighting & Enrichment is the dominant pipeline cost, consuming 33–86% of total time. GeoPackage is significantly slower than PostGIS at this stage, with the gap widening at larger scales.

Comparison at ~300K Undirected Edges (~76K Nodes):

Comparison at ~1.2M Undirected Edges:

Comparison at ~1.7M Undirected Edges (~434K Nodes):

Why GeoPackage is slower at large scales: GeoPackage performs weight computation row-by-row via SpatiaLite SQL, while PostGIS uses TEMP table bulk operations and GiST-indexed spatial joins.

Why GeoPackage can be faster at small-to-medium scales (up to ~1M edges): PostGIS incurs database→system I/O overhead for every operation, while GeoPackage operates directly in the system/Python process. This overhead is amortized at large scales but dominates at smaller ones.

Comparison at ~1.37M Undirected Edges (~455K Nodes) — H3 Mode:

Weighting Sub-Steps (aggregate timing only — individual sub-step breakdown is not captured):

1. Convert to directed — Each undirected edge becomes two directed edges (2× edge count)
2. Enrich with S-57 features — Spatial join edges with ENC feature layers
3. Static weights — Three-tier penalty system: SAFE (bonus), CAUTION (penalty), DANGEROUS (blocking)
4. Directional weights — Angle-band penalties based on feature orientation (ORIENT attribute)
5. Dynamic weights — Vessel-specific constraints (draft, height, safety margins)

Pathfinding & Export¶

Pathfinding operates on the fully weighted directed graph (2× undirected edges) using AstarMaritimeSmooth, a 3-pass algorithm:

1. Pass 1 (A* scout): Fast A* on full directed graph to identify rough corridor
2. Pass 2 (Dijkstra optimizer): Dijkstra within corridor buffer (default 5.0 NM) for mathematically optimal path
3. Pass 3 (String-pulling): Replace zig-zag segments with straight lines, respecting obstacles

String-pulling produces shorter, smoother routes with fewer unnecessary waypoints.

Key Performance Observations¶

• Weighting & Enrichment dominates — 33–86% of total pipeline time (median ~59%)
• Weighting scales linearly with directed edge count across both backends
• GeoPackage outperforms PostGIS at small-to-medium scales (up to ~1M edges) because PostGIS incurs database→system I/O overhead, while GeoPackage operates directly in the system/Python process. PostGIS overcomes this overhead at large scales (3M+ edges) where its bulk TEMP table operations and GiST-indexed spatial joins dominate.
• GeoPackage weighting penalty is scale-dependent — only 1.3× slower at ~300K edges, but 3.2–3.6× slower at 1.2M+ edges with 0.2 NM precision. At 0.1 NM precision, the gap narrows to ~1.06× at ~1.27M edges, suggesting the penalty is more pronounced for coarser graphs with fewer but more complex weighting operations.
• Fine/H3 Graph Creation scales with the number of nodes/edges; PostGIS subdivision is critical (47× faster than single-process SQL)
• Pathfinding scales sub-linearly — A* corridor search limits explored edge count regardless of total graph size
• Base Graph Creation varies primarily by route extent (bounding box area), not node count alone

Fine Graph Creation Performance (Stage 2 Isolated)¶

These benchmarks measure graph creation (Stage 2) in isolation, without weighting or pathfinding. The graph creation code is unchanged from earlier versions. For full pipeline performance including weighting, see above.

Fine Graph by Spacing¶

Fine graphs use buffer-based area selection (24 NM buffer around base route) for focused high-precision routing.

Note: Examples are sliced at south boundary (slice_south_degree=37.0) for efficiency.

0.05 NM Spacing (Highest Precision)¶

0.1 NM Spacing (High Detail)¶

0.2 NM Spacing (Production)¶

H3 Hexagonal (Multi-resolution 6-11)¶

PostGIS Processing Mode — Critical Performance Difference¶

For fine graph creation, PostGIS subdivision dramatically affects performance:

• Single SQL process: ~1,499 s (extremely slow, not recommended)
• With subdivision: ~32 s (47× faster)

Fine Graph Edge Length Statistics¶

Storage Requirements¶

Test Datasets¶

ENC_SF_LA_SET (Los Angeles to San Francisco)¶

Full graph workflow test dataset covering coastal route from LA to SF. When converted, referred to as enc_west.

ENC_ROOT_UPDATE_SET¶

Contains ENC_ROOT (older version) + ENC_ROOT_UPDATE (newer version). Used for testing import and deep-test functionality.

Full NOAA ENC Catalog¶

Complete United States coastal waters dataset for production/regional analysis. Stored as all_enc schema.

Graph Storage (PostGIS)¶

Graph storage in PostGIS is reported as total size (table data + indexes) from scripts/benchmarks/graph_size.csv.

Unweighted Graph Storage¶

Weighted Graph Storage¶

Weighted graphs include directed edges (2× undirected) with 15–25 additional columns per edge (feature attributes, static/directional/dynamic weight factors, adjusted weights). Edge tables dominate storage (95%+ of total); node tables are <5%.

Weighted-to-unweighted ratio ranges from 9.5× to 14.1× depending on feature density and weight columns.

Storage Planning Guidelines¶

Guidelines account for ENC source data, unweighted graph, and weighted graph (the dominant storage consumer).

Testing & Development:

• Minimum: 2 GB free space (small fine graph + weighting)
• Recommended: 5 GB (includes ENC data + multiple small graphs)

Regional Routing (Single Route):

• Minimum: 5 GB free space (~1.2M edges, weighted)
• Recommended: 10 GB (includes base graph + fine graph + weighted + working space)

Multi-Route / Large-Scale:

• Minimum: 15 GB free space (~3.4M edges, weighted)
• Recommended: 30 GB (includes multiple weighted graphs + ENC data)

Full Production (US Coastal Waters):

• Minimum: 50 GB free space (~6.5M+ edges, weighted)
• Recommended: 100 GB (includes all_enc schema + multiple weighted graphs + indexes)

Expansion Ratios by Backend:

• GeoPackage: ~3× raw S-57 size
• SpatiaLite: ~2.5–3× raw S-57 size
• PostGIS: ~4–5× raw S-57 size (with indexes)
• Weighted graph: ~10–14× unweighted graph size (PostGIS)

Operating System Notes¶

Current Platform: Ubuntu 24.04 (Linux)¶

• Hardware: AMD Strix Halo, 128 GB unified memory
• Current RAM allocation: 32 GB (expandable to 64 GB, 96 GB for future tests)
• All benchmarks above run on Linux
• PostgreSQL/PostGIS configuration becomes critical for large weighted graphs (work_mem, maintenance_work_mem)

Future Platforms¶

• Windows 11: Benchmarks planned on same AMD Strix Halo hardware
• Cross-platform performance comparison will be added when available