QSOLE: Automatic QBF Equivalence Checking

Introduction

This artifact was submitted by Peter Pfeiffer, Mark Peyrer, Daniel Große and Martina Seidl for the TACAS 2026 with the submission number 9062 aiming for Available, Functional and Reusable badges. It contains everything necessary to reproduce the examples shown in the corresponding paper alongside testcases to demonstrate basic functionality. In the following sections you will learn everything you need to know about this artifact and how to reproduce the experiments.

The input formulas used by tests are divided into four categories:

• atleast contains at-least-k cardinality constraints with randomly generated quantifier prefixes and different encodings (km-totalizer and sequential counters).
• eq contains equals-k cardinality constraints with randomly generated quantifier prefixes and different encodings (km-totalizer and sequential counters).
• hein features Hein puzzles expressed with different encoding techniques from SQval.
• paper contains the examples presented in the corresponding paper.

The artifact was published under the following DOI: 10.5281/zenodo.17356608

Structure and Content

The artifact has the following structure:
/
|--  expected
|--  output
|--  qsole
|--  scripts
|--  tests

• expected contains the log-files of the experiments conducted with this artifact on our machine
• output is the target of the results from the experiments and is connected to a local folder with the same name on the host-machine. The logfiles from the runs can be found there
• qsole contains the c++ source code and build-environment for the QSOLE tool
• scripts is a collection of bash-scripts in order to run the experiments. The one relevant for you are listed in the next section
• tests contains the input formulas as well as the pcount for each check

Running the artifact

1. Setup Docker

A working docker environment installed on your machine is required. The docker container can be setup the following way:

# download qsole-artifact.zst from zenodo
docker load < qsole-artifact.zst
docker run -v `pwd`/output:/output -itd --network none --name qsole_running1 qsole-artifact
docker exec -it qsole_running1 bash

The first line loads the docker-image from the the export, the second will create a container using the image and the last connects your current terminal to the container.

In order to leave the container, just execute exit.

Furthermore, you can call 

docker stop qsole_running1
docker rm qsole_running1

to stop and delete the running container.

Important: Please ensure to have a working docker setup, with your user added to the docker group. This can be verified using docker ps. If there are no errors, your environment should be in working order.

2. Run the Smoke Test

We prepared a small script for you to check, if the tool was installed successfully. 
This is just for your convenience, please feel free to use any of the provided ressources to conduct the smoke test.

The script /scripts/smoke_test.sh will execute the following code

/qsole/build/qsole --help
/qsole/build/qsole /test/paper_example/phi.qdimacs /test/paper_example/psi.qdimacs 3 --check sole --subsumption --info --noskip

i.e. printing the help-text and then solve the minimal example presented in the paper using a full Solution Equivalence Check.
The following output is to be expected, if the artifact is up and running.

qsole v0.1 - a checker qbf solution equivalence
usage: qsole FORMULA1 FORMULA2 PCOUNT [OPTIONS...]

FORMULA1 expects a file containing a QDIMACS encoded QBF
FORMULA2 expects a file containing a QDIMACS encoded QBF
PCOUNT expects the length of the common prefix
The following values for OPTIONS are valid:
  -h, --help           displays this command
  --check <VALUE>      specifies the check to be made (skent|sole|psole|skeq) [default: skent]
  --ouput <PATH>       outputs the encoding to the specified path
  --models             if specified, models will be printed if suitable  
  --subsumption        if specified, eliminate subsumptions before encoding
  --noskip             if specified, all checks will be done even if the result is already clear
  --quiet              does not print any logging messages, not even errors
  --info               increases verbosity level to "info"
[QSOLE] [INF] Skolem Entailment f1 |=SK f2 resulted in 10
[QSOLE] [INF] Skolem Entailment f2 |=SK f1 resulted in 20
[QSOLE] [INF] Skolem Entailment !f1 |=SK !f2 resulted in 10
[QSOLE] [INF] Skolem Entailment !f2 |=SK !f1 resulted in 10
[QSOLE] [INF] Solution Equivalence (f1 <->SOL f2) resulted in 20

3. Run the Experiment

While connected, you can run one of the following scripts to generate log-files.
The output can be found in the output folder.

The following requirements were measured on a host machine for the docker container with the following specifications:

• Intel Core i7-1355U Prozessor
• 32 GB RAM
• Intel Iris Xe GPU

Dependencies

The following core-dependencies are required to run this artifact.
Note that this is soley for information purpose, those do not have to be installed manually.
For a more detailed list we want to refer to the Dockerfile in the sources, where the whole artifact can be reproduced from scratch.
Each of the used tool has a licence within its source files.

Third Party Tools used by QSOLE:

• DepQBF v6.03
• CaDiCaL v2.1.3
• Nenofex v1.1 (Included in DepQBF)
• Picosat v965 (Included in DepQBF)

Needed for Building:

• Docker image ubuntu:24.04
• GCC for C++ (g++) compiler
• CMake