quast_decisiontree

QuaST Decision Tree

A highly modular package enabling the partial automation of setting up optimization solutions with quantum-assisted algorithms — from problem formulation to algorithm selection and hyperparameter tuning. Its main strength is flexibility: the same tree machinery adapts to a wide range of tasks by swapping problem classes, algorithms, and backends.

Overview

The high-level workflow is:

Define a decision tree in a YAML config (see examples/configs/demo_tree.yaml).
Run it, either from the command line (python -m quast_decisiontree) or from a script, Jupyter notebook, etc. (see examples/basic_usage.ipynb).

Key characteristics:

Modes: fully automatic (auto) or interactive (confirm/manual), configurable via recommendation_mode.
Problem instances: formulated as human-readable JSON files (see examples/instances/, covering MaxCut, QUBO, and TSP at various sizes).
Algorithms: hybrid, classical, and quantum, with backends loaded through extension modules.
Queries: allow automation without restricting the available paths.
Paths: specific decision paths can be pinned via a YAML file (see examples/paths/).
Output: each run creates an output folder containing the configuration, result files, and logs.

For feedback and inquiries, contact Benedikt Poggel (benedikt.poggel@iks.fraunhofer.de).

Installation

This is a uv project. It requires Python 3.11 (>=3.11, <3.12).

With uv (recommended)

git clone git@gitlab.cc-asp.fraunhofer.de:quast_mqv/decisiontree.git
cd decisiontree
uv sync

uv sync creates a virtual environment and installs the project with its locked dependencies. To include the development or documentation tooling, add the respective group:

uv sync --group dev    # tests, linting, pre-commit
uv sync --group docs   # MkDocs and plugins

With pip

git clone git@gitlab.cc-asp.fraunhofer.de:quast_mqv/decisiontree.git
cd decisiontree
python -m pip install .

Structure

The package lives under src/quast_decisiontree/:

core — core machinery: DecisionTree (runner.py), nodes (node.py), queries (query.py), backends (backend.py), path handling (path.py), problem data (problem_data.py)
nodes — concrete decision-tree nodes (formulation, algorithm selection/setup/execution, backend and optimizer configuration). Also useful as example node implementations.
problems — problem classes (MaxCut, QUBO, TSP), the input parser, and the shared OptimizationProblem base.
algorithms — classical/ (brute force, SciPy optimizers, tabu), hybrid/ (variational, Qrisp QAOA/VQE), and quantum/ (LR-QAOA), plus ansätze and mixers.
utils — formatting, general helpers, and QUBO conversions.

Command-Line Usage

Run the tree with:

python -m quast_decisiontree

With no arguments, the tree loads its default configuration and chooses default options at every decision, requiring minimal input. Behavior is controlled by the following flags and options.

Flags

Flag	Alt	Function
`--verbose`	`-v`	Sets the log level to debug
`--no-validate`		Skips validation of the decision tree setup

Options

Option	Alt	Function
`--instance`	`-i`	Path of a problem instance file to load.
`--tree`	`-t`	YAML config defining the decision tree setup. Defaults to `examples/configs/demo_tree.yaml`.
`--config`	`-c`	YAML config updating tree behavior.
`--path`	`-p`	YAML file pinning or influencing the decisions taken. A similar file is written after each run.

Precedence: -c values override -t values; explicit flags (e.g. -v) override both.

Programmatic Usage

The tree can be driven directly from a script or notebook. See examples/basic_usage.ipynb for the full flow; the core steps are:

import os
import yaml

from quast_decisiontree import DecisionTree

### Construct from a YAML config path (or a dict). Use log_level="debug" for more output.

dt = DecisionTree(config="./configs/demo_tree.yaml", log_level="info")

### Visualize the tree.

dt.show()

### Run on a problem instance.

instance_path = os.path.join(os.getcwd(), "instances", "tsp_4.json")
dt.run(problem_instance=instance_path)

### Generate a YAML detailing how paths can be specified

path_spec = dt.generate_path_spec()

### Re-run with a pinned path loaded from a YAML file.

path_path = os.path.join(os.getcwd(), "paths", "TSP_LRQAOA.yaml")
with open(path_path) as file:
    path_dict = yaml.safe_load(file)

dt.run(path=path_dict)

run() accepts problem_instance, path, and further keyword arguments; path may be a dict (as above) or a path to a YAML file.

Configuration

The tree ships with a standard config at src/quast_decisiontree/core/standard_config.yaml. A user-provided config (via -c or the config= argument) is merged on top of it, and command-line flags take highest precedence.

Configuration Keys

Key	Description	Default
`data_folder`	Folder for files generated by the tree. `~` expands to the user's home.	`~/dt_data/`
`verbosity`	General verbosity level for tree output.	`0`
`log_level`	Logging level: `debug`, `info`, `warning`, `error`, `critical`.	`info`
`recommendation_mode`	Automation level: `auto` accepts all recommendations; `confirm`/`manual` require confirmation.	`auto`
`saving_policy`	`discard_if_processed` drops processed result keys before saving; other values keep all keys.	`discard_if_processed`
`no_save_keys`	Keys to exclude from the saved output. Nodes may append to this list under `discard_if_processed`.	`[]`
`result_summary_verbosity`	Verbosity of the terminal result summary. `0` suppresses it, `10` prints a short summary, larger prints the full result.	`10`
`auto_execute`	Whether algorithm execution runs automatically once configured.	`true`

Output Files

Each run writes to a subfolder of data_folder:

File	Contents
`path.yaml`	The path taken / path info for the run.
`problem_data.json`	The problem data accumulated during the run.
`result.json`	The final result dictionary.
`run_config.yaml`	The full configuration used for the run.
`run.log`	The run-specific log.

Documentation

API documentation is built with MkDocs and the mkdocstrings plugin. Build it locally with:

uv run --group docs mkdocs serve

Contributing

See CONTRIBUTING.md. Changes are tracked in CHANGELOG.md.

Licensing Notice

This software is subject to the terms and conditions of the MIT license (https://mit-license.org/). See LICENSE.txt.

Contact: benedikt.poggel@iks.fraunhofer.de