pymdkit 1.6.2__tar.gz → 1.6.4__tar.gz

{pymdkit-1.6.2 → pymdkit-1.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.6.2
+Version: 1.6.4
 Summary: A unified command-line toolkit for atomistic / MD structure workflows.
 Author-email: Yueda Wang <ydwang0608@ustc.edu.cn>
 License-Expression: GPL-3.0-or-later
@@ -63,6 +63,27 @@ pmk -help                   # lists every command
 pmk <command> -help         # shows that command's flags
 ```
 
+## Global configuration and logs
+
+On first use, PMK creates `.pmkrc.yaml` in the active Python environment root.
+For example, an executable at `~/anaconda3/envs/pymdkit/bin/pmk` uses
+`~/anaconda3/envs/pymdkit/.pmkrc.yaml`. View the active file and settings with:
+
+```bash
+pmk config
+pmk config silence -on
+pmk config silence -off
+```
+
+With silence enabled, successful commands do not print to the terminal. Errors
+that prevent an operation are still shown. Command details are never discarded:
+every `pmk <command> ...` invocation appends its exact command, timestamp, exit
+status, and screen output to `<command>.txt` in the directory where PMK was
+invoked. Repeated runs remain in chronological order in the same file. This log
+always stays in the invocation directory even when `-of` selects an output
+folder. Existing command reports that use the same filename, such as `rmsd.txt`
+and `ehull.txt`, are preserved as the report section of that run.
+
 ## Commands
 
 Commands that transform structures accept either a single file (`-i`/`-o`) or a
@@ -71,6 +92,7 @@ directory for job sub-folders automatically.
 
 | Command | What it does |
 |---|---|
+| `config` | View or edit global PMK settings in `.pmkrc.yaml` |
 | `add-config-type` | Add Config_type to one XYZ structure or every trajectory frame |
 | `gpumd-group` | Tag atoms with a GPUMD group index by element order |
 | `gpumd-relax` | Write GPUMD energy-minimization jobs for a file, folder, or trajectory |
@@ -265,7 +287,7 @@ first, until every multiplicity times occupancy times supercell determinant is
 an integer. Equal-volume choices favor the most isotropic resulting cell.
 All selections, site atom counts, oxidation states, charges, failures, the
 allowed occupancy grid, and the final summary are recorded in
-`OUTPUT/realloc-occ.txt` for both single-file and folder modes.
+`realloc-occ.txt` in the invocation directory for both single-file and folder modes.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -336,8 +358,14 @@ CIF input with pymatgen rather than ASE. ASE interprets
 `_space_group_crystal_system` as a setting hint only for rhombohedral groups
 and emits a potentially misleading warning for other crystal systems. Using
 pymatgen avoids that ambiguity while PMK continues to use ASE for non-CIF
-formats. A partially occupied CIF must first be ordered with `convert -d2o`
-before it can be represented as an explicit atom list.
+formats. Pymatgen intentionally snaps fractional coordinates within its
+default `1e-4` tolerance to ideal values before applying symmetry. PMK keeps
+that corrective behavior but hides only its corresponding finite-precision
+notice; composition, occupancy, malformed-CIF, and all other warnings remain
+visible. See the
+[pymatgen CifParser documentation](https://pymatgen.org/pymatgen.io.html#pymatgen.io.cif.CifParser).
+A partially occupied CIF must first be ordered with `convert -d2o` before it
+can be represented as an explicit atom list.
 
 CIF `_atom_type_symbol` and `_atom_site_label` values use per-element
 inequivalent-site identifiers such as `Li1`, `Y1`, `Cl1`, and `Cl2`.

{pymdkit-1.6.2 → pymdkit-1.6.4}/README.md

@@ -36,6 +36,27 @@ pmk -help                   # lists every command
 pmk <command> -help         # shows that command's flags
 ```
 
+## Global configuration and logs
+
+On first use, PMK creates `.pmkrc.yaml` in the active Python environment root.
+For example, an executable at `~/anaconda3/envs/pymdkit/bin/pmk` uses
+`~/anaconda3/envs/pymdkit/.pmkrc.yaml`. View the active file and settings with:
+
+```bash
+pmk config
+pmk config silence -on
+pmk config silence -off
+```
+
+With silence enabled, successful commands do not print to the terminal. Errors
+that prevent an operation are still shown. Command details are never discarded:
+every `pmk <command> ...` invocation appends its exact command, timestamp, exit
+status, and screen output to `<command>.txt` in the directory where PMK was
+invoked. Repeated runs remain in chronological order in the same file. This log
+always stays in the invocation directory even when `-of` selects an output
+folder. Existing command reports that use the same filename, such as `rmsd.txt`
+and `ehull.txt`, are preserved as the report section of that run.
+
 ## Commands
 
 Commands that transform structures accept either a single file (`-i`/`-o`) or a
@@ -44,6 +65,7 @@ directory for job sub-folders automatically.
 
 | Command | What it does |
 |---|---|
+| `config` | View or edit global PMK settings in `.pmkrc.yaml` |
 | `add-config-type` | Add Config_type to one XYZ structure or every trajectory frame |
 | `gpumd-group` | Tag atoms with a GPUMD group index by element order |
 | `gpumd-relax` | Write GPUMD energy-minimization jobs for a file, folder, or trajectory |
@@ -238,7 +260,7 @@ first, until every multiplicity times occupancy times supercell determinant is
 an integer. Equal-volume choices favor the most isotropic resulting cell.
 All selections, site atom counts, oxidation states, charges, failures, the
 allowed occupancy grid, and the final summary are recorded in
-`OUTPUT/realloc-occ.txt` for both single-file and folder modes.
+`realloc-occ.txt` in the invocation directory for both single-file and folder modes.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -309,8 +331,14 @@ CIF input with pymatgen rather than ASE. ASE interprets
 `_space_group_crystal_system` as a setting hint only for rhombohedral groups
 and emits a potentially misleading warning for other crystal systems. Using
 pymatgen avoids that ambiguity while PMK continues to use ASE for non-CIF
-formats. A partially occupied CIF must first be ordered with `convert -d2o`
-before it can be represented as an explicit atom list.
+formats. Pymatgen intentionally snaps fractional coordinates within its
+default `1e-4` tolerance to ideal values before applying symmetry. PMK keeps
+that corrective behavior but hides only its corresponding finite-precision
+notice; composition, occupancy, malformed-CIF, and all other warnings remain
+visible. See the
+[pymatgen CifParser documentation](https://pymatgen.org/pymatgen.io.html#pymatgen.io.cif.CifParser).
+A partially occupied CIF must first be ordered with `convert -d2o` before it
+can be represented as an explicit atom list.
 
 CIF `_atom_type_symbol` and `_atom_site_label` values use per-element
 inequivalent-site identifiers such as `Li1`, `Y1`, `Cl1`, and `Cl2`.

{pymdkit-1.6.2 → pymdkit-1.6.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pymdkit"
-version = "1.6.2"
+version = "1.6.4"
 description = "A unified command-line toolkit for atomistic / MD structure workflows."
 readme = "README.md"
 requires-python = ">=3.9"

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/__init__.py

@@ -1,3 +1,3 @@
 """pymdkit -- a unified CLI for atomistic / MD structure workflows."""
 
-__version__ = "1.6.2"
+__version__ = "1.6.4"

pymdkit-1.6.4/src/pymdkit/_config.py

@@ -0,0 +1,89 @@
+"""Global PMK configuration stored in the active Python environment."""
+
+from __future__ import annotations
+
+import ast
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+DEFAULT_CONFIG: Dict[str, Any] = {"silence": False}
+
+
+def config_path() -> Path:
+    """Return the PMK configuration file for the active Python environment."""
+    override = os.environ.get("PMK_CONFIG_FILE")
+    if override:
+        return Path(override).expanduser().resolve()
+    return Path(sys.prefix).resolve() / ".pmkrc.yaml"
+
+
+def _parse_scalar(raw: str) -> Any:
+    value = raw.strip()
+    lowered = value.lower()
+    if lowered in {"true", "yes", "on"}:
+        return True
+    if lowered in {"false", "no", "off"}:
+        return False
+    if lowered in {"null", "none", "~"}:
+        return None
+    try:
+        return ast.literal_eval(value)
+    except (SyntaxError, ValueError):
+        return value
+
+
+def _read_flat_yaml(path: Path) -> Dict[str, Any]:
+    settings: Dict[str, Any] = {}
+    for line_number, line in enumerate(path.read_text(encoding="utf-8-sig").splitlines(), 1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if ":" not in line:
+            raise ValueError(f"invalid YAML at {path}:{line_number}: expected 'name: value'")
+        key, raw = line.split(":", 1)
+        key = key.strip()
+        if not key or any(char.isspace() for char in key):
+            raise ValueError(f"invalid setting name at {path}:{line_number}")
+        settings[key] = _parse_scalar(raw)
+    return settings
+
+
+def _format_scalar(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value is None:
+        return "null"
+    if isinstance(value, (int, float)):
+        return str(value)
+    return json.dumps(str(value), ensure_ascii=True)
+
+
+def save_config(settings: Dict[str, Any], path: Optional[Path] = None) -> Path:
+    destination = config_path() if path is None else Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    ordered_keys = [key for key in DEFAULT_CONFIG if key in settings]
+    ordered_keys.extend(sorted(key for key in settings if key not in DEFAULT_CONFIG))
+    text = "# Global PMK settings. Edit with `pmk config` or a text editor.\n"
+    text += "".join(f"{key}: {_format_scalar(settings[key])}\n" for key in ordered_keys)
+    temporary = destination.with_name(f".{destination.name}.{os.getpid()}.tmp")
+    temporary.write_text(text, encoding="utf-8")
+    temporary.replace(destination)
+    return destination
+
+
+def load_config(*, create: bool = True) -> Dict[str, Any]:
+    path = config_path()
+    if path.exists():
+        settings = _read_flat_yaml(path)
+    else:
+        settings = {}
+    merged = dict(DEFAULT_CONFIG)
+    merged.update(settings)
+    if not isinstance(merged["silence"], bool):
+        raise ValueError(f"setting 'silence' in {path} must be true or false")
+    if create and not path.exists():
+        save_config(merged, path)
+    return merged

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/commands/_cifio.py

@@ -41,12 +41,31 @@ CIF_FLOAT_TAGS = {
 _CIF_DECIMAL_RE = re.compile(
     r"[-+]?(?:(?:\d+\.\d*|\.\d+)(?:[eE][-+]?\d+)?|\d+[eE][-+]?\d+)"
 )
+_BENIGN_FRACTIONAL_ROUNDING_WARNING = (
+    r"Issues encountered while parsing CIF:\s*\d+ fractional coordinates? "
+    r"rounded to ideal values to avoid issues with finite precision\.\s*$"
+)
 
 
 def is_cif(path):
     return Path(path).suffix.lower() == ".cif"
 
 
+def read_structure(path):
+    """Read with pymatgen, hiding only its benign CIF idealization notice."""
+    from pymatgen.core import Structure
+
+    if not is_cif(path):
+        return Structure.from_file(str(path))
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message=_BENIGN_FRACTIONAL_ROUNDING_WARNING,
+            category=UserWarning,
+        )
+        return Structure.from_file(str(path))
+
+
 def as_pymatgen_structure(structure):
     """Return a periodic pymatgen Structure from pymatgen or ASE input."""
     from pymatgen.core import Structure

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/commands/_symmetry.py

@@ -36,11 +36,9 @@ DEFAULT_OXIDATION_STATES = {
 
 
 def load_structure(path):
-    from pymatgen.core import Structure
-
     path = Path(path)
     try:
-        return Structure.from_file(str(path))
+        return _cifio.read_structure(path)
     except Exception as pymatgen_error:
         if _cifio.is_cif(path):
             raise ValueError(

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/commands/_vaspset.py

@@ -17,12 +17,12 @@ from __future__ import annotations
 
 import argparse
 import ast
-import warnings
 from pathlib import Path
 
 try:
-    from . import _lattice, _precision, _supercell
+    from . import _cifio, _lattice, _precision, _supercell
 except ImportError:
+    import _cifio
     import _lattice
     import _precision
     import _supercell
@@ -216,8 +216,6 @@ def _run_trajectory(args, set_cls, settings):
 def run_vasp_set(args, set_cls, default_settings):
     """Write *set_cls* input files for one structure (-i), a folder (-if), or a
     trajectory (-it). Defaults can be overridden via ``-custom-setting FILE``."""
-    warnings.filterwarnings("ignore", category=UserWarning, module="pymatgen")
-    from pymatgen.core import Structure
 
     settings = dict(default_settings)
     if args.custom_setting:
@@ -244,7 +242,7 @@ def run_vasp_set(args, set_cls, default_settings):
     written = 0
     for struct_file, out_dir in jobs:
         try:
-            structure = Structure.from_file(str(struct_file))
+            structure = _cifio.read_structure(struct_file)
         except Exception as e:  # noqa: BLE001 - report and continue in batch
             print(f"{struct_file}: cannot read ({e}) -> skipping")
             continue

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/commands/compute_rmsd.py

@@ -11,8 +11,9 @@ from itertools import combinations
 from pathlib import Path
 
 try:
-    from . import _fileio
+    from . import _cifio, _fileio
 except ImportError:
+    import _cifio
     import _fileio
 
 COMMAND = "rmsd"
@@ -49,11 +50,9 @@ def create_matcher():
 
 
 def load_structure(path):
-    from pymatgen.core import Structure
-
     path = Path(path)
     try:
-        return Structure.from_file(str(path))
+        return _cifio.read_structure(path)
     except Exception as pymatgen_error:
         if path.suffix.lower() == ".cif":
             print(f"  [warn] pymatgen could not read CIF {path}: {pymatgen_error}")

pymdkit-1.6.4/src/pymdkit/commands/config.py

@@ -0,0 +1,45 @@
+"""View or edit global PMK settings."""
+
+from __future__ import annotations
+
+from pymdkit._config import config_path, load_config, save_config
+
+COMMAND = "config"
+HELP = "View or edit global PMK settings."
+
+
+def add_arguments(parser):
+    parser.add_argument("setting", nargs="?", choices=("silence",),
+                        help="Setting to update; omit it to show all settings.")
+    switch = parser.add_mutually_exclusive_group()
+    switch.add_argument("-on", dest="value", action="store_const", const=True,
+                        help="Enable the selected setting.")
+    switch.add_argument("-off", dest="value", action="store_const", const=False,
+                        help="Disable the selected setting.")
+
+
+def run(args):
+    settings = load_config()
+    value = getattr(args, "value", None)
+    if args.setting is None:
+        if value is not None:
+            print("Error: -on or -off requires a setting name.")
+            return 2
+        print(f"Configuration file: {config_path()}")
+        for name in sorted(settings):
+            if settings[name] is True:
+                shown = "on"
+            elif settings[name] is False:
+                shown = "off"
+            else:
+                shown = settings[name]
+            print(f"{name}: {shown}")
+        return 0
+    if value is None:
+        print(f"Error: pmk config {args.setting} requires -on or -off.")
+        return 2
+    settings[args.setting] = value
+    path = save_config(settings)
+    print(f"{args.setting}: {'on' if value else 'off'}")
+    print(f"Updated {path}")
+    return 0

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/commands/convert.py

@@ -23,10 +23,9 @@ HELP = "Convert structures, refine CIF symmetry, or order disorder."
 
 def _read_cif(path):
     """Read CIF with pymatgen, avoiding ASE's setting-name ambiguity."""
-    from pymatgen.core import Structure
     from pymatgen.io.ase import AseAtomsAdaptor
 
-    structure = Structure.from_file(str(path))
+    structure = _cifio.read_structure(path)
     if not structure.is_ordered:
         raise ValueError(
             "partially occupied CIF cannot be converted to an explicit atom "
@@ -149,9 +148,7 @@ def _write(
             ) from pmg_error
 
 def _read_structure(path):
-    from pymatgen.core import Structure
-
-    return Structure.from_file(str(path))
+    return _cifio.read_structure(path)
 
 
 def _write_structure(

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/commands/ewald.py

@@ -14,14 +14,17 @@ from __future__ import annotations
 import argparse
 from pathlib import Path
 
+try:
+    from . import _cifio
+except ImportError:
+    import _cifio
+
 COMMAND = "ewald"
 HELP = "Compute CIF electrostatic energy using pymatgen EwaldSummation."
 
 
 def read_charged_structure(path):
-    from pymatgen.core import Structure
-
-    structure = Structure.from_file(str(path))
+    structure = _cifio.read_structure(path)
     missing = []
     for site in structure:
         for specie in site.species:

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/commands/realloc_occ.py

@@ -580,9 +580,7 @@ def _write_candidate(
     temporary = output.with_name(f".{output.stem}.base.cif")
     try:
         render_candidate(parsed, occupancies, target, target_counts, z, temporary)
-        from pymatgen.core import Structure
-
-        structure = Structure.from_file(temporary)
+        structure = _cifio.read_structure(temporary)
         structure.make_supercell(list(matrix))
         _cifio.write_cif(structure, output, data_name=output.stem, refine=False)
     finally:
@@ -730,7 +728,7 @@ def run(args):
         f"input structure(s) to {output_root}."
     )
     _emit(report, summary)
-    report_path = output_root / "realloc-occ.txt"
+    report_path = Path.cwd() / "realloc-occ.txt"
     report_path.write_text("\n".join(report) + "\n", encoding="utf-8")
     print(f"Wrote {report_path}")
     return 0 if inputs_done == len(sources) else 1

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit/commands/substitute.py

@@ -207,11 +207,9 @@ def read_cif_labels(path):
 
 def read_structure(path):
     """Read any pymatgen-readable structure, falling back to ASE."""
-    from pymatgen.core import Structure
-
     path = Path(path)
     try:
-        return Structure.from_file(str(path))
+        return _cifio.read_structure(path)
     except Exception as pymatgen_error:
         if _cifio.is_cif(path):
             raise ValueError(

pymdkit-1.6.4/src/pymdkit/pymdkit_main.py

@@ -0,0 +1,253 @@
+"""pmk dispatcher."""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import io
+import importlib
+import os
+import pkgutil
+import shlex
+import sys
+import traceback
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Tuple
+
+from . import __version__, commands
+from ._config import load_config
+
+DESCRIPTION = "A python data processing toolkit for molecular dynamics and high-throughput calculations"
+
+
+def _read_meta(path: Path, modname: str) -> Tuple[str, str]:
+    command, help_text = modname, ""
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8-sig"))
+    except (OSError, SyntaxError):
+        return command, help_text
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if (isinstance(target, ast.Name)
+                        and isinstance(node.value, ast.Constant)
+                        and isinstance(node.value.value, str)):
+                    if target.id == "COMMAND":
+                        command = node.value.value
+                    elif target.id == "HELP":
+                        help_text = node.value.value
+    if not help_text:
+        doc = (ast.get_docstring(tree) or "").strip()
+        help_text = doc.splitlines()[0] if doc else ""
+    return command, help_text
+
+
+def _discover() -> Dict[str, Tuple[str, str]]:
+    pkg_dir = Path(commands.__path__[0])
+    found: Dict[str, Tuple[str, str]] = {}
+    for info in pkgutil.iter_modules([str(pkg_dir)]):
+        if info.name.startswith("_"):
+            continue
+        command, help_text = _read_meta(pkg_dir / f"{info.name}.py", info.name)
+        found[command] = (info.name, help_text)
+    return found
+
+
+def _add_help(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-h", "-help", action="help",
+                        help="show this help message and exit")
+
+
+def print_main_help(cmds) -> None:
+    print("pmk")
+    print()
+    print(DESCRIPTION)
+    print()
+    print(f"Version {__version__}")
+    print()
+    print("Usage: pmk <command> -[options]")
+    print()
+    print("Available commands:")
+    print()
+    for name in sorted(cmds):
+        print(f"    {name:<20} {cmds[name][1]}")
+    print()
+    print("Command details: pmk <command> -h")
+    print()
+    print("Options:")
+    print("  -h, -help             show this help message and exit")
+    print("  -v, -version          show program's version number and exit")
+
+
+def _build_top_parser(cmds: Dict[str, Tuple[str, str]]) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(add_help=False)
+    _add_help(parser)
+    parser.add_argument("-v", "-version", action="version", version=f"pmk {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    for name in sorted(cmds):
+        sub.add_parser(name, help=cmds[name][1], add_help=False)
+    return parser
+
+
+class _OutputRecorder(io.TextIOBase):
+    """Record output while preserving normal live terminal behavior."""
+
+    def __init__(self, terminal, *, echo: bool):
+        self.terminal = terminal
+        self.echo = echo
+        self.buffer = io.StringIO()
+
+    @property
+    def encoding(self):
+        return getattr(self.terminal, "encoding", "utf-8")
+
+    def isatty(self):
+        return bool(getattr(self.terminal, "isatty", lambda: False)())
+
+    def write(self, text):
+        self.buffer.write(text)
+        if self.echo:
+            self.terminal.write(text)
+            self.terminal.flush()
+        return len(text)
+
+    def flush(self):
+        if self.echo:
+            self.terminal.flush()
+
+    def getvalue(self):
+        return self.buffer.getvalue()
+
+
+def _command_text(argv) -> str:
+    return shlex.join(["pmk", *argv])
+
+
+def _write_command_log(command: str, argv, output: str, status: int,
+                       previous: str, native_report: str) -> Path:
+    path = Path.cwd() / f"{command}.txt"
+    separator = "=" * 80
+    lines = [
+        separator,
+        f"Run: {datetime.now().astimezone().isoformat(timespec='seconds')}",
+        f"Command: {_command_text(argv)}",
+        f"Status: {'success' if status == 0 else 'failed'} (exit code {status})",
+        "-" * 80,
+    ]
+    details = output.rstrip()
+    if details:
+        lines.extend(("Output:", details))
+    if native_report.strip():
+        lines.extend(("Report:", native_report.rstrip()))
+    if not details and not native_report.strip():
+        lines.append("No screen output.")
+    block = "\n".join(lines) + "\n"
+    combined = previous.rstrip()
+    if combined:
+        combined += "\n\n"
+    combined += block
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    temporary.write_text(combined, encoding="utf-8")
+    temporary.replace(path)
+    return path
+
+
+def _native_report(path: Path, previous: str) -> str:
+    if not path.exists():
+        return ""
+    current = path.read_text(encoding="utf-8", errors="replace")
+    if current == previous:
+        return ""
+    if previous and current.startswith(previous):
+        return current[len(previous):].lstrip("\r\n")
+    return current
+
+
+def _run_command(command: str, argv, module, parser, *, silence: bool) -> int:
+    log_path = Path.cwd() / f"{command}.txt"
+    previous = log_path.read_text(encoding="utf-8", errors="replace") if log_path.exists() else ""
+    terminal_out, terminal_err = sys.stdout, sys.stderr
+    recorder = _OutputRecorder(terminal_out, echo=not silence)
+    status = 0
+    pending_exception = None
+    exception_text = ""
+    try:
+        sys.stdout = recorder
+        sys.stderr = recorder
+        try:
+            args = parser.parse_args(argv[1:])
+            result = module.run(args)
+            status = 0 if result is None else int(result)
+        except SystemExit as exc:
+            status = exc.code if isinstance(exc.code, int) else 1
+            if exc.code and not isinstance(exc.code, int):
+                print(exc.code)
+        except Exception:
+            status = 1
+            pending_exception = sys.exc_info()
+            exception_text = traceback.format_exc()
+            recorder.buffer.write(exception_text)
+    finally:
+        sys.stdout = terminal_out
+        sys.stderr = terminal_err
+
+    output = recorder.getvalue()
+    native_report = _native_report(log_path, previous)
+    try:
+        _write_command_log(command, argv, output, status, previous, native_report)
+    except Exception as exc:
+        print(f"Error: could not write {log_path}: {exc}", file=terminal_err)
+        if status == 0:
+            status = 1
+    if silence and status != 0 and pending_exception is None:
+        message = output or f"Error: {_command_text(argv)} failed with exit code {status}.\n"
+        terminal_err.write(message)
+        terminal_err.flush()
+    if pending_exception is not None:
+        _, error, tb = pending_exception
+        raise error.with_traceback(tb)
+    return status
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cmds = _discover()
+    top = _build_top_parser(cmds)
+
+    if not argv:
+        print_main_help(cmds)
+        return 1
+    if argv[0] in ("-h", "-help"):
+        print_main_help(cmds)
+        return 0
+    if argv[0] in ("-v", "-version"):
+        top.parse_args(argv)
+        return 0
+
+    command = argv[0]
+    if command not in cmds:
+        print_main_help(cmds)
+        raise SystemExit(f"\nError: invalid command {command!r}")
+
+    modname = cmds[command][0]
+    module = importlib.import_module(f"{commands.__name__}.{modname}")
+    cmd_parser = argparse.ArgumentParser(
+        prog=f"pmk {command}",
+        description=getattr(module, "HELP", None) or (module.__doc__ or "").strip(),
+        add_help=False,
+    )
+    _add_help(cmd_parser)
+    if hasattr(module, "add_arguments"):
+        module.add_arguments(cmd_parser)
+    try:
+        settings = load_config()
+    except (OSError, ValueError) as exc:
+        print(f"Error: could not load PMK configuration: {exc}", file=sys.stderr)
+        return 2
+    return _run_command(command, argv, module, cmd_parser,
+                        silence=settings["silence"])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.6.2
+Version: 1.6.4
 Summary: A unified command-line toolkit for atomistic / MD structure workflows.
 Author-email: Yueda Wang <ydwang0608@ustc.edu.cn>
 License-Expression: GPL-3.0-or-later
@@ -63,6 +63,27 @@ pmk -help                   # lists every command
 pmk <command> -help         # shows that command's flags
 ```
 
+## Global configuration and logs
+
+On first use, PMK creates `.pmkrc.yaml` in the active Python environment root.
+For example, an executable at `~/anaconda3/envs/pymdkit/bin/pmk` uses
+`~/anaconda3/envs/pymdkit/.pmkrc.yaml`. View the active file and settings with:
+
+```bash
+pmk config
+pmk config silence -on
+pmk config silence -off
+```
+
+With silence enabled, successful commands do not print to the terminal. Errors
+that prevent an operation are still shown. Command details are never discarded:
+every `pmk <command> ...` invocation appends its exact command, timestamp, exit
+status, and screen output to `<command>.txt` in the directory where PMK was
+invoked. Repeated runs remain in chronological order in the same file. This log
+always stays in the invocation directory even when `-of` selects an output
+folder. Existing command reports that use the same filename, such as `rmsd.txt`
+and `ehull.txt`, are preserved as the report section of that run.
+
 ## Commands
 
 Commands that transform structures accept either a single file (`-i`/`-o`) or a
@@ -71,6 +92,7 @@ directory for job sub-folders automatically.
 
 | Command | What it does |
 |---|---|
+| `config` | View or edit global PMK settings in `.pmkrc.yaml` |
 | `add-config-type` | Add Config_type to one XYZ structure or every trajectory frame |
 | `gpumd-group` | Tag atoms with a GPUMD group index by element order |
 | `gpumd-relax` | Write GPUMD energy-minimization jobs for a file, folder, or trajectory |
@@ -265,7 +287,7 @@ first, until every multiplicity times occupancy times supercell determinant is
 an integer. Equal-volume choices favor the most isotropic resulting cell.
 All selections, site atom counts, oxidation states, charges, failures, the
 allowed occupancy grid, and the final summary are recorded in
-`OUTPUT/realloc-occ.txt` for both single-file and folder modes.
+`realloc-occ.txt` in the invocation directory for both single-file and folder modes.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -336,8 +358,14 @@ CIF input with pymatgen rather than ASE. ASE interprets
 `_space_group_crystal_system` as a setting hint only for rhombohedral groups
 and emits a potentially misleading warning for other crystal systems. Using
 pymatgen avoids that ambiguity while PMK continues to use ASE for non-CIF
-formats. A partially occupied CIF must first be ordered with `convert -d2o`
-before it can be represented as an explicit atom list.
+formats. Pymatgen intentionally snaps fractional coordinates within its
+default `1e-4` tolerance to ideal values before applying symmetry. PMK keeps
+that corrective behavior but hides only its corresponding finite-precision
+notice; composition, occupancy, malformed-CIF, and all other warnings remain
+visible. See the
+[pymatgen CifParser documentation](https://pymatgen.org/pymatgen.io.html#pymatgen.io.cif.CifParser).
+A partially occupied CIF must first be ordered with `convert -d2o` before it
+can be represented as an explicit atom list.
 
 CIF `_atom_type_symbol` and `_atom_site_label` values use per-element
 inequivalent-site identifiers such as `Li1`, `Y1`, `Cl1`, and `Cl2`.

{pymdkit-1.6.2 → pymdkit-1.6.4}/src/pymdkit.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 src/pymdkit/__init__.py
+src/pymdkit/_config.py
 src/pymdkit/pymdkit_main.py
 src/pymdkit.egg-info/PKG-INFO
 src/pymdkit.egg-info/SOURCES.txt
@@ -27,6 +28,7 @@ src/pymdkit/commands/add_config_type.py
 src/pymdkit/commands/chemsys_entry.py
 src/pymdkit/commands/compute_ehull.py
 src/pymdkit/commands/compute_rmsd.py
+src/pymdkit/commands/config.py
 src/pymdkit/commands/convert.py
 src/pymdkit/commands/ewald.py
 src/pymdkit/commands/gather_fs.py
@@ -49,6 +51,7 @@ src/pymdkit/commands/vasp2xyz.py
 src/pymdkit/commands/vasp_fe.py
 src/pymdkit/commands/vasp_relax.py
 src/pymdkit/commands/vasp_static.py
+tests/test_config_logging.py
 tests/test_convert.py
 tests/test_lattice_symmetry.py
 tests/test_realloc_occ.py

pymdkit-1.6.4/tests/test_config_logging.py

@@ -0,0 +1,97 @@
+"""Tests for PMK global configuration and command logging."""
+
+from __future__ import annotations
+
+import io
+import os
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+from unittest.mock import patch
+
+from pymdkit import _config
+from pymdkit import pymdkit_main
+
+
+class WorkingDirectory:
+    def __init__(self, path):
+        self.path = Path(path)
+        self.previous = None
+
+    def __enter__(self):
+        self.previous = Path.cwd()
+        os.chdir(self.path)
+        return self.path
+
+    def __exit__(self, *exc_info):
+        os.chdir(self.previous)
+
+
+class ConfigTests(unittest.TestCase):
+    def test_default_path_uses_active_environment_root(self):
+        with patch.object(_config.sys, "prefix", r"C:\envs\pymdkit"), \
+                patch.dict(os.environ, {}, clear=True):
+            self.assertEqual(
+                _config.config_path(),
+                Path(r"C:\envs\pymdkit").resolve() / ".pmkrc.yaml",
+            )
+
+    def test_config_command_silence_and_append_only_log(self):
+        with tempfile.TemporaryDirectory() as tmp, WorkingDirectory(tmp):
+            config_file = Path(tmp) / "environment" / ".pmkrc.yaml"
+            environment = {"PMK_CONFIG_FILE": str(config_file)}
+            with patch.dict(os.environ, environment, clear=False):
+                stdout, stderr = io.StringIO(), io.StringIO()
+                with redirect_stdout(stdout), redirect_stderr(stderr):
+                    self.assertEqual(
+                        pymdkit_main.main(["config", "silence", "-on"]), 0
+                    )
+                self.assertIn("silence: on", stdout.getvalue())
+                self.assertIn("silence: true", config_file.read_text(encoding="utf-8"))
+
+                stdout, stderr = io.StringIO(), io.StringIO()
+                with redirect_stdout(stdout), redirect_stderr(stderr):
+                    self.assertEqual(pymdkit_main.main(["config"]), 0)
+                self.assertEqual(stdout.getvalue(), "")
+                self.assertEqual(stderr.getvalue(), "")
+
+                stdout, stderr = io.StringIO(), io.StringIO()
+                with redirect_stdout(stdout), redirect_stderr(stderr):
+                    self.assertEqual(pymdkit_main.main(["config", "silence"]), 2)
+                self.assertEqual(stdout.getvalue(), "")
+                self.assertIn("requires -on or -off", stderr.getvalue())
+
+                stdout, stderr = io.StringIO(), io.StringIO()
+                with redirect_stdout(stdout), redirect_stderr(stderr):
+                    self.assertEqual(
+                        pymdkit_main.main(["config", "silence", "-off"]), 0
+                    )
+                self.assertEqual(stdout.getvalue(), "")
+                self.assertIn("silence: false", config_file.read_text(encoding="utf-8"))
+
+            report = (Path(tmp) / "config.txt").read_text(encoding="utf-8")
+            self.assertIn("Command: pmk config silence -on", report)
+            self.assertIn("Command: pmk config silence -off", report)
+            self.assertEqual(report.count("Command:"), 4)
+            self.assertIn("Status: failed (exit code 2)", report)
+
+    def test_native_report_is_preserved_in_command_log(self):
+        with tempfile.TemporaryDirectory() as tmp, WorkingDirectory(tmp):
+            path = Path(tmp) / "rmsd.txt"
+            previous = "older run\n"
+            path.write_text(previous, encoding="utf-8")
+            path.write_text("new RMSD details\n", encoding="utf-8")
+            native = pymdkit_main._native_report(path, previous)
+            pymdkit_main._write_command_log(
+                "rmsd", ["rmsd", "-if", "structures"], "Wrote rmsd.txt\n",
+                0, previous, native,
+            )
+            report = path.read_text(encoding="utf-8")
+            self.assertIn("older run", report)
+            self.assertIn("Command: pmk rmsd -if structures", report)
+            self.assertIn("Report:\nnew RMSD details", report)
+
+
+if __name__ == "__main__":
+    unittest.main()

{pymdkit-1.6.2 → pymdkit-1.6.4}/tests/test_lattice_symmetry.py

@@ -2,6 +2,7 @@ import math
 import sys
 import types
 import unittest
+import warnings
 from pathlib import Path
 from unittest.mock import patch
 
@@ -38,6 +39,39 @@ class FakeLattice:
         return math.degrees(math.acos(float(np.clip(cosine, -1.0, 1.0))))
 
 
+class CifReaderTests(unittest.TestCase):
+    def test_only_benign_fractional_rounding_warning_is_hidden(self):
+        structure = object()
+
+        class Structure:
+            @classmethod
+            def from_file(cls, path):
+                warnings.warn(
+                    "Issues encountered while parsing CIF: 4 fractional "
+                    "coordinates rounded to ideal values to avoid issues "
+                    "with finite precision.",
+                    UserWarning,
+                )
+                warnings.warn("CIF composition mismatch", UserWarning)
+                return structure
+
+        pymatgen = types.ModuleType("pymatgen")
+        core = types.ModuleType("pymatgen.core")
+        core.Structure = Structure
+        pymatgen.core = core
+        with patch.dict(sys.modules, {
+            "pymatgen": pymatgen,
+            "pymatgen.core": core,
+        }), warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            result = _cifio.read_structure("input.cif")
+
+        self.assertIs(result, structure)
+        self.assertEqual([str(item.message) for item in caught], [
+            "CIF composition mismatch"
+        ])
+
+
 class LatticeGeometryTests(unittest.TestCase):
     def test_gpumd_uses_pymatgen_lattice_row_vectors(self):
         pymatgen = types.ModuleType("pymatgen")

{pymdkit-1.6.2 → pymdkit-1.6.4}/tests/test_realloc_occ.py

@@ -169,13 +169,13 @@ class ReallocOccTests(unittest.TestCase):
                 occ=[0.25, 0.5, 0.75, 1.0],
                 max_supercell="2x2x2",
             )
-            with patch.object(
+            with patch.object(realloc_occ.Path, "cwd", return_value=root), patch.object(
                 realloc_occ._oxidation,
                 "infer_oxidation_states",
                 return_value=OXIDATION,
             ):
                 self.assertEqual(realloc_occ.run(args), 0)
-            report = (output / "realloc-occ.txt").read_text(encoding="utf-8")
+            report = (root / "realloc-occ.txt").read_text(encoding="utf-8")
             self.assertIn(
                 "Allowed occupancies: 0.250, 0.500, 0.750, 1.000",
                 report,

pymdkit-1.6.2/src/pymdkit/pymdkit_main.py

@@ -1,123 +0,0 @@
-"""pmk dispatcher."""
-
-from __future__ import annotations
-
-import argparse
-import ast
-import importlib
-import pkgutil
-import sys
-from pathlib import Path
-from typing import Dict, Tuple
-
-from . import __version__, commands
-
-DESCRIPTION = "A python data processing toolkit for molecular dynamics and high-throughput calculations"
-
-
-def _read_meta(path: Path, modname: str) -> Tuple[str, str]:
-    command, help_text = modname, ""
-    try:
-        tree = ast.parse(path.read_text(encoding="utf-8-sig"))
-    except (OSError, SyntaxError):
-        return command, help_text
-    for node in tree.body:
-        if isinstance(node, ast.Assign):
-            for target in node.targets:
-                if (isinstance(target, ast.Name)
-                        and isinstance(node.value, ast.Constant)
-                        and isinstance(node.value.value, str)):
-                    if target.id == "COMMAND":
-                        command = node.value.value
-                    elif target.id == "HELP":
-                        help_text = node.value.value
-    if not help_text:
-        doc = (ast.get_docstring(tree) or "").strip()
-        help_text = doc.splitlines()[0] if doc else ""
-    return command, help_text
-
-
-def _discover() -> Dict[str, Tuple[str, str]]:
-    pkg_dir = Path(commands.__path__[0])
-    found: Dict[str, Tuple[str, str]] = {}
-    for info in pkgutil.iter_modules([str(pkg_dir)]):
-        if info.name.startswith("_"):
-            continue
-        command, help_text = _read_meta(pkg_dir / f"{info.name}.py", info.name)
-        found[command] = (info.name, help_text)
-    return found
-
-
-def _add_help(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("-h", "-help", action="help",
-                        help="show this help message and exit")
-
-
-def print_main_help(cmds) -> None:
-    print("pmk")
-    print()
-    print(DESCRIPTION)
-    print()
-    print(f"Version {__version__}")
-    print()
-    print("Usage: pmk <command> -[options]")
-    print()
-    print("Available commands:")
-    print()
-    for name in sorted(cmds):
-        print(f"    {name:<20} {cmds[name][1]}")
-    print()
-    print("Command details: pmk <command> -h")
-    print()
-    print("Options:")
-    print("  -h, -help             show this help message and exit")
-    print("  -v, -version          show program's version number and exit")
-
-
-def _build_top_parser(cmds: Dict[str, Tuple[str, str]]) -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(add_help=False)
-    _add_help(parser)
-    parser.add_argument("-v", "-version", action="version", version=f"pmk {__version__}")
-    sub = parser.add_subparsers(dest="command", metavar="<command>")
-    for name in sorted(cmds):
-        sub.add_parser(name, help=cmds[name][1], add_help=False)
-    return parser
-
-
-def main(argv=None) -> int:
-    argv = list(sys.argv[1:] if argv is None else argv)
-    cmds = _discover()
-    top = _build_top_parser(cmds)
-
-    if not argv:
-        print_main_help(cmds)
-        return 1
-    if argv[0] in ("-h", "-help"):
-        print_main_help(cmds)
-        return 0
-    if argv[0] in ("-v", "-version"):
-        top.parse_args(argv)
-        return 0
-
-    command = argv[0]
-    if command not in cmds:
-        print_main_help(cmds)
-        raise SystemExit(f"\nError: invalid command {command!r}")
-
-    modname = cmds[command][0]
-    module = importlib.import_module(f"{commands.__name__}.{modname}")
-    cmd_parser = argparse.ArgumentParser(
-        prog=f"pmk {command}",
-        description=getattr(module, "HELP", None) or (module.__doc__ or "").strip(),
-        add_help=False,
-    )
-    _add_help(cmd_parser)
-    if hasattr(module, "add_arguments"):
-        module.add_arguments(cmd_parser)
-    args = cmd_parser.parse_args(argv[1:])
-    result = module.run(args)
-    return 0 if result is None else int(result)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())