pymdkit 1.7.2__tar.gz → 1.7.4__tar.gz

pymdkit-1.7.4/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 1.7.4
+
+- `pmk msd -ne` retains finite, positive Einstein diffusion coefficients and
+  Nernst–Einstein conductivity when the fit-quality diagnostics would reject the
+  window. The result is reported and aggregated as WARNING, with the original
+  diagnostic details preserved. This applies to automatic and manual windows.
+- Missing valid regression, failed requested estimators, and invalid NE inputs
+  still fail the calculation and preserve existing aggregate summaries.
+
+## 1.7.3
+
+- `pmk msd` analyzes fixed-cell GPUMD NVT trajectories, selects or accepts a
+  fitting window, and optionally reports Nernst–Einstein conductivity. It uses
+  free-intercept OLS by default. Optional WLS and GLS also estimate the intercept.
+  Forced-origin fitting has been removed from production.
+- `pmk pred-msd-time` uses validated full-trajectory OLS references to forecast
+  higher-temperature Li conductivity, diffusion, and NVT production duration.
+  The Arrhenius forecast and square-root duration scaling are planning heuristics.
+  The durations carry no guarantee of MSD convergence.
+- `pmk gpumd-job -msd-time` generates GPUMD 4.2-compatible jobs with explicit
+  NVT temperatures, run lengths, and optional `compute_msd` sample counts.
+  Fixed-cell NVT production is required for MSD analysis. Earlier NPT equilibration
+  is supported when its frames are excluded from the analyzed trajectory.

pymdkit-1.7.4/MANIFEST.in

@@ -0,0 +1,4 @@
+include CHANGELOG.md
+include tests/data/88-Li2YCl3-63-d1.cif
+exclude tests/test_benchmark_msd_io.py
+prune devtools

