04 - Building your own model.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Custom models\n",
    "\n",
    "All elements of zfit are built to be easily customized. Especially models offer many possibilities to be implemented by the user; in the end, regardless of how many models are provided by a library and of how many things are though, there is always a use-case that was not thought of. High flexibility is therefore a crucial aspect.\n",
    "\n",
    "This has disadvantages: the more freedom a model takes for itself, the less optimizations are potentially available. But this is usually not noticeable.\n",
    "\n",
    "## Creating a model\n",
    "\n",
    "Following the philosophy of zfit, there are different levels of customization. For the most simple use-case, all we need to do is to provide a function describing the shape and the name of the parameters. This can be done by overriding `_unnormalized_pdf`.\n",
    "\n",
    "To implement a mathematical function in zfit, znp, a numpy-like interface or z, the backend, should be used. This ensures that the function can be traced and the gradient can be calculated. If a function is not available, `tf` can also be used.\n",
    "(_There are other ways to use arbitrary Python functions, they will be discussed later on_)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:24.303848Z",
     "start_time": "2024-07-02T13:49:24.297744Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import mplhep\n",
    "import numpy as np\n",
    "import tensorflow as tf\n",
    "import zfit\n",
    "import zfit.z.numpy as znp\n",
    "from zfit import z"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "We can start with a simple model and implement a custom second order polynomial. Therefore we need to inherit from the right base class, the simpler one is `ZPDF`.\n",
    "\n",
    "For a minimal example, we need to override only `_unnormalized_pdf` and specify a list of parameters.\n",
    "\n",
    "`_unnormalized_pdf` gets (currently) one argument, x. This is a zfit `Data` object and should first be unstacked. If it is one dimensional - such as here - it will return a single Tensor, otherwise a list of Tensors that can directly be unpacked."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:28.002466Z",
     "start_time": "2024-07-02T13:49:27.995804Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "class SecondOrderPoly(zfit.pdf.ZPDF):\n",
    "    \"\"\"Second order polynomial `a + b * x + c * x^2`\"\"\"\n",
    "    _PARAMS = ['b', 'c']  # specify which parameters to take\n",
    "\n",
    "    @zfit.supports(norm=False)\n",
    "    def _pdf(self, x, norm, params):  # implement function, unnormalized\n",
    "        del norm  # not needed\n",
    "        data = x[0]  # axis 0\n",
    "        b = params['b']\n",
    "        c = params['c']\n",
    "\n",
    "        return 1 + b * data + c * data ** 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Note that we omitted _consciously_ any attempt to normalize the function, as this is usually done over a specific range. Also, no analytic sampling or integration has to be provided. The model handles all of this internally automatically and we have the full functionality available.\n",
    "\n",
    "First, we can instantiate the model:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:28.937621Z",
     "start_time": "2024-07-02T13:49:28.845802Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "obs = zfit.Space(\"obs1\", -4, 4)\n",
    "\n",
    "b = zfit.Parameter('b', 0.2, 0.1, 10)\n",
    "custom_poly = SecondOrderPoly(obs=obs, b=b, c=1.4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "which lets us now fully access all the main methods of a model:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:32.544368Z",
     "start_time": "2024-07-02T13:49:29.422934Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "integral = custom_poly.integrate(limits=(-1, 2))\n",
    "sample = custom_poly.sample(n=10)\n",
    "prob = custom_poly.pdf(sample)\n",
    "print(f\"integral={integral}, sample={sample}, prob={prob}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### What happened?\n",
    "\n",
    "The model tries to use analytical functions for integration and sampling _if available_, otherwise (as happened above), it falls back to the numerical methods. To improve our model, we can add an analytic integral, a common use case. This has to be the _integral over the `_unnormalized_pdf`_.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:32.552725Z",
     "start_time": "2024-07-02T13:49:32.546321Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "# define the integral function\n",
    "\n",
    "\n",
    "def cdf_poly(limit, b, c):\n",
    "    return limit + 0.5 * b * limit ** 2 + 1 / 3 * c * limit ** 3\n",
    "\n",
    "\n",
    "def integral_func(limits, norm_range, params, model):\n",
    "    del norm_range, model  # not needed\n",
    "\n",
    "    b = params['b']\n",
    "    c = params['c']\n",
    "\n",
    "    lower, upper = limits.v1.limits\n",
    "\n",
    "    # calculate the integral\n",
    "    integral = cdf_poly(upper, b, c) - cdf_poly(lower, b, c)\n",
    "    print(\"Integral called\")\n",
    "    return integral\n",
    "\n",
    "\n",
    "# define the space over which it is defined. Here, we use the axes\n",
    "integral_limits = zfit.Space(axes=(0,), limits=(zfit.Space.ANY, zfit.Space.ANY))\n",
    "\n",
    "SecondOrderPoly.register_analytic_integral(func=integral_func, limits=integral_limits)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:32.565361Z",
     "start_time": "2024-07-02T13:49:32.554640Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "poly2 = SecondOrderPoly(obs=obs, b=b, c=1.2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:33.077260Z",
     "start_time": "2024-07-02T13:49:32.568720Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "integral_analytic = custom_poly.integrate(limits=(-1, 2))\n",
    "sample = custom_poly.sample(n=10)\n",
    "prob_analytic = custom_poly.pdf(sample)\n",
    "print(f\"integral={integral}, sample={sample}, prob={prob}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## Multiple dimensions and parameters with angular observables\n",
    "\n",
    "So far, we used rather simple examples and many basic shapes, such as polynomials, already have an efficient implementation within zfit. Therefore, we will now create a three dimensional PDF measuring the angular observables of a $B^+ \\rightarrow K^* l l$ decay.\n",
    "\n",
    "The implementation is not \"special\" or complicated at all, it rather shows how to deal with multiple dimensions and how to manage several parameters. It was created using the equation of the angular observables (taken from a paper).\n",
    "\n",
    "_Many thanks to Rafael Silva Coutinho for the implementation!_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:33.093436Z",
     "start_time": "2024-07-02T13:49:33.079040Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "class AngularPDF(zfit.pdf.ZPDF):\n",
    "    \"\"\"Full d4Gamma/dq2dOmega for Bd -> Kst ll (l=e,mu)\n",
    "\n",
    "    Angular distribution obtained in the total PDF (using LHCb convention JHEP 02 (2016) 104)\n",
    "        i.e. the valid of the angles is given for\n",
    "            - phi: [-pi, pi]\n",
    "            - theta_K: [0, pi]\n",
    "            - theta_l: [0, pi]\n",
    "\n",
    "        The function is normalized over a finite range and therefore a PDF.\n",
    "\n",
    "        Args:\n",
    "\n",
    "            FL (`zfit.Parameter`): Fraction of longitudinal polarisation of the Kst\n",
    "            S3 (`zfit.Parameter`): A_perp^2 - A_para^2 / A_zero^2 + A_para^2 + A_perp^2 (L, R)\n",
    "            S4 (`zfit.Parameter`): RE(A_zero*^2 * A_para^2) / A_zero^2 + A_para^2 + A_perp^2 (L, R)\n",
    "            S5 (`zfit.Parameter`): RE(A_zero*^2 * A_perp^2) / A_zero^2 + A_para^2 + A_perp^2 (L, R)\n",
    "            AFB (`zfit.Parameter`): Forward-backward asymmetry of the di-lepton system (also i.e. 3/4 * S6s)\n",
    "            S7 (`zfit.Parameter`): IM(A_zero*^2 * A_para^2) / A_zero^2 + A_para^2 + A_perp^2 (L, R)\n",
    "            S8 (`zfit.Parameter`): IM(A_zero*^2 * A_perp^2) / A_zero^2 + A_para^2 + A_perp^2 (L, R)\n",
    "            S9 (`zfit.Parameter`): IM(A_perp*^2 * A_para^2) / A_zero^2 + A_para^2 + A_perp^2 (L, R)\n",
    "            obs (`zfit.Space`):\n",
    "            name (str):\n",
    "            dtype (tf.DType):\n",
    "    \"\"\"\n",
    "\n",
    "    _PARAMS = ['FL', 'S3', 'S4', 'S5', 'AFB', 'S7', 'S8', 'S9']\n",
    "    _N_OBS = 3\n",
    "\n",
    "    @zfit.supports(norm=False)\n",
    "    def _pdf(self, x, norm, params):  # or _unnormalized_pdf\n",
    "        del norm\n",
    "        FL = params['FL']\n",
    "        S3 = params['S3']\n",
    "        S4 = params['S4']\n",
    "        S5 = params['S5']\n",
    "        AFB = params['AFB']\n",
    "        S7 = params['S7']\n",
    "        S8 = params['S8']\n",
    "        S9 = params['S9']\n",
    "\n",
    "        costheta_l = x[0]\n",
    "        costheta_k = x[1]\n",
    "        phi = x[2]\n",
    "\n",
    "        sintheta_k = tf.sqrt(1.0 - costheta_k * costheta_k)\n",
    "        sintheta_l = tf.sqrt(1.0 - costheta_l * costheta_l)\n",
    "\n",
    "        sintheta_2k = (1.0 - costheta_k * costheta_k)\n",
    "        sintheta_2l = (1.0 - costheta_l * costheta_l)\n",
    "\n",
    "        sin2theta_k = (2.0 * sintheta_k * costheta_k)\n",
    "        cos2theta_l = (2.0 * costheta_l * costheta_l - 1.0)\n",
    "        sin2theta_l = (2.0 * sintheta_l * costheta_l)\n",
    "\n",
    "        pdf = ((3.0 / 4.0) * (1.0 - FL) * sintheta_2k +\n",
    "               FL * costheta_k * costheta_k +\n",
    "               (1.0 / 4.0) * (1.0 - FL) * sintheta_2k * cos2theta_l +\n",
    "               -1.0 * FL * costheta_k * costheta_k * cos2theta_l +\n",
    "               S3 * sintheta_2k * sintheta_2l * znp.cos(2.0 * phi) +\n",
    "               S4 * sin2theta_k * sin2theta_l * znp.cos(phi) +\n",
    "               S5 * sin2theta_k * sintheta_l * znp.cos(phi) +\n",
    "               (4.0 / 3.0) * AFB * sintheta_2k * costheta_l +\n",
    "               S7 * sin2theta_k * sintheta_l * znp.sin(phi) +\n",
    "               S8 * sin2theta_k * sin2theta_l * znp.sin(phi) +\n",
    "               S9 * sintheta_2k * sintheta_2l * znp.sin(2.0 * phi))\n",
    "\n",
    "        return pdf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Multidimensional Spaces\n",
    "\n",
    "This PDF now expects multidimensional data. Therefore, we need to provide a Space in multiple dimensions. The preferred way is to use the product operations to build this space from one dimensional `Space`s"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:33.098664Z",
     "start_time": "2024-07-02T13:49:33.095561Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:33.112737Z",
     "start_time": "2024-07-02T13:49:33.101750Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "costhetha_k = zfit.Space('costheta_k', -1, 1)\n",
    "costhetha_l = zfit.Space('costheta_l', lower=-1, upper=1)\n",
    "phi = zfit.Space('phi', -np.pi, np.pi)\n",
    "angular_obs = costhetha_k * costhetha_l * phi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Managing parameters\n",
    "\n",
    "Luckily, we're in Python, which provides many tools out-of-the-box. Handling parameters in a `dict` can make things very easy, even for several parameters as here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:33.176420Z",
     "start_time": "2024-07-02T13:49:33.114727Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "params_init = {'FL':  0.43, 'S3': -0.1, 'S4': -0.2, 'S5': -0.4, 'AFB': 0.343, 'S7': 0.001, 'S8': 0.003, 'S9': 0.002}\n",
    "params = {name: zfit.Parameter(name, val, -1, 1) for name, val in params_init.items()}\n",
    "angular_pdf = AngularPDF(obs=angular_obs, **params)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.292888Z",
     "start_time": "2024-07-02T13:49:33.178273Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "integral_analytic = angular_pdf.integrate(limits=angular_obs)  # this should be one\n",
    "sample = angular_pdf.sample(n=1000)\n",
    "prob_analytic = angular_pdf.pdf(sample)\n",
    "print(f\"integral={integral}, sample={sample}, prob={prob[:10]}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Including another observable\n",
    "We built our angular PDF successfully and can use this 3 dimensional PDF now. If we want, we could also include another observable. For example, the polynomial that we created above and make it 4 dimensional. Because it's so simple, let's do that!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.304001Z",
     "start_time": "2024-07-02T13:49:39.297422Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "full_pdf = angular_pdf * poly2\n",
    "\n",
    "# equivalently\n",
    "# full_pdf = zfit.pdf.ProductPDF([angular_pdf, poly2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Done! This PDF is now 4 dimensional, which _had to be_, given that the observable of `poly2` is different from the observable of `angular_pdf`. If they would coincide, e.g. if `poly2` had the observable `phi`, this would now be a 3 dimensional PDF."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.313986Z",
     "start_time": "2024-07-02T13:49:39.305990Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "print(f\"obs angular: {angular_pdf.obs} obs poly:{poly2.obs} obs product: {full_pdf.obs})\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## What happened _exactly_ ?\n",
    "\n",
    "The model tries to be as smart as possible and calls the most explicit function. Then it starts falling back to alternatives and uses, whenever possible, the analytic version (if available), otherwise a numerical.\n",
    "\n",
    "The rule simplified: public (sanitizes input and) calls [...] private. So e.g. `pdf` calls `_pdf` and if this is not provided, it uses the fallback that may not be optimized, but general enough to work.\n",
    "\n",
    "The rule extended (in its current implementation): public calls a series of well defined methods and hooks before it calls the private method. These intermediate _can_ be used, they mostly automatically catch certain cases and handle them for us.\n",
    "\n",
    "**To remember**: in order to have full control over a public function such as `integrate`, `pdf`, `sample` or `normalization`, the private method, e.g. `_integrate` can be overriden and is _guaranteed_ to be called before other possibilities.\n",
    "\n",
    "In the case above, `pdf` called first `_pdf` (which is not implemented), so it calls `_unnormalized_pdf` and divides this by the `normalization`. The latter also does not have an explicit implementation (`_implementation`), so it uses the fallback and calls `integrate` over the `norm_range`. Since `_integrate` is not provided, the fallback tries to perform an analytic integral, which is not available. Therefore, it integrates the `_unnormalized_prob` numerically. In all of this calls, we can hook in by overriding the mentioned, specified methods.\n",
    "\n",
    "What we did not mention: `ZPDF` is just a wrapper around the actual `BasePDF` that should be preferred in general; it simply provides a convenient `__init__`. For the next example, we will implement a multidimensional PDF and use the custom `__init__`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Overriding `pdf`\n",
    "\n",
    "Before, we used `_unnormalized_pdf`, which is the common use-case. Even if we want to add an analytic integral, we can register it. Or do more fancy stuff like overriding the `_normalization`. We can however also get the full control of what our model output by directly overriding `_pdf`. The signature does not contain only `x` but additionally `norm_range`. This can have no limits (`norm_range.has_limits` is False), in which case the \"unnormalized pdf\" is requested. Otherwise, `norm_range` can have different limits and we have to take care of the proper normalization.\n",
    "\n",
    "This is usually not needed and inside zfit, all PDFs are implemented using the `_unnormalized_pdf`.\n",
    "\n",
    "Therefore, it provides mostly a possibility to implement _whatever_ is wanted, any unforeseen use-case, any kind of hack to \"just try out something\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.323430Z",
     "start_time": "2024-07-02T13:49:39.315781Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "class CustomPDF(zfit.pdf.BasePDF):\n",
    "    \"\"\"My custom pdf with three parameters.\n",
    "\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, param1, param2, param3, obs, name=\"CustomPDF\", ):\n",
    "        # we can now do complicated stuff here if needed\n",
    "        # only thing: we have to specify explicitly here what is which parameter\n",
    "        params = {'super_param': param1,  # we can change/compose etc parameters\n",
    "                  'param2': param2, 'param3': param3}\n",
    "        super().__init__(obs, params, name=name)\n",
    "\n",
    "    @zfit.supports(norm=True)\n",
    "    def _pdf(self, x, norm, params):\n",
    "        # we should now normalize in here!\n",
    "        data = x[0]\n",
    "        param1 = params['super_param']\n",
    "        param2 = params['param2']\n",
    "        param3 = params['param3']\n",
    "\n",
    "        # just an arbitrary function\n",
    "        probs = 42 * param1 + (data * param3) ** param2\n",
    "        return probs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "In a similar manner, other methods can be overriden as well. We won't go into further details here, as this provides a quite advanced task. Furthermore, if stability is a large concern or such special cases need to be implemented, it is recommended to get in contact with the developers and share the idea."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Binned PDFs\n",
    "\n",
    "Binned models have two more methods, a `counts` and a `rel_counts` (relative counts) method: the latter is normalized to one.\n",
    "\n",
    "Counts are the expected counts in each bin; comparing with a probability density function, the integral over a bin gives the expected counts in that bin. \n",
    "\n",
    "These methods work differently than the `PDF`: they return a histogram, i.e. the whole model, and allows for easy manipulation of whole histograms using scaling etc.\n",
    "\n",
    "Note that you could also override `_pdf` and return unbinned values, however, it is as efficient as creating an unbinned PDF and then binning it using `to_binned`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.336317Z",
     "start_time": "2024-07-02T13:49:39.325090Z"
    }
   },
   "outputs": [],
   "source": [
    "import uhi\n",
    "\n",
    "\n",
    "class MixtureTwoHists(zfit.pdf.BaseBinnedPDF):\n",
    "    def __init__(self,\n",
    "                 hist1,\n",
    "                 hist2,\n",
    "                 frac,\n",
    "                 extended = None,\n",
    "                 norm = None,\n",
    "                 name = None,\n",
    "                 label = None,\n",
    "                 ) -> None:\n",
    "        self.hist1 = hist1\n",
    "        self.hist2 = hist2\n",
    "        params = {'frac': frac}\n",
    "        space = hist1.space\n",
    "        super().__init__(obs=space, params=params,extended=extended, norm=norm, name=name, label=label)\n",
    "        \n",
    "    @zfit.supports(norm=False)\n",
    "    def _rel_counts(self, x, params):\n",
    "        frac = params['frac']\n",
    "        counts = frac * self.hist1.counts() + (1 - frac) * self.hist2.counts()\n",
    "        return counts"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.383602Z",
     "start_time": "2024-07-02T13:49:39.337987Z"
    }
   },
   "outputs": [],
   "source": [
    "# create two histograms\n",
    "binned_space = zfit.Space('obs1', limits=(-5, 5), binning=100)\n",
    "hist1 = zfit.data.from_numpy(obs=binned_space, array=np.random.normal(-1, 0.5, 1000))\n",
    "hist2 = zfit.data.from_numpy(obs=binned_space, array=np.random.normal(1, 0.5, 1000))\n",
    "frac = zfit.Parameter('frac_binned', 0.5, 0, 1, label=\"Mixture fraction\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.390179Z",
     "start_time": "2024-07-02T13:49:39.385632Z"
    }
   },
   "outputs": [],
   "source": [
    "mixture = MixtureTwoHists(hist1=hist1, hist2=hist2, frac=frac)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.614056Z",
     "start_time": "2024-07-02T13:49:39.391937Z"
    }
   },
   "outputs": [],
   "source": [
    "rel_counts = mixture.rel_counts()\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:39.963906Z",
     "start_time": "2024-07-02T13:49:39.618121Z"
    }
   },
   "outputs": [],
   "source": [
    "mplhep.histplot(mixture.to_hist())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:41.463320Z",
     "start_time": "2024-07-02T13:49:39.965836Z"
    }
   },
   "outputs": [],
   "source": [
    "mplhep.histplot(mixture.sample(n=1000, params={'frac_binned': 0.3}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Composed PDFs\n",
    "\n",
    "So far, we only looked at creating a model that depends on parameters and data but did not include other models. This is crucial to create for example sums or products of PDFs. Instead of inheriting from `BasePDF`, we can use the `BaseFunctor` that contains a mixin which handles daughter PDFs correctly.\n",
    "\n",
    "The main difference is that we can now provide a list of PDFs that our model depends on. There can still be parameters (as for example the `fracs` for the sum) that describe the behavior of the models but they can also be omitted (e.g. for the product). _Sidenote: technically, a normal `BasePDF` can of course also have no parameters, however, since this is a constant function without dependencies, this will rarely be used in practice."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:41.472549Z",
     "start_time": "2024-07-02T13:49:41.465215Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "class SquarePDF(zfit.pdf.BaseFunctor):\n",
    "    \"\"\"Example of a functor pdf that takes the log of a single PDF.\n",
    "\n",
    "    DEMONSTRATION PURPOSE ONLY, DO **NOT** USE IN REAL CASE.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, pdf1, name=\"SumOf3\"):\n",
    "        pdfs = [pdf1]  # we could have more of course, e.g. for sums\n",
    "        # no need for parameters here, so we can omit it\n",
    "        obs = pdf1.space\n",
    "        super().__init__(pdfs=pdfs, obs=obs, name=name)\n",
    "\n",
    "    @zfit.supports(norm=False)\n",
    "    def _pdf(self, x, norm, params):\n",
    "        del norm\n",
    "        # we do not need to unstack x here as we want to feed it directly to the pdf1\n",
    "        pdf1 = self.pdfs[0]\n",
    "\n",
    "        return pdf1.pdf(x) ** 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:41.482167Z",
     "start_time": "2024-07-02T13:49:41.474570Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "squarepdf = SquarePDF(pdf1=poly2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:41.566795Z",
     "start_time": "2024-07-02T13:49:41.485584Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "squarepdf.integrate(limits=(-2, 3.2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.142056Z",
     "start_time": "2024-07-02T13:49:41.568573Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "sample_square = squarepdf.sample(n=1000)\n",
    "sample_square"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.241861Z",
     "start_time": "2024-07-02T13:49:43.144587Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "squarepdf.pdf(sample_square)[:10]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## ...and now?\n",
    "\n",
    "We've implemented a custom PDF. Maybe spent quite some time fine tuning it, debugging it. Adding an integral. And now? Time to make it available to others: [zfit-physics](https://github.com/zfit/zfit-physics). This repository is meant for community contributions. It has less requirements to contribute than to zfit core and has a low threshold. Core devs can provide you with help and you can provide the community with a PDF.\n",
    "\n",
    "Make an issue or a PR, everything is welcome!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Mixing with pure Python\n",
    "\n",
    "Whenever possible, it is preferrable to write anything in TensorFlow. But there is the possibility to mix with pure Python, however losing many of the benefits that TensorFlow provides. To do so:\n",
    "\n",
    "- try to use `z.py_function` or `tf.py_function` to wrap pure Python code\n",
    "- if you write something and want to make sure it is run in eager mode, use `zfit.run.assert_executing_eagerly()`. This way, your function won't be compiled and an error would be raised.\n",
    "- set the graph mode and numerical gradient accordingly"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.259835Z",
     "start_time": "2024-07-02T13:49:43.248122Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "x_tf = z.constant(42.)\n",
    "\n",
    "\n",
    "def sqrt(x):\n",
    "    return np.sqrt(x)\n",
    "\n",
    "\n",
    "y = z.py_function(func=sqrt, inp=[x_tf], Tout=tf.float64)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "This raises a warning: since we do not use pure TensorFlow anymore, it means that the automatic gradient (potentially) fails, as it cannot be traced through Python operations. Depending on the use-case, this is not a problem. That's why the warning is an `AdvancedFeatureWarning`: it doesn't say what we're doing is wrong, it simply warns that we should know what we're doing; it can also be switched off as explained in the warning.\n",
    "\n",
    "It is technically not always required: if we e.g. use the internal, numerical gradient of a minimizer such as Minuit, the global setting does not really matter anyway.\n",
    "\n",
    "This follows strongly the zfit philosophy that there _must_ not be any bounds in terms of flexibility and even hackability of the framework, this should be an inherent part of it. However, the user should be made aware when leaving \"the safe path\".\n",
    "\n",
    "To do what the above warning told us to do, we can use `zfit.run.set_autograd_mode(False)`.\n",
    "\n",
    "This is needed whenever we want to use non-traceable Python calls in the dynamic calculations, be it by using `py_function` or be it by switching off the gradient mode as shown below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "#### Sidestep: What is 'z'?\n",
    "\n",
    "This is a subset of TensorFlow, wrapped to improve dtype handling and sometimes even provide additional functionality, such as `z.function` decorator."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Full Python compatibility\n",
    "\n",
    "To operate in a full Python compatible, yet (way) less efficient mode, we can switch off the automatic gradient, as discussed before, and the graph compilation, leaving us with a Numpy-like TensorFlow"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.269485Z",
     "start_time": "2024-07-02T13:49:43.262050Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "zfit.run.set_graph_mode(False)\n",
    "zfit.run.set_autograd_mode(False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "We can now build a Gaussian purely based on Numpy. As we have seen when building graphs with TensorFlow: anything Python-like will be converted to a static value in the graph. So we have to make sure that our code is never run in graph mode but only executed eagerly.\n",
    "\n",
    "This can be done by calling `zfit.run.assert_executing_eagerly()`, which raises an error if this code is run in graph mode.\n",
    "\n",
    "Note that omitting the graph mode means to loose many optimizations: Not only do we loose the whole TensorFlow speedup from the graph, we also perform redundant tasks that are not cached, since zfit itself is optimized to be run in the graph mode.\n",
    "However, practially, this mode should anyway be used rather rarely and compares still in the same order of magnitude as alternatives."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.281448Z",
     "start_time": "2024-07-02T13:49:43.272265Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "class NumpyGauss(zfit.pdf.ZPDF):\n",
    "    _PARAMS = ['mu', 'sigma']\n",
    "\n",
    "    @zfit.supports()\n",
    "    def _unnormalized_pdf(self, x, params):\n",
    "        zfit.run.assert_executing_eagerly()  # make sure we're eager\n",
    "        data = x[0]\n",
    "        mu = params['mu']\n",
    "        sigma = params['sigma']\n",
    "        return np.exp( - 0.5 * (data - mu) ** 2 / sigma ** 2)  # note that we use numpy here"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "This can be tested and compared."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.313790Z",
     "start_time": "2024-07-02T13:49:43.283633Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "obs = zfit.Space('obs1', (-3, 3))\n",
    "mu = zfit.Parameter('mu', 0., -1, 1)\n",
    "sigma = zfit.Parameter('sigma', 1., 0.1, 10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.338350Z",
     "start_time": "2024-07-02T13:49:43.319641Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "gauss_np = NumpyGauss(obs=obs, mu=mu, sigma=sigma)\n",
    "gauss = zfit.pdf.Gauss(obs=obs, mu=mu, sigma=sigma)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.444358Z",
     "start_time": "2024-07-02T13:49:43.343617Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "integral_np = gauss_np.integrate((-1, 0))\n",
    "integral = gauss.integrate((-1, 0))\n",
    "print(integral_np, integral)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-02T13:49:43.448916Z",
     "start_time": "2024-07-02T13:49:43.445901Z"
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "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.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}