convolution.py テクニカルドキュメント

プログラムの動作

convolution.py は、指定されたCSVファイルからX-Yデータを読み込み、ガウス関数を用いてそのデータを平滑化（スムージング）するPythonプログラムです。平滑化されたデータは新たなCSVファイルとして保存され、同時に元のデータと平滑化されたデータの両方をグラフとして表示します。 このプログラムの主な機能は以下の通りです。

  • データ読み込み: CSVファイルから2列の数値データ（x座標とy座標）を読み込みます。

  • ガウス畳み込み: 読み込んだデータに対して、指定された幅（width）のガウス関数を使った畳み込み演算を適用し、データを平滑化します。

  • 結果の保存: 平滑化されたデータと元のデータを比較できるように、3列（x、元のy、平滑化されたy）のCSVファイルとして結果を保存します。

  • グラフ表示: matplotlib ライブラリを使用して、元のデータと平滑化されたデータを同一のグラフ上にプロットし、視覚的に比較できるようにします。

本プログラムは、実験データやシミュレーション結果に含まれるノイズを除去し、 underlying な傾向を抽出する目的で利用できます。

原理

このプログラムの核となるのは、ガウス畳み込み（Gaussian Convolution）による平滑化です。ガウス畳み込みは、各データ点に対してガウス関数（正規分布の確率密度関数）を重みとして適用し、その点とその周辺のデータ点の加重平均を計算することで、データを滑らかにする手法です。

プログラム中で使用されているガウス関数 \(K(x_d)\) は、幅 width をパラメータとして持ち、以下の形式で表現されます。

\[K(x_d) = \frac{1}{\sqrt{\pi} \cdot \text{width}} \exp\left(-\left(\frac{x_d}{\text{width}}\right)^2\right)\]

ここで、\(x_d\) は中心からの距離です。このガウス関数は、全範囲で積分すると1になるように正規化されています。 プログラムは、離散データ \(y_j\) に対して、以下のように平滑化されたデータ \(Y_i\) を計算します。

\[Y_i = \sum_{j} y_j \cdot K(x_i - x_j) \cdot \Delta x\]

ただし、プログラムの実装では、各入力データ点 \(y_j\) が周囲の出力点 \(Y_{j+k}\) にどのように寄与するかを計算する形で実装されています。具体的には、convolution 関数内で次のような計算が行われます。

ys[j+k] += y0 * dx * coeff * exp(-dvx*dvx)

ここで、y0 は元のデータ \(y_j\)、dx はX軸のデータ間隔、coeff はガウス関数の正規化係数 \(\frac{1}{\sqrt{\pi} \cdot \text{width}}\)、dvx は距離 \(k \cdot \Delta x\) を width で割った値 \(\frac{k \cdot \Delta x}{\text{width}}\) に相当します。この計算をすべてのデータ点と周辺範囲について行うことで、データ全体の平滑化を実現しています。

width パラメータはガウス関数の広がりを制御し、平滑化の度合いを決定します。width の値を大きくすると、より広範囲のデータ点が平均化されるため、結果としてより強く平滑化された（より滑らかな）データが得られます。逆に width を小さくすると、平滑化の効果は弱まります。

必要な非標準ライブラリとインストール方法

convolution.py の実行には、以下の非標準Pythonライブラリが必要です。

  • matplotlib: データのグラフ表示に使用されます。

これらのライブラリは pip コマンドを使用してインストールできます。コマンドライン（ターミナルまたはコマンドプロンプト）で以下のコマンドを実行してください。

pip install matplotlib

必要な入力ファイル

プログラムは、CSV形式の入力ファイルを必要とします。デフォルトのファイル名は dos.csv です。

  • ファイル形式: カンマ区切り値 (CSV)

  • データ構造:

    • 1行目: プログラムは next(fin) でこの行をスキップします。したがって、任意のヘッダー情報を記述できます。

    • 2行目: プログラムは、この行をラベルとして読み込み、コンソールに表示します。例えば、"x_label,y_label" のように記述します。

    • 3行目以降: 実際の数値データが格納されます。各行は少なくとも2つの列を持ち、最初の2列が浮動小数点数に変換可能なデータ (x と y 座標) である必要があります。

    • データの読み込みは、最初の列が空文字列の行に到達すると終了します。

