Runtime-configurable MPI solver, headless Python plotting, and CI smoke workflow

[Copilot]

This PR makes the solver easier to run and automate by moving key runtime knobs from compile-time constants to CLI flags, hardening failure paths, and adding non-MATLAB plotting + CI smoke coverage. It keeps the core algorithm and output contract intact while improving reproducibility and operability.

• Solver runtime configuration + robustness (script/tsp_mpi.c)

  • Replaced compile-time tuning constants with runtime flags:
    • --replicas, --steps, --swap-interval, --initial-temp, --temp-decay, --seed, --deterministic, --help
  • First non-option positional arg is TSPLIB input (default: data/berlin52.tsp)
  • Enforced runtime replica constraint: replicas must be positive and divisible by MPI process count
  • Replaced stack VLAs used in swap paths with heap buffers (malloc/free)
  • Added explicit fopen/malloc failure handling and consistent cleanup/abort behavior
  • Added deterministic mode for reproducible short runs in CI
  • Preserved output files: solution.txt, my_route.txt

• Build/layout updates (Makefile)

  • Added BIN_DIR := bin
  • Build target now produces bin/tsp_solver (still built with mpicc)
  • Added run-example PHONY target with a short deterministic mpirun example

• MATLAB-free plotting path (script/plot_results.py)

  • New minimal matplotlib script (Agg backend) to generate route comparison plots from:
    • solution.txt
    • my_route.txt
    • optional TSPLIB coordinates (default data/berlin52.tsp)

• CI workflow (.github/workflows/ci.yml)

  • Added push/PR workflow to:
    • install OpenMPI + Python matplotlib
    • build with make
    • run deterministic smoke test (-np 2, short steps)
    • execute Python plotting script headlessly
  • Added explicit minimal token permissions (contents: read)

• Docs updates (README.md, CONTRIBUTING.md)

  • Updated getting-started/run docs with new CLI interface and examples
  • Documented replica divisibility requirement and generated outputs
  • Added local smoke-test guidance aligned with CI path
  • Noted Python plotting alternative to MATLAB scripts

mpirun --allow-run-as-root -np 2 bin/tsp_solver data/berlin52.tsp \
  --replicas 4 --steps 10 --swap-interval 2 --deterministic
python3 script/plot_results.py --solution solution.txt --route my_route.txt --tsp data/berlin52.tsp

[Kandil2001]

made it better