qilisdk 0.3.1

QiliSDK is Qilimanjaro Quantum Tech's open-source Python framework for designing and executing analog, digital, and hybrid quantum algorithms. Its modular structure unifies circuit-based and Hamiltonian-based workflows within a single API. It provides high-level abstractions for gates, circuits, Hamiltonians, and more, while remaining fully backend-agnostic allowing a seamless switch between CPU, GPU, or QPU execution. Fast CPU simulation can be done locally using QiliSim, our quantum simulator written in C++.

Why QiliSDK?

There are several other quantum frameworks out there, but QiliSDK has many unique advantages:

• We use a single framework for digital, analog and hybrid workflows, running on CPU, GPU or a Qilimanjaro QPU. Everything is one unified stack.
• All core functionality is included in the package, with performance critical parts pre-compiled from C++, all easily installable with a single pip install command.
• At the highest level we have our Model class, which lets you write problems in their simplest form and simplify the conversion to quantum jobs.
• At a slightly lower level we have our functionals, describing specific quantum tasks: VariationalProgram, AnalogEvolution, DigitalPropagation and even QuantumReservoirs.
• Meanwhile, on the more fundamental side, we have symbolic Hamiltonians and Expression classes, fully customizable analog Schedules, all standard quantum gates, parametrizable objects, our quantum object class QTensor which has a wide range of quantum information utilities, and many more.

Installation

QiliSDK is available via PyPI:

pip install qilisdk

For other installaton options, see the docs.

Usage

Here are just a few examples to get you started, for tutorials and full documentation, please see the docs.

Digital Circuits

To create a simple quantum circuit and simulate it on your CPU:

from qilisdk.digital import Circuit, H, RX, CNOT
from qilisdk.functionals import DigitalPropagation
from qilisdk.readout import Readout
from qilisdk.backends import QiliSim

# Create a simple two-qubit circuit
circuit = Circuit(2)
circuit.add(H(0))
circuit.add(RX(1, theta=3.14))
circuit.add(CNOT(0, 1))

# Set up the quantum task
functional = DigitalPropagation(circuit)
readout = Readout().with_sampling(1000)

# Simulate it with CPU
backend = QiliSim()
results = backend.execute(functional, readout)
print(results)

Analog Evolution

To create a linear interpolation between an initial and final Hamiltonian, then simulate it using your GPU:

from qilisdk.analog import Schedule, X, Z
from qilisdk.functionals import AnalogEvolution
from qilisdk.readout import Readout
from qilisdk.core import InitialState
from qilisdk.backends import QiliSim, AnalogMethod, ExecutionConfig

# Construct the interpolation between Hamiltonians
initial_hamiltonian = -X(0) - X(1)
final_hamiltonian = Z(0) + Z(1) + 0.5 * Z(0) * Z(1)
schedule = Schedule.linear(initial_hamiltonian, final_hamiltonian, total_time=10.0, dt=0.5)

# Set up the quantum task
functional = AnalogEvolution(schedule, initial_state=InitialState.UNIFORM)
readout = Readout().with_expectation([final_hamiltonian])

# Simulate it with GPU
config = ExecutionConfig(gpu=True)
method = AnalogMethod.variational_annealing()
backend = QiliSim(execution_config=config, analog_simulation_method=method)
results = backend.execute(functional, readout)
print(results)

Quantum Reservoirs

import numpy as np
from qilisdk.backends import QiliSim
from qilisdk.core import ket
from qilisdk.digital import Circuit, U2
from qilisdk.functionals.quantum_reservoirs import QuantumReservoir, ReservoirInput, ReservoirLayer
from qilisdk.analog import Schedule, X, Z
from qilisdk.readout import Readout

# Set up the quantum reservoir
pre_processing = Circuit(2)
pre_processing.add(U2(1, phi=ReservoirInput("phi_1", 0.1), gamma=ReservoirInput("gamma_1", 0.1)))
res_layer = ReservoirLayer(
    evolution_dynamics=Schedule(
        hamiltonians={"h": Z(0) + Z(1) + Z(0) * Z(1) + 0.5 * (X(0) + X(1))},
        total_time=1.0,
        dt=0.1,
    ),
    input_encoding=pre_processing,
    qubits_to_reset=[1],
)
reservoir = QuantumReservoir(
    initial_state=(np.random.rand() * ket(0, 0) + np.random.rand() * ket(1, 1)).unit(),
    reservoir_layer=res_layer,
    input_per_layer=[
        {"phi_1": 0.2, "gamma_1": 0.1},
        {"phi_1": 0.3, "gamma_1": 0.2},
        {"phi_1": 0.4, "gamma_1": 0.3},
    ],
)

