tsp-fast-solver-codingwizard34 0.1.0__tar.gz

tsp_fast_solver_codingwizard34-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: tsp-fast-solver-codingwizard34
+Version: 0.1.0
+Summary: A blazing fast C++ TSP solver wrapped in Cython
+Author-email: CodingWizard34 <developer@example.com>
+Keywords: tsp,graph-algorithms,cython,cplusplus,combinatorial-optimization
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# tsp-fast-solver-codingwizard34: Graph Algorithms in Production (TSP)
+
+A high-performance implementation of the Traveling Salesperson Problem (TSP) brute-force solver comparing pure Python against native C++ wrapped with Cython.
+
+## Overview
+
+The Traveling Salesperson Problem (TSP) is an NP-hard combinatorial graph problem: given a list of cities and the distances between each pair of cities, what is the shortest possible route that visits each city exactly once and returns to the origin city?
+
+Because the number of Hamiltonian cycles scales factorially:
+$$\text{Possible Routes} = (N - 1)!$$
+a pure Python search quickly slows down due to interpreter overhead and dynamic type checking. By offloading the permutation traversal to native C++ using `std::next_permutation` and bridging it with a Cython C-extension, we achieve up to **~90x–100x speedup**.
+
+---
+
+## Architecture & Project Structure
+
+```
+tsp-fast-solver/
+├── pyproject.toml            # Build system metadata (PEP 517/518)
+├── setup.py                  # Setuptools & Cython C++ build configuration
+├── benchmark.py              # Benchmarking script comparing both solvers
+├── README.md                 # Project documentation and benchmarks
+├── .gitignore                # Excludes compiled binaries (.pyd, .so, build/)
+├── tests/
+│   └── test_tsp.py           # Comprehensive unit tests (correctness & edge cases)
+└── tsp_fast_solver/
+    ├── __init__.py           # Package exports (tsp_python, tsp_cython)
+    ├── python_solver.py      # Pure Python solver using itertools.permutations
+    ├── tsp.h                 # C++ header declaring tsp_cpp
+    ├── tsp.cpp               # C++ native solver using std::next_permutation
+    ├── c_tsp.pxd             # Cython C++ header declaration
+    └── _tsp_cython.pyx       # Cython wrapper bridging Python 2D lists to std::vector<int>
+```
+
+### Components
+
+1. **Pure Python Solver (`tsp_python`)**:
+   - Uses Python's `itertools.permutations` over nodes $\{1, \dots, N-1\}$.
+   - Evaluates $(N-1)!$ possible paths starting and ending at node 0.
+
+2. **Native C++ Solver (`tsp_cpp`)**:
+   - Implemented in `tsp.h` and `tsp.cpp`.
+   - Uses `std::next_permutation` on a flat `std::vector<int>` distance matrix representation with contiguous memory layout and pointer arithmetic.
+
+3. **Cython Wrapper (`tsp_cython`)**:
+   - Defined across `c_tsp.pxd` and `_tsp_cython.pyx`.
+   - Validates that the input is a square $N \times N$ matrix.
+   - Converts the Python list-of-lists into a 1D `std::vector<int>`, delegates to `tsp_cpp`, and returns the optimal cost.
+
+---
+
+## Benchmark Results
+
+Benchmarked on **Python 3.14 (x86_64 Windows)** using `benchmark.py` with reproducible random symmetric distance matrices:
+
+| Graph Size (Nodes) | Possible Routes $(N-1)!$ | Pure Python Time (s) | Cython + C++ Time (s) | Speedup Delta | Deliverable Expected Time |
+|:------------------:|:------------------------:|:--------------------:|:---------------------:|:-------------:|:-------------------------:|
+| **$N = 8$**        | 5,040                    | 0.0026 s             | 0.00004 s             | **65.2x**     | Python < 0.1s / Instant   |
+| **$N = 10$**       | 362,880                  | 0.2208 s             | 0.0022 s              | **98.5x**     | Python ~1–2s / < 0.05s    |
+| **$N = 11$**       | 3,628,800                | 3.2364 s             | 0.0359 s              | **90.2x**     | Python ~15–30s / ~ 0.5s   |
+
+*Note: The native C++ implementation solves 3.6+ million permutations in just ~36 milliseconds.*
+
+---
+
+## Quick Start & Usage
+
+### 1. Installation
+
+#### From Source (Local Development)
+```bash
+# Clone the repository
+git clone https://github.com/CodingWizard34/tsp-solver.git
+cd tsp-solver
+
+# Build extension in-place
+python setup.py build_ext --inplace
+```
+
+#### Via pip
+```bash
+pip install .
+# Or once published:
+pip install tsp-fast-solver-codingwizard34
+```
+
+### 2. Python API
+
+```python
+from tsp_fast_solver import tsp_python, tsp_cython
+
+# Define an N x N distance matrix (symmetric or asymmetric)
+distance_matrix = [
+    [0, 10, 15, 20],
+    [10,  0, 35, 25],
+    [15, 35,  0, 30],
+    [20, 25, 30,  0]
+]
+
+# Run pure Python solver
+py_cost = tsp_python(distance_matrix)
+print("Pure Python optimal cost:", py_cost)  # Output: 80
+
+# Run compiled Cython / C++ solver
+cy_cost = tsp_cython(distance_matrix)
+print("Cython / C++ optimal cost:", cy_cost)  # Output: 80
+```
+
+### 3. Running Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+### 4. Running Benchmarks
+
+```bash
+python benchmark.py
+```
+
+---
+
+## Packaging and Publishing to PyPI
+
+### 1. Build Source Distribution (sdist) and Wheel
+
+```bash
+# Install the build tool
+python -m pip install --upgrade build
+
+# Generate distributions
+python -m build --sdist
+```
+
+The generated `.tar.gz` archive in `dist/` contains all C++ sources, headers, and Cython `.pyx`/`.pxd` files ready for cross-platform compilation upon `pip install`.
+
+### 2. Upload to PyPI with Twine
+
+```bash
+# Install Twine
+python -m pip install --upgrade twine
+
+# Upload to TestPyPI (recommended first):
+python -m twine upload --repository testpypi dist/*
+
+# Upload to production PyPI:
+python -m twine upload dist/*
+```
+
+When prompted:
+- **Username**: `__token__`
+- **Password**: `<your-pypi-api-token>`
+
+### 3. Verifying Installation
+
+In a clean virtual environment:
+```bash
+pip install tsp-fast-solver-codingwizard34
+python -c "import tsp_fast_solver; print('Success! tsp-fast-solver loaded version:', tsp_fast_solver.__version__)"
+```
+
+---
+
+## License
+
+MIT License.

