# `cfg2cif.py`

## 概要

`cfg2cif.py` は、CFGファイルをCIFファイルに変換するPythonスクリプトです。
このスクリプトは、Open-CFG形式のファイルから結晶構造情報を読み込み、CIF (Crystallographic Information File) 形式に変換して出力します。格子ベクトルの読み込みや、原子サイトの座標処理（必要に応じて ``[0,1)`` 範囲への丸め込み、指定範囲外の除外）をサポートしています。

関連リンクについては、元のコードのdocstringに `:doc:` ロールで `cfg2cif_usage` が指定されていますが、このドキュメントセットには含まれていないため、参照先は解決されません。

## 非標準ライブラリ

本スクリプトは以下の非標準ライブラリに依存しています。

*   ``numpy``: 数値計算、特に配列操作に使用されます。
*   ``scipy.interpolate.interp1d``: 補間機能に使用されます（ただし、本スクリプト内では直接使用されていません）。
*   ``pprint``: データ構造の整形表示に使用されます（ただし、本スクリプト内では直接使用されていません）。
*   ``matplotlib.pyplot``: グラフ描画機能に使用されます（ただし、本スクリプト内では直接使用されていません）。
*   ``tklib``: 以下のモジュールは、スクリプトの実行パスにローカルで追加されたディレクトリからインポートされます。
    *   ``tklib.tkfile.tkFile``: ファイル操作を処理します。
    *   ``tklib.tkutils``: ユーティリティ関数（ディレクトリ/ファイルの存在確認、パス分割、スクリプト終了、型変換、引数取得など）を提供します。
        *   ``IsDir``
        *   ``IsFile``
        *   ``SplitFilePath``
        *   ``terminate``
        *   ``pint``
        *   ``pfloat``
        *   ``getarg``
        *   ``getintarg``
        *   ``getfloatarg``
    *   ``tklib.tksci.tksci``: 科学計算関連のユーティリティ（座標の ``[0,1)`` 範囲への削減、丸め処理など）を提供します。
        *   ``Reduce01``
        *   ``Round``
    *   ``tklib.tksci.tkmatrix``: 行列操作に関連する関数を提供します（本スクリプト内では直接使用されていません）。
        *   ``make_matrix1``
        *   ``make_matrix2``
        *   ``make_matrix3``
    *   ``tklib.tkcrystal.tkcif``: CIFファイル操作に関連する機能を提供します。
        *   ``tkCIF``
        *   ``tkCIFData``
    *   ``tklib.tkcrystal.tkcrystal``: 結晶構造データモデルに関連する機能を提供します。
        *   ``tkCrystal``
    *   ``tklib.tkcrystal.tkatomtype``: 原子種情報に関連する機能を提供します（本スクリプト内では直接使用されていません）。
        *   ``tkAtomType``

## グローバル変数

スクリプトの動作を制御するために、以下のグローバル変数が定義されています。

*   ``debug``: デバッグレベルを示します。初期値は ``0`` です。
*   ``atomtypes``: 認識される原子種のリストです。初期値は ``['O', 'Zn', 'Ga', 'In']`` です。
*   ``xlim``, ``ylim``, ``zlim``: 原子座標の出力範囲の上限です。初期値はそれぞれ ``1.0`` です。
*   ``cfgfile``: 入力CFGファイルのデフォルト名です。初期値は ``'STD0.cfg'`` です。
*   ``ciffile``: 出力CIFファイルのデフォルト名です。初期値は ``'STD0.cif'`` です。
*   ``freduce01``: 分数座標を ``[0,1)`` 範囲に削減するかどうかを示すフラグです。初期値は ``1`` です。

## コマンドライン引数

### 利用方法

スクリプトは、以下の形式でコマンドライン引数を受け取ります。

