CORALL is a novel framework that integrates Large Language Models with real-time risk assessment for autonomous maritime navigation. The system combines LLM-based decision-making with traditional motion planning to enable COLREGs-compliant collision avoidance in autonomous surface vessels.

This repository contains the complete implementation of the CORALL framework as published in our research paper, providing researchers and practitioners with a comprehensive tool for studying LLM-guided autonomous maritime navigation.

• LLM-based COLREGs Interpretation: Advanced decision-making using OpenAI GPT and Claude models
• Real-time Risk Assessment: DCPA/TCPA calculations and comprehensive risk metrics
• Multi-vessel Encounter Handling: Complex scenarios with multiple target vessels
• Explainable Navigation Decisions: Transparent reasoning for autonomous maneuvers
• Standardized Test Scenarios: Validation across 22 Imazu test scenarios
• Dynamic Path Planning: Intelligent waypoint navigation and trajectory optimization
• Vessel Dynamics Simulation: Realistic modeling of marine vessel movement and control
• Comparison Mode: Side-by-side analysis of LLM vs baseline navigation decisions
• Real-time Animation: Interactive visualization of vessel movements and decisions
• Modular Architecture: Clean, extensible codebase with clear separation of concerns

CORALL/
├── main.py                 # Main entry point
├── requirements.txt        # Python dependencies
├── setup.py               # Package installation
├── README.md              # This file
├── .gitignore            # Git ignore rules
│
├── src/                   # Source code
│   ├── core/             # Core simulation components
│   │   ├── simulation.py # Main simulation loop
│   │   └── integration.py # Numerical integration
│   │
│   ├── dynamics/         # Vessel dynamics and control
│   │   ├── vessel_dynamics.py
│   │   ├── controller.py
│   │   └── actuator_modeling.py
│   │
│   ├── navigation/       # Navigation and path planning
│   │   ├── planning.py
│   │   ├── obstacle_sim.py
│   │   └── reactive_avoidance.py
│   │
│   ├── risk_assessment/  # Risk and collision analysis
│   │   ├── cpa_calculations.py
│   │   ├── cpa_calculations_0speed.py
│   │   ├── cpa_calculations2.py
│   │   └── risk_calculations.py
│   │
│   ├── decision_making/  # Autonomous decision systems
│   │   ├── decision_making.py
│   │   ├── decision_makingllm.py
│   │   └── decision_makingllm1.py
│   │
│   ├── visualization/    # Rendering and animation
│   │   ├── animate.py
│   │   ├── rendering.py
│   │   └── save_animation.py
│   │
│   └── utils/           # Utilities and helpers
│       ├── imazu_cases.py
│       └── validation.py
│
├── tests/              
├── docs/                # Documentation   
├── config/              # Configuration files
└── img/                 # Output images and animations

