plot3d プログラム仕様

VASP体積データ可視化ツール (plot3d.py)

概要:

VASPのCHGCARファイルから電荷密度やELFなどの体積データを読み込み、 3D空間に等値面、高密度点群、またはスライス面として可視化するスクリプト。

詳細説明:

本スクリプトは、VASP計算で得られた電荷密度やELFなどの体積データファイル（CHGCAR形式）を解析し、 そのデータをmatplotlibとscikit-image (skimage) のmarching_cubesアルゴリズム、 およびカスタムのtkPlot3dユーティリティを使用して3次元で描画します。 ユーザーは、等値面レベルの指定、データ点群のフィルタリング、特定の分率座標でのスライス表示、 ダウンサンプリングによるパフォーマンス向上などのオプションを通じて、 データの詳細な分析と美しい図の生成が可能です。 matplotlibの3Dプロット機能に依存しており、等値面生成にはscikit-imageが必要です。

関連リンク:

plot3d.py 技術ドキュメント （本スクリプトの使用方法に関する詳細ドキュメント）

Viewer.plot3d.build_cartesian_grid(lattice, nx, ny, nz, dtype=<class 'numpy.float32'>)

分率座標から直交座標への変換に基づき、3次元直交座標グリッドを構築する。

概要:

指定された格子ベクトルとグリッド分割数を用いて、空間の各点に対応する 直交座標のメッシュデータを生成する。

詳細説明:

まず、各軸に沿って正規化された分率座標 (0から1まで) の配列を生成し、 これらを np.meshgrid で組み合わせて3次元分率座標グリッドを作成する。 その後、この分率座標を lattice (格子ベクトル) を使って直交座標に変換する。 これにより、体積データが定義されている空間の物理的なX, Y, Z座標が計算される。

パラメータ:

• lattice -- numpy.ndarray, (3, 3) 形状の格子ベクトル行列。各行が基底ベクトル。

• nx -- int, X軸方向のグリッド点数。

• ny -- int, Y軸方向のグリッド点数。

• nz -- int, Z軸方向のグリッド点数。

• dtype -- numpy.dtype, 座標値の格納に使用するNumPyデータ型。

戻り値:

tuple, - X (numpy.ndarray): X座標の3次元グリッド (nx, ny, nz)。 - Y (numpy.ndarray): Y座標の3次元グリッド (nx, ny, nz)。 - Z (numpy.ndarray): Z座標の3次元グリッド (nx, ny, nz)。

戻り値の型:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Viewer.plot3d.downsample_volume(F, dsx, dsy, dsz)

3次元体積データを指定されたステップでダウンサンプリングする。

概要:

NumPy配列として与えられた体積データ F を、各軸 (X, Y, Z) に沿って 指定された間隔で間引くことでダウンサンプリングする。

詳細説明:

データの各軸に対してスライシング [::step] を適用し、 より少ないデータ点数で元のボリュームを表現する。 これにより、可視化処理のパフォーマンスを向上させることができる。

パラメータ:

• F -- numpy.ndarray, (nx, ny, nz) 形状の元の3次元体積データ。

• dsx -- int, X軸方向のダウンサンプリングステップサイズ。1はダウンサンプリングなし。

• dsy -- int, Y軸方向のダウンサンプリングステップサイズ。1はダウンサンプリングなし。

• dsz -- int, Z軸方向のダウンサンプリングステップサイズ。1はダウンサンプリングなし。

戻り値:

numpy.ndarray, ダウンサンプリングされた3次元体積データ。

戻り値の型:

numpy.ndarray

Viewer.plot3d.fractional_spacing_after_downsampling(nx, ny, nz, dsx, dsy, dsz)

ダウンサンプリング後のデータにおける分率座標でのグリッド間隔を計算する。

概要:

元のグリッドサイズとダウンサンプリングステップから、 ダウンサンプリング後の論理的な分率間隔を算出する。

詳細説明:

skimage.measure.marching_cubes 関数に渡す spacing パラメータは、 実際のデータ点間の相対的な間隔を表す。ダウンサンプリングを行った場合、 この間隔は元のグリッド間隔にダウンサンプリングステップを掛けたものになる。 例えば、nx=100でdsx=2の場合、元の分率間隔は1/100だが、ダウンサンプリング後は 2/100となる。

パラメータ:

• nx -- int, 元のX軸方向のグリッド点数。

• ny -- int, 元のY軸方向のグリッド点数。

• nz -- int, 元のZ軸方向のグリッド点数。

• dsx -- int, X軸方向のダウンサンプリングステップサイズ。

• dsy -- int, Y軸方向のダウンサンプリングステップサイズ。

• dsz -- int, Z軸方向のダウンサンプリングステップサイズ。

戻り値:

tuple, 各軸の分率間隔 (spacing_x, spacing_y, spacing_z)。

戻り値の型:

tuple[float, float, float]

Viewer.plot3d.main()

VASP体積データの可視化スクリプトのメインエントリポイント。

概要:

コマンドライン引数を解析し、CHGCARファイルの読み込み、データ処理、 および3Dプロットによる可視化（等値面、高密度点群、スライス面）を実行する。

詳細説明:

argparse を使用して、入力ファイル、表示モード、等値レベル、ダウンサンプリング、 スライス平面の位置、カラーマップ、透明度、出力ファイル名などの様々なオプションを 受け付ける。読み込まれたCHGCARデータは、必要に応じてダウンサンプリングされ、 指定されたモードでmatplotlibの3Dプロットとして描画される。 結果は画面に表示されるか、画像ファイルとして保存される。

Param:

None, コマンドライン引数からパラメータを受け取るため、関数としての引数はない。

戻り値:

None

Viewer.plot3d.parse_fracs(str_list)

