{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "56aad15a-a5b3-47d9-8753-56d56b419011",
   "metadata": {},
   "source": [
    "# Using material fingerprints"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "950dc761-5074-4827-9608-963c7e0ef4e4",
   "metadata": {},
   "source": [
    "In order to use materials data with data analytics and machine learning methods, often it is necessary to encode material properties, like the atomic or electronic structure, typically as vectors of real values. In MADAS, a fingerprint is the combination of a _descriptor_, i.e., an encoding of material properties, and a _similarity measure_, i.e., a function that takes two descriptors as arguments and returns their similarity in a range between 0 and 1, where 0 means that both fingerprints are completely dissimilar, and 1 means that they are identical. MADAS allows to compute different built-in fingerprints, as well as supports the creation of custom fingerprints."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "46fa445a-732d-4818-bb65-b513b401b7bf",
   "metadata": {},
   "source": [
    "In this tutorial you are going to learn how to:\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    \n",
    "**[Use built-in fingerprints](#Use-built-in-fingerprints)**  \n",
    "**[Create custom fingerprints](#Create-custom-fingerprints)**  \n",
    "\n",
    "</div>\n",
    "\n",
    "Let's get started!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f98afa9-b29d-49a2-9038-6695db77d9e6",
   "metadata": {},
   "source": [
    "## Preparations"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5942e6fa-e405-4a20-a2bd-c83e84b6ebb0",
   "metadata": {},
   "source": [
    "This tutorial uses a database that was created in the first tutorial \"Downloading and managing data with MADAS\". It is suggested to do the tutorials in order, because we will use some functions that are explained in detail in the prior tutorials.  \n",
    "The following lines will create the same data if you didn't do the first tutorial yet. If you did it already, the data will not be downloaded again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "7fa2993e-6abd-4a02-890d-5b0cc1bfb9fa",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2026-04-09 18:37:06,107 - materials_database_log - INFO - Query has already been performed.\n"
     ]
    }
   ],
   "source": [
    "from madas import MaterialsDatabase\n",
    "\n",
    "query = {\n",
    "    \"results.material.symmetry.crystal_system:any\": [\n",
    "      \"cubic\"\n",
    "    ],\n",
    "    \"results.method.simulation.dft.xc_functional_type:any\": [\n",
    "      \"hybrid\"\n",
    "    ],\n",
    "    \"datasets.dataset_name:any\": [\n",
    "      \"Materials Database from All-electron Hybrid Functional DFT Calculations\"\n",
    "    ],\n",
    "    \"results.properties.available_properties:all\": [\n",
    "      \"dos_electronic\"\n",
    "    ]\n",
    "  }\n",
    "\n",
    "db = MaterialsDatabase(filename='materials_database.db')\n",
    "\n",
    "db.fill_database(query)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1eac1907-d5c6-407c-84b7-7151b1e208f7",
   "metadata": {},
   "source": [
    "The database contains cubic materials from a high-throughput dataset computed using the hybrid HSE06 exchange-correlation functional with density functional theory."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b4d80d5f-62d1-4232-bd7d-08c28599c8d2",
   "metadata": {},
   "source": [
    "## Use built-in fingerprints"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03ad6bf4-9745-465e-93e4-55f7c741272c",
   "metadata": {},
   "source": [
    "First, we are going to use build-in fingerprints to encode the electronic density-of-states (DOS) of these structures.  \n",
    "In the first tutorial, we created a database of these compounds, but currently, the DOS of the compounds is still hidden in the NOMAD archive, and not available as a property directly. We therefore need to find this data and update the database."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08de577b-1a82-44d9-8dfa-5264951c4b32",
   "metadata": {},
   "source": [
    "### Updating the database"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10822cd9-e421-47b6-ac60-5c7d86ff3d97",
   "metadata": {},
   "source": [
    "First, let's identity where we can find the DOS in the NOMAD archive."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "b7a617a8-5eb4-4c31-a4b9-975483c759c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "from madas.utils import print_key_paths"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "572f9368-0ca6-4d78-9c05-cdb7a92f53d4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "/archive/run/0/calculation/0/dos_electronic\n",
      "/archive/results/properties/electronic/dos_electronic\n"
     ]
    }
   ],
   "source": [
    "print_key_paths('dos_electronic', db[0].data)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d846bf43-09dc-4707-82b8-8bb55c9f7673",
   "metadata": {},
   "source": [
    "We can see that there are two paths, of wich one is in the in the results section. Let's investigate what is in there."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "3d5b8cfc-bb6f-4f75-aaf0-0ad409f58473",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'energies': '#/run/0/calculation/0/dos_electronic/0/energies',\n",
       "  'total': ['#/run/0/calculation/0/dos_electronic/0/total/0'],\n",
       "  'energy_fermi': -1.1571642761128223e-18}]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db[0].get_data_by_path(\"archive/results/properties/electronic/dos_electronic\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f47a8018-2ae9-420d-8387-d2881a61bffb",
   "metadata": {},
   "source": [
    "We can see that the data here contains paths to the converged total DOS and DOS energies, as well as the Fermi energy. Both paths have a common root. We can investigate what we find there:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "2f7ca5cf-a6d6-4ba9-b39f-365247214341",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['n_energies', 'energies', 'energy_fermi', 'energy_ref', 'total', 'species_projected', 'atom_projected', 'orbital_projected', 'fingerprint', 'band_gap'])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db[0].get_data_by_path(\"archive/run/0/calculation/0/dos_electronic/0\").keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf2daaa0-975e-4238-bdef-1dc718bfa2f4",
   "metadata": {},
   "source": [
    "In all those keys we can find the information we need to prepare the DOS in a human-readable way:  \n",
    "- `total` contains the values of the total DOS  \n",
    "- `energies` contains the energies at which the DOS is evaluated  \n",
    "- `energy_ref` is a shift that needs to be applied to the energy to shift the energy 0 to the valance band edge for semiconductors, or the Fermi energy for metals  \n",
    "\n",
    "With this information, we can write functions that give us the DOS energies and values from the archive.  \n",
    "Please note that these functions may not work reliably for any selection of data, but are tailored to this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "10284dda-6576-44d1-8885-7b4df25229cf",
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.constants import electron_volt\n",
    "import numpy as np\n",
    "\n",
    "from madas import Material\n",
    "\n",
    "def get_dos_values(material: Material) -> list:\n",
    "    \"\"\"\n",
    "    Get total DOS per unit cell and eV from NOMAD archive dictionary.\n",
    "    \"\"\"\n",
    "    path_ = material.get_data_by_path(\"archive/results/properties/electronic/dos_electronic/0/total/0\")\n",
    "    dos = np.array(material.get_data_by_path(f'archive{path_[1:]}/value')) * electron_volt\n",
    "    return dos.tolist()\n",
    "    \n",
    "def get_dos_energies(material: Material) -> list:\n",
    "    \"\"\"\n",
    "    Get DOS energies in eV from a NOMAD archive dictionary, normalized such that E=0 is at the VBM.\n",
    "    \"\"\"\n",
    "    energies_path = material.get_data_by_path(\"archive/results/properties/electronic/dos_electronic/0/energies\")\n",
    "    energies_ref = f\"archive{energies_path[1:]}\"\n",
    "    energies = material.get_data_by_path(energies_ref)\n",
    "    ref_path = '/'.join(energies_ref.split('/')[:-1]+['energy_ref'])\n",
    "    ref_energy = material.get_data_by_path(ref_path)\n",
    "    dos_energies = (np.array(energies) - ref_energy) / electron_volt\n",
    "    return dos_energies.tolist()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32dcd39f-903f-4250-815d-c07dda9e3273",
   "metadata": {},
   "source": [
    "We should test that our functions work:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "0fede28c-1377-41bd-82e6-4a97bec3e1d0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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PTZAAADQfCw0vgCA4+Zyd8EOHTro+uuv17Rp09SrV686z+nevbvuvvtujw0OAAA0L6u1numCXhoPALRGLleyZsyYoY8//lh9+/bV6aefrvnz56ukpKQpxwYAAJpZvdMFSVkA4DKXQ9ZDDz2knTt3avHixerWrZtuv/12JSQk6KabbtKKFSuacowAAKCZVGcspgsCwHFwu/HF2LFj9dZbbykjI0PPPfectm7dquTkZPXv31///Oc/m2KMAACgmTi6C1anK3srdyIWALjO7ZBlFxoaqhtvvFG//fabvvrqK2VkZOi+++7z5NgAAEAzc0wXdLxCYLogALir0SGrpKRE8+fP15gxY3TBBRcoOjpaTz75pCfHBgAAmlmtfbIclSxSFgC4yuXugna///673nzzTS1YsEBVVVW65JJL9Pjjj2v06NFNMT4AANCMajW+qD5utXppQADQCrkcsp555hnNmzdP27dv1/Dhw/Xss8/qyiuvVFhYWFOODwAANCPLUS3c7WELAOA6l0PWs88+q2uuuUYLFizQgAEDmnJMAADAS45ufEF3QQBwn8shKy0tTX5+fk7HysrKFBgY6PFBAQAA77BUTws0OaYLVje+8NaAAKAVcrnxhT1gWa1WPf744+rQoYNCQ0O1e/duSbZ9tN54442mGSUAAGgWFkfjC9tleyXLSiULAFzmdnfBJ554QvPnz9czzzwjf39/x/EBAwbo9ddf9+jgAABA87IetSbLjowFAK5zO2S9/fbbeu2113T11VfLx8fHcXzw4MHatm2bRwcHAACa19HdBe3/krEAwHVuh6yDBw+qR48etY5brVZVVlZ6ZFAAAMA76t0ni5QFAC5zO2T169dPv/76a63jH3/8sYYOHeqRQQEAAO9wtHA/qrsgtSwAcJ3bIevhhx/W7bffrr///e+yWq369NNPddNNN+nJJ5/Uww8/7NZ9vfLKKxo0aJDCw8MVHh6u5ORkfffdd47ry8rKNGPGDEVHRys0NFRTpkxRZmamu0MGAAAusje+MJuduwtayVgA4DK3Q9aFF16or776Sj/88INCQkL08MMPa+vWrfrqq6901llnuXVfSUlJevrpp7V69WqtWrVK48aN04UXXqjNmzdLku6++2599dVXWrBggZYsWaK0tDRdfPHF7g4ZAAC4yHpUJcvMPlkA4DaX98navXu3unXrJkk6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AAAAAGhtCFkAAAAA4EGELAAAAADwIEIWAAAAAHhQqw9ZTz75pEaOHKng4GBFRkbWeU5qaqomTZqk4OBgxcbG6r777lNVVVWD95uTk6Orr75a4eHhioyM1PTp01VUVNQEn0Hb8vPPP8tkMtX5sXLlynpvN3bs2Frn33rrrc048ralS5cutb6eTz/9dIO3KSsr04wZMxQdHa3Q0FBNmTKl1kbgcM3evXs1ffp0de3aVUFBQerevbseeeQRVVRUNHg7ngfHZ86cOerSpYsCAwM1YsQI/fHHHw2ev2DBAvXp00eBgYEaOHCgvv3222Yaadsze/ZsnXzyyQoLC1NsbKwmT56slJSUBm8zf/78Wj/vgYGBzTTitudvf/tbra9nnz59GrwNzwHPqutvr8lk0owZM+o8n+fA8fvll190/vnnKzExUSaTSZ9//rnT9YZh6OGHH1ZCQoKCgoI0fvx47dix45j36+7fk7q0+pBVUVGhSy+9VLfddlud11ssFk2aNEkVFRX6/fff9dZbb2n+/Pl6+OGHG7zfq6++Wps3b9aiRYv09ddf65dfftHNN9/cFJ9CmzJy5Eilp6c7fdx4443q2rWrhg8f3uBtb7rpJqfbPfPMM8006rbpsccec/p63nHHHQ2ef/fdd+urr77SggULtGTJEqWlpeniiy9uptG2Ldu2bZPVatWrr76qzZs36/nnn9fcuXP14IMPHvO2PA8a57///a9mzpypRx55RGvWrNHgwYM1YcIEZWVl1Xn+77//riuvvFLTp0/X2rVrNXnyZE2ePFmbNm1q5pG3DUuWLNGMGTO0fPlyLVq0SJWVlTr77LNVXFzc4O3Cw8Odft737dvXTCNum/r37+/09fztt9/qPZfngOetXLnS6eu/aNEiSdKll15a7214Dhyf4uJiDR48WHPmzKnz+meeeUYvvvii5s6dqxUrVigkJEQTJkxQWVlZvffp7t+TehltxLx584yIiIhax7/99lvDbDYbGRkZjmOvvPKKER4ebpSXl9d5X1u2bDEkGStXrnQc++677wyTyWQcPHjQ42NvyyoqKoz27dsbjz32WIPnjRkzxrjzzjubZ1AngM6dOxvPP/+8y+fn5eUZfn5+xoIFCxzHtm7dakgyli1b1gQjPPE888wzRteuXRs8h+dB451yyinGjBkzHJctFouRmJhozJ49u87zL7vsMmPSpElOx0aMGGHccsstTTrOE0VWVpYhyViyZEm959T3dxuN88gjjxiDBw92+XyeA03vzjvvNLp3725YrdY6r+c54FmSjM8++8xx2Wq1GvHx8cazzz7rOJaXl2cEBAQYH3zwQb334+7fk/q0+krWsSxbtkwDBw502rx4woQJKigo0ObNm+u9TWRkpFPlZfz48TKbzVqxYkWTj7kt+fLLL3X48GHdcMMNxzz3vffeU0xMjAYMGKBZs2appKSkGUbYdj399NOKjo7W0KFD9eyzzzY4RXb16tWqrKzU+PHjHcf69OmjTp06admyZc0x3DYvPz9fUVFRxzyP54H7KioqtHr1aqefX7PZrPHjx9f787ts2TKn8yXb3wZ+3j0jPz9fko75M19UVKTOnTurY8eOuvDCC+v9uwzX7NixQ4mJierWrZuuvvpqpaam1nsuz4GmVVFRoXfffVfTpk2TyWSq9zyeA01nz549ysjIcPo5j4iI0IgRI+r9OW/M35P6+DZu2K1HRkaGU8CS5LickZFR721iY2Odjvn6+ioqKqre26Bub7zxhiZMmKCkpKQGz7vqqqvUuXNnJSYmasOGDbr//vuVkpKiTz/9tJlG2rb8+c9/1kknnaSoqCj9/vvvmjVrltLT0/XPf/6zzvMzMjLk7+9fa11jXFwcP/MesHPnTr300kv6xz/+0eB5PA8a59ChQ7JYLHX+rt+2bVudt6nvbwM/78fParXqrrvu0qhRozRgwIB6z+vdu7fefPNNDRo0SPn5+frHP/6hkSNHavPmzcf8m4HaRowYofnz56t3795KT0/Xo48+qtNPP12bNm1SWFhYrfN5DjStzz//XHl5ebr++uvrPYfnQNOy/yy783PemL8n9WmRIeuBBx7Q3//+9wbP2bp16zEXdMJzGvM9OXDggL7//nt99NFHx7z/muvdBg4cqISEBJ155pnatWuXunfv3viBtyHufA9mzpzpODZo0CD5+/vrlltu0ezZsxUQENDUQ22zGvM8OHjwoM455xxdeumluummmxq8Lc8DtAUzZszQpk2bGlwPJEnJyclKTk52XB45cqT69u2rV199VY8//nhTD7PNmThxouP/gwYN0ogRI9S5c2d99NFHmj59uhdHdmJ64403NHHiRCUmJtZ7Ds+Btq1Fhqx77rmnweQvSd26dXPpvuLj42t1BLF3TIuP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xQoPD9fHH3/s9Fiff/65QkJCVFhY6Nbn2dAYzzvvPLVv317z5893uk1RUZEWLFig6dOnu/VYAIDWh5AFAGhWjz76qC677DJt2LBB5557rq6++mrl5ORIkvLy8jRu3DgNHTpUq1at0sKFC5WZmanLLrvM6T7eeust+fv7a+nSpZo7d6727NmjSy65RJMnT9b69et1yy236K9//avj/JCQEF1xxRW1qmzz5s3TJZdcorCwMJfHf6wx+vr66rrrrtP8+fNlGIbjdgsWLJDFYtGVV17p9tcMANC6ELIAAB7z9ddfKzQ01Onjqaeecjrn+uuv15VXXqkePXroqaeeUlFRkf744w9J0ssvv6yhQ4fqqaeeUp8+fTR06FC9+eab+umnn7R9+3bHffTs2VPPPPOMevfurd69e+vVV19V79699eyzz6p379664oordP311zs97o033qjvv/9e6enpkqSsrCx9++23mjZtmlufoytjnDZtmnbt2qUlS5Y4bjdv3jxNmTJFERERbj0eAKD1YU0WAMBjzjjjDL3yyitOx6Kiopwu29cjSbYKU3h4uLKysiRJ69ev108//VTnOqVdu3apV69ekqRhw4Y5XZeSkqKTTz7Z6dgpp5xS63L//v311ltv6YEHHtC7776rzp07a/To0W59jq6MsU+fPho5cqTefPNNjR07Vjt37tSvv/6qxx57zK3HAgC0ToQsAIDHhISEqEePHg2e4+fn53TZZDLJarVKsq1bOv/88/X3v/+91u0SEhKcHqcxbrzxRs2ZM0cPPPCA5s2bpxtuuEEmk8mt+3B1jNOnT9cdd9yhOXPmaN68eerevbvGjBnTqHEDAFoXpgsCAFqMk046SZs3b1aXLl3Uo0cPp4+GglXv3r21atUqp2MrV66sdd4111yjffv26cUXX9SWLVs0derUJhvjZZddJrPZrPfff19vv/22pk2b5nagAwC0ToQsAIDHlJeXKyMjw+mjZmfAY5kxY4ZycnJ05ZVXauXKldq1a5e+//573XDDDbJYLPXe7pZbbtG2bdt0//33a/v27froo48c3f1qBpt27drp4osv1n333aezzz67Vot1T44xNDRUl19+uWbNmqX09PRaa8QAAG0XIQsA4DELFy5UQkKC08dpp53m8u0TExO1dOlSWSwWnX322Ro4cKDuuusuRUZGymyu/09W165d9fHHH+vTTz/VoEGD9Morrzi6Cx69T9f06dNVUVHhdsOLxoxx+vTpys3N1YQJE5SYmNioxwMAtD4mo2Z/WQAA2ognn3xSc+fO1f79+52Ov/POO7r77ruVlpZ2zE2Mx44dqyFDhuiFF15osnH+7W9/0+eff65169Y12WMAAJoXlSwAQJvw73//WytXrtTu3bv1zjvv6Nlnn3Vac1VSUqJdu3bp6aef1i233HLMgFXzfkNDQ7Vx40aPjjc1NbXOFvcAgNaPShYAoE24++679d///lc5OTnq1KmTrr32Ws2aNUu+vrZGun/729/05JNPavTo0friiy/qbMF+tIMHD6q0tFSS1KlTJ5eDmSuqqqq0d+9eSbYpjR07dvTYfQMAvIuQBQAAAAAexHRBAAAAAPAgQhYAAAAAeBAhCwAAAAA8iJAFAAAAAB5EyAIAAAAADyJkAQAAAIAHEbIAAAAAwIMIWQAAAADgQf8PhonWDEonoyUAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 1000x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "example_material = db['eNT873N0Cde18DQ6Ni9D5MKpx_7C']\n",
    "\n",
    "plt.figure(figsize=(10,5))\n",
    "plt.plot(get_dos_energies(example_material), get_dos_values(example_material))\n",
    "plt.xlim(-10,10)\n",
    "plt.ylim(0,60)\n",
    "plt.xlabel('Energy [eV]')\n",
    "plt.ylabel('DOS [states/eV/unit cell]')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "351cdcaf-7d55-47f8-ab81-06790d61701c",
   "metadata": {},
   "source": [
    "With this we can update the database. Please note that we write the DOS energies and values to the `data` attribute. This is due to technical reasons, which currently allow only to write scalar quantities or strings to the `properties` attribute, which may be resolved in the future."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "7656229a-baa2-48cb-95e3-69820cc5fef5",
   "metadata": {},
   "outputs": [],
   "source": [
    "db.update_derived_properties(['dos_values', 'dos_energies'], [get_dos_values, get_dos_energies], target='data')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77a2235a-2c53-4b1a-a8d2-91d69d079f6b",
   "metadata": {},
   "source": [
    "Now that we have the electronic DOS available, we can use it to compute spectral fingerprints."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "93b4b868-d92a-4859-b9d4-f97353a0ff0f",
   "metadata": {},
   "source": [
    "### Defining and tuning DOS fingerprints"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d1830af-83bb-4919-977f-07c3756f35a2",
   "metadata": {},
   "source": [
    "Spectral fingerprints [2] of the electronic DOS are an effective way of describing the electronic structure of materials. They are computed by integrating the DOS over non-uniform energy intervals, that are small close to a chosen reference energy, and get larger as the energy difference to the reference energy increases. This allows to tailor the fingerprint towards a specific energy region of interest. Then, a grid is laid on top of this histogram of states to discretize it. The final fingerprint consists of a vector that represents the colums of the grid, where each grid cell is represented by a 1 if the cell is completely filled by the histogram, or 0 otherwise.  \n",
    "\n",
    "These fingerprints have some parameters that require to be set for each dataset that they are applied to. We will do this in the following.\n",
    "\n",
    "First, we import the `DOSFingerprint` class from MADAS:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "fb84ad29-46b9-43c3-ae8d-89f6fd35a97e",
   "metadata": {},
   "outputs": [],
   "source": [
    "from madas.fingerprints import DOSFingerprint"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79275047-3db9-43f7-a09d-e4a7d8081c1d",
   "metadata": {},
   "source": [
    "To find the right grid parameters for the fingerprint, we start with the default grid:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "5baac297-1157-436f-b73c-e1998cd84c6f",
   "metadata": {},
   "outputs": [],
   "source": [
    "grid = DOSFingerprint.get_default_grid()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a0775a26-62e2-4e6e-a1cc-c698193977d9",
   "metadata": {},
   "source": [
    "We can inspect what the default settings of the grid are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "9cf72689-afef-4b00-bfda-ccb0150544bc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'grid_type': 'nonuniform',\n",
       " 'e_ref': -2.0,\n",
       " 'delta_e_min': 0.05,\n",
       " 'delta_e_max': 1.05,\n",
       " 'delta_rho_min': 0.5,\n",
       " 'delta_rho_max': 5.5,\n",
       " 'width': 7.0,\n",
       " 'cutoff': [-8.0, 7.0],\n",
       " 'n_pix': 56}"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "grid.resolve_grid_id(grid.grid_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a9081f80-0459-45b6-9915-a3de086e026c",
   "metadata": {},
   "source": [
    "and plot it for an example entry:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "dad2893f-32d2-43c8-9cd2-f8136d1bbf4f",
   "metadata": {},
   "outputs": [],
   "source": [
    "test_fp = DOSFingerprint(grid=grid).calculate(get_dos_energies(example_material), get_dos_values(example_material))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "aa9330f8-fc5c-47f7-9368-343d93e5021f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "test_fp.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2a6bc53-c236-4d37-ae38-af1f37b07a70",
   "metadata": {},
   "source": [
    "We can see that the grid is well filled, but it looks like the fingerprint would reach the top of the grid in some cases. We can increase the minimal and maximal height of the grid:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "c7ea5785-1fcf-45f9-96d5-6df434442d1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "grid.n_pix = 2048\n",
    "grid.delta_rho_min = 5\n",
    "grid.delta_rho_max = 50"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "83a4378c-d141-47aa-8c11-4dcc79e242fd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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xz0QjznCcQ+k4+4vx5xlWbz88ssxevTo425b8PgYOXJkDB48OJqbO7/6vbm5OWpqao7avry8PMrLyzstO/30009ohsrKyj79D9hbA/G4B+IxRwzM4x6IxxzhuAeS/nDMVVVVPdpuUKEfeMiQITFhwoRYu3ZtbllHR0esXbs2Jk+eXOiHAwD6mKI87dLQ0BBz586Niy66KCZOnBhLliyJtra23G+/AAADV1Hi45/+6Z/i+eefj9tvvz2amprine98Z6xatSpGjSru79GXl5fHokWLjnoap78biMc9EI85YmAe90A85gjHPZCOeyAec1mW9eR3YgAACqPgr/kAAOiO+AAAkhIfAEBS4gMASKrfxMdXv/rVeO973xunnnpql29Stnv37pg5c2aceuqpUV1dHZ/73Ofi9ddfTztokf3hD3+ID3/4wzFy5MiorKyMSy+9NJ588slSj5XEY489FpMmTYphw4bFGWecEbNnzy71SEm0t7fHO9/5zigrK4tnn3221OMU1a5du+Laa6+NsWPHxrBhw2LcuHGxaNGiOHDgQKlHK6ilS5fGm9/85hg6dGhMmjQpfvGLX5R6pKJqbGyMiy++OCoqKqK6ujpmz54d27ZtK/VYSX3ta1+LsrKyWLBgQalHSaLfxMeBAwfiqquuihtuuOGY6w8dOhQzZ86MAwcOxNNPPx333XdfLF++PG6//fbEkxbXhz70oXj99dfjiSeeiE2bNsX48ePjQx/6UDQ1NZV6tKL60Y9+FFdffXVcc8018Zvf/CZ+9rOfxcc//vFSj5XELbfc0qO3M+4Pfv/730dHR0fce++9sXXr1vjmN78Z99xzT3z+858v9WgF88ADD0RDQ0MsWrQonnnmmRg/fnxMnz499u/fX+rRimbdunVRX18fGzdujNWrV8fBgwdj2rRp0dbWVurRkvjlL38Z9957b9TV9ZW/I1wAhflzciePZcuWZVVVVUctf/zxx7NBgwZlTU1NuWV33313VllZmbW3tyecsHief/75LCKy9evX55a1trZmEZGtXr26hJMV18GDB7O///u/z77zne+UepTkHn/88ez888/Ptm7dmkVE9utf/7rUIyV3xx13ZGPHji31GAUzceLErL6+Pnf70KFD2ejRo7PGxsYSTpXW/v37s4jI1q1bV+pRiu7ll1/O3vrWt2arV6/O3v/+92ef+cxnSj1SEv3mzMfxbNiwId7xjnd0eqOz6dOnR2tra2zdurWEkxXOiBEj4rzzzovvf//70dbWFq+//nrce++9UV1dHRMmTCj1eEXzzDPPxN69e2PQoEHxrne9K84666yYMWNGbNmypdSjFVVzc3Ncd9118YMf/CBOPfXUUo9TMi0tLTF8+PBSj1EQBw4ciE2bNsXUqVNzywYNGhRTp06NDRs2lHCytFpaWiIi+s2/a3fq6+tj5syZnf7NB4IBEx9NTU1HvcPq4dv95SmJsrKyWLNmTfz617+OioqKGDp0aHzjG9+IVatWxRlnnFHq8YrmT3/6U0REfPGLX4zbbrstVq5cGWeccUZMmTIlXnzxxRJPVxxZlsW8efPi+uuvj4suuqjU45TM9u3b46677opPf/rTpR6lIP7yl7/EoUOHjvm9qr98nzqejo6OWLBgQVxyySVx4YUXlnqcorr//vvjmWeeicbGxlKPktxJHR+33nprlJWVdXv5/e9/X+oxi66nH4csy6K+vj6qq6vjf//3f+MXv/hFzJ49O6688sp47rnnSn0YeevpcXd0dERExL/+67/GnDlzYsKECbFs2bIoKyuLBx98sMRHkZ+eHvNdd90VL7/8cixcuLDUIxdEb77W9+7dG1dccUVcddVVcd1115Vocgqtvr4+tmzZEvfff3+pRymqPXv2xGc+85n44Q9/GEOHDi31OMkV5W+7FMrNN98c8+bN63abc889t0f7qqmpOeoV483Nzbl1J7OefhyeeOKJWLlyZfz1r3/N/Vnmb3/727F69eq477774tZbb00wbeH09LgPh9Xb3/723PLy8vI499xzY/fu3cUcseDy+bfesGHDUX8L4qKLLopPfOITcd999xVxysLL92t93759cfnll8d73/ve+Pd///ciT5fOyJEjY/DgwbnvTYc1Nzef9N+nCmH+/PmxcuXKWL9+fZx99tmlHqeoNm3aFPv37493v/vduWWHDh2K9evXx7/9279Fe3t7DB48uIQTFtdJHR9nnnlmnHnmmQXZ1+TJk+OrX/1q7N+/P6qrqyMiYvXq1VFZWdnph9bJqKcfh1dffTUi/vYc8ZEGDRqUOzvQl/T0uCdMmBDl5eWxbdu2uPTSSyMi4uDBg7Fr164455xzij1mQfX0mL/1rW/FV77yldztffv2xfTp0+OBBx6ISZMmFXPEosjna33v3r1x+eWX585wvfHzvS8bMmRITJgwIdauXZv7VfGOjo5Yu3ZtzJ8/v7TDFVGWZXHjjTfGQw89FE899VSMHTu21CMV3Qc+8IH47W9/22nZNddcE+eff378y7/8S78Oj4iTPD7ysXv37njxxRdj9+7dcejQodz7HbzlLW+J0047LaZNmxZvf/vb4+qrr4477rgjmpqa4rbbbov6+vp+85cEJ0+eHGeccUbMnTs3br/99hg2bFj8x3/8R+zcuTNmzpxZ6vGKprKyMq6//vpYtGhR1NbWxjnnnBN33nlnRERcddVVJZ6uOMaMGdPp9mmnnRYREePGjevX/2Pcu3dvTJkyJc4555z4+te/Hs8//3xuXX85M9DQ0BBz586Niy66KCZOnBhLliyJtra2uOaaa0o9WtHU19fHihUr4pFHHomKiorc61uqqqpi2LBhJZ6uOCoqKo56Tcub3vSmGDFiRL9/rUtE9J9ftZ07d24WEUddnnzyydw2u3btymbMmJENGzYsGzlyZHbzzTdnBw8eLN3QRfDLX/4ymzZtWjZ8+PCsoqIie8973pM9/vjjpR6r6A4cOJDdfPPNWXV1dVZRUZFNnTo127JlS6nHSmbnzp0D4ldtly1bdsyv8370rSzLsiy76667sjFjxmRDhgzJJk6cmG3cuLHUIxVVV/+my5YtK/VoSQ2kX7Uty7IsSx08AMDA1X+eLAUA+gTxAQAkJT4AgKTEBwCQlPgAAJISHwBAUuIDAEhKfAAASYkPACAp8QEAJCU+AICkxAcAkNT/AVELohd1MqS8AAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "test_fp = DOSFingerprint(grid=grid).calculate(get_dos_energies(example_material), get_dos_values(example_material))\n",
    "test_fp.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba211f6e-91f1-40b0-bfec-6bc5e135df29",
   "metadata": {},
   "source": [
    "We can see that after our modification, the grid has a lot of space left to account for DOS with many states. With these settings we can compute the fingerprints for all materials. This can be done by iterating over the database:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "46eb8539-35fe-4fd5-9781-4666946838db",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "11e09ce6607f4f889f8493c6d8808ee4",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "  0%|          | 0/191 [00:00<?, ?it/s]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from madas.utils import tqdm\n",
    "\n",
    "fps = []\n",
    "for entry in tqdm(db):\n",
    "    fp = DOSFingerprint(grid=grid).calculate(entry.data['dos_energies'], entry.data['dos_values'])\n",
    "    fp.set_mid(entry.mid)\n",
    "    fps.append(fp)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c76c68a3-a7a3-4d15-92c7-c42b75d2419e",
   "metadata": {},
   "source": [
    "Because the selection of grid parameters can be challenging for datasets with diverse DOSs, it is useful to check some metrics of the fingerprints. Two examples are the filling factor, which describes how many grid cells are filled:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "fe438a41-e3ba-4561-a7e9-58bae4dc6a99",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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8zdxww03xJ//+Z9HRMT3v//9WLNmTfzwhz+MhQsXdhmbz+cjn88XLre3t0dEREdHR4qpHVVn/p3jentA7xX7+JDqv+9i5lGOjzEp13mgrN3x/remFAbKuTTY126g3L+BOucPbivLso8enJVYPp/Phg8fnj322GNd9n/1q1/Nrrjiim7jFy9enEWEzWaz2Ww2m63Mtj179nxkG5b8mc1f//rX8f7770dtbW2X/bW1tfH66693G79o0aJYsGBB4XJnZ2f85je/iZNPPjkqKipKPb2Cjo6OaGhoiD179sTIkSOT3U45sSbdWZPurEl31qQ7a9KdNenOmnRXLmuSZVkcOHAg6uvrP3JskpfRi5HL5SKXy3XZN2rUqON2+yNHjhzQf5n9wZp0Z026sybdWZPurEl31qQ7a9JdOaxJTU3NMY0r+RuExowZE8OHD4+2trYu+9va2qKurq7UNwcAwABW8tisqqqK6dOnx7p16wr7Ojs7Y926ddHU1FTqmwMAYABL8jL6ggULYu7cuXH++efHBRdcEMuWLYtDhw4V3p0+EORyuVi8eHG3l/CHMmvSnTXpzpp0Z026sybdWZPurEl3g3FNKrLsWN6zXry///u/j3vuuSdaW1vjvPPOi+9973vR2NiY4qYAABigksUmAAD4bnQAAJIRmwAAJCM2AQBIRmwCAJDMoInN5cuXx8SJE2PEiBHR2NgYL7zwwoeOf+SRR2Lq1KkxYsSIOOecc+JnP/tZl+uzLIs777wzxo0bFyeeeGLMnDkztm/fnvIulFyp12TevHlRUVHRZZs9e3bKu1ByxazJa6+9FnPmzImJEydGRUVFLFu2rM/HHIhKvSbf+c53up0nU6dOTXgPSq+YNXnggQfiwgsvjJNOOilOOumkmDlzZrfxQ+3x5FjWZKg9njz66KNx/vnnx6hRo+JjH/tYnHfeefGP//iPXcYMtfPkWNZkMJwnEb3/d2L16tVRUVERV111VZf9ZXeufOS3p5eB1atXZ1VVVdkPf/jD7LXXXstuuOGGbNSoUVlbW1uP45977rls+PDh2d13351t3bo1u+OOO7ITTjghe+WVVwpjli5dmtXU1GSPP/549l//9V/ZFVdckU2aNCn7n//5n+N1t/okxZrMnTs3mz17drZ3797C9pvf/OZ43aU+K3ZNXnjhhez222/PHnrooayuri677777+nzMgSbFmixevDg766yzupwn//3f/534npROsWvypS99KVu+fHn20ksvZb/61a+yefPmZTU1Ndmbb75ZGDPUHk+OZU2G2uPJL3/5y+zRRx/Ntm7dmu3YsSNbtmxZNnz48Gzt2rWFMUPtPDmWNSn38yTLev/vxK5du7JTTz01u/DCC7Mrr7yyy3Xldq4Miti84IILsvnz5xcuv//++1l9fX3W0tLS4/g/+7M/yy677LIu+xobG7O/+Iu/yLIsyzo7O7O6urrsnnvuKVy/f//+LJfLZQ899FCCe1B6pV6TLPu//+iPPOHLSbFr8rsmTJjQY1j15ZgDQYo1Wbx4cXbuueeWcJbHV1//Tn/7299m1dXV2Y9+9KMsy4bm48mRjlyTLBvajycf+IM/+IPsjjvuyLLMefKB312TLCv/8yTLercuv/3tb7M/+qM/yv7hH/6h2xqU47lS9i+jv/fee7F58+aYOXNmYd+wYcNi5syZsXHjxh5/ZuPGjV3GR0TMmjWrMH7Xrl3R2traZUxNTU00NjYe9ZgDSYo1+cD69etj7NixMWXKlLjxxhtj3759pb8DCfRmTfrjmMdTyvlv37496uvrY/LkyfHlL3853njjjb5O97goxZq88847cfjw4Rg9enREDM3HkyMduSYfGKqPJ1mWxbp162Lbtm1x0UUXRYTzpKc1+UC5nicRvV+Xu+66K8aOHRvXX399t+vK8VxJ8nWVx9Ovf/3reP/996O2trbL/tra2nj99dd7/JnW1tYex7e2thau/2Df0cYMZCnWJCJi9uzZcfXVV8ekSZNi586d8a1vfSuam5tj48aNMXz48NLfkRLqzZr0xzGPp1Tzb2xsjJUrV8aUKVNi7969sWTJkrjwwgvj1Vdfjerq6r5OO6lSrMk3v/nNqK+vL/xDMBQfT4505JpEDM3Hk/b29jj11FMjn8/H8OHD4/77748vfOELETF0z5MPW5OI8j5PInq3Ls8++2z84Ac/iC1btvR4fTmeK2Ufmxw/1113XeHP55xzTkybNi1OP/30WL9+fVxyySX9ODMGkubm5sKfp02bFo2NjTFhwoR4+OGHe/x/6YPJ0qVLY/Xq1bF+/foYMWJEf09nQDjamgzFx5Pq6urYsmVLHDx4MNatWxcLFiyIyZMnx4wZM/p7av3mo9ZkqJ0nBw4ciK985SvxwAMPxJgxY/p7OiVT9i+jjxkzJoYPHx5tbW1d9re1tUVdXV2PP1NXV/eh4z/432KOOZCkWJOeTJ48OcaMGRM7duzo+6QT682a9Mcxj6fjNf9Ro0bFmWeeOejPk3vvvTeWLl0aP//5z2PatGmF/UPx8eQDR1uTngyFx5Nhw4bFGWecEeedd17cdtttcc0110RLS0tEDN3z5MPWpCfldJ5EFL8uO3fujN27d8fll18elZWVUVlZGT/+8Y/jX//1X6OysjJ27txZludK2cdmVVVVTJ8+PdatW1fY19nZGevWrYumpqYef6apqanL+IiIp556qjB+0qRJUVdX12VMR0dHPP/880c95kCSYk168uabb8a+ffti3LhxpZl4Qr1Zk/445vF0vOZ/8ODB2Llz56A+T+6+++747ne/G2vXro3zzz+/y3VD8fEk4sPXpCdD8fGks7Mz8vl8RAzd8+RIv7smPSmn8ySi+HWZOnVqvPLKK7Fly5bCdsUVV8TFF18cW7ZsiYaGhvI8V/r7HUqlsHr16iyXy2UrV67Mtm7dmn3ta1/LRo0albW2tmZZlmVf+cpXsoULFxbGP/fcc1llZWV27733Zr/61a+yxYsX9/jRR6NGjcqeeOKJ7OWXX86uvPLKAf2xAkcq9ZocOHAgu/3227ONGzdmu3btyp5++unsD//wD7NPfOIT2bvvvtsv97FYxa5JPp/PXnrppeyll17Kxo0bl91+++3ZSy+9lG3fvv2YjznQpViT2267LVu/fn22a9eu7LnnnstmzpyZjRkzJnv77beP+/3rjWLXZOnSpVlVVVX2L//yL10+nuXAgQNdxgylx5OPWpOh+Hjy13/919nPf/7zbOfOndnWrVuze++9N6usrMweeOCBwpihdp581JoMhvMky4pflyP19I78cjtXBkVsZlmW/d3f/V02fvz4rKqqKrvggguyTZs2Fa773Oc+l82dO7fL+Icffjg788wzs6qqquyss87K1qxZ0+X6zs7O7Nvf/nZWW1ub5XK57JJLLsm2bdt2PO5KyZRyTd55553s0ksvzU455ZTshBNOyCZMmJDdcMMNZRNVHyhmTXbt2pVFRLftc5/73DEfsxyUek2uvfbabNy4cVlVVVV26qmnZtdee222Y8eO43iP+q6YNZkwYUKPa7J48eLCmKH2ePJRazIUH0/+8i//MjvjjDOyESNGZCeddFLW1NSUrV69usvxhtp58lFrMljOkywr/t/j39VTbJbbuVKRZVl2fJ9LBQBgqCj739kEAGDgEpsAACQjNgEASEZsAgCQjNgEACAZsQkAQDJiEwCAZMQmAADJiE0AAJIRmwAAJCM2AQBI5n8BxtouzGrKej8AAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 800x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.figure(figsize=(8,5))\n",
    "plt.hist([fp.filling_factor for fp in fps], bins=50)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c431d1c-bd48-4788-b87d-fb888be5f133",
   "metadata": {},
   "source": [
    "We can see that the filling factors are all well below 0.5, so it seems like the grid is able to cover the DOSs well.   \n",
    "Note that for the computation of similarity scores, the empty grid cells are not considered. Therefore it is always better to have more padding.\n",
    "\n",
    "The other metric is overflow, which describes how many states can not be described because they lie outside of the grid."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "e7136c9d-1298-4b31-8330-6e9897675f5e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAArAAAAGsCAYAAAAluJTLAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjcsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvTLEjVAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAKINJREFUeJzt3X9w1PWdx/HXhiUbBHZj4mSXlURSh2tQKSJgjDA9lUzDj0OQXD2clOYsA2cbREgHIVdD61UNUKsURFIdD3QOasudoMCIRwOGMg0hJFKr0IDXCKl0k+nR7JrQhMh+748bd1yJwOJ32XyS52PmO2O+3+9+896PCE+/883isCzLEgAAAGCIpEQPAAAAAMSCgAUAAIBRCFgAAAAYhYAFAACAUQhYAAAAGIWABQAAgFEIWAAAABjFmegBrkQ4HNbp06c1dOhQORyORI8DAACAz7EsSx9//LH8fr+Skuy9Z2pkwJ4+fVqZmZmJHgMAAACX0NzcrOHDh9t6TSMDdujQoZL+f0HcbneCpwEAAMDnhUIhZWZmRrrNTkYG7KePDbjdbgIWAACgF4vH4578EBcAAACMQsACAADAKAQsAAAAjELAAgAAwCgELAAAAIxCwAIAAMAoBCwAAACMQsACAADAKAQsAAAAjELAAgAAwCgELAAAAIxCwAIAAMAoBCwAAACMQsACAADAKAQsAAAAjELAAgAAwCjORA9gihHLd8V0/ocrp8dpEgAAgP6NO7AAAAAwCgELAAAAoxCwAAAAMAoBCwAAAKMQsAAAADAKAQsAAACjELAAAAAwCgELAAAAoxCwAAAAMAoBCwAAAKMQsAAAADAKAQsAAACjELAAAAAwCgELAAAAoxCwAAAAMAoBCwAAAKMQsAAAADAKAQsAAACjxByw+/fv14wZM+T3++VwOLR9+/YLzjl27JjuvfdeeTweDR48WBMmTNCpU6cixzs7O1VSUqL09HQNGTJEhYWFamlp+VJvBAAAAP1DzAHb0dGhMWPGaP369T0e/5//+R9NmjRJOTk5evvtt/Xuu++qvLxcKSkpkXOWLFmiHTt2aOvWraqurtbp06c1e/bsK38XAAAA6Decsb5g6tSpmjp16hce/8EPfqBp06Zp9erVkX033nhj5J+DwaBeeuklbdmyRffcc48kaePGjRo1apQOHjyoO+64I9aRAAAA0I/Y+gxsOBzWrl279Hd/93cqKChQRkaGcnNzox4zqK+vV3d3t/Lz8yP7cnJylJWVpZqamh6v29XVpVAoFLUBAACgf7I1YFtbW9Xe3q6VK1dqypQp+u///m/dd999mj17tqqrqyVJgUBAycnJSk1NjXqt1+tVIBDo8boVFRXyeDyRLTMz086xAQAAYBDb78BK0syZM7VkyRLdeuutWr58uf7hH/5BlZWVV3zdsrIyBYPByNbc3GzXyAAAADBMzM/AXsx1110np9Opm266KWr/qFGjdODAAUmSz+fTuXPn1NbWFnUXtqWlRT6fr8frulwuuVwuO0cFAACAoWy9A5ucnKwJEyaosbExav/x48d1ww03SJLGjRungQMHqqqqKnK8sbFRp06dUl5enp3jAAAAoA+K+Q5se3u7Pvjgg8jXTU1NOnLkiNLS0pSVlaWlS5fqn/7pn/T1r39dd999t3bv3q0dO3bo7bffliR5PB7NmzdPpaWlSktLk9vt1sMPP6y8vDw+gQAAAACXFHPAHj58WHfffXfk69LSUklScXGxNm3apPvuu0+VlZWqqKjQokWL9NWvflX/9V//pUmTJkVe8+yzzyopKUmFhYXq6upSQUGBnn/+eRveDgAAAPo6h2VZVqKHiFUoFJLH41EwGJTb7b4q33PE8l0xnf/hyulxmgQAAKD3i2ev2foMLAAAABBvBCwAAACMQsACAADAKAQsAAAAjELAAgAAwCgELAAAAIxCwAIAAMAoBCwAAACMQsACAADAKAQsAAAAjELAAgAAwCgELAAAAIxCwAIAAMAoBCwAAACMQsACAADAKAQsAAAAjELAAgAAwCgELAAAAIxCwAIAAMAoBCwAAACMQsACAADAKAQsAAAAjELAAgAAwCgELAAAAIxCwAIAAMAoBCwAAACMQsACAADAKAQsAAAAjELAAgAAwCgELAAAAIxCwAIAAMAoBCwAAACMEnPA7t+/XzNmzJDf75fD4dD27du/8NyHHnpIDodDa9asidp/5swZFRUVye12KzU1VfPmzVN7e3usowAAAKAfijlgOzo6NGbMGK1fv/6i523btk0HDx6U3++/4FhRUZHef/997dmzRzt37tT+/fu1YMGCWEcBAABAP+SM9QVTp07V1KlTL3rORx99pIcfflhvvfWWpk+fHnXs2LFj2r17t+rq6jR+/HhJ0rp16zRt2jQ9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",
      "text/plain": [
       "<Figure size 800x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.figure(figsize=(8,5))\n",
    "plt.hist([fp.overflow for fp in fps], bins=50)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7dec1aec-4b04-4ec9-a3c2-d7f2f4b7dea2",
   "metadata": {},
   "source": [
    "We can see that the vast majority of fingerprints have very low overfow, only some outliers have large values."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f4df33b-4afe-4608-886e-653c1eb93a35",
   "metadata": {},
   "source": [
    "We can use these fingerprints now to compute the similarities between materials. For the DOS fingerprints, we use the Tanimoto coefficient [3] as a similarity metric. It describes the similarity between two fingerprints as the overlap between them, divided by the total area covered by combining both fingerprints. The `DOSFingerprint` has this already implemented, we only need to call the `get_similarities` function to obtain the similarity scores for a list of fingerprints. \n",
    "\n",
    "The following plot shows the similarity of the first entry of the database to all other entries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "0167659d-3420-4d58-962a-947c2be87fa3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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OhUzZszA9u3b8eabb2LZsmV47LHHglxyIiIiIhKBqcHs3LlzMW7cOIwdOxY9e/bEggUL0KpVKyxatMjt9t988w0GDBiAO+64A926dcMNN9yArKwsn9lcIiIiIrIm04LZuro6bNq0CRkZGb8VJiwMGRkZKCoqcvua3//+99i0aZMzeP3pp5/w2Wef4Q9/+IPHz6mtrUV1dbXLPyIiIiKyhuZmffCRI0dQX1+PuLg4l8fj4uKwY8cOt6+54447cOTIEQwcOBCKouDs2bMYP36812EGubm5mDlzpq5lJyIiIiIxmD4BTIvCwkLMmjULr776KjZv3owVK1bg008/xTPPPOPxNdOmTUNVVZXz34EDB4JYYiIiIiIykmmZ2djYWDRr1gyVlZUuj1dWViI+Pt7ta5588kncfffduO+++wAAvXr1Qk1NDe6//348/vjjCAtrGptHREQgIiJC/y9ARERERKYzLTMbHh6Ovn37Ij8/3/mY3W5Hfn4+0tPT3b7m1KlTTQLWZs2aAQAURTGusEREREQkJNMyswCQk5OD7OxsXH755ejXrx/mzZuHmpoajB07FgAwevRodO7cGbm5uQCAIUOGYO7cubjsssuQlpaGPXv24Mknn8SQIUOcQS0RERERhQ5Tg9lRo0bh559/xvTp01FRUYHU1FTk5eU5J4Xt37/fJRP7xBNPwGaz4YknnsDBgwfRoUMHDBkyBH/729/M+gpEREREZCKbEmL989XV1YiOjkZVVRWioqLMLg4RERERNaIlXpNqNQMiIiIiooYYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERERkbQYzBIRERGRtBjMEhEREZG0GMwSERER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SEtLw3PPPYfw8HD84x//wAUXXGBEGYmIiIiI3NIczD7xxBOoqakBADz99NO4+eabceWVV6J9+/ZYtmyZ7gUkIiIiIvJE8x3A3Dl27BjatWvnXNFAZLwDGBEREZHYDL0DmDsxMTF6vA0RERERkSaqgtmRI0eqfsMVK1b4XRgiIiIiIi1UBbPR0dFGl4OIiIiISDNVwezixYuNLgcRERERkWaa15klIiIiIhKFqsxsnz59kJ+fj3bt2uGyyy7zumrB5s2bdSscEREREZE3qoLZYcOGISIiAgAwfPhwI8tDRERERKSaLuvMyoTrzBIRERGJLWjrzJ48eRJ2u93lMQaIRERERBQsmieAlZWV4aabbkLr1q0RHR2Ndu3aoV27dmjbti3atWtnRBmJiIiIiNzSnJm96667oCgKFi1ahLi4OCluYUtERERE1qQ5mN2yZQs2bdqESy65xIjyEBERERGppnmYwRVXXIEDBw4YURYiIiIiIk00Z2bfeOMNjB8/HgcPHkRycjJatGjh8nzv3r11KxwRERERkTeag9mff/4ZpaWlGDt2rPMxm80GRVFgs9lQX1+vawGJiIiIiDzRHMzec889uOyyy7B06VJOACMiIiIiU2kOZvft24ePPvoIF110kRHlISIiIiJSTfMEsEGDBmHLli1GlIWIiIiISBPNmdkhQ4Zg8uTJ2Lp1K3r16tVkAtjQoUN1KxwRERERkTc2RVEULS8IC/OczJVhApiWe/0SERERUfBpidc0Z2btdrvfBSMiIiIi0pPmMbNERERERKJQlZl96aWXcP/99yMyMhIvvfSS120ffvhhXQpGREREROSLqjGzSUlJ+P7779G+fXskJSV5fjObDT/99JOuBdQbx8wSERERiU33MbNlZWVu/09EREREZKaAx8zW19ejuLgYv/zyix7lISIiIiJSTXMw+8gjj+DNN98EcC6Qveqqq9CnTx8kJiaisLBQ7/IREREREXmkOZhdvnw5UlJSAAAff/wx9u7dix07dmDy5Ml4/PHHdS8gEREREZEnmoPZI0eOID4+HgDw2Wef4dZbb8XFF1+Me+65B1u3btW9gEREREREnmgOZuPi4rBt2zbU19cjLy8P119/PQDg1KlTaNasme4FJCIiIiLyRPMdwMaOHYvbbrsNCQkJsNlsyMjIAAB8++236NGjh+4FJCIiIiLyRHMw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ycylKAomTpyIlStXoqCgAElJST5fU1xcDABISEgwuHTiOnnyJEpLS5GQkIC+ffuiRYsWLsfWzp07sX///pA9thYvXoyOHTvipptu8rodjyUgKSkJ8fHxLsdPdXU1vv32W+fxk56ejuPHj2PTpk3ObQoKCmC3250NglDhCGR3796NtWvXon379j5fU1xcjLCwsCbd6qHkv//9L44ePeo813hMuXrzzTfRt29fpKSk+NyWx5MKZs9As7L3339fiYiIUJYsWaJs27ZNuf/++5W2bdsqFRUVZhfNNA888IASHR2tFBYWKuXl5c5/p06dUhRFUfbs2aM8/fTTyvfff6+UlZUpq1evVi644ALlqquuMrnkwfWnP/1JKSwsVMrKypSvv/5aycjIUGJjY5XDhw8riqIo48ePV7p06aIUFBQo33//vZKenq6kp6ebXGpz1NfXK126dFGmTJni8ngoH0snTpxQfvjhB+WHH35QAChz585VfvjhB+cM/GeffVZp27atsnr1auU///mPMmzYMCUpKUn59ddfne8xePBg5bLLLlO+/fZbZf369Ur37t2VrKwss76SYbztq7q6OmXo0KHK+eefrxQXF7vUWbW1tYqiKMo333yjvPDCC0pxcbFSWlqqvPPOO0qHDh2U0aNHm/zN9OVtP504cUJ59NFHlaKiIqWsrExZu3at0qdPH6V79+7K6dOnne8RCseUr3NPURSlqqpKadWqlfLaa681eX2oHE96YzBrsJdfflnp0qWLEh4ervTr10/ZsGGD2UUyFQC3/xYvXqwoiqLs379fueqqq5SYmBglIiJCueiii5Q///nPSlVVlbkFD7JRo0YpCQkJSnh4uNK5c2dl1KhRyp49e5zP//rrr8qDDz6otGvXTmnVqpUyYsQIpby83MQSm+eLL75QACg7d+50eTyUj6V169a5Pc+ys7MVRTm3PNeTTz6pxMXFKREREcp1113XZP8dPXpUycrKUs477zwlKipKGTt2rHLixAkTvo2xvO2rsrIyj3XWunXrFEVRlE2bNilpaWlKdHS0EhkZqVx66aXKrFmzXII4K/C2n06dOqXccMMNSocOHZQWLVooXbt2VcaNG9ckcRMKx5Svc09RFOX1119XWrZsqRw/frzJ60PleNKbTVEUxdDULxERERGRQThmloiIiIikxWCWiIiIiKTFYJaIiIiIpMVgloiIiIikxWCWiIiIiKTFYJaIiIiIpMVgloiIiIikxWCWiEhwhYWFsNlsOH78uNlFISISDoNZIiIvxowZA5vNBpvNhhYtWiAuLg7XX389Fi1aBLvdrum9lixZgrZt2xpTUBOMGTMGw4cPd/lbr31FRKQWg1kiIh8GDx6M8vJy7N27F59//jmuvfZaTJo0CTfffDPOnj1rdvGEwn1FRMHGYJaIyIeIiAjEx8ejc+fO6NOnDx577DGsXr0an3/+OZYsWeLcbu7cuejVqxdat26NxMREPPjggzh58iSAc0MFxo4di6qqKmf28qmnngIA/POf/8Tll1+ONm3aID4+HnfccQcOHz7cpBxff/01evfujcjISPTv3x8lJSXO544ePYqsrCx07twZrVq1Qq9evbB06VKX1y9fvhy9evVCy5Yt0b59e2RkZKCmpsb5/BtvvIFLL70UkZGR6NGjB1599VXD9hURkV4YzBIR+WHQoEFISUnBihUrnI+FhYXhpZdewo8//oi33noLBQUF+Mtf/gIA+P3vf4958+YhKioK5eXlKC8vx6OPPgoAOHPmDJ555hls2bIFq1atwt69ezFmzJgmn/nnP/8Zzz//PL777jt06NABQ4YMwZkzZwAAp0+fRt++ffHpp5+ipKQE999/P+6++25s3LgRAFBeXo6srCzcc8892L59OwoLCzFy5EgoigIAePfddzF9+nT87W9/w/bt2zFr1iw8+eSTeOuttwzZV0REemludgGIiGTVo0cP/Oc//3H+/cgjjzj/361bN/z1r3/F+PHj8eqrryI8PBzR0dGw2WyIj493eZ977rnH+f8LLrgAL730Eq644gqcPHkS5513nvO5GTNm4PrrrwcAvPXWWzj//POxcuVK3HbbbejcubMzOAaAhx56CF988QU++OAD9OvXD+Xl5Th79ixGjhyJrl27AgB69erl8t7PP/88Ro4cCQBISkrCtm3b8PrrryM7O1v3fUVEpBcGs0REflIUBTabzfn32rVrkZubix07dqC6uhpnz57F6dOncerUKbRq1crj+2zatAlPPfUUtmzZgl9++cU5WWr//v3o2bOnc7v09HTn/2NiYnDJJZdg+/btAID6+nrMmjULH3zwAQ4ePIi6ujrU1tY6PzclJQXXXXcdevXqhczMTNxwww344x//iHbt2qGmpgalpaW49957MW7cOOdnnD17FtHR0YbsKyIivXCYARGRn7Zv346kpCQAwN69e3HzzTejd+/e+Ne//oVNmzZh/vz5AIC6ujqP71FTU4PMzExERUXh3XffxXfffYeVK1f6fF1jc+bMwYsvvogpU6Zg3bp1KC4uRmZmpvM9mjVrhjVr1uDzzz9Hz5498fLLL+OSSy5BWVmZc1zvwoULUVxc7PxXUlKCDRs2+LVvGmu4r4iI9MRglojIDwUFBdi6dStuueUWAOeyq3a7Hc8//zz69++Piy++GIcOHXJ5TXh4OOrr610e27FjB44ePYpnn30WV155JXr06OF28hcAl8Dyl19+wa5du3DppZcCODc5bNiwYbjrrruQkpKCCy64ALt27XJ5vc1mw4ABAzBz5kz88MMPCA8Px8qVKxEXF4dOnTrhp59+wkUXXeTyT48AtPG+IiLSE4cZEBH5UFtbi4qKCtTX16OyshJ5eXnIzc3FzTffjNGjRwMALrroIpw5cwYvv/wyhgwZgq+//hoLFixweZ9u3brh5MmTyM/PR0pKClq1aoUuXbogPDwcL7/8MsaPH4+SkhI888wzbsvx9NNPo3379oiLi8Pjjz+O2NhY5zqv3bt3x/Lly/HNN9+gXbt2mDt3LiorK53DFL799lvk5+fjhhtuQMeOHfHtt9/i559/dgbDM2fOxMMPP4zo6GgMHjwYtbW1+P777/HLL78gJydH131FRKQrhYiIPMrOzlYAKACU5s2bKx06dFAyMjKURYsWKfX19S7bzp07V0lISFBatmypZGZmKm+//bYCQPnll1+c24wfP15p3769AkCZMWOGoiiK8t577yndunVTIiIilPT0dOWjjz5SACg//PCDoiiKsm7dOgWA8vHHHyu/+93vlPDwcKVfv37Kli1bnO979OhRZdiwYcp5552ndOzYUXniiSeU0aNHK8OGDVMURVG2bdumZGZmKh06dFAiIiKUiy++WHn55Zddyv/uu+8qqampSnh4uNKuXTvlqquuUlasWOF13zjeX+u+IiLSi01R/rcuCxERERGRZDhmloiIiIikxWCWiIiIiKTFYJaIiIiIpMVgloiIiIikxWCWiIiIiKTFYJaIiIiIpMVgloiIiIikxWCWiIiIiKTFYJaIiIiIpMVgloiIiIikxWCWiIiIiKTFYJaIiIiIpPX/AeKE9EUHjwKDAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 800x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.figure(figsize=(8,5))\n",
    "plt.scatter(range(len(fps)),fps[0].get_similarities(fps))\n",
    "plt.xlabel('Database ID')\n",
    "plt.ylabel('DOS similarity')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "633d7fc0-9612-4997-a9b0-075f9f618383",
   "metadata": {},
   "source": [
    "We see that there are no materials that are highly similar to the first entry of the database. As expected, the similarity of the first entry to itself is 1. We could repeat this search for all members of the dataset to discover similar materials, but this is done more efficiently using similarity matrices and clustering. We will explore these in the next tutorial, \"Similarity matrices and clustering\"."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "747a38c8-4443-456f-a7c9-5fbbd7a830a6",
   "metadata": {},
   "source": [
    "Lastly, we can add the fingerprints to the database, to retrieve them anytime later, and to avoid having to compute them again. For built-in fingerprints, this can be done by specifying the _fingerprint type_ as a string, and passing the relevant arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "1fd1dcef-d11f-43cf-afcd-2c24c90b088d",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2026-04-09 18:37:44,276 - materials_database_log - INFO - Generating DOS fingerprints...\n",
      "2026-04-09 18:37:44,278 - materials_database_log - INFO - Generating \"DOS\" fingerprints.\n"
     ]
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "a4d98cc6b6734509a823987ce9b0d410",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "  0%|          | 0/191 [00:00<?, ?it/s]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2026-04-09 18:38:00,204 - materials_database_log - INFO - Writing DOS fingerprints to database...\n",
      "2026-04-09 18:38:22,401 - materials_database_log - INFO - Finished generation of DOS fingerprints.\n"
     ]
    }
   ],
   "source": [
    "db.add_fingerprint('DOS', fingerprint_kwargs={'grid': grid}, energy_path='dos_energies', dos_path='dos_values')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2652e6dc-56c7-4bbc-8fe3-bd79863b6dca",
   "metadata": {},
   "source": [
    "## Create custom fingerprints"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "247af6e1-10b5-491e-885b-40b81ceb72b0",
   "metadata": {},
   "source": [
    "Finally, we can use MADAS to develop, create, and use our own fingerprint types. For this, we will develop a simple descriptor based on the concentrations of the atoms found in the unti cell of a compound. We generate the descriptor, and develop a similarity measure to use alongside with it.\n",
    "\n",
    "First we develop the descriptor. This is best done on two examples. We pick to specific examples here to illustrate the idea."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "79d47ade-6dee-41c1-a89e-91f8df719e17",
   "metadata": {},
   "outputs": [],
   "source": [
    "example_material = db[\"dl1IDbhK7pPd2Nlalj1T2zXqP6Xw\"]\n",
    "example_material_2 = db[\"X8yjRRcfgr2ffZYLelMEVPTLFW-g\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6892b261-b523-4d57-9746-2971b6cd91cd",
   "metadata": {},
   "source": [
    "We find that we can use the `Atoms` object of a `Material` to get the atomic numbers Z in a compund:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "408f9876-5be5-4b30-bf44-cfaaaa4e8a5f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 29,\n",
       "       29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29,\n",
       "       29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29,\n",
       "       29])"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "example_material.atoms.get_atomic_numbers()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "b238a47a-55d3-48e7-9039-b0bbbe8dc132",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13,\n",
       "       13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 28, 28,\n",
       "       28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28,\n",
       "       28, 28, 28, 28, 28])"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "example_material_2.atoms.get_atomic_numbers()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ffa59bc-71ee-475c-b41f-f13ba13fa228",
   "metadata": {},
   "source": [
    "We can see that both structures contain Al (Z=13), but also other elements."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4879ae56-0827-4dd8-b26e-b4bd5af8c1e7",
   "metadata": {},
   "source": [
    "The idea of our custom descriptor is to store the concentrations of each element in the compound. The concentration is the number of atoms of a certain element, divided by the total number of atoms in the unit cell. To represent this quantity for all elements in the unit cell, we could use a vector of lenght 118, with one entry for each element. However, most of these entries will be 0, and we can save memory by storing only these elements that are actually present in the compound. To do so, we can them write the atomic numbers to a dictionary.  \n",
    "We do this individually for each example material:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "8f21c1a6-5c5b-4952-82d8-00ec5b42f2b9",
   "metadata": {},
   "outputs": [],
   "source": [
    "concentration_dict = {}\n",
    "for number in example_material.atoms.get_atomic_numbers().tolist():\n",
    "    try:\n",
    "        concentration_dict[number] += 1\n",
    "    except KeyError:\n",
    "        concentration_dict[number] = 1\n",
    "for key in concentration_dict.keys():\n",
    "    concentration_dict[key] /= len(example_material.atoms)\n",
    "\n",
    "concentration_dict_2 = {}\n",
    "for number in example_material_2.atoms.get_atomic_numbers().tolist():\n",
    "    try:\n",
    "        concentration_dict_2[number] += 1\n",
    "    except KeyError:\n",
    "        concentration_dict_2[number] = 1\n",
    "for key in concentration_dict_2.keys():\n",
    "    concentration_dict_2[key] /= len(example_material_2.atoms)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "aed2b668-c4ba-427a-a99a-3e86b686bb6c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{13: 0.3076923076923077, 29: 0.6923076923076923}"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "concentration_dict"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "c114bc5e-bdfa-42f6-9904-c8667f8b5408",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{13: 0.5714285714285714, 28: 0.42857142857142855}"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "concentration_dict_2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1f6d0f6c-ec78-4dde-b655-a5130d7d934a",
   "metadata": {},
   "source": [
    "These dictionaries now contain the concentration of each atom type that is present in the compound.\n",
    "\n",
    "We can create a similarity measure: If we picture the concentrations as a vector, the value in each component is represented by the value of our dictionary. If the dictionary does not have an element as a key, the concentration is 0. The \"overlap\" between two concentration vectors is then the minimal value for each component of the vector. Since most of the components are 0 anyway, we only need to compare those that exist as keys in the dictionaries. We can use this overlap directly as a similarity measure, as it is naturally defined between 0 and 1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "0c3f0876-9e05-45e7-ab39-be7c9ddb390b",
   "metadata": {},
   "outputs": [],
   "source": [
    "overlap = 0\n",
    "for number in concentration_dict.keys():\n",
    "    try:\n",
    "        overlap += min(concentration_dict[number], concentration_dict_2[number])\n",
    "    except KeyError:\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f9453ce-3b5f-4e2e-a999-f8fcfdfe3437",
   "metadata": {},
   "source": [
    "If we look at the concentration dicts above, the lower concentration is found for the first example material. Therefore, the overlap between both should be 0.3076923076923077:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "936cf1a5-b0df-43f7-9c90-a7279fe82f93",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.3076923076923077"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "overlap"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "04c9143f-7a91-4c8b-89c2-6843738f0faf",
   "metadata": {},
   "source": [
    "To compute these fingerprints for all materials in the database, we can write them as a MADAS `Fingerprint` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "3c8744dc-2d73-494e-95cc-72fc15cf06d4",
   "metadata": {},
   "outputs": [],
   "source": [
    "from madas import Fingerprint\n",
    "\n",
    "def concentration_vector_similarity(fingerprint1, fingerprint2):\n",
    "    number_dict1 = fingerprint1.data['concentration_dict']\n",
    "    number_dict2 = fingerprint2.data['concentration_dict']\n",
    "    overlap = 0\n",
    "    for number in number_dict1.keys():\n",
    "        try:\n",
    "            overlap += min(number_dict1[number], number_dict2[number])\n",
    "        except KeyError:\n",
    "            pass\n",
    "    return overlap\n",
    "\n",
    "class ConcentrationVectorFingerprint(Fingerprint):\n",
    "\n",
    "   # This declaration can be skipped.\n",
    "   # However, it is advised to explicitly write the `__init__` function.\n",
    "    def __init__(self,\n",
    "               name = \"ConcentrationVector\",\n",
    "               similarity_function=concentration_vector_similarity,\n",
    "               pass_on_exceptions=True) -> None:\n",
    "        super().__init__(name=name, \n",
    "                         similarity_function=similarity_function, \n",
    "                         pass_on_exceptions=pass_on_exceptions)\n",
    "\n",
    "    def calculate(self, atoms):\n",
    "        concentration_dict = {}\n",
    "        for number in atoms.get_atomic_numbers().tolist():\n",
    "            try:\n",
    "                concentration_dict[number] += 1\n",
    "            except KeyError:\n",
    "                concentration_dict[number] = 1\n",
    "        for key in concentration_dict.keys():\n",
    "            concentration_dict[key] /= len(atoms)\n",
    "        # REQUIRED: set the fingerprint data\n",
    "        self.set_data(\"concentration_dict\", concentration_dict)\n",
    "        # REQUIRED: return self\n",
    "        return self\n",
    "    \n",
    "    def from_material(self, material):\n",
    "        # REQUIRED: set the material identifier for this fingerprint\n",
    "        self.set_mid(material)\n",
    "        # calculate the fingerprint\n",
    "        self.calculate(material.atoms)\n",
    "        # REQUIRED: return self\n",
    "        return self"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "86a9be64-28c3-426d-9edf-da858154aaea",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2026-04-09 18:38:22,569 - materials_database_log - INFO - Generating \"<class '__main__.ConcentrationVectorFingerprint'>\" fingerprints.\n"
     ]
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "0fc2840602dd43739e3b123e0f50eac4",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "  0%|          | 0/191 [00:00<?, ?it/s]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "conc_fps = db.get_fingerprints(ConcentrationVectorFingerprint, similarity_function=concentration_vector_similarity)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03c92e8d-ea42-43ef-bbd9-d059b34aa3b2",
   "metadata": {},
   "source": [
    "These fingerprints can be used in the same way as built-in fingerprints:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "222a0d0c-1d62-4c82-a2e9-8e6327865311",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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8JXpCP3JaiSzQfTUU09p+vTpys/PV1FRkYYOHapRo0apqqoq3KGFzZtvvqnbbrtN77//vl577TUdPXpUI0eO1OHDh/3KTZw4UeXl5b6fBx98MEwRh8+gQYP82uCdd97xvTdt2jStXbtWzzzzjN58803t3btX1113XRijDY8PP/zQr41ee+01SdLPfvYzX5mO2JcOHz6soUOHaunSpc2+/+CDD2rx4sVavny5PvjgA51xxhkaNWqU6urqfGVuvPFGffrpp3rttdf0r3/9S2+99ZZuvfXWUH2EkGmtrY4cOaKioiLNmjVLRUVFWrNmjbZt26ZrrrmmSdl7773Xr59NmTIlFOGHzKn6lCTl5ub6tcETTzzh935H6FOnaqcT26e8vFwrVqyQy+XST37yE79y7b0/Wc5A0GRmZhq33Xab77XH4zF69+5tzJs3L4xR2UtVVZUhyXjzzTd9y77//e8bU6dODV9QNpCfn28MHTq02fcOHDhgdO7c2XjmmWd8y7Zs2WJIMjZs2BCiCO1p6tSpxoABAwyv12sYBn3JMAxDkvHcc8/5Xnu9XiMpKclYsGCBb9mBAweM6Oho44knnjAMwzBKS0sNScaHH37oK/PKK68YLpfL2LNnT8hiD7WT26o5GzduNCQZX375pW9Z3759jYcffji4wdlIc+00fvx4Y/To0S2u0xH7VCD9afTo0cbll1/ut6yj9ScrcGU2SBoaGrRp0ybl5OT4lkVERCgnJ0cbNmwIY2T2UlNTI0mKj4/3W/6Pf/xDPXv2VHp6umbOnKkjR46EI7yw+vzzz9W7d2/1799fN954o3bt2iVJ2rRpk44ePerXt8477zydffbZHbpvNTQ0aPXq1br55pvlcrl8y+lL/srKylRRUeHXf9xut7Kysnz9Z8OGDerWrZtGjBjhK5OTk6OIiAh98MEHIY/ZTmpqauRyudStWze/5Q888IB69OihYcOGacGCBTp27Fh4Agyj9evXKyEhQeeee64mT56s/fv3+96jTzVVWVmpl156SbfcckuT9+hP5nQKdwDt1b59++TxeJSYmOi3PDExUVu3bg1TVPbi9Xp155136qKLLlJ6erpv+Q033KC+ffuqd+/e+ve//60ZM2Zo27ZtWrNmTRijDa2srCytXLlS5557rsrLyzV37lxdcsklKikpUUVFhaKiopqcTBMTE1VRURGe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LCIiQosXL9ann36qVatWad26dfr9738vSfre976nRYsWKS4uTuXl5SovL9dvf/tbSdLRo0d13333afPmzXr++ee1c+dO3XTTTU3q/N3vfqeHHnpIH374oXr16qW8vDwdPXpUklRXV6fhw4frpZdeUklJiW699Vb98pe/1MaNGyVJ5eXlGjNmjG6++WZt2bJF69ev13XXXSfDMCRJ//jHPzR79mz96U9/0pYtW3T//fdr1qxZWrVqVVDaCgCs0incAQCAU5133nn697//7Xt95513+v7fr18//dd//ZcmTZqkv/zlL4qKipLb7ZbL5VJSUpLfdm6++Wbf//v376/Fixfrwgsv1KFDh3TmmWf63svPz9eVV14pSVq1apXOOussPffcc/r5z3+uPn36+JJjSZoyZYpeffVVPf3008rMzFR5ebmOHTum6667Tn379pUkDR482G/bDz30kK677jpJUmpqqkpLS/Xoo49q/PjxlrcVAFiFZBYA2sgwDLlcLt/r119/XfPmzdPWrVtVW1urY8eOqa6uTkeOHFHXrl1b3M6mTZs0Z84cbd68Wd98843vYaldu3YpLS3NVy47O9v3//j4eJ177rnasmWLJMnj8ej+++/X008/rT179qihoUH19fW+eocOHaorrrhCgwcP1qhRozRy5Ej99Kc/Vffu3XX48GHt2LFDt9xyiyZOnOir49ixY3K73UFpKwCwCrcZAEAbbdmyRampqZKknTt36uqrr9aQIUP0//7f/9OmTZu0dOlSSVJDQ0OL2zh8+LBGjRqluLg4/eMf/9CHH36o55577pTrnWzBggX67//+b82YMUNvvPGGiouLNWrUKN82IiMj9dprr+mVV15RWlqalixZonPPPVdlZWW++3ofe+wxFRcX+35KSkr0/vvvt6ltTnZiWwGAlUhmAaAN1q1bp08++UQ/+clPJB2/uur1evXQQw/pu9/9rr7zne9o7969futERUXJ4/H4Ldu6dav279+vBx54QJdcconOO++8Zh/+kuSXWH7zzTf67LPPdP7550s6/nDY6NGjNXbsWA0dOlT9+/fXZ5995re+y+XSRRddpLlz5+rjjz9WVFSUnnvuOSUmJqp379764osvNHDgQL8fKxLQk9sKAKzEbQYAcAr19fWqqKiQx+NRZWWlCgoKNG/ePF199dUaN26cJGngwIE6evSolixZory8PL377rtavny533b69eunQ4cOqbCwUEOHDlXXrl119tlnKyoqSkuWLNGkSZNUUlKi++67r9k47r33XvXo0UOJiYn64x//qJ49e/rGeT3nnHP07LPP6r333lP37t21cOFCVVZW+m5T+OCDD1RYWKiRI0cqISFBH3zwgb7++mtfMjx37lzdcccdcrvdys3NVX19vT766CN98803mj59uqVtBQCWMgAALRo/frwhyZBkdOrUyejVq5eRk5NjrFixwvB4PH5lFy5caCQnJxtdunQxRo0aZfz97383JBnffPONr8ykSZOMHj16GJKM/Px8wzAM45///KfRr18/Izo62sjOzjZefPFFQ5Lx8ccfG4ZhGG+88YYhyVi7dq0xaNAgIyoqysjMzDQ2b97s2+7+/fuN0aNHG2eeeaaRkJBg3HPPPca4ceOM0aNHG4ZhGKWlpcaoUaOMXr16GdHR0cZ3vvMdY8mSJX7x/+Mf/zAuuOACIyoqyujevbtx6aWXGmvWrGm1bRq3b7atAMAqLsP4v3FZAAAAAIfhnlkAAAA4FsksAAAAHItkFgAAAI5FMgsAAADHIpkFAACAY5HMAgAAwLFIZgEAAOBYJLMAAABwLJJZAAAAOBbJLAAAAByLZBYAAACORTILAAAAx/r/qoBPAbZeM+YAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 800x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.figure(figsize=(8,5))\n",
    "plt.scatter(range(len(conc_fps)),conc_fps[0].get_similarities(conc_fps))\n",
    "plt.xlabel('Database ID')\n",
    "plt.ylabel('Concentration similarity')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aae310a5-862f-43a9-9f88-6daec557a381",
   "metadata": {},
   "source": [
    "We can also add them to the database for later retrieval:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "id": "f5699920-b6c9-42a4-88d2-42e3ea82b718",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2026-04-09 18:38:29,523 - materials_database_log - INFO - Generating ConcentrationVectorFingerprint fingerprints...\n",
      "2026-04-09 18:38:29,524 - materials_database_log - INFO - Generating \"<class '__main__.ConcentrationVectorFingerprint'>\" fingerprints.\n"
     ]
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "56019fd7b8bc4320ba4f6cfe57820418",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "  0%|          | 0/191 [00:00<?, ?it/s]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2026-04-09 18:38:36,020 - materials_database_log - INFO - Writing ConcentrationVectorFingerprint fingerprints to database...\n",
      "2026-04-09 18:38:57,635 - materials_database_log - INFO - Finished generation of ConcentrationVectorFingerprint fingerprints.\n"
     ]
    }
   ],
   "source": [
    "db.add_fingerprint(ConcentrationVectorFingerprint)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "189ae678-caec-41a3-bb6b-2f3785609a17",
   "metadata": {},
   "source": [
    "We will see what we can discover in our data with these fingerprints in our next tutorial: \"Similarity matrices and clustering\"."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0b8208c-2811-446b-b992-c4c5f95d55b8",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "**[1]** Akhil S. Nair, Lucas Foppa, and Matthias Scheffler   \n",
    "_Materials Database from All-electron Hybrid Functional DFT Calculations_.  \n",
    "_Sci Data_ *12*, 1518 (2025). https://doi.org/10.1038/s41597-025-05867-z\n",
    "\n",
    "**[2]** Martin Kuban, Santiago Rigamonti, Markus Scheidgen, and Claudia Draxl:  \n",
    "_Density-of-states similarity descriptor for unsupervised learning from materials data_.  \n",
    "_Sci Data_ *9*, 646 (2022). https://doi.org/10.1038/s41597-022-01754-z\n",
    "\n",
    "**[3]** Peter Willett, John M. Barnard, and Geoffrey M. Downs  \n",
    "_Chemical Similarity Searching_  \n",
    "_J. Chem. Inf. Comput._ *38* , 983 996 (1998). https://doi.org/10.1021/ci9800211  "
   ]
  }
 ],
 "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.12.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}