genice3 3.0b0__tar.gz

genice3-3.0b0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Masakazu Matsumoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

genice3-3.0b0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: genice3
+Version: 3.0b0
+Summary: A Swiss army knife to generate hydrogen-disordered ice structures.
+Author-email: Masakazu Matsumoto <vitroid@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/genice-dev/GenIce3
+Project-URL: Bug Tracker, https://github.com/genice-dev/GenIce3/issues
+Project-URL: manual, https://genice-dev.github.io/GenIce3
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=2.0.dev20160901144005
+Requires-Dist: numpy>=2.0
+Requires-Dist: pairlist>=0.6.4
+Requires-Dist: cycless>=0.7
+Requires-Dist: graphstat>=0.3.3
+Requires-Dist: yaplotlib>=0.1.2
+Requires-Dist: openpyscad>=0.5.0
+Requires-Dist: genice-core>=1.3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: cif2ice<0.5.0,>=0.4.1
+Provides-Extra: dev
+Requires-Dist: mkdocs>=1.5.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "dev"
+Requires-Dist: pymdown-extensions>=10.0; extra == "dev"
+Requires-Dist: toml>=0.10.2; extra == "dev"
+Requires-Dist: ipykernel>=6.27.1; extra == "dev"
+Requires-Dist: py3dmol>=2.0.4; extra == "dev"
+Requires-Dist: matplotlib>=3.8.2; extra == "dev"
+Requires-Dist: genice2-svg>=2.2; extra == "dev"
+Requires-Dist: plotly>=5.18.0; extra == "dev"
+Requires-Dist: nbformat>=5.9.2; extra == "dev"
+Requires-Dist: genice2-mdanalysis>=0.6.5; extra == "dev"
+Requires-Dist: requests>=2.31.0; extra == "dev"
+Requires-Dist: pytest>=8.1.1; extra == "dev"
+Requires-Dist: genice2-cif>=2.2.1; extra == "dev"
+Dynamic: license-file
+
+![Logo](https://raw.githubusercontent.com/vitroid/GenIce/develop/logo/genice-v0.png)
+
+# GenIce3
+
+A Swiss army knife to generate hydrogen-disordered ice structures.
+
+**Quick start:** Use the unit cell name as the first argument (e.g. `1h` for Ice Ih, `4` for Ice IV): `genice3 1h > ice.gro`
+
+Version 3.0b0
+
+For **usage**, **ice structures**, **output formats**, **water models**, **guest molecules**, and the full manual, see the [documentation](https://genice-dev.github.io/GenIce3).
+
+## New in GenIce3
+
+-   **Command line**: Option syntax unified; options can be read from config files.
+-   **API**: Improved API; embed protonic (H<sub>3</sub>O<sup>+</sup>, OH<sup>−</sup>) and Bjerrum topological defects via Python.
+-   **Algorithm**: Reactive pipeline with `DependencyEngine`; data generation runs automatically from your specifications.
+
+## Demo
+
+[Try GenIce3 on Google Colaboratory](https://colab.research.google.com/github/genice-dev/GenIce3/blob/main/API.ipynb).
+
+## Requirements
+
+- networkx >=2.0.dev20160901144005
+- numpy >=2.0
+- pairlist >=0.6.4
+- cycless >=0.7
+- graphstat >=0.3.3
+- yaplotlib >=0.1.2
+- openpyscad >=0.5.0
+- genice-core >=1.3.1
+- pyyaml >=6.0
+- jinja2 >=3.1.4
+- cif2ice (>=0.4.1,<0.5.0)
+
+
+## Installation
+
+GenIce3 is on [PyPI](https://pypi.org/project/genice3/). Install with pip:
+
+```shell
+pip install genice3
+```
+
+## Uninstallation
+
+```shell
+pip uninstall genice3
+```
+
+## References
+
+See the [manual → References](https://genice-dev.github.io/GenIce3/references/) for the full reference list (generated from `citations.json`).
+
+## Citation
+
+If you use GenIce in your work, please cite as in [CITATION.cff](CITATION.cff) or:
+
+> M. Matsumoto, T. Yagasaki, and H. Tanaka, "GenIce: Hydrogen-Disordered Ice Generator", _J. Comput. Chem._ **39**, 61-64 (2017). [DOI: 10.1002/jcc.25077](http://doi.org/10.1002/jcc.25077)
+
+> M. Matsumoto, T. Yagasaki, and H. Tanaka, "GenIce-core: Efficient algorithm for generation of hydrogen-disordered ice structures.", _J. Chem. Phys._ **160**, 094101 (2024). [DOI:10.1063/5.0198056](https://doi.org/10.1063/5.0198056)
+
+## How to contribute
+
+GenIce is developed on GitHub (https://github.com/genice-dev/GenIce3). Feedback, bug fixes, and contributions are welcome.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

genice3-3.0b0/README.md

@@ -0,0 +1,70 @@
+![Logo](https://raw.githubusercontent.com/vitroid/GenIce/develop/logo/genice-v0.png)
+
+# GenIce3
+
+A Swiss army knife to generate hydrogen-disordered ice structures.
+
+**Quick start:** Use the unit cell name as the first argument (e.g. `1h` for Ice Ih, `4` for Ice IV): `genice3 1h > ice.gro`
+
+Version 3.0b0
+
+For **usage**, **ice structures**, **output formats**, **water models**, **guest molecules**, and the full manual, see the [documentation](https://genice-dev.github.io/GenIce3).
+
+## New in GenIce3
+
+-   **Command line**: Option syntax unified; options can be read from config files.
+-   **API**: Improved API; embed protonic (H<sub>3</sub>O<sup>+</sup>, OH<sup>−</sup>) and Bjerrum topological defects via Python.
+-   **Algorithm**: Reactive pipeline with `DependencyEngine`; data generation runs automatically from your specifications.
+
+## Demo
+
+[Try GenIce3 on Google Colaboratory](https://colab.research.google.com/github/genice-dev/GenIce3/blob/main/API.ipynb).
+
+## Requirements
+
+- networkx >=2.0.dev20160901144005
+- numpy >=2.0
+- pairlist >=0.6.4
+- cycless >=0.7
+- graphstat >=0.3.3
+- yaplotlib >=0.1.2
+- openpyscad >=0.5.0
+- genice-core >=1.3.1
+- pyyaml >=6.0
+- jinja2 >=3.1.4
+- cif2ice (>=0.4.1,<0.5.0)
+
+
+## Installation
+
+GenIce3 is on [PyPI](https://pypi.org/project/genice3/). Install with pip:
+
+```shell
+pip install genice3
+```
+
+## Uninstallation
+
+```shell
+pip uninstall genice3
+```
+
+## References
+
+See the [manual → References](https://genice-dev.github.io/GenIce3/references/) for the full reference list (generated from `citations.json`).
+
+## Citation
+
+If you use GenIce in your work, please cite as in [CITATION.cff](CITATION.cff) or:
+
+> M. Matsumoto, T. Yagasaki, and H. Tanaka, "GenIce: Hydrogen-Disordered Ice Generator", _J. Comput. Chem._ **39**, 61-64 (2017). [DOI: 10.1002/jcc.25077](http://doi.org/10.1002/jcc.25077)
+
+> M. Matsumoto, T. Yagasaki, and H. Tanaka, "GenIce-core: Efficient algorithm for generation of hydrogen-disordered ice structures.", _J. Chem. Phys._ **160**, 094101 (2024). [DOI:10.1063/5.0198056](https://doi.org/10.1063/5.0198056)
+
+## How to contribute
+
+GenIce is developed on GitHub (https://github.com/genice-dev/GenIce3). Feedback, bug fixes, and contributions are welcome.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

genice3-3.0b0/genice3/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+
+
+class ConfigurationError(Exception):
+    """設定に関するエラーを表す例外"""
+
+    pass

genice3-3.0b0/genice3/_build.py

@@ -0,0 +1,43 @@
+"""
+カスタムビルドフック: symlinkを実際のファイルにコピーする
+"""
+import os
+import shutil
+from pathlib import Path
+from setuptools.command.build_py import build_py as _build_py
+
+
+class BuildPy(_build_py):
+    """symlinkを実際のファイルにコピーするカスタムビルドコマンド"""
+
+    def copy_file(self, src, dst, preserve_mode=True, preserve_times=True, link=None, level=1):
+        """ファイルをコピーする際に、symlinkの場合は実際のファイルをコピー"""
+        # symlinkの場合は、ターゲットファイルをコピー
+        if os.path.islink(src):
+            # symlinkのターゲットを取得
+            target = os.readlink(src)
+            
+            # 相対パスの場合は、srcのディレクトリからの相対パスとして解決
+            if not os.path.isabs(target):
+                src_dir = os.path.dirname(src)
+                target_path = os.path.normpath(os.path.join(src_dir, target))
+            else:
+                target_path = target
+            
+            # ターゲットファイルが存在する場合のみコピー
+            if os.path.exists(target_path):
+                # ターゲットファイルをコピー（再帰的に呼び出し）
+                return super().copy_file(
+                    target_path, dst, preserve_mode, preserve_times, link, level
+                )
+            else:
+                # ターゲットが見つからない場合は警告を出してスキップ
+                print(f"Warning: symlink target not found: {src} -> {target_path}")
+                return dst, False
+        
+        # 通常のファイルの場合は親クラスのメソッドを呼び出す
+        return super().copy_file(src, dst, preserve_mode, preserve_times, link, level)
+
+
+
+

genice3-3.0b0/genice3/cage.py

@@ -0,0 +1,160 @@
+"""
+Utility functions for genice3
+"""
+
+import numpy as np
+from dataclasses import dataclass
+import string
+from logging import getLogger
+
+import networkx as nx
+from cycless import center_of_graph
+from cycless.cycles import cycles_iter
+from cycless.polyhed import cage_to_graph, polyhedra_iter
+from graphstat import GraphStat
+
+
+@dataclass
+class CageSpec:
+    """ケージの仕様。cage_type は "A12" などのケージ種別を表す文字列。"""
+
+    cage_type: str  # A12, 1b, etc.
+    faces: str  # 5^12 6^2, etc.
+    graph: nx.Graph  # ケージを構成する水分子ノードのグラフ
+
+    def to_json_capable_data(self) -> dict:
+        return {
+            "cage_type": self.cage_type,
+            "faces": self.faces,
+            "nodes": [int(x) for x in self.graph],
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"CageSpec(cage_type={self.cage_type!r}, "
+            f"faces={self.faces!r}, "
+            f"n_nodes={self.graph.number_of_nodes()})"
+        )
+
+    def __str__(self) -> str:
+        return f"{self.cage_type} ({self.faces}) {self.graph.number_of_nodes()} nodes"
+
+
+@dataclass
+class CageSpecs:
+    """拡大単位胞内の全ケージの位置と仕様。
+
+    specs: 各ケージの CageSpec（cage_type, faces, graph）。
+    positions: 分数座標の配列（Nx3）。specs と同順。
+    node_to_cage_indices: __post_init__ で生成。ノード番号 → そのノードを含むケージのインデックスリスト。
+    """
+
+    specs: list[CageSpec]
+    positions: np.ndarray  # in fractional coordinates
+
+    def __post_init__(self) -> None:
+        """ノード番号 → ケージ番号の逆引き辞書を生成。"""
+        self.node_to_cage_indices: dict[int, list[int]] = {}
+        for cage_idx, spec in enumerate(self.specs):
+            for node in spec.graph:
+                self.node_to_cage_indices.setdefault(int(node), []).append(cage_idx)
+
+    def to_json_capable_data(self) -> dict:
+        """JSON シリアライズ用の辞書を返す。キーはケージインデックス、値は frac_pos と specs。"""
+        data = []
+        for position, specs in zip(self.positions, self.specs):
+            data.append(
+                {
+                    "frac_pos": position.tolist(),
+                    "specs": specs.to_json_capable_data(),
+                }
+            )
+        return dict(enumerate(data))
+
+    def __repr__(self) -> str:
+        return (
+            f"CageSpecs(n_cages={len(self.specs)}, "
+            f"positions_shape={self.positions.shape})"
+        )
+
+
+def _assign_cage_type(basename: int, existing_types: set[str]) -> str:
+    """未使用のケージタイプ名（A12, A12a など）を生成する。"""
+    enum = 0
+    cage_type = f"A{basename}"
+    while cage_type in existing_types:
+        char = string.ascii_lowercase[enum]
+        cage_type = f"A{basename}{char}"
+        enum += 1
+    return cage_type
+
+
+def _make_cage_expression(ring_ids: list, ringlist: list) -> str:
+    """ケージを構成するリングのサイズから "5^12 6^2" のような面表現文字列を生成する。"""
+    ringcount = [0 for i in range(9)]
+    for ring in ring_ids:
+        ringcount[len(ringlist[ring])] += 1
+    index = []
+    for i in range(9):
+        if ringcount[i] > 0:
+            index.append(f"{i}^{ringcount[i]}")
+    index = " ".join(index)
+    return index
+
+
+def assess_cages(
+    graph: nx.Graph, node_frac: np.ndarray
+) -> CageSpecs:
+    """水素結合グラフとノードの分数座標からケージを検出・分類し、CageSpecs を返す。
+
+    Args:
+        graph: 水素結合ネットワーク（無向グラフ）。
+        node_frac: ノードの分数座標（Nx3）。
+
+    Returns:
+        検出されたケージの位置（分数座標）と仕様（CageSpec のリスト）。
+    """
+    logger = getLogger()
+
+    # Prepare the list of rings
+    # taking the positions in PBC into account.
+    ringlist = [
+        [int(x) for x in ring]
+        for ring in cycles_iter(nx.Graph(graph), 8, pos=node_frac)
+    ]
+
+    MaxCageSize = 22
+    cage_fracs = []
+    # data storage of the found cages
+    db = GraphStat()
+    existing_cage_types: set[str] = set()
+    g_id_to_cage_type: dict[int, str] = {}
+
+    # Detect cages and classify
+    cages = [cage for cage in polyhedra_iter(ringlist, MaxCageSize)]
+    cage_graphs = [cage_to_graph(cage, ringlist) for cage in cages]
+    cage_fracs = [center_of_graph(g, node_frac) for g in cage_graphs]
+    if len(cage_fracs) == 0:
+        logger.info("    No cages detected.")
+
+    cagespecs = []
+    for cage, g in zip(cages, cage_graphs):
+        cagesize = len(cage)
+        graph_id = db.query_id(g)
+        # if it is a new cage type
+        if graph_id < 0:
+            # new type!
+            # register the last query
+            graph_id = db.register()
+
+            cage_type = _assign_cage_type(cagesize, existing_cage_types)
+            g_id_to_cage_type[graph_id] = cage_type
+            existing_cage_types.add(cage_type)
+        else:
+            cage_type = g_id_to_cage_type[graph_id]
+        faces = _make_cage_expression(cage, ringlist)
+        cagespecs.append(CageSpec(cage_type=cage_type, faces=faces, graph=g))
+        # print(f"{label=}, {faces=}, {ringlist=}")
+        # print([len(ringlist[ring]) for ring in cage])
+
+    return CageSpecs(specs=cagespecs, positions=np.array(cage_fracs))

genice3-3.0b0/genice3/cli/__init__.py

@@ -0,0 +1,20 @@
+"""
+genice3 CLI パッケージ。
+
+- option_parser: option_handling.md に基づくオプション文字列パーサー
+- runner: argv のパースとプラグイン dispatch（parse_argv, validate_result）
+"""
+
+from genice3.cli.option_parser import (
+    parse_options,
+    structure_for_display,
+    scalarize_single_item_lists,
+    structure_to_option_string,
+)
+
+__all__ = [
+    "parse_options",
+    "structure_for_display",
+    "scalarize_single_item_lists",
+    "structure_to_option_string",
+]

genice3-3.0b0/genice3/cli/genice.py

@@ -0,0 +1,168 @@
+from logging import getLogger, basicConfig, DEBUG, INFO
+import sys
+from importlib.metadata import version, PackageNotFoundError
+
+from genice3.plugin import safe_import
+from genice3.genice import GenIce3, log_cation_cages, log_spot_cation_cages
+from genice3.cli.runner import parse_argv, validate_result
+from genice3.cli.options import (
+    BASE_HELP_ORDER,
+    get_option_def,
+    format_option_for_help,
+    extract_genice_args,
+    validate_parsed_options,
+)
+
+
+def get_version():
+    """パッケージのバージョンを取得する。見つからない場合はデフォルト値を返す。"""
+    try:
+        return version("genice3")
+    except PackageNotFoundError:
+        return "3.*.*.*"
+
+
+# ヘルプ整形: 先頭2スペース＋オプション書式が24文字超なら改行。説明は28〜72桁で折り返し。
+_HELP_OPTION_MAX = 24  # 2スペース＋オプションがこの桁数までなら1行に
+_HELP_DESC_START = 28  # 説明開始桁（1-based）
+_HELP_DESC_END = 72
+_HELP_DESC_WIDTH = _HELP_DESC_END - _HELP_DESC_START + 1  # 45
+
+
+def _wrap_desc(text: str, width: int) -> list[str]:
+    """説明文を width 文字で折り返した行リストを返す"""
+    words = text.split()
+    lines: list[str] = []
+    current: list[str] = []
+    current_len = 0
+    for w in words:
+        need = len(w) + (1 if current else 0)
+        if current_len + need <= width:
+            current.append(w)
+            current_len += need
+        else:
+            if current:
+                lines.append(" ".join(current))
+            current = [w]
+            current_len = len(w)
+    if current:
+        lines.append(" ".join(current))
+    return lines
+
+
+def _opt_line(option: str, description: str) -> list[str]:
+    """オプション1件を指定ルールで整形。2スペース＋オプションが24文字超なら改行。説明は28〜72桁で折り畳み。"""
+    head_len = 2 + len(option)  # 先頭2スペース＋オプション
+    desc_lines = _wrap_desc(description, _HELP_DESC_WIDTH)
+    indent = " " * (_HELP_DESC_START - 1)  # 説明行の左インデント（27スペース）
+
+    if head_len > _HELP_OPTION_MAX:
+        # オプションだけ1行、説明は次の行から28桁目から
+        out = ["  " + option]
+        for line in desc_lines:
+            out.append(indent + line)
+        return out
+    # オプション＋説明を同じ行から（オプション後に空白を入れて28桁目に合わせる）
+    pad = _HELP_DESC_START - 1 - head_len  # 2 + len(option) + pad == 27
+    out = ["  " + option + " " * pad + desc_lines[0]]
+    for line in desc_lines[1:]:
+        out.append(indent + line)
+    return out
+
+
+def print_help():
+    """ヘルプメッセージを表示（options のオプション定義から組み立て）"""
+    print("Usage: genice3 [OPTIONS] UNITCELL")
+    print()
+    print("Options:")
+    seen = set()  # rep / replication_factors は同じ行なので1回だけ表示
+    for name in BASE_HELP_ORDER:
+        if name in seen:
+            continue
+        def_ = get_option_def(name)
+        if def_ is None or def_.help_text is None:
+            continue
+        if def_.name == "replication_factors":
+            seen.add("rep")
+        seen.add(def_.name)
+        opt_str = format_option_for_help(def_)
+        for line in _opt_line(opt_str, def_.help_text):
+            print(line)
+    print()
+    print("Arguments:")
+    for line in _opt_line("UNITCELL", "Unitcell plugin name (required)"):
+        print(line)
+
+
+def main() -> None:
+    """メイン関数"""
+    # --helpと--versionを先に処理
+    if "--help" in sys.argv or "-h" in sys.argv:
+        print_help()
+        sys.exit(0)
+    if "--version" in sys.argv or "-V" in sys.argv:
+        print(f"genice3 {get_version()}")
+        sys.exit(0)
+
+    # ロギングを初期化（デフォルトはINFOレベル）
+    basicConfig(level=INFO)
+    logger = getLogger()
+
+    try:
+        result = parse_argv(sys.argv[1:])
+    except Exception as e:
+        logger.error(f"パースエラー: {e}")
+        import traceback
+
+        traceback.print_exc()
+        sys.exit(1)
+
+    # バリデーション
+    is_valid, errors = validate_result(result)
+    if not is_valid:
+        for error in errors:
+            logger.error(error)
+        sys.exit(1)
+
+    base_options = result["base_options"]
+    if base_options.get("debug"):
+        logger.setLevel(DEBUG)
+        for handler in logger.handlers:
+            handler.setLevel(DEBUG)
+
+    try:
+        validate_parsed_options(base_options)
+    except ValueError as e:
+        logger.error(str(e))
+        sys.exit(1)
+
+    genice_kwargs = extract_genice_args(base_options)
+    logger.debug(f"Settings: {genice_kwargs}")
+
+    unitcell_name = result["unitcell"]["name"]
+    unitcell_processed = result["unitcell"]["processed"]
+    exporter_name = result["exporter"]["name"] or "gromacs"
+    exporter_processed = result["exporter"]["processed"]
+
+    genice = GenIce3(**genice_kwargs)
+
+    # unitcellプラグインを設定
+    genice.unitcell = safe_import("unitcell", unitcell_name).UnitCell(
+        **unitcell_processed
+    )
+
+    log_spot_cation_cages(genice)
+    log_cation_cages(genice)
+
+    # コマンドライン全体を取得
+    command_line = " ".join(sys.argv)
+    exporter_processed["command_line"] = command_line
+
+    # exporterプラグインを実行
+    safe_import("exporter", exporter_name).dump(
+        genice, sys.stdout, **exporter_processed
+    )
+
+
+if __name__ == "__main__":
+    main()

genice3-3.0b0/genice3/cli/option_def.py

@@ -0,0 +1,25 @@
+"""OptionDef と型定数（--help と検証用）。options と validator の両方から参照する。"""
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+OPTION_TYPE_FLAG = "flag"
+OPTION_TYPE_STRING = "string"
+OPTION_TYPE_TUPLE = "tuple"
+OPTION_TYPE_KEYVALUE = "keyvalue"
+
+
+@dataclass(frozen=True)
+class OptionDef:
+    """CLI で認識するオプションの定義（ヘルプ・検証用）。"""
+
+    name: str
+    short: Optional[str] = None
+    is_flag: bool = False
+    max_values: Optional[int] = None
+    level: str = "base"
+    parse_type: Optional[str] = None
+    metavar: Optional[str] = None
+    help_text: Optional[str] = None
+    help_format: Optional[str] = None
+    parse_validator: Optional[Callable[[Any], None]] = None