tsp_fast_solver_codingwizard34-0.1.0/README.md

@@ -0,0 +1,166 @@
+# tsp-fast-solver-codingwizard34: Graph Algorithms in Production (TSP)
+
+A high-performance implementation of the Traveling Salesperson Problem (TSP) brute-force solver comparing pure Python against native C++ wrapped with Cython.
+
+## Overview
+
+The Traveling Salesperson Problem (TSP) is an NP-hard combinatorial graph problem: given a list of cities and the distances between each pair of cities, what is the shortest possible route that visits each city exactly once and returns to the origin city?
+
+Because the number of Hamiltonian cycles scales factorially:
+$$\text{Possible Routes} = (N - 1)!$$
+a pure Python search quickly slows down due to interpreter overhead and dynamic type checking. By offloading the permutation traversal to native C++ using `std::next_permutation` and bridging it with a Cython C-extension, we achieve up to **~90x–100x speedup**.
+
+---
+
+## Architecture & Project Structure
+
+```
+tsp-fast-solver/
+├── pyproject.toml            # Build system metadata (PEP 517/518)
+├── setup.py                  # Setuptools & Cython C++ build configuration
+├── benchmark.py              # Benchmarking script comparing both solvers
+├── README.md                 # Project documentation and benchmarks
+├── .gitignore                # Excludes compiled binaries (.pyd, .so, build/)
+├── tests/
+│   └── test_tsp.py           # Comprehensive unit tests (correctness & edge cases)
+└── tsp_fast_solver/
+    ├── __init__.py           # Package exports (tsp_python, tsp_cython)
+    ├── python_solver.py      # Pure Python solver using itertools.permutations
+    ├── tsp.h                 # C++ header declaring tsp_cpp
+    ├── tsp.cpp               # C++ native solver using std::next_permutation
+    ├── c_tsp.pxd             # Cython C++ header declaration
+    └── _tsp_cython.pyx       # Cython wrapper bridging Python 2D lists to std::vector<int>
+```
+
+### Components
+
+1. **Pure Python Solver (`tsp_python`)**:
+   - Uses Python's `itertools.permutations` over nodes $\{1, \dots, N-1\}$.
+   - Evaluates $(N-1)!$ possible paths starting and ending at node 0.
+
+2. **Native C++ Solver (`tsp_cpp`)**:
+   - Implemented in `tsp.h` and `tsp.cpp`.
+   - Uses `std::next_permutation` on a flat `std::vector<int>` distance matrix representation with contiguous memory layout and pointer arithmetic.
+
+3. **Cython Wrapper (`tsp_cython`)**:
+   - Defined across `c_tsp.pxd` and `_tsp_cython.pyx`.
+   - Validates that the input is a square $N \times N$ matrix.
+   - Converts the Python list-of-lists into a 1D `std::vector<int>`, delegates to `tsp_cpp`, and returns the optimal cost.
+
+---
+
+## Benchmark Results
+
+Benchmarked on **Python 3.14 (x86_64 Windows)** using `benchmark.py` with reproducible random symmetric distance matrices:
+
+| Graph Size (Nodes) | Possible Routes $(N-1)!$ | Pure Python Time (s) | Cython + C++ Time (s) | Speedup Delta | Deliverable Expected Time |
+|:------------------:|:------------------------:|:--------------------:|:---------------------:|:-------------:|:-------------------------:|
+| **$N = 8$**        | 5,040                    | 0.0026 s             | 0.00004 s             | **65.2x**     | Python < 0.1s / Instant   |
+| **$N = 10$**       | 362,880                  | 0.2208 s             | 0.0022 s              | **98.5x**     | Python ~1–2s / < 0.05s    |
+| **$N = 11$**       | 3,628,800                | 3.2364 s             | 0.0359 s              | **90.2x**     | Python ~15–30s / ~ 0.5s   |
+
+*Note: The native C++ implementation solves 3.6+ million permutations in just ~36 milliseconds.*
+
+---
+
+## Quick Start & Usage
+
+### 1. Installation
+
+#### From Source (Local Development)
+```bash
+# Clone the repository
+git clone https://github.com/CodingWizard34/tsp-solver.git
+cd tsp-solver
+
+# Build extension in-place
+python setup.py build_ext --inplace
+```
+
+#### Via pip
+```bash
+pip install .
+# Or once published:
+pip install tsp-fast-solver-codingwizard34
+```
+
+### 2. Python API
+
+```python
+from tsp_fast_solver import tsp_python, tsp_cython
+
+# Define an N x N distance matrix (symmetric or asymmetric)
+distance_matrix = [
+    [0, 10, 15, 20],
+    [10,  0, 35, 25],
+    [15, 35,  0, 30],
+    [20, 25, 30,  0]
+]
+
+# Run pure Python solver
+py_cost = tsp_python(distance_matrix)
+print("Pure Python optimal cost:", py_cost)  # Output: 80
+
+# Run compiled Cython / C++ solver
+cy_cost = tsp_cython(distance_matrix)
+print("Cython / C++ optimal cost:", cy_cost)  # Output: 80
+```
+
+### 3. Running Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+### 4. Running Benchmarks
+
+```bash
+python benchmark.py
+```
+
+---
+
+## Packaging and Publishing to PyPI
+
+### 1. Build Source Distribution (sdist) and Wheel
+
+```bash
+# Install the build tool
+python -m pip install --upgrade build
+
+# Generate distributions
+python -m build --sdist
+```
+
+The generated `.tar.gz` archive in `dist/` contains all C++ sources, headers, and Cython `.pyx`/`.pxd` files ready for cross-platform compilation upon `pip install`.
+
+### 2. Upload to PyPI with Twine
+
+```bash
+# Install Twine
+python -m pip install --upgrade twine
+
+# Upload to TestPyPI (recommended first):
+python -m twine upload --repository testpypi dist/*
+
+# Upload to production PyPI:
+python -m twine upload dist/*
+```
+
+When prompted:
+- **Username**: `__token__`
+- **Password**: `<your-pypi-api-token>`
+
+### 3. Verifying Installation
+
+In a clean virtual environment:
+```bash
+pip install tsp-fast-solver-codingwizard34
+python -c "import tsp_fast_solver; print('Success! tsp-fast-solver loaded version:', tsp_fast_solver.__version__)"
+```
+
+---
+
+## License
+
+MIT License.

