classiq-library: quantum algorithms and circuit synthesis with the Classiq SDK

@qfunc and synthesize: how Classiq turns decorated Python into quantum circuits

Writing a quantum program in Classiq starts with a decorated Python function. The @qfunc decorator marks the function as quantum, and its body uses Classiq's type system (QBit, QNum, QArray and others) alongside operations like allocate, X, H and RY. That decorated function describes the logic; it does not yet produce a runnable circuit.

Converting the logic into a circuit happens in a separate step. synthesize() takes the decorated main function and returns a quantum_program object representing physical qubits and the gates between them. show() opens the circuit visualization. execute() submits the compiled circuit for running, and the README lists simulation as the default target. Connecting to physical quantum hardware is an option but not the default path.

Those 3 steps, synthesize, show and execute, appear in what the README calls the simplest example: 1 qubit and a single X gate:

from classiq import *

NUM_QUBITS = 1


@qfunc
def main(res: Output[QBit]):
    allocate(NUM_QUBITS, res)
    X(res)


quantum_program = synthesize(main)

show(quantum_program)

result = execute(quantum_program).result_value()
print(result.dataframe)

Running this example produces a table with res=1, count=2048, probability=1 and bitstring=1. The README documents what each line does, with links to the Classiq specification pages covering types, allocate and quantum operators for readers who want to go deeper.

pip install classiq versus the no-install GUI at platform.classiq.io

For the Python SDK:

pip install classiq

After cloning the repository, an alternative is:

pip install --upgrade -r requirements.txt

requirements.txt lists classiq and jupyter as its 2 entries. Skipping pip install classiq is possible: platform.classiq.io hosts a GUI interface where examples run entirely through the browser, with no local Python environment or package installation involved.

The repository stores demos in 2 formats with different consumption paths. Quantum model files (.qmod) feed the platform's synthesis pipeline at platform.classiq.io/synthesis, where you upload the file and synthesis runs on Classiq's servers. Interactive notebooks (.ipynb) embed the Python calls and require the classiq package installed and connected to the platform. Using a .qmod file in a notebook environment or pasting .ipynb code into the Synthesis tab produces no output because neither route supports the other's format.

The synthesis engine offers 2 optimization modes: minimal qubits or minimal circuit width

Synthesis is where Classiq's approach diverges from writing quantum gates by hand. The engine offers 2 configuration targets. One minimizes physical qubit count by reusing qubits across time, which keeps the hardware footprint small at the cost of longer circuits. The other minimizes circuit depth, keeping fewer sequential operations, which tends to reduce noise accumulation on physical hardware but may require more qubits to do it.

Those 2 optimization goals conflict. Minimizing qubit count generally lengthens the circuit by forcing operations to share qubits sequentially. Minimizing circuit width may require more qubits to keep operations parallel. Classiq makes that trade-off explicit as a configuration choice rather than applying a single fixed strategy, though the README was truncated before documenting how to select between the 2 modes. The Classiq documentation at docs.classiq.io covers synthesis configuration.

The higher-level programming model shows its benefit in more complex examples. A Deutsch-Jozsa snippet in the README passes a QCallable predicate to hadamard_transform and an oracle without specifying each gate individually. An angle-encoding snippet uses repeat() with a lambda over array indices, which the synthesis step expands into a sequence of RY rotations at compile time.

Repository structure: algorithms, applications, QML and benchmarking in named folders

Content is organized under named top-level directories. algorithms/ and applications/ hold the core examples. A functions/ directory holds reusable quantum function definitions. tutorials/ provides structured walkthroughs. benchmarking/ and community/ also appear at the top level. Repository topics include quantum-machine-learning, quantum-optimization and quantum-synthesis alongside quantum-algorithms.

A CITATION.bib file at the root provides a BibTeX entry pointing to an arXiv preprint at doi:10.48550/arXiv.2412.07372 for citation in academic work. CONTRIBUTING.md and CODE_OF_CONDUCT.md are present. GitHub contribution history shows more than 100 people have submitted to the library.

