add notebook

docs/tutorials/10_ffsim_backend.ipynb

@@ -0,0 +1,109 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "5beda1bd",
+   "metadata": {},
+   "source": [
+    "# The ffsim backend\n",
+    "\n",
+    "Qiskit Cold Atom includes a fermion simulator backend based on [ffsim](https://github.com/qiskit-community/ffsim), a software library for fast simulations of fermionic circuits. This backend is implemented as `FfsimBackend`, and it can be used instead of the `FermionSimulator` backend for significantly improved performance. Currently, the ffsim backend has the following limitations:\n",
+    "- Only supports circuits with exactly 2 species of fermions\n",
+    "- Only supports gates that conserve the number of particles of each species. In particular, the `FR{X,Y,Z}Gate`s are currently not supported.\n",
+    "\n",
+    "The following code cell shows how to use the ffsim backend to simulate a circuit with 2 species of fermions, consisting of `Hop`, `Interaction`, `Phase`, and `FermiHubbard` gates. Unlike the `FermionSimulator` backend, the ffsim backend does not compute the full unitary of the circuit, since doing so is exceedingly expensive at modest system sizes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1ebfe70b",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "from qiskit_cold_atom.fermions import (\n",
+    "    FermiHubbard,\n",
+    "    FfsimBackend,\n",
+    "    Hop,\n",
+    "    Interaction,\n",
+    "    Phase,\n",
+    ")\n",
+    "\n",
+    "# initialize the ffsim backend\n",
+    "backend = FfsimBackend()\n",
+    "\n",
+    "# set the number of orbitals and occupancies\n",
+    "norb = 8\n",
+    "nocc = norb // 4\n",
+    "nvrt = norb - nocc\n",
+    "occ_a = [1] * nocc + [0] * nvrt\n",
+    "occ_b = [1] * nocc + [0] * nvrt\n",
+    "occupations = [occ_a, occ_b]\n",
+    "\n",
+    "# set parameters for fermionic gates\n",
+    "hopping = np.ones(norb - 1)\n",
+    "interaction = 1.0\n",
+    "mu = np.ones(norb)\n",
+    "\n",
+    "# construct a circuit with some fermionic gates\n",
+    "circuit = backend.initialize_circuit(occupations)\n",
+    "circuit.append(Hop(2 * norb, hopping), list(range(2 * norb)))\n",
+    "circuit.append(Interaction(2 * norb, interaction), list(range(2 * norb)))\n",
+    "circuit.append(Phase(2 * norb, mu), list(range(2 * norb)))\n",
+    "circuit.append(FermiHubbard(2 * norb, hopping, interaction, mu), list(range(2 * norb)))\n",
+    "circuit.measure_all()\n",
+    "\n",
+    "# run the circuit and retrieve the measurement counts\n",
+    "job = backend.run(circuit, shots=10, seed=1234, num_species=2)\n",
+    "\n",
+    "# access the counts\n",
+    "print(\"counts :\", job.result().get_counts())\n",
+    "\n",
+    "# access the memory of individual outcomes\n",
+    "print(\"\\nmemory :\", job.result().get_memory())\n",
+    "\n",
+    "# access the statevector\n",
+    "print(\"\\nstatevector :\", job.result().get_statevector())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0e22aa30",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "import qiskit.tools.jupyter\n",
+    "%qiskit_version_table\n",
+    "%qiskit_copyright"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}