文字列のリストから浮動小数点数のリストをパースするユーティリティ関数。

概要:

コマンドライン引数などで渡される文字列のリストを浮動小数点数のリストに変換する。

詳細説明:

例えば、["0.25", "0.5"] のような文字列のリストを受け取り、 [0.25, 0.5] のような浮動小数点数のリストを返す。 入力が None の場合は空のリストを返す。

パラメータ:

str_list -- list of str or None, パースする文字列のリスト。

戻り値:

list of float, パースされた浮動小数点数のリスト。

戻り値の型:

list[float]

Viewer.plot3d.plot_isosurfaces_fractional(ax, F, lattice, levels, alpha=0.3, edgecolor='none', linewidth=0.0, colors=None, spacing_frac=(1, 1, 1), legend=True, antialias=False)

3次元体積データから等値面を抽出し、直交座標系で描画する。

概要:

skimage.measure.marching_cubes を使用して指定された等値レベルの面を抽出し、 それを直交座標に変換してmatplotlibの3D軸上に描画する。

詳細説明:

F は分率座標での体積データと見なされ、marching_cubes 関数に spacing_frac を指定して等値面を抽出する。得られた頂点データは 分率座標であるため、lattice (格子ベクトル) を用いて直交座標に変換される。 その後、tk3d.Poly3DCollection を使ってメッシュとして描画される。 複数の等値レベルに対応し、それぞれ異なる色で描画することが可能。 凡例の表示もサポートする。

パラメータ:

• ax -- matplotlib.axes.Axes, 3D描画を行うmatplotlibの軸オブジェクト。

• F -- numpy.ndarray, (nx, ny, nz) 形状の3次元体積データ。

• lattice -- numpy.ndarray, (3, 3) 形状の格子ベクトル行列。各行が基底ベクトル。

• levels -- list of float, 描画する等値レベルのリスト。

• alpha -- float, 等値面の透明度 (0.0:完全に透明, 1.0:完全に不透明)。

• edgecolor -- str or tuple, 等値面の辺の色。'none' で辺を描画しない。

• linewidth -- float, 等値面の辺の太さ。

• colors -- list of str or tuple, 各等値レベルに対応する色のリスト。Noneの場合、デフォルトのカラーマップが使用される。

• spacing_frac -- tuple of float, marching_cubes に渡す各軸の分率グリッド間隔 (dx, dy, dz)。

• legend -- bool, 等値レベルの凡例を表示するかどうか。

• antialias -- bool, 等値面をアンチエイリアス処理するかどうか。

戻り値:

None

Viewer.plot3d.read_chgcar(filename, dtype=<class 'numpy.float32'>)

VASPのCHGCARファイルを読み込み、ヘッダー情報と体積データを抽出する。

概要:

指定されたVASP CHGCARファイルから結晶情報と3次元の体積データを読み込む。

詳細説明:

CHGCARファイルのフォーマットに従い、タイトル、スケール因子、格子ベクトル、 原子の種類と数、座標タイプ、原子座標、グリッドサイズ、そして電荷密度などの 体積データをパースする。空行のスキップに対応し、データの読み込み時にNumPyの データ型 (dtype) を指定できる。

パラメータ:

• filename -- str, 読み込むCHGCARファイルのパス。

• dtype -- numpy.dtype, 体積データの格納に使用するNumPyデータ型 (例: np.float32, np.float64)。

戻り値:

tuple, - info (dict): CHGCARヘッダーから抽出された情報を格納した辞書。

'title', 'scale', 'lattice', 'atoms', 'numbers', 'coord_type', 'coords', 'grid' のキーを含む。

• P (list of lists of lists): グリッドデータ F を [[[F[i,j,k] for k] for j] for i] 形式にしたもの。

  （既存コードの形式を維持）

• F (numpy.ndarray): 読み込まれた体積データを格納した (nx, ny, nz) 形状の3次元NumPy配列。

戻り値の型:

tuple[dict, list, numpy.ndarray]

Viewer.plot3d.render_slice_plane(ax, lattice, F, which, frac, cmap='viridis', alpha=0.6)

指定された分率座標に沿ってスライス面を抽出し、直交座標系で描画する。

概要:

3D体積データ F から、特定の分率座標 (frac) で切り取られた2Dスライス面を抽出し、 それを直交座標に変換して3Dプロットに描画する。

詳細説明:

which パラメータ ('xy', 'yz', 'zx') に応じて、対応する軸の分率座標 (frac) を固定し、 他の2軸に沿ったスライスデータを抽出する。このスライスデータから _facecolors_from_vals を用いて各面のRGBA色を生成し、格子ベクトル lattice を使って直交座標を計算する。 最終的に tk3d.plot_surface3d を用いて、色付けされたスライス面を3D軸上に配置する。

パラメータ:

• ax -- matplotlib.axes.Axes, 3D描画を行うmatplotlibの軸オブジェクト。

• lattice -- numpy.ndarray, (3, 3) 形状の格子ベクトル行列。各行が基底ベクトル。

• F -- numpy.ndarray, (nx, ny, nz) 形状の3次元体積データ。

• which -- str, スライスする平面の方向 ('xy', 'yz', 'zx')。 - 'xy': fz (Z軸の分率座標) が frac に固定される。 - 'yz': fx (X軸の分率座標) が frac に固定される。 - 'zx': fy (Y軸の分率座標) が frac に固定される。

• frac -- float, スライスする分率座標 (0.0から1.0の範囲)。

• cmap -- str or matplotlib.colors.Colormap, スライス面の描画に使用するカラーマップ。

• alpha -- float, スライス面の透明度 (0.0:完全に透明, 1.0:完全に不透明)。

戻り値:

None

例外:

ValueError -- which が 'xy', 'yz', 'zx' のいずれでもない場合。