Libraries/gemm_oneMKL_SYCL/00_GEMM/01_GEMM_DPCPP_Buffers.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GEMM (Using DPC++ Buffers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following example shows a simple matrix multiplication program using __DPC++__ with the __buffer/accessor__ style of memory management. Follow along with the instructions of the lab to build and run the program. The lab requires a mixture of observing key components, and making simple modifications."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting lab/dpcpp_gemm_buffers.cpp\n"
     ]
    }
   ],
   "source": [
    "%%writefile lab/dpcpp_gemm_buffers.cpp\n",
    "//==============================================================\n",
    "// Copyright © 2023 Intel Corporation\n",
    "//\n",
    "// SPDX-License-Identifier: MIT\n",
    "// =============================================================\n",
    "\n",
    "#include <iostream>\n",
    "#include <vector>\n",
    "\n",
    "//# sycl namespace\n",
    "#include <sycl/sycl.hpp>          \n",
    "using namespace sycl;\n",
    "\n",
    "//# oneMKL DPC++ interface for BLAS functions\n",
    "\n",
    "#include \"oneapi/mkl/blas.hpp\"  \n",
    "// # shorten mkl namespace\n",
    "namespace mkl = oneapi::mkl;    \n",
    "\n",
    "//# The following project performs matrix multiplication using oneMKL / DPC++ with buffers.\n",
    "//# We will execute the simple operation A * B = C\n",
    "//# The matrix B is set equal to the identity matrix such that A * B = A * I\n",
    "//# After performing the computation, we will verify A * I = C -> A = C\n",
    "\n",
    "\n",
    "\n",
    "int main() {\n",
    "\n",
    "    //# dimensions\n",
    "    int m = 3, n = 3, k = 3;\n",
    "    //# leading dimensions\n",
    "    int ldA = 3, ldB = 3, ldC = 3;\n",
    "    //# scalar multipliers\n",
    "    double alpha = 1.0, beta = 1.0;\n",
    "    //# transpose status of matrices\n",
    "    mkl::transpose transA = mkl::transpose::nontrans;\n",
    "    mkl::transpose transB = mkl::transpose::nontrans;\n",
    "    //# matrix data\n",
    "    std::vector<double> A = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0};\n",
    "    std::vector<double> B = {1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0};\n",
    "    std::vector<double> C = {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};\n",
    "    \n",
    "    //### Step 1 - Observe the definition of an asynchronous exception handler.\n",
    "    //# This function object will later be supplied to the queue.\n",
    "    //# It is designed to handle errors thrown while device code executes.\n",
    "    auto async_handler = [](sycl::exception_list exceptions) {\n",
    "        for (std::exception_ptr const &e : exceptions) {\n",
    "            try {\n",
    "                std::rethrow_exception(e);\n",
    "            }\n",
    "            catch (sycl::exception const &e) {\n",
    "                std::cout << \"Caught asynchronous SYCL exception: \" << e.what() << std::endl;\n",
    "           }\n",
    "        }\n",
    "    };\n",
    "\n",
    "    //### Step 2 - Create a device object. (create device and q in one step)\n",
    "    //# Device selectors are used to specify the type of a device.\n",
    "    //# Uncomment _one_ of the following three lines to select a device.\n",
    "    queue q(default_selector_v, async_handler);  //# default_selector returns a device based on a performance heuristic\n",
    "    // queue q(cpu_selector_v);      //# cpu_selector returns a cpu device\n",
    "    // queue q(gpu_selector_v);     //# gpu_selector returns a gpu device\n",
    "    // queue q;\n",
    "    //# Print actual device used\n",
    "    std::cout << \"Device: \" << q.get_device().get_info<info::device::name>() << \"\\n\";\n",
    "\n",
    "    //### Step 4 - Create buffers to hold our matrix data.\n",
    "    //# Buffer objects can be constructed given a container\n",
    "    //# Observe the creation of buffers for matrices A and B.\n",
    "    //# Try and create a third buffer for matrix C called C_buffer.\n",
    "    //# The solution is shown in the hidden cell below.\n",
    "    buffer A_buffer(A);\n",
    "    buffer B_buffer(B);\n",
    "    /* define C_buffer below */\n",
    "    buffer C_buffer(C);\n",
    "    \n",
    "\n",
    "    //### Step 5 - Execute gemm operation.\n",
    "    //# Here, we need only pass in our queue and other familiar matrix multiplication parameters.\n",
    "    //# This includes the dimensions and data buffers for matrices A, B, and C.\n",
    "    mkl::blas::gemm(q, transA, transB, m, n, k, alpha, A_buffer, ldA, B_buffer, ldB, beta, C_buffer, ldC);\n",
    "\n",
    "    //# we cannot explicitly transfer memory to/from the device when using buffers\n",
    "    //# that is why we must use this operation to ensure result data is returned to the host\n",
    "    q.wait_and_throw();  //# block until operation completes, throw any errors\n",
    "\n",
    "    //### Step 6 - Observe creation of accessors to retrieve data from A_buffer and C_buffer.\n",
    "    accessor A_acc(A_buffer,read_only);\n",
    "    accessor C_acc(C_buffer,read_only);\n",
    "\n",
    "    int status = 0;\n",
    "\n",
    "    // verify C matrix using accessor to observe values held in C_buffer\n",
    "    std::cout << \"\\n\";\n",
    "    std::cout << \"C = \\n\";\n",
    "    for (int i = 0; i < m; ++i) {\n",
    "        for (int j = 0; j < n; ++j) {\n",
    "            if (A_acc[i*m+j] != C_acc[i*m+j]) status = 1;\n",
    "            std::cout << C_acc[i*m+j] << \" \";\n",
    "        }\n",
    "        std::cout << \"\\n\";\n",
    "    }\n",
    "    std::cout << \"\\n\";\n",
    "\n",
    "    status == 0 ? std::cout << \"Verified: A = C\\n\" : std::cout << \"Failed: A != C\\n\";\n",
    "    return status;\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solutions - click the three dots below to reveal"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Step 4 - The correct line is\n",
    "```sycl::buffer C_buffer(C);```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Build and Run\n",
    "Select the cell below and click Run ▶ to compile and execute the code above:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Job has been submitted to Intel(R) DevCloud and will execute soon.\n",
      "\n",
      " If you do not see result in 60 seconds, please restart the Jupyter kernel:\n",
      " Kernel -> 'Restart Kernel and Clear All Outputs...' and then try again\n",
      "\n",
      "Job ID                    Name             User            Time Use S Queue\n",
      "------------------------- ---------------- --------------- -------- - -----\n",
      "2281801.v-qsvr-1           ...ub-singleuser u51369          00:01:08 R jupyterhub     \n",
      "2281830.v-qsvr-1           STDIN            u51369          00:00:06 R batch          \n",
      "2281854.v-qsvr-1           ...mm_buffers.sh u51369                 0 Q batch          \n",
      "\n",
      "Waiting for Output ██████████ Done⬇\n",
      "\n",
      "########################################################################\n",
      "#      Date:           Thu 20 Apr 2023 03:27:43 PM PDT\n",
      "#    Job ID:           2281854.v-qsvr-1.aidevcloud\n",
      "#      User:           u51369\n",
      "# Resources:           cput=75:00:00,neednodes=1:gpu:ppn=2,nodes=1:gpu:ppn=2,walltime=06:00:00\n",
      "########################################################################\n",
      "\n",
      "## u51369 is compiling oneMKL_introduction Module0 -- gemm with buffers - 1 of 3 dpcpp_gemm_buffers.cpp\n",
      "\n",
      "########################################################################\n",
      "# End of output for job 2281854.v-qsvr-1.aidevcloud\n",
      "# Date: Thu 20 Apr 2023 03:27:48 PM PDT\n",
      "########################################################################\n",
      "\n",
      "lab/dpcpp_gemm_buffers.cpp:7:10: fatal error: 'sycl/sycl.hpp' file not found\n",
      "#include <sycl/sycl.hpp>          //# sycl namespace\n",
      "         ^~~~~~~~~~~~~~~\n",
      "1 error generated.\n",
      "Job Completed in 10 seconds.\n"
     ]
    }
   ],
   "source": [
    "! chmod 755 q; chmod 755 run_gemm_buffers.sh;if [ -x \"$(command -v qsub)\" ]; then ./q run_gemm_buffers.sh; else ./run_gemm_buffers.sh; fi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The build instructions for this sample can be found in the ```run_gemm_buffers.sh``` script. Consider using the [Link Line Advisor](https://software.intel.com/content/www/us/en/develop/articles/intel-mkl-link-line-advisor.html) to help you create compile and link lines for your oneMKL projects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<html><body><span style=\"color:green\"><h1>Survey</h1></span></body></html>\n",
    "\n",
    "[We would appreciate any feedback you’d care to give, so that we can improve the overall training quality and experience. Thanks! ](https://intel.az1.qualtrics.com/jfe/form/SV_cCpY08ARDi6NhfT)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<html><body><span style=\"color:Red\"><h1>Reset Notebook</h1></span></body></html>\n",
    "\n",
    "##### Should you be experiencing any issues with your notebook or just want to start fresh run the below cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "e9f5a54d77f541bf981b6aebea899d57",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "VBox(children=(Button(description='Reset Notebook', icon='check', style=ButtonStyle(), tooltip='This will upda…"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.display import display, Markdown, clear_output\n",
    "import ipywidgets as widgets\n",
    "button = widgets.Button(\n",
    "    description='Reset Notebook',\n",
    "    disabled=False,\n",
    "    button_style='', # 'success', 'info', 'warning', 'danger' or ''\n",
    "    tooltip='This will update this notebook, overwriting any changes.',\n",
    "    icon='check' # (FontAwesome names without the `fa-` prefix)\n",
    ")\n",
    "out = widgets.Output()\n",
    "def on_button_clicked(_):\n",
    "      # \"linking function with output\"\n",
    "      with out:\n",
    "          # what happens when we press the button\n",
    "          clear_output()\n",
    "          !rsync -a --size-only /data/oneapi_workshop/Intel_oneAPI_MKL_Training/00_GEMM/ ~/Intel_oneAPI_MKL_Training/00_GEMM/\n",
    "          print('Notebook reset -- now click reload on browser.')\n",
    "# linking button and function together using a button's method\n",
    "button.on_click(on_button_clicked)\n",
    "# displaying button and its output together\n",
    "widgets.VBox([button,out])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (Intel® oneAPI 2023.0)",
   "language": "python",
   "name": "c009-intel_distribution_of_python_3_oneapi-beta05-python"
  },
  "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.9.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}