Welcome to BinaryBrain's documentation!¶

本書は BinaryBrain Ver4: https://github.com/ryuz/BinaryBrain/tree/ver4_release のドキュメントです。

はじめに¶

概要¶

特徴¶

BinaryBrain は主に当サイトが研究中の LUT(Look-Up Table)-Networkを実験することを目的に作成したディープラーニング用のプラットフォームです。

LUT-Networkの評価を目的に作成しておりますが、それ以外の用途にも利用可能です。

以下の特徴があります

ニューラルネットのFPGA化をメインターゲットにしている
バイナリネットであるも関わらず変調技術によりAutoencodeや回帰分析が可能
独自のDifferentiable-LUTモデルにより、LUTの性能を最大限引き出したが学習できる
量子化＆疎行列のネットワークでパフォーマンスの良い学習が出来る環境を目指している
C++で記述されている
GPU(CUDA)に対応している
高速でマニアックな自作レイヤーが作りやすい
Pythonからの利用も可能

基本的な使い方¶

基本的には C++ や Python で、ネットワークを記述し、学習を行った後にその結果を verilog などに埋め込んで、FPGA化することを目的に作成しています。

C++用のCPU版に関してはヘッダオンリーライブラリとなっているため、include 以下にあるヘッダファイルをインクルードするだけでご利用いただけます。

GPUを使う場合は、ヘッダ読み込みの際に BB_WITH_CUDA マクロを定義した上で、cuda 以下にあるライブラリをビルドした上でリンクする必要があります。

また、BB_WITH_CEREAL マクロを定義すると、途中経過の保存形式に json が利用可能となります。

Python版を使う場合は、一旦ビルドに成功すれば import するだけで利用可能です。

使い方はsamplesなどを参考にしてください。

事例紹介¶

リアルタイム認識¶

実装事例¶

フルバイナリネットワークで、遅延数ミリ秒(1000fps)での画像認識の例です。

下記のようなブロック図となっています。

FPGAリソース¶

いくつかの認識について実験したものを以下に示します。

下記はカメラやOLEDなどの制御回路も含んだものもありますが、例えば MNIST の Simple DNN であればニューラルネット部分はわずか 1460個のLUTのみで88％の認識が可能です。これは、今手に入るXILINXのもっとも小さなFPGAでも十分収まるサイズです。

これは 1024-360-60-10 の4層構造のネットワークであり、例えば200MHzで動かした場合、 4サイクル(=20ナノ秒)で認識が完了します。そのため極めてリアルタイム性の高い用途への応用も可能です。

もしカメラなどの入力に制約がなく、28x28の画像を毎サイクル供給可能であれば、コア自体は 200Mfpsで動作可能となります。これは1つの対象に対して条件を変えながら非常に多くの認識を行える帯域ですので、 1回の認識率は低くても、結果を二次加工することで実用的な認識率を目指すようなことも可能な帯域です。

Autoencoder¶

通常のバイナリネットワークは出力もバイナリであるため、例えばAutoencoderのような多値出力が必要な用途には応用が難しいという課題があります。 (入力に関しては最初の数層を多値で扱う手はあります)

BinaryBrainでは、バイナリ変調を用いることで、入力から出力まで全層がバイナリである Fully binary neural network で多値データを扱う方法を提供しています。

MNIST¶

MNISTでの Autoencoder の実験結果です。

MNIST画像自体が2値に近いのですが、輪郭付近でやや滑らかさが出ています。

CIFAR-10¶

同様にCIFAR-10のデータセットで扱ったものです。

ぼやけた感じは否めませんが、多値出力に対してある程度のことができているのは確認できます。

もともとがCIFAR-10のデータセット自体が Autoencoder のような学習を目的としたデータセットではないので、多値の従来ネットワークでもかなりボケた画像しか作れない部分はあるので、まずは実験的な結果と言えます。

LUT-Network とは¶

概要¶

LUT-Networkとは、当サイトの提唱するパーセプトロンモデルの代わりにLUT(ルックアップテーブル)のモデルを利用したディープニューラルネットワークのことです。重みの乗算の代わりにテーブル引きを行うことで、パーセプトロンでは学習することのできない XORパターンのようなものも柔軟に学習することができます。乗算を用いない為、低スペックな計算環境でも高速に推論を行うことが可能です。

特にこれをバイナリ化した Binary LUT-Network は、FPGAのLUTに直接変換可能であるため、極めて高い演算機高率を実現できます。

また以下のバイナリ化の欠点をバイナリ変調技術で克服する方法も提供しています

ネットワーク部分は入力初段からフルバイナリネットワークを実現可能で高効率
出力を多値に戻せるため、回帰分析やAutoEncoderなどのアプリケーションにも適用可能
FPGAだと１レイヤーの計算が1サイクルで終わるのでナノ秒クラスで認識できる（高リアルタイム性）
超廉価＆低消費電力なワンコインFPGAから適用が可能

高価な乗算機アレイが不要となるので、特に電力やリアルタイム性、コストなどが課題となるエッジコンピューティング分野にちょっとした認識を実現するなどに適したネットワークです。

Differentiable-LUT モデル¶

LUTによるテーブル参照を誤差逆伝搬で学習させているというと、奇妙に感じられるかもしれません。一般にデジタル回路はANDやORなどの組み合わせ回路で実現されますので、そのままではこれを微分して逆伝搬することはできません。しかしながら機械学習で扱う値は多くの場合は尤度であって、一定の条件下でデジタル回路はStoachstic演算に置き換えても機能します。ここに着想を得て、FPGAのLUT回路を微分して、テーブル内を学習可能な構成を得たうえで、さらになるべく広い条件で利用できるように工夫を要れたものが本モデルとなります。

Stochastic-LUT 演算¶

その計算モデルは、LUTのテーブル引きの回路演算を Stoachstic演算に置き換えて実験しているときに発見されました。 Stochastic-LUTモデルは Differentiable-LUT モデルの中にその一部として含まれています。

Stochastic演算とは、確率的な0/1が入力される回路におけるデジタル演算において、その確率値に対して乗算などの演算子として機能する点に着目したものです。例えばANDゲートは確率値に対しては乗算器として機能します。

後述しますが、BinaryBrainでは任意のフルバイナリネットワークに対して、バイナリ変調を施したデータを入出力させながら学習させる機能があり、このバイナリ変調が Stochastic演算を用いたモデルを有効に機能させるのに役立たせることができます。。

さて、早速ですがLUTも回路的には単なるマルチプレクサですので、一度デジタル回路として考えた後に、 Stoachstic演算に置き換えて考えることで下記のように微分可能な計算で表すことができます。

Wは各ルックアップテーブル内の値に対応し、テーブル内の値が1である確率を表します。 xは入力値が1である確率値であり、yは出力が1となる確率値です。

このモデルを使った学習は、入力同士に相関がなく、純粋に確率値として扱える範疇において、正しく機能し、出力値が一定の確率で1を出力するようにネットワーク全体を学習させることが可能です。

内部に備えたWの後にあるBinaeizerをONにして学習すれば、学習完了後にテーブル値はバイナリに置換することができます。

Differentiable-LUTモデルの全体像¶

Stochastic-LUTの計算モデルを活用し、Stochastic性を持たないデータも視野に入れて広く学習可能にするための疎結合ルックアップテーブル方式のモデルとして、Differentiable-LUTモデルを提唱しています。

BinaryBrain の備える DifferentiableLUT クラスは下記の３つの使い方に対応しています。

Stochastic 値を扱うネットワークを学習可能
非バイナリ(FP32など)の疎結合ネットワークで従来のパーセプトロンよりも高性能に機能
バイナリ疎結合ネットワークでLUTに置換可能なモデルとして学習可能

Differentiable-LUTモデルによるFPGA化¶

Differentiable-LUT を、Stochastic演算用や、Fully-Binary 用に利用した場合には、FPGAに 1個に割り当て可能なモデルとして学習させることができます。

特にFully-Binary 用に利用しする場合が広く汎用的に応用可能であり、下記のようなモデルになります。

バイナリ変調¶

概要¶

本章ではバイナリLUT-Networkに限らず、広くバイナリネットワークに適用可能な技術として、バイナリ変調の適用について述べます。バイナリ変調とフルバイナリネットワークの組み合わせは、本サイトの提唱する技術の１つであり、入出力のに多値データが要求される場合にバイナリネットワークを適用するための手法です。

従来のバイナリネットワーク¶

従来のバイナリネットワークでは、多値画像の認識などを行うために、入力側のいくつかの層をバイナライズせずに多値入力とすることで多値データを扱っていました。この方法は一定の効果はあるものの、入力層では乗算器を必要とする為リソースが大きく増加する上に、出力はバイナリであり、クラスタ分類ぐらいにしか応用できないという課題がありました。

バイナリ変調¶

信号処理の世界にはバイナリ変調という技術があります。例えばデジタルオーディオなどの分野では 1bit ADC やD級アンプの技術は非常に重要です。こでは信号をオーバーサンプリングにより、高い周波数の 1bit のデータに量子化することで、信号処理自体はバイナリで扱うにもかかわらず、入出力データには例えば16bit以上の高品質の信号を得る技術です。

