============================================================================
PROJECT: GERRYMANDERING - ASP vs MiniZinc
============================================================================

COURSE:      Declarative Programming / Constraint Programming
AUTHORS:     Claudio Bendini, Aurora Felisari
UNIVERSITY:  University of Parma
DATE:        7th January 2026

DESCRIPTION:
This project compares two declarative approaches to solve the "Gerrymandering"
(Political Districting) problem:
1. Answer Set Programming (ASP) using Clingo.
2. Constraint Programming (CP) using MiniZinc (Chuffed solver).

The project includes a multi-threaded Python automation script to benchmark 
100 instances, convert formats, and collect results.

============================================================================
1. PROJECT STRUCTURE
============================================================================

.
|-- benchmarks/                       [Dir] Original ASP instances (.lp)
|-- benchmarks_dzn/                   [Dir] Converted MiniZinc instances (.dzn)
|-- imgs/                             [Dir] Charts and images for the report
|-- convert_benchmarks_to_dzn         [File] Converts .lp benchmarks to .mzn
|-- generate_benchmarks.py            [File] Generates .lp benchmarks.
|-- political_districting.lp          [File] ASP Model (Clingo)
|-- political_districting.mzn         [File] Base CP Model (Naive)
|-- political_districting_improved.mzn [File] Optimized CP Model
|-- run_experiments_multithread_python.py [File] Python Script (Runner)
|-- results_python.csv                [File] Results output file
|-- README.txt                        [File] This file
|-- ReportGerrymanderingConstraintProgramming.pdf [File] Report of the project

============================================================================
IMPORTANT NOTE: BENCHMARK PREPARATION
============================================================================

The 'benchmarks' and 'benchmarks_dzn' folders might be empty. 
Before running experiments:

1. Generate the ASP instances (.lp) inside the folder 
 benchmarks/ and run:
 > python generate_benchmarks.py

2. Generate the corresponding MiniZinc instances (.dzn) inside
   benchmarks_dzn/ with the following command: 
   > python convert_benchmarks_to_dzn.py

If these folders are empty, the script will find no instances and exit with 
the message: "No tasks to run".
============================================================================
2. PREREQUISITES AND INSTALLATION
============================================================================

To run the project, the following are required:

A) PYTHON 3
   The "tqdm" library is required to display the progress bar.
   
   Command to install the missing library:
   > pip install tqdm

B) CLINGO (ASP Solver)
   Ensure the 'clingo' executable is installed and added to the system's 
   PATH environment variable.
   Test: Open a terminal and type 'clingo --version'.

C) MINIZINC (CP Solver)
   MiniZinc with the 'Chuffed' solver (included in the standard bundle) is required.
   Ensure the 'minizinc' executable is added to the system PATH.
   Test: Open a terminal and type 'minizinc --version'.

============================================================================
3. USAGE GUIDE - QUICK COMMANDS
============================================================================

Open a terminal in the project folder and use the 
following commands.

----------------------------------------------------------------------------
SCENARIO A: FULL BENCHMARK
----------------------------------------------------------------------------
Runs all 100 instances on all three configurations:
1. ASP Standard
2. MiniZinc Naive (Base)
3. MiniZinc Improved (Optimized)

Command:
python run_experiments_multithread_python.py --solver all

----------------------------------------------------------------------------
SCENARIO B: QUICK TEST
----------------------------------------------------------------------------
Runs only the first 5 instances to verify everything is working, without 
waiting hours for completion.

Command:
python run_experiments_multithread_python.py --solver all --limit 5

----------------------------------------------------------------------------
SCENARIO C: BASE COMPARISON
----------------------------------------------------------------------------
Compares only the original Clingo model with the direct CP translation.

Command:
python run_experiments_multithread_python.py --solver base_comparison

----------------------------------------------------------------------------
SCENARIO D: OPTIMIZED MODEL ONLY 
----------------------------------------------------------------------------
Runs only the 'political_districting_improved.mzn' model. Useful for 
quickly testing performance on large grids without re-running the rest.

Command:
python run_experiments_multithread_python.py --solver improved_minizinc

============================================================================
4. ADVANCED OPTIONS (COMMAND LINE)
============================================================================

The script supports additional parameters:

--workers N
    Specifies the number of parallel processes. 
    Example (uses 8 cores):
    python run_experiments_multithread_python.py --solver all --workers 8

--dry-run
    Prints the commands that would be executed without actually running 
    them. Useful for debugging.
    python run_experiments_multithread_python.py --solver all --dry-run

============================================================================
5. RESULTS OUTPUT
============================================================================

Upon completion, you will find a file named:
"results_python.csv"

The CSV file contains the columns:
- Instance: Instance file name
- PartyOptimized: Party being optimized (0 or 1)
- ModelFile: Model used (.lp or .mzn)
- Strategy: Solver configuration
- MaxReps: Result (seats won)
- TimeSec: Execution time in seconds
- Status: OPTIMAL, SATISFIABLE, or TIMEOUT