packmol-util 0.2.4__tar.gz

packmol_util-0.2.4/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: packmol_util
+Version: 0.2.4
+Summary: using packmol
+Author-email: Kengo NAKADA <kengo.nakada@email.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xlogger-py
+Requires-Dist: dataclasses
+Requires-Dist: coloredlogs
+Requires-Dist: colorlog
+Requires-Dist: pytest
+Requires-Dist: pytest-asyncio
+Requires-Dist: pyyaml
+Requires-Dist: toml
+Requires-Dist: nest_asyncio
+Requires-Dist: sphinx
+Requires-Dist: myst-parser
+Requires-Dist: sphinx-autobuild
+Requires-Dist: sphinx-rtd-theme
+Requires-Dist: sphinxcontrib-napoleon
+Requires-Dist: linkify-it-py
+
+# packmol_util
+[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/shimane-dev/rmc_dft/blob/main/README.md)
+[![ja](https://img.shields.io/badge/lang-ja-yellow.svg)](https://github.com/shimane-dev/rmc_dft/blob/main/README.ja.md)
+
+
+A **Python utility kit for automatically generating amorphous initial structures (POSCAR)** for first-principles calculations (VASP) and molecular dynamics (MD) simulations using Packmol.
+
+By specifying only the stoichiometric ratio, density (mass density or number density), and total number of atoms, this tool automatically completes the full workflow: generating the Packmol input file, running Packmol, and outputting a POSCAR in VASP format with Direct coordinates.
+
+---
+
+## 💡 Features
+
+1. **Intuitive density specification**
+   - Packmol itself does not interpret density or atomic weights, but this tool performs the required internal calculations and determines the cubic cell length $L$ that satisfies the specified density.
+2. **Exclusion radius specification by element symbol**
+   - This hides Packmol's inconvenient atom-index-based specification inside XYZ files. Interatomic avoidance distances can be controlled using an intuitive element-name-based dictionary, such as `{"P": 0.25, "O": 1.05}`.
+3. **Preservation of molecular units (geometries)**
+   - For systems such as $\text{Li}_3\text{PO}_4$, amorphization through mixing and packing can be performed while preserving intramolecular bond lengths, such as those in $\text{PO}_4$ tetrahedra.
+4. **Extremely simple high-level API**
+   - By using `AmorphousBuilder`, the cumbersome file relay workflow (`.inp` construction $\rightarrow$ external execution $\rightarrow$ coordinate conversion) can be condensed into only a few lines of script.
+
+---
+
+## 📁 Directory structure
+
+```text
+src/
+├── packmol_util/
+│
+│   ├── __init__.py          # Package initialization file
+│   ├── builder.py           # High-level integrated builder (AmorphousBuilder) ★NEW
+│   ├── model.py             # Template XYZ generation and structure-definition module
+│   ├── packmol.py           # Core density calculation, Packmol execution, and POSCAR conversion
+│   ├── packmol_inp.py       # Parsing engine for constructing packmol.inp
+│   ├── param.py             # Atomic weights and physical constants for the periodic table
+
+└── example/                 # Location for material-specific generation scripts
+    ├── Li3PO4/
+    │   └── make_Li3PO4.py
+    └── FeSiB/
+        └── make_FeSiB.py
+```

packmol_util-0.2.4/README.md

@@ -0,0 +1,43 @@
+# packmol_util
+[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/shimane-dev/rmc_dft/blob/main/README.md)
+[![ja](https://img.shields.io/badge/lang-ja-yellow.svg)](https://github.com/shimane-dev/rmc_dft/blob/main/README.ja.md)
+
+
+A **Python utility kit for automatically generating amorphous initial structures (POSCAR)** for first-principles calculations (VASP) and molecular dynamics (MD) simulations using Packmol.
+
+By specifying only the stoichiometric ratio, density (mass density or number density), and total number of atoms, this tool automatically completes the full workflow: generating the Packmol input file, running Packmol, and outputting a POSCAR in VASP format with Direct coordinates.
+
+---
+
+## 💡 Features
+
+1. **Intuitive density specification**
+   - Packmol itself does not interpret density or atomic weights, but this tool performs the required internal calculations and determines the cubic cell length $L$ that satisfies the specified density.
+2. **Exclusion radius specification by element symbol**
+   - This hides Packmol's inconvenient atom-index-based specification inside XYZ files. Interatomic avoidance distances can be controlled using an intuitive element-name-based dictionary, such as `{"P": 0.25, "O": 1.05}`.
+3. **Preservation of molecular units (geometries)**
+   - For systems such as $\text{Li}_3\text{PO}_4$, amorphization through mixing and packing can be performed while preserving intramolecular bond lengths, such as those in $\text{PO}_4$ tetrahedra.
+4. **Extremely simple high-level API**
+   - By using `AmorphousBuilder`, the cumbersome file relay workflow (`.inp` construction $\rightarrow$ external execution $\rightarrow$ coordinate conversion) can be condensed into only a few lines of script.
+
+---
+
+## 📁 Directory structure
+
+```text
+src/
+├── packmol_util/
+│
+│   ├── __init__.py          # Package initialization file
+│   ├── builder.py           # High-level integrated builder (AmorphousBuilder) ★NEW
+│   ├── model.py             # Template XYZ generation and structure-definition module
+│   ├── packmol.py           # Core density calculation, Packmol execution, and POSCAR conversion
+│   ├── packmol_inp.py       # Parsing engine for constructing packmol.inp
+│   ├── param.py             # Atomic weights and physical constants for the periodic table
+
+└── example/                 # Location for material-specific generation scripts
+    ├── Li3PO4/
+    │   └── make_Li3PO4.py
+    └── FeSiB/
+        └── make_FeSiB.py
+```

packmol_util-0.2.4/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=71.0","coloredlogs"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "packmol_util"
+version = "0.2.4"
+
+description = "using packmol"
+authors = [
+    { name="Kengo NAKADA", email="kengo.nakada@email.com" },
+]
+readme = "README.md"
+# requires-python = ">=3.8"
+requires-python = ">=3.10"
+dependencies = [
+    #"x_logger",
+    "xlogger-py",
+    "dataclasses",
+    "coloredlogs",
+    "colorlog",
+    "pytest",
+    "pytest-asyncio",
+    "pyyaml",
+    "toml",
+    # "grpcio",
+    "nest_asyncio",
+    "sphinx",
+    "myst-parser",
+    "sphinx-autobuild",
+    "sphinx-rtd-theme",
+    "sphinxcontrib-napoleon",
+    "linkify-it-py"
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+# ここでpytestのiniと同じようにオプションが書ける
+# 例えばテストマーク、フィルタ、カバレッジなども追記可能
+
+[tool.black]
+line-length = 88
+
+[tool.isort]
+profile = "black"

packmol_util-0.2.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

packmol_util-0.2.4/src/packmol_util/__init__.py

@@ -0,0 +1,3 @@
+from packmol_util.builder import AmorphousBuilder
+from packmol_util.config import Config
+from packmol_util.packmol import Packmol

packmol_util-0.2.4/src/packmol_util/builder.py

@@ -0,0 +1,312 @@
+#!/usr/bin/env python3
+"""
+packmol_util/builder.py
+
+詳細なファイルのバケツリレーを隠蔽し、
+数行でアモルファス構造を作成するための高レベル統合モジュール。
+
+以下の 3 点を外部入力の基準とする：
+    1. 化学量論比（整数比）
+    2. 密度 [g/cm^3] または 数密度 [1/Å^3] のいずれか一方
+    3. セル内の総原子数 total_atom_count
+
+【重要】指定した total_atom_count が ratios の合計で割り切れない（組成比を維持できない）場合、
+プログラムが破綻するのを防ぐため、指定された原子数に最も近い「割り切れる総原子数」へ自動補正を行う。
+内部で計算された全体のスケール倍率（multiplier）を外部に公開（プロパティ化）することで、
+利用側のスクリプトがユニット構成単位でのパッキング個数を一元管理できるように設計されている。
+"""
+
+from typing import Dict, List, Optional, Tuple
+from packmol_util.packmol import Packmol
+from packmol_util.packmol_inp import PackmolInp
+
+
+class AmorphousBuilder:
+
+    def __init__(
+        self,
+        symbols: List[str],
+        ratios: List[int],
+        total_atom_count: int,  # 希望するベースの総原子数
+        minimum_separation: float,
+        mass_density: Optional[float] = None,
+        number_density: Optional[float] = None,
+        packmol_bin: str = "packmol",
+    ):
+        if len(symbols) != len(ratios):
+            raise ValueError("symbols と ratios の長さが一致していません。")
+
+        if total_atom_count <= 0:
+            raise ValueError("total_atom_count は正の整数である必要があります。")
+
+        self.symbols = symbols
+        self.ratios = ratios
+        self.minimum_separation = minimum_separation
+        self.packmol_bin = packmol_bin
+
+        # --- 【自動補正ロジック】指定できない比率（割り切れない数）のときの自動補正 ---
+        ratio_sum = sum(ratios)
+        if total_atom_count % ratio_sum != 0:
+            # 最も近い整数倍（倍率）を計算
+            multiplier = round(total_atom_count / ratio_sum)
+            if multiplier < 1:
+                multiplier = 1
+            adjusted_atom_count = ratio_sum * multiplier
+            print(
+                f"[Warning] 指定された総原子数 {total_atom_count} は組成比の合計 {ratio_sum} で割り切れません。"
+            )
+            print(
+                f"          組成比を維持するため、総原子数を {adjusted_atom_count} (倍率: {multiplier}) に自動調整しました。"
+            )
+            self.total_atom_count = adjusted_atom_count
+            self._multiplier = multiplier
+        else:
+            self.total_atom_count = total_atom_count
+            self._multiplier = total_atom_count // ratio_sum
+
+        # 密度の計算とセル一辺の長さ決定
+        self.packmol_runner = Packmol()
+        if number_density is not None:
+            self.box_length = self.packmol_runner.cell_length_from_number_density(
+                self.total_atom_count, number_density
+            )
+        elif mass_density is not None:
+            n_density = self.packmol_runner.number_density_from_mass_density(
+                symbols, ratios, mass_density
+            )
+            self.box_length = self.packmol_runner.cell_length_from_number_density(
+                self.total_atom_count, n_density
+            )
+        else:
+            raise ValueError(
+                "mass_density または number_density のどちらかを指定してください。"
+            )
+
+        self.templates: List[dict] = []
+
+    @property
+    def multiplier(self) -> int:
+        """
+        全体の化学量論比に対するセルのスケール倍率を返す。
+        利用側のスクリプトは、この倍率をユニットの1式あたり構成比に乗算することで、
+        Packmol に引き渡すべき実際の複製個数（number）を算出する。
+        """
+        return self._multiplier
+
+    def add_template(
+        self,
+        xyz_file: str,
+        number: int,  # そのテンプレートを Packmol がセル内に何個配置するかを表す実際の複製個数
+        packing_radii: Optional[Dict[str, float]] = None,
+        fnc_pairs_in_template: Optional[List[Tuple[int, int, int]]] = None,
+        fnc_distance_ranges: Optional[Dict[int, Tuple[float, float]]] = None,
+        # packmol後に、FNC作成での形状固定の選択
+        fnc_output_constraint_types: Optional[List[int]] = None,
+    ):
+        """
+        Packmol の 1 つの structure ブロックに対応するテンプレート情報を登録する。
+
+        引数の説明：
+            xyz_file: Packmol に渡す単原子または分子ユニットテンプレートの座標ファイル名 (.xyz)
+            number: そのテンプレートを何個複製して配置するかを指定する [int]
+            packing_radii: Packmol 配置時に使う元素記号別の排除半径の辞書（任意）。
+                           分子ユニット内部の結合距離や形状を作る値ではない。
+            fnc_pairs_in_template: テンプレート内の局所原子番号で指定した FNC ペア。
+                                   (local_i, local_j, constraint_type) のリストで指定する。
+            fnc_distance_ranges: FNC constraint type ごとの距離範囲。
+                                 {type: (rmin, rmax)} で指定する。
+            fnc_output_constraint_types: .fnc に実際に出力する constraint type のリスト。
+                                         None の場合は全 type を出力する。
+                                         例: [1] を指定すると type 1 のペアだけを出力する。
+                                         Packmol 用 XYZ テンプレートの形状や配置には影響しない。
+        """
+        # builder では、テンプレートをまだ Packmol 入力へ変換しない。
+        # ここでは「どの XYZ テンプレートを何個置くか」と、必要なら配置用 packing 半径だけを保存する。
+        # 具体的な structure ... end structure への変換は build() 内の PackmolInp が担当する。
+        self.templates.append(
+            {
+                "xyz": xyz_file,
+                "number": number,
+                "radii": packing_radii,
+                "fnc_pairs_in_template": fnc_pairs_in_template,
+                "fnc_distance_ranges": fnc_distance_ranges,
+                # Packmol は xyz_file のテンプレート形状をそのまま配置する。
+                # この指定は Packmol には渡さず、Packmol 後に .fnc を作る段階だけで使う。
+                # None: 全 FNC type を出力する。
+                # [1]: type 1 の拘束だけを .fnc に出力する。
+                "fnc_output_constraint_types": fnc_output_constraint_types,
+            }
+        )
+
+    def build(self, output_prefix: str, fnc_file: Optional[str] = None):
+        # output_prefix は、一連の生成ファイル名の接頭辞として使う。
+        # 例: output_prefix="Li3PO4" の場合、Li3PO4_packmol.inp / Li3PO4_packmol.xyz / Li3PO4_packmol.log を作る。
+        input_file = f"{output_prefix}_packmol.inp"
+        output_xyz = f"{output_prefix}_packmol.xyz"
+        output_log = f"{output_prefix}_packmol.log"
+        poscar_file = "POSCAR"
+        vasp_file = "POSCAR.vasp"
+        if fnc_file is None:
+            fnc_file = f"{output_prefix}.fnc"
+
+        # 1. PackmolInp を構築する。
+        # AmorphousBuilder が持つ情報は Python 側の抽象表現である。
+        # PackmolInp は、それを Packmol の .inp 文法へ落とす役割を持つ。
+        inp_builder = PackmolInp(
+            minimum_separation_distance=self.minimum_separation,
+            output_xyz=output_xyz,
+            box_length=self.box_length,
+            use_pbc=True,
+        )
+        for t in self.templates:
+            # 1 件の template は Packmol 入力の 1 つの structure ブロックに対応する。
+            # 単原子テンプレートでも PO4 のような分子ユニットでも、ここでは同じ登録処理を通す。
+            inp_builder.add_structure(
+                xyz_file=t["xyz"],
+                number=t["number"],
+                packing_radii_by_atom_symbol=t["radii"],
+            )
+        # 登録した template 群を Packmol 入力ファイルとして書き出す。
+        inp_builder.write(input_file)
+
+        # 2. Packmol を実行し、生成された XYZ を POSCAR に変換する。
+        self.packmol_runner.run_packmol(
+            input_file=input_file,
+            output_log=output_log,
+            packmol_bin=self.packmol_bin,
+        )
+
+        # Packmol 出力は Cartesian 座標なので、VASP POSCAR 用に Direct 座標へ変換する。
+        xyz_to_poscar_index = self.packmol_runner.xyz_to_poscar(
+            xyz_file=output_xyz,
+            poscar_file=poscar_file,
+            packmol_inp=input_file,
+            comment=f"{output_prefix} amorphous initial model generated by Packmol (Total Atoms: {self.total_atom_count})",
+            elements=self.symbols,
+        )
+
+        self._write_fnc_from_templates(
+            output_xyz=output_xyz,
+            xyz_to_poscar_index=xyz_to_poscar_index,
+            fnc_file=fnc_file,
+            output_prefix=output_prefix,
+        )
+
+        # 外部ツール連携用に vasp.xyz（あるいは POSCAR.vasp）も同様に出力する。
+        self.packmol_runner.xyz_to_poscar(
+            xyz_file=output_xyz,
+            poscar_file=vasp_file,
+            packmol_inp=input_file,
+            comment=f"{output_prefix} amorphous initial model vasp format",
+            elements=self.symbols,
+        )
+
+    def _write_fnc_from_templates(
+        self,
+        output_xyz: str,
+        xyz_to_poscar_index: Dict[int, int],
+        fnc_file: str,
+        output_prefix: str,
+    ) -> None:
+        """
+        登録済みテンプレートの FNC 局所ペアを、最終 POSCAR/cfg 番号へ変換して *.fnc を書く。
+
+        Packmol 出力 XYZ ではテンプレート単位の原子順が残る。一方、POSCAR 変換では
+        元素ごとに座標を並べ替えるため、PO4 の P と O の番号は離れる。
+        このメソッドは、Packmol XYZ 番号を中間番号として使い、
+        テンプレート内局所番号から最終 POSCAR/cfg 番号の FNC ペアを作る。
+        """
+        all_fnc_pairs: List[Tuple[int, int, int]] = []
+        merged_distance_ranges: Dict[int, Tuple[float, float]] = {}
+
+        xyz_start_index = 1
+        for template in self.templates:
+            xyz_file = str(template["xyz"])
+            number = int(template["number"])
+            fnc_pairs_in_template = template.get("fnc_pairs_in_template")
+            fnc_distance_ranges = template.get("fnc_distance_ranges")
+            # packmol後に形状固定でのFNCの選択有無
+            fnc_output_constraint_types = template.get("fnc_output_constraint_types")
+
+            atom_count_in_template = self.packmol_runner.count_atoms_in_xyz(
+                xyz_file=xyz_file,
+            )
+
+            if fnc_pairs_in_template is not None:
+                if fnc_distance_ranges is None:
+                    raise ValueError(
+                        f"{xyz_file} に fnc_pairs_in_template が指定されているが、"
+                        "fnc_distance_ranges が指定されていない。"
+                    )
+                ########################################
+                # Packmol 用テンプレート構造は変更しない。
+                # ここでは Packmol 後の最終構造から .fnc を作る段階だけで、
+                # RMC に渡す constraint type を選別する。
+                if fnc_output_constraint_types is None:
+                    active_constraint_types = list(fnc_distance_ranges.keys())
+                else:
+                    active_constraint_types = list(fnc_output_constraint_types)
+
+                active_constraint_type_set = set(active_constraint_types)
+
+                for type_index in active_constraint_types:
+                    if type_index not in fnc_distance_ranges:
+                        raise ValueError(
+                            f"{xyz_file} の fnc_output_constraint_types に type={type_index} "
+                            "が指定されているが、fnc_distance_ranges に存在しない。"
+                        )
+
+                active_fnc_pairs_in_template = [
+                    pair
+                    for pair in fnc_pairs_in_template
+                    if pair[2] in active_constraint_type_set
+                ]
+
+                active_fnc_distance_ranges = {
+                    type_index: fnc_distance_ranges[type_index]
+                    for type_index in active_constraint_types
+                }
+                ############################
+
+                for type_index, distance_range in active_fnc_distance_ranges.items():
+                    if type_index in merged_distance_ranges:
+                        if merged_distance_ranges[type_index] != distance_range:
+                            raise ValueError(
+                                "同じ FNC constraint type に異なる距離範囲が指定されている。"
+                                f" type={type_index}"
+                            )
+                    else:
+                        merged_distance_ranges[type_index] = distance_range
+
+                copy_index = 0
+                while copy_index < number:
+                    molecule_xyz_start = (
+                        xyz_start_index + copy_index * atom_count_in_template
+                    )
+                    for (
+                        local_i,
+                        local_j,
+                        constraint_type,
+                    ) in active_fnc_pairs_in_template:
+                        xyz_i = molecule_xyz_start + local_i - 1
+                        xyz_j = molecule_xyz_start + local_j - 1
+                        poscar_i = xyz_to_poscar_index[xyz_i]
+                        poscar_j = xyz_to_poscar_index[xyz_j]
+                        all_fnc_pairs.append((poscar_i, poscar_j, constraint_type))
+                    copy_index = copy_index + 1
+
+            xyz_start_index = xyz_start_index + number * atom_count_in_template
+
+        if len(all_fnc_pairs) == 0:
+            return
+
+        self.packmol_runner.write_fnc_file(
+            fnc_file=fnc_file,
+            total_atom_count=self.total_atom_count,
+            fnc_pairs=all_fnc_pairs,
+            distance_ranges_by_type=merged_distance_ranges,
+            title=f"{output_prefix} FNC generated from Packmol template mapping",
+        )
+
+
+#

packmol_util-0.2.4/src/packmol_util/config.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""packmol_util の設定保持クラス。"""
+
+from typing import Optional, Sequence, Union
+import os
+
+import yaml
+from x_logger import XLogger
+
+
+class Config:
+    """packmol_util 用の設定値を保持する。"""
+
+    N_tot: int = 2000
+    mass_density_g_cm3: float = 7.3336
+    number_density_A3: float = 0.09119
+    element_info: Union[str, Sequence[str]] = ["Fe", "Si", "B"]
+    ratios: Sequence[int] = [82, 4, 14]
+
+    packmol_bin: str = "packmol"
+    minimum_separation: float = 2.0
+    output_prefix: str = "amorphous"
+
+    def __init__(
+        self,
+        yaml_path: Optional[str] = None,
+        logger: Optional[XLogger] = None,
+    ) -> None:
+        if logger is None:
+            logger = XLogger(logger_name=__name__)
+        self._logger = logger
+
+        if yaml_path:
+            self._load_yaml(yaml_path)
+
+    @classmethod
+    def load_yaml(cls, yaml_path: Optional[str] = None) -> None:
+        """YAML の内容でクラス変数を上書きする。"""
+        if yaml_path is None:
+            yaml_path = os.environ.get("PACKMOL_UTIL_CONFIG_YAML")
+            if yaml_path is None:
+                return
+
+        with open(yaml_path, "r") as f:
+            data = yaml.safe_load(f)
+
+        if data is None:
+            return
+
+        for key, value in data.items():
+            if hasattr(cls, key):
+                setattr(cls, key, value)
+            else:
+                print("NO SUCH VAR:", key)
+
+    def _load_yaml(self, yaml_path: Optional[str] = None) -> None:
+        """YAML の内容でインスタンス属性を上書きする。"""
+        self._logger.info(f"load_yaml: {yaml_path}")
+
+        if yaml_path is None:
+            yaml_path = os.environ.get("PACKMOL_UTIL_CONFIG_YAML")
+            if yaml_path is None:
+                return
+
+        yaml_path = os.path.abspath(yaml_path)
+        self._logger.info(f"abspath: {yaml_path}")
+
+        with open(yaml_path, "r") as f:
+            data = yaml.safe_load(f)
+
+        if data is None:
+            return
+
+        for key, value in data.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+            else:
+                print("NO SUCH VAR:", key)