もっとも簡単な方法はアナログ値を乱数閾値でバイナリ化することです。結果は元のアナログ値に応じた確率で1と0が生成されますので、扱いたい値がそのまま Stochastic演算の対象となります。しかしながら確率的な振る舞いはデータ数が充分多い時に顕在化してきますので信号オーバーサンプリングは重要な技法となってきます。

BinaryBrain では同様の変調を元データに施してデータを水増しすることで、非常に小さな回路の認識率を上げたり、Autoencoderや回帰分析などの多値出力を必要とする分野への適用可能性を広げました。

下記は、通常の Dense CNN の ReLU を Binarizer に置き換え、入力もバイナリ化してフルバイナリネットワーク化したものを用いて、バイナリ変調の効果を実験した結果です。

binary_x1 が1倍のオーバーサンプル、すなわち何もせずに単純にフルバイナリ化した場合ですが、 FP32での結果に比べて大きく認識率が落ち込みます。そして、binary_x3、binary_x7, binary_x15, binary_x31 が、それぞれ3倍、7倍、15倍、31倍のオーバーサンプリングでのバイナリ変調を行ったものですが、ある程度の回復を見せている事がうかがえます。

同じ回路に、より高いフレームレートで、変調したデータを通すだけなので、スループットは低下しますが、ネットワークを構成する回路自体のリソースは一切変化することなく、認識率だけが向上しているのが特徴です。

クイックスタート(C++)¶

まずはじめに付属のMNISTサンプルを動かすまでを紹介します。

AXV2以降の命令が使えるCPUと、Windows7以降もしくは Linuxの環境を想定しております。 CUDAにも対応していまが、nvccが利用可能な環境でビルドする必要があります。

CUDAについてはNVIDIAのページを参考に事前にインストールください。 https://developer.nvidia.com/cuda-downloads

なお make 時に make WITH_CUDA=No と指定することで、GPUを使わないCPU版もビルド可能です。

Windows¶

install VisualStudio 2019 + CUDA 11.3
git clone --recursive -b ver4_release https://github.com/ryuz/BinaryBrain.git
download MNIST from http://yann.lecun.com/exdb/mnist/
decompress MNIST for "samplescppmnist"
open VC++ solution "samplescppmnistsample_mnist.sln"
build "x64 Release"
run

Linux(Ubuntu 20.04)¶

1. install tools¶

% sudo apt update
% sudo apt upgrade
% sudo apt install git
% sudo apt install make
% sudo apt install g++
% wget https://developer.download.nvidia.com/compute/cuda/11.3.1/local_installers/cuda_11.3.1_465.19.01_linux.run
% sudo sh cuda_11.3.1_465.19.01_linux.run

2. build and run¶

% git clone --recursive -b ver4_release  https://github.com/ryuz/BinaryBrain.git
% cd BinaryBrain/samples/cpp/mnist
% make
% make dl_data
% ./sample-mnist All

ここで単に

% ./sample-mnist

と打ち込むと、使い方が表示されます。

Google Colaboratory¶

nvcc が利用可能な Google Colaboratory でも動作可能なようです。以下あくまで参考ですが、ランタイムのタイプをGPUに設定した上で、下記のような操作で、ビルドして動作させることができます。

!git clone --recursive -b ver4_release  https://github.com/ryuz/BinaryBrain.git
%cd BinaryBrain/samples/cpp/mnist
!make all
!make run

クイックスタート(Python)¶

BinaryBrain は pybind11 を利用して Python からの呼び出しも可能にしています。 python3を前提としています。

pipでのインストール¶

下記のコマンドでインストール可能(になる予定)です。

% pip3 install binarybrain

Google Colaboratory からも

!pip install binarybrain

とすることでインストール可能です。

BinaryBrainは python3 専用です。Python2 との共存環境の場合など必要に応じて pip3 を実行ください。そうでなければ pip に読み替えてください。インストール時にソースファイルがビルドされますので、コンパイラやCUDAなどの環境は事前に整えておく必要があります。

(Windows版はバイナリwheelが提供されるかもしれません。作者環境は ver4.0.1 現在、Python 3.7.4(Windows10)、Python 3.6.9(Ubuntu 18) です)

Python用のサンプルプログラムは下記などを参照ください。

https://github.com/ryuz/BinaryBrain/tree/ver4_release/samples/python

（ipynb 形式ですので、Jupyter Notebook、Jupyter Lab、VS code、PyCharm、GoogleColab など、読める環境を準備ください。）

setup.py でのインストール¶

pip でのインストールがうまくいかない場合や、github上の最新版を試したい場合などは setup.py でのインストールも可能です。

事前準備¶

Python版は各種データセットに PyTorch を利用しています。事前にインストールください。

またその他必要なパッケージを事前にインストールください。pybind11 などが必須です。

% pip3 install setuptools
% pip3 install pybind11
% pip3 install numpy
% pip3 install tqdm

Windows環境の場合、nvccのほかにも VisualStudio の 64bit 版がコマンドラインから利用できるようにしておく必要があります。例えば以下のように実行しておきます。 x64 の指定が重要です。

> "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x64

インストール(pipを使う場合)¶

下記のコマンドでインストール可能です。

% pip install binarybrain

インストール(setup.pyを使う場合)¶

下記のコマンドでインストール可能です。

% # install
% cd python
% python3 setup.py install

サンプルの実行¶

コマンドラインから以下のサンプルを試すことができます。

% cd samples/python/mnist

% # Simple DNN sample
% python3 MnistDifferentiableLutSimple.py

% # CNN sample
% python3 MnistDifferentiableLutCnn.py

その他のサンプルは ipynb 形式で samples/python フォルダの中にあるので Jupyter Notebook などで参照ください。

Google Colaboratory での setup.py¶

Google Colaboratory で利用する場合は、ランタイムのタイプを「GPU」にして、下記を実行した後にランタイムの再起動を行えば利用できるようになるはずです。

!pip install pybind11
!git clone -b ver4_release  https://github.com/ryuz/BinaryBrain.git
%cd BinaryBrain
!python3 setup.py install --user

クイックスタート(Verilog)¶

RTL Simulation の試し方¶

C++, Pythonともに Verilog RTL のソースファイルの出力が可能です。出力したRTLの試し方は

https://github.com/ryuz/BinaryBrain/blob/ver4_release/samples/verilog/mnist/README.md

のなどをご参照ください。

C++ API¶

概要¶

本章ではC++のAPIについて触れます。

現時点では細かなドキュメントが用意できておらず、ソースを読み人のために概要を掴む為の情報を記載します。

なお BinaryBrain のコードは namespace に bb という名称を持ちます。

モデルクラス¶

基本クラス¶

すべてのレイヤーはModelクラスからの派生で生成されます。

Model(抽象クラス)¶

抽象クラスは直接生成できませんが、各レイヤーの基礎となっており、操作を定義します。以下のようなメソッドを備えます。

SendCommand(): 文字列によって汎用的に各レイヤーの属性変更などを行えます。階層的にサブレイヤーに伝播させることを目的としておりますが、送信先クラス名を指定することで、特定のレイヤにのみコマンドを送ることも出来ます。現在の主な用途として "binary true" のようなコマンドで、バイナリ活性層を有効にしたり、 "host_only" コマンドで、部分的に動作をCPU版に切り替えたりできます。将来的には、部分的に学習時のパラメータ学習を固定したりなど、いろいろな設定を追加していくことを考えています。文字列なので、自作レイヤーに独自コマンドを追加することも簡単です。
GetClassName(): クラス名を取得します。SendCommand() で、コマンド送付先をクラス名で指定することが出来ます。
SetName(): クラス名とは別にインスタンス個別に自由に名前設定が出来ます。生成時に固有の名前をつけておけば、後から SendCommand() で、個別に属性変更コマンドが送れます。
GetParameters(): 内部パラメータの参照を取得します。重み係数などが取得対象です。内部パラメータを持った自作レイヤーを作成する場合に実装が必要になります。
GetGradients(): 内部パラメータの勾配への参照を取得します。Backward時に値が計算され、主に Optimizer が利用します。内部パラメータを持った自作レイヤーを作成する場合に実装が必要になります。
SetInputShape(): 入力のデータ形状を指定します。戻り値は出力のデータ形状となります。階層的にサブレイヤーに伝播させることを目的としており、各レイヤーを連結後に呼びさすことで内部パラメータのサイズが決定され初期化されます。自作レイヤーを作成する場合には必ず実装が必要になります。
Forward(): 前方伝播を行います。階層的にサブレイヤーも実行することを想定しています。自作レイヤーを作成する場合には必ず実装が必要になります。
Backward(): 誤差逆伝播を行います。階層的にサブレイヤーも実行することを想定しています。自作レイヤーを作成する場合には必ず実装が必要になります。
PrintInfo(): レイヤーの情報を表示します。自作レイヤーを作成する場合に実装しておけば独自の情報を出力できます。

