## File: README.md

[](https://opensource.org/license/mit)
[](https://badge.fury.io/py/classiq)

[](https://pepy.tech/project/classiq)
[](https://doi.org/10.48550/arXiv.2412.07372)



# Classiq: End to End Platform for Developing Quantum Software

Classiq provides a powerful platform for **designing, optimizing, analyzing, and executing** quantum programs. This repository hosts a comprehensive collection of quantum functions, algorithms, applications, and tutorials built using the Classiq SDK and our native Qmod language.

Whether you're a researcher, developer, or student, Classiq helps you simplify complex quantum workflows and seamlessly transform quantum logic into optimized circuits by leveraging our **high-level functional design** approach. A user-friendly interface allows you to model, simulate, visualize, and execute quantum programs across various quantum hardware platforms.

<hr> 



<hr>

[](https://github.com/Classiq/classiq-library/graphs/contributors)

Classiq enjoys the support of more than 100 contributors!

Feel free to join and submit your own fantastic quantum algorithm!

[](https://short.classiq.io/join-slack)

<hr>

Want to cite classiq?
[](https://citation.doi.org/format?doi=10.48550/arXiv.2412.07372&style=bibtex)

<hr>

# Installation

[](https://platform.classiq.io)
[](https://platform.classiq.io/studio)

Working with Classiq's latest GUI requires no installations!
Just head over to [Classiq's platform](https://platform.classiq.io/) and follow the examples below over there :)

If you'd rather work programmatically using Python, Classiq also provides an SDK, which can be installed as follows:

```bash
pip install classiq
```

Alternatively, after cloning this repository, you may run

```bash
pip install --upgrade -r requirements.txt
```

## Running This Repository's Demos

This repository has 2 kinds of demos: `.qmod` and `.ipynb`.

The `.qmod` files are intended for usage with [Classiq's platform](https://platform.classiq.io/).
Upload those `.qmod` files into the [Synthesis tab](https://platform.classiq.io/synthesis)

The `.ipynb` files are intended to be viewed inside [JupyterLab](https://jupyter.org/) (or by programs that support such files, such as VSCode).

## Use the library with AI agents

See the [Classiq documentation](https://docs.classiq.io/latest/user-guide/ai/) to learn how to use the Classiq library with AI agents.

# Create Quantum Programs with Classiq

The simplest quantum circuit has 1 qubit and has a single `X` gate.

Using Classiq's SDK, it would look like this:

```python
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)
```

|     | res | count | probability | bitstring |
| --: | --: | ----: | ----------: | --------: |
|   0 |   1 |  2048 |           1 |         1 |

Let's unravel the code above:

1. `def main` : We define the logic of our quantum program. We'll expand on this point soon below.
2. `synthesize` : We synthesize the logic we defined into a Quantum Program. From a logical definition of quantum operations, into a series of quantum gates.
3. `execute` : Executing the quantum program. Can be executed on a physical quantum computer, or on simulations. Defaults to simulations.

## 1) Defining the Logic of Quantum Programs

The function above had 4 lines:

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

The 1st line states that the function will be a quantum one. [Further documentation](https://docs.classiq.io/latest/qmod-reference/language-reference/functions/).

The 2nd line defines the type of the output. [Further examples on types](https://docs.classiq.io/latest/qmod-reference/language-reference/classical-types/)

The 3rd line allocates several qubits (in this example, only 1) in this quantum variable. [Further details on allocate](https://docs.classiq.io/latest/qmod-reference/language-reference/quantum-variables/)

The 4th line applies an `X` operator on the quantum variable. [Further details on quantum operators](https://docs.classiq.io/latest/qmod-reference/language-reference/operators/)

### More Examples

Initializing $\ket{-}$ state:

```python
@qfunc
def prep_minus(out: Output[QBit]) -> None:
    allocate(1, out)
    X(out)
    H(out)
```

A part of the Deutsch Jozsa algorithm (see the full algorithm [here](/algorithms/foundational/deutsch_jozsa/deutsch_jozsa.ipynb))

```python
@qfunc
def deutsch_jozsa(predicate: QCallable[QNum, QBit], x: QNum) -> None:
    hadamard_transform(x)
    my_oracle(predicate=lambda x, y: predicate(x, y), target=x)
    hadamard_transform(x)
```

A part of a QML encoder (see the full algorithm [here](/algorithms/QML/quantum_autoencoder/quantum_autoencoder.ipynb))

```python
@qfunc
def angle_encoding(exe_params: CArray[CReal], qbv: Output[QArray[QBit]]) -> None:
    allocate(exe_params.len, qbv)
    repeat(
        count=exe_params.len,
        iteration=lambda index: RY(pi * exe_params[index], qbv[index]),
    )
```

For more, see this repository :)

## 2) Synthesis : Logic to Quantum Program

This is where the magic happens.
Taking a the `main` function, which is a set of logical operations, and synthesizing it into physical qubits and the gates entangling them, is not an easy task.

Classiq's synthesis engine is able to optimize this process, whether by requiring the minimal amount of physical qubits, thus reusing as many qubits as possible, or by requiring minimal circuit width, thus lowering execution time and possible errors.

## 3) Execution

Classiq provides an easy-to-use way to execute quantum programs, and provides various insights of the execution results together with a familiar interface: `pandas.DataFrame`.

## Diagrams

1 diagram is worth a thousand words

```mermaid
flowchart
    IDEInput[[Classiq IDE](https://platform.classiq.io/)]

    SDKInput[[Classiq python SDK](https://docs.classiq.io/latest/sdk-reference/)]

    Model[[Quantum Model](https://docs.classiq.io/latest/qmod-reference/)]

    Synthesis[[Synthesis Engine](https://docs.classiq.io/latest/classiq_101/classiq_concepts/optimize/)]

    QuantumProgram[Quantum Program]

    Execution[[Execution](https://docs.classiq.io/latest/classiq_101/classiq_concepts/execute/)]

    Analyze[[Analyze & Debug](https://docs.classiq.io/latest/classiq_101/classiq_concepts/analyze/)]

    IBM[IBM]
    Amazon[Amazon Braket]
    Azure[Azure Quantum]
    Nvidia[Nvidia]


    IDEInput --> Model;
    SDKInput --> Model;
    Model --> Synthesis;
    Synthesis --> QuantumProgram;
    ExternalProgram <--> QuantumProgram;
    QuantumProgram --> Analyze;
    QuantumProgram --> Execution;
    Execution --> IBM
    Execution --> Amazon
    Execution --> Azure
    Execution --> Nvidia
```

# Build Your Own

With Classiq, you can build anything. Classiq provides a powerful modeling language to describe any quantum program, which can then be synthesized and executed on any hardware or simulator. Explore our [Documentation](https://docs.classiq.io/latest/) to learn everything.

## SDK : Classiq's Python Interface

### Example: Calculating 3+5 with Classiq

```python
from classiq import *


@qfunc
def prepare_3(var: Output[QArray]) -> None:
    allocate(2, var)
    X(var[0])
    X(var[1])


@qfunc
def prepare_5(var: Output[QArray]) -> None:
    allocate(3, var)
    X(var[0])
    X(var[2])


@qfunc
def main(res: Output[QNum]) -> None:
    a = QNum("a")
    b = QNum("b")

    prepare_3(a)
    prepare_5(b)

    res |= a + b  # 3+5 should be 8
    drop(a)
    drop(b)


quantum_program = synthesize(main)

show(quantum_program)

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

|     | res | count | probability | bitstring |
| --: | --: | ----: | ----------: | --------: |
|   0 |   8 |  2048 |           1 |      1000 |

For some pre-built state preparations, read [here](https://docs.classiq.io/latest/qmod-reference/api-reference/functions/open_library/state_preparation/?h=state)

## IDE : Classiq's Platform

Every example found in this repository can also be accessed via [Classiq's platform](https://platform.classiq.io/), in the [`model`](https://platform.classiq.io/dsl-synthesis) tab, under the same folder structure.

Additionally, one may write their own model in the model editor (highlighted in green) or upload his own model (highlighted in red)



### Example: 3+5 with Classiq

1. Create a model (paste in the [`model`](https://platform.classiq.io/dsl-synthesis) tab)

```
qfunc get_3(output x: qbit[]){
 allocate(2,x);
 X(x[0]);
 X(x[1]);
}

qfunc get_5(output x: qbit[]){
 allocate(3,x);
 X(x[0]);
 X(x[2]);
}

qfunc main(output res: qnum){
 a: qnum;
 b: qnum;
 get_3(a);
 get_5(b);
 res = a + b;
 drop(a);
 drop(b);

}
```

2. Press Synthesize:







3. Press Execute:







4. Press Run:







5. View Results:







<hr>

Have questions? Feedback? Something to share?
Welcome to join our open [Slack Community](https://short.classiq.io/join-slack)

---

## File: algorithms/README.md

# Quantum Algorithms Implementations

This directory gathers implementations for both canonical and recent works, that
include concrete quantum algorithms. Researchers are invited to add their work
to the table. We also encourage the community to add implementations to papers listed
in the table or to add new ones.

The directory is organized into multiple subject areas:

**Amplitude Amplification and Estimation** - Includes variants of amplitude amplification and
estimation algorithms, which generalize Grover’s search to boost the probability of measuring
marked states and achieve a quadratic speedup—finding a state of initial probability
$𝑝$
p with near certainty using $O(1/
\sqrt{p})$ iterations.

**Foundational** - Fundamental quantum algorithms, providing the foundations for future advancements
and demonstrating query complexity advantages.

**Hamiltonian Simulation** - Advanced methods to simulate physical systems,
including product-formula decompositions and block-encoding–based techniques such as QSP,
qubitization, and QSVT.

**Number Theory and Cryptography** - Contains quantum algorithms for number-theoretic
problems that achieve dramatic speedups over classical methods and underpin cryptographic
attacks on widely used schemes such as RSA, elliptic-curve cryptography, and Diffie–Hellman.

**Quantum Machine Learning** - Hybrid quantum–classical machine learning algorithms that
integrate parameterized quantum circuits with classical optimization frameworks to perform
tasks such as classification, generative modeling, and data compression,

**Quantum Differential Equation Solvers** - Shows how partial differential equations and dynamical evolution
problems can be mapped to linear systems or block-encoded operators and solved with quantum hardware,
to enable efficient scientific and engineering simulations.

**Quantum Linear Solvers** - Brings together principal quantum algorithms for solving linear systems—including
adiabatic approaches, HHL, QSVT-based matrix inversion, and variational methods.

**Quantum Phase Estimation** - Demonstrates how eigenvalues of Hermitian operators can be extracted via controlled
unitary evolution using techniques such as Trotterized simulation and qubitization-based block-encoding,
with applications to quantum chemistry and advanced linear algebra algorithms.

**Quantum Primitives** - Provides core quantum algorithmic primitives—such as the Hadamard test, Swap test, and
Generalized Quantum Signal Processing (GQSP)—that act as modular building blocks for higher-level algorithms

**Quantum State Preparation** - Presents advanced quantum state preparation techniques—including adaptive variational
methods such as ADAPT-VQE and block-encoding–based Gibbs state generation.

**Quantum Walks** - Demonstrates discrete quantum walk implementations, including explicit comparisons with classical
random walks and specialized constructions for structured graphs.

**Search and Optimization** - Showcases quantum algorithms for unstructured search and combinatorial
optimization—including Grover’s amplitude amplification,
Decoded Quantum Interferometry, and variational frameworks such as QAOA and Grover-based mixers.

A representative selection of algorithms is presented below:



| Algorithm | Paper Name | Implementations | Short Description |
| --- | --- | --- | --- |
| Shor | [Polynomial-Time Algorithms for Prime Factorization and Discrete Logarithms on a Quantum Computer](https://arxiv.org/abs/quant-ph/9508027) | [Prime Factorization](number_theory_and_cryptography/shor/shor.ipynb)
          [Discrete Logarithm](number_theory_and_cryptography/discrete_log/discrete_log.ipynb) | Shor's algorithm for prime factorization and discrete logarithms |
| Grover | [A fast quantum mechanical algorithm for database search](https://arxiv.org/abs/quant-ph/9605043) | [Grover search for a 3-SAT problem](search_and_optimization/grover/grover.ipynb) | Grover's algorithm for fast database search |
| HHL | [Quantum algorithm for solving linear systems of equations](https://arxiv.org/abs/0811.3171) | [HHL Implementation](quantum_linear_solvers/hhl/hhl.ipynb) | HHL algorithm for solving linear systems |
| QAOA | [A Quantum Approximate Optimization Algorithm](https://arxiv.org/abs/1411.4028) | [Max Cut Problem](search_and_optimization/QAOA/qaoa.ipynb) | QAOA for combinatorial optimization problems |
| VQE | [A variational eigenvalue solver on a quantum processor](https://arxiv.org/abs/1304.3061) | [VQE Implementation for molecule ground state solving](../applications/chemistry/molecular_energy_curve/molecular_energy_curve.ipynb) | Variational Quantum Eigensolver (VQE) for finding eigenvalues |
| Quantum Walk (Glued Trees) | [Exponential quantum speedup in simulating coupled classical oscillators](https://arxiv.org/abs/2303.13012) | [Glued Trees Implementation](quantum_walks/glued_trees/glued_trees.ipynb) | Exponential speedup in solving system of coupled harmonic oscillators |
| Deutsch–Jozsa | [Rapid solution of problems by quantum computation](https://royalsocietypublishing.org/doi/epdf/10.1098/rspa.1992.0167) | [Deutsch-Jozsa Implementation](foundational/deutsch_jozsa/deutsch_jozsa.ipynb) | Deutsch-Jozsa algorithm for rapid problem solving |
| QSVT | [Quantum singular value transformation and beyond: exponential improvements for quantum matrix arithmetics](https://arxiv.org/abs/1806.01838) | [QSVT matrix inversion](quantum_linear_solvers/qsvt_matrix_inversion/qsvt_matrix_inversion.ipynb)
          [QSVT fixed point amplitude amplification](amplitude_amplification_and_estimation/qsvt_fixed_point_amplitude_amplification/qsvt_fixed_point_amplitude_amplification.ipynb) | Introduction of the QSVT Algorithmic framework and its applications |
| Simon | [On the Power of Quantum Computation](https://epubs.siam.org/doi/10.1137/S0097539796298637) | [Simon's Algorithm Implementation](foundational/simon/simon.ipynb) | Simon's algorithm demonstrating quantum computational power |
| DQI | [Optimization by Decoded Quantum Interferometry](https://arxiv.org/abs/2408.08292) | [DQI Algorithm Implementation](search_and_optimization/dqi/dqi_max_xorsat.ipynb) | Decoded Quantum Interferometry Algorithm for discrete optimization problems |
| Quantum Amplitude Loading | [Quantum Amplitude Loading for Rainbow Options Pricing](https://arxiv.org/abs/2402.05574) | [Direct Method](../applications/finance/rainbow_options/rainbow_options_direct_method.ipynb)
          [Integration Method](../applications/finance/rainbow_options/rainbow_options_integration_method.ipynb) | Implementation of the quantum monte-carlo integration method for the use case of rainbow option pricing |