{pymdkit-1.7.2 → pymdkit-1.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.7.2
+Version: 1.7.4
 Summary: A Python command-line toolkit for high-throughput atomistic workflows in AI-driven materials design.
 Author-email: Yueda Wang <ydwang0608@ustc.edu.cn>
 License-Expression: GPL-3.0-or-later
@@ -36,6 +36,26 @@ materials design. Install `pymdkit` once and call its tools from anywhere as
 Commands expose explicit, documented CLI interfaces designed for reproducible shell,
 HPC, and AI-agent workflows, and each underlying script is still runnable on its own.
 
+## 1.7.4 release notes
+
+- `pmk msd -ne` retains valid Einstein diffusion coefficients and conductivity
+  as WARNING when fit quality would otherwise be REJECT. This applies to
+  automatic and manual windows and preserves the individual diagnostic results.
+- Missing valid regression, failed requested estimators, and invalid NE inputs
+  still cause calculation errors. Without `-ne`, fit-quality rejection still
+  withholds diffusion coefficients.
+
+## 1.7.3 release notes
+
+- `pmk msd` analyzes GPUMD trajectories from fixed-cell NVT production. OLS is
+  the default, and OLS, WLS and GLS all fit a free intercept. Forced-origin
+  fitting has been removed from production. Changing-cell MSD is outside scope.
+- `pmk pred-msd-time` uses validated free-intercept OLS references for
+  higher-temperature Li transport and production-time planning. The duration
+  heuristic carries no guarantee of MSD convergence.
+- `pmk gpumd-job -msd-time` turns predictions into GPUMD 4.2-compatible NVT
+  job inputs. Earlier NPT equilibration can precede the analyzed production.
+
 ## Install
 
 ### Online installation
@@ -86,7 +106,7 @@ installed.
 On a machine with Internet access, run:
 
 ```bash
-python -m pip download pymdkit==1.7.2 -d pymdkit-offline
+python -m pip download pymdkit==1.7.4 -d pymdkit-offline
 ```
 
 This downloads `pymdkit` and the dependencies resolved by pip into the
@@ -94,14 +114,14 @@ This downloads `pymdkit` and the dependencies resolved by pip into the
 system. Then, inside the target pymdkit Python or conda environment, run:
 
 ```bash
-python -m pip install --no-index --find-links=pymdkit-offline pymdkit==1.7.2
+python -m pip install --no-index --find-links=pymdkit-offline pymdkit==1.7.4
 ```
 
 For optional GPU use, prepare the bundle on a networked machine compatible with
 the target HPC platform and Python environment:
 
 ```bash
-python -m pip download "pymdkit[gpu-cuda12]==1.7.2" -d pymdkit-offline
+python -m pip download "pymdkit[gpu-cuda12]==1.7.4" -d pymdkit-offline
 ```
 
 Transfer the whole `pymdkit-offline` directory, then install from it on the
@@ -109,7 +129,7 @@ target system:
 
 ```bash
 python -m pip install --no-index --find-links=pymdkit-offline \
-    "pymdkit[gpu-cuda12]==1.7.2"
+    "pymdkit[gpu-cuda12]==1.7.4"
 ```
 
 This GPU bundle includes the optional `cupy-cuda12x` package. Its wheels must also
@@ -190,6 +210,7 @@ preserve occupancy, oxidation, symmetry, and Wyckoff metadata.
 | `dope` | Dope structures by substituting or removing selected atoms/sites |
 | `ewald` | Compute CIF electrostatic energy |
 | `gpumd-job` | Create supercell, temperature, potential, input, and grouped GPUMD jobs |
+| `pred-msd-time` | Predict Li conductivity, diffusion and NVT production durations from GPUMD MSD |
 | `gpumd-out` | Export GPUMD thermo/MSD results or gather final structures |
 | `mp-chemsys` | Download stable Materials Project structures for a chemical system |
 | `nep-rmse` | Compute NEP energy/force/stress RMSE and select candidates |
@@ -425,8 +446,13 @@ pmk gpumd-out -save-fs [-entry-path DIR] [-fs-name FILENAME] (-of DIR | -output-
 ```
 
 `-entry-path` defaults to `.`. Thermo mode defaults to `thermo.out` and
-`run.in`, preserving the per-job text tables, `thermo.png`, and
-`abnormal-time.txt` when an abnormal interval is detected. MSD mode defaults
+`run.in`, writing per-job `temperature.txt`, `potential-energy.txt`,
+`pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`,
+and the six-panel `thermo.png`. Abnormal-fluctuation diagnostics remain in
+console warnings and `gpumd-out.log`; the plot has no abnormal-region shading
+or legend. Thermo mode no longer generates `abnormal-time.txt` and removes
+that exact stale file only after successfully exporting a job's tables and
+plot. MSD mode defaults
 to mobile ion `Li` with charge `1`, writes
 `sigma-sdc-summary.txt` at the entry root, and preserves each job's
 `msd/group_*_msd.txt`, `group_*_sdc.txt`, and `group_*_results.txt`.
@@ -720,3 +746,354 @@ Every command module still works directly, which is handy for debugging:
 ```bash
 python src/pymdkit/commands/supercell.py -i in.cif -close-abc 20 -o sc.vasp
 ```
+## Atomic trajectory MSD
+
+```bash
+pmk msd -group 0
+pmk msd -group 0 -ne
+pmk msd -group 0 -ne -charge 2
+pmk msd -group 0 -fit-method gls
+pmk msd -group 0 -fit-range 10 100
+pmk msd -group 0 -ne -trajectory-range 0 10
+pmk msd -group 0 -ne -trajectory-range 10 20
+```
+
+`-md-program gpumd` is the default. The current directory and calculation
+subdirectories are searched deterministically, excluding generated `msd`, hidden,
+environment and build directories. Each calculation needs `model.xyz`, `run.in`
+and the native full-system trajectory named by `dump_xyz`, or `dump.xyz` from
+legacy `dump_exyz interval velocity_flag force_flag`. Group selection uses the
+first grouping method in `model.xyz`. Missing group labels are an error.
+
+Both `dump_xyz interval filename properties...` and GPUMD 4.2's
+`dump_xyz grouping_method group_id interval filename properties...` are supported.
+For example, `dump_xyz -1 0 200 dump.xyz group unwrapped_position` saves the whole
+system every 200 steps. Legacy grouping methods must be negative (full system);
+the group ID must be an integer and is ignored in this mode. Subset trajectories
+are rejected because whole-system COM correction requires every atom. Legacy
+`group` and modern `group_labels` properties are supported. Earlier NPT
+equilibration without trajectory output is allowed before fixed-cell NVT production.
+Directories with active unresolved `target_t`, `${...}` or `{{...}}` placeholders
+in `run.in` are skipped with a reason; commented placeholders are ignored.
+
+This is the mean of individual atomic squared displacements, **not group-COM
+MSD**. Every frame is streamed through a native GPUMD numeric parser (other
+extxyz schemas retain the ASE fallback), then selected coordinates are stored
+in a temporary float64 memmap. All system atoms contribute to mass-weighted COM
+displacement removal using ASE tabulated atomic masses. Species order, atom count,
+PBC flags, and group/ID columns (when present) are checked against the model.
+Native GPUMD full-system row ordering is required: externally sorted same-element
+atoms without stable IDs cannot be identified and must not be supplied.
+
+For fixed triclinic cells, consistent `unwrapped_position` is preferred; otherwise
+ASE's general lattice minimum-image algorithm accumulates successive displacements.
+Wrapped output must be frequent enough to resolve each displacement uniquely;
+multiple unseen boundary crossings cannot be recovered from saved frames.
+**MSD analysis supports fixed-cell NVT production.** NPT and changing-cell
+production are rejected, including pure affine deformation.
+
+The default `--fit-window auto` searches atom-based total MSD lag windows using
+log-log OLS beta, then calculates D independently with free-intercept Einstein
+OLS (directional slopes/2; total is their arithmetic mean). Following
+[MDTransport (2026)](https://doi.org/10.1021/acs.jcim.6c00558), the search grid
+is 100 ps. The default minimum duration is `min(T/2, 8000 ps)`, a continuous
+pymdkit engineering adaptation of the published piecewise rule that avoids
+infeasible windows immediately above 10 ns. Following
+[He et al. (2018)](https://doi.org/10.1038/s41524-018-0074-y), every automatic
+upper lag is strictly below 0.7T. T is saved frame count times frame interval,
+not the absolute simulation timestamp. Grid boundaries map to nearest MSD
+samples; first positive lag and last allowed lag are included as endpoints.
+The minimum duration is never silently relaxed.
+
+Controls are `--min-fit-window PS`, `--fit-window-step PS`, and
+`--beta-tolerance VALUE` (default 0.075, maximum 0.20). Among beta-qualified
+windows, choose D closest to the pool median, then smaller beta deviation, then
+longer duration. Without qualified windows choose minimum beta deviation.
+Separate `beta_status`, `intercept_status`, `einstein_slope_status` and
+`overall_status` distinguish raw beta from affine Einstein model consistency
+and slope stability. Beta thresholds remain 0.075 and 0.20. PASS additionally
+requires available, positive early/middle/late Einstein slopes with relative
+spread `(max-min)/median <= 0.20`. Insufficient segment data or a larger spread
+produces WARNING for beta within 0.20. Above 0.20 the result is REJECT unless
+the positive-intercept model agrees with observed beta within 0.05 **and**
+segment stability passes; this exception permits WARNING only, never PASS.
+
+The default reported D uses free-intercept OLS, `MSD(t) = A + 6 D t`.
+For each valid candidate, diagnostics retain free-intercept D,
+intercept fractions at both endpoints, and beta predicted
+by log-log OLS of `b+s*t` on the actual fitting samples. No intercept is
+subtracted from the measured MSD. A detected intercept effect explains model
+consistency, not the physical cause of the intercept. Full-window D remains the
+published estimate; segment D values never replace it. Segment diagnostics are
+computed only for the selected candidate, with explicit unavailable reasons.
+Relative D sensitivity `(P90-P10)/median > 0.5` also produces WARNING. These
+are diagnostics, not evidence of statistical convergence. Internal thresholds
+are named constants in `_msd_auto.py`; no smoothing or independent-window
+sample-count assumption is used. `--mobile-site-distance A` optionally checks
+the approximate MSD >= 0.5a^2 criterion using a known neighboring mobile-site
+distance; this is not a universal cutoff or an inferred instantaneous ion distance.
+Without it the structural ballistic cutoff is not independently determined.
+
+`-fit-range START_PS END_PS` retains manual lag-window fitting, including its
+previous upper-lag freedom; it conflicts with explicit `--fit-window auto`.
+`--fit-window manual` requires a range. For example:
+
+```bash
+pmk msd -group 0 -ne --fit-window auto
+pmk msd -group 0 -ne -fit-range 500 1200
+```
+
+Optional `-fit-method wls` and `-fit-method gls` fit the same free-intercept
+Einstein model per direction, using binary nonoverlapping block samples within
+the selected window. WLS uses diagonal block-error covariance and GLS includes
+cross-lag correlations. At least four binary sampling levels and an identifiable
+fit are required. The weighted intercepts appear in `fit-diagnostic.txt`.
+The window and its quality diagnostics use OLS for all three methods.
+Forced-origin fitting has been removed from the production workflow.
+
+`-trajectory-range START END` selects a separate saved-trajectory subset in ns,
+using the half-open interval `[START, END)` relative to the first original
+`Time=` header, not the simulation start. GPUMD header times are in fs.
+Every scanned timestamp must be finite, increasing, uniformly spaced and
+consistent with `run.in`; missing timestamps/frames or unreliable thermo
+alignment fail clearly. Boundary comparisons use the existing schedule-scale
+tolerance `max(1e-5 fs, abs(Time)*1e-9)` for floating accumulation. Available
+coverage ends one sampling interval after the last frame (thus 100000 frames
+at 0.2 ps cover 20 ns). Actual selected timestamps/count are recorded.
+Headers and rows before START are streamed without coordinate parsing; reading
+stops at the END header when present. The suffix beyond END is not validated.
+Only selected coordinates enter the existing whole-system mass-weighted COM
+correction, selected individual-atom memmap and independent all-origin FFT.
+Lag time restarts at zero; `-fit-range` remains an independent lag interval in ps.
+
+Range outputs go to `msd/segments/START-ENDns/`, with shortest decimal float
+values expanded without exponent or redundant trailing zeros (`0-10ns`,
+`10-20ns`, `0.5-2.5ns`). Existing segment directories are refused. Full-run
+outputs, other segments and root summaries are preserved; successful segment
+aggregate summaries live in the segment directory. Each segment also records
+`diagnostics.json`, `fit-windows.txt` and `fit-diagnostic.txt`, including REJECT.
+No credible fit means no new formal D or conductivity. A 10 ns segment cannot
+fit the full trajectory's 5.9–14 ns window: unchanged automatic thresholds
+search only its available lags. NE uses measured thermo samples in the same
+half-open global interval, after header/schedule alignment and cell checks;
+segment mode never substitutes a full-run temperature or nominal fallback.
+No validated uncertainty estimate or formal confidence interval is implied.
+Omitting `-trajectory-range` retains the full-trajectory path.
+
+Each successful calculation creates `msd/msd.txt` (five numeric columns: lag
+time in ps, x/y/z MSD and their sum in Ų), `msd/self-diff.txt` (x/y/z/total
+diffusion in cm²/s, `%.2e`) and, only with `-ne`, `msd/sigma.txt` (x/y/z/total
+Nernst–Einstein conductivity in mS/cm, `%.2f`). Headers are comments. Total
+diffusion and conductivity are directional arithmetic means before rounding;
+display rounding may cause last-digit differences. PASS and WARNING write these
+coefficients with the quality status in their comment headers. `provenance.json`
+records the final quality and full-precision total coefficients.
+
+With `-ne`, an automatic or manual window with finite, positive x/y/z/total
+Einstein diffusion coefficients retains D and NE conductivity even when the fit
+quality would otherwise be REJECT. The overall status becomes WARNING. The
+original reason and the beta, intercept-consistency, and three-segment slope
+diagnostics remain in the fit output. A WARNING can indicate that the physical
+diffusion regime failed quality criteria. Without `-ne`, REJECT returns nonzero
+and retains only raw MSD and fit diagnostics. PASS and WARNING retain D.
+
+`fit-windows.txt` records evaluated candidates, rejection reasons, beta,
+directional D, R², intercept, RSS, points, upper-lag origin count, intercept
+diagnostics, and selected-window segment D values. `fit-diagnostic.txt` records
+settings, selection, and sensitivity. Beta-qualified window sensitivity,
+all-valid-candidate sensitivity, and three-segment slope spread are reported
+separately. Segments and MSD time origins are correlated. Window-to-window spread
+measures sensitivity. Formal statistical uncertainty requires an explicit
+request. Move an existing `msd` directory aside before repeating a calculation.
+Temporary coordinate storage is removed when the calculation ends.
+
+The five-column raw MSD is published immediately after FFT succeeds, before
+window search, optional uncertainty, or thermodynamic/NE processing. Later errors
+retain this curve and any completed fit diagnostics. A missing valid regression,
+a failed requested WLS/GLS estimator, or invalid required thermodynamic inputs
+returns nonzero and prevents publication of new coefficients and aggregates.
+Parsing and FFT failures occur before the raw curve is published.
+FFT uses float64 atom chunks sized from an internal 128 MiB workspace budget,
+with bounded remapping of time slabs to avoid retaining the entire coordinate
+memmap in RAM. For 100000 frames and 784 selected atoms the temporary coordinate
+file needs 1,881,600,000 bytes, plus filesystem overhead and output files.
+Installation diagnostics are available with `python devtools/diagnose_msd_install.py`;
+run it using the interpreter in the `pmk` shebang, since source and installed
+distribution versions can differ. Both `pmk -version` and `pmk --version` work.
+
+Optional covariance uncertainty (experimental Phase 4B.1.1):
+
+```text
+pmk msd -group 0 --uncertainty covariance
+pmk msd -group 0 -ne --uncertainty covariance --uncertainty-lag-points 100 --uncertainty-confidence 0.95
+```
+
+Adds `self-diff-uncertainty.txt`, `uncertainty-diagnostic.txt` and, with `-ne`,
+`sigma-uncertainty.txt`, using labeled JSON records. Existing point estimates and
+formats remain unchanged. Available results include 68% and 95% Bayesian credible
+intervals plus the requested confidence-level interval. SciPy is lazily imported.
+All overlapping origins contribute to moments: `M=N_mobile*(N_frames-lag_index)`.
+The continuous effective scaling parameter is `N'=N_mobile*N_frames/lag_index`,
+not a literal count of disjoint intervals. The default selects 100 original lag
+indices including window endpoints. The smoothing law `a*t^2/N_effective` uses
+closed-form unweighted nonnegative least squares, verified against the objective
+in kinisi 1.1.0 (without copying its implementation).
+
+Continuous counts remove the artificial integer discontinuities. Diagnostics
+compare raw and smoothed covariance, and Tabeart minimum-eigenvalue reconditioning
+at condition limits 1e8/1e12/1e16, including eigenvalue adjustments, relative matrix
+change and conditional posteriors. The threshold is lambda_max/condition_limit;
+no diagonal jitter is added. Failed numerical verification remains unavailable.
+Real 500 K covariance is now positive definite, but reported intervals remain
+`UNAVAILABLE`: interacting-ion coverage has not been established. WARNING windows
+retain conditional candidates in diagnostics only; rejected windows have none.
+CLI success does not imply an available interval: inspect the uncertainty status.
+
+Intervals are conditional on the chosen window and estimated covariance.
+Interacting ions and whole-system COM correction limit the independent-particle
+approximation. Covariance-parameter, window-selection, distinct-ion correlation
+and Haven-ratio uncertainties are excluded. With uncertainty requested, missing
+`thermo.out` uses a labeled nominal stationary NVT target; the existing ordinary
+NE path still requires measured temperature. NPT remains release-blocked.
+See [Phase 4B.1 report](devtools/MSD_UNCERTAINTY_PHASE4B1_REPORT.md).
+The [Phase 4B.1.1 correction report](devtools/MSD_UNCERTAINTY_PHASE4B1_1_REPORT.md)
+supersedes its effective-count and real-covariance conclusions. Correlated-particle
+nominal 95% coverage is 67% in the corrected seeded benchmark; a narrow interval
+does not demonstrate statistical convergence.
+
+External validation is opt-in via `PYMDKIT_MSD_TEST_DATA` or:
+
+```text
+python devtools/validate_msd_uncertainty.py --data-dir PATH --output NEW_OUTPUT_DIRECTORY
+```
+
+Output must be a new directory outside the input dataset. The script hashes
+original inputs/results before and after, regenerates missing diagnostics,
+reads the original trajectory and removes temporary coordinates. Normal tests
+do not require this external dataset.
+
+After every eligible calculation succeeds, root-level `self-diff-total.txt` and,
+with `-ne`, `sigma-total.txt` summarize directory, temperature (K), and the
+isotropic total D (cm²/s, `%.2e`) or conductivity (mS/cm, `%.2f`). Rows use
+relative paths and sort by numeric temperature, then path. Summaries use internal
+unrounded totals. NE uses measured mean production temperature; without NE a
+single stationary production NVT target is required (ramps, multiple targets and
+missing NVT targets produce an explicit error). Genuine calculation failures return
+nonzero and preserve previous summaries; skipped templates are not failures.
+A successful run without `-ne` removes any stale root `sigma-total.txt`.
+The companion `msd-quality-total.txt` retains each directory's PASS/WARNING
+status. In NE mode, a directory whose valid coefficients were retained despite
+fit-quality rejection appears as WARNING and contributes to both numeric
+summaries. Without `-ne`, a directory with overall REJECT prevents publication
+of new aggregates.
+See [the automatic-fit report](devtools/MSD_AUTO_FIT_REPORT.md) for validation,
+and [the intercept/stability update](devtools/MSD_AUTO_FIT_PHASE4A1_REPORT.md)
+for the current policy, 500 K MSD comparison and limitations.
+
+`-ne` requires a homogeneous selected element and `thermo.out`. The default
+`-charge 1.0` is an explicit +1 formal-charge assumption, not inferred oxidation
+state; negative charges are accepted and the sign cancels. The log records charge,
+measured and target temperature, volume and fit diagnostics. Thermodynamic rows
+are aligned using every run's own output interval. Volume is the absolute cell
+determinant from columns 10–18, never a separate column or the initial model
+volume. Only records between the first and last saved trajectory timestamps are
+averaged; shared sample times cross-check trajectory volumes. The thermo reader
+supports NPT mean volumes internally, but this does not enable NPT MSD. NVT
+volumes must be constant. Measured mean temperature enters the NE equation;
+a >5% target mismatch warns. Temperature ramps are rejected for NE.
+
+Nernst–Einstein conductivity uses self-diffusion and neglects distinct-ion cross
+correlations. It is not generally equal to experimental conductivity. The existing
+`gpumd-out -msd` workflow is unchanged.
+
+## Plan GPUMD NVT production from Li MSD
+
+Run the predictor from a project directory containing completed GPUMD tasks.
+
+```bash
+pmk pred-msd-time -ea 0.2 -temp-interval 50 -max-temp 550
+pmk gpumd-job -i model.xyz -nep nep.txt -in run.in -msd-time pred-msd-time.log
+```
+
+The predictor defaults to Li group 0 in grouping method 0 and selects the lowest
+eligible measured temperature. Use `-group` to select a different Li group or
+`-ref-temp 300` to select a reference by its nominal or measured temperature.
+The prediction grid advances by `-temp-interval` from the reference's nominal
+setpoint up to `-max-temp`. Each target must be above the measured reference.
+Inconsistent results at the same reference temperature require resolution
+before planning.
+
+Use a completed, fixed-cell NVT production trajectory with its original
+`run.in`, `model.xyz`, and aligned `thermo.out`. The predictor requires a
+full-trajectory free-intercept OLS result from `pmk msd -ne -group 0` (or the
+matching Li group) with a +1 formal charge. PASS and WARNING are eligible. A
+baseline WARNING carries into every prediction, and REJECT excludes the fit
+from baseline selection. Successful MSD analyses write `msd/provenance.json`
+(or the equivalent file in a segment directory), which records source and
+result fingerprints, the selected group and fit, and measured thermodynamics
+when available. Older full-run results require an identifiable trajectory,
+group, fit window and quality, agreement with the saved curve and NE totals,
+and output timestamps at least as recent as the inputs. Incomplete or stale
+analyses are reported with their reason. Prediction does not rerun MSD.
+
+Measured conductivity comes from the reference MSD slope and Nernst–Einstein
+(NE) relation. The forecast uses the measured reference temperature and
+conductivity with the conventional `ln(sigma*T)` Arrhenius relation.
+
+```text
+sigma(T) = sigma_r * (T_r / T) * exp[-Ea/kB * (1/T - 1/T_r)]
+D(T)     = sigma(T) * V(T) * kB * T / (N_Li * q^2)  [in consistent units]
+t_raw    = saved_reference_ns * sqrt(D_reference / D(T))
+t_plan   = ceil(max(min_production_ns, t_raw))      [ns]
+```
+
+Conductivity is independent of the volume prediction. Diffusion uses the same
+NE relation with the predicted volume and the reference Li count. With one NVT
+volume sample the volume is constant. With compatible samples (same full-cell
+composition, selected Li count and fully periodic fixed-cell convention), it
+is interpolated between measured temperatures. Targets beyond the measured
+volume range use the nearest endpoint and generate a warning. Other measured
+conductivities are compared at their actual measured temperatures. The log
+reports the absolute gap, fractional gap relative to the measurement, and
+measured-to-predicted ratio. Different fit windows limit the comparison to an
+indicative check. The supplied activation energy stays fixed.
+
+The square-root scaling is an empirical planning heuristic. The default 6 ns
+is a planning floor, configurable with `-min-production-ns`. Recommended
+durations carry no guarantee of MSD convergence. Determine the actual diffusion
+regime and fit quality with `pmk msd` after production.
+
+Provide a fixed timestep and use the placeholders in the production block of
+the job template. Earlier equilibration blocks can use their own numeric
+temperatures and run lengths. The template syntax below is compatible with
+GPUMD 4.2.
+
+```text
+potential nep.txt
+time_step 1.0
+ensemble npt_scr 300 300 100 0.0 100.0 1000
+run 2000000
+
+ensemble nvt_bdp target_t target_t 100
+dump_thermo 10
+dump_exyz 1000 1 1
+compute_msd 5 msd-steps group 0 0
+run production-steps
+```
+
+- `production-steps` is the number of NVT MD integration steps,
+  `ceil(t_plan * 1e6 / dt_fs)`.
+- `msd-steps` is GPUMD's `Nc`, the maximum number of correlation samples.
+  It is `floor(0.5 * t_plan * 1e6 / (sample_interval * dt_fs))`. The sample
+  interval is the first argument of the template's `compute_msd`.
+  Omit the entire directive if you only need raw-trajectory `pmk msd`.
+
+Pass `-in run.in` to the predictor to use the job template's timestep and
+sampling interval in the table. Otherwise the table uses the reference run's
+settings and shows a dash when the saved run has no `compute_msd`. The job
+generator uses the actual template settings and reports any recalculation.
+It validates the latest successful prediction record and the complete job
+batch, then creates one directory per target in the invocation directory.
+Existing destinations cause the batch to fail before generation. The original
+template, equilibration runs, `dump_exyz` cadence and optional
+`compute_msd` arguments are preserved.