{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Overview of adcc\n",
    "\n",
    "ADC-connect – or adcc in short – is a Python-based framework to connect to arbitrary programs and perform calculations based on the algebraic-diagrammatic construction approach (ADC) on top of their existing self-consistent field (SCF) procedures. Four SCF codes can be used with adcc out of the box, namely [molsturm](https://molsturm.org),\n",
    "[psi4](https://psicode.org/), [PySCF](https://github.com/pyscf/pyscf), and [veloxchem](https://veloxchem.org/), see [01_Backends.ipynb](01_Backends.ipynb). Without expressing any particular preference these notebooks will focus on psi4 and pyscf to obtain an SCF reference, but the other codes work very similar.\n",
    "\n",
    "This notebook and the others in the [0_basics](https://github.com/adc-connect/adcc/tree/doc/examples/0_basics) folder will introduce adcc from the practitioners perspective and give an idea of supported features. For a more structured documentation and an API reference, see https://adc-connect.org. In particular for installation instructions see https://adc-connect.org/installation.html. If you cannot be bothered to install adcc just to try these notebooks, just go to https://try.adc-connect.org, which will allow you to play with the notebooks from `0_basics` in your browser.\n",
    "\n",
    "In contrast these notebooks will not put a strong emphasis on the theory and numerical methods behind adcc, save a small  introduction in [02_Theory.ipynb](02_Theory.ipynb). If you have the desire to dig deeper, a review of ADC literature is provided in https://adc-connect.org/theory.html."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A first calculation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Running a simple ADC calculation on top of an HF reference takes pretty much a single line of code. Let's see this in action for computing the excitation spectrum of water in the UV/vis range. First we prepare our reference in psi4 in a cc-pVTZ basis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import psi4\n",
    "import adcc\n",
    "\n",
    "# By default adcc uses all cores on the machnine. For the binder VMs we need\n",
    "# to reduce this a little and tell adcc to use two threads (see 03_Tweaks.ipynb)\n",
    "adcc.set_n_threads(2)\n",
    "\n",
    "# Run SCF in Psi4 using a cc-pVTZ basis\n",
    "mol = psi4.geometry(\"\"\"\n",
    "    O 0 0 0\n",
    "    H 0 0 1.795239827225189\n",
    "    H 1.693194615993441 0 -0.599043184453037\n",
    "    symmetry c1\n",
    "    units au\n",
    "\"\"\")\n",
    "psi4.core.be_quiet()\n",
    "psi4.set_options({'basis': \"cc-pvtz\", })\n",
    "scf_e, wfn = psi4.energy('SCF', return_wfn=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we perform an ADC(2) calculation on top, asking for 10 singlet states:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "state = adcc.adc2(wfn, n_singlets=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are greeted with a nice convergence table and the result of the calculation is stored in the `state`. Now let's actually look at it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "state"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result is again a table, summarising excitation energies, oscillator strengths as well as  `|v1|^2` and `|v2|^2`, the norms of the singles and doubles blocks of the ADC vectors (to be explained in more detail in [02_Theory.ipynb](02_Theory.ipynb)).\n",
    "\n",
    "Note: If you are running adcc from a script, than just `print(state)` will not give you the same answer, instead you will have to explicitly call the `state.describe()` function, like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(state.describe())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With 10 states nicely computed, we want to plot a simulated excitation spectrum, which again can be done in a single function call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "state.plot_spectrum()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The plotted spectrum shows both the exact excitation energies with dashed lines as well as a Lorenzian envelope in solid. Notice that plot spectrum is pretty flexible and takes typical arguments you can pass to a `plt.plot` function call from matplotlib (which it uses under the hood), for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from matplotlib import pyplot as plt\n",
    "\n",
    "state.plot_spectrum(color=\"green\", label=\"ADC(2)\")\n",
    "plt.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another important way to get insight into a result is by looking at the dominating amplitudes (dominating orbital excitations) for each of the states:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(state.describe_amplitudes())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default output is pretty detailed. You can get less printed by increasing the tolerance for printing an amplitude. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(state.describe_amplitudes(0.1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Comparing ADC methods"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us get a feeling for adcc as well as the different ADC methods implemented by comparing the excitation spectra for our water molecule in a single plot. Since visual comparison can certainly not distinguish five digits in the energies we will also lower the convergence tolerance a little to speed up the calculation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from matplotlib import pyplot as plt\n",
    "\n",
    "n_singlets = 10\n",
    "state_1 = adcc.adc1(wfn, n_singlets=n_singlets, conv_tol=1e-3)           # ADC(1)\n",
    "print()\n",
    "state_2x = adcc.adc2x(state.ground_state, n_singlets=n_singlets,         # ADC(2)-x\n",
    "                      guesses=state.excitation_vectors, conv_tol=1e-3)   # use ADC(2) result as guesses\n",
    "print()\n",
    "state_3 = adcc.adc3(state_2x.ground_state, n_singlets=n_singlets,\n",
    "                    guesses=state_2x.excitation_vectors, conv_tol=1e-3)  # ADC(3)\n",
    "\n",
    "# Plot all results in one plot\n",
    "state_1.plot_spectrum(label=\"ADC(1)\")\n",
    "state.plot_spectrum(label=\"ADC(2)\")\n",
    "state_2x.plot_spectrum(label=\"ADC(2)-x\")\n",
    "state_3.plot_spectrum(label=\"ADC(3)\")\n",
    "plt.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One clearly notices the increase in computational time between the methods of the ADC hierarchy. Between ADC(2) and ADC(2)-x the changes are usually most drastic due to an increase in computational scaling (from $O(N^5)$ to $O(N^6)$)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting help\n",
    "\n",
    "Documentation in adcc is still a little sparser than it should. Still most functions are documented and their docstrings can be easily obtained, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "adcc.adc2?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Last but not least, if you find a bug or need help you are always welcome to file [an issue](https://github.com/adc-connect/adcc/issues) or contact us by mail: developers@adc-connect.org."
   ]
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.3rc1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}