dos.csv の例:

Header for this data set,e.g., Run 1
Energy,DOS
0.0,0.1
0.1,0.2
0.2,0.4
0.3,0.7
0.4,1.0
0.5,0.9
0.6,0.7
0.7,0.5
0.8,0.3
0.9,0.2
1.0,0.1
1.1,0.05

この例では、Energy,DOS がラベルとして扱われ、0.0,0.1 から始まる行が実際のデータとして読み込まれます。

生成される出力ファイル

プログラムは、平滑化されたデータを含むCSVファイルを生成します。デフォルトのファイル名は convolution.csv です。

  • ファイル形式: カンマ区切り値 (CSV)

  • データ構造:

    • 1行目: ヘッダー行として x,y(raw),y(smooth) が書き込まれます。

    • 2行目以降: 各行に、元のx座標、元のy座標、およびガウス畳み込みによって平滑化されたy座標が格納されます。

convolution.csv の例 (出力の一部):

x,y(raw),y(smooth)
0.0,0.1,0.12651139789312526
0.1,0.2,0.24580226998656654
0.2,0.4,0.4357288647047976
0.3,0.7,0.6865223390236402
...

コマンドラインでの使用例 (Usage)

convolution.py は、オプションでガウス畳み込みの width パラメータをコマンドライン引数として受け取ります。

python convolution.py [width]

  • [width] (オプション): ガウス関数の広がりを指定する浮動小数点数です。この値が大きいほど、データはより強く平滑化されます。省略した場合、デフォルト値の 0.2 が使用されます。

コマンドラインでの具体的な使用例

以下の例では、上記「必要な入力ファイル」で示した dos.csv を入力ファイルとして使用します。

例1: デフォルトの width (0.2) で実行

python convolution.py

実行結果の説明:

  • プログラムは dos.csv を読み込み、デフォルトの width=0.2 でデータを平滑化します。

  • コンソールには、データの読み込み状況、ラベル行、元のデータと平滑化されたデータがタブ区切りで出力されます。

  • convolution.csv というファイルが作成され、x、元のy、平滑化されたyのデータが保存されます。

  • 元のデータと平滑化されたデータを示すグラフウィンドウが表示されます。ウィンドウを閉じるには、コンソールで Enter キーを押します。

例1のコンソール出力例:

Read data from [dos.csv]
Energy	DOS
x	y
0.0	0.1
0.1	0.2
0.2	0.4
0.3	0.7
0.4	1.0
0.5	0.9
0.6	0.7
0.7	0.5
0.8	0.3
0.9	0.2
1.0	0.1
1.1	0.05

Smoothing by convolution with Gauss function of w = 0.2
0.0	0.1	0.12651139789312526
0.1	0.2	0.24580226998656654
0.2	0.4	0.4357288647047976
0.3	0.7	0.6865223390236402
0.4	1.0	0.9167385203792019
0.5	0.9	0.9231267597193233
0.6	0.7	0.7486411586526154
0.7	0.5	0.5284074219416248
0.8	0.3	0.3182888640776993
0.9	0.2	0.1764357777717462
1.0	0.1	0.09106067677840833
1.1	0.05	0.04689625345758079
Write to [convolution.csv]

Press ENTER to exit>>

例2: width を 0.1 に指定して実行

python convolution.py 0.1

実行結果の説明:

  • プログラムは dos.csv を読み込み、指定された width=0.1 でデータを平滑化します。

  • コンソール出力は例1と同様ですが、平滑化の width の値が 0.1 と表示され、それに伴い平滑化された y の値も変化します。

  • convolution.csv にも更新されたデータが保存されます。

  • グラフウィンドウが表示されます。width=0.1 はデフォルトの 0.2 よりも小さいため、グラフ上の平滑化されたデータは元のデータにより近い形（より少ない平滑化）を示します。

例2のコンソール出力例 (一部):

Read data from [dos.csv]
Energy	DOS
x	y
... (データ読み込みは例1と同様)

Smoothing by convolution with Gauss function of w = 0.1
0.0	0.1	0.10901594580041696
0.1	0.2	0.21855877478663857
0.2	0.4	0.4075591350614392
0.3	0.7	0.6729215037149306
... (平滑化されたyの値が異なる)
Write to [convolution.csv]

Press ENTER to exit>>