interpolate3d_fft.py のソースコード解析に基づいた、Sphinx（MyST）でビルド可能なMarkdownドキュメントを以下に示します。

`interpolate3d_fft.py` ドキュメント

ファイル概要

ファイル名: interpolate3d_fft.py
説明: 3次元周期データのFFTを用いた補間処理を提供します。

このモジュールは、フーリエ変換とゼロパディングを利用して、3次元空間に周期的に配置された離散データを高解像度化するための関数を含みます。主に科学技術計算や画像処理の分野で、データの補間やアップサンプリングに利用されます。
目的: 3次元の等間隔周期データをFFT（高速フーリエ変換）を用いて補間し、高解像度化すること。関連ドキュメントとして interpolate3d_fft_usage が参照されています。

非標準ライブラリ

このプログラムは、以下の非標準ライブラリを使用します。

numpy (np): 高度な数値計算、特に多次元配列（NumPy配列）の効率的な操作を可能にします。データの生成、形状操作、要素ごとの計算などに使用されます。
matplotlib.pyplot (plt): 2Dグラフの描画機能を提供します。本プログラムでは、補間前後のデータの2次元スライスを画像として表示するために使用されます。
mpl_toolkits.mplot3d.Axes3D: matplotlib の3Dプロット機能を提供します。3次元空間におけるデータ点の散布図や表面プロットを描画するために使用されます。
scipy.fft: SciPyライブラリのフーリエ変換モジュールで、高速フーリエ変換 (FFT) および逆フーリエ変換 (IFFT) の関数を提供します。具体的には、以下の関数が使用されます。
- fftn(): N次元FFTを実行します。
- ifftn(): N次元IFFTを実行します。
- fftshift(): FFTのゼロ周波数成分を配列の中心にシフトします。
- ifftshift(): fftshift() の逆操作を行い、ゼロ周波数成分を元の位置に戻します。

関数

`interpolate_3d_periodic_data_fft()`

3次元の等間隔周期データをFFT（高速フーリエ変換）で補間します。

この関数は、与えられた3次元データをフーリエ変換（FFT）により周波数領域に変換します。周波数領域において、元のデータが占める領域以外の部分をゼロで埋める（ゼロパディング）ことで、より高周波数成分がゼロであると仮定し、実空間での高解像度補間を実現します。ゼロパディングされた周波数領域データに逆フーリエ変換（IFFT）を適用することで、指定された補間倍率でサンプリングされた高解像度のデータが得られます。補間は周期境界条件を仮定して行われます。 fftshift と ifftshift を使用して、FFTのDC成分が配列の中心にくるように処理することで、ゼロパディングが適切に行われます。

引数:
- data (np.ndarray): 補間したい3次元の周期データ。形状は (Nx, Ny, Nz) である必要があります。要素のデータ型は実数または複素数に対応します。
- interp_factor (tuple): 各次元 (x, y, z) の補間倍率を示す3つの整数 (interp_x, interp_y, interp_z) のタプル。各要素は1以上の整数である必要があります。 1 を指定した場合、その次元は補間されません。
戻り値:
- np.ndarray: 補間された3次元データ。元のデータ型が実数であれば実数データが返されます。この実装では最終的に np.real を適用しているため、実数部のみが返されます。形状は (Nx * interp_x, Ny * interp_y, Nz * interp_z) となります。
例外:
- ValueError: 入力データが3次元のNumPy配列でない場合、または interp_factor が適切な形式でない場合に発生します。

使用例

概要

このセクションでは、interpolate3d_fft.py スクリプトがどのように interpolate_3d_periodic_data_fft() 関数を使用し、結果を可視化するかを示します。まず、3次元の周期的なサンプルデータを作成し、次に指定された補間倍率でデータを補間します。最後に、matplotlib を使用して、元のデータと補間後のデータを2Dスライスと3Dプロットの両方で視覚的に比較します。

実行方法

このプログラムは、Pythonインタープリタを使って直接実行できます。

python interpolate3d_fft.py

出力

プログラムを実行すると、以下の情報が標準出力に表示され、2つのグラフィックウィンドウが開きます。

標準出力:

元のデータの形状: (10, 10, 10)
補間後のデータの形状: (40, 40, 40)

グラフィック出力:
1. 最初のウィンドウ (2Dスライス):
  - 左側のサブプロットには、元のデータ original_data のX軸方向中央スライス (slice_idx_orig_x) がカラーマップ viridis で表示されます。タイトルは「Original Data (X-slice at slice_idx_orig_x)」です。
  - 右側のサブプロットには、補間後のデータ interpolated_data のX軸方向中央スライス (slice_idx_interp_x) が同様にカラーマップ viridis で表示されます。タイトルは「Interpolated Data (X-slice at slice_idx_interp_x)」です。
  - 両方のサブプロットにはカラーバーが付属し、Y軸とZ軸のラベルが表示されます。
2. 2番目のウィンドウ (3Dプロット):
  - 左側のサブプロットには、元のデータ original_data の全てのデータ点が3D散布図 (scatter) として表示されます。各点の色はデータ値に対応し、カラーマップ viridis が使用されます。タイトルは「Original Data Points」です。
  - 右側のサブプロットには、補間後のデータ interpolated_data のZ軸方向中央スライス (z_slice_idx) が3D表面プロット (plot_surface) として表示されます。表面の色はデータ値に対応し、カラーマップ viridis が使用されます。タイトルは「Interpolated Data (Z-slice at z_slice_idx)」です。
  - 両方のサブプロットにはカラーバーが付属し、X、Y、Z軸のラベルが表示されます。

これらの可視化により、FFTを用いた補間が元の離散データをより滑らかで高密度のデータに変換する様子を確認できます。

interpolate3d_fft.py ドキュメント