Release cadence has been frequent: version 1.31 published on 2026-10-05, 1.30 on 2026-09-29 and 1.28.0 on 2026-08-31. That is 3 releases in just over 5 weeks. The version numbers match those of the Classiq platform, which suggests the library is versioned to track the platform rather than on its own independent schedule.

AI agent integration links out to docs, and the library itself has no agent-specific notebooks

One README section covers using the Classiq library with AI agents. Its content is a single link to docs.classiq.io/latest/user-guide/ai/, with no in-repository example. Whether that section describes an MCP server, a tool API or another integration mechanism is not stated in the README.

That brief treatment reflects the library's function as a collection of SDK examples, not a documentation source for the SDK's own capabilities. Installation parameters, synthesis settings and execution targeting are handled by the classiq package; the library notebooks call into that package and depend on it matching the current platform version.

Version alignment carries a practical implication. Each release (1.28.0, 1.30, 1.31) matches a platform version, and a notebook written for 1.28.0 may depend on behavior that changed by 1.31. No per-notebook changelog appears in the repository. The top-level release notes are the only record of what changed between versions. That tight coupling of library and platform versions means the two cannot drift independently: adopting a newer platform version means the library notebooks should also come from that release.

MIT licence on the library code, but synthesis and execution go through Classiq's cloud

LICENSE.txt at the repository root confirms the MIT licence. Code in the library is freely reusable and modifiable. The constraint on adoption is different: the classiq Python package and the Classiq cloud platform are required for synthesis and execution, and neither is part of this repository.

The GUI path makes that dependency explicit. Going to platform.classiq.io and using the browser-based interface is the route the README describes for users who want no local installation, which means synthesis runs on Classiq's servers in both the GUI and the SDK case. The README does not document any option for running synthesis locally without a platform connection.

For organizations with strict data egress policies or air-gapped environments, the MIT licence on the examples does not remove the cloud dependency. pyproject.toml and requirements.txt are in the repository but they configure the Python tooling (isort, black) and list the pip dependencies rather than providing an offline synthesis path.

Where classiq-library is the wrong starting point: open-source toolchains and gate-level work

Classiq targets users who want to describe quantum programs at a high functional level and have the platform handle qubit routing and gate optimization. For that use case, the library is a direct collection of worked examples covering QML, optimization and foundational algorithms.

For engineers whose constraint is staying within open-source quantum computing frameworks, it is the wrong tool. Qiskit and Cirq both support local compilation and execution on simulators without any cloud dependency, and a circuit written for either runs entirely offline. Moving a Classiq notebook to Qiskit or Cirq requires rewriting the Qmod types and SDK calls, not just reconfiguring a backend.

A second mismatch is the programming model itself. Classiq's abstractions sit above the gate level, which can make it harder to reason about what circuit the synthesis engine will produce for a given function. show() and the Studio tab on the platform expose the synthesized output, but the library notebooks present the high-level functional code and do not routinely show the resulting gate sequence alongside it. Users whose work requires verifying the exact circuit structure before running it on hardware have an extra step: synthesize, then inspect the circuit in the platform before trusting the output. The library covers the programming step; validation of what the synthesis produced is a separate workflow the notebooks leave to the reader.

Editorial conclusion

Classiq Library suits researchers, developers and students who want to write quantum programs at a high level of abstraction and let a synthesis engine handle circuit optimization. Skip it if your requirement is staying entirely within open-source frameworks like Qiskit or Cirq, since synthesis and execution run through Classiq's cloud platform rather than local compilation. Before committing, verify that your platform account has access to the synthesis features the notebooks use, and run the 1-qubit example from the README to confirm pip install classiq and your platform connection both work.

Frequently asked questions

Official sources

1. Classiq/classiq-library on GitHub
2. License: MIT
3. Project website
4. README
5. Releases