bz_draw プログラム仕様
第一ブリルアンゾーンまたは実空間のウィグナー・ザイツセル描画スクリプト。
このスクリプトは、指定された結晶学的パラメータと格子タイプに基づいて、 第一ブリルアンゾーン（逆空間）またはウィグナー・ザイツセル（実空間）を3Dで可視化します。 さらに、周囲の周期的なセルをタイリング表示する機能、高対称点のパス表示（逆空間の場合）、 およびインタラクティブなパラメータ調整機能（スライダーとApplyボタン）を提供します。
- class crystal.bz_draw.SceneManager(args)[ソース]
ベースクラス:
objectMatplotlibの3Dシーンを管理し、描画オブジェクト（アーティスト）の追加、クリア、更新を行います。
特に、描画のたびに既存のオブジェクトを効率的に削除し、新しいオブジェクトを追加することで、 インタラクティブな描画でのちらつきを抑え、高速な更新を可能にします。
- add_artist(*objs)[ソース]
新しいMatplotlibアーティストを管理リストに追加します。
描画されたアーティストは、後で clear_artists メソッドで効率的に削除できるように このリストに格納されます。リストやタプルの形式で複数のアーティストを渡すことも可能です。
- draw_scene(space, A_prim, Bstd, n_shell, tile_nx, tile_ny, tile_nz, tile_rmax, show_outside_points, highlight_face_points, draw_connectors_to_faces, draw_kpath, color_mode='checker', fade_power=1.0, kpts_abs=None, kpath=None, label_fontsize=10)[ソース]
第一ブリルアンゾーンまたはウィグナー・ザイツセル、およびそのタイリングされたビューを描画します。
空間タイプ（実空間または逆空間）に応じてVoronoi図を構築し、 中心セル、面生成点、周期タイル、高対称点とパス（逆空間の場合のみ）を描画します。 既存のアーティストをクリアし、新しいアーティストを追加する差分更新方式を採用しています。
- パラメータ:
space (str) -- 描画する空間タイプ ('reciprocal' または 'real')
A_prim (numpy.ndarray) -- 原始3x3格子基底行列（実空間の基底）
Bstd (numpy.ndarray or None) -- 標準逆格子3x3基底行列（逆空間の基底、2π因子を含む）
n_shell (int) -- Voronoi計算のために考慮する格子点/逆格子点のシェル数
tile_nx (int) -- x軸方向のタイルの最大数（0で非表示）
tile_ny (int) -- y軸方向のタイルの最大数（0で非表示）
tile_nz (int) -- z軸方向のタイルの最大数（0で非表示）
tile_rmax (float or None) -- タイル描画の半径上限（中心から距離 r <= rmax のセルのみ描画） Noneまたは0以下の場合、距離による制限なし
show_outside_points (bool) -- セル外部の格子点/逆格子点を表示するかどうか
highlight_face_points (bool) -- セルの面を定義する点を強調表示するかどうか
draw_connectors_to_faces (bool) -- 面を定義する点と原点を結ぶ破線を描画するかどうか
draw_kpath (bool) -- 高対称点パスを描画するかどうか（reciprocal空間のみ有効）
color_mode (str) -- タイルの色付けモード ('checker', 'byindex', 'distance')
fade_power (float) -- 距離に応じた透明度フェードの指数
kpts_abs (dict[str, numpy.ndarray] or None) -- 高対称点の絶対座標を格納した辞書 (reciprocal空間の場合のみ)
kpath (list[tuple[str, str]] or None) -- 高対称点パスのリスト (reciprocal空間の場合のみ)
label_fontsize (int) -- 高対称点ラベルのフォントサイズ
- crystal.bz_draw.alpha_fade(t, rmax, a_min=0.06, a_max=0.22, power=1.0)[ソース]
原点からの距離に基づいて透明度をフェードさせる値を返します。
点の位置ベクトル t の原点からの距離が rmax に近づくにつれて、 透明度が a_max から a_min へとフェードアウトするように計算されます。 power パラメータでフェードの非線形性を調整できます。
- crystal.bz_draw.build_conventional_basis(a, b, c, alpha, beta, gamma)[ソース]
従来の結晶学的パラメータから直交座標系における格子基底ベクトルを構築します。
最初の基底ベクトルをx軸に沿わせ、2番目の基底ベクトルをxy平面に置き、 3番目の基底ベクトルを正のz成分を持つように配置します。
- crystal.bz_draw.bz_and_kpath_from_seekpath_cached(A_prim, symprec=1e-07)[ソース]
seekpath を用いて、第一ブリルアンゾーンの標準逆格子基底、高対称点、およびパスを取得します。
_seekpath_cached を通じて functools.lru_cache によるキャッシュを利用するため、 同じ原始格子基底に対しては seekpath の計算がスキップされ、高速に結果を返します。
- crystal.bz_draw.cell_polygons(vor, point_index)[ソース]
Voronoi図の中心点に関連する多角形（セル面）と隣接点のリストを生成します。
get_cell_faces_and_neighbors を利用して面の頂点インデックスを取得し、 order_polygon_vertices_on_plane で頂点を反時計回りに順序付けて多角形オブジェクトを構築します。
- crystal.bz_draw.color_checker(i, j, k)[ソース]
三次元インデックス (i,j,k) に基づいてチェッカーボード状の色を返します。
各インデックスの偶奇性から0から7までのインデックスを生成し、 定義されたパレットから色を選択します。
- crystal.bz_draw.color_distance(t, rmax, cmap=<matplotlib.colors.ListedColormap object>)[ソース]
原点からの距離に基づいてグラデーション色を返します。
点の位置ベクトル t の原点からの距離を計算し、rmax で正規化して 指定されたカラーマップ cmap から色を抽出します。
- crystal.bz_draw.color_hash(i, j, k, cmap=<matplotlib.colors.ListedColormap object>)[ソース]
三次元インデックス (i,j,k) に基づいてハッシュ値から色を生成します。
与えられた整数インデックスから一意のハッシュ値を生成し、 そのハッシュ値を正規化して指定されたカラーマップから色を抽出します。
- crystal.bz_draw.get_cell_faces_and_neighbors(vor, point_index)[ソース]
Voronoi図の中心点に関連する面の頂点インデックスと隣接点のインデックスを取得します。
Voronoiオブジェクトのridge_pointsとridge_verticesを走査し、 指定された点に関連する有限な面（-1を含まない、3頂点以上）を抽出します。
- crystal.bz_draw.main()[ソース]
プログラムのエントリーポイントです。
コマンドライン引数を解析し、ユーザーの選択に応じて 第一ブリルアンゾーンまたはウィグナー・ザイツセルの描画機能 （一度きりの描画またはインタラクティブな描画）を呼び出します。
- crystal.bz_draw.order_polygon_vertices_on_plane(P)[ソース]
平面上にある多角形の頂点を反時計回りに並べ替えるインデックスを返します。
頂点の重心を計算し、SVD（特異値分解）を用いて平面の法線ベクトルを決定します。 その後、基準ベクトルと法線に垂直なベクトルを生成し、これらの座標系で各頂点の角度を計算してソートします。 この順序はMatplotlibで多角形を描画する際に重要です。
- パラメータ:
P (numpy.ndarray) -- 多角形の頂点群を表すNx3のNumPy配列。
- 戻り値:
頂点を反時計回りに並べ替えるためのインデックスの配列。
- 戻り値の型:
numpy.ndarray
- crystal.bz_draw.plot_interactive_apply(args)[ソース]
スライダーと「Apply」ボタンを備えたインタラクティブな描画インターフェースを提供します。
a, b, c の格子定数をスライダーで調整でき、「Apply」ボタンをクリックしたときにのみ シーンが再描画されます。seekpath の結果はキャッシュされるため、 再描画時の計算コストが削減され、高速な更新が可能です。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数を格納するargparse.Namespaceオブジェクト
- crystal.bz_draw.plot_once(args)[ソース]
指定されたパラメータに基づいて、第一ブリルアンゾーンまたはウィグナー・ザイツセルを一度だけ描画します。
結晶学的パラメータから格子基底を構築し、SceneManager を使用してシーンを描画し、 結果をMatplotlibウィンドウに表示します。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数を格納するargparse.Namespaceオブジェクト
- 例外:
SystemExit -- seekpath の実行に失敗した場合
- crystal.bz_draw.primitive_from_centering(A_conv, lattice_tag)[ソース]
従来の格子基底と格子タイプから原始格子基底を計算します。
与えられた従来の格子基底に対し、指定されたセンタリングタイプ（P, I, Fなど）に 対応する変換行列を適用して原始格子基底を導出します。
- パラメータ:
A_conv (numpy.ndarray) -- 従来の3x3格子基底行列（列が基底ベクトル）
lattice_tag (str) -- 格子タイプを示す文字列 (例: 'P', 'I', 'F', 'SC', 'BCC', 'FCC', 'A', 'B', 'C')
- 戻り値:
原始3x3格子基底行列（列が原始基底ベクトル）
- 戻り値の型:
numpy.ndarray
- 例外:
ValueError -- 未知の格子タイプまたは未サポートの格子タイプが指定された場合
- crystal.bz_draw.reciprocal_points_from_basis(B, n)[ソース]
与えられた基底ベクトルとシェル数に基づいて、格子点または逆格子点の配列を生成します。
各基底ベクトルの整数倍（-nからnまで）の組み合わせで、中心の点を含む広範囲の点を生成します。 これはVoronoi図の計算に必要な点群を提供します。
- パラメータ:
B (numpy.ndarray) -- 3x3の基底ベクトル行列（列が基底ベクトル）
n (int) -- 各基底ベクトルに沿って考慮するシェル数（例: n=1なら-1,0,1の係数を使用）
- 戻り値:
生成された点群のNx3のNumPy配列
- 戻り値の型:
numpy.ndarray