以下は、Python プログラム bond_valence_sum.py の解析結果を整理したドキュメントです。

1) プログラムの動作
- 概要
  - 指定された CIF ファイルを読み込み、原子間の結合長さに基づく「Bond Valence Sum (BVS)」を各原子について計算します。結合長さと事前に用意された結合価パラメータ（BV パラメータ）を使って、各隣接原子に対する寄与を指数関数的に計算し、全寄与の総和を各原子の BVS として出力します。
- 主な流れ
  - 環境変数 tkProg_Root が設定されていることを確認します。そうでない場合、エラーメッセージを出して終了します。
  - データベース BV パラメータファイルのパスを tkProg_Root/tkdb/Databases/bvparm2020.cif として設定します。
  - bvparm2020.cif から BV パラメータを読み込み、辞書 bv_params に格納します。各エントリは「atom1:atom2」ペアをキーとし、r0、B、ref、details などの情報を含みます。
  - コマンドライン引数として CIF ファイルと、任意の最大半径 max_r（デフォルト 2.7 Å）を受け取ります。
  - 指定 CIF ファイルを pymatgen の Structure オブジェクトとして読み込みます。
  - 各原子サイトについて、指定半径内の近傍を structure.get_neighbors で取得します。近傍ごとに以下を実施します。
    - 隣接原子の化学種名（symbol）および酸化状態（oxi_state）を取得。酸化状態が不明の場合は 0 とする。
    - 対になる BV パラメータのキーを作成（fwd: "name1:name2"）と反対キー（bwd: "name2:name1"）を探索して bv_params を取得。
    - BV パラメータが見つからなければエラーメッセージを出してその近傍をスキップ。
    - B = パラメータの B が 0 の場合は警告を出してスキップ。
    - 対象結合の距離 d を用いて bv = exp((r0 - d) / B) を計算してこれをその原子の BVS に加算。
    - 近傍原子の情報（インデックス、元素、酸化状態、r0、B、d、bv、参照情報）を出力します。
  - 原子ごとに最終的な Bond Valence Sum を出力します。
  - 最後に「Press ENTER to terminate>> 」の待機を行い、エンター入力で終了します。
- 出力の特徴
  - 各原子ごとに「Bond Valence Sum (BVS)」を明示的に表示。
  - 各近傍について、距離 d、r0、B、寄与 bv、隣接原子のインデックスと名称・酸化状態を出力。
  - BV パラメータの不在や B=0 などのケースでは適切な警告・エラーメッセージを表示。

2) 必要な非標準ライブラリとインストール方法
- 非標準ライブラリ
  - pymatgen
  - numpy
- インストール方法（例：pip を使用）
  - Python 3.8 以降を想定
  - 基本的な環境でのインストール
    - pip install numpy
    - pip install pymatgen
- 追加メモ
  - pymatgen は CIF ファイルの読み込みなどを行うために必須です。依存関係が多いことがあるので、仮想環境の利用を推奨します。

3) 必要な入力ファイル
- CIF ファイル
  - コマンドライン引数として渡す対象の CIF ファイル。Structure.from_file で読み込まれます。
- BV パラメータファイル（データベース）
  - tkProg_Root/tkdb/Databases/bvparm2020.cif
  - 書式の要点
    - セクション名の例: _valence_param_details
    - そのセクションの下に 7 列以上の行があり、以下の値を空白区切りで含む必要があります。
      - atom1, Z1, atom2, Z2, r0, B, ref  そしてオプションで details
    - 各行は 7 列未満の場合は警告としてスキップされます。
  - 実際にはこのファイルに BV のパラメータペア（例: Fe:O、Fe:P など）が定義されていると想定されます。

4) 実行後に生成される出力ファイル
- 注意事項
  - このスクリプトは標準出力へ逐次的に情報を表示します。明示的な「出力ファイル」を作成する動作は実装上ありません。
- 出力内容の例（概要）
  - 各原子について
    - インデックス: 物質内の原子インデックス
    - 元素名と酸化状態の表示（酸化状態が不明の場合は空文字）
    - 近傍情報のリスト: 隣接原子のインデックス、元素名、酸化状態、距離 d、r0、B、寄与 bv、BV パラメータの参照情報
  - 原子ごとの合計
    - Bond Valence Sum: その原子の BVS
  - すべての原子の処理後、暫定的なプロンプト「Press ENTER to terminate>> 」が表示され、エンター押下で終了します。

5) コマンドラインでの使用例 (Usage)
- 必須引数
  - cif_file: 入力 CIF ファイル
- オプション引数
  - max_r: 隣接原子を考慮する最大半径（Å、デフォルト 2.7）
- 実行例
  - 環境変数設定と実行
    - bash の例
      - export tkProg_Root=/path/to/project
      - python3 bond_valence_sum.py my_structure.cif 2.5
  - すでに tkProg_Root が設定済みであれば、以下のように実行
    - python3 bond_valence_sum.py /path/to/structure.cif
      - max_r は省略時デフォルト 2.7 Å が使用されます
- 典型的なコマンド
  - python3 bond_valence_sum.py example_structure.cif 2.7
  - python3 bond_valence_sum.py example_structure.cif
- 注意点
  - tkProg_Root 環境変数が未設定だと、スクリプトは実行を開始できずエラーを返します:
    - Error: Environment variable tkProg_Root must be specified
  - bvparm2020.cif が指定パスに存在しない場合は、BV パラメータの読み込み段階でエラーとなります。
  - 指定 CIF ファイルの存在確認に失敗すると、"CIF file not found" のエラーメッセージで終了します。

補足
- 出力の解釈
  - 各邻接原子ごとに bv = exp((r0 - d) / B) の形で寄与が計算され、元の原子の BVSum に積算されます。
  - BV パラメータが見つからない