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 <fred.jendrzejewski@gmail.com>

.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

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