# dmishin/tsp-solver architecture

> Architecture diagram of the GitHub repository dmishin/tsp-solver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dmishin/tsp-solver
- Repository: https://github.com/dmishin/tsp-solver

## Overview

##### Project type and purpose
- This is an open-source Python library and command-line tool for computing sub-optimal solutions to the Travelling Salesman Problem (TSP).
- It comes with core solver modules, demonstration scripts, CLI entrypoints, and visualization utilities.

##### File structure
- Top-level files:
- setup.py, setup.cfg – installation and packaging
- Makefile, runtest.sh – build/test conveniences
- bin/ – command-line wrappers (tsp_demo, tsp_numpy2svg)
- tests/ – unit and performance tests
- samples/, images/ – demo inputs and assets
- Core package: tsp_solver/
- tsp_solver/greedy.py – pure-Python greedy solver
- tsp_solver/greedy_numpy.py – NumPy- backed solver
- tsp_solver/util.py – cost‐calculation helper
- tsp_solver/demo/ – scripts for generating TSPs and rendering results

##### Key insights from README
- Two solver implementations (pure Python vs. NumPy-accelerated).
- Demo scripts depend on external libraries: NumPy, PIL, Matplotlib.
- Entry points: “demo_tsp” (random TSP generation -> solve -> save .npy) and “tsp_numpy2svg” (convert .npy to SVG).
- Supports Python 2 & 3, installed via PyPI or manually via setup.py.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User(("User")):::ext

    %% CLI Layer
    subgraph "CLI Layer"
        CLI_Demo["demo_tsp"]:::cli
        CLI_SVG["tsp_numpy2svg"]:::cli
    end

    %% Demo & Visualization
    subgraph "Demo & Visualization"
        TSP_Demo["tsp_solver.demo.tsp"]:::demo
        N2SVG["tsp_solver.demo.numpy2svg"]:::demo
        Img2Points["tsp_solver.demo.image2point_cloud"]:::demo
    end

    %% Core Library
    subgraph "Solver Core"
        GreedyPy["tsp_solver.greedy"]:::core
        GreedyNP["tsp_solver.greedy_numpy"]:::core
    end
    Util["tsp_solver.util"]:::core

    %% External Libraries
    subgraph "External Libraries"
        NumPy["NumPy"]:::ext
        PIL["PIL/Pillow"]:::ext
        MPL["Matplotlib"]:::ext
    end

    %% Data Artifacts
    subgraph "Data Artifacts"
        Samples["samples/"]:::data
        Images["images/"]:::data
        NPY[".npy files"]:::data
        SVG[".svg files"]:::data
    end

    %% Test Suite
    subgraph "Test Suite"
        TestGreedy["tests/test_greedy.py"]:::test
        TestUtil["tests/test_util.py"]:::test
        PerfTest["tests/perftest.py"]:::test
    end

    %% Packaging & Build
    subgraph "Packaging & Build"
        SetupPy["setup.py"]:::pkg
        SetupCfg["setup.cfg"]:::pkg
        Makefile["Makefile"]:::pkg
        RunTestSh["runtest.sh"]:::pkg
        Doc["README.md"]:::doc
    end

    %% Connections
    User -->|invokes| CLI_Demo
    User -->|invokes| CLI_SVG

    CLI_Demo -->|calls demo| TSP_Demo
    TSP_Demo -->|generates TSP| Samples
    TSP_Demo -->|loads assets| Images
    TSP_Demo -->|calls| GreedyPy
    TSP_Demo -->|calls| GreedyNP
    GreedyPy -->|uses| Util
    GreedyNP -->|uses| Util
    TSP_Demo -->|saves| NPY

    CLI_SVG -->|calls converter| N2SVG
    N2SVG -->|reads| NPY
    N2SVG -->|uses| MPL
    N2SVG -->|uses| PIL
    N2SVG -->|writes| SVG

    TSP_Demo -->|uses| Img2Points
    Img2Points -->|uses| Util
    Img2Points -->|uses| PIL

    TestGreedy -->|tests| GreedyPy
    TestUtil -->|tests| Util
    PerfTest -->|performance tests| GreedyNP
    PerfTest -->|performance tests| Util

    SetupPy -->|packages| GreedyPy
    SetupPy -->|packages| GreedyNP
    SetupPy -->|packages| Util
    SetupPy -->|packages| TSP_Demo
    SetupPy -->|packages| N2SVG
    SetupPy -->|defines entrypoints| CLI_Demo
    SetupPy -->|defines entrypoints| CLI_SVG
    SetupPy -->|includes docs| Doc
    SetupCfg -->|metadata| SetupPy

    Makefile -->|automation| SetupPy
    Makefile -->|automation| RunTestSh
    RunTestSh -->|runs| TestGreedy
    RunTestSh -->|runs| TestUtil
    RunTestSh -->|runs| PerfTest

    %% Click Events
    click CLI_Demo "https://github.com/dmishin/tsp-solver/tree/master/bin/tsp_demo"
    click CLI_SVG "https://github.com/dmishin/tsp-solver/tree/master/bin/tsp_numpy2svg"
    click TSP_Demo "https://github.com/dmishin/tsp-solver/blob/master/tsp_solver/demo/tsp.py"
    click N2SVG "https://github.com/dmishin/tsp-solver/blob/master/tsp_solver/demo/numpy2svg.py"
    click Img2Points "https://github.com/dmishin/tsp-solver/blob/master/tsp_solver/demo/image2point_cloud.py"
    click GreedyPy "https://github.com/dmishin/tsp-solver/blob/master/tsp_solver/greedy.py"
    click GreedyNP "https://github.com/dmishin/tsp-solver/blob/master/tsp_solver/greedy_numpy.py"
    click Util "https://github.com/dmishin/tsp-solver/blob/master/tsp_solver/util.py"
    click TestGreedy "https://github.com/dmishin/tsp-solver/blob/master/tests/test_greedy.py"
    click TestUtil "https://github.com/dmishin/tsp-solver/blob/master/tests/test_util.py"
    click PerfTest "https://github.com/dmishin/tsp-solver/blob/master/tests/perftest.py"
    click SetupPy "https://github.com/dmishin/tsp-solver/blob/master/setup.py"
    click SetupCfg "https://github.com/dmishin/tsp-solver/blob/master/setup.cfg"
    click Makefile "https://github.com/dmishin/tsp-solver/tree/master/Makefile"
    click RunTestSh "https://github.com/dmishin/tsp-solver/blob/master/runtest.sh"
    click Samples "https://github.com/dmishin/tsp-solver/tree/master/samples/"
    click Images "https://github.com/dmishin/tsp-solver/tree/master/images/"
    click Doc "https://github.com/dmishin/tsp-solver/blob/master/README.md"

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff
    classDef demo fill:#d4edda,stroke:#28a745
    classDef cli fill:#fff3cd,stroke:#ffcd39
    classDef ext fill:#e2e3e5,stroke:#6c757d
    classDef data fill:#f0e6f6,stroke:#9b59b6
    classDef test fill:#f8d7da,stroke:#dc3545
    classDef pkg fill:#d1ecf1,stroke:#17a2b8
    classDef doc fill:#fdfd96,stroke:#e6e600
```
