# medelbou3/ray-tsp-research-findings-report architecture

> Architecture diagram of the GitHub repository medelbou3/ray-tsp-research-findings-report, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/medelbou3/ray-tsp-research-findings-report
- Repository: https://github.com/medelbou3/ray-tsp-research-findings-report

## Overview

Ray TSP is both a TSP heuristic study and a small browser demonstration. The central workflow takes city coordinates, constructs a tour with a directional-sweep or baseline heuristic, optionally refines it, and returns a tour and cost. The repository also includes enhanced Ray variants, a population-based recombination solver, TSPLIB input, synthetic-instance generation, and statistical evaluation. The README documents these broader capabilities; some modules were not sampled, so their links are shown only where the tree and documentation support them. The browser wiring is based on the partial `script.js` excerpt.

Main entry points: [`src/ray_tsp.py`](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/ray_tsp.py) (Directional Ray), [`stats/significance_tests.py`](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/stats/significance_tests.py) (Paired significance), [`script.js`](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/script.js) (Interactive algorithms), [`src/memetic.py`](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/memetic.py) (Edge recombination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_browser["Browser demo<br/>[index.html]"]
  node_browser_logic["Interactive algorithms<br/>[script.js]"]
end

subgraph group_inputs["Problem Inputs"]
  node_synthetic["Synthetic instances<br/>[data_generator.py]"]
  node_tsplib["TSPLIB parser<br/>[tsplib_parser.py]"]
end

subgraph group_construction["Tour Construction"]
  node_ray["Directional Ray<br/>[ray_tsp.py]"]
  node_ray_improved["Improved Ray"]
  node_ray_enhanced["Enhanced Ray"]
  node_nearest["Nearest neighbor"]
  node_christofides["Christofides baseline<br/>[christofides.py]"]
end

subgraph group_optimization["Tour Optimization"]
  node_memetic["Edge recombination<br/>[memetic.py]"]
  node_twoopt["2-opt search<br/>[two_opt.py]"]
  node_annealing["Simulated annealing"]
end

subgraph group_evaluation["Study Evaluation"]
  node_metrics["Tour metrics<br/>[metrics.py]"]
  node_significance["Paired significance"]
end

node_user(("User"))
node_researcher(("Researcher"))

node_user -->|"uses"| node_browser
node_browser -->|"loads"| node_browser_logic
node_browser_logic -->|"constructs tour"| node_ray
node_browser_logic -->|"constructs baseline"| node_nearest
node_browser_logic -->|"refines tours"| node_twoopt
node_synthetic -->|"supplies coordinates"| node_ray
node_tsplib -->|"supplies coordinates"| node_ray
node_ray_improved -->|"reuses helpers"| node_ray
node_ray_enhanced -->|"reuses helpers"| node_ray
node_memetic -->|"refines offspring"| node_twoopt
node_memetic -->|"anneals candidates"| node_annealing
node_memetic -->|"uses tour length"| node_ray
node_researcher -->|"runs evaluation"| node_significance
node_significance -->|"generates instances"| node_synthetic
node_significance -->|"constructs tours"| node_ray
node_significance -->|"constructs baseline"| node_nearest
node_significance -->|"refines tours"| node_twoopt
node_researcher -.->|"evaluates solver"| node_memetic
node_researcher -.->|"evaluates variant"| node_ray_improved
node_researcher -.->|"evaluates variant"| node_ray_enhanced
node_researcher -.->|"compares baseline"| node_christofides
node_researcher -.->|"assesses tours"| node_metrics

click node_browser "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/index.html"
click node_browser_logic "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/script.js"
click node_synthetic "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/data_generator.py"
click node_tsplib "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/tsplib_parser.py"
click node_ray "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/ray_tsp.py"
click node_ray_improved "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/ray_tsp_improved.py"
click node_ray_enhanced "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/ray_tsp_enhanced.py"
click node_nearest "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/nearest_neighbor.py"
click node_christofides "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/christofides.py"
click node_memetic "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/memetic.py"
click node_twoopt "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/two_opt.py"
click node_annealing "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/simulated_annealing.py"
click node_metrics "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/metrics.py"
click node_significance "https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/stats/significance_tests.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_browser_logic,node_user toneBlue
class node_synthetic,node_tsplib toneAmber
class node_ray,node_ray_improved,node_ray_enhanced,node_nearest,node_christofides toneMint
class node_memetic,node_twoopt,node_annealing toneRose
class node_metrics,node_significance,node_researcher toneIndigo
```

## Components

### User Interface

- [Browser demo](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/index.html): `index.html`
- [Interactive algorithms](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/script.js): `script.js`

### Problem Inputs

- [Synthetic instances](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/data_generator.py): `src/data_generator.py`
- [TSPLIB parser](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/tsplib_parser.py): `src/tsplib_parser.py`

### Tour Construction

- [Directional Ray](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/ray_tsp.py): `src/ray_tsp.py`
- [Improved Ray](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/ray_tsp_improved.py): `src/ray_tsp_improved.py`
- [Enhanced Ray](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/ray_tsp_enhanced.py): `src/ray_tsp_enhanced.py`
- [Nearest neighbor](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/nearest_neighbor.py): `src/nearest_neighbor.py`
- [Christofides baseline](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/christofides.py): `src/christofides.py`

### Tour Optimization

- [Edge recombination](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/memetic.py): `src/memetic.py`
- [2-opt search](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/two_opt.py): `src/two_opt.py`
- [Simulated annealing](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/simulated_annealing.py): `src/simulated_annealing.py`

### Study Evaluation

- [Tour metrics](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/src/metrics.py): `src/metrics.py`
- [Paired significance](https://github.com/medelbou3/ray-tsp-research-findings-report/blob/main/stats/significance_tests.py): `stats/significance_tests.py`

### Other components

- **User**
- **Researcher**

## Connections

- User → Browser demo: uses
- Browser demo → Interactive algorithms: loads
- Interactive algorithms → Directional Ray: constructs tour
- Interactive algorithms → Nearest neighbor: constructs baseline
- Interactive algorithms → 2-opt search: refines tours
- Synthetic instances → Directional Ray: supplies coordinates
- TSPLIB parser → Directional Ray: supplies coordinates
- Improved Ray → Directional Ray: reuses helpers
- Enhanced Ray → Directional Ray: reuses helpers
- Edge recombination → 2-opt search: refines offspring
- Edge recombination → Simulated annealing: anneals candidates
- Edge recombination → Directional Ray: uses tour length
- Researcher → Paired significance: runs evaluation
- Paired significance → Synthetic instances: generates instances
- Paired significance → Directional Ray: constructs tours
- Paired significance → Nearest neighbor: constructs baseline
- Paired significance → 2-opt search: refines tours
- Researcher → Edge recombination: evaluates solver
- Researcher → Improved Ray: evaluates variant
- Researcher → Enhanced Ray: evaluates variant
- Researcher → Christofides baseline: compares baseline
- Researcher → Tour metrics: assesses tours