genice3 3.0__py3-none-any.whl

dependency_engine/__init__.py

@@ -0,0 +1,218 @@
+"""
+Dependency-resolution engine for reactive pipelines.
+
+Executes only the tasks needed to reach a given goal, working backwards
+from the target. May be split into a separate package in the future.
+"""
+
+import inspect
+from logging import getLogger
+import time
+
+# @reactive でデコレートされた関数を (モジュール名, 関数) で保持。
+# 利用側が _register_tasks で get_reactive_tasks(__name__) により自モジュール分だけ登録する。
+_REACTIVE_REGISTRY = []
+
+# Sentinel: Input に default も default_factory もない。
+_MISSING = object()
+
+
+class UnsetInputError(Exception):
+    """Raised when a required ``Input`` has not been assigned."""
+
+
+def reactive(func=None, *, public=False):
+    """Marker decorator to register a function as a DependencyEngine task.
+
+    The decorated function name becomes the reactive property name
+    (for example, ``genice.cages``). Names should be nouns.
+
+    Args:
+        public: If True, the task is part of the public API listing.
+
+    Side effect: the function is registered in ``_REACTIVE_REGISTRY``.
+    Use ``get_reactive_tasks(module_name)`` to obtain the task list for a module.
+    """
+
+    def decorate(fn):
+        fn._reactive_public = public
+        _REACTIVE_REGISTRY.append((fn.__module__, fn))
+        return fn
+
+    if func is None:
+        return decorate
+    return decorate(func)
+
+
+def get_reactive_tasks(module_name: str):
+    """Return functions decorated with ``@reactive`` in the given module."""
+    return [f for mod, f in _REACTIVE_REGISTRY if mod == module_name]
+
+
+class Input:
+    """Descriptor for a DAG root (settable reactive input).
+
+    Assignment stores the value, optionally coerces it (same kind of object),
+    runs ``on_set``, and clears ``obj.engine.cache``. Getter and
+    ``collect_inputs`` are derived from the class-level declaration.
+
+    Do not use ``coerce`` to change the public type (for example str to a
+    constructed object). Keep a separate factory method for that.
+    """
+
+    def __init__(
+        self,
+        *,
+        default=_MISSING,
+        default_factory=None,
+        public=False,
+        required=False,
+        coerce=None,
+        on_set=None,
+        unset_error=None,
+        doc=None,
+    ):
+        if required and (default is not _MISSING or default_factory is not None):
+            raise TypeError("required Input cannot have a default")
+        if default is not _MISSING and default_factory is not None:
+            raise TypeError("specify default or default_factory, not both")
+        self.default = default
+        self.default_factory = default_factory
+        self.public = public
+        self.required = required
+        self.coerce = coerce
+        self.on_set = on_set
+        self.unset_error = unset_error
+        self.name = None
+        self.private_name = None
+        if doc is not None:
+            self.__doc__ = doc
+
+    def __set_name__(self, owner, name):
+        self.name = name
+        self.private_name = f"_{name}"
+        if "_input_fields" not in owner.__dict__:
+            owner._input_fields = {}
+        owner._input_fields[name] = self
+
+    def is_set(self, obj) -> bool:
+        """Return True if this input has been assigned on ``obj``."""
+        return self.private_name in obj.__dict__
+
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            return self
+        if self.private_name in obj.__dict__:
+            return obj.__dict__[self.private_name]
+        if self.required:
+            if self.unset_error is not None:
+                err = self.unset_error
+                raise err() if callable(err) else err
+            raise UnsetInputError(
+                f"{type(obj).__name__}.{self.name} is not set."
+            )
+        if self.default_factory is not None:
+            return self.default_factory()
+        if self.default is not _MISSING:
+            return self.default
+        raise UnsetInputError(f"{type(obj).__name__}.{self.name} is not set.")
+
+    def __set__(self, obj, value):
+        if self.coerce is not None:
+            value = self.coerce(value)
+        obj.__dict__[self.private_name] = value
+        logger = getattr(obj, "logger", None)
+        if logger is not None:
+            logger.debug("  %s=%r", self.name, value)
+        if self.on_set is not None:
+            self.on_set(obj, value)
+        engine = getattr(obj, "engine", None)
+        if engine is not None:
+            engine.cache.clear()
+
+
+def input_fields(cls) -> dict:
+    """Return ``{name: Input}`` declared on ``cls`` (including bases)."""
+    fields = {}
+    for base in reversed(cls.__mro__):
+        fields.update(getattr(base, "_input_fields", {}))
+    return fields
+
+
+def collect_inputs(obj) -> dict:
+    """Return a dict of all ``Input`` values on ``obj`` for ``engine.resolve``."""
+    return {name: getattr(obj, name) for name in input_fields(type(obj))}
+
+
+class DependencyEngine:
+    """Engine that back-solves dependencies and runs only needed tasks."""
+
+    logger = getLogger("dependency_engine")
+
+    def __init__(self):
+        self.registry = {}  # { 'output_name': function }
+        self.cache = {}
+
+    def task(self, func):
+        """Decorator to register a task with ``func.__name__`` as its output name."""
+        self.registry[func.__name__] = func
+        return func
+
+    def resolve(self, target: str, inputs: dict):
+        """Resolve ``target`` by recursively computing its dependencies."""
+
+        # 1. 既に計算済み or 入力として与えられているならそれを返す
+        if target in inputs:
+            return inputs[target]
+        if target in self.cache:
+            return self.cache[target]
+
+        # 2. 生成ルール（関数）を探す
+        if target not in self.registry:
+            raise ValueError(f"Don't know how to make '{target}'")
+
+        func = self.registry[target]
+
+        # 3. その関数の引数（依存先）を調べて、再帰的に解決する
+        sig = inspect.signature(func)
+        dependencies = {}
+        for param_name in sig.parameters:
+            dependencies[param_name] = self.resolve(param_name, inputs)
+
+        # 4. 実行して結果を保存（所要時間は JSON ログの duration_ms にも載せる）
+        now = time.time()
+        result = func(**dependencies)
+        delta_ms = (time.time() - now) * 1000.0
+        self.logger.info(
+            "Executing: %s",
+            target,
+            extra={
+                "event": "task.execute",
+                "task": target,
+                "duration_ms": round(delta_ms, 3),
+            },
+        )
+        self.cache[target] = result
+        return result
+
+
+def _demo():
+    """Package self-test demo (run with ``python -m dependency_engine``)."""
+    engine = DependencyEngine()
+
+    @engine.task
+    def reaction_A(raw_material: int):
+        return raw_material * 2
+
+    @engine.task
+    def reaction_B(reaction_A: int, catalyst: int):
+        return reaction_A + catalyst
+
+    result = engine.resolve(
+        target="reaction_B", inputs={"raw_material": 10, "catalyst": 5}
+    )
+    print(result)
+
+
+if __name__ == "__main__":
+    _demo()

