Add structure for multiple Rust crates

.github/workflows/coverage.yml

@@ -45,8 +45,8 @@ jobs:
           stestr run
           # We set the --source-dir to '.' because we want all paths to appear relative to the repo
           # root (we need to combine them with the Python ones), but we only care about `grcov`
-          # keeping the `src/*` files; we don't care about coverage in dependencies.
-          grcov . --binary-path target/debug/ --source-dir . --output-type lcov --output-path rust.info --llvm --branch --parallel --keep-only 'src/*'
+          # keeping the `crates/*` files; we don't care about coverage in dependencies.
+          grcov . --binary-path target/debug/ --source-dir . --output-type lcov --output-path rust.info --llvm --branch --parallel --keep-only 'crates/*'
         env:
           QISKIT_TEST_CAPTURE_STREAMS: 1
           QISKIT_PARALLEL: FALSE

Cargo.toml

@@ -1,42 +1,14 @@
-[package]
-name = "qiskit-terra"
+[workspace]
+members = ["crates/*"]
+
+# This has no meaning until we're on Rust 1.64, but once we get there, the subpackages will be able
+# to inherit from this rather than needing to duplicate its content themselves.  Until we get there,
+# keep this in sync with each subpackage `Cargo.toml`'s `package` key.
+[workspace.package]
 version = "0.24.0"
 edition = "2021"
-# Keep in sync with README.md and rust-toolchain.toml.
-rust-version = "1.61"
-
-# 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.7"
-numpy = "0.18.0"
-rand = "0.8"
-rand_pcg = "0.3"
-rand_distr = "0.4.3"
-ahash = "0.8.3"
-num-complex = "0.4"
-num-bigint = "0.4"
-rustworkx-core = "0.12"
-
-[dependencies.pyo3]
-version = "0.18.1"
-features = ["extension-module", "hashbrown", "num-complex", "num-bigint", "indexmap"]
-
-[dependencies.ndarray]
-version = "^0.15.6"
-features = ["rayon"]
-
-[dependencies.hashbrown]
-version = "0.13.2"
-features = ["rayon"]
-
-[dependencies.indexmap]
-version = "1.9"
-features = ["rayon"]
+rust-version = "1.61"  # Keep in sync with README.md and rust-toolchain.toml.
+license = "Apache-2.0"
 
 [profile.release]
 lto = 'fat'

MANIFEST.in

@@ -18,4 +18,4 @@ include test/python/notebooks/*.ipynb
 
 include Cargo.toml
 include Cargo.lock
-recursive-include src *
+recursive-include crates *

crates/accelerate/Cargo.toml

@@ -0,0 +1,41 @@
+[package]
+name = "qiskit_accelerate"
+# The following options can be inherited with (e.g.) `version.workspace = true` once we hit Rust
+# 1.64.  Until then, keep in sync with the root `Cargo.toml`.
+version = "0.24.0"
+edition = "2021"
+rust-version = "1.61"
+license = "Apache-2.0"
+
+[lib]
+name = "qiskit_accelerate"
+crate-type = ["cdylib"]
+
+[dependencies]
+rayon = "1.7"
+numpy = "0.18.0"
+rand = "0.8"
+rand_pcg = "0.3"
+rand_distr = "0.4.3"
+ahash = "0.8.3"
+num-complex = "0.4"
+num-bigint = "0.4"
+rustworkx-core = "0.12"
+
+# The base version of PyO3 and setting a minimum feature set (e.g. probably just 'extension-module')
+# can be done in the workspace and inherited once we hit Rust 1.64.
+[dependencies.pyo3]
+version = "0.18.1"
+features = ["extension-module", "hashbrown", "indexmap", "num-complex", "num-bigint"]
+
+[dependencies.ndarray]
+version = "^0.15.6"
+features = ["rayon"]
+
+[dependencies.hashbrown]
+version = "0.13.2"
+features = ["rayon"]
+
+[dependencies.indexmap]
+version = "1.9"
+features = ["rayon"]

crates/accelerate/README.md

@@ -0,0 +1,21 @@
+# `qiskit._accelerate`
+
+This crate provides a bits-and-pieces Python extension module for small, self-contained functions
+that are used by the main Python-space components to accelerate certain tasks.  If you're trying to
+speed up one particular Python function by replacing its innards with a Rust one, this is the best
+place to put the code.  This is _usually_ the right place to put Rust/Python interfacing code.
+
+The crate is made accessible as a private submodule, `qiskit._accelerate`.  There are submodules
+within that (largely matching the structure of the Rust code) mostly for grouping similar functions.
+
+Some examples of when it might be more appropriate to start a new crate instead of using the
+ready-made solution of `qiskit._accelerate`:
+
+* The feature you are developing will have a large amount of domain-specific Rust code and is a
+  large self-contained module.  If it reasonably works in a single Rust file, you probably just want
+  to put it here.
+
+* The Rust code is for re-use within other Qiskit crates and maintainability of the code will be
+  helped by using the crate system to provide API boundaries between the different sections.
+
+* You want to start writing your own procedural macros.

setup.py

@@ -99,7 +99,9 @@
         "Documentation": "https://qiskit.org/documentation/",
         "Source Code": "https://github.com/Qiskit/qiskit-terra",
     },
-    rust_extensions=[RustExtension("qiskit._accelerate", "Cargo.toml", binding=Binding.PyO3)],
+    rust_extensions=[
+        RustExtension("qiskit._accelerate", "crates/accelerate/Cargo.toml", binding=Binding.PyO3)
+    ],
     zip_safe=False,
     entry_points={
         "qiskit.unitary_synthesis": [