以下は bz_draw.py の解析結果をまとめたドキュメントです。

1) プログラムの動作
- 概要
  - 第一布居 (Brillouin zone) の描画を行うツール。実空間の Wigner–Seitzセルと逆格子の第一BZを、Voronoi分割を用いて作成・描画します。
  - 描画はタイル（周期的な繰り返しセル）の表現を用いてカラーリングする機能を持ち、スライダを使ったインタラクティブ更新や、初期描画と差分更新を実現しています。
- 主な機能
  - 格子の格子ベースを構築:
    - 正準基底 (a, b, c) と角度 (α, β, γ) から行列として基底を計算。
    - centering（中心化）情報から原始基底を決定（P、I、F、A、B、Cなどの格子タイプサポート）。
  - 序列的なセルの描画
    - Reciprocal space（第一BZ） or Real space（Wigner–Seitzセル）を選択可能。
    - Voronoi解析の結果に基づくポリゴンの作成と描画。
    - 面（セルのポリゴン）を半透明で描画し、外周を強調。
  - タイル描画
    - tile_nx, tile_ny, tile_nz で周期タイルを展開して描画。
    - tile_rmax による半径の上限制限。
    - カラーモードは:
      - checker: チェッカー風のパターン
      - byindex: 色はインデックスベースのハッシュ
      - distance: 距離に応じたグラデーション
    - alpha_fade でセルの透明度を距離に応じて設定
  - 高対称点と k-path の表示
    - reciprocal space の場合、SeekPath から得た高対称点と経路を描画
  - 描画の差分更新と UI
    - 既存のアーティストを削除して差分更新
    - インタラクティブモードではスライダと Apply ボタンで再描画
- 入力・出力
  - コマンドライン引数で格子パラメータや描画オプションを指定し、描画を表示します。

2) 必要な非標準ライブラリとインストールコマンドとインストール方法
- 必須ライブラリ（Python パッケージとして必要）
  - numpy
  - matplotlib
  - scipy
  - seekpath
  -（任意）spglib などの依存が警告出力で参照されているため、関連ライブラリが環境にあると良いです
- インストール例（pip を想定）
  - pip install numpy matplotlib scipy seekpath
  - なお「seekpath」は第一BZ/高対称点の取得に使われます。環境によっては SeekPath の追加設定が必要な場合があります。
- 備考
  - このスクリプトは spglib の DeprecationWarning をフィルタしているため、spglib 自体は必須ではない可能性がありますが、システムに Python ライブラリとして存在する場合は注意が必要です。

3) 必要な入力ファイル
- 本プログラムはファイル入力を必要とせず、コマンドライン引数で格子パラメータを与えて実行します。
- 入力としては以下のパラメータが有効です（例示）:
  - --space reciprocal|real
  - --lattice P|SC|I|BCC|F|FCC|A|B|C
  - --a, --b, --c
  - --alpha, --beta, --gamma
  - その他描画オプション（n-shell、tile-nx/y/z、tile-rmax、塗りつぶしモード等）

4) 実行後に生成される出力ファイル
- 本コードは基本的に matplotlib を用いた GUI/プロットを表示します。標準的な「出力ファイル」は生成されません（画面に描画されることが主目的）。
- ただし、CLI 引数として --save オプションが用意されていますが、現時点のコードにはこのパスへ自動保存する処理は実装されていません。将来のバージョンで対応する可能性があります。
- 実運用での出力としては、以下を想定できます:
  - 実行時のウィンドウに表示される3D描画
  - もし将来的にファイル保存機能を追加した場合は、指定パスへ画像ファイル（例: PNG/JPEG）として保存される可能性

5) コマンドラインでの使用例 (Usage)
- 基本的な reciprocal-space first Brillouin zone の描画
  - python bz_draw.py --space reciprocal --lattice P --a 1.0 --b 1.0 --c 1.0 --alpha 90 --beta 90 --gamma 90
- 実空間の Wigner–Seitz セルを描く（real space）
  - python bz_draw.py --space real --lattice F --a 1.0 --b 1.0 --c 1.0 --alpha 90 --beta 90 --gamma 90
- タイル描画を有効にする例
  - python bz_draw.py --space reciprocal --lattice P --a 1.0 --b 1.0 --c 1.0 --tile-nx 1 --tile-ny 1 --tile-nz 0 --tile-rmax 2.5 --tile-color-mode distance
- カラーモードを切替
  - python bz_draw.py --space reciprocal --lattice P --a 1.0 --b 1.0 --c 1.0 --tile-color-mode byindex
- スライダ付きのインタラクティブ更新を使う（Apply ボタン付き UI）
  - python bz_draw.py --space reciprocal --lattice P --a 1.0 --b 1.0 --c 1.0 --interactive-apply
  - インタラクティブモードで a, b, c の値をスライダで変更し、「Apply」ボタンを押して再描画
- k-path の表示を有効化／無効化
  - reciprocal space の場合、デフォルトで SeekPath の高対称点と経路を描画。経路を描かない設定は --no-kpath で無効化
  - python bz_draw.py --space reciprocal --lattice P --no-kpath
- 出力ファイルの保存（現時点では未実装の可能性あり）
  - 将来の実装を想定して、保存パスを指定する例:
  - python bz_draw.py --space reciprocal --lattice P --save ./bz_plot.png

補足
- 本プログラムは 3D 描画のため、描画をサポートする環境が必要です。GUI（Makie 等）ではなく matplotlib の 3D 図を用います。
- SeekPath を用いた高対称点・経路の取得にはネット接続が不要な形でキャッシュされる設計になっています（_seekpath_cached と l