Add Jupyter notebooks for the examples

Author: JanLuca

examples/data

@@ -0,0 +1,384 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "f6cb1fe6-ae30-4ceb-a7bf-605fad9540cf",
+   "metadata": {},
+   "source": [
+    "<h1>Heisenberg antiferromagnet on the square lattice</h1>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "030ee89c-ec88-4c0e-bb8b-09e30c8f2e18",
+   "metadata": {},
+   "source": [
+    "<figure style=\"text-align:center\">\n",
+    "    <img src=\"https://varipeps.readthedocs.io/en/latest/_images/square_lattice.svg\"\n",
+    "         alt=\"Two dimensional square lattice with red links indicating horizontal and blue links indicating vertical interactions.\">\n",
+    "    <figcaption><em>Two dimensional square lattice</em></figcaption>\n",
+    "</figure>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8e1498f8-fdc1-4545-a89a-6d602d6ae2ea",
+   "metadata": {},
+   "source": [
+    "The Hamiltonian for the Heisenberg antiferromagnet with constant exchange interaction strength $J > 0$ is defined as:\n",
+    "\n",
+    "$$ H = J \\sum_{\\langle ij \\rangle} \\vec{S}_{i} \\vec{S}_{j} $$\n",
+    "\n",
+    "where $\\langle ij \\rangle$ denotes the sum over all nearest neighbors in the lattice.\n",
+    "\n",
+    "Our aim is now to find the ground state of the model using the variational iPEPS code of the variPEPS library."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2c26bb16-3a92-414f-8a90-79f26d0cc010",
+   "metadata": {},
+   "source": [
+    "<h2>Loading of relevant Python modules</h2>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "eed1c1da-97a2-4d46-a8d8-9c8e3d82ff20",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import varipeps\n",
+    "import jax\n",
+    "import jax.numpy as jnp"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "47850928-d204-4e6e-8c01-418c8277ce4c",
+   "metadata": {},
+   "source": [
+    "First of all we have to load the relevant Python modules for our simulation. The [`varipeps`](https://varipeps.readthedocs.io/en/latest/api/index.html) module includes the full library to perform the variational optimization. Internally it is based on the [`jax`](https://docs.jax.dev/en/latest/) framework and its [`numpy`](https://numpy.org/doc/stable/reference/index.html)-like interface to execute the calculations. Since we will need arrays to define for example the Hamiltonian, we load this numpy interface as well."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fc0c3c0b-f4f0-408b-9b62-105a8744451d",
+   "metadata": {},
+   "source": [
+    "<h2>variPEPS config settings</h2>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "83ba46bc-51e9-41a2-a0b2-f0270960211d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Config Setting\n",
+    "\n",
+    "## Set maximal steps for the CTMRG routine\n",
+    "varipeps.config.ctmrg_max_steps = 100\n",
+    "## Set convergence threshold for the CTMRG routine\n",
+    "varipeps.config.ctmrg_convergence_eps = 1e-7\n",
+    "## Select the method used to calculate the (full) projectors in the CTMRG routine\n",
+    "varipeps.config.ctmrg_full_projector_method = (\n",
+    "    varipeps.config.Projector_Method.FISHMAN\n",
+    ")\n",
+    "## Enable dynamic increase of CTMRG environment bond dimension\n",
+    "varipeps.config.ctmrg_heuristic_increase_chi = True\n",
+    "## Increase CTMRG enviroment bond dimension if truncation error exceeds this value\n",
+    "varipeps.config.ctmrg_heuristic_increase_chi_threshold = 1e-4\n",
+    "\n",
+    "## Set maximal steps for the fix point routine in the gradient calculation\n",
+    "varipeps.config.ad_custom_max_steps = 100\n",
+    "## Set convergence threshold for the fix point routine in the gradient calculation\n",
+    "varipeps.config.ad_custom_convergence_eps = 5e-8\n",
+    "\n",
+    "## Enable/Disable printing of the convergence of the single CTMRG/gradient fix point steps.\n",
+    "## Useful to enable this during debugging, should be disabled for batch runs\n",
+    "varipeps.config.ctmrg_print_steps = False\n",
+    "varipeps.config.ad_custom_print_steps = False\n",
+    "\n",
+    "## Select the method used to calculate the descent direction during optimization\n",
+    "varipeps.config.optimizer_method = varipeps.config.Optimizing_Methods.CG\n",
+    "## Set maximal number of steps for the optimization routine\n",
+    "varipeps.config.optimizer_max_steps = 2000"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "148b69f0-6b36-4528-889d-affce1ea0cf9",
+   "metadata": {},
+   "source": [
+    "The [`varipeps`](https://varipeps.readthedocs.io/en/latest/api/index.html) library allows to configure a large number of numerical parameters to fine-tune the simulation. In this example we include several options commonly used in an optimization run. For a detailed description of the configurable options we refer to the API description of the config class: [`varipeps.config.VariPEPS_Config`](https://varipeps.readthedocs.io/en/latest/api/config.html#varipeps.config.VariPEPS_Config)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8ca36e8f-92e8-4bc2-8248-fd42e72fef91",
+   "metadata": {},
+   "source": [
+    "<h2>Model parameters</h2>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "042b7ebd-63df-42e1-a507-e30e59f85996",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Set constants for the simulation\n",
+    "modelName = \"HeisenbergModel\"\n",
+    "# Interaction strength\n",
+    "J = 1\n",
+    "# iPEPS bond dimension\n",
+    "chiB = 2\n",
+    "# Physical dimension\n",
+    "p = 2\n",
+    "# Maximal enviroment bond dimension\n",
+    "maxChi = 36\n",
+    "# Start value for enviroment bond dimension\n",
+    "startChi = chiB**2 if chiB**2 < maxChi else maxChi"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9f5c5931-2407-4d84-9df0-3afba2ad6120",
+   "metadata": {},
+   "source": [
+    "In this block we define imporant parameters for the model we want to simulate, such as as the interaction strength, the physical dimension of our tensor network and the iPEPS bond dimension. In the last two lines the initial and the maximal enviroment bond dimension is defined. A feature of the variPEPS library is that it not only supports simulation at a fixed enviroment bond dimension, but also a heurisitic increase/decrease of the dimension up to a maximal value. The dynamic change is controlled by the truncation error in the CTMRG projector calculation (increase if the truncation errror becomes too large, decrease if it becomes insignificant). For example, in the config block above the parameter ``ctmrg_heuristic_increase_chi_threshold`` is set to the threshold at which to increase the refinement parameter. The maximal bond dimension ``maxChi`` ensures that the parameter does now grow unbounded, to the point where the memory and computational resources are exhausted."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "089d5b07-76bf-4062-a3e4-e5886b7e668d",
+   "metadata": {},
+   "source": [
+    "<h2>Constructing the Hamiltonian</h2>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "2796f1f6-170b-4a43-a220-37a3f411b40a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# define spin-1/2 matrices\n",
+    "Id = jnp.eye(2)\n",
+    "Sx = jnp.array([[0, 1], [1, 0]]) / 2\n",
+    "Sy = jnp.array([[0, -1j], [1j, 0]]) / 2\n",
+    "Sz = jnp.array([[1, 0], [0, -1]]) / 2\n",
+    "\n",
+    "# construct Hamiltonian terms\n",
+    "hamiltonianGates = J * (jnp.kron(Sx, Sx) + jnp.kron(Sy, Sy) + jnp.kron(Sz, Sz))\n",
+    "\n",
+    "# create function to compute expectation values for the square Heisenberg AFM\n",
+    "exp_func = varipeps.expectation.Two_Sites_Expectation_Value(\n",
+    "    horizontal_gates=(hamiltonianGates,),\n",
+    "    vertical_gates=(hamiltonianGates,),\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "60042a7e-1217-46d0-a78f-3a6c83cf2134",
+   "metadata": {},
+   "source": [
+    "Here the Hamiltonian is constructed for our model. The Heisenberg AFM on the square lattice can be described by the sum of the spin-spin interactions on the horizontal and vertical bonds. Since we assume a constant interaction strength for all bonds in our example, the expectation value can be calculated by the same two-site interaction gate applied in all nearest neighbor directions. The expectation function ``exp_func`` is later used in the optimization to calculate the energy expectation value, which in turn is used as cost function to obtain the ground state."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d0654d74-97f1-475b-8f55-50b6fbfff94c",
+   "metadata": {},
+   "source": [
+    "<h2>Initial unit cell construction</h2>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "483a00e1-062c-4ea6-8f14-fc345aaa2014",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Unit cell structure\n",
+    "structure = [[0, 1], [1, 0]]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9aace0ba-1085-468c-8888-02d4237d771f",
+   "metadata": {},
+   "source": [
+    "Here we define the unit cell structure which is used to simulate our model. In this example we assume a $\\scriptsize{\\begin{matrix}A&B\\\\B&A\\end{matrix}}$-structure, i.e. a two-site antiferromagnetic state."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "04f0cf82-ed0a-45eb-bad1-4044626e13d5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create random initialization for the iPEPS unit cell\n",
+    "unitcell = varipeps.peps.PEPS_Unit_Cell.random(\n",
+    "    structure,  # Unit cell structure\n",
+    "    p,  # Physical dimension\n",
+    "    chiB,  # iPEPS bond dimension\n",
+    "    startChi,  # Start value for enviroment bond dimension\n",
+    "    float,  # Data type for the tensors: `float` (real) or `complex` tensors\n",
+    "    max_chi=maxChi,  # Maximal enviroment bond dimension\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "24fdebb9-62ff-4750-8663-1b4ac44f2ec5",
+   "metadata": {},
+   "source": [
+    "Using the unit cell structure and the model parameter defined above, we can generate an initial unit cell. Here we initialize the iPEPS tensors with random numbers. Other ways to initialize the tensors are provided, for example loading results from a simple update calculation."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7e0ee381-0a00-49a6-9735-c8ae02cf1a87",
+   "metadata": {},
+   "source": [
+    "<h2>Run the optimization</h2>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f3e40cd4-6584-4f0b-aaf7-5268164cb041",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Run optimization\n",
+    "result = varipeps.optimization.optimize_peps_network(\n",
+    "    unitcell,\n",
+    "    exp_func,\n",
+    "    autosave_filename=f\"data/autosave_square_chiB_{chiB:d}.hdf5\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c66e58f4-8710-447c-956b-dc014c4638cf",
+   "metadata": {},
+   "source": [
+    "This function call executes the main function of the library, the variational energy optimization to obtain a good ground state candidate. The function offers several options to customize the optimization for different iPEPS ansätze, such as the spiral iPEPS approach. In our example, we only need to provide the initial unit cell, the function for calculating the energy expectation value, and a file path for autosaving the optimization process, enabling the restoration of interrupted simulations."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "441ca3ab-fcaf-412b-8fff-2d1a9a8736ab",
+   "metadata": {},
+   "source": [
+    "<h2>Evaluate the results</h2>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "69ec6e81-8cf0-4abb-af9b-79789bc53a1e",
+   "metadata": {},
+   "source": [
+    "In this section we show some exemplary evaluation of the result of the optimization."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dc2a1460-976c-4a4c-a099-07d46f5ae361",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Calculate magnetic expectation values\n",
+    "Mag_Gates = [Sx, Sy, Sz]\n",
+    "\n",
+    "\n",
+    "def calc_magnetic(unitcell):\n",
+    "    mag_result = []\n",
+    "    for ti, t in enumerate(unitcell.get_unique_tensors()):\n",
+    "        r = varipeps.expectation.one_site.calc_one_site_multi_gates(\n",
+    "            t.tensor, t, Mag_Gates\n",
+    "        )\n",
+    "        mag_result += r\n",
+    "    return mag_result\n",
+    "\n",
+    "\n",
+    "magnetic_exp_values = calc_magnetic(result.unitcell)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c0b049d1-4507-442e-95f8-dda31ea0e66d",
+   "metadata": {},
+   "source": [
+    "We assume for our example that we are interested in the single-site spin expectation values. These could be used to analyse the $z$-magnetization or the staggered magnetization of our model at/near the ground state."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "52e354b8-06f9-4685-aee4-c908b50886e8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Define some auxiliary data which should be stored along the final iPEPS unit cell\n",
+    "auxiliary_data = {\n",
+    "    \"best_energy\": result.fun,\n",
+    "    \"best_run\": result.best_run,\n",
+    "    \"magnetic_exp_values\": magnetic_exp_values,\n",
+    "}\n",
+    "for k in sorted(result.max_trunc_error_list.keys()):\n",
+    "    auxiliary_data[f\"max_trunc_error_list_{k:d}\"] = result.max_trunc_error_list[k]\n",
+    "    auxiliary_data[f\"step_energies_{k:d}\"] = result.step_energies[k]\n",
+    "    auxiliary_data[f\"step_chi_{k:d}\"] = result.step_chi[k]\n",
+    "    auxiliary_data[f\"step_conv_{k:d}\"] = result.step_conv[k]\n",
+    "    auxiliary_data[f\"step_runtime_{k:d}\"] = result.step_runtime[k]\n",
+    "\n",
+    "# save full iPEPS state\n",
+    "result.unitcell.save_to_file(\n",
+    "    f\"data/heisenberg_square_J_{J:d}_chiB_{chiB:d}_chiMax_{chiM:d}.hdf5\",\n",
+    "    auxiliary_data=auxiliary_data,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "eadb6c10-34be-4ace-b130-51cac295e871",
+   "metadata": {},
+   "source": [
+    "Finally, we want to save the unit cell with the optimized tensors to a file for further analysis. The library allows to store the data directly into a HDF5 file along with user-supplied auxiliary data. Here, for example, we not only want to store the plain tensors but also the calculated energy, meta information from the optimization run (e.g. energy per step or the runtime per step) and the calculated magnetic expectation values. At a later examination of the results, these data can be easily loaded along with the tensors of the tensor network."
+   ]
+  }
+ ],
+ "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.13.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}