{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# 深層学習APIで学習機の実装を加速させる\n",
"\n",
"__目次__\n",
"\n",
"- 自動微分について\n",
" - フォワードモード(1変数の例)\n",
" - フォワードモード(多変数の例)\n",
" - リバースモード\n",
"- ニューラルネットワークと逆伝播法\n",
"- Chainerを使ってみよう\n",
" - 簡単な計算\n",
" - 線形回帰での最小二乗法を再現\n",
" - 任意の活性化関数を用いた非線形モデル\n",
" - 多クラスのロジスティック回帰の自作と比較\n",
" - 最適化と自分の手で\n",
"\n",
"___"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"## 自動微分について\n",
"\n",
"一言でいうと、自動微分(automatic differentiation, AD)とは、連鎖律を巧妙に繰り返して使うことで、合成関数の微分計算を実装する多種の手法のことである。まず重要なことを述べておくと、\n",
"\n",
"- 数式処理も近似もせず、合成関数のパーツから解析的に求める。\n",
"\n",
"- 代表的なものとしてボトムアップ型もトップダウン型もあって、扱っている関数の入力と出力それぞれの数によって、どれが効率的かが違ってくる。\n",
"\n",
"さて、簡単な事例から見ていこう。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"### フォワードモード(1変数の例)\n",
"\n",
"まずは一変数の関数からなる単純な合成関数を例として取り上げて、ボトムアップ型の方法を見ていくことにする。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"関数$f(g(h(x)))$を考える。\n",
"\n",
"これらの$f,g,h$が$\\mathbb{R}$の上で微分可能で、実数値を返す関数とする。\n",
"\n",
"やりたいこと:$x$について、$f(g(h(x)))$の微分を求めたい(導関数の取る値を計算したい)。\n",
"\n",
"次の表現を使うと便利である。\n",
"\n",
"\\begin{align*}\n",
"u_{0} & = x\\\\\n",
"u_{1} & = h(u_{0})\\\\\n",
"u_{2} & = g(u_{1})\\\\\n",
"u_{3} & = f(u_{2}).\n",
"\\end{align*}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"連鎖律を何度か使うと、以下のように展開できる。\n",
"\n",
"\\begin{align*}\n",
"\\frac{d u_{3}}{d x} & = \\left(\\frac{d u_{3}}{d u_{2}}\\frac{d u_{2}}{d x}\\right)\\\\\n",
"& = \\frac{d u_{3}}{d u_{2}}\\left(\\frac{d u_{2}}{d u_{1}}\\frac{d u_{1}}{d x}\\right)\\\\\n",
"& = \\frac{d u_{3}}{d u_{2}}\\frac{d u_{2}}{d u_{1}} \\left(\\frac{d u_{1}}{d u_{0}}\\frac{d u_{0}}{d x}\\right).\n",
"\\end{align*}\n",
"\n",
"括弧の中にあるところに注視しながら、「層」ごとに入力$x$についての微分を次のように定義する。\n",
"\n",
"\\begin{align*}\n",
"\\dot{u}_{i} = \\frac{d u_{i}}{d x}, \\quad i = 0,1,\\ldots,3\n",
"\\end{align*}\n",
"\n",
"明らかな通り、「下層」から始めると、次のように全層分を再帰的に計算できる。\n",
"\n",
"\\begin{align*}\n",
"\\dot{u}_{i} = \\frac{d u_{i}}{d u_{i-1}} \\dot{u}_{i-1}.\n",
"\\end{align*}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"フォワードモードの自動微分のアルゴリズムをざっくりまとめると次の通りである。\n",
"\n",
"0. シードたる$\\dot{u}_{0}$を計算しておく(普通は$\\dot{u}_{0}=1$)\n",
"\n",
"0. 以降、$i=1,2,\\ldots$に対して:\n",
" 0. $d u_{i} / d u_{i-1}$を計算\n",
" 0. $\\dot{u}_{i-1}$を用いて、$\\dot{u}_{i}$を計算\n",
"\n",
"上記の通りに、有限個の計算を経て、$d f(g(h(x))) / dx$を正しく計算することができる。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"### フォワードモード(多変数の例)\n",
"\n",
"次は多変数への拡張を考える。\n",
"\n",
"\\begin{align*}\n",
"\\mathbf{x} \\in \\mathbb{R}^{d_{0}}, \\enspace h:\\mathbb{R}^{d_{0}} \\to \\mathbb{R}^{d_{1}}, \\enspace g:\\mathbb{R}^{d_{1}} \\to \\mathbb{R}^{d_{2}}, \\enspace f:\\mathbb{R}^{d_{2}} \\to \\mathbb{R}^{d_{3}}\\end{align*}\n",
"\n",
"先ほどと同様に、いくつかの層に分けて、その入出力をベクトル表記すると以下のようになる。\n",
"\n",
"\\begin{align*}\n",
"\\mathbf{u}_{0} & = \\mathbf{x}\\\\\n",
"\\mathbf{u}_{1} & = h(\\mathbf{u}_{0})\\\\\n",
"\\mathbf{u}_{2} & = g(\\mathbf{u}_{1})\\\\\n",
"\\mathbf{u}_{3} & = f(\\mathbf{u}_{2}).\n",
"\\end{align*}\n",
"\n",
"流れは特に変わらないが、ここでは通常の微分ではなく、__偏微分__である。偏微分をたくさん整列させたヤコビ行列が基本となる。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"入力を$\\mathbf{x} = (x_{1},\\ldots,x_{d_{0}})$、各層の出力を$\\mathbf{u}_{i}=(u_{i,1},\\ldots,u_{i,d_{i}})$と書く。次のように各層の出力を下層の入力について微分したヤコビ行列を表わす。\n",
"\n",
"\\begin{align*}\n",
"\\dot{U}_{i} = \\left[ \\frac{\\partial u_{i,j}}{\\partial x_{k}} \\right]_{j,k},\n",
"\\end{align*}\n",
"\n",
"この行列の形は$(d_{i} \\times d_{0})$である。\n",
"\n",
"前節の肝ともいえる再帰的な演算をここで多次元へと拡張する。\n",
"\n",
"\\begin{align*}\n",
"\\frac{\\partial u_{i,j}}{\\partial x_{k}} = \\sum_{l=1}^{d_{i-1}} \\frac{\\partial u_{i,j}}{\\partial u_{i-1,l}} \\frac{\\partial u_{i-1,l}}{\\partial x_{k}}\n",
"\\end{align*}\n",
"\n",
"これは各$i=1,2\\ldots$と$j \\in [d_{i}]$に対して定義されている。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"各層の入出力だけで出来上がる$(d_{i} \\times d_{i-1})$ヤコビ行列もある。\n",
"\n",
"\\begin{align*}\n",
"J_{i} = \\left[\\frac{\\partial u_{i,j}}{\\partial u_{i-1,k}}\\right]_{j,k},\n",
"\\end{align*}\n",
"\n",
"この2つをかけておくと、行列の掛け算による再帰的計算式が得られる。\n",
"\n",
"\\begin{align*}\n",
"\\dot{U}_{i} = J_{i}\\dot{U}_{i-1}.\n",
"\\end{align*}\n",
"\n",
"今度はシードたるものが$\\dot{U}_{0}$で、普通は単位行列となるが、あとは先述の一変数のときとまったく同様に進む。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"__練習問題__\n",
"\n",
"0. 以下の関数について「層」に分けて、計算の順序を明記すること。\n",
"\n",
"\\begin{align*}\n",
"f(x_{1},x_{2}) & = x_{1}x_{2} + \\sin(x_{1})\\\\\n",
"f(x_{1},x_{2}) & = x_{1}+x_{2} + 2\\exp(x_{1}x_{2})\\\\\n",
"f(x_{1},x_{2}) & = \\frac{x_{1}^{3}}{x_{2}} + \\exp(\\sin(x_{1}))\n",
"\\end{align*}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"### リバースモード\n",
"\n",
"正方向のほうは入力から計算していくため自然でわかりやすいが、入力変数が多い場合は計算が大変である。一方のリバースモードは少し変わった計算をするが、フォワードモードが遅いときには活躍することが多い。\n",
"\n",
"前の例をここでも使うことにする。$y = f(g(h(x)))$という合成関数であったことを思い出して、連鎖律を駆使すると以下のように展開できる。\n",
"\n",
"\\begin{align*}\n",
"\\frac{d y}{d x} & = \\left(\\frac{d y}{d u_{0}} \\frac{d u_{0}}{d x}\\right)\\\\\n",
"& = \\left(\\frac{d y}{d u_{1}} \\frac{d u_{1}}{d u_{0}}\\right) \\frac{d u_{0}}{d x}\\\\\n",
"& = \\left(\\frac{d y}{d u_{2}} \\frac{d u_{2}}{d u_{1}}\\right) \\frac{d u_{1}}{d u_{0}} \\frac{d u_{0}}{d x}\\\\\n",
"& = \\left(\\frac{d y}{d u_{3}} \\frac{d u_{3}}{d u_{2}}\\right) \\frac{d u_{2}}{d u_{1}} \\frac{d u_{1}}{d u_{0}} \\frac{d u_{0}}{d x}.\n",
"\\end{align*}\n",
"\n",
"ここでもやはり括弧の中に注視しながら、今度は上層の出力を、任意の中間層の出力について微分を取ることが重要になる。\n",
"\n",
"\\begin{align*}\n",
"\\bar{u}_{i} = \\frac{d y}{d u_{i}}, \\quad i=0,1,2,3.\n",
"\\end{align*}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"以下の通り、この新しい微分を再帰的に求めることができる。\n",
"\n",
"\\begin{align*}\n",
"\\bar{u}_{i} = \\bar{u}_{i+1} \\frac{d u_{i+1}}{d u_{i}}.\n",
"\\end{align*}\n",
"\n",
"最上層のインデックスが$K$であるとすれば、リバースモードの自動微分は概ね次のように行われる。\n",
"\n",
"0. シードたる$\\bar{u}_{K}$を計算しておく(普通は$\\bar{u}_{K}=1$)\n",
"0. 各$i=0,1,\\ldots,K-1$に対して:\n",
" 0. $d u_{K-i} / d u_{K-i-1}$を計算\n",
" 0. $\\bar{u}_{K-i}$を使って、$\\bar{u}_{K-i-1}$を計算\n",
"\n",
"正方向とはまさに逆で、上層から下りていくという流れである。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"多変数への拡張も想像できるように行なう。$\\mathbf{y} = \\mathbf{u}_{K}$とおくと、各層の出力で微分を求めると以下のようになる。\n",
"\n",
"\\begin{align*}\n",
"\\frac{\\partial y_{j}}{\\partial u_{i,k}} = \\sum_{l=1}^{d_{i+1}} \\frac{\\partial y_{j}}{\\partial u_{i+1,l}} \\frac{\\partial u_{i+1,l}}{\\partial u_{i,k}}\n",
"\\end{align*}\n",
"\n",
"これを各$i=0,1,\\ldots,K-1$と$k \\in [d_{i}]$に対して定義される。\n",
"\n",
"2種のヤコビ行列を以下のように表わす。\n",
"\n",
"\\begin{align*}\n",
"\\bar{U}_{i} & = \\left[ \\frac{\\partial y_{j}}{\\partial u_{i,k}} \\right]_{j,k} \\quad (d_{K} \\times d_{i}), \\quad i = 0,1,\\ldots,K \\\\\n",
"\\widetilde{J}_{i} & = \\left[ \\frac{\\partial u_{i+1,j}}{\\partial u_{i,k}} \\right]_{j,k} \\quad (d_{i+1} \\times d_{i}), \\quad i=0,1,\\ldots,K-1.\n",
"\\end{align*}\n",
"\n",
"シードが$\\bar{U}_{K}$で、普通は単位行列となるのだが、これさえあればあとは再帰的に「下りていく」だけである。\n",
"\n",
"\\begin{align*}\n",
"\\bar{U}_{i} = \\bar{U}_{i+1} \\widetilde{J}_{i}.\n",
"\\end{align*}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"機械学習では、実数値を返すロス関数の勾配を求めること、つまり$d_{K}=1$となることが多い。\n",
"\n",
"\n",
"\n",
"うまく実装すると、$d_{K} \\ll d_{0}$という状況下では、フォワードよりも、リバースのほうが格段に速い。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"___"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"## ニューラルネットワークと逆伝播法\n",
"\n",
"ニューラルネットワークを定式化するにあたって、2つの関係式を用いることでほぼ何でも表せる。\n",
"\n",
"\\begin{align*}\n",
"x_{j} & = \\sum_{i \\to j} w_{ij}y_{i}\\\\\n",
"y_{j} & = f_{j}(x_{j})\n",
"\\end{align*}\n",
"\n",
"この$j \\in \\mathcal{V}$がユニット(ノードなどとも)のインデックスである。\n",
"\n",
"- $x_{j}$は$j$番目のユニットへの入力。\n",
"- $y_{j}$は$j$番目のユニットからの出力。\n",
"- $f_{j}$は$j$番目のユニットの活性化関数。\n",
"- \"$i \\to j$\"とは、$j$に接続する(直接$j$の入力に寄与する)すべてのユニット。\n",
"\n",
"「ユニット$i$がユニット$j$に接続する」ことを$e_{i,j}=1$で表し、そうでない場合は$e_{i,j}=0$とする。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"ニューラルネットワークの「層」はユニットの部分集合である。\n",
"\n",
"\\begin{align*}\n",
"V_{1}, V_{2}, \\ldots, V_{L} \\subseteq \\mathcal{V}.\n",
"\\end{align*}\n",
"\n",
"簡明でよく使われる構造としては、フィードフォワードが代表的である。我々の記号を使うと、任意の$i \\in V_{l}$, $j \\in V_{m}$について、\n",
"\n",
"\\begin{align*}\n",
"m \\geq l \\implies e_{j,i} = 0\n",
"\\end{align*}\n",
"\n",
"と下層から上層へと計算をきれいに分離できるモデルである。\n",
"\n",
"- 一般には何でも良いが、よくある「fully connected」層とは、各$i \\in V_{l}$と$j \\in V_{l+1}$に対して、$e_{i,j}=1$が成り立つということである。\n",
"\n",
"- $m > l+1$でも$e_{i,j}=1$となることもある(\"skip-layer\"接続)。\n",
"\n",
"- 任意の$i$に対して$e_{i,j}=0$であれば、$j$を__入力ユニット__と呼ぶ。\n",
"\n",
"- 任意の$i$に対して$e_{j,i}=0$であれば、$j$を__出力ユニット__と呼ぶ。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"有名な活性化関数をいくつかピックアップ:\n",
"\n",
"- 線形:$f(x) = x$\n",
"- 閾値:$f(x) = I\\{x > 0\\}$\n",
"- ロジスティック:$f(x) = e^{x}/(1+e^{x})$\n",
"- Rectified linear unit: $f(x) = \\max\\{0,x\\}$"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"ネットワークの重みが最適化の対象となることが多いが、そのためには何らかの目的関数が必要である。仮にそれを$L$と書く。出力層$O \\subset \\mathcal{V}$に直接的に依存することが多い。$\\ell_{2}$誤差(つまり$\\ell_{2}$ノルムの二乗をとったもの)が回帰問題では定番の一つである。\n",
"\n",
"\\begin{align*}\n",
"L = \\sum_{l \\in O} (t_{l} - y_{l})^{2},\n",
"\\end{align*}\n",
"\n",
"これらの$t_{l}$が出力層の各ユニットの値である。2018年現在、最適化法として、偏微分を求めて勾配ベクトルだけを使った反復的な更新が主流である。前の章でも扱っている最急降下法の一種である。\n",
"\n",
"\\begin{align*}\n",
"w_{ij} \\gets w_{ij} - \\eta \\frac{\\partial L}{\\partial w_{ij}}.\n",
"\\end{align*}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"それでは、ロス関数の返す値と、任意の重みパラメータ$w_{ij}$の依存関係についてもう少し詰めていくことにしよう。インデックス$j$に注目しつつ、以下の数量が重要である。\n",
"\n",
"\\begin{align*}\n",
"L & = L((y_{l})_{l \\in O})\\\\\n",
"y_{l} & = f_{l}(x_{l})\\\\\n",
"x_{l} & = x_{l}(y_{j})\\\\\n",
"y_{j} & = f_{j}(x_{j})\n",
"\\end{align*}\n",
"\n",
"1行目:ロス関数$L$は出力層の関数であるとしている。2行目:出力層の出力値は言うまでもなくその層の入力に依存する。3行目:出力層の入力が$j$番目のユニットに依存するならば、$x_{l}$を$y_{j}$の関数と見るべきである。ここで「依存する」ことは直接的に接続しているときも、間接的に接続しているときもいえる。4行目:あとは$j$番目ユニットの出力がどのように$w_{ij}$に依存するかは、その入力値$x_{j}$と活性化関数$f_{j}$によって決まる。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"以上のことを踏まえて、連鎖律を繰り返して適用することによって、便利な計算式を導出することができる。活性化関数はみな微分可能であるとして、以下のように展開できる。\n",
"\n",
"\\begin{align*}\n",
"\\frac{\\partial L}{\\partial w_{ij}} & = \\sum_{l \\in O} \\frac{\\partial L}{\\partial y_{l}} \\frac{\\partial y_{l}}{\\partial y_{j}} \\frac{\\partial y_{j}}{\\partial x_{j}} \\frac{\\partial x_{j}}{\\partial w_{ij}}\\\\\n",
"& = y_{i} f_{j}^{\\prime}(x_{j}) \\sum_{l \\in O} \\frac{\\partial L}{\\partial y_{l}} \\frac{\\partial y_{l}}{\\partial y_{j}}\\\\\n",
"& = y_{i} f_{j}^{\\prime}(x_{j}) \\frac{\\partial L}{\\partial y_{j}}.\n",
"\\end{align*}\n",
"\n",
"便宜上、ここで$\\delta_{j} = f_{j}^{\\prime}(x_{j}) (\\partial L / \\partial y_{j})$と定義しておくと、綺麗に書き換えられる。\n",
"\n",
"\\begin{align*}\n",
"\\frac{\\partial L}{\\partial w_{ij}} = y_{i} \\delta_{j}.\n",
"\\end{align*}\n",
"\n",
"このデルタに注目して、効率的な計算方法を導き出したのが、\"generalized delta rule\"と呼ばれる著名な手法である。RumelhartとMcClellandの両氏率いる研究グループによって、80年代なかばに知名度が急上昇した。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"一つの良い計算方法は、最上層のユニットのデルタを計算し、それを下層へと「伝播」させる。これは実際のところ、難しいことではない。先述の通り、出力層の$l \\in O$では、$\\delta_{l}$はロス関数の定義からすぐに計算できる。たとえば、2乗誤差の場合、以下のような形を取る。\n",
"\n",
"\\begin{align*}\n",
"\\delta_{l} & = 2y_{l}(1 - y_{l})(y_{l} - t_{l}), & \\text{ logistic activations}\\\\\n",
"\\delta_{l} & = 2(y_{l} - t_{l}), & \\text{ linear activations}\n",
"\\end{align*}\n",
"\n",
"ほかのロス関数や活性化関数でもまったく同様に求めることができる。\n",
"\n",
"それから、出力層以外のユニット$l \\notin O$について重要なのは、$y_{l}$が直接接続しているユニットを追っていくことである。それ以外のユニットは$L$の値を考える上で関係がないので、無視しても良い。展開すると以下のようになる。\n",
"\n",
"\\begin{align*}\n",
"\\frac{\\partial L}{\\partial y_{l}} & = \\sum_{i:l \\to i} \\frac{\\partial L}{\\partial y_{i}} \\frac{\\partial y_{i}}{\\partial y_{l}}\\\\\n",
"& = \\sum_{i:l \\to i} \\frac{\\partial L}{\\partial y_{i}} f_{i}^{\\prime}(x_{i}) w_{li}.\n",
"\\end{align*}\n",
"\n",
"前の定義を利用して整理しておくと、任意のデルタの再帰的な表現が得られる。\n",
"\n",
"\\begin{align*}\n",
"\\delta_{l} = f_{l}^{\\prime}(x_{l}) \\sum_{i:l \\to i} \\delta_{i} w_{li}.\n",
"\\end{align*}\n",
"\n",
"数式では明確であるが、言葉でも難しいことはない。任意の$\\delta_{l}$について、もし$l \\to i$を満たすあらゆるユニット$i$の$\\delta_{i}$をすでに計算しているのであれば、その単純な線形和で$\\delta_{l}$を手に入れることができる。上から始まり、段々と下りていく。これは典型的な「逆伝播法(back-propagation)」である。\n",
"\n",
"用語について: 入力層から入って、各ユニットの$y_{j}$を求める一連の作業をフォワードパス(*forward pass*)と呼ぶことが多い。これに対して、上記のデルタの計算など、重みの偏微分を上から下へと順序よく計算していくことをバックワードパス(*backward pass*)と呼ばれる。この用法は、90年代からすでに浸透しており、2018年現在でも広く使われている(例:後ほど見るChainerの文法に入っている)。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"さて、長々とニューラルネットワークの定式化と一つの最適化方法を見てきたが、これが一体どのように前節のリバースモード自動微分と関わるのだろうか。その答えは、先述の逆伝播法を賢く実装する方法がリバースモード自動微分そのものであり、後者のスペシャルケースとして捉えることができる。\n",
"\n",
"具体例を使って、先ほどのgeneralized delta ruleとの接点を見ていこう。下図のような単純なフィードフォワードニューラルネットワークを考える。\n",
"\n",
""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"ユニットの添え字は絵に書いてある通り、$1,2,3,4,5,6$である。入力層を$u_{1},u_{2},u_{3}$と書く。残りは以下のように整理できる。\n",
"\n",
"\\begin{align*}\n",
"u_{4} & = x_{4} = \\sum_{i \\to 4} w_{i4}u_{i}\\\\\n",
"u_{5} & = x_{5} = \\sum_{i \\to 5} w_{i5}u_{i}\\\\\n",
"u_{6} & = y_{4} = f_{4}(x_{4})\\\\\n",
"u_{7} & = y_{5} = f_{5}(x_{5})\\\\\n",
"u_{8} & = x_{6} = \\sum_{i \\to 5} w_{i6}u_{i}\\\\\n",
"u_{9} & = y_{6} = f_{6}(x_{6})\n",
"\\end{align*}\n",
"\n",
"例のデルタの計算は、自動微分を実行していくことで必然的に入手することになる。\n",
"\n",
"\\begin{align*}\n",
"\\delta_{4} = \\frac{\\partial u_{9}}{\\partial u_{4}}, \\quad \\delta_{5} = \\frac{\\partial u_{9}}{\\partial u_{5}}, \\quad \\delta_{6} = \\frac{\\partial u_{9}}{\\partial u_{8}}\n",
"\\end{align*}\n",
"\n",
"以上のように、リバースモード自動微分を正しく行うことで、デルタの再帰的な計算が自ずと行われることになる。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"___"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"## Chainerを使ってみよう\n",
"\n",
"ごく簡単な紹介ではあったが、自動微分とニューラルネットワークの基本的な考え方を見て、パラメータの最適化を効率的に行う道筋が見えてきている。ただし、多種多様なネットワークアーキテクチャをカバーしながら、これを実装する作業は多大なる労力を要する。幸い、この作業を代行してくれる優秀なエンジニアがたくさんいるので、機械学習の手法のプロトタイプを開発するにあたって、彼らが作ったライブラリを用いることが賢明であろう。言語をPythonに限定しても、オープンソースで使い勝手の良いパッケージが多数ある。\n",
"\n",
"そのなかから、我々が使うのは、__Chainer__という国産のディープラーニングAPIである[link]。日本国内では有名だが、世界ではTensorFlow, PyTorch, Caffeなどの人気APIの陰に隠れている現状である。それでも、Chainerは大変よくできており、実に簡明な枠組みであり、高い自由度と充実した機能性を誇る。また、複数のGPUを同時に駆使する仕組みも整備されており、ソフトウェア工学のバックグラウンドが浅い人でもすぐに使えるはずである。\n",
"\n",
"技術的な特徴としては、開発者がいう\"Define-by-Run\"の仕組みである。実行前にネットワーク構造を固定するのではなく、実行時にフォワードパスを行いながら、動的にネットワーク構造を求めていく[link]。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Chainerの導入については、ドキュメンテーションで推奨されているように[link]、`chainer`を`pip`で入手していることを前提に以下の作業を進めていく。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"モデルの造設にあたって、以下の点を念頭に置いて、作業に入る。\n",
"\n",
"- ありとあらゆるデータやパラメータ(普段、Numpyの配列に格納するもの)は、`Variable`オブジェクトとする[link]。\n",
"\n",
"- `Variable`オブジェクトはNumpyの配列とほぼ同じように扱うことができる[link].\n",
"\n",
"- `FunctionNode`オブジェクトはcomputational graphにおけるノードに相当する。正確にいえば、微分可能な関数を実装したものである[link]。\n",
"\n",
"- 各々の`FunctionNode`に対して、フォワードパスに相当する`forward()`と、バックワードパスに相当する`backward()`という2つのメソッドを必ず整備する。\n",
"\n",
"- ノードの入力を所与として、それを処理する`FunctionNode`は、`apply()`というメソッドによって実行される。実行時には、computational graphにノードが追加され、フォワードパスの計算結果を返すという働きである。\n",
"\n",
"- モデルを作る上で、基本単位となるのは`Link`というオブジェクトである[link]。ある`FunctionNode`に基づく`Link`では、扱っている多数の`Variable`のうち、どれが観測データに相当し、どれが最適化の対象となるパラメータなのかを指定する。一部の変数を`Parameter`オブジェクトとして「登録」する作業が重要である。あと、`Link`では、`FunctionNode`を`__call__()`するためのメソッドも備えている。\n",
"\n",
"- `Chain`と呼ばれるオブジェクトは、`Link`から構成されるもので、モデルの全体あるいはその一部を表わすために使われる(注:`Chain`も`Link`である)[link]。段取りとしては、`Chain`を作成するときに、その構成要素に相当する\"child links\"を登録しておく。\n",
"\n",
"さて、機械学習にあたっての学習作業について考えよう。Chainerの標準搭載の技術を中心としたやり方だと、以下のような手順になる。\n",
"\n",
"- モデルのオブジェクト(ほぼ例外なく`Chain`のサブクラス)を、`setup()`というメソッドによって`Optimizer`オブジェクトに渡しておく。\n",
"\n",
"- 反復的には以下の計算を行う。\n",
"\n",
" - 実数値`Variable`を計算し、例として`loss`と呼ぶ。\n",
" \n",
" - `loss.backward()`を実行して逆伝播法によって、出力層に相当する`loss`から、入力層の重みまで、すべての`FunctionNode`オブジェクトの偏微分を行う。\n",
" \n",
" - 勾配を手に入れた上で、`Optimizer`オブジェクトの`update()`を使って、登録した`Parameter`を更新する。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"### 簡単な計算\n",
"\n",
"Chainerの基本的な働きを調べていくための簡単な事例をいくつか見ていこう。たとえば、以下の入出力の関係を考える。\n",
"\n",
"\\begin{align*}\n",
"y = 2 x_{1}x_{2} + e^{x_{1}}\n",
"\\end{align*}"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"import math\n",
"import chainer as ch\n",
"import numpy as np"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Gradients prior to calling y.backward():\n",
"None\n",
"None\n",
"None\n",
"\n",
"Gradients after calling y.backward():\n",
"[1.]\n",
"[10.481689] ( answer = 10.481689 )\n",
"[3.] ( answer = 3.0 )\n"
]
}
],
"source": [
"touse_1 = 1.5\n",
"touse_2 = 3.0\n",
"\n",
"x1 = ch.Variable(np.array([touse_1], dtype=np.float32))\n",
"x2 = ch.Variable(np.array([touse_2], dtype=np.float32))\n",
"y = 2*x1*x2 + math.exp(1)**x1\n",
"\n",
"# Note that all gradients start out empty.\n",
"print(\"Gradients prior to calling y.backward():\")\n",
"print(y.grad)\n",
"print(x1.grad)\n",
"print(x2.grad)\n",
"\n",
"# Now, compute the gradients of y.\n",
"y.backward()\n",
"print(\"\\nGradients after calling y.backward():\")\n",
"print(y.grad)\n",
"print(x1.grad, \"( answer =\",\n",
" np.float32(2*x2.data[0] + math.exp(1)**x1.data[0]),\n",
" \")\")\n",
"print(x2.grad, \"( answer =\",\n",
" np.float32(2*x1.data[0] + 0),\n",
" \")\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"ちゃんと正解を出しているので、一安心である。この計算がどのように行われているか精密検査すべく、3つの層($\\mathbf{u}_{0}, \\mathbf{u}_{1}, \\mathbf{u}_{2}$)に分ける。\n",
"\n",
"\\begin{align*}\n",
"\\mathbf{u}_{0} & = (u_{0,1}, u_{0,2}) = (x_{1}, x_{2})\\\\\n",
"\\mathbf{u}_{1} & = (u_{1,1}, u_{1,2}) = (u_{0,1}u_{0,2}, e^{u_{0,1}})\\\\\n",
"\\mathbf{u}_{2} & = (u_{2,1}) = (2u_{1,1} + u_{1,2}).\n",
"\\end{align*}\n",
"\n",
"上記から明らかなように、$\\mathbf{u}_{0}$を入力として、$\\mathbf{u}_{0} \\mapsto \\mathbf{u}_{1} \\mapsto \\mathbf{u}_{2}$という2つの変換を経て、最終的な出力を得る。以下では、これらの変換をそれぞれ実装した`U1`および`U2`という`FunctionNode`サブクラスを掲げている。"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [],
"source": [
"class U1(ch.function_node.FunctionNode):\n",
" \n",
" def forward(self, inputs):\n",
" \n",
" u0, = inputs\n",
" u1 = np.array([u0[0,0]*u0[0,1], math.exp(1)**u0[0,0]],\n",
" dtype=np.float32)\n",
" u1 = u1.reshape((1,2))\n",
" self.retain_inputs((0,))\n",
" return (u1,)\n",
"\n",
" def backward(self, indices, grad_outputs):\n",
" \n",
" u0, = self.get_retained_inputs()\n",
" u0 = u0.data\n",
" gy, = grad_outputs # defaults to shape (1,2).\n",
" print(\"U1 gy:\", gy.data)\n",
" \n",
" # Compute the Jacobian.\n",
" J = np.array([u0[0,1], u0[0,0], math.exp(1)**u0[0,0], 0.0],\n",
" dtype=np.float32).reshape((2,2))\n",
" J = ch.Variable(J)\n",
" \n",
" # Compute partial derivatives of interest.\n",
" gu0 = gy @ J # gy.dot(J)\n",
" print(\"U1 backward():\", gu0.data)\n",
" return (gu0,)\n",
"\n",
"def fn_u1(u0):\n",
" args = (u0,)\n",
" y, = U1().apply(args)\n",
" return y\n",
"\n",
"\n",
"class U2(ch.function_node.FunctionNode):\n",
" \n",
" def forward(self, inputs):\n",
" \n",
" u1, = inputs\n",
" u2 = np.array([2*u1[0,0]+u1[0,1]])\n",
" self.retain_inputs((0,))\n",
" return (u2,)\n",
"\n",
" def backward(self, indices, grad_outputs):\n",
" \n",
" u1, = self.get_retained_inputs()\n",
" gy, = grad_outputs # defaults to shape (1,).\n",
" gy = gy.reshape((1,1))\n",
" gy = ch.functions.cast(gy, np.float32)\n",
" print(\"U2 gy:\", gy.data)\n",
" \n",
" # Compute the Jacobian.\n",
" J = np.array([2.0, 1.0], dtype=np.float32).reshape((1,2))\n",
" J = ch.Variable(J)\n",
" \n",
" # Compute partial derivatives of interest.\n",
" gu1 = gy @ J # gy.dot(J)\n",
" print(\"U2 backward():\", gu1.data)\n",
" return (gu1,)\n",
" \n",
"def fn_u2(u1):\n",
" args = (u1,)\n",
" y, = U2().apply(args)\n",
" return y"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"フォワードパスのときに使う`forward()`メソッドはすぐに整備できる。定義どおりに実装するだけである。\n",
"\n",
"バックワードパスのときに使う`backward()`に関しては、Chainerの規定をしっかりと理解しておく必要がある(下図を参照)。\n",
"\n",
"\n",
"\n",
"要するに、各層の入出力の偏微分を整列させたヤコビ行列を計算し、`grad_outputs`から渡された係数をかけて、出力のインデックスについて足し合わせていく。上記の`U1`で計算している`J`の寸法は$(2 \\times 2)$で、次の形を取る。\n",
"\n",
"\\begin{align*}\n",
"\\left[ \\frac{\\partial u_{1,i}}{\\partial u_{0,j}} \\right]_{i,j}, \\quad i = 1,2 \\quad j = 1,2.\n",
"\\end{align*}\n",
"\n",
"`U2`で計算している`J`の寸法は$(1 \\times 2)$で、以下の形を取る。\n",
"\n",
"\\begin{align*}\n",
"\\left[ \\frac{\\partial u_{2,i}}{\\partial u_{1,j}} \\right]_{i,j}, \\quad i = 1 \\quad j = 1,2.\n",
"\\end{align*}\n",
"\n",
"リバースモード自動微分の話を思い出すと、次の再帰的な計算が重要であった。\n",
"\n",
"\\begin{align*}\n",
"\\bar{U}_{i} = \\bar{U}_{i+1} \\widetilde{J}_{i}\n",
"\\end{align*}\n",
"\n",
"仮に層の数が$K$であるとして、これらの行列は以下のとおりである。\n",
"\n",
"\\begin{align*}\n",
"\\bar{U}_{i} & = \\left[ \\frac{\\partial y_{j}}{\\partial u_{i,k}} \\right]_{j,k} \\quad (d_{K} \\times d_{i}), \\quad i = 0,1,\\ldots,K \\\\\n",
"\\widetilde{J}_{i} & = \\left[ \\frac{\\partial u_{i+1,j}}{\\partial u_{i,k}} \\right]_{j,k} \\quad (d_{i+1} \\times d_{i}), \\quad i=0,1,\\ldots,K-1.\n",
"\\end{align*}\n",
"\n",
"具体例に戻ると、$K=2$で、次元の数は$d_{0}=2, d_{1}=2, d_{2}=1$となる。以下のコードでは、`backward()`を我々の手作りノードに対して実行することで、その結果が元のコードの結果と完全に一致することがわかる。"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Output of forward passes:\n",
"y: 13.481689\n",
"_y: 13.481688976287842\n",
"\n",
"Content of our backward() passes:\n",
"U2 gy: [[1.]]\n",
"U2 backward(): [[2. 1.]]\n",
"U1 gy: [[2. 1.]]\n",
"U1 backward(): [[10.481689 3. ]]\n",
"\n",
"Gradient of (x1,x2): (10.481689, 3.0)\n",
"Gradient of u0: (10.481689, 3.0)\n"
]
}
],
"source": [
"touse_1 = 1.5\n",
"touse_2 = 3.0\n",
"\n",
"# Original code.\n",
"x1 = ch.Variable(np.array([touse_1], dtype=np.float32))\n",
"x2 = ch.Variable(np.array([touse_2], dtype=np.float32))\n",
"y = 2*x1*x2 + math.exp(1)**x1\n",
"y = y.reshape((1,1))\n",
"\n",
"# Our custom reformulation.\n",
"_u0 = np.array([touse_1, touse_2], dtype=np.float32).reshape((1,2))\n",
"_u0 = ch.Variable(_u0)\n",
"_u1 = fn_u1(u0=_u0)\n",
"_y = fn_u2(u1=_u1)\n",
"_y = _y.reshape((1,1))\n",
"\n",
"print(\"Output of forward passes:\")\n",
"print(\"y:\", *y.data[0])\n",
"print(\"_y:\", *_y.data[0])\n",
"\n",
"y.backward()\n",
"print(\"\\nContent of our backward() passes:\")\n",
"_y.backward()\n",
"\n",
"print(\"\\nGradient of (x1,x2):\", (x1.grad[0], x2.grad[0]))\n",
"print(\"Gradient of u0:\", tuple(*_u0.grad))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"上の実行結果から明らかなように、2層目の`backward()`の結果が、下の1層目に`grad_outputs`という形で渡されている。期待どおりの計算である。\n",
"\n",
"__重要:__ 一般的な自動微分の枠組みでは、究極の計算目的である$\\bar{U}_{0}$が($d_{K} \\times d_{0}$)という形をとっても、何も問題はない。しかし、Chainerでは、必ず$d_{K}=1$と制限されていることに注意が必要である。これが事実であることは、明らかである。その理由は、Chainerのドキュメンテーションより、関数$f: \\mathbb{R}^{a} \\to \\mathbb{R}^{b}$のバックワードパス計算である`backward()`を実装する際、その出力が$\\mathbb{R}^{a}$でなければならないからである。\n",
"\n",
"しかし、数学的には、これは大丈夫であろうか。何を意味するものなのか。さらに検証していくために、先ほどの具体例に戻るが、今度はbackpropの対象を最終層の$\\mathbf{u}_{2} \\in \\mathbb{R}$ではなく、$\\mathbf{u}_{1} \\in \\mathbb{R}^{2}$とする(なお、$\\mathbf{u}_{0}$について微分を求めていることは変わらない)。そのためには、`grad_outputs`を、勾配を初期化する(`grad`を設定する)ことで、自分で渡す必要がある(以下のコードを参照)。"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"U1 gy: [[1. 1.]]\n",
"U1 backward(): [[7.481689 1.5 ]]\n",
"_u0.grad = (7.481689, 1.5)\n"
]
}
],
"source": [
"_u0 = np.array([touse_1, touse_2], dtype=np.float32).reshape((1,2))\n",
"_u0 = ch.Variable(_u0)\n",
"_u1, = fn_u1(u0=_u0)\n",
"_u1.grad = np.ones(_u1.shape, dtype=np.float32)\n",
"_u1.backward()\n",
"print(\"_u0.grad =\", tuple(*_u0.grad))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"すぐにわかるのは、$(1.0, 1.0)$に初期化したとき、計算結果が前と異なることである。その理由は、最後の変換が反映されていないからである。さて、今の例では、逆伝播法の対象となる関数の出力が多次元であることもあって、`backward()`の実行結果がヤコビ行列$\\partial \\mathbf{u}_{1} / \\partial \\mathbf{u}_{0}$となることを予想する読者がいるかもしれない。しかし、先述の理由により、これはあり得ないことである。勾配ベクトルしか保存されない。\n",
"\n",
"そうなると、数学的に、Chainerの中で一体何の関数が微分されているのだろうか。その答えは簡単で、以下のようなダミー関数が微分されているのである。\n",
"\n",
"\\begin{align*}\n",
"f(\\mathbf{u}_{K}) = a_{1} u_{K,1} + \\cdots + a_{K} u_{K,d_{K}}\n",
"\\end{align*}\n",
"\n",
"ここでの$\\mathbf{u}_{K}$は我々のモデルの最終層の出力に相当し、係数$(a_{1},\\ldots,a_{K})$は逆伝播に際して最初に使われる`grad_outputs`に相当する。上の例では、\n",
"\n",
"```\n",
"_u1.grad = np.ones(_u1.shape, dtype=np.float32)\n",
"```\n",
"\n",
"という初期化をしたのだが、これは上記のダミー関数で、$a_{1}=\\cdots=a_{K}=1$と置いたことにほかならない。\n",
"\n",
"上を要約すると、最終層の出力がスカラー値であれば、$d_{K}=1$なのですべてが直感通りである。一方の$d_{K} > 1$の場合、`grad`をどのように初期化するかによって、バックエンドに隠れているダミー関数の係数が変わるため、計算結果も変わってくる。ちなみに、$d_{K}=1$の場合は、わざわざ初期化する必要はなく、自動的に`grad`が1.0に初期化されるようになっている。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"__練習問題__\n",
"\n",
"0. 上の具体例で、2層目を自動微分の対象とした場合、`_u1.grad`を全部1.0にした結果、`_u1.backward()`を実行した結果が、もともとの`_u2.backward()`の実行結果と異なるものであった。どのように初期化すれば、前者が後者に一致するか。\n",
"\n",
"0. 上記の具体例を拡張すべく、たとえば3つか4つほどの層を持つように新しい演算を追加すること。上と同様に、自分で実装し、Chainerの計算結果が我々の数学的な予想と一致するかどうか確認すること。\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"### 線形回帰での最小二乗法を再現\n",
"\n",
"練習の対象として、前の章では下記の学習機を取り上げた。\n",
"\n",
"> - データ:入力ベクトルと実数値の応答$x \\in \\mathbb{R}^{d}$, $y \\in \\mathbb{R}$.データセットの全体は$\\{(x_{1},y_{1}),\\ldots,(x_{n},y_{n})\\}$とする。\n",
"> \n",
"> - モデル:二乗誤差を用いた線形回帰モデル。つまり、$y = \\langle w^{\\ast}, x\\rangle + \\varepsilon$と仮定している。ロス関数は$L(w;x,y) = (y - \\langle w, x\\rangle)^{2}/2$で、勾配が$\\nabla L(w;x,y) = -(y-\\langle w, x\\rangle)x$である。\n",
"> \n",
"> - アルゴリズム:最急降下法を使って、固定したステップサイズ$\\alpha > 0$を用いる。数式で表わすと、$z_{i}=(x_{i},y_{i})$として以下の通りである。\n",
"> \n",
"> \\begin{align*}\n",
"w_{(t+1)} \\gets w_{(t)} - \\alpha \\frac{1}{n} \\sum_{i=1}^{n}\\nabla L(w_{(t)}; z_{i}).\n",
"\\end{align*}\n",
"\n",
"前の章で叩きだした各種のクラスなど、上記を実装するのに必要なものは全部`algorithms.py`, `models.py`, `dataclass.py`, and `helpers.py`に収めてある。ここでは、自作の学習機を、ChainerのAPIによって完全に再現することである。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"まずは必要なモジュールを`import`して、いわゆる\"fully connected linear layer\"を実装した`FunctionNode`を整備する(活性化関数を介さず、入力の線形和を取るだけ)。"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [],
"source": [
"import math\n",
"import numpy as np\n",
"import chainer as ch\n",
"import matplotlib\n",
"import matplotlib.pyplot as plt\n",
"\n",
"import algorithms\n",
"import models\n",
"import dataclass\n",
"import helpers as hlp"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [],
"source": [
"# FunctionNode sub-class, for implementing a fully connected linear layer.\n",
"\n",
"class LinearFunction(ch.function_node.FunctionNode):\n",
" '''\n",
" FunctionNode object, defined on Variable objects,\n",
" which is the basis for a linear transformation to\n",
" be wrapped up as a Link object.\n",
" \n",
" Take d-dimensional inputs x, and using array W of\n",
" shape (k,d), map this input to k outputs. That is,\n",
" we have a fully-connected layer with d input units\n",
" and k output units.\n",
" '''\n",
" \n",
" def forward(self, inputs):\n",
" '''\n",
" Forward computation for both CPU and GPU.\n",
" '''\n",
" \n",
" # Unpack the tuple of inputs.\n",
" if len(inputs) == 3:\n",
" x, W, b = inputs\n",
" else:\n",
" (x, W), b = inputs, None\n",
"\n",
" y = x.dot(W.T).astype(x.dtype, copy=False)\n",
" \n",
" # Add a bias term, if relevant.\n",
" if b is not None:\n",
" y += b\n",
" \n",
" # Since backward() depends only on x and W,\n",
" # we need only retain these two.\n",
" self.retain_inputs((0,1))\n",
" \n",
" # Must return the output as a tuple.\n",
" return (y,)\n",
"\n",
" def backward(self, indices, grad_outputs):\n",
" '''\n",
" General-purpose computation for both CPU/GPU.\n",
" '''\n",
" \n",
" x, W = self.get_retained_inputs()\n",
" gy, = grad_outputs # written as gamma in their docs.\n",
" \n",
" # Says that backward() must return a tuple, but\n",
" # looking at their source code for linear.py, it\n",
" # seems like lists are fine.\n",
" out = []\n",
" if 0 in indices:\n",
" gx = gy @ W # gy.dot(W)\n",
" out.append(ch.functions.cast(gx, x.dtype))\n",
" if 1 in indices:\n",
" gW = gy.T @ x # gy.T.dot(x)\n",
" out.append(ch.functions.cast(gW, W.dtype))\n",
" if 2 in indices:\n",
" # Summing here is simple: for n observations,\n",
" # gy has shape (n,k), where k is the number of\n",
" # layer outputs. Summing over axis=0 is summing\n",
" # over OBSERVATIONS, not over outputs.\n",
" gb = ch.functions.sum(gy, axis=0)\n",
" \n",
" # Return just the relevant gradients we appended.\n",
" return out\n",
"\n",
"\n",
"def linear(x, W, b):\n",
" '''\n",
" A nice thin wrapper for our linear FunctionNode on\n",
" Variable objects.\n",
" '''\n",
" \n",
" if b is None:\n",
" args = (x, W)\n",
" else:\n",
" args = (x, W, b)\n",
" \n",
" # Don't forget to unpack from the tuple.\n",
" y, = LinearFunction().apply(args)\n",
" return y"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"`FunctionNode`の要点:\n",
"\n",
"- `forward()`はNumpyの配列だけで定義している(`Variable`でも良いが)。\n",
"\n",
"- `backward()`はサンプルの上で足しあわせていることに注意が必要。\n",
"\n",
"- さらに、`backward()`となると、`Variable`オブジェクトを前提とした実装にしなければならない(特別な演算記号`@`などがあるおは、そのためである)。\n",
"\n",
"次は、このノードに基づく`Link`オブジェクトを作る。"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [],
"source": [
"# Link object for our linear FunctionNode.\n",
"\n",
"class Linear(ch.Link):\n",
" '''\n",
" A Link class for our linear transformation, implemented\n",
" in the LinearFunction class.\n",
" '''\n",
" def __init__(self,\n",
" in_size, out_size,\n",
" init_W=None, init_b=None,\n",
" init_delta=None,\n",
" nobias=False):\n",
" super(Linear, self).__init__()\n",
" \n",
" # Here we initialize and \"register\" the parameters\n",
" # of interest. This is critical because when we\n",
" # call __call__(x) and apply the underlying affine\n",
" # transformations to input x (both forward pass and\n",
" # backward pass), the optimization algorithms knows\n",
" # that we want to optimize W and maybe b, but not x.\n",
"\n",
" with self.init_scope():\n",
" \n",
" # If provided an ndarray, use it.\n",
" if init_W is not None:\n",
" self.W = ch.Parameter(initializer=np.copy(init_W))\n",
" \n",
" # Else, use a built-in initializer.\n",
" else:\n",
" W_initializer = ch.initializers.Uniform(scale=init_delta,\n",
" dtype=np.float32)\n",
" self.W = ch.Parameter(initializer=W_initializer,\n",
" shape=(out_size, in_size))\n",
" \n",
" if nobias:\n",
" self.b = None\n",
" else:\n",
" if init_b is not None:\n",
" self.b = ch.Parameter(initializer=np.copy(init_b))\n",
" else:\n",
" self.b = ch.Parameter(initializer=0,\n",
" shape=(out_size,))\n",
" \n",
" def __call__(self, x):\n",
" '''\n",
" This method actually applies the linear layer to\n",
" inputs x.\n",
" '''\n",
" return linear(x, self.W, self.b)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"この`Link`の定義でもっとも重要なのは、学習すべきパラメータを登録していることである。その段取りとしては、`init_scope()`なるコンテキストマネジャーを使って、指定したパラメータを属性(attributes)として格納しておく。この`Link`は先ほどの`LinearFunction`に基づくものであり、`__call__()`によって呼び出される。\n",
"\n",
"上記で区別しているのは、データの`x`と、学習すべきパラメータの`W`および`b`である。いずれも計算する必要があるのだが、最適化の対象となるのは後者のみであるから、明確に区別することがきわめて重要である。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"最後に、`Chain`オブジェクトを先ほどの`Link`から造設していく。`Chain`の定義が`Link`の定義に酷似しているのは、`Chain`自体が`Link`でもあるからである。"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [],
"source": [
"# Chain object, composed of Link objects. This is a proper model in the\n",
"# sense that it can be fed to optimizers.\n",
"\n",
"class Chain_LinReg(ch.Chain):\n",
" '''\n",
" Perhaps the simplest possible model, a\n",
" feed-forward neural network without any\n",
" hidden layers. Just one, fully-connected\n",
" linear layer, aka a classical linear\n",
" regression model, with arbitrary number\n",
" of outputs.\n",
" \n",
" out_l0: number of outputs from layer 0.\n",
" out_l1: number of outputs from layer 1.\n",
" '''\n",
" \n",
" def __init__(self,\n",
" out_l0,\n",
" out_l1,\n",
" init_W=None,\n",
" init_b=None,\n",
" init_delta=1.0,\n",
" nobias=False):\n",
" super(Chain_LinReg, self).__init__()\n",
" \n",
" with self.init_scope():\n",
" self.l1 = Linear(in_size=out_l0,\n",
" out_size=out_l1,\n",
" init_W=init_W,\n",
" init_b=init_b,\n",
" init_delta=init_delta,\n",
" nobias=True)\n",
"\n",
" def __call__(self, x):\n",
" return self.l1(x) # parameters are managed by Links.\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"`Link`オブジェクトがパラメータを登録するのと同様に、`Chain`オブジェクトは\"child links\"を登録し、属性として格納する(ここもやはり`init_scope()`なるコンテキストマネジャーを使う)。\n",
"\n",
"我々が扱っている今回の具体例では、モデルが至ってシンプルなので、長さ`out_l0`のベクトルを入力として受け取り、たった1回の行列の掛け算を`Linear`で実行し、出力する。その実行結果の長さが`out_l1`である。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"我々としてもっとも重要なのは、勾配降下法などに際して、Chainerが予想通りに偏微分を計算してくれているかどうかである。丁寧にこれを検証するために、同一のデータセットに対して、自作の学習機とChainerによって作った学習機を両方試してみよう。"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [],
"source": [
"## Experiment setup.\n",
"\n",
"# Data-related.\n",
"data = dataclass.DataSet() # Initialize one data object; will be re-populated at each trial.\n",
"n = 500 # sample size\n",
"d = 2 # number of parameters\n",
"init_delta = 5.0 # controls support of random initialization\n",
"num_trials = 250 # number of independent random trials to conduct\n",
"cov_X = np.eye(d) # covariance matrix of the inputs.\n",
"\n",
"w_star = np.ones(d).reshape((d,1)) # vector specifying true model\n",
"\n",
"# Algorithm-related.\n",
"m_idx_todo = [0,1] # let's us manually pick and choose which methods to evaluate.\n",
"t_max = 30 # termination condition; maximum number of iterations.\n",
"thres = -1.0 # termination condition; if negative, runs for max iterations.\n",
"\n",
"def alpha_fixed(t, val): # step-size callback function.\n",
" return val\n",
"def make_step(u):\n",
" def mystep(t, model=None, data=None, newdir=None):\n",
" return alpha_fixed(t=t, val=u)\n",
" return mystep\n",
"alphaval = 0.25\n",
"\n",
"# Clerical.\n",
"mth_names = [\"gd\", \"gd-ch\"]\n",
"num_mths = len(mth_names)\n",
"mth_colours = [\"black\", \"blue\"]"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [],
"source": [
"# Make choice of additive noise distribution (un-comment your choice).\n",
"#paras = {\"name\": \"norm\", \"shift\": 0.0, \"scale\": 20.0}\n",
"paras = {\"name\": \"lnorm\", \"meanlog\": 0.0, \"sdlog\": 1.75}\n",
"\n",
"# Put together risk function.\n",
"def risk(w):\n",
" mean_noise, var_noise = hlp.noise_risk(paras=paras)\n",
" return hlp.riskMaker(w=w, A=cov_X, b=math.sqrt(var_noise), w_star=w_star)\n",
"risk_star = risk(w=w_star) # optimal risk value."
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [],
"source": [
"## Running the algorithms.\n",
"\n",
"# Prepare storage for performance metrics.\n",
"riskvals = np.zeros((num_trials,t_max,num_mths), dtype=np.float32)\n",
"loss_tr = np.zeros((num_trials,t_max,num_mths), dtype=np.float32)\n",
"truedist = np.zeros((num_trials,t_max,num_mths), dtype=np.float32)\n",
"\n",
"# Loop over trials.\n",
"for tri in range(num_trials):\n",
" \n",
" # Generate new data (with *centered* noise).\n",
" X = np.random.normal(loc=0.0, scale=1.0, size=(n,d))\n",
" noise = hlp.noise_data(n=n, paras=paras)\n",
" y = np.dot(X, w_star) + noise\n",
" data.init_tr(X=X, y=y)\n",
" \n",
" # Data for Chainer model.\n",
" Z = ch.datasets.TupleDataset(np.float32(X),\n",
" np.float32(y))\n",
" \n",
" # Initial weight settings.\n",
" w_init = w_star + np.random.uniform(low=-init_delta, high=init_delta, size=d).reshape((d,1))\n",
" w_init = np.float32(w_init)\n",
" \n",
" # Initialize models (hand-built).\n",
" mod_learner = models.LinearL2(data=data)\n",
" risk_star = risk(w=w_star) # optimal risk value.\n",
" loss_star = np.mean(mod_learner.l_tr(w=w_star, data=data))\n",
" \n",
" # Initialize models (Chainer-based).\n",
" mod_chainer = Chain_LinReg(out_l0=d,\n",
" out_l1=1,\n",
" init_W=w_init.T,\n",
" init_b=None,\n",
" init_delta=init_delta,\n",
" nobias=True)\n",
" \n",
" # Initialize algorithms (hand-built).\n",
" al_gd = algorithms.Algo_GD(w_init=w_init,\n",
" step=make_step(alphaval),\n",
" t_max=t_max,\n",
" thres=thres,\n",
" store=True,\n",
" lamreg=None)\n",
" \n",
" # Initialize algorithms (Chainer-based).\n",
" opt_chainer = ch.optimizers.SGD(lr=alphaval)\n",
" opt_chainer.setup(mod_chainer) # pass model!\n",
"\n",
" \n",
" # Run all algorithms and save their performance.\n",
" \n",
" ## ERM-GD.\n",
" mthidx = 0\n",
" if mthidx in m_idx_todo: \n",
" idx = 0\n",
" for onestep in al_gd:\n",
" al_gd.update(model=mod_learner, data=data)\n",
" # Record performance\n",
" loss_tr[tri,idx,mthidx] = np.mean(mod_learner.l_tr(w=al_gd.w, data=data))-loss_star\n",
" riskvals[tri,idx,mthidx] = risk(w=al_gd.w)-risk_star\n",
" truedist[tri,idx,mthidx] = np.linalg.norm(w_star-al_gd.w)-0\n",
" idx += 1\n",
" \n",
" \n",
" ## Replication of ERM using Chainer.\n",
" mthidx = 1\n",
" if mthidx in m_idx_todo:\n",
" idx = 0\n",
" iter_train = ch.iterators.SerialIterator(dataset=Z,\n",
" batch_size=n, # thus SGD=GD; deterministic.\n",
" repeat=True,\n",
" shuffle=False)\n",
" while iter_train.epoch < t_max:\n",
" \n",
" # Get our mini-batch.\n",
" Z_batch = iter_train.next()\n",
" X_batch, y_batch = ch.dataset.concat_examples(Z_batch)\n",
"\n",
" # Predictions.\n",
" prediction_tr = mod_chainer(X_batch)\n",
"\n",
" # Loss computations (will feed the grad computations).\n",
" loss = ch.functions.mean_squared_error(prediction_tr, y_batch) / 2.0\n",
" #old_loss = np.mean(mod_learner.l_tr(w=mod_chainer.l1.W.data.T, data=data))\n",
" #print(\"old versus new:\")\n",
" #print(loss, old_loss)\n",
" loss_star = np.mean(mod_learner.l_tr(w=w_star, data=data))\n",
" \n",
" # Gradient computations.\n",
" mod_chainer.cleargrads()\n",
" loss.grad = np.ones(loss.data.shape, dtype=np.float32)\n",
" loss.backward()\n",
"\n",
" # Parameter updates.\n",
" opt_chainer.update()\n",
"\n",
" # Record performance\n",
" loss_tr[tri,idx,mthidx] = np.mean(mod_learner.l_tr(w=mod_chainer.l1.W.data.T, data=data))-loss_star\n",
" riskvals[tri,idx,mthidx] = risk(w=mod_chainer.l1.W.data.T)-risk_star\n",
" truedist[tri,idx,mthidx] = np.linalg.norm(w_star-mod_chainer.l1.W.data.T)-0\n",
" idx += 1\n",
"\n",
"\n",
"# Finally, take statistics of the performance metrics over all trials.\n",
"ave_loss_tr = np.mean(loss_tr, axis=0)\n",
"ave_riskvals = np.mean(riskvals, axis=0)\n",
"ave_truedist = np.mean(truedist, axis=0)\n",
"sd_loss_tr = np.std(loss_tr, axis=0)\n",
"sd_riskvals = np.std(riskvals, axis=0)\n",
"sd_truedist = np.std(truedist, axis=0)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"要点:\n",
"\n",
"- `loss.grads`を手動で初期化していないことは、微分の対象となるものがスカラーだからである(先述)。\n",
"\n",
"- 反復的に更新しているが、複数ステージにわたって勾配情報が加算されていくと誤った計算結果につながるため、必ず`cleargrads()`を実行すること。これは`mod_chainer`と呼んでいる`Chain`のメソッドである。\n",
"\n",
"- 今回使っている`Optimizer`オブジェクト(`opt_chainer`)がパラメータの更新をChainer側でさばいてくれている。学習したい`Parameter`はすべて`mod_chainer`で登録していること、また`mod_chainer`が`opt_chainer`に渡されていることなどを踏まえると、最適化担当はしかるべき情報をもらっていることがわかる。"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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\n",
"text/plain": [
"