pymdkit 1.5.1__tar.gz → 1.5.2__tar.gz

{pymdkit-1.5.1 → pymdkit-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.5.1
+Version: 1.5.2
 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
@@ -84,7 +84,7 @@ directory for job sub-folders automatically.
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `trj-sparse` | Deterministically retain a requested fraction of XYZ trajectory frames |
 | `umap` | Reduce descriptor data to two dimensions with UMAP; optional FPS sampling |
-| `msd` | Diffusivity & conductivity from GPUMD MSD jobs (auto-scans `<structure>/<temp>/`) |
+| `gpumd-msd` | Recursively extract directional SDC and Nernst-Einstein conductivity from GPUMD jobs |
 | `nep-rmse` | Compute NEP energy/force/stress RMSE with terminal plots and optional candidate selection |
 | `perturb` | Generate perturbed structures with dpdata |
 | `vasp2xyz` | Collect SCF-converged VASP job folders (any name) into one extxyz file |
@@ -92,6 +92,7 @@ directory for job sub-folders automatically.
 | `rmsd` | Compare structures by RMSD and optionally remove higher-energy duplicates |
 | `chemsys-entry` | Download stable Materials Project structures for a chemical system |
 | `convert` | Convert structures, trajectories, or folders between ASE/pymatgen formats |
+| `realloc-occ` | Generate charge-balanced CIF occupancy allocations for a target formula |
 | `substitute` | Randomly substitute or remove selected atoms/sites from a structure |
 | `supercell` | Build a supercell with cell lengths capped at a maximum (Angstrom); optional per-temperature GPUMD setup |
 | `symmetrize` | Detect/refine symmetry for structure files, folders, or CSV rows -> CIF |
@@ -119,8 +120,8 @@ pmk gpumd-relax -if example -nep nep89_20250409.txt            # model.xyz + run
 pmk gpumd-relax -it train.xyz -nep nep.txt -in run.in         # one ./frame_N/ GPUMD job per frame
 pmk vasp-static -if cifs/ -custom-setting my_incar.txt         # static inputs, custom INCAR
 pmk vasp-static -it traj.xyz                                    # one ./frame_N/ job per trajectory frame
-pmk msd                                         # scans <structure>/<temp>/ -> per-job msd/ + msd_summary.txt
-pmk msd -diffuse_ion Li -ion_charge 1         # choose the mobile ion for conductivity
+pmk gpumd-msd                                   # recursively scans GPUMD jobs -> per-job msd/ + sigma-sdc-summary.txt
+pmk gpumd-msd -diffuse_ion Li -ion_charge 1     # choose the mobile ion and signed valence
 pmk chemsys-entry -s Li La Ta Cl                 # MP stable entries -> Li-La-Ta-Cl-stable-entries/
 pmk ehull -mp-api-key $MP_API_KEY              # scans ./ for VASP jobs -> ehull.txt
 pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
@@ -132,6 +133,8 @@ pmk vasp2xyz                                    # scans ./ for VASP output folde
 pmk vasp2xyz -position-only                    # write positions only, without energy/forces/stress
 pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
 nohup pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30 > submit-vasp.log 2>&1 &
+pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6
+pmk realloc-occ -if cifs -of chg-balance -formula Li3YCl6
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we Na -wn 3 -on 100
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we none -on 100
 pmk substitute -i Li96Ta6La11Cl72.cif -se Li1 Li2 -sn 20 67 -we none -on 100
@@ -200,6 +203,36 @@ dump_xyz    -1 0 1 relaxed.xyz force
 run 1
 ```
 
+`gpumd-msd` recursively discovers job folders at any depth below `-entry-path`
+(the current directory by default). A job must contain `msd.out`, `model.xyz`,
+`run.in`, and `thermo.out`; the common accidental name `thermos.out` is also
+accepted. Following the [official GPUMD `msd.out` format](https://gpumd.org/gpumd/output_files/msd_out.html), each group block is read as three MSD columns
+followed by three directional SDC columns. PMK takes the arithmetic mean over
+the last 50% of the SDC correlation-time range, converts A^2/ps to cm^2/s by
+multiplying by `1e-4`, and reports `D_total = (D_x + D_y + D_z) / 3`.
+Each job receives `msd/group_INDEX_ELEMENT_TEMP_msd.txt`, a matching `_sdc.txt`,
+and a `_results.txt`. The root receives `sigma-sdc-summary.txt` with directional
+and total diffusion coefficients and conductivities.
+
+Ionic conductivity uses the Nernst-Einstein relation with the mean temperature
+of the final SDC-producing MD run and the official 18-column
+[`thermo.out` format](https://gpumd.org/gpumd/output_files/thermo_out.html):
+for NPT ensembles (`npt_scr`, `npt_mttk`, and other `npt_*` forms), PMK uses
+the mean triclinic-box volume over that run; for NVT ensembles (`nvt_bdp`,
+`nvt_ber`, and other `nvt_*` forms), it uses the final fixed-cell volume.
+`V(A^3) * 1e-24 -> V(cm^3)`, exact SI values for elementary charge and the
+Boltzmann constant, and a final `* 1000` conversion from S/cm to mS/cm.
+
+`realloc-occ -i INPUT.cif -of OUTPUT -formula FORMULA` computes atom counts as
+Wyckoff multiplicity times occupancy and uses `_cell_formula_units_Z` to map the
+target reduced formula into the existing cell. It enumerates finite site-wise
+occupancy allocations, retains only charge-balanced candidates using the CIF
+oxidation-number loop, and preserves the original symmetry, coordinates,
+Wyckoff labels, and CIF layout. Every input receives `OUTPUT/INPUT_STEM/`; for
+the supplied Li4YCl6 example, the two outputs are `...-d1.cif` with `Li1=0.50`
+and `...-d2.cif` with `Li2=0.50`. Folder mode uses `-if` with the same `-of` and
+`-formula` options.
+
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
 requires full convergence before copying the selected `-fs-name` as `.vasp`. The gathered VASP file's first line is replaced with `energy=<final_energy> eV` for later screening.
@@ -346,6 +379,7 @@ pymdkit/
         |-- _geometry.py        # shared minimum-image geometry helper
         |-- _vaspset.py         # shared VASP input-set helper (not a command)
         |-- gpumd_group.py
+        |-- gpumd_msd.py
         |-- gpumd_relax.py
         |-- gpumd_thermo.py
         |-- gpumd_trjcat.py
@@ -360,6 +394,7 @@ pymdkit/
         |-- chemsys_entry.py
         |-- submit_vasp.py
         |-- convert.py
+        |-- realloc_occ.py
         |-- substitute.py
         |-- supercell.py
         |-- vasp2xyz.py

{pymdkit-1.5.1 → pymdkit-1.5.2}/README.md

@@ -57,14 +57,15 @@ directory for job sub-folders automatically.
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `trj-sparse` | Deterministically retain a requested fraction of XYZ trajectory frames |
 | `umap` | Reduce descriptor data to two dimensions with UMAP; optional FPS sampling |
-| `msd` | Diffusivity & conductivity from GPUMD MSD jobs (auto-scans `<structure>/<temp>/`) |
+| `gpumd-msd` | Recursively extract directional SDC and Nernst-Einstein conductivity from GPUMD jobs |
 | `nep-rmse` | Compute NEP energy/force/stress RMSE with terminal plots and optional candidate selection |
 | `perturb` | Generate perturbed structures with dpdata |
 | `vasp2xyz` | Collect SCF-converged VASP job folders (any name) into one extxyz file |
 | `submit-vasp` | Submit/resubmit VASP job folders while limiting active queue jobs |
 | `rmsd` | Compare structures by RMSD and optionally remove higher-energy duplicates |
 | `chemsys-entry` | Download stable Materials Project structures for a chemical system |
-| `convert` | Convert structures, trajectories, or folders between ASE/pymatgen formats |
+| `convert` | Convert structures, trajectories, or folders between ASE/pymatgen formats |
+| `realloc-occ` | Generate charge-balanced CIF occupancy allocations for a target formula |
 | `substitute` | Randomly substitute or remove selected atoms/sites from a structure |
 | `supercell` | Build a supercell with cell lengths capped at a maximum (Angstrom); optional per-temperature GPUMD setup |
 | `symmetrize` | Detect/refine symmetry for structure files, folders, or CSV rows -> CIF |
@@ -92,8 +93,8 @@ pmk gpumd-relax -if example -nep nep89_20250409.txt            # model.xyz + run
 pmk gpumd-relax -it train.xyz -nep nep.txt -in run.in         # one ./frame_N/ GPUMD job per frame
 pmk vasp-static -if cifs/ -custom-setting my_incar.txt         # static inputs, custom INCAR
 pmk vasp-static -it traj.xyz                                    # one ./frame_N/ job per trajectory frame
-pmk msd                                         # scans <structure>/<temp>/ -> per-job msd/ + msd_summary.txt
-pmk msd -diffuse_ion Li -ion_charge 1         # choose the mobile ion for conductivity
+pmk gpumd-msd                                   # recursively scans GPUMD jobs -> per-job msd/ + sigma-sdc-summary.txt
+pmk gpumd-msd -diffuse_ion Li -ion_charge 1     # choose the mobile ion and signed valence
 pmk chemsys-entry -s Li La Ta Cl                 # MP stable entries -> Li-La-Ta-Cl-stable-entries/
 pmk ehull -mp-api-key $MP_API_KEY              # scans ./ for VASP jobs -> ehull.txt
 pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
@@ -105,6 +106,8 @@ pmk vasp2xyz                                    # scans ./ for VASP output folde
 pmk vasp2xyz -position-only                    # write positions only, without energy/forces/stress
 pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
 nohup pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30 > submit-vasp.log 2>&1 &
+pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6
+pmk realloc-occ -if cifs -of chg-balance -formula Li3YCl6
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we Na -wn 3 -on 100
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we none -on 100
 pmk substitute -i Li96Ta6La11Cl72.cif -se Li1 Li2 -sn 20 67 -we none -on 100
@@ -173,6 +176,36 @@ dump_xyz    -1 0 1 relaxed.xyz force
 run 1
 ```
 
+`gpumd-msd` recursively discovers job folders at any depth below `-entry-path`
+(the current directory by default). A job must contain `msd.out`, `model.xyz`,
+`run.in`, and `thermo.out`; the common accidental name `thermos.out` is also
+accepted. Following the [official GPUMD `msd.out` format](https://gpumd.org/gpumd/output_files/msd_out.html), each group block is read as three MSD columns
+followed by three directional SDC columns. PMK takes the arithmetic mean over
+the last 50% of the SDC correlation-time range, converts A^2/ps to cm^2/s by
+multiplying by `1e-4`, and reports `D_total = (D_x + D_y + D_z) / 3`.
+Each job receives `msd/group_INDEX_ELEMENT_TEMP_msd.txt`, a matching `_sdc.txt`,
+and a `_results.txt`. The root receives `sigma-sdc-summary.txt` with directional
+and total diffusion coefficients and conductivities.
+
+Ionic conductivity uses the Nernst-Einstein relation with the mean temperature
+of the final SDC-producing MD run and the official 18-column
+[`thermo.out` format](https://gpumd.org/gpumd/output_files/thermo_out.html):
+for NPT ensembles (`npt_scr`, `npt_mttk`, and other `npt_*` forms), PMK uses
+the mean triclinic-box volume over that run; for NVT ensembles (`nvt_bdp`,
+`nvt_ber`, and other `nvt_*` forms), it uses the final fixed-cell volume.
+`V(A^3) * 1e-24 -> V(cm^3)`, exact SI values for elementary charge and the
+Boltzmann constant, and a final `* 1000` conversion from S/cm to mS/cm.
+
+`realloc-occ -i INPUT.cif -of OUTPUT -formula FORMULA` computes atom counts as
+Wyckoff multiplicity times occupancy and uses `_cell_formula_units_Z` to map the
+target reduced formula into the existing cell. It enumerates finite site-wise
+occupancy allocations, retains only charge-balanced candidates using the CIF
+oxidation-number loop, and preserves the original symmetry, coordinates,
+Wyckoff labels, and CIF layout. Every input receives `OUTPUT/INPUT_STEM/`; for
+the supplied Li4YCl6 example, the two outputs are `...-d1.cif` with `Li1=0.50`
+and `...-d2.cif` with `Li2=0.50`. Folder mode uses `-if` with the same `-of` and
+`-formula` options.
+
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
 requires full convergence before copying the selected `-fs-name` as `.vasp`. The gathered VASP file's first line is replaced with `energy=<final_energy> eV` for later screening.
@@ -318,7 +351,8 @@ pymdkit/
         |-- _gpumd.py           # shared GPUMD run.in and thermo analysis
         |-- _geometry.py        # shared minimum-image geometry helper
         |-- _vaspset.py         # shared VASP input-set helper (not a command)
-        |-- gpumd_group.py
+        |-- gpumd_group.py
+        |-- gpumd_msd.py
         |-- gpumd_relax.py
         |-- gpumd_thermo.py
         |-- gpumd_trjcat.py
@@ -332,7 +366,8 @@ pymdkit/
         |-- _cifio.py
         |-- chemsys_entry.py
         |-- submit_vasp.py
-        |-- convert.py
+        |-- convert.py
+        |-- realloc_occ.py
         |-- substitute.py
         |-- supercell.py
         |-- vasp2xyz.py

{pymdkit-1.5.1 → pymdkit-1.5.2}/pyproject.toml

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

{pymdkit-1.5.1 → pymdkit-1.5.2}/src/pymdkit/__init__.py

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

pymdkit-1.5.2/src/pymdkit/commands/gpumd_msd.py

@@ -0,0 +1,461 @@
+"""Extract directional self-diffusion and conductivity from GPUMD MSD jobs.
+
+``pmk gpumd-msd`` recursively scans for job folders containing ``msd.out``,
+``thermo.out`` (or ``thermos.out``), ``model.xyz``, and ``run.in``. GPUMD
+already writes directional self-diffusion coefficients (SDC) in columns 5-7
+of each six-column group block. Reported diffusion coefficients are arithmetic
+means over the last 50% of the correlation-time range.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+try:
+    from ._gpumd import cell_quantities
+except ImportError:  # pragma: no cover - direct script execution
+    from _gpumd import cell_quantities
+
+COMMAND = "gpumd-msd"
+HELP = "Recursively extract GPUMD self-diffusion and ionic conductivity."
+CORE_JOB_FILES = ("msd.out", "model.xyz", "run.in")
+THERMO_NAMES = ("thermo.out", "thermos.out")
+SUMMARY_FILE = "sigma-sdc-summary.txt"
+ELEMENTARY_CHARGE_C = 1.602176634e-19
+BOLTZMANN_J_PER_K = 1.380649e-23
+A2_PER_PS_TO_CM2_PER_S = 1.0e-4
+AVERAGE_FRACTION = 0.5
+
+
+@dataclass(frozen=True)
+class MsdSpec:
+    sample_interval: int
+    correlation_steps: int
+    time_step_fs: float
+    group_method: int = 0
+    group_id: Optional[int] = None
+    all_groups: bool = False
+
+    @property
+    def maximum_time_ps(self):
+        return (self.sample_interval * self.correlation_steps
+                * self.time_step_fs / 1000.0)
+
+
+def _parse_compute_msd(parts, time_step_fs):
+    if len(parts) < 3:
+        raise ValueError("compute_msd requires sample_interval and Nc")
+    sample_interval, correlation_steps = int(parts[1]), int(parts[2])
+    if sample_interval <= 0 or correlation_steps <= 0:
+        raise ValueError("compute_msd sample_interval and Nc must be positive")
+    tail = parts[3:]
+    group_method, group_id, all_groups = 0, None, False
+    if "all_groups" in tail:
+        index = tail.index("all_groups")
+        if index + 1 >= len(tail):
+            raise ValueError("compute_msd all_groups requires a group method")
+        group_method, all_groups = int(tail[index + 1]), True
+    elif "group" in tail:
+        index = tail.index("group")
+        if index + 2 >= len(tail):
+            raise ValueError("compute_msd group requires a method and group index")
+        group_method, group_id = int(tail[index + 1]), int(tail[index + 2])
+    return MsdSpec(sample_interval, correlation_steps, float(time_step_fs),
+                   group_method, group_id, all_groups)
+
+
+def parse_run_file(path):
+    """Return the final SDC-producing specification, runs, and target run."""
+    time_step_fs = 1.0
+    active_dump_thermo = None
+    active_ensemble = None
+    active_msd = None
+    runs = []
+    for raw in Path(path).read_text(encoding="utf-8").splitlines():
+        parts = raw.split("#", 1)[0].split()
+        if not parts:
+            continue
+        key = parts[0].lower()
+        if key == "time_step" and len(parts) >= 2:
+            time_step_fs = float(parts[1])
+        elif key == "dump_thermo" and len(parts) >= 2:
+            active_dump_thermo = int(parts[1])
+        elif key == "ensemble" and len(parts) >= 2:
+            active_ensemble = parts[1].lower()
+        elif key == "compute_msd":
+            active_msd = _parse_compute_msd(parts, time_step_fs)
+        elif key == "run" and len(parts) >= 2:
+            runs.append({
+                "index": len(runs),
+                "steps": int(parts[1]),
+                "dump_thermo": active_dump_thermo,
+                "time_step_fs": time_step_fs,
+                "ensemble": active_ensemble,
+                "compute_msd": active_msd,
+            })
+            active_dump_thermo = None
+            active_ensemble = None
+            active_msd = None
+    sdc_runs = [run for run in runs if run["compute_msd"] is not None]
+    if not sdc_runs:
+        raise ValueError("run.in contains no compute_msd directive")
+    target_run = sdc_runs[-1]
+    return target_run["compute_msd"], runs, target_run
+
+
+def _last_monotonic_segment(data):
+    """Keep the final block if appended GPUMD runs reset correlation time."""
+    if len(data) < 2:
+        return data
+    resets = np.flatnonzero(np.diff(data[:, 0]) <= 0.0)
+    return data[resets[-1] + 1:] if len(resets) else data
+
+
+def _thermo_run_slice(n_points, runs, target_run):
+    """Map the target run to its rows in a concatenated thermo.out."""
+    thermo_runs = [run for run in runs if run["dump_thermo"]]
+    if target_run["dump_thermo"] is None:
+        raise ValueError("the SDC-producing run has no dump_thermo directive")
+    counts = {
+        run["index"]: max(1, run["steps"] // run["dump_thermo"])
+        for run in thermo_runs
+    }
+    expected_total = sum(counts.values())
+    target_count = counts[target_run["index"]]
+    if expected_total == n_points:
+        start = sum(
+            counts[run["index"]]
+            for run in thermo_runs
+            if run["index"] < target_run["index"]
+        )
+        return slice(start, start + target_count)
+    if thermo_runs[-1]["index"] == target_run["index"]:
+        return slice(max(0, n_points - target_count), n_points)
+    raise ValueError(
+        "thermo.out row count does not match run.in, so the SDC-producing "
+        "run cannot be mapped safely"
+    )
+
+
+def _thermo_path(folder):
+    for name in THERMO_NAMES:
+        path = Path(folder) / name
+        if path.is_file():
+            return path
+    return None
+
+
+def load_thermo(path, runs, target_run):
+    """Return temperature and ensemble-appropriate volume for the SDC run."""
+    data = np.atleast_2d(np.loadtxt(Path(path)))
+    if data.shape[1] != 18:
+        raise ValueError("thermo.out must use the official 18-column GPUMD format")
+    selected = data[_thermo_run_slice(len(data), runs, target_run)]
+    if not len(selected):
+        raise ValueError("the SDC-producing run has no mapped thermo records")
+    volumes = cell_quantities(selected)[2]
+    ensemble = target_run["ensemble"]
+    if ensemble is None:
+        raise ValueError("the SDC-producing run has no ensemble directive")
+    if ensemble.startswith(("npt_", "nph_")):
+        volume = float(np.mean(volumes))
+        volume_source = "mean over SDC-producing run"
+    elif ensemble == "nve" or ensemble.startswith("nvt_"):
+        volume = float(volumes[-1])
+        volume_source = "final cell of SDC-producing run"
+    else:
+        raise ValueError(
+            f"unsupported ensemble '{ensemble}' for conductivity volume"
+        )
+    temperature = float(np.mean(selected[:, 0]))
+    if temperature <= 0.0 or volume <= 0.0:
+        raise ValueError("temperature and volume must be positive")
+    return temperature, volume, ensemble, volume_source
+
+
+def load_groups(path, group_method=0):
+    """Return group_id -> {element, count} from model.xyz."""
+    from ase.io import read
+
+    atoms = read(str(path), index=0)
+    symbols = np.asarray(atoms.get_chemical_symbols(), dtype=object)
+    raw_groups = atoms.arrays.get("group")
+    if raw_groups is None:
+        group_values = np.zeros(len(atoms), dtype=int)
+    else:
+        raw_groups = np.asarray(raw_groups)
+        if raw_groups.ndim == 1:
+            if group_method != 0:
+                raise ValueError(
+                    f"model.xyz has one grouping method, not method {group_method}")
+            group_values = raw_groups.astype(int)
+        else:
+            if group_method < 0 or group_method >= raw_groups.shape[1]:
+                raise ValueError(
+                    f"model.xyz has {raw_groups.shape[1]} grouping method(s), "
+                    f"not method {group_method}")
+            group_values = raw_groups[:, group_method].astype(int)
+    groups = {}
+    for group_id in sorted(set(group_values.tolist())):
+        selected = symbols[group_values == group_id]
+        elements = sorted(set(selected.tolist()))
+        groups[int(group_id)] = {
+            "element": elements[0] if len(elements) == 1 else "mixed",
+            "count": int(len(selected)),
+        }
+    return groups
+
+
+def load_msd(path, spec, groups):
+    """Return group_id -> (time, MSD_xyz, SDC_xyz) from official blocks."""
+    data = np.atleast_2d(np.loadtxt(Path(path)))
+    if data.shape[1] < 7 or (data.shape[1] - 1) % 6:
+        raise ValueError(
+            "msd.out must contain time plus one or more six-column MSD/SDC blocks")
+    data = _last_monotonic_segment(data)
+    if len(data) < 2 or np.any(np.diff(data[:, 0]) <= 0.0):
+        raise ValueError("msd.out needs at least two increasing time points")
+    block_count = (data.shape[1] - 1) // 6
+    if spec.all_groups:
+        group_ids = sorted(groups)
+        if block_count != len(group_ids):
+            raise ValueError(
+                f"msd.out has {block_count} blocks, but model.xyz grouping method "
+                f"{spec.group_method} has {len(group_ids)} groups")
+    elif spec.group_id is not None:
+        if block_count != 1 or spec.group_id not in groups:
+            raise ValueError("single-group msd.out cannot be mapped to model.xyz")
+        group_ids = [spec.group_id]
+    elif block_count == 1 and len(groups) == 1:
+        group_ids = [next(iter(groups))]
+    else:
+        raise ValueError(
+            "compute_msd without group/all_groups cannot map multiple groups")
+    result = {}
+    for block_index, group_id in enumerate(group_ids):
+        start = 1 + 6 * block_index
+        result[group_id] = (data[:, 0], data[:, start:start + 3],
+                            data[:, start + 3:start + 6])
+    return result
+
+
+def average_sdc(times, sdc_xyz, fraction=AVERAGE_FRACTION):
+    """Average directional SDC over the final correlation-time fraction."""
+    if not 0.0 < fraction <= 1.0:
+        raise ValueError("SDC averaging fraction must be in (0, 1]")
+    start_time = times[0] + (1.0 - fraction) * (times[-1] - times[0])
+    mask = times >= start_time
+    if np.count_nonzero(mask) < 2:
+        mask = np.zeros(len(times), dtype=bool)
+        mask[max(0, len(times) // 2):] = True
+    averaged = np.mean(sdc_xyz[mask], axis=0)
+    diffusion_xyz = averaged * A2_PER_PS_TO_CM2_PER_S
+    return np.append(diffusion_xyz, np.mean(diffusion_xyz)), mask, averaged
+
+
+def calculate_conductivity(diffusion, num_ions, charge, volume_a3, temperature):
+    """Nernst-Einstein conductivity in mS/cm for D in cm^2/s."""
+    number_density_cm3 = int(num_ions) / (float(volume_a3) * 1.0e-24)
+    charge_c = float(charge) * ELEMENTARY_CHARGE_C
+    factor = (number_density_cm3 * charge_c ** 2
+              / (BOLTZMANN_J_PER_K * float(temperature)))
+    return np.asarray(diffusion) * factor * 1000.0
+
+
+def _safe_name(value):
+    return re.sub(r"[^A-Za-z0-9_.+-]+", "_", str(value)).strip("_") or "unknown"
+
+
+def _temperature_label(folder_name, temperature):
+    match = re.fullmatch(r"([0-9]+(?:\.[0-9]+)?)K?", str(folder_name), re.I)
+    if match:
+        value = float(match.group(1))
+        return str(int(value)) if value.is_integer() else match.group(1)
+    return str(int(round(float(temperature))))
+
+
+def save_group_data(output_dir, group_id, element, temp_label,
+                    times, msd_xyz, sdc_xyz):
+    stem = f"group_{group_id}_{_safe_name(element)}_{temp_label}"
+    np.savetxt(Path(output_dir) / f"{stem}_msd.txt",
+               np.column_stack([times, msd_xyz, np.sum(msd_xyz, axis=1)]),
+               fmt="%.8f",
+               header="time(ps) MSD_x(A^2) MSD_y(A^2) MSD_z(A^2) MSD_total(A^2)",
+               comments="", encoding="utf-8")
+    np.savetxt(Path(output_dir) / f"{stem}_sdc.txt",
+               np.column_stack([times, sdc_xyz]), fmt="%.8f",
+               header="time(ps) SDC_x(A^2/ps) SDC_y(A^2/ps) SDC_z(A^2/ps)",
+               comments="", encoding="utf-8")
+    return stem
+
+
+def save_group_results(output_dir, stem, record, averaged_sdc):
+    labels = ("x", "y", "z", "total")
+    lines = [
+        f"Job: {record['job']}",
+        f"Group: {record['group_id']}",
+        f"Element: {record['element']}",
+        f"Mobile particles: {record['count']}",
+        f"Mean temperature (K): {record['temperature']:.8f}",
+        f"Ensemble: {record['ensemble']}",
+        f"Conductivity volume (A^3): {record['volume']:.8f}",
+        f"Volume source: {record['volume_source']}",
+        ("SDC averaging interval (ps): "
+         f"{record['average_start']:.8f} to {record['average_end']:.8f}"),
+        "Average SDC (A^2/ps):",
+        *(f"  SDC_{label} = {value:.8f}"
+          for label, value in zip(("x", "y", "z"), averaged_sdc)),
+        "Diffusion coefficient (cm^2/s):",
+        *(f"  D_{label} = {value:.8f}"
+          for label, value in zip(labels, record["diffusion"])),
+    ]
+    if record["conductivity"] is not None:
+        lines.extend([
+            "Ionic conductivity (mS/cm):",
+            *(f"  sigma_{label} = {value:.8f}"
+              for label, value in zip(labels, record["conductivity"])),
+        ])
+    (Path(output_dir) / f"{stem}_results.txt").write_text(
+        "\n".join(lines) + "\n", encoding="utf-8")
+
+
+def discover_jobs(root):
+    """Recursively find GPUMD MSD job folders at any depth."""
+    root = Path(root)
+    if not root.is_dir():
+        raise SystemExit(f"Error: entry path not found: {root}")
+    jobs = []
+    for msd_path in root.rglob("msd.out"):
+        folder = msd_path.parent
+        thermo = _thermo_path(folder)
+        if (thermo is not None
+                and all((folder / name).is_file() for name in CORE_JOB_FILES)):
+            jobs.append((folder, thermo))
+    return sorted(jobs, key=lambda item: item[0].relative_to(root).as_posix())
+
+
+def analyze_job(root, folder, thermo_path, args):
+    spec, runs, target_run = parse_run_file(folder / "run.in")
+    temperature, volume, ensemble, volume_source = load_thermo(
+        thermo_path, runs, target_run
+    )
+    groups = load_groups(folder / "model.xyz", spec.group_method)
+    blocks = load_msd(folder / "msd.out", spec, groups)
+    temp_label = _temperature_label(folder.name, temperature)
+    job_label = folder.relative_to(root).as_posix() or "."
+    output_dir = folder / "msd"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    end_time = next(iter(blocks.values()))[0][-1]
+    interval_ps = spec.sample_interval * spec.time_step_fs / 1000.0
+    if abs(end_time - spec.maximum_time_ps) > max(interval_ps, 1.0e-8):
+        print(f"  [WARN] {folder}: msd.out ends at {end_time:.8f} ps; "
+              f"run.in implies {spec.maximum_time_ps:.8f} ps")
+
+    records, job_sigma, mobile_found = [], np.zeros(4), False
+    for group_id in sorted(blocks):
+        times, msd_xyz, sdc_xyz = blocks[group_id]
+        info = groups[group_id]
+        diffusion, average_mask, averaged_sdc = average_sdc(times, sdc_xyz)
+        conductivity = None
+        if info["element"] == args.diffuse_ion:
+            conductivity = calculate_conductivity(
+                diffusion, info["count"], args.ion_charge, volume, temperature)
+            job_sigma += conductivity
+            mobile_found = True
+        stem = save_group_data(output_dir, group_id, info["element"], temp_label,
+                               times, msd_xyz, sdc_xyz)
+        record = {
+            "job": job_label, "temperature": temperature, "volume": volume,
+            "ensemble": ensemble, "volume_source": volume_source,
+            "group_id": group_id, "element": info["element"],
+            "count": info["count"],
+            "average_start": float(times[average_mask][0]),
+            "average_end": float(times[average_mask][-1]),
+            "diffusion": diffusion,
+            "conductivity": conductivity,
+        }
+        save_group_results(output_dir, stem, record, averaged_sdc)
+        records.append(record)
+    sigma_text = (f", total sigma_{args.diffuse_ion}={job_sigma[3]:.8f} mS/cm"
+                  if mobile_found else f", no {args.diffuse_ion} group")
+    print(
+        f"  {job_label} -> {output_dir} "
+        f"({len(records)} group(s), {ensemble}, {volume_source}{sigma_text})"
+    )
+    return records
+
+
+def write_summary(root, records, diffuse_ion):
+    columns = [
+        "Job", "T(K)", "V(A^3)", "Ensemble", "Volume_source",
+        "Group", "Element", "N", "average_start(ps)", "average_end(ps)",
+        "D_x(cm^2/s)", "D_y(cm^2/s)", "D_z(cm^2/s)", "D_total(cm^2/s)",
+        "sigma_x(mS/cm)", "sigma_y(mS/cm)", "sigma_z(mS/cm)",
+        "sigma_total(mS/cm)",
+    ]
+    lines = [
+        "GPUMD SDC and Nernst-Einstein conductivity summary",
+        f"Mobile ion: {diffuse_ion}",
+        "SDC average: arithmetic mean over the last 50% of correlation time",
+        "\t".join(columns),
+    ]
+    for record in sorted(records, key=lambda item: (item["job"], item["group_id"])):
+        conductivity = record["conductivity"]
+        sigma = ([f"{value:.8f}" for value in conductivity]
+                 if conductivity is not None else ["N/A"] * 4)
+        fields = [
+            record["job"], f"{record['temperature']:.8f}",
+            f"{record['volume']:.8f}", record["ensemble"],
+            record["volume_source"], str(record["group_id"]),
+            record["element"], str(record["count"]),
+            f"{record['average_start']:.8f}",
+            f"{record['average_end']:.8f}",
+            *(f"{value:.8f}" for value in record["diffusion"]), *sigma,
+        ]
+        lines.append("\t".join(fields))
+    (Path(root) / SUMMARY_FILE).write_text(
+        "\n".join(lines) + "\n", encoding="utf-8")
+
+
+def add_arguments(parser):
+    parser.formatter_class = argparse.ArgumentDefaultsHelpFormatter
+    parser.add_argument("-entry-path", default=".",
+                        help="Root recursively scanned for GPUMD MSD jobs.")
+    parser.add_argument("-diffuse_ion", default="Li",
+                        help="Mobile ion used for conductivity.")
+    parser.add_argument("-ion_charge", type=int, default=1,
+                        help="Signed mobile-ion valence Z (the formula uses Z squared).")
+
+
+def run(args):
+    root = Path(args.entry_path).resolve()
+    jobs = discover_jobs(root)
+    if not jobs:
+        print("No GPUMD MSD jobs found recursively (need msd.out, thermo.out "
+              "or thermos.out, model.xyz, and run.in in one folder).")
+        return 0
+    print(f"Found {len(jobs)} GPUMD MSD job folder(s).")
+    records = []
+    for folder, thermo_path in jobs:
+        try:
+            records.extend(analyze_job(root, folder, thermo_path, args))
+        except Exception as exc:
+            print(f"  {folder}: analysis failed ({exc}) -> skipping")
+    if records:
+        write_summary(root, records, args.diffuse_ion)
+        print(f"Wrote {root / SUMMARY_FILE} ({len(records)} group record(s)).")
+        return 0
+    print("No GPUMD MSD job could be analyzed; summary was not written.")
+    return 1
+
+
+if __name__ == "__main__":
+    _parser = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_parser)
+    raise SystemExit(run(_parser.parse_args()))