{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "aee6880a-d666-42a9-8267-2774cfc9da0e",
   "metadata": {},
   "source": [
    "# Using FermionicOperators\n",
    "\n",
    "Fulqrum uses ``FermionicOperator`` to describe operators derived from fermionic systems comprised primarily of ladder operators.  In reality, the ``FermionicOperator`` class shares the same data structures as ``QubitOperator``, and the only real difference comes in the ability to use repeated indices and several different methods attached to the operator.  As such, all of the building routines are the same as those for ``QubitOperator`` but using the ladder operators `+` and `-`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3834acb2-579c-4f13-b1d6-d12c876e98eb",
   "metadata": {},
   "outputs": [],
   "source": [
    "import fulqrum as fq"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b81a790-602b-4cf2-880b-3f787e07bea9",
   "metadata": {},
   "source": [
    "## Constructing fermionic operators\n",
    "\n",
    "A simple single-term fermionic operator, here with a width of `14` from an LiH example, can be expressed as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "64776c07-c2b7-489d-91eb-8a86c8c47bd3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<FermionicOperator[('+:0 +:0 -:1 -:5', (-0.018+0j))], width=14>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fq.FermionicOperator(14, [(\"++--\", [0, 0, 1, 5], -0.018)])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7153299-8370-4c0e-8598-baeba620202c",
   "metadata": {},
   "source": [
    "If we take the same operator, but reverse the indices, then we get:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "3bb57c0d-a8a0-4dd0-9b35-3e5075de8fa3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<FermionicOperator[('-:0 -:0 +:1 +:5', (0.018-0j))], width=14>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fq.FermionicOperator(14, [(\"++--\", [5, 1, 0, 0], -0.018)])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dd12bddb-6987-489f-bcd4-76a044214bdf",
   "metadata": {},
   "source": [
    "Notice that the coefficient has changed sign.  This is because the `FermionicOperator`` automatically index sorts the operators from low to high index, and commutation relations will modify signs.\n",
    "\n",
    "Note that things like creating multi-term operators and combining operators follow in the same manner as ``QubitOperator``"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05f0221a-7a25-458f-a5ff-1ff2117c2d2e",
   "metadata": {},
   "source": [
    "## Deflating repeated operator indices\n",
    "\n",
    "In order to convert fermionic systems to qubit representations, we need to \"deflate\" repeated indices so there is only a single operator associated with each index.  As an user you do not need to handle this directly, but here we illustrate this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "65aec77f-953a-485a-b2d0-78e563962286",
   "metadata": {},
   "outputs": [],
   "source": [
    "fop1 = fq.FermionicOperator(14, [(\"++--\", [5, 1, 0, 0], -0.018)])\n",
    "fop2 = fq.FermionicOperator(14, [(\"+--+\", [0, 0, 8, 13], -0.007)])\n",
    "\n",
    "fop = fop1 + fop2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10e54c52-6357-4f14-ac06-ddb64616dbd2",
   "metadata": {},
   "source": [
    "A defalted operator is generated using the method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "75b36961-db7b-41ae-8073-23be99e3f95e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<FermionicOperator[('1:0 -:8 +:13', (-0.007+0j))], width=14>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fop.deflate_repeated_indices()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "404a3da7-eb42-4233-9435-65b62d3475ad",
   "metadata": {},
   "source": [
    "The first term `fop1` vanishes because repeated raising or lowering operators yield a zero term, and the second has the zeroth index term collapsed down to a single `1` projection operator."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "455a5482-419d-47c2-9081-0f44d2096135",
   "metadata": {},
   "source": [
    "## Fermionic to qubit system transformations\n",
    "\n",
    "Fulqrum solves every system in the qubit representation.  Therefore, ``FermionicOperator`` Hamiltonians need to be mapped to ``QubitOperator`` Hamiltionians.  This is done using a Jordan-Wigner transformation over an extended alphabet:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "038fe4a9-8b35-4d69-a6fa-c65ef476e9c1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<QubitOperator[('1:0 -:8 Z:9 Z:10 Z:11 Z:12 +:13', (0.007-0j))], width=14, extended=1, group=-1>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fop.extended_jw_transformation()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cdb910ac-d389-43ea-a766-5540dacb3418",
   "metadata": {},
   "source": [
    "We see that the resulting transformation has one term, as expected given `fop1` is a zero operator, and that the ladder and projector operators remain, with additional `Z` operators to maintain the proper commutation relations.  No additional `Z` terms are applied below index `8` because `Z*Z=I`.  Note that there is a sign change in the coefficient."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b3ccd33a-7ac4-4ead-9c23-fe1531362d5c",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.12.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}