notebooks/interface_demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Implement your own energy evaluator interface\n",
    "\n",
    "This notebook tutorial shows the basic steps to implement your own interface for your preferred energy evaluation method. CARE implements GAME-Net-UQ as default estimator for the intermediate and reaction properties, but no worries, if you don't like it or you prefer other methods, here we show the basic steps to do so."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Step 1: Import the base classes for intermediates and reactions. You will have to define a specific interface for your own model as child classes of the one imported here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from care.evaluators import IntermediateEnergyEstimator, ReactionEnergyEstimator\n",
    "from care.evaluators.gamenet_uq import GameNetUQInter, GameNetUQRxn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check the method resolution order (*mro*) for the interfaces implementing GAME-Net-UQ, you will see that these are defined as subclasses of ``IntermediateEnergyEstimator``  and ``ReactionEnergyEstimator``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "GameNetUQInter.__mro__  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "GameNetUQRxn.__mro__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Intermediate evaluator interface\n",
    "\n",
    "We will implement here a model based on group additivity with random values. The main effort involves implementing the method ``IntermediateEnergyEstimator.eval()``, which thakes as input the ``Intermediate`` instance and returns it with the correponsing energy evalautino as instance attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from care import Intermediate, Surface\n",
    "import random\n",
    "\n",
    "class ExampleIntermediate(IntermediateEnergyEstimator):\n",
    "    def __init__(\n",
    "        self, surface: Surface\n",
    "    ):\n",
    "        \"\"\"Example Interface\n",
    "        \"\"\"\n",
    "\n",
    "        self.surface = surface\n",
    "        self.metal_contribution = random.random()  # RANDOM VALUES FOR TUTORIAL PURPOSES!!!\n",
    "\n",
    "    def adsorbate_domain(self):\n",
    "        return ['C', 'H', 'O', 'N', 'S']\n",
    "\n",
    "    def surface_domain(self):\n",
    "        return ['Pd']        \n",
    "\n",
    "    def eval(\n",
    "        self,\n",
    "        intermediate: Intermediate,\n",
    "    ) -> None:\n",
    "\n",
    "        if intermediate.phase == \"surf\":  # active site\n",
    "            intermediate.energy = 0.0\n",
    "        elif intermediate.phase == \"gas\":  # gas phase\n",
    "            intermediate.energy = intermediate.ref_energy()\n",
    "        elif intermediate.phase == \"ads\":  # adsorbed\n",
    "            intermediate.energy = intermediate.ref_energy() + self.metal_contribution\n",
    "        else:\n",
    "            raise ValueError(\"Phase not supported by the current estimator.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reaction evaluator interface\n",
    "\n",
    "Important note: The reaction properties evaluator interface could depend on the way you implement the intermediate energy interface!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from care import ElementaryReaction\n",
    "\n",
    "class ExampleReaction(ReactionEnergyEstimator):\n",
    "    \"\"\"\n",
    "    Example of Interface for evaluating reaction properties.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(\n",
    "        self,\n",
    "        intermediates: dict[str, Intermediate],\n",
    "    ):\n",
    "        self.intermediates = intermediates\n",
    "\n",
    "    def adsorbate_domain(self):\n",
    "        return ['C', 'H', 'O', 'N', 'S']\n",
    "\n",
    "    def surface_domain(self):\n",
    "        return ['Pd']  \n",
    "\n",
    "    def calc_reaction_energy(self, reaction: ElementaryReaction) -> None:\n",
    "        \"\"\"\n",
    "        Get the reaction energy of the elementary reaction.\n",
    "\n",
    "        Args:\n",
    "            reaction (ElementaryReaction): Elementary reaction.\n",
    "        \"\"\"\n",
    "        e_is, e_fs = 0.0, 0.0\n",
    "        \n",
    "        for reactant in reaction.reactants:\n",
    "            if reactant.is_surface:\n",
    "                continue\n",
    "            e_is += abs(reaction.stoic[reactant.code]) * self.intermediates[reactant.code].energy  # energy attribute is set by the IntermediateEnergyEstimator\n",
    "        for product in reaction.products:\n",
    "            if product.is_surface:\n",
    "                continue\n",
    "            e_fs += abs(reaction.stoic[product.code]) * self.intermediates[product.code].energy  # energy attribute is set by the IntermediateEnergyEstimator\n",
    "\n",
    "        reaction.e_is = e_is\n",
    "        reaction.e_fs = e_fs        \n",
    "        reaction.e_rxn = e_fs - e_is\n",
    "\n",
    "    def calc_reaction_barrier(self, reaction: ElementaryReaction) -> None:\n",
    "        \"\"\"\n",
    "        Get BEP activation energy of the elementary reaction.\n",
    "\n",
    "        Args:\n",
    "            reaction (ElementaryReaction): Elementary reaction.\n",
    "        \"\"\"\n",
    "        alpha = 0.5  # scaling factor for activation energy (RANDOM VALUES!!!)\n",
    "        beta = 0.25 # scaling factor for reaction energy (RANDOM VALUES!!!)\n",
    "        reaction.e_ts = alpha * reaction.e_fs + (1 - alpha) * reaction.e_is + beta        \n",
    "        reaction.e_act = reaction.e_ts - reaction.e_is\n",
    "\n",
    "    def eval(\n",
    "        self,\n",
    "        reaction: ElementaryReaction,\n",
    "    ) -> None:\n",
    "        \"\"\"\n",
    "        Estimate the reaction energy properties.\n",
    "\n",
    "        Args:\n",
    "            reaction (ElementaryReaction): The elementary reaction.\n",
    "        \"\"\"\n",
    "        self.calc_reaction_energy(reaction)\n",
    "        self.calc_reaction_barrier(reaction)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Generate CRN with your own interfaces!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from care import gen_blueprint\n",
    "from care.evaluators import load_surface"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "inters, rxns = gen_blueprint(2, 1, False, False, False)  # generate a blueprint with 2 intermediates and 1 reaction"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "surface = load_surface('Pt', '110')  # load a surface from the database"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "your_intermediate_estimator = ExampleIntermediate(surface)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for k, inter in inters.items():    \n",
    "    your_intermediate_estimator.eval(inter)\n",
    "    print(inter, '    ', inters[k].energy)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "your_reaction_estimator = ExampleReaction(inters)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for rxn in rxns:\n",
    "    your_reaction_estimator.eval(rxn)\n",
    "    print(rxn.repr_hr, '    ', rxn.e_rxn, '    ', rxn.e_act)\n",
    "\n",
    "rxns_evaluated = sorted(rxns)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Observations:\n",
    "- **The values shown here are random**, and the formulas used here are extremely simple, but this is just to show how to implement the interface classes. You are free to implement whatever model you prefer (e.g., GNNs, MLPs, group-additivity based, etc.)\n",
    "- The examples shown here do not take into account the dependence on variables like temperature, pressure, pH, etc. but you can easily include them as class attributes\n",
    "- Contact us if you need support in implementing more complex evalautors! :)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "carep",
   "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}