tsp_fast_solver_codingwizard34-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0", "cython"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tsp-fast-solver-codingwizard34"
+version = "0.1.0"
+authors = [
+    { name = "CodingWizard34", email = "developer@example.com" }
+]
+description = "A blazing fast C++ TSP solver wrapped in Cython"
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = ["tsp", "graph-algorithms", "cython", "cplusplus", "combinatorial-optimization"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C++",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]

tsp_fast_solver_codingwizard34-0.1.0/setup.cfg

@@ -0,0 +1,10 @@
+[build]
+compiler = mingw32
+
+[build_ext]
+compiler = mingw32
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

tsp_fast_solver_codingwizard34-0.1.0/setup.py

@@ -0,0 +1,50 @@
+import os
+import sys
+from setuptools import setup, find_packages, Extension
+
+try:
+    from Cython.Build import cythonize
+    USE_CYTHON = True
+except ImportError:
+    USE_CYTHON = False
+
+source_ext = ".pyx" if USE_CYTHON else ".cpp"
+
+extra_compile_args = []
+extra_link_args = []
+
+if sys.platform != "win32":
+    extra_compile_args.extend(["-O3", "-std=c++11"])
+
+pkg_dir = os.path.abspath("tsp_fast_solver")
+
+extensions = [
+    Extension(
+        name="tsp_fast_solver._tsp_cython",
+        sources=[
+            os.path.join("tsp_fast_solver", f"_tsp_cython{source_ext}"),
+            os.path.join("tsp_fast_solver", "tsp.cpp"),
+        ],
+        include_dirs=[pkg_dir],
+        language="c++",
+        extra_compile_args=extra_compile_args,
+        extra_link_args=extra_link_args,
+    ),
+]
+
+if USE_CYTHON:
+    ext_modules = cythonize(
+        extensions,
+        include_path=[pkg_dir, "."],
+        compiler_directives={"language_level": "3"},
+    )
+else:
+    ext_modules = extensions
+
+setup(
+    packages=find_packages(),
+    ext_modules=ext_modules,
+    package_data={
+        "tsp_fast_solver": ["*.h", "*.pxd", "*.pyx", "*.cpp"],
+    },
+)

tsp_fast_solver_codingwizard34-0.1.0/tests/test_tsp.py

@@ -0,0 +1,83 @@
+import unittest
+import random
+from tsp_fast_solver.python_solver import tsp_python
+
+try:
+    from tsp_fast_solver._tsp_cython import tsp_cython
+    CYTHON_AVAILABLE = True
+except ImportError:
+    CYTHON_AVAILABLE = False
+
+
+def generate_random_matrix(n, seed=None):
+    if seed is not None:
+        random.seed(seed)
+    matrix = [[0] * n for _ in range(n)]
+    for i in range(n):
+        for j in range(i + 1, n):
+            d = random.randint(5, 100)
+            matrix[i][j] = d
+            matrix[j][i] = d
+    return matrix
+
+
+class TestTSPSolvers(unittest.TestCase):
+
+    def test_trivial_cases(self):
+        self.assertEqual(tsp_python([]), 0)
+        self.assertEqual(tsp_python([[0]]), 0)
+
+        if CYTHON_AVAILABLE:
+            self.assertEqual(tsp_cython([]), 0)
+            self.assertEqual(tsp_cython([[0]]), 0)
+
+    def test_two_cities(self):
+        mat = [
+            [0, 15],
+            [15, 0]
+        ]
+        self.assertEqual(tsp_python(mat), 30)
+        if CYTHON_AVAILABLE:
+            self.assertEqual(tsp_cython(mat), 30)
+
+    def test_three_cities(self):
+        mat = [
+            [0, 10, 20],
+            [10, 0, 15],
+            [20, 15, 0]
+        ]
+        # Only one distinct cycle (both directions have same length): 0 -> 1 -> 2 -> 0 => 10 + 15 + 20 = 45
+        self.assertEqual(tsp_python(mat), 45)
+        if CYTHON_AVAILABLE:
+            self.assertEqual(tsp_cython(mat), 45)
+
+    def test_four_cities_known(self):
+        mat = [
+            [0, 10, 15, 20],
+            [10, 0, 35, 25],
+            [15, 35, 0, 30],
+            [20, 25, 30, 0]
+        ]
+        # Best route: 0 -> 1 -> 3 -> 2 -> 0 => 10 + 25 + 30 + 15 = 80
+        self.assertEqual(tsp_python(mat), 80)
+        if CYTHON_AVAILABLE:
+            self.assertEqual(tsp_cython(mat), 80)
+
+    def test_python_and_cython_equivalence(self):
+        if not CYTHON_AVAILABLE:
+            self.skipTest("Cython extension not built yet")
+
+        for size in [4, 5, 6, 7]:
+            mat = generate_random_matrix(size, seed=100 + size)
+            py_cost = tsp_python(mat)
+            cy_cost = tsp_cython(mat)
+            self.assertEqual(py_cost, cy_cost, f"Mismatch on size {size}: Python={py_cost}, Cython={cy_cost}")
+
+    def test_invalid_dimension(self):
+        if CYTHON_AVAILABLE:
+            with self.assertRaises(ValueError):
+                tsp_cython([[0, 10], [10]])
+
+
+if __name__ == "__main__":
+    unittest.main()

tsp_fast_solver_codingwizard34-0.1.0/tsp_fast_solver/__init__.py

@@ -0,0 +1,15 @@
+"""
+tsp-fast-solver: High-performance Traveling Salesperson Problem (TSP) solver
+comparing pure Python against Cython-wrapped C++ std::next_permutation.
+"""
+
+from .python_solver import tsp_python
+
+try:
+    from ._tsp_cython import tsp_cython
+except ImportError:
+    # Fallback for environments where the compiled C-extension has not been built yet
+    tsp_cython = None
+
+__version__ = "0.1.0"
+__all__ = ["tsp_python", "tsp_cython"]