活性化層¶

Binarize クラス¶

バイナライズ層です。 Forward では、0を閾値に出力を0と1に二値化します。 Backward では hard-tanh として動作します。バイナリネットワークの基礎となります。

ReLU クラス¶

普通のReLU です。 Binarize から派生しており、SendCommand() にて、"binary true" を送ることでBinarize層として動作します。

Sigmoid クラス¶

普通のSigmoid です。 Binarize から派生しており、SendCommand() にて、"binary true" を送ることでBinarize層として動作します。

演算層¶

StochasticLutN クラス¶

LUT-Network の LUT に相当する部分をStochasticモデルに基づいて学習させるためのレイヤーです。 Stochastic計算に基づいてFPGAのLUTロジックを微分可能記述に直して、テーブル内容の逆伝搬学習を可能としています。 StochasticバイナリデータがStochastic性を持っている対象への学習に限定されますが、 DifferentiableLutN モデルよりも高速に学習させることが可能です。

このモデルは１層でXORパターンを含めたLUTで表現可能な空間すべてを学習可能です。

DifferentiableLutN クラス¶

LUT-Network の LUT に相当する部分を独自のモデルで学習させるためのレイヤーです。 StochasticLutN クラスにさらに BatchNormalization と hard-tanh によるバイナリ化を統合しています。 Stochastic性を持たない一般的なデータに対してバイナリネットワークとしての学習能力を持ちます。

このモデルも StochasticLutN 同様に1層でXORパターンを含めたLUTで表現可能な空間すべてを学習可能です。

一方で１つのノードの接続数がFPGA同様に6個などに限定されるため、疎結合網となり、ネットワークの構築には工夫が必要です。

MicroMlpAffine クラス¶

MicroMlp の構成要素で、入力数を6などに限定した疎結合、且つ、内部に隠れ層を備えた小さなMLP(Multi Layer Perceptron)の集合体です。入力数や隠れ層の数テンプレート引数で変更可能です。

MicroMlp クラス¶

LUT-Network の LUT に相当する部分をパーセプトロンを用いて学習させるレイヤーです。内部は MicroMlpAffine + BatchNormalization + 活性化層の３層で構成されます。活性化層はデフォルトは ReLU ですが、テンプレート引数で変更可能です。

DenseAffine クラス¶

いわゆる普通の浮動小数点による全結合のニューラルネットです。

BatchNormalization クラス¶

BatchNormalization層です。活性化層でバイナリ化を行う前段ほぼ必須となってくる層です。

MaxPooling クラス¶

MaxPooling層です。

LutLayer (抽象クラス)¶

LUT-Network を記述する基本モデルです。現在 ver2 の直接学習機能はまだ ver3 には未実装です。 MicroMlp などで逆伝播で学習した内容をテーブル化して写し取ることを目的としています。テーブル化取り込みに ImportLayer() メソッドを備えます。

BinaryLutN クラス¶

各ノードの入力数を１つに固定したLUTモデルです。一般的なFPGAに適合します。入力数はテンプレート引数で指定でき、FPGAでは 4 か 6 のものが一般的と思われます。入力数を固定することで演算を高速化できますが、ver3 への移植はまだ行えていません。

補助層¶

Sequential クラス¶

各種の層を直列に接続して１つの層として扱えるようにします。

Convolution2d クラス¶

Lowering を行い畳こみ演算を行います。

ConvolutionIm2Col + 引数で渡したモデル + ConvolutionCol2Im DenseAffine を渡すと、通常のCNNになり、MicroMlp を用いたサブネットワークを渡すことで、

LUT-Network での畳込みが可能です。

ConvolutionIm2 クラス¶

畳み込みの為のLoweringを行います。通常、 Convolution2d クラスの中で利用されます。 Loweringされたデータに対して BatchNormalization するのも LUT-Network 学習時の特徴の一つかもしれません。

ConvolutionCol2Im クラス¶

畳み込みの為のLoweringの復元を行います。通常、 Convolution2d クラスの中で利用されます。

BinaryModulation クラス¶

内部でRealToBinary クラスとBinaryToRealクラスを組み合わせて、多値データをバイナリ化して学習するのに利用できます。

RealToBinary クラス¶

実数値をバイナライズします。その際にframe方向に拡張して変調を掛ける(多重化)が可能です。現在、PWM変調と、乱数での変調を実装しており、デフォルトでPWM変調となります(将来⊿Σなどの誤差蓄積機能も検討中です)。変調を行うことで、入力値に対して確率的な0/1比率の値を生成できるため、出力も確率的なものとなります。

BinaryToReal クラス¶

多重化された確率的な0と1をカウンティングして実数値を生成します。 RealToBinary 対応しますが、こちらは時間方向だけでなく、空間方向のカウントも可能です。オーバーサンプリングによる十分な多重化数が確保できれば、回路規模を増加させること無く回帰などの実数値へのフィッティング可能性が出てきます。

モデル以外のクラス¶

損失関数¶

LossSoftmaxCrossEntropy クラス¶

普通のSoftmax-CrossEntropyクラスです。

"¶

平均二乗誤差を損失とするクラスです。

評価関数¶

MetricsCategoricalAccuracy クラス¶

Categorical Classification の精度を評価値とするクラスです。

MetricsMeanSquaredError クラス¶

MSE(平均二乗誤差)を評価値とするクラスです。

最適化(Optimizer)¶

OptimizerSgd クラス¶

普通のSGDです。

OptimizerAdam クラス¶

普通のAdamです。

実行補助¶

Runner クラス¶

構築したモデルのフィッティングや評価などの実行を補助します。論よりRUN。 Runner のソースが各種の使い方で、参考になるはずです。

データ保持¶

Tensor クラス¶

多次元のデータを保持できるクラスで、演算も可能です。名前に反してまだ Tensor演算は実装できていません。

Variables クラス¶

複数の Tensor を束ねる機能を持ったクラスです。形状が同じなら Variables 間での演算も可能です。主にOptimizerでの利用を想定しています。

FrameBuffer クラス¶

１つの Tensor を 1 frame として、複数frame を保持できるクラスです。ただし、内部では、NCHW や NHWC ではなく、CHWN 形式になるように並び替えてデータを保持しています。これは Lowering されて frame数が十分増やされた疎行列に特化して性能を出すための配置で、BinaryBrainの特徴の一つです。一方で、一般的な算術ライブラリに適合しない(並び替えが必要)ので注意が必要です。

各種関数¶

FPGAへのエクスポート¶

ExportVerilog_LutLayers 関数¶

LutLayer を Verilog-RTL で出力します。

ExportVerilog_LutCnnLayersAxi4s 関数¶

畳み込み層を含む LutLayer を纏めて Verilog-RTL で出力します。 MaxPoolingなどの入出力でデータが不連続になる層は最後に1つだけ指定することができます。

Python API¶

概要¶

Python版モジュールは binarybarin パッケージを import することで利用可能です。

binarybarin パッケージ¶

binarybarin には以下のモジュールが含まれています。

基本クラス¶

Object クラス¶

class binarybrain.object.Object(core_object=None)¶

ベースクラス: object

各クラスの基底クラス

本クラスから派生する各種のクラスにはシリアライズの機能がサポートされる

dumps() → bytes¶

バイトデータにシリアライズ

モデルのデータをシリアライズして保存するためのバイト配列を生成

戻り値: Serialize data
戻り値の型: data (bytes)

loads(data: bytes) → bytes¶

バイトデータをロード

モデルのデータをシリアライズして復帰のバイト配列ロード

パラメータ: data (bytes) -- Serialize data

dump(filename: str)¶

ファイルに保存

モデルのデータをシリアライズしてファイルに保存

パラメータ: filename (str) -- ファイル名

load(filename: str)¶

ファイルからロード

ファイルからロード

パラメータ: filename (str) -- ファイル名

データ格納¶

DType クラス(Enum定義)¶

class binarybrain.dtype.DType(value)¶

ベースクラス: IntEnum

データ型定義

BINARY = 2¶

BIT = 1¶

FP16 = 272¶

FP32 = 288¶

FP64 = 320¶

INT16 = 528¶

INT32 = 544¶

INT64 = 576¶

INT8 = 520¶

UINT16 = 784¶

UINT32 = 800¶

UINT64 = 832¶

UINT8 = 776¶

Tensor クラス¶

class binarybrain.tensor.Tensor(shape: Optional[List[int]] = None, *, dtype=DType.FP32, host_only=False, core_tensor=None)¶

ベースクラス: Object

Tensor class

多次元データ構造。

パラメータ

shape (list[int]) -- Shape of created array
dtype (int) -- Data type
host_only (bool) -- flag of host only

static from_numpy(ndarray: ndarray, host_only=False)¶

NumPy から生成

パラメータ

ndarray (ndarray) -- array of NumPy
host_only (bool) -- flag of host only

get_shape() → List[int]¶

データのシェイプ取得

戻り値: shape

get_type() → int¶

データ型取得

戻り値: data type.

numpy() → ndarray¶

NumPy の ndarray に変換

戻り値: ndarray (array)

