cunqa

KO | EN

gitlite — search

#javascript #ai #typescript #llm #golang #machine-learning #docker #macos #nodejs #kubernetes #pytorch #mcp #openai #open-source

(★ 24)

CUNQA is a platform for emulating distributed quantum computing (DQC) architectures on HPC environments.

cunqa 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A Distributed Quantum Computing emulator for HPC

## Authors 
<ul>
 <li> <a href="https://github.com/martalosada">Marta Losada Estévez </a> </li>
 <li> <a href="https://github.com/jorgevazquezperez">Jorge Vázquez Pérez </a></li>
 <li> <a href="https://github.com/alvarocarballido">Álvaro Carballido Costas </a></li>
 <li> <a href="https://github.com/D-Exposito">Daniel Expósito Patiño </a></li>
 
</ul>

## Documentation
For a complete and exhaustive explanation and functionality showcase of CUNQA visit the [CUNQA documentation](https://cesga-quantum-spain.github.io/cunqa/).

# Table of contents
  - [INSTALL](#install)
    - [Clone repository](#clone-repository)
    - [Define STORE environment variable](#clone-repository)
    - [Dependencies](#dependencies)
    - [Configure, build and install](#configure-build-and-install)
    - [Install as Lmod module](#install-as-lmod-module)
  - [UNINSTALL](#uninstall)
  - [RUN YOUR FIRST DISTRIBUTED PROGRAM](#run-your-first-distributed-program)
    - [PYTHON-BASH](#python-bash)
    - [PYTHON-ONLY](#python-only)
  - [ACKNOWLEDGEMENTS](#acknowledgements)

## Install

### Clone repository

To get the source code, simply clone the CUNQA repository:

```bash
git clone git@github.com:CESGA-Quantum-Spain/cunqa.git
```

> [!WARNING]
> If SSH cloning fails, you may not have properly linked your environment to GitHub. To do this, run the following commands:
>
> ```bash
> eval "$(ssh-agent -s)"
> ssh-add ~/.ssh/SSH_KEY
> ```
>
> where *SSH_KEY* is the secure key that connects your environment with GitHub, usually stored in the `~/.ssh` folder.

Now CUNQA must be built and installed. If you are installing CUNQA in an HPC center other than CESGA,
you might need to solve some dependencies or manually define the installation path. If you are installing 
it in CESGA, the steps in the next dropdown menu can be skipped.

---
<details open>
<summary>Generic HPC center steps</summary>

### Define STORE environment variable

At build time, CUNQA will look at the `STORE` environment variable to set the root of the `.cunqa` folder where configuration and logging files will be stored. If it is **not** defined in your environment, run:

```bash
export STORE=/path/to/your/store
```

If you plan to compile CUNQA multiple times, we recommend adding this directive to your `.bashrc` file to avoid potential issues.

### Dependencies

CUNQA has a set of dependencies, as any other platform. The versions listed below are those used during development and are therefore recommended. They are divided into three main groups:

#### Must be installed by the user before configuration

```text
gcc             12.3.0
qiskit          1.2.4
CMake           3.24 (recommended 3.27.6)
python          3.11 (3.11.9 used at CESGA)
pybind11        2.12 (recommended 2.13.6)
MPI             3.1
OpenMP          4.5
Boost           1.85.0
Eigen           5.0.0
CUDA            12.8.0
Cython          >= 3.0
Blas            -
Lapack          -
```

#### Can be installed by the user (otherwise installed automatically during configuration)

```text
nlohmann JSON   3.12.0
spdlog          1.16.0
MQT-DDSIM       2.2.0
libzmq          4.3.5
cppzmq          4.11.0
CunqaSimulator  0.1.1
```

#### Installed automatically during configuration

```text
argparse -
qiskit-aer 0.17.2 (modified version)
```
</details>

---

### Configure, build and install

To build, compile, and install CUNQA, follow the standard three-step CMake workflow:

```bash
cmake -B build/ -DCMAKE_INSTALL_PREFIX=/your/installation/path
cmake --build build/ --parallel $(nproc)
cmake --install build/
```

> [!WARNING]
> If `CMAKE_INSTALL_PREFIX` is not provided, CUNQA will be installed in the directory pointed to by 
the `HOME` environment variable.

> [!NOTE] 
> To enable GPU execution (only supported by the Aer simulator), configure with `-DUSE_GPU=ON`. The 
> target CUDA architecture(s) can optionally be set with `-DGPU_ARCH` (e.g. `75;80`); if omitted, it 
> defaults to `all-major`:
>
> ```bash
> cmake -B build/ -DCMAKE_INSTALL_PREFIX=/your/installation/path -DUSE_GPU=ON -DGPU_ARCH="75;80"
> ```
>
> Equivalently, use the `gpu` CMake preset:
>
> ```bash
> cmake --preset gpu -DCMAKE_INSTALL_PREFIX=/your/installation/path
> cmake --build --preset gpu
> cmake --install build/gpu
> ```

You can also use [Ninja](https://ninja-build.org/) to perform this task:

```bash
cmake -G Ninja -B build/ -DCMAKE_INSTALL_PREFIX=/your/installation/path
ninja -C build/ -j $(nproc)
cmake --install build/
```

CUNQA also ships a `CMakePresets.json` with ready-made `dev`, `release` and `gpu` configurations 
(each building into `build/<preset>/`):

```bash
cmake --preset release -DCMAKE_INSTALL_PREFIX=/your/installation/path
cmake --build --preset release
cmake --install build/release
```

Alternatively, you can use the `configure.sh` script, which loads the required modules for the 
detected CESGA system (QMIO or FT3) and then configures, builds and installs CUNQA:

```bash
source configure.sh /your/installation/path
```

---

### Install as Lmod module

CUNQA is available as an Lmod module at CESGA. To use it:

- In QMIO:
  ```bash
  module load qmio/hpc gcc/12.3.0 cunqa/3.0.0-python-3.11.9-mpi
  ```

- In FT3:
  ```bash
  module load cesga/2022 gcc/system cunqa/3.0.0 # without GPUs
  module load cesga/2022 gcc/system cunqa/3.0.0-cuda-12.8.0 # with GPUs
  ```

> [!TIP]
> Module names and available versions may change over time. Run `module spider cunqa` (or 
> `ml av cunqa`) to list the exact module strings installed on your system.

If your HPC center is interested in deploying it this way, the EasyBuild files used at CESGA are 
available in the `easybuild/` folder.

---

### Uninstall

A Make directive is available to uninstall CUNQA if needed:

1. If installed using the standard method:
   ```bash
   make uninstall
   ```

2. If installed using Ninja:
   ```bash
   ninja uninstall
   ```

Be sure to execute these commands inside the `build/` directory in both cases.

Alternatively, you can run:

```bash
cmake --build build/ --target uninstall
```

to abstract from the installation method.

## Run your first distributed program

To achieve this, you have two options: a Python–Bash workflow or a Python-only workflow. With the 
first option, virtual QPUs (vQPUs) can be deployed from the terminal and the employed in the Python 
executable, while the second allows to deploy, use, and drop the vQPUs within the Python program.

### Python-Bash

To deploy the vQPUs we use the `qraise` Bash command.

```bash
qraise -n 4 -t 01:00:00 --co-located
```

Once the vQPUs are deployed, we can design and execute quantum tasks:

```python
import os, sys

# Adding path to access CUNQA module
sys.path.append("</your/cunqa/installation/path>")

# Gettting the raised QPUs
from cunqa.qpu import get_QPUs

qpus  = get_QPUs(co_located=True)

# Creating a circuit to run in our QPUs
from cunqa.circuit import CunqaCircuit

qc = CunqaCircuit(num_qubits = 2)
qc.h(0)
qc.cx(0,1)
qc.measure_all()

# Submitting the same circuit to all vQPUs
from cunqa.qpu import run

qcs = [qc] * 4
qjobs = run(qcs , qpus, shots = 1000)

# Gathering results
from cunqa.qjob import gather

results = gather(qjobs)

# Getting and printing the counts
counts_list = [result.counts for result in results]

for counts in counts_list:
    print(f"Counts: {counts}" ) # Format: {'00':546, '11':454}
```

It is a good practice to relinquish resources when the work is done. This is achieved by the `qdrop` 
command:

```bash
qdrop --all
```

### Python-only

Here, the `qraise` and `qdrop` steps are integrated into the Python executable.

```python
import os, sys

# Adding path to access CUNQA module
sys.path.append("</your/cunqa/installation/path>")

# Raising the QPUs
from cunqa.qpu import qraise

family = qraise(4, "01:00:00", simulator="Aer", co_located=True)

# Gettting the raised QPUs
from cunqa.qpu import get_QPUs

qpus  = get_QPUs(co_located=True)

# Creating a circuit to run in our QPUs
from cunqa.circuit import CunqaCircuit

qc = CunqaCircuit(num_qubits = 2)
qc.h(0)
qc.cx(0,1)
qc.measure_all()

# Submitting the same circuit to all vQPUs
from cunqa.qpu import run

qcs = [qc] * 4
qjobs = run(qcs , qpus, shots = 1000)

# Gathering results
from cunqa.qjob import gather

results = gather(qjobs)

# Getting and printing the counts
counts_list = [result.counts for result in results]

for counts in counts_list:
    print(f"Counts: {counts}" ) # Format: {'00':546, '11':454}

# Relinquishing the resources
from cunqa.qpu import qdrop

qdrop(family)
```

## Acknowledgements
This work has been mainly funded by the project QuantumSpain, financed by the Ministerio de 
Transformación Digital y Función Pública of Spain’s Government through the project call 
QUANTUM ENIA – Quantum Spain project, and by the European Union through the Plan de Recuperación, 
Transformación y Resiliencia – NextGenerationEU within the framework of the Agenda España 
Digital 2026. J. Vázquez-Pérez was supported by the Axencia Galega de Innovación (Xunta de Galicia) 
through the Programa de axudas á etapa predoutoral (ED481A & IN606A).

Additionally, this research project was made possible through the access granted by the Galician 
Supercomputing Center (CESGA) to two key parts of its infrastructure. Firstly, its Qmio quantum 
computing infrastructure with funding from the European Union, through the Operational Programme 
Galicia 2014-2020 of ERDF_REACT EU, as part of theEuropean Union’s response to the COVID-19 
pandemic.

Secondly, The supercomputer FinisTerrae III and its permanent data storage system, which have been 
funded by the NextGeneration EU 2021 Recovery, Transformation and Resilience Plan, ICT2021-006904, 
and also from the Pluriregional Operational Programme of Spain 2014-2020 of the European Regional 
Development Fund (ERDF), ICTS-2019-02-CESGA3, and from the State Programme for the Promotion of 
Scientific and Technical Research of Excellence of the State Plan for Scientific and Technical 
Research and Innovation 2013-2016 State subprogramme for scientific and technical infrastructures 
and equipment of ERDF, CESG15-DE-3114.

## How to cite:

When citing the software, please cite the original CUNQA paper:

```bibtex
@misc{vázquezpérez2025cunqadistributedquantumcomputing,
    title={CUNQA: a Distributed Quantum Computing emulator for HPC}, 
    author={
      Jorge Vázquez-Pérez and 
      Daniel Expósito-Patiño and 
      Marta Losada and 
      Álvaro Carballido and 
      Andrés Gómez and 
      Tomás F. Pena},
    year={2025},
    eprint={2511.05209},
    archivePrefix={arXiv},
    primaryClass={quant-ph},
    url={https://arxiv.org/abs/2511.05209}, 
}
```

cunqa

cunqa 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

cunqa

cunqa 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README