search_cif_db_tkcif プログラム仕様

概要:

CIFファイルを再帰的に検索し、その組成情報をSQLite3データベースに格納するツールです。格納されたデータベースを利用して、組成式からCIFデータを検索することができます。

詳細説明:

このスクリプトは、指定されたルートディレクトリ以下のCIFファイルを読み込み、 pymatgenとtkcifライブラリを使用して構造と組成情報を解析します。解析された情報はSQLite3データベースに保存され、後で高速に検索できるようになります。特に、組成式、還元組成式、元素のリスト、空間群、格子定数などのメタデータが格納されます。

主な機能: - indexモード: 指定されたディレクトリからCIFファイルをスキャンし、データベースを構築または更新します。

コマンド例:
python search_cif_db_tkcif.py --mode index --root ./COD --db cif_index.sqlite

searchモード: データベースに対して、組成式に基づいてCIFデータを検索します。検索モードには、exact (還元組成式が完全に一致)、elements (構成元素が完全に一致)、 contains (指定元素が部分集合として含まれる) の3種類のマッチング方式があります。コマンド例:

python search_cif_db_tkcif.py --mode search --db cif_index.sqlite --formula BaTiO3 python search_cif_db_tkcif.py --mode search --db cif_index.sqlite --formula TiBaO3 --match exact python search_cif_db_tkcif.py --mode search --db cif_index.sqlite --formula BaTiO3 --match elements python search_cif_db_tkcif.py --mode search --db cif_index.sqlite --formula BaTiO3 --match contains
infoモード: データベースの統計情報を表示します。コマンド例:

python search_cif_db_tkcif.py --mode info --db cif_index.sqlite

データベースのカラムは、ソースデータベース名、マテリアルID、CIFファイルのパス、組成式、還元組成式、匿名組成式、JSON形式の組成情報、元素リスト、元素数、サイト数、空間群記号、空間群番号、体積、原子あたりの体積、密度、格子定数 (a, b, c, alpha, beta, gamma)、使用されたバックエンド、正規化の有無、処理ステータス、エラーメッセージを含みます。

関連リンク:

search_cif_db_tkcif_usage

crystal.search_cif_db_tkcif.build_index(root: Path, db_path: Path, pattern: str = '*.cif', store_errors: int = 1, commit_interval: int = 200) → None

概要:

指定されたルートディレクトリ以下のCIFファイルをスキャンし、データベースインデックスを構築します。

詳細説明:

再帰的にCIFファイルを検索し、各ファイルから組成および構造情報を抽出します。抽出された情報はSQLiteデータベースに格納され、検索可能なインデックスが作成されます。ファイル処理中にエラーが発生した場合、store_errors が1であればエラー情報もデータベースに記録されます。 commit_interval ごとにトランザクションがコミットされ、進行状況が出力されます。最後に、処理の要約と、使用されたバックエンドの統計情報が表示されます。

引数:

param root:: CIFファイルを検索するルートディレクトリのパス。
type root:: pathlib.Path
param db_path:: SQLiteデータベースファイルのパス。
type db_path:: pathlib.Path
param pattern:: 検索するCIFファイルのパターン (例: "*.cif")。
type pattern:: str
param store_errors:: エラーが発生したレコードをデータベースに保存するかどうか (0: 保存しない, 1: 保存する)。
type store_errors:: int
param commit_interval:: データベースにコミットする間隔 (処理されたファイル数)。
type commit_interval:: int

戻り値:

returns:: なし
rtype:: None

crystal.search_cif_db_tkcif.composition_info_from_structure(path: Path) → dict[str, Any]

概要:

CIFファイルから構造情報を読み込み、検索用の組成および構造メタデータを作成します。

詳細説明:

指定されたCIFファイルを tkcif.tkcif_reader.read_structure を使って読み込み、 pymatgen.core.Structure オブジェクトを生成します。そこから組成式、還元組成式、匿名組成式、元素リスト、サイト数、空間群情報、格子定数、体積、原子あたりの体積、密度などを抽出し、辞書形式で返します。空間群情報の取得に失敗した場合は、空文字列や -1 を返します。

引数:

param path:: CIFファイルのパス。
type path:: pathlib.Path

戻り値:

returns:: 検索用のメタデータを含む辞書。
rtype:: dict

crystal.search_cif_db_tkcif.composition_to_sorted_json(comp: Composition) → str

概要:

pymatgen.core.Composition オブジェクトを、元素名でソートされたJSON文字列に変換します。

詳細説明:

Composition オブジェクトの各元素と量の情報を取得し、元素のシンボル (文字列) でソートします。その後、JSON形式の文字列として出力します。 pymatgen Composition.as_dict() のキーは Element オブジェクトではなく文字列として扱われます。

引数:

param comp:: 変換する組成オブジェクト。
type comp:: pymatgen.core.Composition

戻り値:

returns:: 元素名でソートされた組成情報のJSON文字列。
rtype:: str

crystal.search_cif_db_tkcif.create_schema(conn: Connection) → None

概要:

SQLiteデータベースのスキーマを新規作成または既存のスキーマを更新します。

詳細説明:

cif_index テーブルが存在しない場合は作成し、必要なカラムとインデックスを追加します。テーブルが既に存在する場合は、SCHEMA_COLUMNS に定義されているがまだ存在しないカラムがあれば追加します。これにより、新しいバージョンのスキーマに既存のデータベースをアップグレードできます。その後、検索パフォーマンス向上のために複数のインデックスを作成します。

引数:

param conn:: SQLiteデータベース接続オブジェクト。
type conn:: sqlite3.Connection

戻り値:

returns:: なし
rtype:: None

crystal.search_cif_db_tkcif.get_existing_columns(conn: Connection, table_name: str) → set[str]

概要:

指定されたSQLiteテーブルに存在するカラム名を取得します。

詳細説明:

PRAGMA table_info SQLコマンドを実行し、テーブルのスキーマ情報を取得します。結果からカラム名のみを抽出し、集合として返します。

引数:

param conn:: SQLiteデータベース接続オブジェクト。
type conn:: sqlite3.Connection
param table_name:: カラム情報を取得するテーブルの名前。
type table_name:: str

戻り値:

returns:: 既存のカラム名の集合。
rtype:: set

crystal.search_cif_db_tkcif.guess_db_name(path: Path) → str

概要:

ファイルのパスからデータベース名を推定します。

詳細説明:

パスの要素を小文字に変換し、"pcod", "tcod", "cod" のいずれかが含まれる場合、その名前をデータベース名として返します。これらの名前が見つからない場合は "unknown" を返します。

引数:

param path:: CIFファイルのパス。
type path:: pathlib.Path

戻り値:

returns:: 推定されたデータベース名 (例: "cod", "tcod", "pcod", "unknown")。
rtype:: str

crystal.search_cif_db_tkcif.guess_material_id(path: Path) → str

概要:

CIFファイルのファイル名からマテリアルIDを推定します。

詳細説明:

ファイル名から最初に見つかる数字列をマテリアルIDとして抽出します。例えば、"1234567.cif" から "1234567" を返します。数字が見つからない場合は、ファイル名全体 (拡張子なし) を返します。

引数:

param path:: CIFファイルのパス。
type path:: pathlib.Path

戻り値:

returns:: 推定されたマテリアルID。
rtype:: str

crystal.search_cif_db_tkcif.main() → None

概要:

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

詳細説明:

コマンドライン引数を解析し、指定されたモード (index, search, info) に応じて適切な処理関数を呼び出します。 --mode index はCIFファイルのインデックスを構築し、 --mode search はデータベースから組成式で検索し、 --mode info はデータベースの統計情報を表示します。検索モード (--mode search) の場合、--formula 引数が必須です。

引数:

なし

戻り値:

returns:: なし
rtype:: None

crystal.search_cif_db_tkcif.make_subset_condition_for_contains(target_elements: list[str]) → tuple[str, list[Any]]

概要:

データベースの elements カラムが指定された元素リストの部分集合である条件を生成します。

詳細説明:

