{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "aa43e0e7-0c18-4750-9e2b-3a48f106d2ca",
   "metadata": {},
   "source": [
    "# Activity 9: Comparing simulation and experiment with R-factors\n",
    "In order to extract precise crystallographic information from electronic spectroscopy, we need to compare MsSpec calculations with experimental results and adjust the modelling parameters to simulate the experiment as accurately as possible.\n",
    "\n",
    "*R-factors* (reliability factors) are commonly used for this task. In the following example, we will see how MsSpec can extract the adsorption geometry of a molecule.\n",
    "\n",
    "## The unusual tilt of CO molecule on Fe(001)\n",
    "The carbon monoxide molecule can be adsorbed onto a Fe(001) surface in the hollow site. It was experimentally demonstrated that the CO molecule is tilted by 55$\\pm$2° in <100> azimuthal directions. The molecule is bonded to the Fe surface by the carbon atom and the adsorption height was estimated to be $\\sim$ 0.6 Å.\n",
    "\n",
    "(COFe-paper)=\n",
    ":::{seealso}\n",
    "based on this paper from R. S. Saiki *et al.*\n",
    "[Phys. Rev. Lett. **63(3)** p283-6 (1989)](https://doi.org/10.1103/PhysRevLett.63.283)\n",
    ":::\n",
    "\n",
    "We will try to reproduce the polar scan of the figure below of CO adsorbed in the hollow site of the Fe(001) surface with simple single scattering calculations with MsSpec and by using R-Factors to find the best adsorption geometry. We will use the simple cluster displayed on the left hand side of the figure.\n",
    "\n",
    ":::{figure-md} COFe-fig1\n",
    "<img src=\"COFe_fig1.jpg\" alt=\"\" width=\"600px\" align=\"center\">\n",
    "\n",
    "Small cluster used for SSC calculations (left) and (right) Normalized polar scan of the C(1s) at 1202 eV for [100] and [1-10] azimths.\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91c03801-b46b-4844-8c89-655700419063",
   "metadata": {},
   "source": [
    "::::{tab-set}\n",
    "\n",
    ":::{tab-item} <i class=\"fa-solid fa-circle-question\"></i> Quiz\n",
    "Download [this script](./COFe.py) and write the body of the function `create_cluster`. The function should return a \n",
    "small cluster of 5 Fe atoms with the CO molecule adsorbed like in figure {numref}`Fig. %s <COFe-fig2>` below. The function\n",
    "will accept 4 keyword arguments to control the adsorption geometry.\n",
    "\n",
    "```{figure-md} COFe-fig2\n",
    "<img src=\"COFe_fig2.jpg\" alt=\"CO-Fe adsorption geometry\" width=\"600px\" align=\"center\">\n",
    "\n",
    "Adsorption geometry of carbon monoxide on Fe(001).\n",
    "```\n",
    "\n",
    "```{note}\n",
    "Remember to use the [`ase.build.bulk`](https://wiki.fysik.dtu.dk/ase/ase/build/build.html#ase.build.bulk), the [`msspec.utils.hemispherical_cluster`](https://msspec.cnrs.fr/faq/hemispherical_cluster/hemispherical_cluster.html#hemispherical-cluster-faq) and the [`ase.build.add_adsorbate`](https://wiki.fysik.dtu.dk/ase/ase/build/surface.html#ase.build.add_adsorbate) \n",
    "functions.\n",
    "```\n",
    "\n",
    ":::\n",
    "\n",
    "::::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1be5047-fb75-4e98-a6a2-fc6f678e68ff",
   "metadata": {},
   "source": [
    "```{toggle}\n",
    "Here is the code of the `create_cluster` function\n",
    "\n",
    ":::{literalinclude} COFe_completed.py\n",
    ":lines: 10-35\n",
    ":emphasize-lines: 10-21\n",
    ":::\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7697c4f-949b-4261-abaf-96eefaa9a6ba",
   "metadata": {},
   "source": [
    "Now that the `create_cluster` function is done, look at the rest of the script. The next function is called `compute_polar_scan` and will obviously be used to compute the $\\theta$-scan of the C1s for a given cluster geometry.\n",
    "Finally there is the *Main part* that is built in two sections:\n",
    "\n",
    "1. A section containing nested *for loops*\n",
    "2. A final section for *R-Factor analysis*\n",
    "\n",
    "::::{tab-set}\n",
    "\n",
    ":::{tab-item} <i class=\"fa-solid fa-circle-question\"></i> Quiz\n",
    "1. Complete the nested for loops in section 1) in order to compute polar scans for CO molecule tilted from 45° to 60° with a 1° step and aligned either along the [100] direction of Fe, 30° from this direction or along [110]. The adsorption height is 0.6 Å and the bond length is 1.157 Å.\n",
    "2. What is the best $(\\theta, \\phi)$ according to the R-Factor analysis\n",
    ":::\n",
    "\n",
    "::::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "670cbd24-efd4-4c51-89e2-f1d96c53908d",
   "metadata": {},
   "source": [
    "```{toggle}\n",
    "Here are the code of the nested *for loops*\n",
    "\n",
    ":::{literalinclude} COFe_completed.py\n",
    ":lines: 58-79\n",
    ":emphasize-lines: 10,11,13,14,16\n",
    ":::\n",
    "\n",
    "Runing the code gives the following result. The CO molecule belongs to the (100), (010), (-100), (0-10) planes of iron and is tilted by 55° from the surface normal (*ie* 35° from the surface itself).\n",
    "\n",
    ":::{figure-md} COFe-comparison\n",
    "<img src=\"Comparison.png\" alt=\"R-Factor result\" width=\"600px\" align=\"center\">\n",
    "\n",
    "Best polar scan according to R-Factor analysis.\n",
    ":::\n",
    "\n",
    "MsSpec uses 12 different R-Factors formula to compare the calculted curve to the experimental data. The set of parameters giving the best agreement according to the majority of those 12 R-factors is assumed to be the best solution. Here are the R-factors formula used in MsSpec\n",
    "\n",
    ":::{figure-md} rfactors-formula\n",
    "<img src=\"formula.jpg\" alt=\"R-Factor result\" width=\"800px\" align=\"center\">\n",
    "\n",
    "The 12 R-Factors used in MsSpec. The Pendry's R-Factor is n° ??\n",
    ":::\n",
    "\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f7827b3c-0cac-42e2-a587-8b30ee3632b4",
   "metadata": {},
   "source": [
    "::::{tab-set}\n",
    "\n",
    ":::{tab-item} <i class=\"fa-solid fa-circle-question\"></i> Quiz\n",
    "How many R-Factors do agree that $(\\theta,\\phi)=(55,0)$ gives the best agreement ?\n",
    ":::\n",
    "\n",
    "::::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa8d2dc4-286a-441d-9c21-dab6bac8145c",
   "metadata": {},
   "source": [
    "```{toggle}\n",
    "\n",
    "6 R-factors out of 12 do agree that *variable set n°30* gives the best agreement. The set n°30 corresponds to\n",
    "$\\theta=55°$ and $\\phi=0°$.\n",
    "\n",
    ":::{figure-md} results\n",
    "<img src=\"results.png\" alt=\"results\" width=\"800px\" align=\"center\">\n",
    "\n",
    "The number of R-Factors for which the parameter set (in abscissa) gives the best agreement.\n",
    ":::\n",
    "\n",
    "\n",
    "```"
   ]
  }
 ],
 "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.11.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