FrameBuffer クラス¶

class binarybrain.frame_buffer.FrameBuffer(frame_size: int = 0, shape: List[int] = [], dtype=DType.FP32, host_only: bool = False, core_buf=None)¶

ベースクラス: Object

FrameBuffer class

BinaryBrainでの学習データを格納する特別な型であるバッチと対応する 1次元のframe項と、各レイヤーの入出力ノードに対応する多次元のnode項を有している numpy の ndarray に変換する際は axis=0 が frame 項となり、以降が node項となる

Tensor と異なり、frame 項に対して reshape を行うことはできず、 node 項に対しても transpose することはできない。

node に関しては 2次元以上の shape も持ちうるが、実際のレイヤー間接続に際しては、畳み込みなどの次元に意味を持つノード以外では、ノード数さえあっていれば接続できるものが殆どである(多くの処理系で必要とする flatten が省略できる)。

host_only フラグを指定すると device(GPU側) が利用可能であっても host(CPU側) のみにメモリを確保する

パラメータ

frame_size (int) -- frame サイズ
shape (list[int]) -- node シェイプ
dtype (int) -- Data type
host_only (bool) -- flag of host only

static from_numpy(ndarray: ndarray, host_only=False)¶

Create from NumPy

パラメータ

ndarray (np.ndarray) -- array of NumPy
host_only (bool) -- flag of host only

get_frame_size() → int¶

get size of frame.

戻り値: frame size.

get_frame_stride() → int¶

get stride of frame.

戻り値: frame stride.

get_node_shape() → List[int]¶

get shape of node.

戻り値: shape

get_node_size() → int¶

get size of node.

戻り値: node size.

get_type() → int¶

データ型取得

戻り値: dtype (DType)

numpy() → ndarray¶

Convert to NumPy

パラメータ

shape (list[int]) -- Shape of created array
dtype (int) -- Data type
host_only (bool) -- flag of host only

Variables クラス¶

class binarybrain.variables.Variables¶

ベースクラス: object

Variables class

学習の為の Optimizer と実際の学習ターゲットの変数の橋渡しに利用されるクラス。内部的には各モデル内の重みや勾配を保有する Tensor をまとめて保持している。

append(variables)¶

変数を追加

パラメータ: variables (Variables) -- 追加する変数

基本モデル (Base models)¶

models モジュールには、ネットワークを構成するための各種演算モデルがあります。

Model クラス¶

class binarybrain.models.Model(*, core_model=None, input_shape=None, name=None)¶

ベースクラス: Object

Model class ネットワーク各層の演算モデルの基底クラスすべてのモデルはこのクラスを基本クラスに持つ

BinaryBrain では、モデルを実際にインスタンスとして生成して組み合わせることで学習ネットワークを構成する。特にネットワーク内のインスタンス化されたモデルをレイヤーという呼び方をする場合がある。

set_name(name: str)¶

インスタンス名の設定

生成したモデルには任意の名前を付けることが可能であり、表示や保存時のファイル名などに利用することが可能である

パラメータ: name (str) -- 新しいインスタンス名

get_name()¶

インスタンス名の取得

インスタンス名を取得する。名称が設定されていない場合はクラス名が返される

戻り値: name (str)

is_named()¶

インスタンス名の設定確認

インスタンス名が設定されているかどうか確認する

戻り値: named (bool)

get_model_name()¶

モデル名の取得

モデル名を取得する。

戻り値: model name (str)

get_info(depth: int = 0, *, columns: int = 70, nest: int = 0) → str¶

モデル情報取得

モデルの情報表示用の文字列を取得するそのまま表示やログに利用することを想定している

戻り値: info (str)

print_info(depth: int = 0)¶

モデル情報表示

モデルの情報を表示する

send_command(command, send_to='all')¶

コマンドの送信

モデルごとにコマンド文字列で設定を行うコマンド文字列の定義はモデルごとに自由である Sequentialクラスなどは、保有する下位のモデルに再帰的にコマンドを伝搬させるので、複数の層に一括した設定が可能である受取先は send_to で送り先はインスタンス名やクラス名で制限でき 'all' を指定するとフィルタリングされない

パラメータ

command (str) -- コマンド文字列
send_to (str) -- 送信先

set_input_shape(input_shape)¶

入力シェイプ設定

BinaryBarainではモデル生成時に入力のシェイプを決定する必要はなくネットワーク構築後に、ネットワークを構成する各モデルの set_input_shape を順に呼び出して形状を伝搬させることで各モデルの形状の設定を簡易化できる

set_input_shape が呼ばれるとそれまでの各層で保有する情報は保証されない。ネットワーク構築後に一度だけ呼び出すことを想定している

パラメータ: input_shape (List[int]) -- 入力シェイプ
戻り値: 出力シェイプ
戻り値の型: output_shape (List[int])

get_input_shape() → List[int]¶

入力シェイプ取得

戻り値: 入力シェイプ
戻り値の型: input_shape (List[int])

get_output_shape() → List[int]¶

出力シェイプ取得

戻り値: 出力シェイプ
戻り値の型: output_shape (List[int])

get_parameters()¶

パラメータ変数取得

学習対象とするパラメータ群を Variables として返す主に最適化(Optimizer)に渡すことを目的としている

モデル側を自作する際には、このメソッドで戻す変数の中に含めなかったパラメータは学習対象から外すことができる為パラメータを凍結したい場合などに利用できる

戻り値: パラメータ変数
戻り値の型: parameters (Variables)

get_gradients()¶

勾配変数取得

get_parameters と対になる勾配変数を Variables として返す主に最適化(Optimizer)に渡すことを目的としている

戻り値: 勾配変数
戻り値の型: gradients (Variables)

forward(x_buf, train=True)¶

Forward

モデルは学習および推論の為に forward メソッドを持つ
train 変数を

パラメータ

x_buf (FrameBuffer) -- 入力データ
train (bool) -- Trueで学習、Falseで推論

戻り値

出力データ

戻り値の型

y_buf (FrameBuffer)

backward(dy_buf)¶

Backward

モデルは学習の為に backword メソッドを持つ必ず forwad と対で呼び出す必要があり、直前の forward 結果に対する勾配計算を行いながら逆伝搬する

BinaryBrain は自動微分の機能を備えないので、backword の実装は必須である

パラメータ: dy_buf (FrameBuffer) -- 入力データ
戻り値: 出力データ
戻り値の型: dx_buf (FrameBuffer)

Sequential クラス¶

class binarybrain.models.Sequential(model_list=None, *, input_shape=None, name=None)¶

ベースクラス: Model

Sequential class

複数レイヤーを直列に接続してグルーピングするクラス

リストの順番で set_input_shape, forward, backward などを実行するまた send_command の子レイヤーへのブロードキャストや、 get_parameters, get_gradients の統合を行うことで複数のレイヤーを１つのレイヤーとして操作できる

パラメータ: model_list (List[Model]) -- モデルのリスト

append(model)¶

リストへのモデル追加

パラメータ: model (Model) -- リストに追加するモデル

get_model_list()¶

モデルリストの取得

戻り値: モデルのリスト
戻り値の型: model_list (List[Model])

set_model_list(model_list)¶

モデルリストの設定

パラメータ: model_list (List[Model]) -- モデルのリスト

Switcher クラス¶

class binarybrain.models.Switcher(model_dict=None, init_model_name=None, *, input_shape=None, name=None)¶

ベースクラス: Model

モデル切り替え用基底クラス

主に蒸留や転移学習などでレイヤー差し替えに用いる send_command から 'switch_model [name]' でも切り替え可能

パラメータ

(Dict{str (model_dict) -- Model}): 切り替えるモデルの辞書
init_model_name (str) -- 初期選択するモデルの名前

backward(dy_buf)¶

Backward

モデルは学習の為に backword メソッドを持つ必ず forwad と対で呼び出す必要があり、直前の forward 結果に対する勾配計算を行いながら逆伝搬する

BinaryBrain は自動微分の機能を備えないので、backword の実装は必須である

パラメータ: dy_buf (FrameBuffer) -- 入力データ
戻り値: 出力データ
戻り値の型: dx_buf (FrameBuffer)

dumps()¶

バイトデータにシリアライズ

モデルのデータをシリアライズして保存するためのバイト配列を生成

戻り値: Serialize data
戻り値の型: data (bytes)

forward(x_buf, train=True)¶

Forward

モデルは学習および推論の為に forward メソッドを持つ
train 変数を

パラメータ

x_buf (FrameBuffer) -- 入力データ
train (bool) -- Trueで学習、Falseで推論

戻り値

出力データ

戻り値の型

y_buf (FrameBuffer)

get_gradients()¶

勾配変数取得

get_parameters と対になる勾配変数を Variables として返す主に最適化(Optimizer)に渡すことを目的としている

戻り値: 勾配変数
戻り値の型: gradients (Variables)

get_info(depth: int = 0, *, columns: int = 70, nest: int = 0) → str¶

モデル情報取得

モデルの情報表示用の文字列を取得するそのまま表示やログに利用することを想定している

