===================================
Heuback Admissibility Solver - README
===================================

Overview
--------
This package contains a Python script (`heuback.py`) designed to solve decision problems related to the admissibility semantics in Abstract Argumentation Frameworks (AFs). It utilizes different strategies based on a specified task parameter, including direct grounded extension checks, an SCC reinstatement heuristic, and a backtracking search algorithm.

The primary way to interact with the solver, especially in competitive environments like ICCMA, is through the provided BASH wrapper script (`solver.sh`).

Files Included
--------------
* heuback.py: The main Python solver script containing the core logic.
* solver.sh: A BASH wrapper script providing a standard command-line interface (compatible with ICCMA specifications) for running `heuback.py`.
* README: This file

Prerequisites
-------------
1.  Python: Python 3 is required. Version 3.7 or higher is recommended. The script uses features commonly available in modern Python 3.

2.  Dependencies:
    * NumPy: Required for significant performance improvements, especially with large AFs. The solver will run without NumPy using pure Python fallbacks, but it will be considerably slower.
    * Numba: Requires NumPy. Provides further acceleration for computationally intensive parts (like conflict checking, defect calculation, and grounded extension) via Just-In-Time (JIT) compilation. Performance gain is most notable with NumPy already installed.

Installation of Dependencies
--------------------------
You can install the recommended dependencies using pip:

   pip install numpy numba

It's often recommended to do this within a Python virtual environment to avoid conflicts with system packages.

   python3 -m venv solver_env
   source solver_env/bin/activate  # On Linux/macOS
   # solver_env\Scripts\activate  # On Windows
   pip install numpy numba
   # Deactivate with 'deactivate' when done

Permissions
-----------
Make sure the wrapper script is executable:

   chmod +x solver.sh

Usage
-----
Always use the `solver.sh` wrapper script to run the solver. It handles the standard command-line arguments and calls the Python script correctly.

Command-Line Interface (`solver.sh`)
------------------------------------
The wrapper script follows the standard ICCMA interface:

./solver.sh [OPTIONS]

Required Options:
* -f <filename> : Specifies the path to the input Argumentation Framework file. The file should be in the '.af' format.
* -p <task>     : Specifies the task to be solved. See "Supported Tasks" below.
* -a <argument> : Specifies the argument ID (from the input file) to query. This is required for all supported decision (DC/DS) tasks.

Informational Options:
* --problems    : Prints the list of supported tasks.
* (no arguments): Prints solver information (name, author).

Supported Tasks (`-p` option)
-----------------------------
The wrapper script declares support for the following tasks. The Python solver (`solver.py`) handles them based on the provided task string:

* DS-PR   (Decide Skeptically Preferred)
* DC-CO   (Decide Credulously Complete)
* DS-ST   (Decide Skeptically Stable)
* DS-SST  (Decide Skeptically Semi-stable)
* DC-ST   (Decide Credulously Stable)
* DC-SST  (Decide Credulously Semi-stable)
* DC-ID   (Decide Credulously Ideal)

How Tasks are Handled Internally by `heuback.py`:
* Grounded Check First: The solver *always* computes the grounded extension first. If the query argument `-a` is in the grounded extension, the result is immediately "IN".
* Tasks starting with "DS" (except DS-ST): If the argument is not in the grounded extension, the result is "OUT". (e.g., DS-PR, DS-SST)
* Task "DC-ID": If the argument is not in the grounded extension, the result is "OUT".
* Task "DS-ST": If the argument is not in the grounded extension, the SCC Reinstatement heuristic is used to determine the result ("IN" or "OUT").
* Tasks starting with "DC" (except DC-ID): If the argument is not in the grounded extension, the solver proceeds with preprocessing (SCC reduction, k-hop cone extraction) and then runs the backtracking search algorithm to find if *any* admissible set containing the query exists. If found, result is "IN", otherwise "OUT". (e.g., DC-CO, DC-ST, DC-SST)

Examples
--------
1.  Check if argument '5' is credulously accepted according to Complete semantics in `example.af`:
    ./solver.sh -f example.af -p DC-CO -a 5

2.  Check if argument 'arg10' is skeptically accepted according to Stable semantics (using the heuristic) in `test_graph.af`:
    ./solver.sh -f test_graph.af -p DS-ST -a arg10

3.  Check if argument '1' is credulously accepted according to Ideal semantics in `ideal_test.af`:
    ./solver.sh -f ideal_test.af -p DC-ID -a 1

4.  List supported tasks:
    ./solver.sh --problems

Output Format
-------------
The solver prints the result to standard output:
* "IN" : If the argument `-a` is accepted according to the specified task `-p`.
* "OUT": If the argument `-a` is not accepted according to the specified task `-p`.

