00-Getting_started.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "\n",
    "%matplotlib widget\n",
    "import numpy as np\n",
    "import scipy as sp\n",
    "import matplotlib as mpl\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from scwidgets import (AnswerRegistry, TextareaAnswer, CodeDemo,\n",
    "                       ParametersBox, PyplotOutput, ClearedOutput,\n",
    "                       AnimationOutput,CheckRegistry)\n",
    "\n",
    "from widget_code_input import WidgetCodeInput\n",
    "\n",
    "import ase\n",
    "import chemiscope"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to atomic-scale modeling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This course provides a hands-on introduction to the modeling of materials at the atomic scale. \n",
    "The purpose is both to provide a first example of the application of some of the techniques used to predict and characterize the behavior of materials in terms of the fundamental physical laws that govern the interactions between their atoms, as well as to demonstrate in a practical, numerical way some of the foundational concepts of materials science, such as the formation of crystal structures, \n",
    "\n",
    "The course is organized as a series of Jupyter notebooks, each covering one module:\n",
    "\n",
    "1. [Atomic structures on a computer](./01-Atomic_scale_structures.ipynb)\n",
    "2. [Crystallography and diffraction](./02-Crystallography.ipynb)\n",
    "3. [Vibrations in solids, phonons](./03-Lattice_dynamics.ipynb)\n",
    "4. [Interatomic potentials](./04-Potentials.ipynb)\n",
    "5. [Defects in solids](./05-Defects.ipynb)\n",
    "6. [Molecular dynamics](./06-Molecular_dynamics.ipynb)\n",
    "7. [Machine learning](./07-Machine_learning.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Course how-to"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The course contains a combination of text-book-style explanations, simple mathematical derivations, and interactive widgets in which you need to manipulate functions or atomic structures, and/or enter short snippets of code. The course material is conceived so that minimal amounts of prior knowledge about Python or Jupyter notebooks is needed, but you will have to do _some_ coding. \n",
    "If your Python is rusty, you can look at this [brief re-cap](./00b-Atomic_scale_structures.ipynb) that summarizes some of the topics (modules, classes, NumPy) that you might have not seen before. Looking up examples and documentation online is fine, and even encouraged."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At the top of each notebook you will find a box to enter your name. This will also be used to create a file in which you can save (and load from) the answers you have given to exercises and text widgets. We suggest to use `SurnameName`, which will lead to a file named `module_XX-SurnameName.json`. If you are looking at these notebooks as part of a formal course, you will be able to send these for grading. \n",
    "\n",
    "_NB: the state of the widgets is not saved automatically, so remember to click \"Save\" once you are done with each exercise._"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "check_registry = CheckRegistry()  # this is needed to coordinate code checking\n",
    "answer_registry = AnswerRegistry(prefix=\"module_00\")\n",
    "display(answer_registry)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style=\"color:blue\">\n",
    "<b>01</b> Throughout the notebook you will find highlighted paragraphs with a bold number.  These are instructions that you need to follow to answer some exercises, or comment on what you observe in interactive widgets. \n",
    "</span>\n",
    "\n",
    "This might imply typing some open answer commenting the results you are seeing, or reporting the result of some simple derivation. Please keep this as tidy and clean: be concise and to the point, this is to help you collect your thoughts as much as to provide evaluation.  For example, this is a box to answer an open question: experiment with saving and loading the answer: should be pretty intuitive but it's better to figure it out here. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "answerbox = TextareaAnswer(\"Write here your answer\")\n",
    "answer_registry.register_answer_widget(\"answerbox-example\", answerbox)\n",
    "display(answerbox)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Appmode, hide inputs, and dependencies"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The notebooks work on both Jupyter classic notebooks and in JupyterLab. To help you focus on the content and not on the quirks of building an interactive notebook, they are designed to function without the need for you to enter code into input cells, but only inside dedicated widgets. To avoid being distracted, you can hide the input cells using the *Appmode* Jupyter plugin (for Jupyter classic), which you can activate by clicking on the corresponding button\n",
    "<img src=\"figures/appmode_button.png\" width=\"80\"/>, or the *hide code* extension for JupyterLab, which you can activate clicking the \"hide input\" icon <img src=\"figures/hidecode_button.png\" height=\"20\"/>. After clicking on the \"hide input\" icon, please restart and rerun the notebook by clicking on the <img src=\"figures/rerunnotebook_button.png\" height=\"20\"/> icon. Students with stronger programming background, who want to look \"under the hood\", can look at the source code at any time switching on and off these extensions (NB: save your progress before doing so, as some content might get lost). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you are using these notebooks for a course using your school's jupyter server, you should find yourself in a fully-configured environment, or you should ask the instructor to have it set up for you. If instead you are using them on your own system, you may need to install several prerequisites. In this case, from the main folder, run `pip install -r requirements.txt`, or a similar command with your favourite Python package manager."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interactive widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The notebooks often contain interactive widgets that can be manipulated by changing some slider values, to visualize the concepts being discussed. Usually these don't require any coding, just to follow some instructions and/or to experiment with the values do develop a more intuitive understanding of the significance of an equation, or to test its limits."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plot_sine(ax, w, a, abval):\n",
    "    xgrid = np.linspace(0,5,100)\n",
    "    if abval:\n",
    "        ax.plot(xgrid, np.abs(a*np.sin(xgrid*w)))\n",
    "        ax.set_ylabel(r\"$|\\sin x|$\")\n",
    "    else:\n",
    "        ax.plot(xgrid, a*np.sin(xgrid*w))\n",
    "        ax.set_ylabel(r\"$\\sin x$\")\n",
    "    ax.set_xlabel(\"$x$\")\n",
    "    \n",
    "sine_parameterbox = ParametersBox(w = (2.0, 0, 10, 0.1, r'$\\omega$'), a = (2., 1,100, 2, r'$A$'), \n",
    "                                  abval=(False, r'Absolute value'))\n",
    "sine_fig, sine_ax = plt.subplots(1,1,figsize=(5,3.5))\n",
    "sine_output =  PyplotOutput(sine_fig)\n",
    "\n",
    "def sine_update(w,a, abval, visualizers):\n",
    "    pyplot_output = visualizers[0]\n",
    "    axes = pyplot_output.figure.get_axes()[0]\n",
    "    plot_sine(axes,w,a,abval)\n",
    "    \n",
    "sine_demo = CodeDemo(\n",
    "            input_parameters_box = sine_parameterbox,\n",
    "            visualizers=[sine_output],\n",
    "            update_visualizers=sine_update,\n",
    "            \n",
    "            ) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The widget displays a sine function $y = A \\sin \\omega x$, that oscillates with a period $2\\pi/\\omega$ amd an amplitude spanning the range $[-A,A]$.\n",
    "Optionally, you can compute (and plot) the absolute value of the function. \n",
    "When you modify the values of the parameters, the plot is automatically updated. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(sine_demo)\n",
    "sine_demo.run_demo()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sine_parameterbox_click = ParametersBox(w = (2.0, 0, 10, 0.1, r'$\\omega$'), a = (2., 1,100, 2, r'$A$'), \n",
    "                                  abval=(False, r'Absolute value'), refresh_mode=\"click\")\n",
    "sine_fig_click, sine_ax_click = plt.subplots(1,1,figsize=(5,3.5))\n",
    "sine_output_click =  PyplotOutput(sine_fig_click)\n",
    "\n",
    "sine_demo_click = CodeDemo(\n",
    "            input_parameters_box = sine_parameterbox_click,\n",
    "            visualizers=[sine_output_click],\n",
    "            update_visualizers=sine_update\n",
    "            ) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some more time-consuming visualizations cannot be updated on-the-fly. In these cases, you'll find an _Update_ button that you can press after you have set all the parameters to your liking. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(sine_demo_click)\n",
    "sine_demo_click.run_demo()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "structures = [ ase.Atoms(\"OH2\", positions=np.asarray([[0,0,0], [0.7,0.5,0],  [-0.7,0.5,0]])*np.asarray([[0,s1,s2]]).T) for s1 in [0.9,1,1.1,1.2] for s2 in [0.9,1,1.1,1.2] ]\n",
    "properties = np.asarray([(s1, s2, (s1-1)**2+(s2-1)**2) for s1 in [0.9,1,1.1,1.2] for s2 in [0.9,1,1.1,1.2] ] )\n",
    "properties = { \"stretch_1\":  properties[:,0]-1, \"stretch_2\":  properties[:,1]-1, \"energy\" : properties[:,2] }\n",
    "cs = chemiscope.show(structures, properties, meta= {\"name\": \"Water molecules\", \"description\": \"Stretched water molecules with completely made up energy\"},mode=\"structure\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also display atomic structures in a dedicated [chemiscope](https://chemiscope.org/) widget. Experiment with the settings for visualizing the structure by clicking on the <img src=\"figures/chemiscopesettings_button.png\" height=\"20\"/> icon. Also try clicking on the structure information <img src=\"figures/chemiscopeinfo_button.png\" height=\"20\"/> field and the play button below the structure panel."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(cs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Chemiscope also allows to associate a list of properties with the corresponding structures, displaying an interactive map that allows, by clicking, to view the corresponding structure. You can change the visualization settings if you want, and save a snapshot of either the plot or the structure.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Code widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some exercises require inputting short code snippets into a dedicated code widget. This code forms the body of a function, whose return value can then be checked by plotting, or by comparison with known reference values. The function is run as a stand-alone Python code, so you can only use variables and modules that are defined or imported within the code widget. Each code widget has its separate scope."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wci_code = WidgetCodeInput(\n",
    "        function_name=\"plot_function\", \n",
    "        function_parameters=\"x, a, w, f_abs\",\n",
    "        code_theme = \"default\",\n",
    "        docstring=\"\"\"\n",
    "Computes the sine function with a given frequency and amplitude, optionally taking the absolute value\n",
    "\n",
    ":param x: the input variable\n",
    ":param a: the amplitude\n",
    ":param w: the frequency\n",
    ":param f_abs: bool: take the absolute value?\n",
    "\n",
    ":return: abs(a*sin(w x)) if f_abs else a*sin(w x)\n",
    "\"\"\",\n",
    "            function_body=\"\"\"\n",
    "# Write your solution, then click on the button below to update the plotter and check against the reference values\n",
    "from math import sin\n",
    "if f_abs:\n",
    "    return abs(a*sin(w*x))\n",
    "else:\n",
    "    return a*sin(w*x)\n",
    "\"\"\"\n",
    "        )\n",
    "\n",
    "\n",
    "\n",
    "code_fig = plt.figure()\n",
    "code_fig.add_subplot(111)\n",
    "code_plot = PyplotOutput(code_fig)\n",
    "\n",
    "def code_update(w, a, f_abs, code_input, visualizers):\n",
    "    pyplot_output = visualizers[0]\n",
    "    ax = pyplot_output.figure.get_axes()[0]\n",
    "    func = code_input.get_function_object()\n",
    "    xgrid = np.linspace(-10,10,500)    \n",
    "    ygrid = np.asarray([ func(x, a, w, f_abs) for x in xgrid])\n",
    "    ax.plot(xgrid, ygrid, 'b-')\n",
    "    ax.set_xlabel(r\"x\")\n",
    "    ax.set_ylabel(\"y\")    \n",
    "    \n",
    "code_parameterbox = ParametersBox(w = (2.0, 0, 10, 0.1, r'$\\omega$'), a = (2., 1,100, 2, r'$A$'), \n",
    "                                  abval=(False, r'Absolute value'), refresh_mode=\"click\")\n",
    "code_demo = CodeDemo( \n",
    "            code_input = wci_code,\n",
    "            check_registry = check_registry,\n",
    "            input_parameters_box=code_parameterbox,\n",
    "            visualizers = [code_plot],\n",
    "            update_visualizers=code_update,\n",
    "            merge_check_and_update_buttons=False,\n",
    "            ) \n",
    "\n",
    "check_registry.add_check(code_demo,\n",
    "                         inputs_parameters=[{\"x\" : 2, \"w\":1, \"a\":2, \"f_abs\":False}, \n",
    "                                            {\"x\" : 1, \"w\":-0.5, \"a\":0.2, \"f_abs\":True},\n",
    "                                           ],\n",
    "                         reference_outputs=[1.8185948536513634, 0.0958851077208406],\n",
    "                         equal=np.allclose\n",
    "                         )\n",
    "            \n",
    "answer_registry.register_answer_widget(\"code_function\", code_demo)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# check_registry.print_reference_outputs(code_demo, ignore_errors=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style=\"color:blue\">\n",
    "<b>02</b> Many of the answers you will have to give involve simple coding exercises. \n",
    "</span>\n",
    "\n",
    "To answer these questions you just need to write a function that performs the task specified. In this case, the function is already written and computes the sine. \n",
    "Often you'll see these exercises associated with a visualizer that displays e.g. the function you compute, helping you understand if there is an error, and just familiarize yourself with the concepts. \n",
    "\n",
    "To help you check whether the code is producing correct results, you will usually also find a _Check_ button, that runs a few tests and returns either a confirmation that the core has run correctly, or some errors that may help you correct mistakes.\n",
    "\n",
    "Finally, remember to _Save_ your code before moving on to the next exercise. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(code_demo)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "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.10.12"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": false,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": false,
   "user_envs_cfg": false
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {
    "height": "160px",
    "width": "252px"
   },
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "461px",
    "left": "0px",
    "right": "927.667px",
    "top": "107px",
    "width": "139px"
   },
   "toc_section_display": "block",
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}