Merge pull request #24 from qiboteam/qibotn_integration

Qibotn integration to Qibo

.envrc

@@ -0,0 +1,9 @@
+if ! has nix_direnv_version || ! nix_direnv_version 2.2.1; then
+  source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/2.2.1/direnvrc" "sha256-zelF0vLbEl5uaqrfIzbgNzJWGmLzCmYAkInj/LNxvKs="
+fi
+
+nix_direnv_watch_file flake.nix
+nix_direnv_watch_file flake.lock
+if ! use flake . --impure; then
+  echo "devenv could not be built. The devenv environment was not loaded. Make the necessary changes to devenv.nix and hit enter to try again." >&2
+fi

.github/workflows/rules.yml

@@ -1,22 +1,38 @@
 # A single CI script with github workflow
 name: Tests
 
+env:
+  CUDA_PATH:
+
 on:
+  workflow_dispatch:
   push:
   pull_request:
     types: [labeled]
 
 jobs:
+  check:
+    # job to check cuda availability
+    runs-on: ubuntu-latest
+    steps:
+      - id: step1
+        run: echo "test=${{ env.CUDA_PATH != ''}}" >> "$GITHUB_OUTPUT"
+      - id: step2
+        run: echo "test=${{ contains(github.event.pull_request.labels.*.name, 'run-workflow') || github.event_name == 'push' }}" >> "$GITHUB_OUTPUT"
+    outputs:
+      cuda_avail: ${{ fromJSON(steps.step1.outputs.test) && fromJSON(steps.step2.outputs.test) }}
+
   build:
-    if: contains(github.event.pull_request.labels.*.name, 'run-workflow') || github.event_name == 'push' && {{ $CUDA_PATH != '' }}
+    # job to build
+    needs: check
+    if: ${{fromJSON(needs.check.outputs.cuda_avail)}}
     strategy:
-      matrix:
-        os: [ubuntu-latest]
-        python-version: [3.8, 3.9, "3.10"]
-    uses: qiboteam/workflows/.github/workflows/rules.yml@main
+          matrix:
+            os: [ubuntu-latest]
+            python-version: [3.8, 3.9, "3.10", "3.11"]
+    uses: qiboteam/workflows/.github/workflows/rules-poetry.yml@main
     with:
       os: ${{ matrix.os }}
       python-version: ${{ matrix.python-version }}
-      environment: "qibotn"
-      pip-extras: "analysis,tests"
+      poetry-extras: "--with analysis,tests"
     secrets: inherit

.gitignore

@@ -159,3 +159,4 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+.devenv

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
-# See https://pre-commit.com for more information
-# See https://pre-commit.com/hooks.html for more hooks
+ci:
+  autofix_prs: true
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
@@ -8,18 +8,41 @@ repos:
       - id: end-of-file-fixer
       - id: check-yaml
       - id: check-toml
-      - id: check-merge-conflict
       - id: debug-statements
   - repo: https://github.com/psf/black
-    rev: 24.2.0
+    rev: 24.1.1
     hooks:
       - id: black
   - repo: https://github.com/pycqa/isort
     rev: 5.13.2
     hooks:
       - id: isort
         args: ["--profile", "black"]
+  - repo: https://github.com/PyCQA/docformatter
+    rev: v1.7.5
+    hooks:
+      - id: docformatter
+        additional_dependencies: [tomli]
+        args: [--in-place, --config, ./pyproject.toml]
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.15.1
     hooks:
       - id: pyupgrade
+  - repo: https://github.com/hadialqattan/pycln
+    rev: v2.4.0
+    hooks:
+      - id: pycln
+        args:
+          - --config=pyproject.toml
+          - --all
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.16.0
+    hooks:
+      - id: blacken-docs
+  - repo: https://github.com/pycqa/pydocstyle
+    rev: 6.3.0
+    hooks:
+      - id: pydocstyle
+        args:
+          - --select=D103,D200,D206,D300,D301
+        files: ^src/

README.md

@@ -1,3 +1,118 @@
-Qibotn is the tensor-network translation module for Qibo to support large-scale simulation of quantum circuits and acceleration.
+# Qibotn
 
-To get started, `python setup.py install` to install the tools and dependencies.
+The tensor network translation module for Qibo to support large-scale simulation of quantum circuits and acceleration.
+
+## Supported Computation
+
+Tensor Network Types:
+
+- Tensornet (TN)
+- Matrix Product States (MPS)
+
+Tensor Network contractions to:
+
+- dense vectors
+- expecation values of given Pauli string
+
+The supported HPC configurations are:
+
+- single-node CPU
+- single-node GPU or GPUs
+- multi-node multi-GPU with Message Passing Interface (MPI)
+- multi-node multi-GPU with NVIDIA Collective Communications Library (NCCL)
+
+Currently, the supported tensor network libraries are:
+
+- [cuQuantum](https://github.com/NVIDIA/cuQuantum), an NVIDIA SDK of optimized libraries and tools for accelerating quantum computing workflows.
+- [quimb](https://quimb.readthedocs.io/en/latest/), an easy but fast python library for ‘quantum information many-body’ calculations, focusing primarily on tensor networks.
+
+## Installation
+
+To get started:
+
+```sh
+python setup.py install
+```
+
+to install the tools and dependencies. A few extras are provided, check `setup.py` in
+case you need them.
+
+<!-- TODO: describe extras, after Poetry adoption and its groups -->
+
+## Sample Codes
+
+### Single-Node Example
+
+The code below shows an example of how to activate the Cuquantum TensorNetwork backend of Qibo.
+
+```py
+import numpy as np
+from qibo import Circuit, gates
+import qibo
+
+# Below shows how to set the computation_settings
+# Note that for MPS_enabled and expectation_enabled parameters the accepted inputs are boolean or a dictionary with the format shown below.
+# If computation_settings is not specified, the default setting is used in which all booleans will be False.
+# This will trigger the dense vector computation of the tensornet.
+
+computation_settings = {
+    "MPI_enabled": False,
+    "MPS_enabled": {
+        "qr_method": False,
+        "svd_method": {
+            "partition": "UV",
+            "abs_cutoff": 1e-12,
+        },
+    },
+    "NCCL_enabled": False,
+    "expectation_enabled": False,
+}
+
+
+qibo.set_backend(
+    backend="qibotn", platform="cutensornet", runcard=computation_settings
+)  # cuQuantum
+# qibo.set_backend(backend="qibotn", platform="QuimbBackend", runcard=computation_settings) #quimb
+
+
+# Construct the circuit
+c = Circuit(2)
+# Add some gates
+c.add(gates.H(0))
+c.add(gates.H(1))
+
+# Execute the circuit and obtain the final state
+result = c()
+
+print(result.state())
+```
+
+Other examples of setting the computation_settings
+
+```py
+# Expectation computation with specific Pauli String pattern
+computation_settings = {
+    "MPI_enabled": False,
+    "MPS_enabled": False,
+    "NCCL_enabled": False,
+    "expectation_enabled": {
+        "pauli_string_pattern": "IXZ",
+    },
+}
+
+# Dense vector computation using multi node through MPI
+computation_settings = {
+    "MPI_enabled": True,
+    "MPS_enabled": False,
+    "NCCL_enabled": False,
+    "expectation_enabled": False,
+}
+```
+
+### Multi-Node Example
+
+Multi-node is enabled by setting either the MPI or NCCL enabled flag to True in the computation settings. Below shows the script to launch on 2 nodes with 2 GPUs each. $node_list contains the IP of the nodes assigned.
+
+```sh
+mpirun -n 4 -hostfile $node_list python test.py
+```