# Simulate it with CPU
results = QiliSim().execute(
    reservoir,
    Readout().with_expectation(observables=[Z(0), Z(1), Z(0) * Z(1)]),
)
print(results.get_expectation_values())

Benchmarks

Development Guide

This section covers how to set up a local development environment for qilisdk, run tests, enforce code style, manage dependencies, and contribute to the project. We use a number of tools to maintain code quality and consistency:

• uv for dependency management and packaging.
• ruff for linting and code formatting.
• ty for language server and static type checking.
• towncrier for automated changelog generation.

Setup & Dependency Management

For instructions on how to compile from source and set up the development environment, see the docs. Following those instructions will setup a virtual environment (venv) in which you can run all other development tools (e.g. tests, linting).

Testing

We use pytest for the test suite. Once you have your venv set up, run the Python unit tests using:

pytest tests/unit_python

To run the integration tests (bigger tests which use the full QiliSDK stack and might take a bit longer):

pytest tests/integration

To run the CUDA, qutip, and SpeQtrum backend tests, install the optional dependencies first (e.g., uv sync --all-groups --extra all-cu13).

To run the C++ tests, you first need to recompile with C++ testing enabled:

uv sync --reinstall -Ccmake.define.tests=ON

The C++ testing suite can then be ran using:

./tests/unit_cpp/test_cpp

Linting & Formatting

We enforce code style and best practices using ruff. ruff handles:

• Lint checks (similar to flake8, pylint).
• Formatting (similar to black or isort).
• Automated fixes for certain issues.

To check linting:

ruff check

To automatically fix lint issues (where possible):

ruff check --fix

To automatically format your code:

ruff format

(We recommend running ruff check --fix and ruff format before committing any changes.)

To check the C++ code, compile with the tidy flag:

uv pip install -v -e ./ -Ccmake.build-type=Debug -Ccmake.define.tidy=ON

This will run clang-tidy as well as a number of C++ compiler flags for debugging. For this you will need clang-tidy installed, which can be done on Debian/Ubuntu with:

sudo apt-get install clang-tidy

It may also throw an error about not being able to find omp.h, if so, try:

sudo apt-get install libomp-dev

For ease of use there are also a number of bash scripts in the "scripts" folder, for instance to generate coverage reports or to run all pre-commit checks.

Type Checking

We use ty for static type checking. This helps ensure our code is type-safe and maintainable.

ty check

(We encourage developers to annotate new functions, classes, and methods with type hints.)

Helpful Scripts

For ease of use there are also a number of scripts in the scripts/ directory. Each of these generates a .log file with the same name as the script (checks.sh generates checks.log and so on).

To run all pre-commit checks (e.g. linting/tests):

bash scripts/checks.sh

To check all of the code blocks in the documentaton:

bash scripts/docs.sh

To generate a full coverage report of all code, run:

bash scripts/coverage.sh

This will generate a html file which you can open in your browser to see which lines (in both the C++ and Python) are covered by the tests. We aim for 100% coverage!

Changelog Management

We manage our changelog using towncrier. Instead of editing CHANGELOG.md directly, each pull request includes a small news fragment file in the changes/ directory describing the user-facing changes.

For example, if you create a PR with id #123 adding a new feature, you add:

changes/123.feature.md

Inside this file, you briefly describe the new feature:

Added a new `cool_feature` in the `qilisdk.backends` module.

These change fragments should be written in Markdown, so use standard Markdown syntax. Also, instead of manually creating the file, you can run:

towncrier create --no-edit

When we cut a new release, we update the version in pyproject.toml file and run:

towncrier

This aggregates all the news fragments into the CHANGELOG.md under the new version and removes the used fragments.

Contributing

We welcome contributions! Here’s the workflow:

1. Fork this repository and create a feature branch.
2. Write your changes (code, docs, or tests).
3. Add a news fragment in changes/ describing the user-facing impact.
4. Run the following checks locally:

   bash scripts/checks.sh
   

5. Commit and push your branch to your fork.
6. Open a Pull Request against the main branch here.

Our CI will run tests, linting, and type checks. Please make sure your branch passes these checks before requesting a review.

License

This project is licensed under the Apache License.

Acknowledgments

• Thanks to all the contributors who help develop qilisdk!
• uv for making dependency management smoother.
• ruff, ty, and towncrier for their amazing tooling.

Feel free to open issues or pull requests if you have questions or contributions. Happy quantum coding!