QueraTechnical2026

Environment setup (pip-based)

These steps are intentionally environment-agnostic: you can run them inside either a Conda environment or a virtual environment.

1. Create and activate your environment (Conda or venv).
2. Install uv using pip:

pip install uv

3. From the repository root (this folder), install project dependencies from requirements.txt with uv:

uv pip install -r requirements.txt

Quick note for Windows users

Some Python packages may require native compilation during install. If you see an error like:

Microsoft Visual C++ 14.0 or greater is required

install Microsoft C++ Build Tools and retry the install:

https://visualstudio.microsoft.com/visual-cpp-build-tools/

Project use

This section documents how to run single experiments, how configuration and presets are structured, and how to use the plotting CLI workflow.

Run individual experiments with main.py

Use src/main.py to execute one experiment configuration from the command line.

Description of argument/command	Examples
Run one experiment using positional arguments nb_shots and kernel (x, z, xz)	python .\src\main.py 100 xz
Enable correction mode for xz kernel	python .\src\main.py 200 xz --corrected
Set Pauli channel probabilities with --error_rate PX PY PZ	python .\src\main.py 300 x --error_rate 0.02 0 0
Select faulty qubit index in [0, 6] with --qubits	python .\src\main.py 300 z --qubits 4
Set logical input preparation with --input_state (zero, one, plus, minus, T, H)	python .\src\main.py 200 xz --input_state H

Expected behavior:

• Each command runs the simulator for the requested number of shots.
• A JSON file is written in results by default.
• Result JSON stores top-level metadata and records.

ExperimentConfig and ExperimentPreset

src/experiment_config.py defines two levels of configuration.

• ExperimentConfig is one concrete run definition.
• ExperimentPreset is a sweep template that expands into multiple ExperimentConfig entries.
• Presets are grouped by objective in EXPERIMENT_PRESETS_BY_OBJECTIVE.
• The first-batch preset list is defined by FIRST_BATCH_PRESET_NAMES.

Organization summary:

• Input-state options and validation are defined once and reused by both CLI and kernel binding.
• Presets encode sweep axes: kernels, correction flags, error rates, faulty qubits, input states, and shots.
• expand_preset(...) computes the Cartesian product of sweep axes and returns concrete run configurations.

Add a new configuration or preset

Use this workflow to extend experiments.

1. Add a one-off run configuration by instantiating ExperimentConfig and passing it to main(...).
2. Add a reusable sweep by creating a new ExperimentPreset constant in src/experiment_config.py.
3. Register the preset in EXPERIMENT_PRESETS_BY_OBJECTIVE under the target objective key.
4. Optionally include the new preset name in FIRST_BATCH_PRESET_NAMES if it should run in first-batch mode.
5. Use plotting CLI commands to execute and visualize the new preset.

Minimal Python example for a single config:

from experiment_config import ExperimentConfig
from main import main

cfg = ExperimentConfig(
	nb_shots=150,
	kernel="xz",
	corrected=True,
	error_rate=(0.01, 0.0, 0.01),
	qubits=2,
	input_state="plus",
)

result_path = main(cfg)
print(result_path)

Plotting module CLI

Use src/plotting.py to list presets, run campaign batches, and generate plots.

Description of argument/command	Examples
List preset catalog grouped by objective	python .\src\plotting.py list
Generate plots from existing JSON file or directory with plot	python .\src\plotting.py plot --results-path results --output-dir plots
Run one preset campaign with run-preset PRESET	python .\src\plotting.py run-preset baseline_ideal --result-dir results --output-dir plots
Run all presets in one objective with run-objective OBJECTIVE	python .\src\plotting.py run-objective scaling --result-dir results --output-dir plots
Run first-batch preset set with run-first-batch	python .\src\plotting.py run-first-batch --result-dir results --output-dir plots
Skip plotting and run experiments only using --no-plot	python .\src\plotting.py run-preset localization_all_qubits --no-plot

Expected behavior:

• run-preset, run-objective, and run-first-batch execute one or more experiments and save JSON files in the selected result directory.
• Commands return JSON summaries to stdout.
• Plot commands generate image files only when required metadata and records are available; non-generated plots are reported in the summary.