この関数は、SQLのLIKE演算子を使用して、ある元素集合 (target_elements) の中にデータベースレコードの元素集合が含まれるかを判定するためのWHERE句とパラメータを生成します。 elementsカラムは、DB作成時にソートされたカンマ区切りの文字列として格納されているため、例として、targetが Ba,O,Ti の場合、DBレコードの elements が Ba,O や Ti,O などであればヒットします。要素の境界を明確にするために、カンマで囲まれた文字列に対する LIKE 検索を行います。

引数:

param target_elements:: 検索対象となる元素のソート済みリスト。
type target_elements:: list

戻り値:

returns:: WHERE句の条件文字列と、その条件にバインドするパラメータのリストのタプル。
rtype:: tuple

crystal.search_cif_db_tkcif.normalize_formula(formula: str) → str

概要:

与えられた組成式をpymatgen.core.Compositionを使用して標準化（還元）します。

詳細説明:

例えば、"BaTiO3" や "Ba Ti O3" のような式を pymatgen が認識する標準形式に変換し、さらに組成が最も簡単な整数比になるように還元します。

引数:

param formula:: 標準化する組成式文字列。
type formula:: str

戻り値:

returns:: 標準化された還元組成式文字列。
rtype:: str

crystal.search_cif_db_tkcif.search_by_formula(db_path: Path, formula: str, source_db: str = '', match: str = 'exact', limit: int = 100, output_json: int = 0) → None

概要:

指定された組成式とマッチングモードに基づいて、データベースからCIFデータを検索します。

詳細説明:

pymatgen.core.Composition を用いて検索対象の組成式を正規化し、指定されたマッチングモード (exact, elements, contains) に従ってデータベースをクエリします。検索結果は、source_db、material_id、reduced_formula、elements、空間群、格子定数などの情報を含みます。結果は、元素数、ソースデータベース、還元組成式、マテリアルIDの順にソートされ、指定された件数に制限されます。 output_json が1の場合、結果はJSON形式で出力されます。それ以外の場合は、人間が読みやすい形式で出力されます。

引数:

param db_path:: SQLiteデータベースファイルのパス。
type db_path:: pathlib.Path
param formula:: 検索する組成式。
type formula:: str
param source_db:: 検索対象のソースデータベース名 (例: "cod", "tcod")。空文字列の場合はすべてのデータベースを検索します。
type source_db:: str
param match:: マッチングモード。"exact" (還元組成式が完全に一致), "elements" (構成元素が完全に一致), "contains" (指定元素集合が部分集合として含まれる) のいずれかを指定します。
type match:: str
param limit:: 検索結果の最大件数。
type limit:: int
param output_json:: 結果をJSON形式で出力するかどうか (0: 通常出力, 1: JSON出力)。
type output_json:: int

戻り値:

returns:: なし
rtype:: None

例外:

raises ValueError:: 未知のマッチングモードが指定された場合に発生します。

crystal.search_cif_db_tkcif.show_info(db_path: Path) → None

概要:

指定されたデータベースの統計情報を表示します。

詳細説明:

データベースに格納されているCIFレコードの総数、ステータスごとの内訳 (成功/エラー)、ソースデータベースごとの内訳、使用されたバックエンドごとの内訳、および正規化の有無ごとの内訳を出力します。これらの情報は、データベースの状態やインデックス作成の品質を把握するのに役立ちます。

引数:

param db_path:: SQLiteデータベースファイルのパス。
type db_path:: pathlib.Path

戻り値:

returns:: なし
rtype:: None

crystal.search_cif_db_tkcif.upsert_record(conn: Connection, rec: dict[str, Any]) → None

概要:

データベースにレコードを挿入または更新（UPSERT）します。

詳細説明:

指定されたレコード辞書recの内容に基づいて、cif_indexテーブルにデータを挿入します。 cif_path カラムは UNIQUE 制約を持つため、同じパスのレコードが既に存在する場合は既存のレコードが新しいデータで置き換えられます（INSERT OR REPLACE）。

引数:

param conn:: SQLiteデータベース接続オブジェクト。
type conn:: sqlite3.Connection
param rec:: データベースに挿入または更新するレコードデータを含む辞書。
type rec:: dict

戻り値:

returns:: なし
rtype:: None