1.7 Shared inputs, conventions and evidence
1.7.1 Complete shared inputs and analysis templates
1.7.1.1 Input block 1
runs/
si_pbe_ec60_rho480_k8_scf/
input.in
output.out
manifest.json
pseudo.sha256
extract.py
launch.txt
result.csv
si_pbe_ec80_rho640_k8_scf/
...independent files, never overwrite the first point...
1.7.1.2 Input block 2
{
"run_id": "si_pbe_ec60_rho480_k8_scf",
"status": "not_run",
"program": "pw.x",
"qe_version": "record_actual_banner_before_analysis",
"task": "fixed_geometry_scf",
"geometry_source": "case_1_4_with_declared_lattice",
"nat": 2,
"ecutwfc_Ry": 60.0,
"ecutrho_Ry": 480.0,
"k_mesh": [8, 8, 8],
"k_shift": [0, 0, 0],
"functional": "verify_from_output",
"pseudopotentials": [
{"file": "Si.PBE.UPF", "sha256": "replace_with_actual_hash"}
],
"energy_reference_run_ids": [],
"analysis_status": "unverified_template"
}
1.7.1.3 Input block 3
from pathlib import Path
import csv
import json
import re
RY_TO_EV = 13.605693122994
energy_re = re.compile(
r'^\s*!\s+total energy\s*=\s*([-+0-9.EeDd]+)\s+Ry',
re.MULTILINE,
)
rows = []
for folder in sorted(Path('runs').iterdir()):
if not folder.is_dir():
continue
manifest_path = folder / 'manifest.json'
output_path = folder / 'output.out'
if not manifest_path.exists() or not output_path.exists():
raise RuntimeError(f'{folder}: missing manifest or output')
meta = json.loads(manifest_path.read_text())
if meta.get('task') != 'fixed_geometry_scf':
raise RuntimeError(f'{folder}: unsupported task for this extractor')
text = output_path.read_text(errors='replace')
if 'JOB DONE.' not in text:
raise RuntimeError(f'{folder}: no orderly completion marker')
if 'convergence has been achieved' not in text:
raise RuntimeError(f'{folder}: no SCF convergence evidence')
if 'convergence NOT achieved' in text or 'Error in routine' in text:
raise RuntimeError(f'{folder}: failure marker requires manual review')
values = energy_re.findall(text)
if len(values) != 1:
raise RuntimeError(f'{folder}: expected one marked SCF energy, got {len(values)}')
energy_ry = float(values[0].replace('D', 'E').replace('d', 'e'))
nat = int(meta['nat'])
if nat <= 0:
raise RuntimeError(f'{folder}: invalid atom count')
rows.append({
'run_id': meta['run_id'],
'nat': nat,
'ecutwfc_Ry': meta['ecutwfc_Ry'],
'ecutrho_Ry': meta['ecutrho_Ry'],
'energy_Ry_cell': energy_ry,
'energy_eV_atom': energy_ry * RY_TO_EV / nat,
})
if not rows:
raise RuntimeError('No SCF results were accepted')
with open('scf_results.csv', 'w', newline='') as f:
writer = csv.DictWriter(f, fieldnames=list(rows[0]))
writer.writeheader()
writer.writerows(rows)
1.7.2 Conventions and learning evidence
**Execution status
1.7.2.1 How to use the course
Work in dependency order. Cases 1.1–1.4 establish the environment and the silicon reference; later cases state whether they reuse that reference or introduce a new system. Every reported comparison must preserve the Hamiltonian unless changing it is the experiment. A reproducible result consists of the exact input, executable version, pseudopotential hashes, successful output, relevant restart files, extraction script and a convergence argument. A screenshot of a curve is not the underlying evidence.
The executable-specific manual shipped with your installation takes precedence over an old tutorial. The official pages consulted identify version 7.5; their public URLs may change when a later release is published. Archive a copy alongside your own work. Optional packages and compatibility between pseudopotential type, functional, spin treatment and response method must be verified for the particular build. This is a QE-native course: PW, PHonon, PP, turboTDDFPT, CP and PWneb have different input grammars and capabilities.
- **Build the calculation correctly
- **Atoms, molecules and metallic sampling
- **Geometry and mechanics
- **Electronic interpretation
- **Surfaces and defects
- **Lattice response
- **Spectroscopy and method boundaries
- **Dynamics, pathways and production
1.7.2.2 Unit and evidence conventions
1.7.2.3 Build the calculation correctly
1.7.2.4 Appendix A. A fail-closed reproducibility bundle
1.7.2.5 A.1 Directory and naming contract
Use one immutable run directory per scientific state or convergence point. The distinction between a new run and a restart should be visible from its metadata, not inferred from whatever happens to remain in scratch. A useful folder contains the input, standard output, standard error if separate, manifest, pseudopotential checksums, extraction script and a record of the exact launch command. Restart files may be stored elsewhere if their location and retention policy are recorded. Large wavefunctions are not always needed for archival of an energy result, but they are often essential for the next response or post-processing calculation.
See input block 1 above.
A run ID should encode human-meaningful differences while the manifest remains authoritative. Do not depend on rounded directory names for precision. In a relaxation, preserve both the starting and final geometry. In an adsorption or defect energy, link all reference run IDs; if one reference changes, invalidate the derived result until it is recomputed. A convergence plot's caption should identify the observable and the reference setting, not simply say “converged.”
1.7.2.6 A.2 Original minimal manifest
See input block 2 above.
This manifest intentionally contains unresolved provenance fields. Replace them only with observations. Never label a run successful merely because the input was generated. A useful validation state sequence is prepared→started→electronically converged→task converged→analysis checked; not every task visits every state in the same way. A completed NSCF is not a relaxed structure, and a completed relaxation is not a verified phonon minimum.
1.7.2.7 A.3 Original cautious SCF extractor
The following standard-library Python example extracts one fixed-geometry SCF energy per directory. It is unexecuted teaching code. It refuses missing completion/convergence evidence and writes the unit into the column name. It is not a parser for MD, NEB, relaxation or PH outputs. Extend it only after testing on real logs, including deliberately failed logs. A successful parse still does not validate geometry, pseudopotentials, k sampling or scientific convergence.
See input block 3 above.
Deliberately strict parsing prevents a relaxation's many marked energies from being silently reduced to the wrong state. If your version formats messages differently, update the parser with a tested fixture rather than weakening all checks. The nat value here comes from metadata and must be cross-checked against the output header. For a publication workflow, add input hashes, pseudopotential hashes and actual version validation before accepting comparisons.
1.7.2.8 Appendix B. What each executable contributes
- ground-state SCF/NSCF/bands, forces, stress, relaxation and Born–Oppenheimer dynamics within supported methods. Its save directory is the starting point for many dependent programs.
1.7.2.9 Appendix C. Chapter-level assessment and expected evidence
1.7.2.10 C.1 Foundations
Submit two equivalent Si inputs, the pseudopotential passport and one successful SCF log. Explain why changing coordinate units can leave syntax valid while changing the physics. The grader should be able to reconstruct cell volume and valence-electron count without running the code. Evidence is incomplete if the UPF is identified only by a nickname or if the result is an unlabeled screenshot.
1.7.2.11 C.2 Numerical convergence
Submit a matrix separating cutoffs, density grid, k mesh and smearing, with a predeclared target observable. Defend the working choice using one stricter cross-check. State both absolute numerical differences and their physical relevance. Full credit requires recognizing that a stable total energy alone does not certify stress, forces or small energy differences.
1.7.2.12 C.3 Structural response
Submit final geometry with an independent force/stress verification, an EOS residual plot and a finite-strain sign/unit audit. Explain the difference between relaxing atoms at fixed cell and minimizing cell degrees of freedom. If two bulk-modulus routes disagree, diagnose before averaging them; averaging inconsistent calculations is not uncertainty estimation.
1.7.2.13 C.4 Electronic structure
Submit a band/DOS sampling comparison, projection interpretation and one carefully controlled beyond-basic-DFT study. Explain why SOC, DFT+U and hybrids are different changes to the model and why their numerical requirements differ. The report must distinguish a chosen parameter, an initial seed, a constrained quantity and an observed result.
1.7.2.14 C.5 Surfaces and defects
Submit an energy ledger with every reference state identified, plus separate lateral-size, thickness and vacuum tests where applicable. Draw the stoichiometry before writing the energy expression. A charge-density difference must state fragment geometry and grid matching; a charged-defect result must state the electron reservoir and correction convention.
1.7.2.15 C.6 Lattice dynamics
Submit a raw-versus-corrected Γ comparison, one direct-versus-interpolated off-grid frequency comparison and a DOS normalization test. Explain why an imaginary mode cannot simply be removed from a free-energy integral. If claiming stability, state the sampled q coverage and limitations; Γ stability alone is not full Brillouin-zone stability.
1.7.2.16 C.7 Spectroscopy
Submit a method-boundary diagram and one independently converged spectrum. Identify energy units for every broadening parameter, which interactions are included and which are omitted. Show convergence before comparing peak positions to experiment. An empirical shift must be visible in the method statement and cannot be relabeled as an ab initio quasiparticle correction.
1.7.2.17 C.8 Production readiness
Submit a restart equivalence test, an MD time-step/SCF sensitivity test or a NEB image/force convergence report, plus a fixed-work performance comparison. Separate computational completion from scientific completion. A report that lists a blocker precisely is more trustworthy than one that fills missing output with a plausible expected trend.