Imported from TUDelft-CITG/seamulator (AGENTS.md). Install upstream with npx skills add TUDelft-CITG/seamulator. Copyright stays with the author.

Maritime Traffic Simulator - Agent Instructions

Project Goal

Build a macro-scale maritime traffic simulator with interactive visualization and simulation capabilities. The simulator aims to:

1. Visualize global maritime traffic patterns using real-time or sample data
2. Simulate vessel movements, traffic flows, and port operations at macro scale
3. Analyze maritime traffic density, routing efficiency, and congestion points
4. Support decision-making for maritime operations, port management, and logistics

Phase Objectives

Phase 1: Visualization Foundation (COMPLETE)

• Interactive map-based visualization of maritime traffic
• Sample data generation for testing and demonstration
• Basic filtering and control capabilities
• Real-time statistics display

Phase 2: Data Pipeline

• Integration with AIS (Automatic Identification System) data feeds
• Real-time data ingestion and processing
• Historical data analysis and replay
• Data validation and cleaning pipelines

Phase 3: Simulation Engine

• Vessel movement algorithms based on maritime physics
• Collision avoidance and routing logic
• Port operations simulation (docking, loading, unloading)
• Weather and sea state effects on traffic
• Traffic pattern prediction

Phase 4: Advanced Features

• Traffic density heatmaps
• Route optimization suggestions
• Congestion detection and alerts
• Integration with maritime APIs
• Multi-user collaborative viewing

Technical Stack

• Runtime: Python 3.13+
• Package Manager: uv
• Visualization: Dash + Plotly
• Data Processing: pandas, numpy
• Data Validation: pandera
• Type System: Full type hints with mypy, typing library
• Code Quality: ruff
• Routing: searoute, networkx
• Geospatial: haversine
• Logging: Python logging

Agent Guidelines

Code Style

• Follow existing style (88 char line length)
• Use type hints for all public functions
• Strong typing: Use typing library for complex types (Protocol, TypedDict, etc.) and pandera for DataFrame validation schemas
• Include docstrings for all modules, classes, and public functions
• Keep imports organized and minimal

Architecture

• Maintain clean separation: data → visualization → simulation
• Components should be reusable and testable
• Prefer composition over inheritance
• Use dependency injection for testability

Testing

• Write tests for all new functionality
• Maintain >90% test coverage for core modules
• Use pytest for test framework
• Include both unit and integration tests
• Always write tests when the user requests a new feature, while the associated tests have not been created

Code Quality

• ALWAYS run ruff check and ruff format after completing any task
• Fix all ruff linting errors before committing
• Use mypy for type checking on critical modules
• Pre-commit hooks: Setup pre-commit to run ruff check on every commit. If ruff check fails, the commit must fail
• Always run ruff format before committing to ensure consistent code formatting

Documentation

• Update docstrings when adding new functionality
• Maintain accurate type hints
• Document assumptions and limitations

Project Structure

seamulator/
├── src/seamulator/
│   ├── core/           # Core utilities (logging, etc.)
│   ├── data/           # Data models, generators, loaders
│   ├── visualization/  # All UI/visualization code
│   │   ├── components/ # Reusable UI components
│   │   └── styles/    # CSS and styling
│   └── simulation/    # Discrete event simulation engine
├── tests/              # All tests
└── docs/              # Documentation (future)

Current Status

• Phase 1: COMPLETE ✓

  • Project setup with uv and Python 3.13
  • Sample data generation (100 vessels, 8 types, 10 ports)
  • Interactive Dash app with Plotly maps
  • Vessel filtering by type
  • Statistics panel
  • 9 passing tests

• Phase 2: COMPLETE ✓

  • North Sea focus: ports and vessel spawning in North Sea region
  • Map centered on North Sea (55°N, 5°E) with zoom level 5

• Phase 3: COMPLETE ✓

  • Discrete event-time simulation engine
  • searoute library integration for maritime route calculation
  • Vessel movement along calculated paths with haversine distance
  • Vessel state: position, speed (5-15 knots), route, destination, heading
  • Simulation controls: start, pause, reset, set_speed_factor, step
  • RouteCalculator class for pathfinding between ports
  • MaritimeSimulation class with step-based advancement
  • get_vessel() and add_vessel() methods for vessel management
  • calculate_bearing() function for heading calculation
  • Vessel heading updated at each step to point to next waypoint
  • 22 passing tests including vessel movement verification

• Phase 3.5: COMPLETE ✓

  • Core utilities module with logging configuration
  • DEBUG logging added to simulation step, vessel updates, and visualization
  • TrafficMap class for efficient figure updates (no recreate_base_map on each update)
  • Simulation integrated into Dash app with Play/Pause/Step/Reset controls
  • Vessels displayed as oriented triangles based on heading
  • Real-time statistics display with simulation time and state
  • Auto-update when simulation is playing (500ms interval)

• Next: Phase 4 - Advanced Features

Quick Start

# Development
cd seamulator
uv sync
uv run python -m seamulator.visualization.app

# Testing
uv run python -m pytest tests/ -v

# Linting and Formatting
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# View logs (DEBUG level during development)
# Logs are automatically displayed in console during app execution

Workflow Requirements

After completing ANY task:

1. Run ruff check src/ tests/ - fix any errors
2. Run ruff format src/ tests/ - auto-format all files
3. Run tests to ensure nothing broke
4. Commit changes