第一讲-如何在Jupyterhub运行和调试ProtoPNet的简明学习版本
#########################################################################################


简介
***************************

本文介绍原开源仓库ProtoPNet的一个简化后的学习版本。 开源仓库ProtoPNet是由论文《This Looks Like That: Deep Learning for Interpretable Image Recognition》的作者提供的ProtoPNet的一种python实现。但是，如果要运行该仓库，论文作者推荐硬件配置是 4 NVIDIA Telsa P-100 GPUs，或者8 NVIDIA Tesla K-80 GPUs. 但是，这对于刚进入ML/AI领域的读者来说，该硬件配置要求太高。

本文介绍的简明学习版本是对原完整仓库的简化，目的是方便刚进入ML/AI领域的读者学习该AI算法；简化后的代码可以在纯CPU上环境上运行、调试，读者可以把每一行代码和原论文的算法描述仔细对比、交叉验证，从而熟练掌握算法原理，为以后进一步快速迁移到GPU环境运行打好基础。

本文是以上主题的第一讲：如何在AcdEvent提供的Jupyterhub运行、调试该ProtoPNet的学习版本。

使用AcdEvent提供的Jupyterhub运行、调试ProtoPNet的学习版本
***********************************************************************************

感兴趣的读者可以访问 :doc:`Academic Simulation Hub <../../simulation>` 在网页底部的’Comment’留言“我申请学习ProtoPNet”。申请成功后，将免费获得登录账号和密码。

获得账号和密码的读者，可以继续访问 `Acdevent's Jupyterhub`_, 使用账号和密码登录Academic Simulation Hub（如图 1)。

.. figure:: ./images/L1/figure01.png

   图 1 登录Academic Simulation Hub

成功登录Academic Simulation Hub后，就可以看到如图 2的登录ProtoPNet简明学习版本的界面。左边是工作空间，右边是Launcher(目前暂时不用）。工作空间下有一个名字为codes的目录。

.. figure:: ./images/L1/figure02.png

   图 2 登录ProtoPNet简明学习版本的界面
 
双击进入codes目录，可以看到ProtoPNet的工程目录（如图 3）。

.. figure:: ./images/L1/figure03.png

   图 3 ProtoPNet的工程目录

继续双击进入ProtoPNet目录，可以看到若干的子目录和文件(如图 4)。

.. figure:: ./images/L1/figure04.png

   图 4 ProtoPNet目录下的子目录和文件

其中：

* *datasets*, *pretrained_models* 和 *saved_models* 是已经提前准备好的训练和测试数据集、预训练模型，和临时保存的文件，当前可以不关注。
* *LICENSE* - MIT license
* *poster.pdf*, *slides.pdf*, *supp_this_looks_like_that.pdf* 和 *this_looks_like_that.pdf* : 它们是原完整仓库所实现的prototypical part network (ProtoPNet)的论文。
* *main.ipynb* - 这就是简化后的ProtoPNet的实验版本。它使用jupyter notebook作为运行环境；运行所需要的python library和package等都已经在云端配置好。读者只需要在线打开该main.ipynb，就可以阅读代码、设置断点并运行、调试，查看中间变量，验证想法，对比原论文的算法细节等。

在开始阅读代码之前，先介绍怎么使用jupyter notebook debugger的调试功能来设置断点和观察中间变量的结果等。

双击打开main.ipynb, 然后点击打开最右边的Debugger图标（如图 5）：

.. figure:: ./images/L1/figure05.png

   图 5 打开Debugger

然后再找到中间偏右的地方的’Enable Debugger’图标(如图 6)并点击; 等待该图标变成红色，代表已经成功Enable Debugger了（如图 7）。

.. figure:: ./images/L1/figure06.png

   图 6 点击Enable Debugger图标

.. figure:: ./images/L1/figure07.png

   图 7 成功Enable Debugger后的图标状态

然后在main.ipynb的第一行的开头点击，添加第一个断点（如图 8）：

.. figure:: ./images/L1/figure08.png

   图 8 在第一行设置断点

点击如图 9所示的右向三角形图标，运行该notebook的第一个cell单元，然后等待第一行的背景变灰，这说明程序程序运行到了第一行的断点处。

.. figure:: ./images/L1/figure09.png

   图 9 运行所选择的一个单元

然后，可以在右边的Debugger窗口中，可以选择Continue, Terminate, Next, Step In, Step-Out来调试；以及Evaluate Code来计算、打印中间结果（如图 10）。

.. figure:: ./images/L1/figure10.png

   图 10 可以选择继续、终止、下一步、进入函数、退出函数、执行表达式等

这里选择Terminate来结束这一次调试，并双击第一行取消该行的断点（如图 11）。

.. figure:: ./images/L1/figure11.png

   图 11选择终止调试和取消断点

然后来到main.ipynb的第八个单元的 def foward(self, x)函数，并点击该函数的第一行，来添加一个新断点(如图 12)：

.. figure:: ./images/L1/figure12.png

   图 12 添加新断点

然后选择notebook的菜单中的Run→Run All Cells (如图 13），从头开始运行main.ipynb.

.. figure:: ./images/L1/figure13.png

   图 13 选择Run All Cells

如果一切正常，那么程序就会在刚才设置的断点处暂停（如图 14）：

.. figure:: ./images/L1/figure14.png

   图 14 在新断点处暂停

然后就可以在Debugger的窗口查看VARIABLES, CALLSTACKS等（如图 15）

.. figure:: ./images/L1/figure15.png

   图 15 在Debugger窗口查看变量、调用栈等

也可以使用如图 16和图 17中的CALLSTACKS中的“Evaluate Code”来打印变量（例如Tensor x)的值：

.. figure:: ./images/L1/figure16.png

   图 16使用Evaluation Code的示例-1

.. figure:: ./images/L1/figure17.png

   图 17使用Evaluation Code的示例-2

打印出来的结果在main.ipynb的最后显示（如图 18）：

.. figure:: ./images/L1/figure18.png

   图 18 查看Evaluation Code的输出结果

如果在以上的操作遇到问题，例如“点击运行按钮过一段时间后程序没有响应”，那么可以重启kernel(如图 19），然后重新点击运行按钮

.. figure:: ./images/L1/figure19.png

   图 19 重启kernel

以上的本讲的内容。下一讲将讲解论文算法原理，并和代码对比和交叉验证。

参考
************************

1. ProtoPNet的原完整仓库  `https://github.com/cfchen-duke/ProtoPNet <https://github.com/cfchen-duke/ProtoPNet>`__

2. Academic Simulation Hub from AcdEvent.com , `https://acdevent.com/simulation.html <https://acdevent.com/simulation.html>`__

.. _Acdevent's Jupyterhub: https://acdevent.cn