```bash
python cfg2cif.py cfgfile [reduce01] [xlim] [ylim] [zlim]

引数の詳細

  • 位置引数 1: cfgfile

    • 入力CFGファイルのパスです。省略された場合は、グローバル変数のデフォルト値 STD0.cfg が使用されます。

  • 位置引数 2: reduce01

    • 分数座標を [0,1) 範囲に削減するかどうかを指定する整数フラグです。

    • 1 の場合、削減が実行されます。

    • 0 の場合、削減は実行されません。

    • 省略された場合は、グローバル変数のデフォルト値 1 が使用されます。

  • 位置引数 3: xlim

    • 原子のX座標の出力上限値を指定する浮動小数点数です。この値を超えるX座標を持つ原子は出力から除外されます。

    • 省略された場合は、グローバル変数のデフォルト値 1.0 が使用されます。

  • 位置引数 4: ylim

    • 原子のY座標の出力上限値を指定する浮動小数点数です。この値を超えるY座標を持つ原子は出力から除外されます。

    • 省略された場合は、グローバル変数のデフォルト値 1.0 が使用されます。

  • 位置引数 5: zlim

    • 原子のZ座標の出力上限値を指定する浮動小数点数です。この値を超えるZ座標を持つ原子は出力から除外されます。

    • 省略された場合は、グローバル変数のデフォルト値 1.0 が使用されます。

例:

python cfg2cif.py STD0.cfg 1 0.7 0.7 0.7

入出力仕様

入力

  • CFGファイル: コマンドライン引数 cfgfile またはデフォルトの STD0.cfg で指定されるCFGファイルです。このファイルは以下の情報を特定の形式で含んでいる必要があります。

    • 最初の2行はサンプル名（2行目）です。

    • molecules of all の記述を含む行から総原子数 natoms を読み取ります。

    • Defining vectors の記述を含む行の後に続く3行が格子ベクトルデータです。ただし、1行目の各要素は読み込み後に2倍され、2行目と3行目のベクトルはそれぞれ [0.0, aij[0][0], 0.0] と [0.0, 0.0, aij[0][0]] として構築されます。この動作はコードにハードコードされています。

    • molecules of type の記述を含む行から、各原子種の原子数を読み取ります。

    • これらの記述の後に、各原子の分数座標 (x, y, z) が行ごとに記述されます。原子種はグローバル変数 atomtypes のリスト順で割り当てられます。

  • コマンドライン引数: 上述の「コマンドライン引数」セクションで説明された通りです。

出力

  • CIFファイル: 入力CFGファイルのファイル名（拡張子を除く）に .cif 拡張子を付けた名前で出力されます。

    • 例えば、入力ファイルが example.cfg の場合、出力ファイルは example.cif となります。

    • ファイルの内容は、読み込んだ結晶構造情報に基づいて tkCIFData オブジェクトによって生成されたCIF形式データです。

  • 標準出力: 処理の進行状況、読み込んだサンプル名、格子ベクトル、各原子サイトの情報、最終的な結晶情報などが逐次出力されます。エラーが発生した場合は、エラーメッセージと利用方法が表示されてスクリプトが終了します。

主要な関数

usage()

スクリプトのコマンドライン引数の利用方法を標準出力に表示します。 グローバル変数の cfgfile, freduce01, xlim, ylim, zlim の現在の値を用いて、具体的な使用例も提示します。

updatevars()

コマンドライン引数を解析し、関連するグローバル変数を更新します。

  • sys.argv から引数を取得し、getarg(), getintarg(), getfloatarg() を使用して cfgfile, freduce01, xlim, ylim, zlim の値を設定します。

  • cfgfile のファイル名に基づいて、出力CIFファイル名 ciffile を決定します。

read_cfgfile(cfgfile)

指定されたCFGファイルを読み込み、tkCrystal オブジェクトを構築して返します。

  • 引数:

    • cfgfile (str): 読み込むCFGファイルのパス。

  • 処理内容:

    • tkFile を使用してCFGファイルを開きます。

    • サンプル名、総原子数、格子ベクトル、各原子サイトの座標と原子種をファイルから抽出します。

      • 特に、格子ベクトルの [0] 行目は2倍され、他の2つの格子ベクトルは aij[0][0] の値から構築されることに注意してください。

    • 抽出された情報をもとに tkCrystal オブジェクトを初期化し、原子サイトを追加します。

    • グローバル変数 freduce01 が 1 の場合、原子座標は Reduce01() 関数によって [0,1) 範囲に正規化されます。

    • グローバル変数 xlim, ylim, zlim で指定された範囲外にある原子は、tkCrystal オブジェクトに追加されません。

  • 戻り値:

    • 構築された tkCrystal オブジェクト。ファイルの読み込みに失敗した場合や tkCrystal オブジェクトの構築に失敗した場合は None を返します。

cfg2cif()

グローバル変数で指定されたCFGファイルを読み込み、CIFファイルに変換して保存します。

  • 処理内容:

    • read_cfgfile() 関数を呼び出してCFGファイルから結晶情報を取得し、tkCrystal オブジェクトを生成します。

    • 取得した tkCrystal オブジェクトを使用して tkCIFData オブジェクトを生成します。

    • tkCIFData.CreateCIFFileFromCCrystal() メソッドを呼び出し、結晶情報をグローバル変数 ciffile で指定されたパスにCIFファイルとして書き出します。

    • 処理の最後に terminate() 関数が呼ばれ、スクリプトの利用方法が表示されて終了します。

main()

スクリプトのエントリポイントです。

  • 処理内容:

    • updatevars() を呼び出してコマンドライン引数を処理し、グローバル変数を更新します。

    • cfg2cif() を呼び出してCFGからCIFへの変換処理を実行します。

    • スクリプトの開始時と終了時にメッセージを標準出力に出力します。

コード例

CFGファイルを指定し、座標を [0,1) 範囲に削減し、出力範囲を 0.7 に制限するコマンドラインの例を以下に示します。

python cfg2cif.py STD0.cfg 1 0.7 0.7 0.7