Installation

Clone repository

To get the source code, simply clone CUNQA repository:

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:

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, some steps can be skipped.

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 files and logging files will be stored. So, if it is not defined by default on the environment, just run:

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 here displayed are the ones that have been employed in the development and, therefore, that are recommended. They are divided in three main groups:

  • Must be installed by the user before configuration.

   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
   Blas            -
   Lapack          -


- **Can be installed by the user**, but if they are not they will be automatically installed by the configuration process.

.. code-block:: text

   nlohmann JSON   3.12.0
   Eigen           5.0.0
   spdlog          1.16.0
   MQT-DDSIM       2.2.0
   QuEST           4.2.0
   qsim            0.22.0
   libzmq          4.3.5
   cppzmq          4.9.0
   CunqaSimulator  0.1.2

- **Will be installed automatically** by the configuration process.

argparse        -
qiskit-aer      0.17.2 (modified version)
pyzmq           27.1.0
Maestro         - (bundles QCSim and a qiskit-aer fork)
Qulacs          - (modified version)

Configure, build and install

To build, compile, and install CUNQA, the three usual steps in a CMake project are followed.

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 where the environment variable HOME points.

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.

cmake -B build/ -DCMAKE_INSTALL_PREFIX=/your/installation/path -DUSE_GPU=ON -DGPU_ARCH="75;80"

Equivalently, use the gpu CMake preset:

cmake --preset gpu -DCMAKE_INSTALL_PREFIX=/your/installation/path
cmake --build --preset gpu
cmake --install build/gpu

You can also employ Ninja to perform this task.

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

Using CMake presets

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

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

Alternatively, you can use the configure.sh file, but only after all the dependencies have been solved.

source configure.sh /your/installation/path

Install as Lmod module

If your HPC center is interested in using it this way, EasyBuild files employed to install it in CESGA are available inside easybuild/ folder.

Configure, build and install

To build, compile, and install CUNQA, the three usual steps in a CMake project are followed.

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 where the environment variable HOME points.

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.

cmake -B build/ -DCMAKE_INSTALL_PREFIX=/your/installation/path -DUSE_GPU=ON -DGPU_ARCH="75;80"

Equivalently, use the gpu CMake preset:

cmake --preset gpu -DCMAKE_INSTALL_PREFIX=/your/installation/path
cmake --build --preset gpu
cmake --install build/gpu

You can also employ Ninja to perform this task.

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

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

source configure.sh /your/installation/path

Install as Lmod module

CUNQA is available as Lmod module in CESGA. To use it all you have to do is:

  • In QMIO:

module load qmio/hpc gcc/12.3.0 cunqa/3.0.0-python-3.11.9-mpi

  • In FT3:

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.

Uninstall

There has also been developed a Make directive to uninstall CUNQA if needed:

  1. If you installed using the standard way: make uninstall.

  2. If you installed using Ninja: ninja uninstall.

Be sure to execute this command inside the build/ directory in both cases. An alternative is using:

cmake --build build/ --target uninstall

to abstract from the installation method.