part5_bdt.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://github.com/thesps/conifer/blob/master/conifer_v1.png?raw=true\" width=\"250\" alt=\"conifer\" />\n",
    "\n",
    "In this notebook we will take the first steps with training a BDT with `xgboost`, then translating it to HLS code for FPGA with `conifer`\n",
    "\n",
    "Key concepts:\n",
    "- model training\n",
    "- model evaluation\n",
    "- `conifer` configuration and conversion\n",
    "- model emulation\n",
    "- model synthesis\n",
    "- accelerator creation\n",
    "\n",
    "For some use cases, the Forest Processing Unit might be an easier entry point as no FPGA synthesis is required for supported boards. Read more about the FPU here: https://ssummers.web.cern.ch/conifer/fpu.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import xgboost as xgb\n",
    "import matplotlib.pyplot as plt\n",
    "import plotting\n",
    "import numpy as np\n",
    "from scipy.special import softmax\n",
    "from sklearn.preprocessing import LabelEncoder, OneHotEncoder\n",
    "import conifer\n",
    "import json\n",
    "import os\n",
    "import sys\n",
    "\n",
    "os.environ['PATH'] = os.environ['XILINX_VITIS'] + '/bin:' + os.environ['PATH']\n",
    "\n",
    "# enable more output from conifer\n",
    "import logging\n",
    "\n",
    "logging.basicConfig(stream=sys.stdout, level=logging.WARNING)\n",
    "logger = logging.getLogger('conifer')\n",
    "logger.setLevel('DEBUG')\n",
    "\n",
    "# create a random seed at we use to make the results repeatable\n",
    "seed = int('hls4ml-tutorial'.encode('utf-8').hex(), 16) % 2**31\n",
    "\n",
    "print(f'Using conifer version {conifer.__version__}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Load dataset\n",
    "\n",
    "Load the jet tagging dataset.\n",
    "\n",
    "**Note**: you need to run part1 first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "X_train_val = np.load('X_train_val.npy')\n",
    "X_test = np.load('X_test.npy')\n",
    "y_train_val_one_hot = np.load('y_train_val.npy')\n",
    "y_test_one_hot = np.load('y_test.npy')\n",
    "classes = np.load('classes.npy', allow_pickle=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We need to transform the test labels from the one-hot encoded values to labels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "le = LabelEncoder().fit(classes)\n",
    "ohe = OneHotEncoder().fit(le.transform(classes).reshape(-1, 1))\n",
    "y_train_val = ohe.inverse_transform(y_train_val_one_hot.astype(int))\n",
    "y_test = ohe.inverse_transform(y_test_one_hot)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Train a BDT\n",
    "We'll use `xgboost`'s `XGBClassifier` with:\n",
    "\n",
    "| Parameter | Explanation |\n",
    "| --- | --- |\n",
    "| `n_estimators=25` | 25 trees |\n",
    "| `max_depth=5` | maximum tree depth of 5 |"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "clf = xgb.XGBClassifier(n_estimators=25, max_depth=5, learning_rate=1.0, random_state=seed).fit(X_train_val, y_train_val)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Validate performance\n",
    "Now we check whether the trained model is any good. We'll plot the ROC curve."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sklearn.metrics import accuracy_score\n",
    "from tensorflow.keras.models import load_model\n",
    "\n",
    "# load the KERAS model from part 1\n",
    "model_ref = load_model('model_1/KERAS_check_best_model.h5')\n",
    "y_ref = model_ref.predict(X_test)\n",
    "\n",
    "# compute predictions of the xgboost model\n",
    "y_xgb = clf.predict_proba(X_test)\n",
    "print(f'Accuracy baseline:  {accuracy_score(np.argmax(y_test_one_hot, axis=1), np.argmax(y_ref, axis=1)):.5f}')\n",
    "print(f'Accuracy xgboost:   {accuracy_score(np.argmax(y_test_one_hot, axis=1), np.argmax(y_xgb, axis=1)):.5f}')\n",
    "\n",
    "fig, ax = plt.subplots(figsize=(9, 9))\n",
    "_ = plotting.makeRoc(y_test_one_hot, y_ref, classes, linestyle='--')\n",
    "plt.gca().set_prop_cycle(None)  # reset the colors\n",
    "_ = plotting.makeRoc(y_test_one_hot, y_xgb, classes, linestyle='-')\n",
    "\n",
    "# add a legend\n",
    "from matplotlib.lines import Line2D\n",
    "\n",
    "lines = [\n",
    "    Line2D([0], [0], ls='--'),\n",
    "    Line2D([0], [0], ls='-'),\n",
    "]\n",
    "from matplotlib.legend import Legend\n",
    "\n",
    "leg = Legend(ax, lines, labels=['part1 Keras', 'xgboost'], loc='lower right', frameon=False)\n",
    "ax.add_artist(leg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://github.com/thesps/conifer/blob/master/conifer_v1.png?raw=true\" width=\"250\" alt=\"conifer\" />\n",
    "\n",
    "Now we'll convert this model to FPGA firmware with `conifer`. We first need to create a configuration in the form of a dictionary. The quickest way to get started is to create a default configuration from the intended target backend (`xilinxhls` for us). Each backend may have different configuration options, so getting the configuration this way helps enumerate the possible options.\n",
    "\n",
    "We will print the configuration, modify it, and print it again. The modifications are:\n",
    "- set the `OutputDirectory` to something descriptive\n",
    "- set the `XilinxPart` to the part number of the FPGA on the Alveo U50"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg = conifer.backends.xilinxhls.auto_config()\n",
    "\n",
    "# print the config\n",
    "print('Default Configuration\\n' + '-' * 50)\n",
    "plotting.print_dict(cfg)\n",
    "print('-' * 50)\n",
    "\n",
    "# modify the config\n",
    "cfg['OutputDir'] = 'model_5/'\n",
    "cfg['XilinxPart'] = 'xcu250-figd2104-2L-e'\n",
    "\n",
    "# print the config again\n",
    "print('Modified Configuration\\n' + '-' * 50)\n",
    "plotting.print_dict(cfg)\n",
    "print('-' * 50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Convert and write\n",
    "Convert the `xgboost` model to a `conifer` one, and print the `help` to see what methods it implements.\n",
    "Then `write` the model, creating the specified output directory and writing all the HLS files to it. We also save the `xgboost` model itself.\n",
    "\n",
    "#### Other converters:\n",
    "`conifer` has converters for several popular BDT training libraries. Each one is used like: `conifer.converters.convert_from_<library>(model, config)`\n",
    "The converters are:\n",
    "- `sklearn`\n",
    "- `xgboost`\n",
    "- `ydf`\n",
    "- `tmva`\n",
    "- `onnx` (exposing `catboost` and `lightGBM`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# convert the model to the conifer representation\n",
    "conifer_model = conifer.converters.convert_from_xgboost(clf, cfg)\n",
    "# print the help to see the API on the conifer_model\n",
    "help(conifer_model)\n",
    "# write the project (writing HLS project to disk)\n",
    "conifer_model.write()\n",
    "# save the conifer model - we can load this again later\n",
    "clf.save_model('model_5/xgboost_model.json')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Explore\n",
    "Browse the files in the newly created project directory to take a look at the HLS code.\n",
    "\n",
    "The output of `!tree model_5` is:\n",
    "\n",
    "```\n",
    "model_5/\n",
    "├── bridge.cpp\n",
    "├── build_hls.tcl\n",
    "├── firmware\n",
    "│   ├── BDT.cpp\n",
    "│   ├── BDT.h\n",
    "│   ├── my_prj.cpp\n",
    "│   ├── my_prj.h\n",
    "│   └── parameters.h\n",
    "├── hls_parameters.tcl\n",
    "├── my_prj.json\n",
    "├── my_prj_test.cpp\n",
    "├── tb_data\n",
    "└── vivado_synth.tcl\n",
    "```\n",
    "\n",
    "- files under `firmware` are the HLS implementation of the model\n",
    "- `my_prj.json` is the saved converted `conifer` model that can be loaded again without the original `xgboost` model\n",
    "- `tcl` scripts are used for synthesizing the project"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Emulate\n",
    "Before starting the lengthy FPGA build process, we should validate that our conversion was successful and that the choice of precision was suitable with a bit-accurate emulation. To do this we need to run the HLS C++ code on the CPU with some test data first. This is like the HLS C Simulation step, but rather than writing a C++ testbench and invoking `vitis_hls` to run `csim`, `conifer` implements Python bindings for the HLS, just like `hls4ml`.\n",
    "\n",
    "We first need to compile (which uses the C++ compiler), then we can make predictions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "conifer_model.compile()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "y_hls = conifer_model.decision_function(X_test)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Compare\n",
    "\n",
    "Now we check whether the emulated predictions are good. To do this we'll plot the ROC curve again with the HLS predictions overlaid."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "y_hls_proba = softmax(y_hls)  # compute class probabilities from the raw predictions\n",
    "\n",
    "print(f'Accuracy baseline:  {accuracy_score(np.argmax(y_test_one_hot, axis=1), np.argmax(y_ref, axis=1)):.5f}')\n",
    "print(f'Accuracy xgboost:   {accuracy_score(np.argmax(y_test_one_hot, axis=1), np.argmax(y_xgb, axis=1)):.5f}')\n",
    "print(f'Accuracy conifer:   {accuracy_score(np.argmax(y_test_one_hot, axis=1), np.argmax(y_hls_proba, axis=1)):.5f}')\n",
    "\n",
    "\n",
    "fig, ax = plt.subplots(figsize=(9, 9))\n",
    "_ = plotting.makeRoc(y_test_one_hot, y_ref, classes, linestyle='--')\n",
    "plt.gca().set_prop_cycle(None)  # reset the colors\n",
    "_ = plotting.makeRoc(y_test_one_hot, y_xgb, classes, linestyle=':')\n",
    "plt.gca().set_prop_cycle(None)  # reset the colors\n",
    "_ = plotting.makeRoc(y_test_one_hot, y_hls_proba, classes, linestyle='-')\n",
    "\n",
    "# add a legend\n",
    "from matplotlib.lines import Line2D\n",
    "\n",
    "lines = [\n",
    "    Line2D([0], [0], ls='--'),\n",
    "    Line2D([0], [0], ls=':'),\n",
    "    Line2D([0], [0], ls='-'),\n",
    "]\n",
    "from matplotlib.legend import Legend\n",
    "\n",
    "leg = Legend(ax, lines, labels=['part1 Keras', 'xgboost', 'conifer'], loc='lower right', frameon=False)\n",
    "ax.add_artist(leg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Build\n",
    "Now we'll run the Vitis HLS and Vivado synthesis. HLS C Synthesis compiles our C++ to RTL, performing scheduling and resource mapping. Vivado synthesis synthesizes the RTL from the previous step into a netlist, and produces a more realistic resource estimation. The latency can't change during Vivado synthesis, it's fixed in the RTL description.\n",
    "\n",
    "After the build completes we can also browse the new log files and reports that are generated.\n",
    "\n",
    "**Warning**: this step might take around 10 minutes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "conifer_model.build(synth=True, vsynth=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Report\n",
    "If the synthesis completed successfuly, we can extract the key metrics from the reports and print them out.\n",
    "The section `\"vsynth\"` contains the report from the Vivado RTL synthesis, which is usually lower, and more realistic than the HLS report."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "report = conifer_model.read_report()\n",
    "plotting.print_dict(report)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deployment with `pynq`\n",
    "\n",
    "There are two main ways to deploy a BDT to an accelerator card with `conifer`:\n",
    "- build a static accelerator with Xilinx HLS backend\n",
    "- use the dynamic accelerator Forest Processing Unit (FPU)\n",
    "\n",
    "Getting started with the FPU is straightforward. For a supported board, you will need only the converted model JSON, and a bitfile that can be downloaded from the conifer website. Read more about the FPU here: https://ssummers.web.cern.ch/conifer/fpu.html\n",
    "\n",
    "However, without a physical device there's not much to show, so in this section we'll see how to deploy the model that we already trained as a static accelerator to a `pynq-z2` board.\n",
    "We'll use the `AcceleratorConfig` part of the configuration that we previously left undefined."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pynq_model_cfg = conifer.backends.xilinxhls.auto_config()\n",
    "pynq_model_cfg['OutputDir'] = 'model_5_pynq'  # choose a new project directory\n",
    "pynq_model_cfg['ProjectName'] = 'conifer_jettag'\n",
    "pynq_model_cfg['AcceleratorConfig'] = {\n",
    "    'Board': 'pynq-z2',  # choose a pynq-z2 board\n",
    "    'InterfaceType': 'float',  # floating point for the data I/O (this is default)\n",
    "}\n",
    "\n",
    "# print the config\n",
    "print('Modified Configuration\\n' + '-' * 50)\n",
    "print(json.dumps(pynq_model_cfg, indent=2))\n",
    "print('-' * 50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Supported boards\n",
    "\n",
    "Here we print the list of supported boards, so you can see what else works \"out of the box\". It's relatively easy to add other Zynq SoC or Alveo boards, for example to add an Alveo U50 card targeting `xilinx_u50_gen3x16_xdma_5_202210_1` platform:\n",
    "\n",
    "```\n",
    "u50 = conifer.backends.boards.AlveoConfig.default_config()\n",
    "u50['xilinx_part'] = 'xcu50-fsvh2104-2-e'\n",
    "u50['platform'] = 'xilinx_u50_gen3x16_xdma_5_202210_1'\n",
    "u50['name'] = 'xilinx_u50_gen3x16_xdma_5_202210_1'\n",
    "u50 = conifer.backends.boards.AlveoConfig(u50)\n",
    "conifer.backends.boards.register_board_config(u50.name, u50)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This is the full list of supported boards:\n",
    "print(f'Supported boards: {conifer.backends.boards.get_available_boards()}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load the model\n",
    "\n",
    "We load the JSON for the conifer model we previously used, applying the new configuration just defined. We'll see that the FPGA part specified by the board overrides the `XilinxPart` specified in the default."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pynq_model = conifer.model.load_model('model_5/my_prj.json', new_config=pynq_model_cfg)\n",
    "pynq_model.write()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Build the model\n",
    "\n",
    "Now we run `build` again, running HLS Synthesis, Logic Synthesis and Place & Route, finally producing a bitfile and an archive of files that we'll need to run inference on the pynq-z2 board. \n",
    "\n",
    "**Warning**: this step might take around 20 minutes to complete.\n",
    "\n",
    "The floorplan of the bitfile should like something like this, where the individual tree modules are highlighted in different colours:\n",
    "\n",
    "<img src=\"./images/part5_floorplan.png\" width=\"300\" />"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pynq_model.build(synth=True, bitfile=True, package=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inference on pynq-z2\n",
    "\n",
    "Running inference on the `pynq-z2` would look like this:\n",
    "- download the `model_5/conifer_jettag.zip` archive from this notebook\n",
    "- upload `conifer_jettag.zip` to the pynq-z2 device and unzip it\n",
    "- start a jupyter notebook on the `pynq-z2` and run the following code:\n",
    "\n",
    "```\n",
    "import conifer\n",
    "accelerator = conifer.backends.xilinxhls.runtime.ZynqDriver('conifer_jettag.bit', batch_size=1)\n",
    "X = ... # load some data \n",
    "y_pynq = accelerator.decision_function(X)\n",
    "```\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}