戻り値: info (str)

get_input_shape() → List[int]¶

入力シェイプ取得

戻り値: 入力シェイプ
戻り値の型: input_shape (List[int])

get_output_shape() → List[int]¶

出力シェイプ取得

戻り値: 出力シェイプ
戻り値の型: output_shape (List[int])

get_parameters()¶

パラメータ変数取得

学習対象とするパラメータ群を Variables として返す主に最適化(Optimizer)に渡すことを目的としている

モデル側を自作する際には、このメソッドで戻す変数の中に含めなかったパラメータは学習対象から外すことができる為パラメータを凍結したい場合などに利用できる

戻り値: パラメータ変数
戻り値の型: parameters (Variables)

loads(data)¶

バイトデータをロード

モデルのデータをシリアライズして復帰のバイト配列ロード

パラメータ: data (bytes) -- Serialize data

send_command(command, send_to='all')¶

コマンドの送信

モデルごとにコマンド文字列で設定を行うコマンド文字列の定義はモデルごとに自由である Sequentialクラスなどは、保有する下位のモデルに再帰的にコマンドを伝搬させるので、複数の層に一括した設定が可能である受取先は send_to で送り先はインスタンス名やクラス名で制限でき 'all' を指定するとフィルタリングされない

パラメータ

command (str) -- コマンド文字列
send_to (str) -- 送信先

set_input_shape(input_shape: List[int])¶

入力シェイプ設定

BinaryBarainではモデル生成時に入力のシェイプを決定する必要はなくネットワーク構築後に、ネットワークを構成する各モデルの set_input_shape を順に呼び出して形状を伝搬させることで各モデルの形状の設定を簡易化できる

set_input_shape が呼ばれるとそれまでの各層で保有する情報は保証されない。ネットワーク構築後に一度だけ呼び出すことを想定している

パラメータ: input_shape (List[int]) -- 入力シェイプ
戻り値: 出力シェイプ
戻り値の型: output_shape (List[int])

switch_model(model_name: str)¶

モデルを切り替える

パラメータ: (Dict{str (model_dict) -- Model}): 切り替えるモデルの辞書

バイナリ変調モデル (Binary modulation)¶

models モジュールのうち、バイナリネットを構成する変調にかかわるモデルです。

RealToBinary class¶