dependency_engine/__main__.py

@@ -0,0 +1,4 @@
+"""python -m dependency_engine でデモを実行"""
+from dependency_engine import _demo
+
+_demo()

genice3/__init__.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+from logging import getLogger
+
+from genice3.logging_config import setup_logging as _setup_logging_impl
+
+
+class ConfigurationError(Exception):
+    """設定に関するエラーを表す例外"""
+
+    pass
+
+
+def _setup_logging(debug: bool = False, fmt: str | None = None) -> str:
+    """ルートロガーの設定を統一する（:func:`genice3.logging_config.setup_logging` への薄いラップ）。"""
+    return _setup_logging_impl(debug=debug, fmt=fmt)
+
+
+# API利用時にも明示的な呼び出しなしでINFOログが出るよう、
+# ハンドラ未設定の場合だけデフォルト設定を適用する。
+# （ユーザーが事前に basicConfig 等を呼んでいる場合はそちらを尊重する）
+if not getLogger().handlers:
+    _setup_logging(debug=False)

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/cage.py

@@ -0,0 +1,202 @@
+"""
+Utility functions for genice3
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from dataclasses import dataclass
+import string
+from logging import getLogger
+from typing import TYPE_CHECKING
+
+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
+
+if TYPE_CHECKING:
+    from genice3.genice import GenIce3
+
+
+@dataclass
+class CageSpec:
+    """Specification of a cage.
+
+    ``cage_type`` is a string such as "A12" that represents the cage type.
+    """
+
+    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": sorted(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:
+    """Positions and specifications of all cages in the expanded unit cell.
+
+    specs: A list of ``CageSpec`` (cage_type, faces, graph) for each cage.
+    positions: Array of fractional coordinates (Nx3), in the same order as ``specs``.
+    node_to_cage_indices: Mapping generated in ``__post_init__``; node index -> list of cage indices that contain the node.
+    """
+
+    specs: list[CageSpec]
+    positions: np.ndarray  # in fractional coordinates
+
+    def __post_init__(self) -> None:
+        """Build a reverse lookup dictionary from node index to cage indices."""
+        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:
+        """Return a dict suitable for JSON serialization.
+
+        Keys are cage indices; values contain ``frac_pos`` and ``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:
+    """Generate an unused cage type name (e.g., 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:
+    """Generate a face-expression string such as "5^12 6^2".
+
+    The expression is built from the sizes of the rings that form the cage.
+    """
+    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,
+    *,
+    max_cage_rings: int = 16,
+) -> CageSpecs:
+    """Detect and classify cages from a hydrogen-bond graph.
+
+    Cages are defined here as quasipolyhedra surrounded by cycles of
+    hydrogen bonds [Matsumoto 2007].
+
+    Args:
+        graph: Undirected graph representing the hydrogen-bond network.
+        node_frac: Fractional coordinates of nodes (Nx3).
+        max_cage_rings: Upper bound on the number of rings (faces) per cage
+            passed to ``polyhedra_iter`` (default 16, historical GenIce used 22).
+
+    Returns:
+        A ``CageSpecs`` object containing the positions (fractional
+        coordinates) and specifications (list of ``CageSpec``) of the
+        detected cages.
+    """
+    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)
+    ]
+    # logger.info(f"{len(ringlist)=} {graph.number_of_nodes()=}")
+    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, max_cage_rings)]
+    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))
+
+
+def apply_max_cage_rings(genice: GenIce3, max_cage_rings: int | None) -> None:
+    """単位胞のケージ検出のリング数上限を変え、GenIce3 のリアクティブキャッシュを無効化する。
+
+    CIF 等で既に ``_cages`` が埋まっている単位胞（``_cages_lazy`` が False）では何もしない。
+    """
+    if max_cage_rings is None:
+        return
+    uc = genice.unitcell
+    if not getattr(uc, "_cages_lazy", True):
+        return
+    v = int(max_cage_rings)
+    if v < 1:
+        raise ValueError(f"max_cage_rings must be >= 1, got {v}")
+    uc._max_cage_rings = v
+    uc._cages = None
+    genice.engine.cache.clear()

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/cli/engine.py

@@ -0,0 +1,71 @@
+"""
+CLI / Web 等が共有する GenIce3 実行コア（パース済み result → exporter 出力）。
+"""
+
+from __future__ import annotations
+
+import time
+from logging import getLogger
+from typing import Any, Dict, TextIO
+
+from genice3.cage import apply_max_cage_rings
+from genice3.genice import GenIce3
+from genice3.plugin import safe_import
+from genice3.cli.options import extract_genice_args
+
+logger = getLogger(__name__)
+
+
+def run_parsed_result(
+    result: Dict[str, Any],
+    file: TextIO,
+    *,
+    command_line: str | None = None,
+) -> None:
+    """パース・検証済みの ``result`` で GenIce3 を実行し、exporter 出力を ``file`` に書く。
+
+    Args:
+        result: :func:`genice3.cli.runner.parse_argv` または
+            :func:`genice3.cli.runner.parsed_result_from_merged` が返す辞書。
+        file: 出力先（例: ``sys.stdout``、``io.StringIO()``）。
+        command_line: exporter に渡すメタ用。省略時は ``""``。
+
+    Raises:
+        プラグインや exporter の例外はそのまま伝播する（呼び出し側で捕捉してよい）。
+    """
+    base_options = result["base_options"]
+    genice_kwargs = extract_genice_args(base_options)
+
+    unitcell_name = result["unitcell"]["name"]
+    unitcell_processed = result["unitcell"]["processed"]
+    exporter_name = result["exporter"]["name"] or "gromacs"
+    exporter_processed = dict(result["exporter"]["processed"])
+
+    genice = GenIce3(**genice_kwargs)
+    genice.unitcell = safe_import("unitcell", unitcell_name).UnitCell(**unitcell_processed)
+
+    if exporter_name == "cage_survey":
+        apply_max_cage_rings(genice, exporter_processed.get("max_cage_rings"))
+
+    exporter_processed["command_line"] = command_line if command_line is not None else ""
+
+    logger.info(
+        "Executing exporter: %s",
+        exporter_name,
+        extra={"event": "exporter.execute", "exporter": exporter_name},
+    )
+    t0 = time.time()
+    try:
+        safe_import("exporter", exporter_name).dump(genice, file, **exporter_processed)
+    finally:
+        duration_ms = round((time.time() - t0) * 1000.0, 3)
+        logger.info(
+            "  %.4f sec for exporter %s",
+            time.time() - t0,
+            exporter_name,
+            extra={
+                "event": "exporter.execute",
+                "exporter": exporter_name,
+                "duration_ms": duration_ms,
+            },
+        )