This is the supplementary material belonging to the paper "A Graph-Based Algorithm for the Automated Justification of Collective Decisions" by Oliviero Nardi, Arthur Boixel and Ulle Endriss, published in the proceedings of the 21st International Conference on Autonomous Agents and Multiagent Systems (AAMAS-2022).
The supplementary material consists of the code used to run the experiments featured in the paper, together with a full record of the results.
More details on each of these files are contained within the files themselves.
Experiments/
Contains the bash scripts used to run the experiments.
Outputs/
Contains the outputs of the experiments.
ReadOutputs.py
Used to parse the (JSON) outputs of the experiments.
Preflib/
Contains the Preflib files used for our experiments, plus a Python file implementing our sampling approach for Preflib profiles.
AllProfiles/
Contains, for all scenarios (i.e., number of voters and alternatives) considered in our experiments, a document listing every profile in that scenario (up to symmetry breaking). These are used by the experiment scripts.
Axioms/InterAxioms/
Contains the implementation of axioms whose instances mention one profile at a time.
Axioms/IntraAxioms/
Contains the implementation of axioms whose instances mention more than one profile at a time.
Axioms/DerivedAxioms/
Contains the implementation of the various derived axioms heuristics.
Axioms/Utils/
Contains various utilities: abstract classes and a Python file implementing various functions used to iterate through sets of axioms.
corpus.txt
The corpus used in our experiments (list of axioms).
main.py
Program interface.
core.py
Contains the implementation of the main algorithm.
Profile.py
Contains a class representing a (preference) profile.
GraphGen.py
Graph-based (BFS) generation algorithm.
SATEncoding.py
Class that implements various utilities for the solving phase: an object of this class handles the SAT encoding and the MUS enumeration.
Helpers.py
Various helper functions.
README.md
This file.
MARCO
External MUS enumerator.
Alternatives are represented as integers and preference orders as strings of integers. For example, 012 means that 0 is preferred to 1, which is preferred to 2. The enumeration of alternatives should always start from 0. A profile is represented as a comma-separated list of preference orders, either with or without counts. For example, 012,012,210 and 2:012,1:210 express the same profile.
To find an outcome that can be justified for a given profile (and obtain a justification for that outcome), run:
python main.py --p <profile>You can also specify a target outcome:
python main.py --p <profile> --o <outcome>Here, <outcome> is a set of alternatives, simply written as a string of alternatives. For example, 01 and 10 both mean {0, 1}. If no outcome is specified, the algorithm tries to find a justification for some outcome (recall that there never can be more than one justifiable outcome for the same profile and the same corpus of axioms).
To specify a corpus of axioms, add the --corpus <file> flag; <file> must be a text file (in the same folder as main.py) containing an endline-separated list of axiom names. Default: corpus.txt.
Furthermore, add --max_depth <d> to place a restriction on the maximum depth (<d>). Default: no restriction.
Lastly, specify --limit <l> to force the gMUS extractor to generate <l> gMUSes and pick the smallest one (in terms of number of instances). Default: 1.
To try and find a justification for some outcome (no concrete outcome can be specified here) for a random profile use:
python main.py --random --n <N> --m <M>This generates a profile by sampling uniformly the space of all profiles with N voters and M alternatives.
To use a profile sampled from Preflib (no concrete outcome can be specified here, either):
python main.py --random --n <N> --m <M> --preflib --preflib_folder <folder> --file <filename>Here <filename> must be the name of a file in the <folder> folder. Do not add .soc add the end of file.
To save the results of a run, add the flag --save_out.
To run the experiments, you can run any of the bash scripts in the Experiments/ folder. For each of them, run:
bash <script>.sh <N> <M> <D>Here N, M, and D are the voters, alternatives, and maximum depths, respectively. If you want to place no bound on the depth, just use a very large number, such as 100. Note that, for preflib, you can only set M to 3 or 4. For manual, you have to restrict yourself to one of the scenarios found in the AllProfiles/ folder.
Outputs are saved inside Outputs/. To read the results inside a folder called Outputs/<folder>, run:
python ReadOutputs.py --f <folder>Written in Python3. Requires the library pylgl for SAT solving (available here).
The ReadOutputs.py file requires the package numpy (available here).
The binaries of the gMUS extractor MARCO have been included. This should work out of the box.