From 48e97ed07d06b4d7fd62bd6975fcbe736e7eabca Mon Sep 17 00:00:00 2001
From: Jake Lishman <jake.lishman@ibm.com>
Date: Mon, 6 Mar 2023 18:44:47 +0000
Subject: [PATCH 1/3] Add structure for multiplie Rust extension crates

This is a precursor to adding an entirely separate and self-contained
crate to handle parsing of OpenQASM 2 (not 3 - this is kind of like a
trial run for that).  It could conceivably still live within
`qiskit._accelerate`, but having separate crates helps us enforce more
sane API barriers, and has improvements in the incremental build time
when working on only one of the Rust extensions.

The intent after this commit is still to have `qiskit._accelerate` as an
easy catch-all for accelerators for Python.  Developers should not need
to be concerned with defining a new crate for every new feature, and for
the most part `_accelerate` is still logically interoperative within
itself (for example, `NLayout` is used all over).  This is just laying
out the groundwork so more complex crate additions _can_ also be made.

Some of the niceties to do with Cargo workspaces only became stabilised
in Rust 1.64.  In particular, inheritance from the workspace root for
things like the package version, Rust version, and dependencies only
came in then.  For now, the `workspace.packages` key in the root
`Cargo.toml` is ignored with a small warning during the build, but I've
put it in place mostly to keep track of what we can change once the MSRV
becomes 1.64 or greater (likely not til at least Terra 0.26).
---
 .github/workflows/coverage.yml                |  4 +-
 Cargo.lock                                    | 84 +++++++++----------
 Cargo.toml                                    | 46 ++--------
 MANIFEST.in                                   |  2 +-
 crates/accelerate/Cargo.toml                  | 41 +++++++++
 .../accelerate/src}/dense_layout.rs           |  0
 .../accelerate/src}/edge_collections.rs       |  0
 {src => crates/accelerate/src}/error_map.rs   |  0
 .../src}/euler_one_qubit_decomposer.rs        |  0
 {src => crates/accelerate/src}/lib.rs         |  0
 {src => crates/accelerate/src}/nlayout.rs     |  0
 .../accelerate/src}/optimize_1q_gates.rs      |  0
 .../accelerate/src}/pauli_exp_val.rs          |  0
 .../accelerate/src}/results/converters.rs     |  0
 .../src}/results/marginalization.rs           |  0
 {src => crates/accelerate/src}/results/mod.rs |  0
 .../accelerate/src}/sabre_layout.rs           |  0
 .../accelerate/src}/sabre_swap/layer.rs       |  0
 .../accelerate/src}/sabre_swap/mod.rs         |  0
 .../src}/sabre_swap/neighbor_table.rs         |  0
 .../accelerate/src}/sabre_swap/sabre_dag.rs   |  0
 .../accelerate/src}/sabre_swap/swap_map.rs    |  0
 .../accelerate/src}/sampled_exp_val.rs        |  0
 .../accelerate/src}/sparse_pauli_op.rs        |  0
 .../accelerate/src}/stochastic_swap.rs        |  0
 {src => crates/accelerate/src}/vf2_layout.rs  |  0
 setup.py                                      |  4 +-
 27 files changed, 98 insertions(+), 83 deletions(-)
 create mode 100644 crates/accelerate/Cargo.toml
 rename {src => crates/accelerate/src}/dense_layout.rs (100%)
 rename {src => crates/accelerate/src}/edge_collections.rs (100%)
 rename {src => crates/accelerate/src}/error_map.rs (100%)
 rename {src => crates/accelerate/src}/euler_one_qubit_decomposer.rs (100%)
 rename {src => crates/accelerate/src}/lib.rs (100%)
 rename {src => crates/accelerate/src}/nlayout.rs (100%)
 rename {src => crates/accelerate/src}/optimize_1q_gates.rs (100%)
 rename {src => crates/accelerate/src}/pauli_exp_val.rs (100%)
 rename {src => crates/accelerate/src}/results/converters.rs (100%)
 rename {src => crates/accelerate/src}/results/marginalization.rs (100%)
 rename {src => crates/accelerate/src}/results/mod.rs (100%)
 rename {src => crates/accelerate/src}/sabre_layout.rs (100%)
 rename {src => crates/accelerate/src}/sabre_swap/layer.rs (100%)
 rename {src => crates/accelerate/src}/sabre_swap/mod.rs (100%)
 rename {src => crates/accelerate/src}/sabre_swap/neighbor_table.rs (100%)
 rename {src => crates/accelerate/src}/sabre_swap/sabre_dag.rs (100%)
 rename {src => crates/accelerate/src}/sabre_swap/swap_map.rs (100%)
 rename {src => crates/accelerate/src}/sampled_exp_val.rs (100%)
 rename {src => crates/accelerate/src}/sparse_pauli_op.rs (100%)
 rename {src => crates/accelerate/src}/stochastic_swap.rs (100%)
 rename {src => crates/accelerate/src}/vf2_layout.rs (100%)

diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
index 1cb82d976736..bf31e54872c2 100644
--- a/.github/workflows/coverage.yml
+++ b/.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
diff --git a/Cargo.lock b/Cargo.lock
index e392767ad8e6..becd4597ed46 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -45,9 +45,9 @@ checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
 
 [[package]]
 name = "crossbeam-channel"
-version = "0.5.6"
+version = "0.5.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c2dd04ddaf88237dc3b8d8f9a3c1004b506b54b3313403944054d23c0870c521"
+checksum = "cf2b3e8478797446514c91ef04bafcb59faba183e621ad488df88983cc14128c"
 dependencies = [
  "cfg-if",
  "crossbeam-utils",
@@ -55,9 +55,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-deque"
-version = "0.8.2"
+version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "715e8152b692bba2d374b53d4875445368fdf21a94751410af607a5ac677d1fc"
+checksum = "ce6fd6f855243022dcecf8702fef0c297d4338e226845fe067f6341ad9fa0cef"
 dependencies = [
  "cfg-if",
  "crossbeam-epoch",
@@ -66,31 +66,31 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-epoch"
-version = "0.9.13"
+version = "0.9.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "01a9af1f4c2ef74bb8aa1f7e19706bc72d03598c8a570bb5de72243c7a9d9d5a"
+checksum = "46bd5f3f85273295a9d14aedfb86f6aadbff6d8f5295c4a9edb08e819dcf5695"
 dependencies = [
  "autocfg",
  "cfg-if",
  "crossbeam-utils",
- "memoffset 0.7.1",
+ "memoffset",
  "scopeguard",
 ]
 
 [[package]]
 name = "crossbeam-utils"
-version = "0.8.14"
+version = "0.8.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4fb766fa798726286dbbb842f174001dab8abc7b627a1dd86e0b7222a95d929f"
+checksum = "3c063cd8cc95f5c377ed0d4b49a4b21f632396ff690e8470c29b3359b346984b"
 dependencies = [
  "cfg-if",
 ]
 
 [[package]]
 name = "either"
-version = "1.8.0"
+version = "1.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90e5c1c8368803113bf0c9584fc495a58b86dc8a29edbf8fe877d21d9507e797"
+checksum = "7fcaabb2fef8c910e7f4c7ce9f67a1283a1715879a7c230ca9d6d1ae31f16d91"
 
 [[package]]
 name = "fixedbitset"
@@ -157,9 +157,9 @@ dependencies = [
 
 [[package]]
 name = "indoc"
-version = "1.0.8"
+version = "1.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da2d6f23ffea9d7e76c53eee25dfb67bcd8fde7f1198b0855350698c9f07c780"
+checksum = "bfa799dd5ed20a7e349f3b4639aa80d74549c81716d9ec4f994c9b5815598306"
 
 [[package]]
 name = "libc"
@@ -192,15 +192,6 @@ dependencies = [
  "rawpointer",
 ]
 
-[[package]]
-name = "memoffset"
-version = "0.7.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5de893c32cde5f383baa4c04c5d6dbdd735cfd4a794b0debdb2bb1b421da5ff4"
-dependencies = [
- "autocfg",
-]
-
 [[package]]
 name = "memoffset"
 version = "0.8.0"
@@ -291,9 +282,9 @@ dependencies = [
 
 [[package]]
 name = "once_cell"
-version = "1.17.0"
+version = "1.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6f61fba1741ea2b3d6a1e3178721804bb716a68a6aeba1149b5d52e3d464ea66"
+checksum = "b7e5500299e16ebb147ae15a00a942af264cf3688f47923b8fc2cd5858f23ad3"
 
 [[package]]
 name = "parking_lot"
@@ -307,9 +298,9 @@ dependencies = [
 
 [[package]]
 name = "parking_lot_core"
-version = "0.9.6"
+version = "0.9.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ba1ef8814b5c993410bb3adfad7a5ed269563e4a2f90c41f5d85be7fb47133bf"
+checksum = "9069cbb9f99e3a5083476ccb29ceb1de18b9118cafa53e90c9551235de2b9521"
 dependencies = [
  "cfg-if",
  "libc",
@@ -320,9 +311,9 @@ dependencies = [
 
 [[package]]
 name = "petgraph"
-version = "0.6.2"
+version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6d5014253a1331579ce62aa67443b4a658c5e7dd03d4bc6d302b94474888143"
+checksum = "4dd7d28ee937e54fe3080c91faa1c3a46c06de6252988a7f4592ba2310ef22a4"
 dependencies = [
  "fixedbitset",
  "indexmap",
@@ -336,9 +327,9 @@ checksum = "5b40af805b3121feab8a3c29f04d8ad262fa8e0561883e7653e024ae4479e6de"
 
 [[package]]
 name = "priority-queue"
-version = "1.3.0"
+version = "1.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d7685ca4cc0b3ad748c22ce6803e23b55b9206ef7715b965ebeaf41639238fdc"
+checksum = "5ca9c6be70d989d21a136eb86c2d83e4b328447fac4a88dace2143c179c86267"
 dependencies = [
  "autocfg",
  "indexmap",
@@ -346,9 +337,9 @@ dependencies = [
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.50"
+version = "1.0.51"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ef7d57beacfaf2d8aee5937dab7b7f28de3cb8b1828479bb5de2a7106f2bae2"
+checksum = "5d727cae5b39d21da60fa540906919ad737832fe0b1c165da3a34d6548c849d6"
 dependencies = [
  "unicode-ident",
 ]
@@ -364,7 +355,7 @@ dependencies = [
  "indexmap",
  "indoc",
  "libc",
- "memoffset 0.8.0",
+ "memoffset",
  "num-bigint",
  "num-complex",
  "parking_lot",
@@ -418,7 +409,7 @@ dependencies = [
 ]
 
 [[package]]
-name = "qiskit-terra"
+name = "qiskit_accelerate"
 version = "0.24.0"
 dependencies = [
  "ahash 0.8.3",
@@ -567,9 +558,9 @@ checksum = "a507befe795404456341dfab10cef66ead4c041f62b8b11bbb92bffe5d0953e0"
 
 [[package]]
 name = "syn"
-version = "1.0.107"
+version = "1.0.109"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1f4064b5b16e03ae50984a5a8ed5d4f8803e6bc1fd170a3cda91a1be4b18e3f5"
+checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -578,15 +569,15 @@ dependencies = [
 
 [[package]]
 name = "target-lexicon"
-version = "0.12.5"
+version = "0.12.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9410d0f6853b1d94f0e519fb95df60f29d2c1eff2d921ffdf01a4c8a3b54f12d"
+checksum = "8ae9980cab1db3fceee2f6c6f643d5d8de2997c58ee8d25fb0cc8a9e9e7348e5"
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.6"
+version = "1.0.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "84a22b9f218b40614adcb3f4ff08b703773ad44fa9423e4e0d346d5db86e4ebc"
+checksum = "e5464a87b239f13a63a501f2701565754bae92d243d4bb7eb12f6d57d2269bf4"
 
 [[package]]
 name = "unindent"
@@ -608,9 +599,18 @@ checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423"
 
 [[package]]
 name = "windows-sys"
-version = "0.42.0"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75283be5efb2831d37ea142365f009c02ec203cd29a3ebecbc093d52315b66d0"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.42.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5a3e1820f08b8513f676f7ab6c1f99ff312fb97b553d30ff4dd86f9f15728aa7"
+checksum = "8e2522491fbfcd58cc84d47aeb2958948c4b8982e9a2d8a2a35bbaed431390e7"
 dependencies = [
  "windows_aarch64_gnullvm",
  "windows_aarch64_msvc",
diff --git a/Cargo.toml b/Cargo.toml
index 1db82bf185fe..66583f6e1126 100644
--- a/Cargo.toml
+++ b/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-file = "LICENSE.txt"
 
 [profile.release]
 lto = 'fat'
diff --git a/MANIFEST.in b/MANIFEST.in
index 9d3fae282ed0..4af4594ace58 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -18,4 +18,4 @@ include test/python/notebooks/*.ipynb
 
 include Cargo.toml
 include Cargo.lock
-recursive-include src *
+recursive-include crates *
diff --git a/crates/accelerate/Cargo.toml b/crates/accelerate/Cargo.toml
new file mode 100644
index 000000000000..6a2acfac5c34
--- /dev/null
+++ b/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-file = "LICENSE.txt"
+
+[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"]
diff --git a/src/dense_layout.rs b/crates/accelerate/src/dense_layout.rs
similarity index 100%
rename from src/dense_layout.rs
rename to crates/accelerate/src/dense_layout.rs
diff --git a/src/edge_collections.rs b/crates/accelerate/src/edge_collections.rs
similarity index 100%
rename from src/edge_collections.rs
rename to crates/accelerate/src/edge_collections.rs
diff --git a/src/error_map.rs b/crates/accelerate/src/error_map.rs
similarity index 100%
rename from src/error_map.rs
rename to crates/accelerate/src/error_map.rs
diff --git a/src/euler_one_qubit_decomposer.rs b/crates/accelerate/src/euler_one_qubit_decomposer.rs
similarity index 100%
rename from src/euler_one_qubit_decomposer.rs
rename to crates/accelerate/src/euler_one_qubit_decomposer.rs
diff --git a/src/lib.rs b/crates/accelerate/src/lib.rs
similarity index 100%
rename from src/lib.rs
rename to crates/accelerate/src/lib.rs
diff --git a/src/nlayout.rs b/crates/accelerate/src/nlayout.rs
similarity index 100%
rename from src/nlayout.rs
rename to crates/accelerate/src/nlayout.rs
diff --git a/src/optimize_1q_gates.rs b/crates/accelerate/src/optimize_1q_gates.rs
similarity index 100%
rename from src/optimize_1q_gates.rs
rename to crates/accelerate/src/optimize_1q_gates.rs
diff --git a/src/pauli_exp_val.rs b/crates/accelerate/src/pauli_exp_val.rs
similarity index 100%
rename from src/pauli_exp_val.rs
rename to crates/accelerate/src/pauli_exp_val.rs
diff --git a/src/results/converters.rs b/crates/accelerate/src/results/converters.rs
similarity index 100%
rename from src/results/converters.rs
rename to crates/accelerate/src/results/converters.rs
diff --git a/src/results/marginalization.rs b/crates/accelerate/src/results/marginalization.rs
similarity index 100%
rename from src/results/marginalization.rs
rename to crates/accelerate/src/results/marginalization.rs
diff --git a/src/results/mod.rs b/crates/accelerate/src/results/mod.rs
similarity index 100%
rename from src/results/mod.rs
rename to crates/accelerate/src/results/mod.rs
diff --git a/src/sabre_layout.rs b/crates/accelerate/src/sabre_layout.rs
similarity index 100%
rename from src/sabre_layout.rs
rename to crates/accelerate/src/sabre_layout.rs
diff --git a/src/sabre_swap/layer.rs b/crates/accelerate/src/sabre_swap/layer.rs
similarity index 100%
rename from src/sabre_swap/layer.rs
rename to crates/accelerate/src/sabre_swap/layer.rs
diff --git a/src/sabre_swap/mod.rs b/crates/accelerate/src/sabre_swap/mod.rs
similarity index 100%
rename from src/sabre_swap/mod.rs
rename to crates/accelerate/src/sabre_swap/mod.rs
diff --git a/src/sabre_swap/neighbor_table.rs b/crates/accelerate/src/sabre_swap/neighbor_table.rs
similarity index 100%
rename from src/sabre_swap/neighbor_table.rs
rename to crates/accelerate/src/sabre_swap/neighbor_table.rs
diff --git a/src/sabre_swap/sabre_dag.rs b/crates/accelerate/src/sabre_swap/sabre_dag.rs
similarity index 100%
rename from src/sabre_swap/sabre_dag.rs
rename to crates/accelerate/src/sabre_swap/sabre_dag.rs
diff --git a/src/sabre_swap/swap_map.rs b/crates/accelerate/src/sabre_swap/swap_map.rs
similarity index 100%
rename from src/sabre_swap/swap_map.rs
rename to crates/accelerate/src/sabre_swap/swap_map.rs
diff --git a/src/sampled_exp_val.rs b/crates/accelerate/src/sampled_exp_val.rs
similarity index 100%
rename from src/sampled_exp_val.rs
rename to crates/accelerate/src/sampled_exp_val.rs
diff --git a/src/sparse_pauli_op.rs b/crates/accelerate/src/sparse_pauli_op.rs
similarity index 100%
rename from src/sparse_pauli_op.rs
rename to crates/accelerate/src/sparse_pauli_op.rs
diff --git a/src/stochastic_swap.rs b/crates/accelerate/src/stochastic_swap.rs
similarity index 100%
rename from src/stochastic_swap.rs
rename to crates/accelerate/src/stochastic_swap.rs
diff --git a/src/vf2_layout.rs b/crates/accelerate/src/vf2_layout.rs
similarity index 100%
rename from src/vf2_layout.rs
rename to crates/accelerate/src/vf2_layout.rs
diff --git a/setup.py b/setup.py
index ac1716ab4f48..7f6f2cb5b918 100755
--- a/setup.py
+++ b/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": [

From 76e6496bf033a371f60fb9357df35f8b9fdac3c3 Mon Sep 17 00:00:00 2001
From: Jake Lishman <jake.lishman@ibm.com>
Date: Tue, 7 Mar 2023 22:13:03 +0000
Subject: [PATCH 2/3] Add README.md to crates/accelerate

---
 crates/accelerate/README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 crates/accelerate/README.md

diff --git a/crates/accelerate/README.md b/crates/accelerate/README.md
new file mode 100644
index 000000000000..65f4eebe5844
--- /dev/null
+++ b/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.

From a6982456034321cad866933cf8e12538e0a64592 Mon Sep 17 00:00:00 2001
From: Jake Lishman <jake.lishman@ibm.com>
Date: Tue, 7 Mar 2023 22:17:51 +0000
Subject: [PATCH 3/3] Correct licence metadata

---
 Cargo.toml                   | 2 +-
 crates/accelerate/Cargo.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 66583f6e1126..ece643e5c8fe 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -8,7 +8,7 @@ members = ["crates/*"]
 version = "0.24.0"
 edition = "2021"
 rust-version = "1.61"  # Keep in sync with README.md and rust-toolchain.toml.
-license-file = "LICENSE.txt"
+license = "Apache-2.0"
 
 [profile.release]
 lto = 'fat'
diff --git a/crates/accelerate/Cargo.toml b/crates/accelerate/Cargo.toml
index 6a2acfac5c34..5021bb523c33 100644
--- a/crates/accelerate/Cargo.toml
+++ b/crates/accelerate/Cargo.toml
@@ -5,7 +5,7 @@ name = "qiskit_accelerate"
 version = "0.24.0"
 edition = "2021"
 rust-version = "1.61"
-license-file = "LICENSE.txt"
+license = "Apache-2.0"
 
 [lib]
 name = "qiskit_accelerate"