FreeBSD で ATLAS と LAPACK をビルドとインストール

このページでは， ATLAS と CBLAS と LAPACK のインストール手順を図解で説明する．

ATLAS（Automatically Tuned Linear Algebra Software）は，実行環境に合わせて自動チューニングを行う BLAS の実装である．ライセンスは BSD ライセンス．
CBLAS は，FORTRAN で書かれた BLAS を C 言語から呼び出すためのインタフェースである．
CBLAS は，ATLAS に同梱されているので，ATLAS をインストールすると，CBLAS もインストールされたことになる．
LAPACK とは，行列に関する種々の問題（連立１次方程式，固有値問題，などなど多数）を解く機能を持つソフトウェア．BLAS の機能を使う．

【版とソフトウェアの選択について】

ATLAS の最新の安定版は 3.10.3（2016年7月28日公開）であり，その後の開発は停滞している．新しい CPU では自動チューニングが十分に働かないことがある．
現在，最適化された BLAS 実装としては OpenBLAS（GotoBLAS2 を引き継いだもの）や BLIS が広く使われている．特に理由がなければ OpenBLAS を使う方が簡単で，新しい CPU での性能も得やすい．
```
pkg install openblas lapack
```
ATLAS と LAPACK も packages で導入できる．自動チューニングを自分で行う必要がなければ，こちらを使う．
```
pkg install atlas lapack
```
以下では，実行環境に合わせて自動チューニングを行うために，ソースコードからビルドする手順を説明する．

＜BLAS の主な機能（ごく一部を紹介）＞

