QEGuard Brings Guarded Precedent Reuse to Quantum ESPRESSO Simulation Records

Computational materials scientists spend an enormous amount of time configuring density functional theory calculations, and much of that work consists of rediscovering parameter choices that colleagues or their own past runs have already established. A new open-source Python package called QEGuard, described in the journal SoftwareX, aims to make this everyday practice of reusing prior simulation settings both systematic and safe. Developed by Hyunseob Kim, Husung Kim, Sunggeun Han, and Jeongcheol Lee, the software treats completed Quantum ESPRESSO calculations as evidence that must pass explicit eligibility checks before any of their parameters can inform a new simulation.

The central insight behind QEGuard is that a previous calculation can be relevant without being transferable. Two records may be similar enough to invite comparison, yet differ in conditions that determine whether specific parameters can actually be reused. Switching from a primitive to a conventional unit cell, for example, makes direct reuse of k-point settings inappropriate, because the same reciprocal-space resolution is expressed through different grid indices. A density-of-states calculation may contain occupation settings unsuitable for a baseline self-consistent-field run, and a non-converged calculation can remain structurally informative while being entirely unsuitable as a source of defaults. In current practice, researchers embed these judgments in implicit rules, such as borrowing from the most similar successful run, and such rules conflate decisions with fundamentally different transfer semantics.

QEGuard implements a staged architecture that separates record relevance from transfer eligibility. First, a parser converts Quantum ESPRESSO stdout and XML outputs into canonical JSON-compatible records containing structural descriptors, calculation settings, workflow context, result summaries, and quality signals. The parser extracts cutoff values, k-point grids, occupation and smearing settings, total and Fermi energies, band-gap metadata, cell vectors, atomic positions, and symmetry descriptors, using the Atomic Simulation Environment for structure handling and spglib for symmetry analysis. Second, a retrieval layer stores these records in a SQLite-backed database and ranks candidate precedents using a structure-aware score that combines formula agreement, cell-scale geometry, local-environment proxies, symmetry signals, and compact fingerprints.

That retrieval score proved remarkably effective in benchmarking. Across 3352 queries drawn from 5777 JARVIS-derived records, the structure-aware score achieved 83.7 percent Top-1 success, meaning it recovered the intended source record as the highest-ranked candidate, compared with 48.3 percent for formula-only retrieval, 76.1 percent for formula-gated pymatgen StructureMatcher, and 78.4 percent for SOAP descriptors. The authors stress that this score is designed for candidate selection within their parsed-record setting rather than as a universal crystal-similarity metric, and its role is simply to supply relevant precedents to the guarded transfer stage.

The transfer-decision component is where QEGuard departs most clearly from conventional practice. It evaluates each retrieved candidate against the target calculation context using method compatibility, scientific-objective agreement, accuracy-profile sufficiency, candidate quality, representation relationships, workflow-context matching, and parameter-level transfer rules. The output is a structured decision record specifying which parameters can be proposed for reuse, which are excluded, and the reason for each exclusion. Three outcomes are possible: a full transfer when all checks pass, a partial transfer applying only eligible fields, or an abstention that returns no precedent-derived updates when no candidate qualifies. Notably, abstention is treated as a first-class policy outcome rather than a retrieval failure.

When a cell representation changes, the package can derive an initial k-point mesh by preserving reciprocal-space resolution rather than blindly copying cell-index grids. In validation tests, directly reusing a conventional-cell 7x7x7 mesh for silicon in its primitive cell produced a 4.67 meV/atom energy difference, whereas the resolution-preserving approach generated a 12x12x12 mesh with a difference of only 0.023 meV/atom. For molybdenum disulfide, mapping a 6x6x1 primitive-cell mesh to a 3x3x1 supercell mesh reduced observed wall time by a factor of 1.84, and for anatase titanium dioxide the mapped mesh reduced wall time by a factor of 2.65 while matching an independent reference to within 0.000295 meV/atom. These derived meshes remain starting values subject to target-specific convergence validation.

The negative-control experiments illustrate why such safeguards matter. Across nine deliberately incompatible cases, unguarded top-ranked reuse transferred at least one ineligible field in every case, propagating 27 of 39 predefined ineligible parameters. QEGuard transferred none of them while retaining all nine predefined eligible fields. One striking negative control involved a self-consistent-field calculation that printed JOB DONE and returned process code zero despite reporting non-convergence; a process-completion criterion would have exposed its parameters for reuse, but QEGuard rejected the record based on the parsed convergence state. Another showed that screening settings with errors of 20.22 and 74.64 meV/atom were being applied to a 1 meV/atom accuracy target, a mismatch the software correctly refused.

Controlled evaluation reinforced these findings. Across 74 deterministic policy cases spanning the titanium dioxide and silica/zirconia families, covering compatible precedents, polymorph discrimination, workflow-conditioned ranking, representation changes, quality criteria, and compatibility metadata, QEGuard achieved perfect Top-1 source recovery, correct transfer, and zero unsafe transfer. A titanium dioxide case further demonstrated that parameter adequacy depends on the scientific objective: at a 37.5/300 Ry cutoff the energy error reached 74.64 meV/atom, yet the maximum force-component error of 0.00222 eV/Å comfortably satisfied the force criterion, showing that the same settings can be inadequate for one property and acceptable for another.

QEGuard complements rather than competes with existing infrastructure. Workflow systems such as AiiDA, FireWorks, and Atomate provide provenance capture and high-throughput execution, while Materials Cloud and NOMAD support dissemination and reuse of simulation data, but none addresses the narrower question of which portion of an available prior record can responsibly inform a new calculation. Similarly, community parameter templates offer general defaults, whereas QEGuard evaluates whether a provenance-bearing local record can supply context-specific starting parameters for a declared objective and accuracy requirement. The package occupies the gap between record availability and authoring-time parameter reuse.

The software is released under the MIT license, version 0.1.0 is available on GitHub, and the repository includes reproducible examples, schema documentation, benchmark data, and resources for reproducing the numerical-validation calculations. Although the current implementation is specific to Quantum ESPRESSO, the staged interface is designed to support other density functional theory codes through additional parsers, parameter mappings, and code-specific validation of transfer rules. The authors argue that negative decisions are themselves valuable output: exclusion can be as informative as transfer, and structured decision records allow downstream tools to retain both proposed fields and the reasons for withholding others, making parameter reuse explicit, inspectable, and reproducible.

Subject of Research: Guarded reuse of parameters from prior Quantum ESPRESSO density functional theory simulation records

Article Title: QEGuard: A python package for guarded precedent reuse in Quantum ESPRESSO simulation records

Article References: Kim, H., Kim, H., Han, S., & Lee, J. (2026). QEGuard: A python package for guarded precedent reuse in Quantum ESPRESSO simulation records. SoftwareX, 36, Article 103017. https://doi.org/10.1016/j.softx.2026.103017

Image Credits: AI Generated

DOI: 10.1016/j.softx.2026.103017

Keywords: QEGuard, Quantum ESPRESSO, density functional theory, computational materials science, parameter reuse, k-point mesh, simulation records, retrieval, SQLite, pseudopotentials, workflow systems, open-source software