pymdkit 1.4.4__tar.gz → 1.4.6__tar.gz

{pymdkit-1.4.4 → pymdkit-1.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.4.4
+Version: 1.4.6
 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
@@ -177,7 +177,7 @@ When `pca` or `umap` receives `-it train.xyz`, it reads `Config_type` from every
 
 For folder conversion, `convert -if INPUT -of OUTPUT` writes `.xyz` by default. Set another target extension with `-oe`, for example `-oe cif` or `-oe vasp`. Single-file and trajectory modes infer the target format from `-o` and `-ot`.
 
-`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When multiple lattice or volume measures independently show a transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters, volume, temperature, pressure, and angles remain supporting diagnostics. Thermo plots use Arial when available, opaque legends, correct Å units, and shaded abnormal regions on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. The analysis uses the last `run` segment, or the last 80% when `run.in` has no `run` record; inspect the plot before making a final scientific judgment.
+`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When at least two independent lattice-parameter or volume measures show the same mapped transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters and volume can corroborate an energy transition. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. The analysis uses the last `run` segment, or the last 80% when `run.in` has no `run` record; inspect the plot before making a final scientific judgment.
 
 The thermo parser follows the [official GPUMD thermo.out format](https://gpumd.org/gpumd/output_files/thermo_out.html): 18 columns are required, `pressure.txt` exports `Pxx Pyy Pzz Pyz Pxz Pxy`, box vectors are interpreted as a full 3×3 matrix, `time_step` propagates between runs, and `dump_thermo` does not.
 

{pymdkit-1.4.4 → pymdkit-1.4.6}/README.md

@@ -151,7 +151,7 @@ When `pca` or `umap` receives `-it train.xyz`, it reads `Config_type` from every
 
 For folder conversion, `convert -if INPUT -of OUTPUT` writes `.xyz` by default. Set another target extension with `-oe`, for example `-oe cif` or `-oe vasp`. Single-file and trajectory modes infer the target format from `-o` and `-ot`.
 
-`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When multiple lattice or volume measures independently show a transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters, volume, temperature, pressure, and angles remain supporting diagnostics. Thermo plots use Arial when available, opaque legends, correct Å units, and shaded abnormal regions on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. The analysis uses the last `run` segment, or the last 80% when `run.in` has no `run` record; inspect the plot before making a final scientific judgment.
+`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When at least two independent lattice-parameter or volume measures show the same mapped transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters and volume can corroborate an energy transition. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. The analysis uses the last `run` segment, or the last 80% when `run.in` has no `run` record; inspect the plot before making a final scientific judgment.
 
 The thermo parser follows the [official GPUMD thermo.out format](https://gpumd.org/gpumd/output_files/thermo_out.html): 18 columns are required, `pressure.txt` exports `Pxx Pyy Pzz Pyz Pxz Pxy`, box vectors are interpreted as a full 3×3 matrix, `time_step` propagates between runs, and `dump_thermo` does not.
 

{pymdkit-1.4.4 → pymdkit-1.4.6}/pyproject.toml

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

{pymdkit-1.4.4 → pymdkit-1.4.6}/src/pymdkit/__init__.py

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

{pymdkit-1.4.4 → pymdkit-1.4.6}/src/pymdkit/commands/_gpumd.py

@@ -310,8 +310,6 @@ def structural_abnormal_mask(lengths, volume):
     ]
     votes = np.sum(masks, axis=0)
     candidate = votes >= 2
-    if not candidate.any():
-        candidate = votes >= 1
     candidate = _bridge_mask(candidate, max(1, len(candidate) // 50))
     return _keep_major_regions(_clean_mask(candidate))
 
@@ -363,7 +361,9 @@ def load_thermo(thermo_path, run_path):
     thermo_path = Path(thermo_path)
     data = np.loadtxt(thermo_path, ndmin=2)
     if data.shape[1] != 18:
-        raise ValueError(f"{thermo_path} must use the official 18-column GPUMD format")
+        raise ValueError(
+            f"{thermo_path} must use the official 18-column GPUMD format"
+        )
 
     time_step, dump_interval, runs = parse_run_input(run_path)
     time = time_axis(len(data), time_step, dump_interval, runs)
@@ -373,63 +373,54 @@ def load_thermo(thermo_path, run_path):
     lengths, angles, volume = cell_quantities(data)
     start = equilibrium_start(len(data), runs)
 
-    structural_warnings = find_abnormal({
+    cell_warnings = find_abnormal({
         "lattice-parameter": lengths,
         "volume": volume,
+    }, start)
+    angle_warnings = find_abnormal({
         "lattice-angle": angles,
     }, start)
-    other_warnings = find_abnormal({
+    diagnostic_warnings = find_abnormal({
         "temperature": temperature,
         "pressure": pressure,
     }, start)
 
-    abnormal_mask = np.zeros(len(data), dtype=bool)
+    segment_length = len(data) - start
     segment_mask = potential_abnormal_mask(potential[start:])
-    abnormal_mask[start:] = segment_mask
-    warnings = []
+    warning_prefix = "potential-energy: localized"
 
-    if not segment_mask.any() and structural_warnings:
+    # Structural evidence can lower the energy threshold only when at least
+    # two independent cell measures agree on a mapped transition.
+    if not segment_mask.any() and len(cell_warnings) >= 2:
         structural_mask = structural_abnormal_mask(
             lengths[start:], volume[start:]
         )
-        relaxed_energy = potential_abnormal_mask(
-            potential[start:], corroborated=True
-        )
-        overlap = relaxed_energy & structural_mask
-        if overlap.any():
-            segment_mask = _keep_major_regions(
-                _bridge_mask(overlap, max(1, len(overlap) // 20))
+        if structural_mask.any():
+            relaxed_energy = potential_abnormal_mask(
+                potential[start:], corroborated=True
             )
-            warning_prefix = "potential-energy: structurally corroborated"
-        elif structural_mask.any():
-            segment_mask = structural_mask
-            warning_prefix = "structure: mapped fallback"
-        else:
-            segment_mask = np.ones(len(potential) - start, dtype=bool)
-            warning_prefix = "structure: full equilibrium fallback"
-        abnormal_mask[start:] = segment_mask
-    else:
-        warning_prefix = "potential-energy: localized"
+            overlap = relaxed_energy & structural_mask
+            if overlap.any():
+                segment_mask = _keep_major_regions(
+                    _bridge_mask(overlap, max(1, segment_length // 20))
+                )
+                warning_prefix = "potential-energy: structurally corroborated"
+            else:
+                segment_mask = structural_mask
+                warning_prefix = "structure: coherently mapped"
 
+    abnormal_mask = np.zeros(len(data), dtype=bool)
+    abnormal_mask[start:] = segment_mask
     intervals = mask_intervals(time, abnormal_mask)
+    warnings = []
     if intervals:
         warnings.append(
             f"{warning_prefix} abnormal region(s) at "
             + _format_intervals(intervals)
         )
-    else:
-        potential_reason = abnormal_reason(potential[start:])
-        if potential_reason:
-            warnings.append(f"potential-energy: {potential_reason}")
-            abnormal_mask[start:] = True
-
-    warnings.extend(structural_warnings)
-    warnings.extend(other_warnings)
-    if warnings and not abnormal_mask.any():
-        abnormal_mask[start:] = True
-        warnings.insert(
-            0, "region mapping: full equilibrium segment used as fallback"
-        )
+        warnings.extend(cell_warnings)
+        warnings.extend(angle_warnings)
+        warnings.extend(diagnostic_warnings)
 
     return ThermoData(
         time=time,

{pymdkit-1.4.4 → pymdkit-1.4.6}/src/pymdkit/commands/gpumd_thermo.py

@@ -13,14 +13,21 @@ except ImportError:
     from _gpumd import load_thermo, mask_intervals
 
 COMMAND = "gpumd-thermo"
-HELP = "Export and plot GPUMD thermo.out data and warn about instability."
-
+HELP = "Export and plot GPUMD thermo.out data and warn about instability."
+
+DARK2_NAME = "Dark2"
 
 def save_table(path, time, values, header):
     values = np.asarray(values)
     if values.ndim == 1:
         values = values[:, None]
-    np.savetxt(path, np.column_stack([time, values]), fmt="%.10g", header=header)
+    np.savetxt(
+        path,
+        np.column_stack([time, values]),
+        fmt="%.10g",
+        header=header,
+        encoding="utf-8",
+    )
 
 
 def scaled_plot_values(values, quantity, unit):
@@ -32,47 +39,49 @@ def scaled_plot_values(values, quantity, unit):
     return values, f"{quantity} ({unit})"
 
 
-def mark_abnormal_regions(axis, intervals):
-    for begin, end in intervals:
+def mark_abnormal_regions(axis, intervals, color):
+    for index, (begin, end) in enumerate(intervals):
         axis.axvspan(
-            begin, end, color="#d9e8f5", alpha=0.85, linewidth=0, zorder=0
-        )
-        axis.text(
-            (begin + end) / 2.0,
-            0.97,
-            "abnormal region",
-            transform=axis.get_xaxis_transform(),
-            ha="center",
-            va="top",
-            fontsize=7,
-            color="#315a7d",
-            bbox={
-                "facecolor": "white",
-                "edgecolor": "none",
-                "alpha": 0.8,
-                "pad": 1.0,
-            },
-            clip_on=True,
-            zorder=4,
+            begin,
+            end,
+            color=color,
+            alpha=0.25,
+            linewidth=0,
+            label="abnormal region" if index == 0 else "_nolegend_",
+            zorder=0,
         )
 
+def set_upper_headroom(axis, values):
+    values = np.asarray(values, dtype=float)
+    finite = values[np.isfinite(values)]
+    if not finite.size:
+        return
+    minimum = float(np.min(finite))
+    maximum = float(np.max(finite))
+    span = maximum - minimum
+    if span == 0:
+        span = max(abs(maximum) * 0.05, 1.0)
+    axis.set_ylim(minimum - 0.05 * span, maximum + 0.4 * span)
 
 def plot_thermo(path, thermo):
     import matplotlib
     matplotlib.use("Agg")
+    from cycler import cycler
+    colors = [
+        matplotlib.colors.to_hex(color)
+        for color in matplotlib.colormaps[DARK2_NAME].colors
+    ]
     matplotlib.rcParams.update({
         "font.family": "sans-serif",
         "font.sans-serif": ["Arial", "Liberation Sans", "DejaVu Sans"],
+        "axes.prop_cycle": cycler(color=colors),
+        "image.cmap": DARK2_NAME,
     })
     import matplotlib.pyplot as plt
 
-    colors = ("#d22027", "#015699", "#fac00f")
     legend_style = {
-        "loc": "best",
-        "frameon": True,
-        "facecolor": "white",
-        "edgecolor": "none",
-        "framealpha": 1.0,
+        "loc": "upper right",
+        "frameon": False,
     }
     intervals = mask_intervals(thermo.time, thermo.abnormal_mask)
     potential, potential_label = scaled_plot_values(
@@ -93,9 +102,11 @@ def plot_thermo(path, thermo):
         thermo.time, potential, color=colors[0], zorder=2
     )
     axes[0, 1].set_ylabel(potential_label)
-    mark_abnormal_regions(axes[0, 1], intervals)
+    mark_abnormal_regions(axes[0, 1], intervals, colors[7])
+    if intervals:
+        axes[0, 1].legend(**legend_style).set_zorder(4)
 
-    for index, label in enumerate(("Pxx", "Pyy", "Pzz")):
+    for index, label in enumerate(("Pxx", "Pyy", "Pzz", "Pyz", "Pxz", "Pxy")):
         axes[0, 2].plot(
             thermo.time,
             thermo.pressure[:, index],
@@ -104,7 +115,8 @@ def plot_thermo(path, thermo):
             zorder=2,
         )
     axes[0, 2].set_ylabel("Pressure (GPa)")
-    axes[0, 2].legend(**legend_style).set_zorder(4)
+    set_upper_headroom(axes[0, 2], thermo.pressure)
+    axes[0, 2].legend(**legend_style, ncol=2).set_zorder(4)
 
     for index, label in enumerate(("a", "b", "c")):
         axes[1, 0].plot(
@@ -115,14 +127,17 @@ def plot_thermo(path, thermo):
             zorder=2,
         )
     axes[1, 0].set_ylabel("Lattice parameters (Å)")
-    mark_abnormal_regions(axes[1, 0], intervals)
+    mark_abnormal_regions(axes[1, 0], intervals, colors[7])
+    set_upper_headroom(axes[1, 0], thermo.lengths)
     axes[1, 0].legend(**legend_style).set_zorder(4)
 
     axes[1, 1].plot(
         thermo.time, volume, color=colors[1], zorder=2
     )
     axes[1, 1].set_ylabel(volume_label)
-    mark_abnormal_regions(axes[1, 1], intervals)
+    mark_abnormal_regions(axes[1, 1], intervals, colors[7])
+    if intervals:
+        axes[1, 1].legend(**legend_style).set_zorder(4)
 
     for index, label in enumerate(("alpha", "beta", "gamma")):
         axes[1, 2].plot(
@@ -151,6 +166,25 @@ def plot_thermo(path, thermo):
     plt.close(fig)
 
 
+def write_abnormal_time(path, intervals):
+    path = Path(path)
+    if not intervals:
+        path.unlink(missing_ok=True)
+        return False
+
+    text = "".join(
+        f"{begin:.2f} ps to {end:.2f} ps\n"
+        for begin, end in intervals
+    )
+    temporary = path.with_name(f".{path.name}.pmk-tmp")
+    try:
+        temporary.write_text(text, encoding="utf-8")
+        temporary.replace(path)
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+    return True
+
 def process_job(folder, thermo_name, run_name):
     thermo = load_thermo(folder / thermo_name, folder / run_name)
     save_table(
@@ -190,6 +224,10 @@ def process_job(folder, thermo_name, run_name):
         "time(ps) alpha(deg) beta(deg) gamma(deg)",
     )
     plot_thermo(folder / "thermo.png", thermo)
+    intervals = mask_intervals(thermo.time, thermo.abnormal_mask)
+    wrote_abnormal_time = write_abnormal_time(
+        folder / "abnormal-time.txt", intervals
+    )
 
     print(
         f"{folder}: {len(thermo.time)} thermo record(s), "
@@ -202,6 +240,8 @@ def process_job(folder, thermo_name, run_name):
     else:
         print("No sustained equilibrium drift or level shift detected.")
     print("Wrote thermo text tables and thermo.png")
+    if wrote_abnormal_time:
+        print("Wrote abnormal-time.txt")
 
 
 def discover_jobs(thermo_arg, run_arg):
@@ -257,4 +297,4 @@ def run(args) -> int:
 if __name__ == "__main__":
     _parser = argparse.ArgumentParser(description=__doc__)
     add_arguments(_parser)
-    raise SystemExit(run(_parser.parse_args()))
+    raise SystemExit(run(_parser.parse_args()))

{pymdkit-1.4.4 → pymdkit-1.4.6}/src/pymdkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.4.4
+Version: 1.4.6
 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
@@ -177,7 +177,7 @@ When `pca` or `umap` receives `-it train.xyz`, it reads `Config_type` from every
 
 For folder conversion, `convert -if INPUT -of OUTPUT` writes `.xyz` by default. Set another target extension with `-oe`, for example `-oe cif` or `-oe vasp`. Single-file and trajectory modes infer the target format from `-o` and `-ot`.
 
-`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When multiple lattice or volume measures independently show a transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters, volume, temperature, pressure, and angles remain supporting diagnostics. Thermo plots use Arial when available, opaque legends, correct Å units, and shaded abnormal regions on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. The analysis uses the last `run` segment, or the last 80% when `run.in` has no `run` record; inspect the plot before making a final scientific judgment.
+`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When at least two independent lattice-parameter or volume measures show the same mapped transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters and volume can corroborate an energy transition. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. The analysis uses the last `run` segment, or the last 80% when `run.in` has no `run` record; inspect the plot before making a final scientific judgment.
 
 The thermo parser follows the [official GPUMD thermo.out format](https://gpumd.org/gpumd/output_files/thermo_out.html): 18 columns are required, `pressure.txt` exports `Pxx Pyy Pzz Pyz Pxz Pxy`, box vectors are interpreted as a full 3×3 matrix, `time_step` propagates between runs, and `dump_thermo` does not.