examples/0_basics/01_Backends.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Supported Backends\n",
    "\n",
    "Since adcc does not implement a self-consistent field procedure or any integral computation routine it is only an addon to existing backends providing such functionality. Before starting an ADC calculation a Hartree-Fock reference first needs to be computed in a third-party code. For this purpose four codes are tightly integrated with adcc: [molsturm](https://molsturm.org), [psi4](https://psicode.org/), [PySCF](https://github.com/pyscf/pyscf), and [veloxchem](https://veloxchem.org/).\n",
    "\n",
    "While other codes are supported out of the box, they can still be used if the required data can be stored inside a python dictionary or in an HDF5 file in the format expected by adcc, see the [last section of this notebook](#Starting-calculations-from-pregenerated-data). One should note that adding support for further host programs is rather simple, see https://adc-connect.org/q/hostprograms for details and feel free to contact us if you want to add support for another code.\n",
    "\n",
    "For our discussion we will mostly focus on PySCF and Psi4, the codes for which integration and performance is best and supported featureset is most exhaustive."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## PySCF backend\n",
    "\n",
    "[PySCF](http://pyscf.org/) is a python-based package for a large range of quantum-chemistry methods. It can be easily installed from [pypi](https://pypi.org/project/pyscf/) or [conda](https://anaconda.org/pyscf/pyscf), see the [detailed installation instructions](http://pyscf.org/pyscf/install.html). See their great [tutorial](http://pyscf.org/pyscf/tutorial.html) for details how to setup geometries and SCF calculations.\n",
    "\n",
    "The water example from [00_Overview.ipynb](00_Overview.ipynb) would look like this using PySCF:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note: PySCF is not installed on try.adc-connect.org, so this cell won't work there.\n",
    "import adcc\n",
    "from pyscf import gto, scf\n",
    "adcc.set_n_threads(2)  # Reduce threads for binder VMs (see 03_Tweaks.ipynb)\n",
    "\n",
    "# Run SCF in pyscf using a cc-pVTZ basis\n",
    "mol = gto.M(\n",
    "    atom='O 0 0 0;'\n",
    "         'H 0 0 1.795239827225189;'\n",
    "         'H 1.693194615993441 0 -0.599043184453037',\n",
    "    basis='cc-pvtz',\n",
    "    unit=\"Bohr\",\n",
    ")\n",
    "mf = scf.HF(mol)\n",
    "mf.kernel()\n",
    "\n",
    "# Run ADC(2) for 10 states\n",
    "state = adcc.adc2(mf, n_singlets=10)\n",
    "print(state.describe())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that aspects such as the one- and two-electron integrals, the molecular geometry and so on are passed to adcc automatically without any additional intervention from the user.\n",
    "\n",
    "##### Strengths and weaknesses of the PySCF backend\n",
    "- Restricted and unrestricted references supported\n",
    "- Fastest AO to MO transformation of of the supported host programs, thus usually best performance\n",
    "- Supports the generation of core holes (X-ray emission spectroscopy)\n",
    "- Incomplete integration of adcc into PySCF itself: Not all features of PySCF can be used with adcc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Psi4 backend\n",
    "\n",
    "[Psi4](http://www.psicode.org/) is a quantum-chemistry package with a broad range of features including a rich and powerful python frontend. It can be easily installed from [conda](https://anaconda.org/psi4/psi4), see their [detailed installation instructions](http://psicode.org/psi4manual/1.3.2/external.html). For getting started with the code a [tutorial](http://psicode.org/psi4manual/1.3.2/psiapi.html) is available. \n",
    "\n",
    "For completeness we show again the water example from [00_Overview.ipynb](00_Overview.ipynb):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import psi4\n",
    "import adcc\n",
    "adcc.set_n_threads(2)  # Reduce threads for binder VMs (see 03_Tweaks.ipynb)\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",
    "_, wfn = psi4.energy('SCF', return_wfn=True)\n",
    "\n",
    "# Run ADC(2) for 10 states\n",
    "state = adcc.adc2(wfn, n_singlets=10)\n",
    "print(state.describe())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Strengths and weaknesses of the Psi4 backend\n",
    "- Restricted and unrestricted references supported\n",
    "- Slightly slower than the PySCF backend, since AO to MO transformation not yet properly parallelised.\n",
    "- Most feature complete integration, including a direct integration of adcc into Psi4 (see next section)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using adcc within the Psi4 package\n",
    "\n",
    "Not only can Psi4 SCF results be used to drive ADC calculations in adcc, but the integration of both packages is so close, that the reverse can be achieved as well. The next code example shows the same water calculation as above, but this time using only functions from Psi4."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import psi4\n",
    "\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.set_output_file(\"/tmp/psi4.out\")\n",
    "psi4.set_options({\n",
    "    \"basis\": \"cc-pvtz\",\n",
    "    \"roots_per_irrep\": [10],\n",
    "    \"kind\": \"singlet\",\n",
    "    \"qc_module\": \"adcc\",\n",
    "})\n",
    "psi4.properties(\"adc(2)\", properties=[\"oscillator_strength\"])\n",
    "\n",
    "print(open(\"/tmp/psi4.out\", \"r\").read())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a similar way adcc calculations can be directly run from Psi4's [Psithon plain text input files](http://www.psicode.org/psi4manual/1.3.2/psithoninput.html) as well if desired."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other backends\n",
    "\n",
    "This section presents the above water example for the other supported backends."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### molsturm\n",
    "**Website:** https://molsturm.org "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note: molsturm is not installed on try.adc-connect.org, so this cell won't work there.\n",
    "import molsturm\n",
    "import adcc\n",
    "\n",
    "# Run Hartree-Fock in \n",
    "water = molsturm.System([\"O\", \"H\", \"H\"], [\n",
    "    [0, 0, 0],\n",
    "    [0, 0, 1.795239827225189],\n",
    "    [1.693194615993441, 0, -0.599043184453037]\n",
    "])\n",
    "scfres = molsturm.hartree_fock(water, basis_type=\"gaussian\", basis_set_name=\"cc-pvdz\")\n",
    "\n",
    "# Run ADC(2) for 10 states\n",
    "state = adcc.adc2(scfres, n_singlets=10)\n",
    "print(state.describe())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Veloxchem\n",
    "**Website:** https://veloxchem.org  \n",
    "**Documentation:** https://veloxchem.org/manual"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note: veloxchem is not installed on try.adc-connect.org, so this cell won't work there.\n",
    "import os\n",
    "import adcc\n",
    "import tempfile\n",
    "\n",
    "import veloxchem as vlx\n",
    "from mpi4py import MPI\n",
    "from veloxchem.mpitask import MpiTask\n",
    "\n",
    "# Run SCF in Veloxchem\n",
    "with tempfile.TemporaryDirectory() as tmpdir:\n",
    "    infile = os.path.join(tmpdir, \"vlx.in\")\n",
    "    outfile = os.path.join(tmpdir, \"vlx.out\")\n",
    "\n",
    "    with open(infile, \"w\") as fp:\n",
    "        fp.write(\"\"\"\n",
    "                 @jobs\n",
    "                 task: hf\n",
    "                 @end\n",
    "\n",
    "                 @method settings\n",
    "                 basis: cc-pvtz\n",
    "                 @end\n",
    "\n",
    "                 @molecule\n",
    "                 charge: 0\n",
    "                 multiplicity: 1\n",
    "                 units: bohr\n",
    "                 xyz:\n",
    "                 O 0 0 0\n",
    "                 H 0 0 1.795239827225189\n",
    "                 H 1.693194615993441 0 -0.599043184453037\n",
    "                 @end\n",
    "                 \"\"\")\n",
    "    task = MpiTask([infile, outfile], MPI.COMM_WORLD)\n",
    "    scfdrv = vlx.ScfRestrictedDriver(task.mpi_comm, task.ostream)\n",
    "    scfdrv.compute(task.molecule, task.ao_basis, task.min_basis)\n",
    "    scfdrv.task = task\n",
    "\n",
    "# Run ADC(2) for 10 states\n",
    "state = adcc.adc2(scfdrv, n_singlets=10)\n",
    "print(state.describe())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Starting calculations from pregenerated data\n",
    "\n",
    "If adcc does not have an interface for the SCF code of your choice, you can still start an ADC calculation in adcc from the Hartree Fock results. The only requirement is that you can export the Fock matrix, the two-electron integrals and a few other quantities. The latter you can feed directly to adcc in a python dictionary or by reading them from an HDF5 file. For details on the format of the expected data, see https://adc-connect.org/q/hostprograms.\n",
    "\n",
    "To provide you with a small example this repository is shipped with the HDF5 file `h2o_sto3g_hfdata.hdf5`, which contains precomputed data for water in an STO-3G basis in the expected format. To start a calculation from such data, just pass the file name of the HDF5 file or the python dictionary to adcc:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import adcc\n",
    "state = adcc.adc2x(\"h2o_sto3g_hfdata.hdf5\", n_singlets=5)\n",
    "print(state.describe())"
   ]
  }
 ],
 "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}