Level 1 ベクトルとベクトルの演算
- DOT : 内積
- AXPY : AXPY 演算 ( y <- ax + y の形など)
- NORM : ノルム　など
Level 2 行列とベクトルと計算
- 行列とベクトルの積 ( y <- Ax )
- 行列の rank-1 更新 ( A <- A + xy' )
Level 3 行列同士の演算
- 行列と行列の積 ( Z <- XY )

＜ATLAS と LAPACK のインストールの要点＞

FreeBSD を使う．
* Windows での手順は，別のページで説明している
* Linux での手順は，別のページで説明している
ATLAS と LAPACK と CBLAS をソースコードからコンパイルします（CBLAS は，ATLAS に同梱されている）．それには C コンパイラや FORTRAN コンパイラなどが必要．
コンパイルには GNU コンパイラ（lang/gcc の gcc と gfortran）を使う．
FORTRAN コンパイラは基本システムに含まれないので，packages で導入する．また，ATLAS の自動チューニングのコードは clang での動作確認が十分でないため，C コンパイラも gcc を指定する．
ATLAS の configure の引数の例（物理コア数 2，クロック周波数 3160MHz，64 ビットの FreeBSD の場合）
```
../configure -t 2 -m 3160 -b 64 -Fa alg -fPIC -D c -DPentiumCPS=3160 -D c -DWALL --prefix=/usr/local/atlas \
--with-netlib-lapack-tarfile=/tmp/lapack-3.12.1.tar.gz
```
【設定の要点】
CPU の種類によって設定すべき引数値
- CPU の物理コア数: -t 2 　・・・　「物理コア数が 2 個」という意味．物理コアが 4 個のときは -t 4 になる．
  * Simultaneous Multi-Threading（Intel の Hyper-Threading など）により，物理コア数と論理コア数が異なる場合がある．ATLAS のチューニングでは 物理コア数を指定する．
- CPU のクロック周波数: -m 3160　・・・　周波数（MHz 単位）
- CPU のビット数（ポインタの幅）: -b 64　・・・　64 ビット．32 ビットの FreeBSD を使っているときは -b 32 になる．

謝辞

ATLAS の自動チューニングとマルチコア対応（configure の「-t」オプション）については，Octave 利用者コミュニティでの情報提供を参考にした．記して感謝する．

* 本 Web ページに残っているであろうミスは，本 Web ページの作者である私の責任です．

前準備

前もってインストールしておくソフトウェア

GNU コンパイラ（gcc, gfortran）のインストール
```
pkg install gcc13
```
これで gcc13 と gfortran13 が /usr/local/bin に入る．版が違う場合は，以下のコマンドの「13」を読み替えること．
LAPACK のソースコードのダウンロード
ATLAS のビルド時に LAPACK を組み込むので，LAPACK の tar ファイルを用意する．最新版は 3.12.1（2025年1月8日公開）．
```
cd /tmp
fetch https://github.com/Reference-LAPACK/lapack/archive/refs/tags/v3.12.1.tar.gz -o lapack-3.12.1.tar.gz
```

事前に決めておく事項

ATLAS のインストールディレクトリ: /usr/local/atlas
ATLAS のソースコードを展開してできるディレクトリ: /tmp/ATLAS3.10.3

CPU の物理コア数，クロック周波数，ビット数の確認

CPU のビット数の確認
CPU のビット数は，「32」か「64」のいずれか．必ず調べておく．次のコマンドで確認する（amd64 と表示されれば 64 ビット）．
```
uname -m
```
CPU の種類，コア数，クロック周波数の確認
FreeBSD では sysctl で確認できる．
```
sysctl hw.model
sysctl hw.ncpu
sysctl kern.smp.cores
sysctl dev.cpu.0.freq
```
hw.ncpu は論理コア数，kern.smp.cores は物理コア数を示す． dev.cpu.0.freq は現在の動作周波数（MHz 単位）である．

ATLAS と LAPACK のビルドとインストール

ここでの説明は，CPU の物理コア数，クロック周波数，ビット数が下記の通りであるとして説明を続けるので，適切に読み替えてください．

【本 Web ページでの設定】

CPU の物理コア数: 2
CPU のクロック周波数: 3160
CPU のビット数（ポインタの幅）: 64

⇒　各自，読み替えてください．

ATLAS のダウンロード

ATLAS の「インストール概要」の Web ページを開く．
https://math-atlas.sourceforge.net/atlas_install/atlas_install.html
CPU の周波数を変動させる機能を無効にする．
ATLAS は実測値をもとにチューニングを行うので，測定中に周波数が変動すると結果が不正確になる．FreeBSD では powerd を止め，周波数を最大値に固定する．
```
service powerd stop
sysctl dev.cpu.0.freq=3160
```
ATLAS の Web ページを開く
https://math-atlas.sourceforge.net/
「SourceForge Summary Page」をクリック
「Files」をクリック
ファイルの選択
安定版の atlas3.10.3.tar.bz2 をクリックする．クリックすると，ダウンロードが始まる．

ATLAS のビルドとインストール

ダウンロードしたファイルを /tmp に移動
tar コマンドを用いて解凍
```
cd /tmp
tar -xvjof atlas3.10.3.tar.bz2
```
解凍終了の確認
「mv ATLAS ATLAS3.10.3」の実行
configure コマンドの実行
【本 Web ページでの設定】
- CPU の物理コア数: 2
- CPU のクロック周波数: 3160
- CPU のビット数（ポインタの幅）: 64
⇒　各自，読み替えてください．
```
cd ATLAS3.10.3
mkdir B1
cd B1
../configure --prefix=/usr/local/atlas \
--cc=gcc13 -C acg gcc13 -C ic gcc13 -C xc gcc13 -C dk gcc13 -C dm gcc13 -C if gfortran13 \
-t 2 -m 3160 -b 64 -Fa alg -fPIC -D c -DPentiumCPS=3160 -D c -DWALL \
--with-netlib-lapack-tarfile=/tmp/lapack-3.12.1.tar.gz
```
* 「-t ... -m ...」のところは，物理コア数と周波数を正しく設定すること．
* LAPACK の新しい版で configure やビルドが通らない場合は，packages の math/atlas（動作確認済みの LAPACK を同梱）を使う．
＜説明＞
- mkdir B1
  作業用のディレクトリの作成．「B1」のところは好きな名前でよい．ATLAS はソースディレクトリの直下ではビルドできないので，別のディレクトリを作ってその中で configure を実行する．
- CPU の物理コア数: -t 2
  マルチコアの CPU では，「-t ＜物理コア数＞」を引数に含めます．「-t 2 」は、「物理コア数が 2 個」という意味．物理コアが 4 個のときは -t 4 になる．「-t ＜物理コア数＞」を付けると，ATLAS のシングルスレッド版とマルチスレッド版の両方のライブラリファイルがビルドされる．
  マルチコアの CPU でない場合には，「-t ＜物理コア数＞」を付けないで下さい． ATLAS のシングルスレッド版のライブラリファイルだけがビルドされる．
- CPU のクロック周波数: -m 3160
  周波数（MHz 単位）
- CPU のビット数（ポインタの幅）: -b 64
  32 ビットの時は -b 32 になる．
- -fPIC: 共有ライブラリを作るために位置独立コードを生成する
- 使用するコンパイラの指定
  gcc と gfortran を明示的に指定する．
```
--cc=gcc13 -C acg gcc13 -C ic gcc13 -C xc gcc13 -C dk gcc13 -C dm gcc13 -C if gfortran13
```
- LAPACK の組み込み
  configure コマンドの引数に「--with-netlib-lapack-tarfile=/tmp/lapack-3.12.1.tar.gz」を付けると，ATLAS が LAPACK のソースコードを展開してビルドし，ATLAS で最適化したルーチンを含む liblapack.a を生成する．
configure コマンドの結果の確認
「make」の実行
```
make
```
自動チューニングを行うため，完了までに数時間かかることがある．
「make」の結果，エラーメッセージが出ないことを確認しておく．
「make check」の実行
```
make check
```
「make check」の結果，エラーメッセージが出ないことを確認しておく．
「make ptcheck」の実行
```
make ptcheck
```
「make ptcheck」の結果，エラーメッセージが出ないことを確認しておく．マルチスレッド版のライブラリの検査である．
make time の実行
```
make time
```
make time の結果の確認
「make time」の結果，エラーメッセージが出ないことを確認しておく．
「make install」の実行
```
make install
```
「make install」の結果の確認
エラーメッセージが出ていないことを確認する．
ファイルの確認
/usr/local/atlas/lib と /usr/local/atlas/include にファイルができていることを確認する．

共有オブジェクト (.so) の生成とインストール

cd lib
make shared cshared ptshared cptshared
cp *.so /usr/local/atlas/lib

CBLAS のテスト

CBLAS のソースコードを用意する
CBLAS の参照実装とサンプルプログラムは，LAPACK の配布物の CBLAS ディレクトリに含まれている．前準備でダウンロードした tar ファイルを展開する．
```
cd /tmp
tar -xzf lapack-3.12.1.tar.gz
```
サンプルプログラムのテスト実行
```
cd /tmp/lapack-3.12.1/CBLAS/examples
gcc13 -I/usr/local/atlas/include cblas_example1.c -L/usr/local/atlas/lib -lptcblas -lptf77blas -latlas -lpthread -L/usr/local/lib/gcc13 -lgfortran
./a.out
```
cblas_example1.c では，次を確認できる．
- cblas_dgemv() : 行列とベクトルの積
- ベクトルの要素の間隔を表す引数は incx = 1, incy = 1 になっている（連続した配列を使うという意味）