Qolumbina (version 0.1.0)

Qolumbina (version 0.1.0)#

Qolumbina is a benchmark suite of scalable quantum programs for controlled software testing.

Qolumbina Infrastructure#

License Python Qiskit Pytest

This repository contains the reusable benchmark infrastructure for Qolumbina:

  • quantum benchmark programs under qolumbina/programs;

  • execution, measurement, state-initialization, and data-conversion utilities under qolumbina/utils;

  • unit tests under tests.

The empirical study scripts, figures, tables, and research-question analysis code are kept in the companion repository qolumbina-empirical-study. The Sphinx documentation sources are kept in the companion repository qolumbina-documentation.

Repository Layout#

qolumbina-infrastructure/
  qolumbina/
    programs/        # benchmark program implementations
    utils/           # simulation, execution, measurement, and conversion helpers
  tests/             # pytest-based test suite
  pyproject.toml     # editable-install metadata
  environment.yml    # conda environment definition

The Python package is named qolumbina. For example:

from qolumbina.utils import QuantumSystemSimulation
from qolumbina.programs.comparator import IntegerComparatorGreedy

Setup#

The recommended conda environment name is qolumbina.

Using conda:

conda env create -f environment.yml
conda activate qolumbina

If the environment already exists:

conda activate qolumbina
python -m pip install -e .

The editable install is important when this repository is used by qolumbina-empirical-study, because it makes the qolumbina package importable outside this repository.

Benchmark Registry#

To print an overview of the benchmark suite, run:

python -m pytest tests\programs\test_benchmark_registry.py -s

Documentation#

Throughout the documentation, the most significant bit and qubit are written first, while the least significant bit and qubit are written last and indexed with 0. For a computational basis state |x>_n,

|x>_n = |q_{n-1} ... q_1 q_0>

where x is the decimal value of the binary string q_{n-1} ... q_0.

The Sphinx documentation is maintained in the sibling qolumbina-documentation repository. With both repositories checked out under the same parent directory, rebuild the HTML documentation locally from the documentation repository:

cd ..\qolumbina-documentation
conda env create -f environment.yml
conda activate qolumbina_doc
make.bat clean
make.bat html

To update without cleaning the previous build:

make.bat html

Testing#

Run the full test suite:

python -m pytest

Run a specific test file:

python -m pytest tests\utils\test_backend_execution.py

Useful pytest options:

python -m pytest tests\utils\test_backend_execution.py -v -s --log-cli-level=INFO

Coverage#

Run tests with coverage:

coverage run -m pytest

Generate an HTML coverage report for benchmark programs:

coverage html --include="qolumbina/programs/*" --omit="qolumbina/programs/__init__.py,qolumbina/programs/benchmark_registry.py,qolumbina/programs/monte_carlo/_common/mc_utils.py,qolumbina/programs/shor_algorithm/_common/shor_postprocessing.py,*/__init__.py"

Relationship to the Empirical Study Repository#

When working with both repositories locally, install this repository first:

cd qolumbina-infrastructure
conda activate qolumbina
python -m pip install -e .

Then run the empirical study repository from its source tree:

cd ..\qolumbina-empirical-study

The empirical study code can then import this infrastructure through the qolumbina package.

Detailed Documentation#

The documentation only includes contents for benchmark programs and and related scripts. Code and docs for tests and empirical results are not included.

Contents:

Contents