Add ffsim simulator backend (#90)

* add ffsim simulator backend * fix hop gate sorting * add support for fermiongate * lint * add ffsim backend to providers * make ffsim dependency optional * remove asv benchmarks * update TODOs * from __future__ import annotations * add notebook * update docs * remove TODOs * add support for spinless fermions * test python 3.8 in github actions * union keys instead of entire dictionary * add support for FR{XYZ} gates * pin ffsim to 0.0.19 * update docs and README * add release note * document ValueError * Create 10_fermions_spin_charge_sep.ipynb * Update 10_fermions_spin_charge_sep.ipynb * Update 10_fermions_spin_charge_sep.ipynb * Update 10_fermions_spin_charge_sep.ipynb * fix spinless measurements * move ffsim tutorial content to tutorial 01 * format * just print statevector length instead of all entries --------- Co-authored-by: fretchen <[email protected]>
qiskit-community · Jan 31, 2024 · e4f0993 · e4f0993
1 parent f6c2390
commit e4f0993
Show file tree

Hide file tree

Showing 12 changed files with 2,236 additions and 30 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -94,3 +94,29 @@ jobs:
         with:
           name: html_docs
           path: docs/_build/html
+  ffsim:
+    name: tests-ffsim-python${{ matrix.python-version }}-${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: [3.8, 3.11]
+        os: ["ubuntu-latest", "macOS-latest"]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Pip cache
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-${{ matrix.python-version }}-pip-tests-${{ hashFiles('setup.py','requirements-dev.txt','constraints.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ matrix.python-version }}-pip-tests-
+            ${{ runner.os }}-${{ matrix.python-version }}-pip-
+            ${{ runner.os }}-${{ matrix.python-version }}
+      - name: Install Deps
+        run: python -m pip install -U tox setuptools virtualenv wheel
+      - name: Run ffsim tests
+        run: tox -e ffsim
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ Here, we extend this concept and allow wires to represent individual internal st
 This currently covers two settings, one for fermionic modes and one for spin modes, 
 demonstrating that a broad range of hardware can be accommodated in Qiskit.
 
-We encourage new users to familiarize themselves with the basic functionalities through the tutorial-style python notebooks in `/docs/tutorials`. 
+We encourage new users to familiarize themselves with the basic functionalities through the tutorial-style python notebooks in [`docs/tutorials`](docs/tutorials). 
 These require an environment to execute `.ipynb` notebooks such as jupyter lab. 
 
 ## Installation
@@ -30,6 +30,10 @@ or Pypi
 ```bash
 pip install qiskit-cold-atom
 ```
+To install Qiskit Cold Atom with the [ffsim fermion simulator backend](#cold-atomic-circuits) (not supported on Windows), specify the `ffsim` extra in the `pip` install command, e.g.
+```bash
+pip install "qiskit-cold-atom[ffsim]"
+```
 
 ## Setting up the Cold Atom Provider 
 Qiskit Cold Atom includes local simulator backends to explore the cold atomic hardware. In order to access
@@ -59,10 +63,20 @@ spin_simulator_backend = provider.get_backend("collective_spin_simulator")
 
 ## Cold atomic circuits
 
-The circuits that can be run on the cold atomic hardware explored in this project use different gates 
-from the qubit circuits typically employed in Qiskit, because their systems are described by different
-Hilbert spaces. 
-To see how to define and run gates through quantum circuits in this setting, please refer to the tutorials (in `/docs/tutorials`).
+The circuits that can be run on the cold atomic hardware explored in this project use different gates
+from the circuits typically employed in Qiskit, because these hardware are not built from qubits,
+but from fermions or spins.
+Qiskit Cold Atom includes basic simulators for both the fermion and spin settings that can be used
+to simulate small circuits. See [Introduction & Fermionic Circuits](docs/tutorials/01_introduction_and_fermionic_circuits.ipynb)
+and [Spin circuits](docs/tutorials/02_spin_circuits.ipynb) for tutorials on how to define and run gates through
+quantum circuits in these settings.
+
+Qiskit Cold Atom also includes a high-performance simulator for fermionic circuits based on
+[ffsim](https://github.com/qiskit-community/ffsim), which can handle much larger circuits than the basic simulator mentioned before. The ffsim simulator is not supported on Windows, and in order
+for it to be available, Qiskit Cold Atom must be installed with the `ffsim` extra, e.g.
+```bash
+pip install "qiskit-cold-atom[ffsim]"
+```
 
 ## Documentation
 

diff --git a/docs/tutorials/01_introduction_and_fermionic_circuits.ipynb b/docs/tutorials/01_introduction_and_fermionic_circuits.ipynb