• Python 3.8 or higher
• pip package manager
• OpenAI API key (get from: https://platform.openai.com/api-keys)
• Claude API key (get from: https://console.anthropic.com/)
• Internet connection for LLM API calls

1. Clone the repository:

git clone https://github.com/Klins101/CORALL
cd CORALL

2. Create a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up API keys and configuration:

Create a .env file in the root directory with your API keys:

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key-here
OPENAI_MODEL=gpt-4
OPENAI_TEMPERATURE=0.1
OPENAI_MAX_TOKENS=50

# Claude Configuration  
CLAUDE_API_KEY=your-claude-api-key-here
CLAUDE_MODEL=claude-sonnet-4-20250514
CLAUDE_TEMPERATURE=0.1

# Default LLM Provider
LLM_PROVIDER=openai

Note: The .env file is not included in the repository for security reasons. You must create it yourself with your own API keys.

5. Run a simulation:

python main.py

Run the default simulation (Case 1):

python main.py

python main.py [OPTIONS]

Options:
  --case_number INT    Simulation scenario (default: 1)
  --sim_time FLOAT     Simulation duration in seconds (default: 450.0)
  --dt FLOAT           Time step size (default: 0.1)
  --no_animation       Disable real-time animation
  --output_dir PATH    Output directory for results (default: img/)
  --llm INT           Enable LLM decision making (0=off, 1=on, default: 0)
  --llm_provider STR   LLM provider (openai, claude)
  --compare            Run comparison between LLM and baseline simulation

1. Run Case 2 with extended simulation time:

python main.py --case_number 2 --sim_time 600

2. Quick simulation without animation:

python main.py --no_animation --sim_time 300

3. Run with LLM-based decision making:

python main.py --llm 1 --case_number 3

4. Custom output directory:

python main.py --output_dir results/experiment1/

5. Run LLM vs Baseline comparison:

python main.py --compare --llm_provider claude --case_number 1
python main.py --compare --llm_provider openai --case_number 2

The system includes several predefined test scenarios (Imazu cases) that represent common marine navigation situations:

• Case 1: Head-on encounter
• Case 2: Crossing situation
• Case 3: Overtaking scenario
• Case 4: Multiple vessel encounter
• Case 5-23: Various complex scenarios

Each simulation run generates:

1. Animation: scenario_animation{case_number}.gif

   • Real-time visualization of vessel movements
   • Obstacle positions and trajectories
   • Risk zones and avoidance maneuvers

2. Analysis Plots: plot_dcpa_tcpa_risk_{case_number}.png

   • DCPA (Distance at Closest Point of Approach)
   • TCPA (Time to Closest Point of Approach)
   • Distance to obstacles over time
   • Risk metrics evolution

3. Simulation Results: simulation_result{case_number}.png

   • Final vessel trajectories
   • Waypoint achievements
   • Collision avoidance paths

When using --compare flag, additional files are generated:

1. Kdir Comparison: kdir_comparison_{provider}_case_{number}.png

   • Side-by-side comparison of turn decisions
   • Baseline vs LLM steering commands
   • Statistical analysis of navigation behavior

2. Trajectory Comparison: trajectory_comparison_{provider}_case_{number}.png

   • Overlay of vessel paths (baseline vs LLM)
   • Start/end positions and obstacle locations
   • Visual comparison of navigation efficiency

3. Summary Report: comparison_summary_{provider}_case_{number}.txt

   • Quantitative comparison statistics
   • Turn frequency and risk management analysis
   • Performance metrics and behavioral insights

Important Security Notes:

• Never commit your .env file to version control
• Keep your API keys secure and do not share them publicly
• The .env file is already included in .gitignore for security
• API keys are loaded automatically when the simulation starts
• You can switch between providers using the LLM_PROVIDER environment variable

You can customize LLM behavior by modifying the environment variables:

# Adjust response length (max 100 characters recommended)
OPENAI_MAX_TOKENS=INT
CLAUDE_MAX_TOKENS=INT

# Adjust creativity (0.0 = deterministic, 1.0 = creative)
OPENAI_TEMPERATURE=0.1
CLAUDE_TEMPERATURE=0.1

# Switch between models
OPENAI_MODEL=gpt-gpt-4
CLAUDE_MODEL=claude-sonnet-4-20250514

You can customize the LLM prompt template to implement your own COLREGs interpretation or navigation logic. The prompt template is located in:

src/decision_making/multi_llm_decision.py

To modify the prompt:

1. Edit the system prompt in the MultiLLMCOLREGSInterpreter class (around line 131):

self.system_prompt = """You are a ship navigation officer. Make COLREGs-compliant decisions..."""

2. Customize for your needs:

   • Add specific COLREGs rules you want to emphasize
   • Modify the response format if needed
   • Adjust the character limit (but keep responses concise)
   • Add domain-specific knowledge or constraints

3. Example custom prompt:

self.system_prompt = """You are an expert maritime navigator with 20 years experience.
Follow IMO COLREGs strictly. Consider vessel types, weather, and traffic density.

Response format:
- "turn starboard" - right turn per Rule 14/15
- "turn port" - left turn per Rule 16/17  
- "stand on" - maintain course per Rule 13/17
"""

4. Response parsing: If you change the response format, also update the extract_kdir_from_response() function in the same file to properly parse your custom responses.

Note: Keep responses under 50 characters for optimal performance and ensure they can be parsed by the extract_kdir_from_response() function.

Modify vessel characteristics in the simulation:

• Length Overall (LOA)
• Beam Overall (BOL)
• Maximum speed
• Turning rates

Adjust control system settings:

• PID controller gains
• Sampling time
• Actuation limits

Configure safety parameters:

• Minimum safe distance
• Risk assessment weights
• COLREGs compliance levels

from src.core.simulation import run_simulation
from src.dynamics.vessel_dynamics import vessel_dynamics
from src.navigation.planning import waypoint_selection
from src.risk_assessment.cpa_calculations import cpa_calculations

Create custom simulation scenarios:

from src.core.simulation import run_simulation
import numpy as np

# Define custom waypoints
waypoints = np.array([[100, 200], [300, 400], [500, 300]])

# Run simulation with custom parameters
run_simulation(
    case_number=23,
    waypoints=waypoints,
    sim_time=600.0,
    dt=0.1
)

Here are some example simulations demonstrating CORALL's performance across different encounter types:

Crossing encounter showing LLM-guided starboard turn decision

Complex scenario handling Head-on vessel while managing crossing vessel

Three-vessel encounter demonstrating complex decision-making capabilities

Each animation shows:

• Own Ship (OS) in voilet
• Target Ships (TS) in blue, orange and green respectively depending on the number of target ships
• Vessel trajectories and maneuvers
• Real-time COLREGs-compliant decisions

Evolution of DCPA, TCPA, Range, and Risk parameters

The plots demonstrate:

• DCPA/TCPA trends showing effective collision avoidance
• Risk assessment throughout the encounter
• Clear correlation between risk levels and LLM decisions
• Validation of COLREGs compliance through maneuver choices

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow PEP 8 guidelines
• Add docstrings to all functions
• Include type hints where applicable
• Write unit tests for new features

This project is licensed under the MIT License - see the LICENSE file for details.

If you use CORALL in your research, please cite:

@software{corall_2025,
  title = {CORALL: COLREGs-Guided Risk-Aware LLM for Maritime Autonomous Navigation},
  author = {Agyei, Klinsmann and Sarhadi, Pouria and Naeem, Wasif },
  year = {2025},
  url = {https://github.com/Klins101/CORALL}
}

This work was developed in collaboration with:

• Dr. Pouria Sarhadi (University of Hertfordshire)
• Prof. Wasif Naeem (Queen's University Belfast)
• LLM integration using OpenAI GPT and Anthropic Claude models

For questions or support, please open an issue on GitHub or contact:

• Dr. Pouria Sarhadi - p.sarhadi@herts.ac.uk
• Prof. Wasif Naeem - w.naeem@ee.qub.ac.uk
• Klinsmann Agyei - k.agyei@herts.ac.uk