class binarybrain.models.RealToBinary(*, input_shape=None, frame_modulation_size=1, depth_modulation_size=1, value_generator=None, framewise=False, input_range_lo=0.0, input_range_hi=1.0, name=None, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

RealToBinary class: 実数値をバイナリ値に変換する。バイナリ変調機能も有しており、フレーム方向に変調した場合フレーム数(=ミニバッチサイズ)が増える。またここでビットパッキングが可能であり、32フレームのbitをint32に詰め込みメモリ節約可能である

パラメータ

frame_modulation_size (int) -- フレーム方向への変調数(フレーム数が増える)
depth_modulation_size (int) -- Depth方向への変調数(チャンネル数が増える)
framewise (bool) -- Trueで変調閾値をフレーム単位とする(Falseでピクセル単位)
bin_dtype (DType) -- 出力の型を bb.DType.FP32 もしくは bb.DType.BIT で指定可能

BinaryToReal class¶

class binarybrain.models.BinaryToReal(*, frame_integration_size=1, depth_integration_size=1, output_shape=None, input_shape=None, name=None, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

BinaryToReal class: バイナリ値を実数値に戻す。その際にフレーム方向に変調されたデータを積算して元に戻すことが可能である

パラメータ

frame_integration_size (int) -- フレーム方向の積算サイズ数(フレーム変調の統合)
depth_integration_size (int) -- チャンネル方向の積算サイズ(0の時はoutput_shape優先)
output_shape (List[int]) -- 出力のシェイプ(指定が無ければ入力と同じshape)
bin_dtype (DType) -- 入力の型を bb.DType.FP32 もしくは bb.DType.BIT で指定可能

BitEncode class¶

class binarybrain.models.BitEncode(bit_size=1, *, output_shape=None, input_shape=None, name=None, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

BitEncode class: 実数値をバイナリ表現としてdepth方向に展開する

パラメータ: bit_size (int) -- エンコードするbit数

Reduce class¶

class binarybrain.models.Reduce(output_shape=None, integration_size=0, *, input_shape=None, name=None, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

Reduce class: 多重化されている出力を折り返して積和する

パラメータ

output_shape ([int]) -- 出力のシェイプ
integration_size (int) -- 積算するサイズ

演算モデル (Operation models)¶

models モジュールには、ネットワークを構成するための各種演算モデルがあります。

DifferentiableLut クラス¶

class binarybrain.models.DifferentiableLut(output_shape=None, *, input_shape=None, connection='random', binarize=True, batch_norm=True, momentum=0.0, gamma=0.3, beta=0.5, seed=1, name=None, N=6, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: SparseModel

DifferentiableLut class

微分可能LUTモデル

内部計算的には StocasticLUT + BatchNormalization + Binarize(HardTanh) で構成される

FPGA合成するためのルックアップテーブル型のモデルを学習することができる純粋な Stochastic 演算のみを行いたい場合は binarize と batch_norm の両方を False にすればよい。

パラメータ

output_shape (List[int]) -- 出力のシェイプ
connection (str) -- 結線ルールを 'random', 'serial', 'depthwise' から指定可能
batch_norm (bool) -- BatchNormalization を有効にするか
binarize (bool) -- 二値化出力を有効にするか
momentum (float) -- BatchNormalization の momentum
gamma (float) -- BatchNormalization の gamma
beta (float) -- BatchNormalization の beta
N (int) -- LUTの入力数
seed (int) -- 変数初期値などの乱数シード
bin_dtype (DType)) -- バイナリ出力の型を bb.DType.FP32 と bb.DType.BIT から指定(bb.DType.BIT は binarize=True 時のみ)

W()¶

重み行列取得

コピーではなくスライス参照を得ており、本体の値を書き換え可能

戻り値: 重み行列を指すTensor
戻り値の型: W (Tensor)

dW()¶

重みの勾配行列取得

コピーではなくスライス参照を得ており、本体の値を書き換え可能

戻り値: 重みの勾配を指すTensor
戻り値の型: W (Tensor)

AverageLut クラス¶

class binarybrain.models.AverageLut(output_shape=None, *, input_shape=None, name=None, N=6, connection='serial', binarize=True, binarize_input=False, seed=1, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: SparseModel

AverageLut class
入力値の平均を出力するLUT型のモデルバイナリの場合、bitをカウントして1の方が多ければ1を出力するテーブル固定のLUTと考える事ができる

パラメータ

output_shape ([int]) -- 出力のシェイプ

connection (str) -- 結線ルールを 'random', 'serial', 'depthwise' から指定可能

binarize (bool) -- 二値化出力を有効にするか

binarize_input (bool) -- 入力を二値化してから使うようにするか

N (int) -- LUTの入力数

seed (int) -- 変数初期値などの乱数シード

bin_dtype (DType)) -- バイナリ出力の型を bb.DType.FP32 と bb.DType.BIT から指定(bb.DType.BIT は binarize=True 時のみ)

BinaryLut クラス¶

class binarybrain.models.BinaryLut(output_shape=None, *, input_shape=None, connection='random', seed=1, name=None, N=6, fw_dtype=DType.FP32, bw_dtype=DType.FP32, core_model=None)¶

ベースクラス: SparseModel

バイナリLUTモデル

一般的なFPGAのLUTと同等の機能をするモデル。学習能力はなく、他のモデルで学習した結果をインポートしてモデル評価を行うためのもの

パラメータ

output_shape (List[int]) -- 出力のシェイプ
connection (str) -- 結線ルールを 'random', 'serial', 'depthwise' から指定可能(未実装)
N (int) -- LUTの入力数
seed (int) -- 変数初期値などの乱数シード
fw_dtype (DType)) -- forwardの型を bb.DType.FP32 と bb.DType.BIT から指定

static from_sparse_model(layer, *, fw_dtype=DType.FP32)¶

他のモデルを元に生成

インポート元は入出力が同じ形状をしている必要があり、デジタル値の入力に対して出力を 0.5 を閾値として、バイナリテーブルを構成して取り込む

パラメータ: leyaer (Model) -- インポート元のモデル

import_layer(leyaer)¶

他のモデルからからインポート

インポート元は入出力が同じ形状をしている必要があり、デジタル値の入力に対して出力を 0.5 を閾値として、バイナリテーブルを構成して取り込む

パラメータ: leyaer (Model) -- インポート元のモデル

DenseAffine クラス¶

class binarybrain.models.DenseAffine(output_shape=None, *, input_shape=None, initialize_std=0.01, initializer='', seed=1, name=None, dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

DenseAffine class: 普通のDenseAffine

パラメータ

output_shape (List[int]) -- 出力のシェイプ
initialize_std (float) -- 重み初期化乱数の標準偏差
initializer (str) -- 変数の初期化アルゴリズム選択(default/normal/uniform/He/Xavier)。
seed (int) -- 変数初期値などの乱数シード

DenseAffineQuantize クラス¶

class binarybrain.models.DenseAffineQuantize(output_shape=None, *, input_shape=None, quantize=True, weight_bits=8, output_bits=16, input_bits=0, weight_scale=0.00390625, output_scale=0.00390625, input_scale=0.00390625, initialize_std=0.01, initializer='', seed=1, name=None, dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

DenseAffineQuantize class: DenseAffine に量子化のサポートを付けたもの

パラメータ

output_shape (List[int]) -- 出力のシェイプ
initialize_std (float) -- 重み初期化乱数の標準偏差
initializer (str) -- 変数の初期化アルゴリズム選択(default/normal/uniform/He/Xavier)。
quantize (bool) -- 量子化の有効状態の初期値
weight_bits (int) -- 重みの量子化bit数 (0で量子化しない)
output_bits (int) -- 入力の量子化bit数 (0で量子化しない)
input_bits (int) -- 出力の量子化bit数 (0で量子化しない)
weight_scale (float) -- 重みの量子化スケール(0でbit数に合わせる)
output_scale (float) -- 入力の量子化スケール(0でbit数に合わせる)
input_scale (float) -- 出力の量子化スケール(0でbit数に合わせる)
seed (int) -- 変数初期値などの乱数シード

DepthwiseDenseAffine クラス¶

class binarybrain.models.DepthwiseDenseAffine(output_shape=None, *, input_shape=None, input_point_size=0, depth_size=0, initialize_std=0.01, initializer='', seed=1, name=None, dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

DepthwiseDenseAffine class: 普通のDepthwiseDenseAffine

パラメータ

output_shape (List[int]) -- 出力のシェイプ
input_point_size (int) -- 入力のpoint数
depth_size (int) -- depthサイズ
initialize_std (float) -- 重み初期化乱数の標準偏差
initializer (str) -- 変数の初期化アルゴリズム選択(default/normal/uniform/He/Xavier)。
seed (int) -- 変数初期値などの乱数シード

DepthwiseDenseAffineQuantize クラス¶

class binarybrain.models.DepthwiseDenseAffineQuantize(output_shape=None, *, input_shape=None, input_point_size=0, depth_size=0, quantize=True, weight_bits=8, output_bits=16, input_bits=0, weight_scale=0.00390625, output_scale=0.00390625, input_scale=0.00390625, initialize_std=0.01, initializer='', seed=1, name=None, dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

DepthwiseDenseAffineQuantize class: DepthwiseDenseAffine に量子化のサポートを付けたもの

パラメータ

output_shape (List[int]) -- 出力のシェイプ
input_point_size (int) -- 入力のpoint数
depth_size (int) -- depthサイズ
weight_bits (int) -- 重みの量子化bit数 (0で量子化しない)
output_bits (int) -- 入力の量子化bit数 (0で量子化しない)
input_bits (int) -- 出力の量子化bit数 (0で量子化しない)
weight_scale (float) -- 重みの量子化スケール(0でbit数に合わせる)
output_scale (float) -- 入力の量子化スケール(0でbit数に合わせる)
input_scale (float) -- 出力の量子化スケール(0でbit数に合わせる)
initialize_std (float) -- 重み初期化乱数の標準偏差
initializer (str) -- 変数の初期化アルゴリズム選択(default/normal/uniform/He/Xavier)。
seed (int) -- 変数初期値などの乱数シード

畳み込み/プーリング(Convolution and Pooling)¶

models モジュールの、畳み込みやプーリングなどのフィルタ演算を行うモデルです。

Convolution2d クラス¶

class binarybrain.models.Convolution2d(sub_layer, filter_size=(1, 1), stride=(1, 1), *, input_shape=None, padding='valid', border_mode='reflect_101', border_value=0.0, name=None, fw_dtype=DType.FP32, bw_dtype=DType.FP32)¶

ベースクラス: Sequential

Convolution class

Lowering による畳み込み演算をパッキングするクラス

sub_layer で指定した演算レイヤーを畳み込み計算するためのモデル例えば sub_layer に DenseAffineレイヤーを指定すると一般的なCNN用の畳み込み層となるが、 BinaryBrain ではここに DifferentiableLut モデルを組み合わせて作った複合レイヤーを指定することでFPGA化に適した畳み込み層を学習させることができる。

sub_layer で指定したサブレイヤーが im2col と col2im で挟み込まれ、一般に Lowering と呼ばれる方法で畳み込み演算が実行される

パラメータ

sub_layer (Model) -- 畳み込みを行うサブレイヤー(このレイヤが im2col と col2im で挟み込まれる)
filter_size ((int, int)) -- 2次元のタプルでフィルタサイズを指定する
stride ((int, int)) -- 2次元のタプルでストライドサイズを指定する
batch_norm (bool) -- BatchNormalization を有効にするか
padding (str)) -- パディングの方法を 'valid' と 'same' で指定する
border_mode (Border)) -- 'same' 時のボーダー処理を指定する
border_value (float) -- 'same' 時のボーダー処理が CONSTANT の場合にパディング値を指定する
fw_dtype (DType)) -- forwarする型を bb.DType.FP32 と bb.DType.BIT から指定

backward(dy_buf)¶

Backward

モデルは学習の為に backword メソッドを持つ必ず forwad と対で呼び出す必要があり、直前の forward 結果に対する勾配計算を行いながら逆伝搬する

BinaryBrain は自動微分の機能を備えないので、backword の実装は必須である

パラメータ: dy_buf (FrameBuffer) -- 入力データ
戻り値: 出力データ
戻り値の型: dx_buf (FrameBuffer)

dumps()¶

バイトデータにシリアライズ

モデルのデータをシリアライズして保存するためのバイト配列を生成

戻り値: Serialize data
戻り値の型: data (bytes)

forward(x_buf, train=True)¶

Forward

モデルは学習および推論の為に forward メソッドを持つ
train 変数を

パラメータ

x_buf (FrameBuffer) -- 入力データ
train (bool) -- Trueで学習、Falseで推論

戻り値

出力データ

戻り値の型

y_buf (FrameBuffer)

loads(data)¶

バイトデータをロード

モデルのデータをシリアライズして復帰のバイト配列ロード

パラメータ: data (bytes) -- Serialize data

send_command(command, send_to='all')¶

コマンドの送信

モデルごとにコマンド文字列で設定を行うコマンド文字列の定義はモデルごとに自由である Sequentialクラスなどは、保有する下位のモデルに再帰的にコマンドを伝搬させるので、複数の層に一括した設定が可能である受取先は send_to で送り先はインスタンス名やクラス名で制限でき 'all' を指定するとフィルタリングされない

パラメータ

command (str) -- コマンド文字列
send_to (str) -- 送信先

set_input_shape(shape)¶

入力シェイプ設定

BinaryBarainではモデル生成時に入力のシェイプを決定する必要はなくネットワーク構築後に、ネットワークを構成する各モデルの set_input_shape を順に呼び出して形状を伝搬させることで各モデルの形状の設定を簡易化できる

set_input_shape が呼ばれるとそれまでの各層で保有する情報は保証されない。ネットワーク構築後に一度だけ呼び出すことを想定している

パラメータ: input_shape (List[int]) -- 入力シェイプ
戻り値: 出力シェイプ
戻り値の型: output_shape (List[int])

MaxPooling クラス¶

class binarybrain.models.MaxPooling(filter_size=(2, 2), *, input_shape=None, name=None, fw_dtype=DType.FP32, bw_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

MaxPooling class

パラメータ

filter_size ((int, int)) -- 2次元のタプルでフィルタサイズを指定する
fw_dtype (DType)) -- forwarする型を bb.DType.FP32 と bb.DType.BIT から指定

StochasticMaxPooling クラス¶

class binarybrain.models.StochasticMaxPooling(filter_size=(2, 2), *, input_shape=None, name=None, fw_dtype=DType.FP32, bw_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

StochasticMaxPooling class

Stochastic 演算として OR 演算で Pooling 層を構成するモデル

パラメータ

filter_size ((int, int)) -- 2次元のタプルでフィルタサイズを指定する(現在2x2のみ)
fw_dtype (DType)) -- forwarする型を bb.DType.FP32 と bb.DType.BIT から指定

UpSampling クラス¶

class binarybrain.models.UpSampling(filter_size=(2, 2), *, fill=True, input_shape=None, name=None, fw_dtype=DType.FP32, bw_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

UpSampling class

畳み込みの逆方向にアップサンプリングを行うモデル

パラメータ

filter_size ((int, int)) -- 2次元のタプルでフィルタサイズを指定する(現在2x2のみ)
fw_dtype (DType)) -- forwarする型を bb.DType.FP32 と bb.DType.BIT から指定

活性化(Activation)¶

models モジュールの活性化層(Activation層()を作るためのモデルです。

Binarize クラス¶

class binarybrain.models.Binarize(*, input_shape=None, binary_th=0.0, binary_low=-1.0, binary_high=1.0, hardtanh_min=-1.0, hardtanh_max=1.0, name=None, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

Binarize class

2値化(活性化層) backward は hard-tanh となる

パラメータ: bin_dtype (DType)) -- バイナリ型を bb.DType.FP32 と bb.DType.BIT から指定

Sigmoid クラス¶

class binarybrain.models.Sigmoid(*, input_shape=None, name=None, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

Sigmoid class

Sigmoid 活性化層 send_command で "binary true" とすることで、Binarize に切り替わる多値で学習を進めて、途中から Binarize に切り替える実験などが可能である

ReLU クラス¶

class binarybrain.models.ReLU(*, input_shape=None, name=None, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

ReLU class

ReLU 活性化層 send_command で "binary true" とすることで、Binarize に切り替わる多値で学習を進めて、途中から Binarize に切り替える実験などが可能である

HardTanh クラス¶

class binarybrain.models.HardTanh(*, input_shape=None, name=None, bin_dtype=DType.FP32, real_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

HardTanh class

HardTanh 活性化層 send_command で "binary true" とすることで、Binarize に切り替わる多値で学習を進めて、途中から Binarize に切り替える実験などが可能である

Softmax クラス¶

class binarybrain.models.Softmax(*, input_shape=None, name=None, dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

Softmax class

Softmax 活性化層

補助モデル¶

models モジュールのその他のモデルです。

BatchNormalization クラス¶

class binarybrain.models.BatchNormalization(*, input_shape=None, momentum=0.9, gamma=1.0, beta=0.0, fix_gamma=False, fix_beta=False, name=None, dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

BatchNormalization class

パラメータ

momentum (float) -- 学習モーメント
gamma (float) -- gamma 初期値
beta (float) -- beta 初期値
fix_gamma (bool) -- gamma を固定する(学習させない)
fix_beta (bool) -- beta を固定する(学習させない)
bin_dtype (DType)) -- バイナリ型を bb.DType.FP32 と bb.DType.BIT から指定

Dropout クラス¶

class binarybrain.models.Dropout(*, rate=0.5, input_shape=None, seed=1, name=None, fw_dtype=DType.FP32, bw_dtype=DType.FP32, core_model=None)¶

ベースクラス: Model

Dropout class

パラメータ

rate (float) -- Drop率
seed (int) -- 乱数シード
fw_dtype (DType) -- forwardの型を bb.DType.FP32 と bb.DType.BIT から指定

Shuffle クラス¶

class binarybrain.models.Shuffle(shuffle_unit, *, output_shape=None, input_shape=None, name=None, core_model=None)¶

ベースクラス: Model

Shuffle class

所謂 ShuffleNet のようなシャッフルを行うモデル入力ノードが shuffle_unit 個のグループに分割されるようにシャッフルする

パラメータ: shuffle_unit (int) -- シャッフルする単位

最適化 (optimizer)¶

Optimizer クラス¶

class binarybrain.optimizer.Optimizer(core_optimizer=None)¶

ベースクラス: Object

Optimizer の基本クラス

set_learning_rate(learning_rate)¶: 学習率設定

set_variables(params, grads)¶

変数設定

パラメータ

params (Variables) -- 学習対象のパラメータ変数
grads (Variables) -- paramsに対応する勾配変数

step()¶

パラメータ更新

set_variablesで設定された勾配変数に基づいた学習をset_variablesで設定されたパラメータ変数に適用する

update()¶

パラメータ更新＆勾配ゼロクリア

set_variablesで設定された勾配変数に基づいた学習をset_variablesで設定されたパラメータ変数に適用して、勾配をゼロクリアする

zero_grad()¶

勾配のゼロクリア

set_variablesで設定された勾配変数をゼロクリアする

OptimizerSgd クラス¶

class binarybrain.optimizer.OptimizerSgd(learning_rate=0.001, dtype=DType.FP32)¶

ベースクラス: Optimizer

SGD 最適化クラス

パラメータ: learning_rate (float) -- 学習率

OptimizerAdaGrad クラス¶

class binarybrain.optimizer.OptimizerAdaGrad(learning_rate=0.01, dtype=DType.FP32)¶

ベースクラス: Optimizer

AdaGrad 最適化クラス

パラメータ: learning_rate (float) -- 学習率

OptimizerAdam クラス¶

class binarybrain.optimizer.OptimizerAdam(learning_rate=0.001, beta1=0.9, beta2=0.999, dtype=DType.FP32)¶

ベースクラス: Optimizer

Adam 最適化クラス

パラメータ

learning_rate (float) -- 学習率
beta1 (float) -- beta1
beta2 (float) -- beta2

損失関数(Loss functions)¶

LossFunction クラス¶

class binarybrain.losses.LossFunction(core_loss=None)¶

ベースクラス: Object

LossFunction class 損失関数の基底クラス

calculate(y_buf, t_buf, mini_batch_size=None)¶

損失の計算

mini_batch_size はメモリなどの都合でミニバッチをさらに分割する場合などに用いる。通常はNoneでよい。

パラメータ

y_buf (FrameBuffer) -- forward演算結果
t_buf (FrameBuffer) -- 教師データ
mini_batch_size (int) -- ミニバッチサイズ

戻り値

逆伝搬させる誤差を返す

戻り値の型

dy_buf (FrameBuffer)

clear()¶

値のクリア

集計をクリアする。通常 epoch の単位でクリアして再集計を行う

get()¶

値の取得

戻り値: 現在までの損失値を返す
戻り値の型: loss(float)

LossMeanSquaredError クラス¶

class binarybrain.losses.LossMeanSquaredError(reduction='mean', dtype=DType.FP32)¶

ベースクラス: LossFunction

LossMeanSquaredError class

平均二乗誤差(MSE)を計算して誤差として戻す

LossCrossEntropy クラス¶

class binarybrain.losses.LossCrossEntropy(dtype=DType.FP32)¶

ベースクラス: LossFunction

LossCrossEntropy class

交差エントロピー誤差を戻す

LossBinaryCrossEntropy クラス¶

class binarybrain.losses.LossBinaryCrossEntropy(dtype=DType.FP32)¶

ベースクラス: LossFunction

LossBinaryCrossEntropy class

2値の交差エントロピー誤差を戻す

LossSoftmaxCrossEntropy クラス¶

class binarybrain.losses.LossSoftmaxCrossEntropy(dtype=DType.FP32)¶

ベースクラス: LossFunction

LossSoftmaxCrossEntropy class

Softmax(活性化) と CrossEntropy(損失関数) の複合両者を統合すると計算が簡略化される。

利用に際しては最終段に Softmax が挿入されたのと等価になるので注意すること。

LossSigmoidCrossEntropy クラス¶

class binarybrain.losses.LossSigmoidCrossEntropy(dtype=DType.FP32)¶

ベースクラス: LossFunction

LossSigmoidCrossEntropy class

Sigmoid(活性化) と BinaryCrossEntropy(損失関数) の複合両者を統合すると計算が簡略化される。

利用に際しては最終段に Sigmoid が挿入されたのと等価になるので注意すること。

評価関数(Metrics functions)¶

Metrics クラス¶

class binarybrain.metrics.Metrics(core_metrics=None)¶

ベースクラス: Object

Metrics class 評価関数の基底クラス

calculate(y_buf, t_buf)¶

評価の計算

パラメータ

y_buf (FrameBuffer) -- forward演算結果
t_buf (FrameBuffer) -- 教師データ

clear()¶

値のクリア

集計をクリアする。通常 epoch の単位でクリアして再集計を行う

get()¶

値の取得

戻り値: 現在までの損失値を返す
戻り値の型: metrics(float)

get_metrics_string()¶

評価対象の文字列取得

評価関数ごとに評価値の単位が異なるため計算しているものの文字列を返す平均二乗誤差(MSE)であったり、認識率(accuracy)であったり getで得られる値を、表示やログで表す際に利用できる

パラメータ: metrics_string (str) -- 評価対象の文字列取得

MetricsMeanSquaredError クラス¶

class binarybrain.metrics.MetricsMeanSquaredError(dtype=DType.FP32)¶

ベースクラス: Metrics

MetricsMeanSquaredError class

平均二乗誤差の評価関数教師信号との平均二乗誤差を計算する

MetricsCategoricalAccuracy クラス¶

class binarybrain.metrics.MetricsCategoricalAccuracy(dtype=DType.FP32)¶

ベースクラス: Metrics

MetricsCategoricalAccuracy class

多クラス分類用の評価関数一致率を accuracy として計算する

MetricsBinaryCategoricalAccuracy クラス¶

class binarybrain.metrics.MetricsBinaryCategoricalAccuracy(dtype=DType.FP32)¶

ベースクラス: Metrics

MetricsBinaryCategoricalAccuracy class

2クラス分類用の評価関数一致率を accuracy として計算する

保存／復帰(Serialize)¶

storage モジュール¶

binarybrain.storage.copy_network_files(data_path, dst_name, src_name, wildcard='*', exist_ok=False, verbose=1)¶: ネットワークファイルのコピー

binarybrain.storage.get_latest_path(path: str) → str¶

Get latest data path 最新のデータ保存パスを取得

パラメータ: path (str) -- 検索するパス
戻り値: 見つかったパス. 見つからなければ None

binarybrain.storage.get_load_networks_path(path: str, net, name=None)¶: ネットワークをロードするパスを取得

binarybrain.storage.is_date_string(text: str)¶

Check if the string is a date データ保存パス用の日付文字列かどうか判定

パラメータ: text (str) -- 判定する文字列
戻り値: Boolean.

binarybrain.storage.load_models(path: str, net, *, read_layers: bool = False, file_format=None, verbose=True)¶

load networks ネットを構成するモデルの保存

パラメータ

path (str) -- 読み出すパス
net (Model) -- 読み込むネット
read_layers (bool) -- レイヤー別に読み込むか
verbose (bool) -- 詳しく表示する

binarybrain.storage.load_networks(path: str, net, name=None, *, read_layers: bool = False, file_format=None, verbose=True)¶

load network ネットを構成するモデルの読み込み

最新のデータを探して読み込み名前を指定した場合はそれを読み込み

パラメータ

path (str) -- 読み込むパス
net (Model) -- 読み込むネット
file_format (str) -- 読み込む形式(Noneがデフォルト)
verbose (bool) -- 詳しく表示する

binarybrain.storage.remove_backups(path: str, keeps: int = -1)¶

Get latest data path 最新のデータ保存パスを取得

パラメータ

path (str) -- 検索するパス
keeps (int) -- 削除せずに残す数

binarybrain.storage.save_models(path: str, net, *, write_layers=True, file_format=None)¶

save networks ネットを構成するモデルの保存

パラメータ

path (str) -- 保存するパス
net (Model) -- 保存するネット
write_layers (bool) -- レイヤー別にも出力するかどうか

binarybrain.storage.save_networks(path: str, net, name=None, *, backups: int = 10, write_layers: bool = False, file_format=None)¶

save networks ネットを構成するモデルの保存

指定したパスの下にさらに日付でディレクトリを作成して保存古いものから削除する機能あり名前を指定すれば日付ではなく名前で記録可能

パラメータ

path (str) -- 保存するパス
net (Model) -- 保存するネット
name (str) -- 保存名(指定しなければ日時で保存)
backups (int) -- 残しておく古いデータ数(-1ですべて残す)
write_layers (bool) -- レイヤー別に出力

戻り値

保存名を返す

戻り値の型

name (str)

RTL(Verilog/HLS)変換¶

学習が完了したネットは結果パラメータに基づいて、ユーザ側で自由に実装可能ですが、 BinaryBrainでも若干のサポート関数を備えています。

binarybrain.verilog.dump_verilog_lut_cnv_layers(f, module_name: str, net, device='')¶

dump verilog source of Convolutional LUT layers

畳み込み層を含むネットを AXI4 Stream Video 形式のVerilogソースコードして出力する。縮小を伴う MaxPooling 層は最後に1個だけ挿入を許される

パラメータ

f (StreamIO) -- 出力先ストリーム
module_name (str) -- モジュール名
net (Model) -- 変換するネット

binarybrain.verilog.dump_verilog_lut_layers(f, module_name: str, net, device='')¶

dump verilog source of LUT layers 変換できないモデルは影響ない層とみなして無視するので注意

パラメータ

f (StreamIO) -- 出力先ストリーム
module_name (str) -- モジュール名
net (Model) -- 変換するネット

binarybrain.verilog.dump_verilog_readmemb_image_classification(f, loader, *, class_digits=8)¶

verilog用データダンプ verilog の $readmemb() での読み込み用データ作成

クラスID + 画像データの形式で出力する

パラメータ

f (StreamIO) -- 出力先
loader (Loader) -- モジュール名
class_digits (int) -- クラス分類のbit数

binarybrain.verilog.make_image_tile(rows, cols, img_gen)¶

画像をタイル状に並べて大きな画像にする

学習用の c, h, w 順の画像データをタイル状に結合する

パラメータ

rows (int)) -- 縦の結合枚数
cols (int)) -- 横の結合枚数
gen (ndarray) -- 画像を返すジェネレータ

戻り値

作成した画像

戻り値の型

img (ndarray)

binarybrain.verilog.make_verilog_lut_layers(module_name: str, net, device='')¶

make verilog source of LUT layers 変換できないモデルは影響ない層とみなして無視するので注意

パラメータ

module_name (str) -- モジュール名
net (Model) -- 変換するネット

戻り値

Verilog source code (str)

binarybrain.verilog.write_ppm(fname, img)¶

ppmファイルの出力

学習用の c, h, w 順の画像データを ppm形式で保存する

パラメータ

fname (str) -- 出力ファイル名
img (ndarray) -- モジュール名

binarybrain.hls.dump_hls_lut_layer(f, name, lut)¶

dump HLS source of LUT layer

パラメータ

f (StreamIO) -- 出力先ストリーム
name (str) -- 関数名
lut (Model) -- 変換するネット

binarybrain.hls.make_hls_lut_layer(name, lut)¶

make HLS source of LUT layer

パラメータ

name (str) -- 関数名
lut (Model) -- 変換するネット

戻り値

HLS source code (str)

システム／GPU関連(System/GPU)¶

その他システム制御関連のAPIです

binarybrain.system.get_cuda_driver_version()¶

CUDAドライババージョンの取得

戻り値: CUDAドライババージョン
戻り値の型: driver_version (int)

binarybrain.system.get_cuda_driver_version_string()¶

CUDAドライババージョン文字列の取得

戻り値: CUDAドライババージョン文字列
戻り値の型: driver_version (str)

binarybrain.system.get_device_count()¶

利用可能なデバイス(GPU)の個数を確認

戻り値: 利用可能なデバイス(GPU)の個数を返す
戻り値の型: device_count (int)

binarybrain.system.get_device_properties_string(device_id)¶

現在のデバイス(GPU)の情報を入れた文字列を取得

パラメータ: device_id (int) -- 情報を取得するデバイス番号を指定
戻り値: 現在のデバイス(GPU)の情報を入れた文字列を返す
戻り値の型: device_properties_string (str)

binarybrain.system.get_version_string()¶

バージョン文字列取得

戻り値: バージョン文字列
戻り値の型: version (str)

binarybrain.system.is_device_available()¶

デバイス(GPU)が有効かの確認

戻り値: デバイス(GPU)が利用可能なら True を返す
戻り値の型: device_available (bool)

binarybrain.system.omp_set_num_threads(threads: int)¶

omp_set_num_threadsを呼び出すバックグランドで学習する場合など、Host側のCPUをすべて使うと逆に性能が落ちる場合や、運用上不便なケースなどで個数制限できる

パラメータ: threads (int) -- OpenMPでのスレッド数

binarybrain.system.set_device(device_id)¶

利用するデバイス(GPU)を切り替え

パラメータ: device_id (int) -- 利用するデバイス番号を指定

binarybrain.system.set_host_only(host_only: bool)¶

ホスト(CPU)のみの指定

True を設定するとデバイス(GPU)を未使用としてホスト(CPU)のみを利用

パラメータ: host_only (bool) -- ホストのみの場合 True を指定

開発情報¶

githubについて¶

現在 version4 は下記の branch で管理しています

ver4_develop: 開発用ブランチです。ビルド不能な状態になることもあります。最新のコードにアクセスしたい場合はここをご覧ください。
ver4_release: リリース作成用ブランチです。
master: リリースブランチで確認したものを反映。

tag はリリースのタイミングでバージョン番号のタグを打つようにしております。また、開発都合で ver4_build0001 のような形式でリリースと無関係にビルドタグを打つ場合があります。

まだ、開発初期で仕様が安定していませんので、再現性の確保などが必要な際はタグを活用ください。

作者情報¶

渕上竜司(Ryuji Fuchikami)

github : https://github.com/ryuz
blog : http://ryuz.txt-nifty.com
twitter : https://twitter.com/ryuz88
facebook : https://www.facebook.com/ryuji.fuchikami
web-site : http://ryuz.my.coocan.jp/
e-mail : ryuji.fuchikami@nifty.com

参考にさせて頂いた情報¶

バイナリニューラルネットとハードウェアの関係

https://www.slideshare.net/kentotajiri/ss-77136469
BinaryConnect: Training Deep Neural Networks with binary weights during propagations

https://arxiv.org/pdf/1511.00363.pdf
Binarized Neural Networks

https://arxiv.org/abs/1602.02505
Binarized Neural Networks: Training Deep Neural Networks with Weights and Activations Constrained to +1 or -1

https://arxiv.org/abs/1602.02830
XNOR-Net: ImageNet Classification Using Binary Convolutional Neural Networks

https://arxiv.org/abs/1603.05279
Xilinx UltraScale Architecture Configurable Logic Block User Guide

https://japan.xilinx.com/support/documentation/user_guides/ug574-ultrascale-clb.pdf

参考にした書籍¶

ゼロから作るDeep Learning ―Pythonで学ぶディープラーニングの理論と実装

https://www.oreilly.co.jp/books/9784873117584/