Implement multithreaded stochastic swap in rust

.cargo/config

@@ -0,0 +1,11 @@
+[target.x86_64-apple-darwin]
+rustflags = [
+  "-C", "link-arg=-undefined",
+  "-C", "link-arg=dynamic_lookup",
+]
+
+[target.aarch64-apple-darwin]
+rustflags = [
+  "-C", "link-arg=-undefined",
+  "-C", "link-arg=dynamic_lookup",
+]

.gitignore

@@ -151,3 +151,8 @@ test/ipynb/mpl/circuit/result_test.json
 test/ipynb/mpl/graph/*.png
 test/ipynb/mpl/graph/*.zip
 test/ipynb/mpl/graph/result_test.json
+
+# Added by cargo
+
+/target
+Cargo.lock

.pylintrc

@@ -33,7 +33,7 @@ unsafe-load-any-extension=no
 # A comma-separated list of package or module names from where C extensions may
 # be loaded. Extensions are loading into the active Python interpreter and may
 # run arbitrary code
-extension-pkg-allow-list=retworkx, numpy, tweedledum
+extension-pkg-allow-list=retworkx, numpy, tweedledum, qiskit._accelerate
 
 
 [MESSAGES CONTROL]

CONTRIBUTING.md

@@ -225,9 +225,32 @@ build all the documentation into `docs/_build/html` and the release notes in
 particular will be located at `docs/_build/html/release_notes.html`
 
 ## Installing Qiskit Terra from source
-Please see the [Installing Qiskit Terra from
-Source](https://qiskit.org/documentation/contributing_to_qiskit.html#installing-terra-from-source)
-section of the Qiskit documentation.
+
+Qiskit Terra is primarily written in Python but there are some core routines
+that are written in the [Rust](https://www.rust-lang.org/) programming
+language to improve the runtime performance. For the released versions of
+qiskit-terra we publish precompiled binaries on the
+[Python Package Index](https://pypi.org/) for all the supported platforms
+which only requires a functional Python environment to install. However, when
+building and installing from source you will need a rust compiler installed. You can do this very easily
+using rustup: https://rustup.rs/ which provides a single tool to install and
+configure the latest version of the rust compiler.
+[Other installation methods](https://forge.rust-lang.org/infra/other-installation-methods.html)
+exist too. For windows users besides rustup you will also need install
+the Visual C++ build tools so that rust can link against the system c/c++
+libraries. You can see more details on this in the
+[rustup documentation](https://rust-lang.github.io/rustup/installation/windows.html).
+
+Once you have a rust compiler installed you can rely on the normal Python
+build/install steps to install Qiskit Terra. This means you just run
+`pip install .` in your local git clone to build and install Qiskit Terra.
+
+Do note that if you do use develop mode/editable install (via `python setup.py develop` or `pip install -e .`) the Rust extension will be built in debug mode
+without any optimizations enabled. This will result in poor runtime performance.
+If you'd like to use an editable install with an optimized binary you can
+run `python setup.py build_rust --release --inplace` after you install in
+editable mode to recompile the rust extensions in release mode.
+
 
 ## Test
 

Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "qiskit-terra"
+version = "0.20.0"
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[lib]
+name = "qiskit_accelerate"
+crate-type = ["cdylib"]
+
+[dependencies]
+rayon = "1.5"
+numpy = "0.15.1"
+rand = "0.8"
+rand_pcg = "0.3"
+rand_distr = "0.4.3"
+
+[dependencies.pyo3]
+version = "0.15.1"
+features = ["extension-module", "hashbrown"]
+
+[dependencies.ndarray]
+version = "^0.15.0"
+features = ["rayon"]
+
+[dependencies.hashbrown]
+version = "0.11.2"
+features = ["rayon"]
+
+[profile.release]
+lto = 'fat'
+codegen-units = 1

MANIFEST.in

@@ -15,3 +15,6 @@ include test/python/pickles/*.pickle
 include test/python/qasm/*.qasm
 include test/python/visualization/references/*.png
 include test/python/notebooks/*.ipynb
+
+include Cargo.toml
+recursive-include src *

azure-pipelines.yml

@@ -180,6 +180,7 @@ stages:
             pip install -U "cplex" "qiskit-aer" "z3-solver" -c constraints.txt
             mkdir -p /tmp/terra-tests
             cp -r test /tmp/terra-tests/.
+            cp tools/verify_parallel_map.py /tmp/terra-tests/.
             cp .stestr.conf /tmp/terra-tests/.
             cp -r .stestr /tmp/terra-tests/. || :
             sudo apt-get update
@@ -193,8 +194,11 @@ stages:
             export PYTHONHASHSEED=$(python -S -c "import random; print(random.randint(1, 4294967295))")
             echo "PYTHONHASHSEED=$PYTHONHASHSEED"
             stestr run
+            python ./verify_parallel_map.py
             popd
           displayName: 'Run tests'
+          env:
+            QISKIT_PARALLEL: FALSE
         - task: CopyFiles@2
           condition: failed()
           displayName: 'Copy images'
@@ -239,7 +243,6 @@ stages:
             virtualenv image_tests
             image_tests/bin/pip install -U -r requirements.txt -c constraints.txt
             image_tests/bin/pip install -U -c constraints.txt -e ".[visualization]"
-            image_tests/bin/python setup.py build_ext --inplace
             sudo apt-get update
             sudo apt-get install -y graphviz pandoc
             image_tests/bin/pip check
@@ -286,6 +289,8 @@ stages:
             tools/verify_headers.py qiskit test
             python tools/find_optional_imports.py
             reno lint
+            cargo fmt --check
+            cargo clippy -- -D warnings
           displayName: 'Style and lint'
     - job: 'Docs'
       pool: {vmImage: 'ubuntu-latest'}
@@ -314,7 +319,6 @@ stages:
             set -e
             python -m pip install --upgrade pip setuptools wheel
             pip install -U tox
-            python setup.py build_ext --inplace
             sudo apt-get update
             sudo apt-get install -y graphviz
           displayName: 'Install dependencies'
@@ -384,7 +388,10 @@ stages:
             export PYTHONHASHSEED=$(python -S -c "import random; print(random.randint(1, 4294967295))")
             echo "PYTHONHASHSEED=$PYTHONHASHSEED"
             stestr run
+            python ./tools/verify_parallel_map.py
           displayName: 'Run tests'
+          env:
+            QISKIT_PARALLEL: FALSE
         - task: CopyFiles@2
           condition: failed()
           displayName: 'Copy images'
@@ -454,10 +461,12 @@ stages:
             export PYTHONHASHSEED=$(python -S -c "import random; print(random.randint(1, 1024))")
             echo "PYTHONHASHSEED=$PYTHONHASHSEED"
             stestr run
+            python ./tools/verify_parallel_map.py
           displayName: 'Run tests'
           env:
             LANG: 'C.UTF-8'
             PYTHONIOENCODING: 'utf-8:backslashreplace'
+            QISKIT_PARALLEL: FALSE
         - task: CopyFiles@2
           condition: failed()
           displayName: 'Copy images'
@@ -538,6 +547,7 @@ stages:
             export PYTHONHASHSEED=$(python -S -c "import random; print(random.randint(1, 1024))")
             echo "PYTHONHASHSEED=$PYTHONHASHSEED"
             stestr run
+            python ./tools/verify_parallel_map.py
           env:
             LANG: 'C.UTF-8'
             PYTHONIOENCODING: 'utf-8:backslashreplace'
@@ -630,7 +640,10 @@ stages:
             export PYTHONHASHSEED=$(python -S -c "import random; print(random.randint(1, 4294967295))")
             echo "PYTHONHASHSEED=$PYTHONHASHSEED"
             stestr run
+            python ./tools/verify_parallel_map.py
           displayName: 'Run tests'
+          env:
+            QISKIT_PARALLEL: FALSE
         - task: CopyFiles@2
           condition: failed()
           displayName: 'Copy images'
@@ -712,6 +725,7 @@ stages:
             export PYTHONHASHSEED=$(python -S -c "import random; print(random.randint(1, 4294967295))")
             echo "PYTHONHASHSEED=$PYTHONHASHSEED"
             stestr run
+            python ./tools/verify_parallel_map.py
           displayName: 'Run tests'
         - task: CopyFiles@2
           condition: failed()

examples/python/stochastic_swap.py

@@ -73,23 +73,22 @@
 # Build the expected output to verify the pass worked
 expected = QuantumCircuit(qr, cr)
 expected.cx(qr[1], qr[2])
+expected.h(qr[2])
 expected.swap(qr[0], qr[1])
+expected.h(qr[0])
 expected.cx(qr[1], qr[3])
 expected.h(qr[3])
-expected.h(qr[2])
 expected.measure(qr[1], cr[0])
-expected.h(qr[0])
 expected.swap(qr[1], qr[3])
-expected.h(qr[3])
 expected.cx(qr[2], qr[1])
+expected.h(qr[3])
+expected.swap(qr[0], qr[1])
 expected.measure(qr[2], cr[2])
-expected.swap(qr[1], qr[3])
-expected.measure(qr[3], cr[3])
-expected.cx(qr[1], qr[0])
-expected.measure(qr[1], cr[0])
-expected.measure(qr[0], cr[1])
+expected.cx(qr[3], qr[1])
+expected.measure(qr[0], cr[3])
+expected.measure(qr[3], cr[0])
+expected.measure(qr[1], cr[1])
 expected_dag = circuit_to_dag(expected)
-
 # Run the pass on the dag from the input circuit
 pass_ = StochasticSwap(coupling, 20, 999)
 after = pass_.run(dag)

pyproject.toml

@@ -1,5 +1,6 @@
 [build-system]
-requires = ["Cython>=0.27.1", "setuptools", "wheel"]
+requires = ["Cython>=0.27.1", "setuptools", "wheel", "setuptools-rust"]
+build-backend = "setuptools.build_meta"
 
 [tool.black]
 line-length = 100
@@ -16,3 +17,7 @@ test-command = "python {project}/examples/python/stochastic_swap.py"
 # Numpy 1.22 there are no i686 wheels, so we force pip to use older ones without
 # restricting any dependencies that Numpy and Scipy might have.
 before-test = "pip install --only-binary=numpy,scipy numpy scipy"
+
+[tool.cibuildwheel.linux]
+before-all = "yum install -y wget && {package}/tools/install_rust.sh"
+environment = 'PATH="$PATH:$HOME/.cargo/bin"'

qiskit/__init__.py

@@ -18,6 +18,15 @@
 import sys
 import warnings
 
+import qiskit._accelerate
+
+# Globally define compiled modules. The normal import mechanism will not
+# find compiled submodules in _accelerate because it relies on file paths
+# manually define them on import so people can directly import
+# qiskit._accelerate.* submodules and not have to rely on attribute access
+sys.modules["qiskit._accelerate.stochastic_swap"] = qiskit._accelerate.stochastic_swap
+
+
 # qiskit errors operator
 from qiskit.exceptions import QiskitError, MissingOptionalLibraryError