SPARTAというDSMCのオープンソースコードのセットアップ方法

# はじめに

[SPARTA Direct Simulation Monte Carlo (DSMC) Simulator](https://sparta.github.io/index.html)とは、Stochastic PArallel Rarefied-gas Time-accurate Analyzerの頭文字をとったもので、DSMCのオープンソースコードである。
[ここ](https://sjplimp.github.io//download.html)からダウンロードし、基本的にはドキュメント通りにやっていけば問題なく動く。
これはセットアップ方法の備忘録である。

やったことは以下の通りである。
- ダミーMPIライブラリの作成
- JPEGライブラリのインストール
- JPEG出力に対応させる
- make
- テスト計算
  - 標準的なアウトプット
  - スナップショットデータのアウトプット
  - スナップショット画像のアウトプット
  - 動画への変換

# makeまでの道のり
## まずはエラー文

doc/Section_start.htmlを参考に作業していく。
まずはsrcのディレクトリに移る。
以下のコマンドで、makeのオプションが出力される。
~~~
src % make
~~~
このうち、
~~~
# mac = Apple PowerBook laptop, c++, serial (no MPI)
~~~
が今回のコンパイル環境である。
no MPIというのがポイント。

とりあえず以下のコマンドを実行。
~~~
src % make mac
~~~
そしてエラー文が出力される。
~~~
ld: library not found for -lmpi_stubs
clang: error: linker command failed with exit code 1 (use -v to see invocation)
~~~
lmpi_stubsがないらしいが、これはmpiに関するもので、mpiがなくてもシングルコアで動かせるはずである。

## ダミーMPIライブラリの作成

ドキュメントのStep 5にも書いてあるように、シングルコアで動かしたい場合はダミーMPIライブラリを作ることができる。
~~~
src % make mpi-stubs
~~~
なにか警告は出たが、makeは通った。

## makeの成功

~~~
src % make clean-all
src % make mac
~~~
これで無事、spa_macが作成できた。

# テスト計算
## 標準的なアウトプット

前提として、インプットファイル in.* (たとえばin.free)と同じディレクトリにspa_macをコピーする必要がある。
まずはベンチマークのものを使うことにする。
~~~
src % cp spa_mac ../bench
~~~

インプットファイルと同じディレクトリに移動し、以下のコマンドを入力。
~~~
bench % ./spa_mac < in.free
~~~
すると、log.spartaというファイルが作られる。

## スナップショットデータのアウトプット

インプットファイルのstats_styleの次の行に以下を追加。
~~~in.free_v2
dump 1 particle all 10 dump.position.* id type xs ys zs vx vy vz
~~~
詳しくはdoc/dump.htmlに書いてある。
- dump: 出力(?)
- 1: 適当に付ける名前
- particle: スタイル。他にはgrid, surf, image
- all: どの粒子を出力するか
- 10: 出力するタイムステップ
- dump.position.*: 出力するファイル
- id type xs ys zs vx vy vz: 出力する中身。typeというのは粒子の化学種(?)。x, y, zのあとのsはscaledという意味。

これで出力は
~~~
dump.position.0
dump.position.10
dump.position.100
dump.position.110
dump.position.120
dump.position.130
dump.position.20
dump.position.30
dump.position.40
dump.position.50
dump.position.60
dump.position.70
dump.position.80
dump.position.90
~~~
となった。

## スナップショット画像のアウトプット

doc/dump_image.htmlを見ると、画像のアウトプットもしてくれそうである。
doc/dump_modify.htmlも参考にしながら、インプットファイルに以下を追加。
~~~in.free_v3
dump 1 image all 10 dump.*.jpg type type pdiam 3.0e-6 size 512 512 gline yes 0.005
dump_modify	1 pad 4
~~~
- dump: 出力
- 1: 適当に付ける名前
- image: スタイル、他にはmovie
- all: どの粒子を出力するか
- 10: 出力するタイムステップ
- dump.*.jpg: 出力するファイル
- type: particle attribute that determines color of each particle (粒子の色を決める属性を粒子の化学種typeにする)
- type: particle attribute that determines size of each particle (粒子のサイズを決める属性を粒子の化学種typeにする)
- pdiam 3.0e-6: numeric value for particle diameter (distance units) (粒子の直径の値)
- size 512 512: size of images (画像のサイズを幅・高さ pixels で)
  - width = width of image in # of pixels
  - height = height of image in # of pixels
- gline yes 0.005: draw outline of each grid cell (グリッドを描くか・グリッドの直径）
  - yes/no = do or do not draw grid cell outlines
  - diam = diameter of grid outlines as fraction of shortest box length
- dump_modify: 出力コマンドを修正
- 1: 修正するコマンド名
- pad 4: 4桁 (0000)にする

ちなみに、type以降の文法はよくわからなかったのでexamples/free/in.freeをコピペした。
今後もbenchよりはexamplesを参考にしたほうがいいかもしれない。

### しかし、エラーが出る

~~~
ERROR: Support for writing images in JPEG format not included (../dump_image.cpp:82)
~~~

doc/Section_start.html#start_2に書いてある通り、MAKEディレクトリ下で新たなMakefileを作る。
~~~
MAKE % cp Makefile.mac Makefile.foo
~~~

以下のように編集。
~~~Makefile.foo
# foo = Apple PowerBook laptop, c++, serial (no MPI)
...
SPARTA_INC =	-DSPARTA_GZIP -DSPARTA_UNORDERED_MAP -DSPARTA_JPEG
~~~

以下のコマンドを入力。
~~~
src % make clean-all
src % make foo
~~~

しかし、エラーが出る。
~~~
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
~~~

### HomebrewでのJPEGライブラリのインストール

~~~
% brew install jpeg 
~~~
最後に以下のメッセージが現れた。
~~~
If you need to have jpeg first in your PATH, run:
  echo 'export PATH="/opt/homebrew/opt/jpeg/bin:$PATH"' >> ~/.zshrc

For compilers to find jpeg you may need to set:
  export LDFLAGS="-L/opt/homebrew/opt/jpeg/lib"
  export CPPFLAGS="-I/opt/homebrew/opt/jpeg/include"

For pkg-config to find jpeg you may need to set:
  export PKG_CONFIG_PATH="/opt/homebrew/opt/jpeg/lib/pkgconfig"
==> Summary
🍺  /opt/homebrew/Cellar/jpeg/9f: 21 files, 904.6KB
~~~

それにならい、以下のようにMakefileを編集
~~~Makefile.foo
JPG_INC = -I/opt/homebrew/opt/jpeg/include
JPG_PATH = -L/opt/homebrew/opt/jpeg/lib
JPG_LIB = -ljpeg
~~~

そして以下のコマンドを入力。
~~~
src % make clean-all
src % make foo
~~~
ついに成功！

### スナップショット画像のアウトプット(再)

~~~
bench % ./spa_foo < in.free_v3
~~~
これで以下の画像が出力された。
~~~
dump.0000.jpg
dump.0010.jpg
dump.0020.jpg
dump.0030.jpg
dump.0040.jpg
dump.0050.jpg
dump.0060.jpg
dump.0070.jpg
dump.0080.jpg
dump.0090.jpg
dump.0100.jpg
dump.0110.jpg
dump.0120.jpg
dump.0130.jpg
~~~

### 画像から動画へ

~~~
bench % convert -delay 10 -loop 0 dump*.jpg dump.mpg &
~~~
dump movieでもできるらしいが、自分で作っても問題ないはずだ。

### コマンドの文法が合わないときのエラー文
~~~
ERROR: Illegal dump image command (../dump_image.cpp:91)
~~~
こういうときは、ドキュメントを見るよりもexamplesのインプットファイルを見たほうが早い。

# おわりに

オープンソースコードを使うのは初めてで、なかなか動くまでに苦労した気がするが、SPARTAはオプションが豊富で、使いこなせれば応用先は広いように感じた。
新しい計算機になったときに同じような環境構築が必要になると思われるので、そのときにはまた頑張っていきたいと思う。