DFT Research Workflow

Worked Workflows

Worked research case

Silicon Ground-State and Electronic-Structure Workflow

Follow a real COD Silicon structure through model inspection, numerical setup, reference calculations, bands, DOS, plots, and bounded interpretation using separately recorded real QE 7.5 evidence.

Scientific objective and starting object

Follow a real COD Silicon structure through model inspection, numerical setup, a reference state, bands, DOS, plots, and a bounded scientific interpretation.

Current claim boundary: This assembled public case does not establish one continuous historical launcher, transferable cutoff or k mesh, a converged band gap or DOS, structural stability, experimental agreement, or a material-level conclusion.

Work across the interface that fits the task: use a browser for source records and manuals, VESTA or another structure viewer for visual inspection, a text editor for inputs, and the terminal or scheduler for execution. The Software Bridge points users of other codes to their native artifacts.

Open the starting sources

Automated download is optional. First identify what the source represents, what metadata must return with it, and what still requires human inspection.

COD 9013102 Silicon structure

structure

Human action: Open the record in a browser when one is declared, read its metadata and source publication, download the structure, inspect the text, and visualize the cell before conversion.

Exact source identity and case files
  • public CIF SHA-256 cd12420b831cd62227a36865179d12c5eece74e4a40e8d135abc981ced42ca55
  • COD record 9013102
  • Fd-3m space group 227 at symprec=1e-5
  • two-site symmetry-idealized primitive QE geometry

Boundary: The source identity and bounded representation transform do not establish relaxation, stability, model ranking, or numerical suitability.

SSSP v1.3.0 PBE precision Silicon archive member

pseudopotential

Human action: Open the official library or file record, inspect method compatibility and metadata, then acquire and preserve the exact file used.

Exact source identity and case files
  • archive bytes 62963841
  • archive SHA-256 d91db6b4b3788501d535a5b84ebabf3859ea3e3ac6ea154c4be3718da50f0c85
  • archive member ./Si.pbe-n-rrkjus_psl.1.0.0.UPF
  • member bytes 1299382
  • member SHA-256 ae3aefd0811f9499dbc4a72f1f9ae02ef4fc7f3568bf6f559b68668719c69e2b

Boundary: No UPF body is redistributed. Archive and member identity checks do not establish transferability, convergence, or scientific suitability.

Follow the calculation

At each stage, open the real object, inspect what a researcher would actually look at, make the bounded decision, and then use a command where the terminal is the natural interface. Return to an earlier stage whenever a model, method, reference state, target calculation, or validation check fails. This case order is not a universal DFT sequence.

  1. Obtain the source structure

    Open the COD record, read its metadata, download and visually inspect the CIF, then bind the starting crystal to the public source before changing its representation.

    Open the declared database, paper, or teaching record. Read its composition, cell, provenance, revision, conditions, and access boundary before downloading or converting anything. Read the source structure as text and visualize it. Check periodicity, cell choice, occupancies, missing or disordered sites, short contacts, orientation, and whether the object matches the intended material.

    Continue when: Accept the source identity for model construction, or return to the database, paper, Supplementary Information, or another source class.

    Run this step: Inspect the downloaded CIF and its source receipt

    Run from: repository-root

    case_root=examples/cases/silicon-ground-state-electronic-structure
sed -n '1,120p' "$case_root/source/silicon-cod-9013102.cif"
cat "$case_root/source/silicon-cod-9013102.sanitization.json"
cat "$case_root/source/seekpath.json"

    Boundary: This inspection binds the starting record and recorded representation notes. It does not accept the transformed model or launch QE.

    Exact files and recorded evidence for this stage

    Boundary: A database structure is a source record, not yet an accepted DFT model.

  2. Build the computational model

    Compare the conventional COD cell and the declared two-site primitive QE representation visually and numerically before accepting the transformation.

    Open both the source structure and the exact computational cell. Compare composition, atom count, lattice, orientation, periodicity, symmetry, vacuum where relevant, and the mapping between conventional, primitive, or modified cells.

    Continue when: Proceed only when the transformed model still represents the intended physical system and every deliberate modification is recorded.

    Run this step: Compare the source and two-site QE representations

    Run from: repository-root

    case_root=examples/cases/silicon-ground-state-electronic-structure
cat "$case_root/source/seekpath.json"
sed -n '/CELL_PARAMETERS/,/K_POINTS/p' "$case_root/input/scf.in"

    Boundary: The displayed transform is a model choice to inspect and record. It is not a relaxation, stability test, or model ranking.

    Exact files and recorded evidence for this stage

    Boundary: The representation is NOT_RANKED and is not a relaxation, stability result, or proof of method suitability.

  3. Obtain and verify the pseudopotential

    Inspect the SSSP family and potential metadata, then acquire the exact declared archive member without redistributing it.

    Open the library or file record before using a download command. Read the family, exchange–correlation compatibility, valence configuration, relativistic treatment, provenance, and recommended cutoff information. Compare those choices with the physical method and elements in the model; then retain the exact file identity.

    Continue when: Choose a compatible family for a controlled convergence study. A matching hash establishes identity, not suitability.

    Run this step: Download and verify the declared Silicon potential

    Run from: repository-root

    set -euo pipefail
case_root=examples/cases/silicon-ground-state-electronic-structure
prepared=/absolute/path/outside/the/repository/silicon-prepared
test ! -e "$prepared"
python3 -m venv .venv
.venv/bin/pip install -r requirements-practical.txt
.venv/bin/python "$case_root/prepare-replay.py" --download-pseudopotential --output-dir "$prepared"
cat "$prepared/model/si-primitive-qe.inc"
printf '%s  %s\n' 'ae3aefd0811f9499dbc4a72f1f9ae02ef4fc7f3568bf6f559b68668719c69e2b' "$prepared/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF" | sha256sum --check -

    Boundary: The case preparation script fails closed on the recorded CIF, archive, member, model, and pseudopotential identities. A successful identity check does not establish transferability or convergence.

    Exact files and recorded evidence for this stage

    Boundary: Exact bytes establish identity only, not transferability or numerical convergence.

  4. Prepare the Quantum ESPRESSO inputs

    Inspect the recorded calculation types, model, method, cutoffs, sampling, and output locations before execution.

    Read every input that will be submitted, including the structure, calculation type, physical method, numerical settings, prefix, scratch path, and parent artifacts. Identify which choices came from the scientific model, which are numerical parameters to test, and which paths or defaults are site-specific.

    Continue when: Submit only an input whose choices and expected outputs you can explain and audit.

    Run this step: Read the inputs before launching anything

    Run from: repository-root

    case_root=examples/cases/silicon-ground-state-electronic-structure
for input in si-relax.in scf.in bands.in bands.x.in dos-nscf.in dos.x.in; do printf '\n### %s\n' "$input"; sed -n '1,180p' "$case_root/input/$input"; done

    Boundary: Confirm calculation type, geometry, prefix, outdir, pseudo_dir, cutoffs, occupations, and k sampling before execution. These recorded values are not universal recommendations.

    Exact files and recorded evidence for this stage

    Boundary: The stored PBE, cutoff, k-mesh, and sampling settings are case records, not transferable recommendations.

  5. Run the calculation

    Start a new fixed-cell relaxation in an empty external directory. The later reference-geometry and SCF stages continue this fresh lineage; the broad run.sh replay template remains a separate optional case record.

    Read the launcher or job script, working directory, resource request, output paths, and site policy before submission. Watch scheduler state and the complete stdout/stderr without mistaking new text, a queue state, or a termination marker for scientific convergence.

    Continue when: Continue, diagnose, or stop only from the identified job, output, ownership, and failure layer.

    Run this step: Run one fresh fixed-cell relaxation

    Run from: repository-root

    set -euo pipefail
case_root=examples/cases/silicon-ground-state-electronic-structure
prepared=/absolute/path/outside/the/repository/silicon-prepared
runtime=/absolute/path/outside/the/repository/silicon-fresh-reference
QE_PW=${QE_PW:?Set QE_PW to the absolute path to pw.x}
test -x "$QE_PW"; test -s "$prepared/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF"; test ! -e "$runtime"
printf '%s  %s\n' 'ae3aefd0811f9499dbc4a72f1f9ae02ef4fc7f3568bf6f559b68668719c69e2b' "$prepared/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF" | sha256sum --check -
mkdir -p "$runtime/relax/out" "$runtime/relax/pseudo"
cp "$case_root/input/si-relax.in" "$runtime/relax/si-relax.in"; cp "$prepared/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF" "$runtime/relax/pseudo/"
(cd "$runtime/relax" && "$QE_PW" -in si-relax.in > si-relax.out 2> si-relax.err)

    Boundary: This launches only the fresh relaxation. It neither executes the case-wide replay template nor creates bands or DOS evidence.

    Exact files and recorded evidence for this stage

    Boundary: The direct action creates a new relaxation record only. The replay template does not establish the historical launcher or case-wide continuity.

  6. Check program and solver outcomes

    Separate program termination, electronic convergence, ionic evidence, warnings, and artifact presence.

    Open the complete stage, not only a grep result or final line. Read iteration behaviour, warnings, termination context, forces or stress where applicable, and whether the intended artifacts were actually written.

    Continue when: Classify program completion, solver convergence, optimization convergence, and artifact completeness separately.

    Run this step: Inspect the fresh relaxation outcome

    Run from: repository-root

    runtime=/absolute/path/outside/the/repository/silicon-fresh-reference
test -s "$runtime/relax/si-relax.out"; wc -c "$runtime/relax/si-relax.err"
grep -nE 'convergence has been achieved|bfgs converged|End of BFGS Geometry Optimization|JOB DONE|Error in routine' "$runtime/relax/si-relax.out"
sed -n '/Forces acting on atoms/,/Total force/p' "$runtime/relax/si-relax.out"
sed -n '/Begin final coordinates/,/End final coordinates/p' "$runtime/relax/si-relax.out"

    Boundary: Inspect the final complete force block, declared ionic criteria, final coordinates, constraints, stderr, and termination separately. JOB DONE alone is insufficient.

    Exact files and recorded evidence for this stage

    Boundary: JOB DONE and parser success do not establish ionic convergence, target-observable convergence, or scientific support.

  7. Test the required numerical convergence

    Inspect the recorded cutoff/k-mesh matrix without promoting it beyond its declared scope.

    Open the calculated series and its predeclared comparison quantity before reading the pass/fail summary. Look for a stable tail, oscillation, state changes, outliers, and whether only one parameter varied while the physical model stayed fixed.

    Continue when: Accept only the tested observable and tolerance; otherwise extend or redesign the series without erasing the adverse points.

    Silicon total-energy differences relative to the 50 Ry, 10 by 10 by 10 reference across 30, 40, and 50 Ry cutoffs and three k meshes; all three curves decrease toward the reference.
    cutoff and k-mesh energy-difference plot. Read it together with the source table and the stage boundary below. Open the source figure.

    Run this step: Read the stored convergence matrix before choosing settings

    Run from: repository-root

    case_root=examples/cases/silicon-ground-state-electronic-structure
sed -n '1,40p' "$case_root/derived/convergence.csv"
cat "$case_root/source/qe_plan.json"

    Boundary: This is an exploratory total-energy matrix. It supplies no accepted stable-tail result for bands, DOS, phonons, dielectric response, or another target observable.

    Exact files and recorded evidence for this stage
    • derived/convergence.csv — convergence_table; SHA-256 b9ad834441ec6f96c0871cdc6477d6f7d011ec401f3813d47bc01bd269a84c86
    • figures/convergence-matrix.png — cutoff and k-mesh energy-difference plot; SHA-256 1fd386c9b80a8bc76d37ff7e9abb073aae65079f99b2696e01745e4c1d86e984

    Assessment: No accepted observable-specific stable-tail result

    Observable convergence: not tested

    Boundary: The 3 by 3 total-energy matrix is not a transferable cutoff/k-mesh recommendation and does not establish DOS, phonon, dielectric, or band convergence.

  8. Establish the reference geometry

    Inspect the separately recorded fixed-cell relaxation before deciding whether a geometry is an acceptable reference.

    Open the starting and final structures side by side with the final force, stress, constraint, and optimizer records. Look for unexpected reconstruction, broken symmetry, short contacts, cell distortion, or a visually plausible structure that still fails a numerical criterion.

    Continue when: Accept the geometry only within the declared optimization conditions; visual plausibility alone is not convergence or stability.

    Run this step: Create a static input from the inspected final geometry

    Run from: repository-root

    set -euo pipefail
case_root=examples/cases/silicon-ground-state-electronic-structure
runtime=/absolute/path/outside/the/repository/silicon-fresh-reference
relax_output="$runtime/relax/si-relax.out"; reference="$runtime/reference"
test -s "$relax_output"; grep -Fqx '   JOB DONE.' "$relax_output"; grep -F 'bfgs converged' "$relax_output"; test ! -e "$reference"
ACCEPT_RELAX_GEOMETRY=${ACCEPT_RELAX_GEOMETRY:?After inspecting the final force block, criteria, constraints, and coordinates, set ACCEPT_RELAX_GEOMETRY=yes}
test "$ACCEPT_RELAX_GEOMETRY" = yes
mkdir -p "$reference/out" "$reference/pseudo"
awk '/^Begin final coordinates/{seen=1; next} seen && /^ATOMIC_POSITIONS/{print; getline; print; getline; print; exit}' "$relax_output" > "$reference/final-positions.inc"
test "$(wc -l < "$reference/final-positions.inc" | tr -d '[:space:]')" = 3
awk 'FNR==NR {replacement[++n]=$0; next} /^ATOMIC_POSITIONS[[:space:]]/ {for (i=1; i<=n; i++) print replacement[i]; skip=2; next} skip {skip--; next} {print}' "$reference/final-positions.inc" "$case_root/input/scf.in" > "$reference/static-scf.in"
cp "$runtime/relax/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF" "$reference/pseudo/"
cat "$reference/final-positions.inc"
diff -u "$case_root/input/scf.in" "$reference/static-scf.in" || test "$?" = 1

    Boundary: The direct transformation copies only the final two-site ATOMIC_POSITIONS block into a new static template and leaves the fixed cell unchanged. Inspect the displayed block and diff before proceeding; this does not establish scientific acceptance or historical stored lineage.

    Exact files and recorded evidence for this stage

    Boundary: The public bundle does not establish relax-output to static-SCF input lineage, accepted ionic convergence, stability, or the lowest relevant structure.

  9. Calculate the reference SCF state

    Inspect the electronic reference calculation independently of relaxation and downstream observables.

    Open the state, occupations, spin treatment, energy, residual history, warnings, and parent geometry together. Look for slow or oscillatory convergence, state changes, inconsistent occupations, and whether the output belongs to the accepted model.

    Continue when: Use the state as a parent only when the electronic criterion and reference-state logic are both adequate.

    Run this step: Run and inspect the new static SCF

    Run from: new external reference directory

    set -euo pipefail
runtime=/absolute/path/outside/the/repository/silicon-fresh-reference
QE_PW=${QE_PW:?Set QE_PW to the absolute path to pw.x}
test -x "$QE_PW"; test -s "$runtime/reference/static-scf.in"
(cd "$runtime/reference" && "$QE_PW" -in static-scf.in > static-scf.out 2> static-scf.err)
grep -Fqx '   JOB DONE.' "$runtime/reference/static-scf.out"
grep -F 'convergence has been achieved' "$runtime/reference/static-scf.out"
wc -c "$runtime/reference/static-scf.err"; test -d "$runtime/reference/out/si_cod9013102.save"

    Boundary: These checks cover this process, its reported electronic convergence, stderr size, and the expected save tree only. Geometry acceptance, numerical convergence, observable convergence, and scientific support remain separate.

    Exact files and recorded evidence for this stage

    Boundary: Electronic convergence in the named SCF outputs does not establish relax-to-SCF lineage, target-observable convergence, or scientific acceptance.

  10. Calculate bands and DOS

    Follow the line-path, nominal-grid, and uniform-mesh DOS branches as distinct target calculations.

    Open the parent SCF/NSCF state, path or full-zone sampling record, energy reference, number of bands, and the resulting bands or DOS data. Check path labels, Fermi reference, crossings or gaps, full-zone limitations, DOS normalization, broadening, warnings, and sampling density.

    Continue when: Use only the observable supported by the sampled domain and its own convergence evidence; a high-symmetry path is not a full-zone proof.

    Run this step: Inspect the stored bands and DOS as separate evidence

    Run from: repository-root

    case_root=examples/cases/silicon-ground-state-electronic-structure
for output in bands-pw.out bandsx-main.out dos-nscf.out dosx.out; do test -s "$case_root/output/$output"; grep -nE 'JOB DONE|convergence has been achieved|c_bands|Error in routine' "$case_root/output/$output" || true; done
sed -n '1,20p' "$case_root/derived/band-path.csv"
sed -n '1,20p' "$case_root/derived/dos.csv"
printf '%s\n' 'The fresh static SCF is not the parent of these stored files. Prepare new compatible bands and uniform-NSCF/DOS inputs against the fresh prefix/outdir/save tree before any fresh downstream run.'

    Boundary: This is stored-evidence inspection only. No fresh bands or DOS command is supplied, and the older data must not be relabelled as descendants of the new static SCF.

    Exact files and recorded evidence for this stage

    Observable convergence: not tested

    Boundary: The line path retains solver warnings, and the nominal 8x8x8 route is a 260-point time-reversal-reduced sample. Neither branch establishes a converged fundamental gap or DOS. The fresh route stops after static SCF until compatible downstream inputs are prepared and reviewed.

  11. Rebuild tables and plots

    Open the public teaching figures beside their source tables, inspect the axes, references, warnings, and visible trends, then regenerate them from the stored raw-output record if needed.

    Open each real figure beside its underlying calculated values. Check axes, units, reference zeros, calculated points, fits or smoothing, warnings, and features that change with representation.

    Continue when: Retain figures that expose the scientific evidence and its limitations; a regenerated image is not an independently validated result.

    Eight stored Silicon line-path bands plotted against cumulative path coordinate, with a dashed zero-energy reference and the solver-warning boundary stated in the title.
    line-path band plot with solver warning retained. Read it together with the source table and the stage boundary below. Open the source figure.
    Scatter plot of Silicon band 4 occupied and band 5 empty eigenvalues over the 260-point time-reversal-reduced sample from the nominal 8 by 8 by 8 grid; the sampled bands remain separated.
    full-zone occupied and empty band samples. Read it together with the source table and the stage boundary below. Open the source figure.
    Stored Silicon 12 by 12 by 12 tetrahedron density of states versus energy relative to the Fermi level, showing a zero-DOS interval near the reference.
    tetrahedron density-of-states plot. Read it together with the source table and the stage boundary below. Open the source figure.

    Run this step: Inspect the stored tables behind the teaching figures

    Run from: repository-root

    case_root=examples/cases/silicon-ground-state-electronic-structure
sed -n '1,30p' "$case_root/derived/convergence.csv"
sed -n '1,20p' "$case_root/derived/band-path.csv"
sed -n '1,20p' "$case_root/derived/dos.csv"

    Boundary: These tables feed the displayed stored-evidence figures. They are not outputs of the new static SCF and do not establish target-observable convergence or a scientific claim.

    Exact files and recorded evidence for this stage
    • figures/band-path.png — line-path band plot with solver warning retained; SHA-256 50108e1b6c391380d85f35bc8fae59fa747fee1f053ba4ffdfadbda62e1cdc0f
    • figures/full-zone-bands.png — full-zone occupied and empty band samples; SHA-256 b1fffd7acbe40d02c51b6ba3fe21489766aa1e9d130d1951995a7ceb955c29dd
    • figures/dos.png — tetrahedron density-of-states plot; SHA-256 33f2d775d055c51805eae489a0a1ff3f816e1059760ca42aeded51b1fb965494

    Boundary: A reconstructed figure verifies the stored parser path, not a fresh execution or an independently converged observable.

  12. Interpret within the evidence boundary

    Read the real figures, parsed samples, raw anomalies, warnings, sampling policy, relevant literature, and explicit non-claims together.

    Compare the calculated object with independent calculations or measurements only after matching structure, state, conditions, and observable definition. Look for contradictions, method sensitivity, missing alternatives, and conclusions controlled by an unconverged or untested stage.

    Continue when: State the narrowest supported claim and the evidence that would change it.

    Run this step: Read the stored result boundaries before writing a conclusion

    Run from: repository-root

    case_root=examples/cases/silicon-ground-state-electronic-structure
cat "$case_root/derived/observables.json"
cat "$case_root/derived/full-zone-status.json"

    Boundary: Retain every warning and NOT TESTED field. The next defensible action is to run the missing observable-specific convergence or physics test, not to strengthen the claim from the existing plots.

    Exact files and recorded evidence for this stage

    Observable convergence: not tested

    Boundary: The evidence does not support a converged gap, DOS, stability result, experimental agreement, or material-level conclusion.

  13. Preserve the reproducible record

    Keep the human decision record, source/browser receipt, visual inspection notes, inputs, outputs, figures, hashes, parsers, environment, routes, and non-claims together.

    Collect the human decision history together with sources, inputs, outputs, tables, figures, warnings, failed attempts, and software context. Confirm that another researcher can identify what was done, what was viewed, what was excluded, and which steps can or cannot be reconstructed.

    Continue when: Freeze a versioned study object while keeping hashes and manifests as supporting identity evidence rather than the scientific narrative.

    Run this step: Write a bounded record beside the fresh calculation

    Run from: repository-root

    set -euo pipefail
runtime=/absolute/path/outside/the/repository/silicon-fresh-reference
record="$runtime/STUDY-NOTES.txt"; sums="$runtime/SELECTED-SHA256SUMS"
test -s "$runtime/relax/si-relax.in"; test -s "$runtime/relax/si-relax.out"; test -s "$runtime/reference/static-scf.in"; test -s "$runtime/reference/static-scf.out"; test ! -e "$record"; test ! -e "$sums"
printf '%s\n' 'Question: inspect a fresh fixed-cell Si relaxation and its descendant static SCF.' 'Decision: retain the final geometry only after human force, criteria, constraint, and coordinate inspection.' 'Boundary: this fresh route stops after static SCF; no fresh bands or DOS were prepared or run.' > "$record"
sha256sum -- "$runtime/relax/si-relax.in" "$runtime/relax/si-relax.out" "$runtime/reference/final-positions.inc" "$runtime/reference/static-scf.in" "$runtime/reference/static-scf.out" > "$sums"
cat "$record"; cat "$sums"

    Boundary: This preserves the question, decision, explicit stopping point, selected inputs/outputs, geometry handoff, and byte identities. It is not a universal package schema, a regeneration claim, or scientific validation.

    Exact files and recorded evidence for this stage
    • source/output-excerpt.txt — deterministic public output excerpt rendered by the Worked Workflow; SHA-256 26e8498be220c2c64e6c7996a47628f3f60a1cd9f3733e14c9da6331cbc3c1e6

    Boundary: The public record preserves assembled evidence and claim boundaries, not one historical launcher, case-wide shell exits, cross-route save trees, or the private Maxwell replay.

Reproducibility appendix

Open this only when you need the exact published case record, hashes, historical commands, or replay boundary.

How to use this workflow

Evidence boundary
Program completion, SCF convergence, ionic convergence, expected-artifact presence, target-observable convergence, and scientific support are separate decisions.
Continuity boundary
The public case is an assembled set of hash-bound, separately recorded real QE 7.5 stages. It does not claim one continuous historical launcher, case-wide shell-exit transcript, execution interval, or cross-route save-tree ancestry.
Claim boundary
This assembled public case does not establish one continuous historical launcher, transferable cutoff or k mesh, a converged band gap or DOS, structural stability, experimental agreement, or a material-level conclusion.

Execution contexts

Local interactive execution
Use when: Only when local and site policy permits calculation on the current machine and sufficient resources are available.. Boundary: Never assume that an SSH login shell or cluster login node is a permitted compute context.
Slurm allocation or batch execution
Use when: Only inside an active compute allocation or a site-approved batch job.. Boundary: Use the site's documented launcher inside the allocation. Translate the displayed direct pw.x invocation into the reviewed site command; neither a shell variable nor an SSH login grants permission to compute on a login node.

Inspect stored evidence or run a fresh calculation

Inspect stored evidence

This track reads the published, hash-bound case records and does not launch a new DFT calculation.

Reconstruct the stored public evidence

case_root=examples/cases/silicon-ground-state-electronic-structure
(cd "$case_root" && bash replay-derived.sh)
(cd "$case_root" && bash extract.sh)
(cd "$case_root" && bash check.sh)

Output policy: Rebuild only the case-derived tables, figures, manifest relationships, and isolated-copy checks from committed source/input/output records.

Audit

  • Confirm that parsing starts from the declared stored raw outputs.
  • Retain solver warnings and time-reversal-reduced sampling labels.
  • Check artifact relationships and hashes without treating them as observable convergence.

Parse and plot boundary: These commands parse and plot the stored public record; they do not prove that a new DFT calculation ran.

Boundary: Stored reconstruction supports parser and artifact lineage only, not historical continuity, fresh execution, target-observable convergence, or scientific acceptance.

Run a fresh calculation

This track launches software in a caller-controlled runtime directory. Its new outputs do not rewrite the historical records published in the case bundle.

Run a fresh relaxation and static SCF, then stop

set -euo pipefail
case_root=examples/cases/silicon-ground-state-electronic-structure
prepared=/absolute/path/outside/the/repository/silicon-prepared
runtime=/absolute/path/outside/the/repository/silicon-fresh-reference
QE_PW=${QE_PW:?Set QE_PW to the absolute path to pw.x}
test -x "$QE_PW"; test -s "$prepared/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF"; test ! -e "$runtime"
printf '%s  %s\n' 'ae3aefd0811f9499dbc4a72f1f9ae02ef4fc7f3568bf6f559b68668719c69e2b' "$prepared/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF" | sha256sum --check -
mkdir -p "$runtime/relax/out" "$runtime/relax/pseudo"
cp "$case_root/input/si-relax.in" "$runtime/relax/si-relax.in"; cp "$prepared/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF" "$runtime/relax/pseudo/"
(cd "$runtime/relax" && "$QE_PW" -in si-relax.in > si-relax.out 2> si-relax.err)
grep -Fqx '   JOB DONE.' "$runtime/relax/si-relax.out"; grep -F 'bfgs converged' "$runtime/relax/si-relax.out"
awk '/Forces acting on atoms/{block=$0 ORS; inside=1; next} inside{block=block $0 ORS} inside && /Total force =/{last=block; inside=0} END{if (last == "") exit 1; printf "%s", last}' "$runtime/relax/si-relax.out"
sed -n '/Begin final coordinates/,/End final coordinates/p' "$runtime/relax/si-relax.out"
ACCEPT_RELAX_GEOMETRY=${ACCEPT_RELAX_GEOMETRY:?After inspecting the final force block, criteria, constraints, and coordinates, set ACCEPT_RELAX_GEOMETRY=yes}
test "$ACCEPT_RELAX_GEOMETRY" = yes
mkdir -p "$runtime/reference/out" "$runtime/reference/pseudo"
awk '/^Begin final coordinates/{seen=1; next} seen && /^ATOMIC_POSITIONS/{print; getline; print; getline; print; exit}' "$runtime/relax/si-relax.out" > "$runtime/reference/final-positions.inc"
test "$(wc -l < "$runtime/reference/final-positions.inc" | tr -d '[:space:]')" = 3
awk 'FNR==NR {replacement[++n]=$0; next} /^ATOMIC_POSITIONS[[:space:]]/ {for (i=1; i<=n; i++) print replacement[i]; skip=2; next} skip {skip--; next} {print}' "$runtime/reference/final-positions.inc" "$case_root/input/scf.in" > "$runtime/reference/static-scf.in"
cp "$prepared/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF" "$runtime/reference/pseudo/"
diff -u "$case_root/input/scf.in" "$runtime/reference/static-scf.in" || test "$?" = 1
(cd "$runtime/reference" && "$QE_PW" -in static-scf.in > static-scf.out 2> static-scf.err)
grep -Fqx '   JOB DONE.' "$runtime/reference/static-scf.out"; grep -F 'convergence has been achieved' "$runtime/reference/static-scf.out"; test -d "$runtime/reference/out/si_cod9013102.save"
printf '%s\n' 'STOP: no fresh bands or DOS calculation is supplied here; inspect the stored branches separately.'

Output policy: Use one new caller-selected external directory for the fresh relax-to-static-SCF lineage; never overwrite committed evidence or reuse the older bands/DOS files as descendants.

Audit

  • Record the shell exit and inspect every stdout and stderr independently.
  • Check program termination separately from electronic SCF convergence.
  • For relaxation, inspect ionic criteria, final coordinates, forces, and constraints rather than JOB DONE alone.
  • Confirm every expected downstream artifact before parsing or interpretation.
  • Test the selected target observable with its own numerical convergence protocol.
  • State the scientific claim only after the evidence supports it.

Parse and plot boundary: No fresh bands or DOS parsing is attempted. The public stored bands, DOS, tables, and plots remain a separate historical evidence set.

Boundary: This present-day route creates a direct fresh relaxation-to-static-SCF lineage and stops there. The new static SCF is not the parent of the stored bands or DOS; a future compatible bands/NSCF/DOS branch must inherit this new prefix, outdir, and save tree and has not been prepared or run here.

Reproduce the exact published evidence

Use this section after understanding the scientific route. It retrieves the exact reviewed checkout and keeps new runtime evidence separate from the published case.

Repository: https://github.com/Maxwell3919/DFT-Research-Workflow.git

Source revision: 2ba561ac0937a938764bc283b25edb3a4700ece0

Working directory: repository-root

Case root: examples/cases/silicon-ground-state-electronic-structure

git clone https://github.com/Maxwell3919/DFT-Research-Workflow.git
cd DFT-Research-Workflow
git checkout --detach 2ba561ac0937a938764bc283b25edb3a4700ece0
test "$(git rev-parse HEAD)" = "2ba561ac0937a938764bc283b25edb3a4700ece0"
case_root=examples/cases/silicon-ground-state-electronic-structure

Open the Silicon source record before preparing a calculation

Run from: repository-root

case_root=examples/cases/silicon-ground-state-electronic-structure
sed -n '1,120p' "$case_root/source/silicon-cod-9013102.cif"
cat "$case_root/source/silicon-cod-9013102.sanitization.json"
cat "$case_root/source/pseudopotentials.json"

Boundary: This action exposes the downloaded structure, its representation receipt, and the pseudopotential identity record. It does not prepare or launch QE, accept the model, or establish numerical suitability.

Exact case bundle files

This page is a reader-facing entry point for the case directory. Inspect the files themselves for the exact source record, input, command scope, raw or sanitized output, checks, extraction, parser, derived data, and figure lineage.

Recorded commands and outputs

These records distinguish captured output, replay instructions, and unavailable historical shell details. Records may belong to different declared routes; adjacency on this page does not establish one continuous run. An exit is shown only when the manifest scopes where that value came from, and a QE terminal marker is not silently converted into a shell exit code.

Case-wide timing boundary: No case-wide start, completion, or exit is claimed. 2026-08-05T00:06:24+08:00 is only the latest QE-printed termination among separately recorded artifacts.

Assembled stored real QE 7.5 stages

Route ID: assembled-stored-output-set

Route timing: 2026-08-04T20:44:32+08:00 to 2026-08-05T00:06:24+08:00. Earliest and latest QE-printed timestamps across the assembled artifact set only; this is not a continuous case run or publication-completion window.

Exact historical command: Not captured for the historical stages. run.sh contains a present-day replay template, not the original launcher.

Exact historical exit: Shell exit codes were not retained. Each declared stdout has one QE JOB DONE marker; that marker is reported separately.

  • The cutoff, relax/restart, electronic, DOS, Gamma-response, and nominal-grid outputs were recorded as separate stage groups.
  • Inputs and outputs are hash-bound; cross-route scheduler records and save-tree payloads are absent.
  • No single run.sh invocation is claimed for the historical artifact set.

Boundary: Assembled real stages do not establish one continuous historical execution, observable convergence, or a material-level scientific claim.

Stored nominal-8x8x8 bands route

Route ID: stored-260-point-time-reversal-reduced-bands

Route timing: 2026-08-04T22:26:20+08:00 to 2026-08-04T22:27:05+08:00. QE-printed timestamps for output/full-zone/scf.out, bands-pw.out, and bandsx.out only.

Exact historical command: Historical shell launcher not captured; replay commands and ordering are declared in run.sh.

Exact historical exit: Shell exit codes not captured; all three stdout files print JOB DONE and the three committed stderr files are empty.

  • input/full-zone/scf.in -> output/full-zone/scf.out
  • input/full-zone/bands.in declares the same prefix/outdir -> output/full-zone/bands-pw.out
  • input/full-zone/bands.x.in -> output/full-zone/bandsx.out -> output/full-zone/si-fullzone.bands.dat
  • nosym=.true. with no noinv=.true. retained time-reversal equivalence, producing 260 printed k points from the nominal 8x8x8 grid.

Boundary: The save-tree payload is not published; the hash-bound input/output declarations support stage ancestry, not a converged fundamental gap.

Optional native replay template

Route ID: native-replay-template

Route timing: start not recorded to completion not recorded. Not executed by this provenance edit; no Maxwell replay result is recorded.

Exact historical command: The caller-facing invocation and program order are in run.sh.

Exact historical exit: Not recorded for the updated template.

  • prepare-replay.py binds the exact public CIF to the declared two-site primitive geometry and obtains only the pinned SSSP archive member after archive/member checks.
  • A caller-supplied UPF must match the declared SHA-256 before any QE executable starts.
  • run.sh creates a new caller-selected runtime directory and never supplies the missing historical save trees.

Boundary: The pinned archive/member route establishes exact replay-byte identity only. It does not establish pseudopotential transferability, numerical convergence, physical validity, or a material-level claim.

stored real QE stage set · exit not recorded

Route: assembled-stored-output-set

Record kind: recorded-output-only

Exact historical shell commands and launcher were not captured; inspect the hash-bound inputs and stdout records.

Evidence scope: Real QE 7.5 stdout is present for the declared stages; one historical continuous run is not claimed.

Exit scope: Shell exits not recorded; QE JOB DONE markers remain program-output evidence only.

Inputs: input/*.in -> input/full-zone/*.in

Outputs: output/*.out -> output/full-zone/*.out -> output/full-zone/si-fullzone.bands.dat

native replay template · exit not recorded

Route: native-replay-template

Record kind: replay-command-not-executed-by-this-edit

PSEUDO_DIR=/absolute/path/to/pseudo QE_PW=pw.x QE_BANDS=bands.x QE_DOS=dos.x QE_PH=ph.x QE_LAUNCHER='mpirun -np 4' bash run.sh

Evidence scope: Exact current replay invocation; not an assertion about the historical launcher.

Exit scope: No fresh replay exit is recorded.

Inputs: prepare-replay.py -> run.sh -> input/*.in -> input/full-zone/*.in -> source/pseudopotentials.json

Outputs: caller-selected external preparation and runtime directories (not committed)

rebuild derived artifacts from stored outputs · exit not recorded

Route: stored-output-postprocess

Record kind: available-command-not-rerun-by-this-edit

bash replay-derived.sh

Evidence scope: Operates on stored outputs only; it does not launch QE.

Exit scope: No fresh exit is recorded pending the later replay follow-up.

Declared parents: source/ -> input/ -> output/

Outputs: derived/ -> figures/ -> manifest.json

isolated case check · exit not recorded

Route: stored-output-postprocess

Record kind: isolated-copy-check-command-not-rerun-by-this-edit

bash check.sh

Evidence scope: check.sh copies the case to a temporary directory before parse.py materializes files.

Exit scope: No fresh exit is recorded pending the later replay follow-up.

Inputs: check.sh -> parse.py -> source/ -> input/ -> output/

Source-bound excerpt: source/output-excerpt.txt

SCF: Quantum ESPRESSO PWSCF v.7.5; 29 irreducible k points; 4 Kohn-Sham states.
SCF: convergence has been achieved in 10 iterations; JOB DONE.
bands: Quantum ESPRESSO PWSCF v.7.5; 260 time-reversal-reduced k points from a nominal 8x8x8 grid; 8 Kohn-Sham states.
bands: End of band structure calculation; JOB DONE.
bands.x: Quantum ESPRESSO BANDS v.7.5; JOB DONE.
All three captured stderr streams were empty.

Complete artifact appendix

Stage-scoped lists above identify only the artifacts critical for reading each stage. This appendix retains every artifact declared by the case manifest, including supporting inputs, outputs, checks, tables, and figures.

Show every manifest-bound artifact and checksum
  • source/output-excerpt.txt — deterministic public output excerpt rendered by the Worked Workflow; SHA-256 26e8498be220c2c64e6c7996a47628f3f60a1cd9f3733e14c9da6331cbc3c1e6
  • derived/convergence.csv — convergence_table; SHA-256 b9ad834441ec6f96c0871cdc6477d6f7d011ec401f3813d47bc01bd269a84c86
  • derived/band-path.csv — band_path_table; SHA-256 5d140d9e2cf5ca039cd1d13e5dfd157aeabc2e969ca89f61fcefbc4e745a6841
  • derived/full-zone-bands.csv — time_reversal_reduced_zone_table; SHA-256 5f181b3b664353a5a46bdd71a0841975f623d7eaf26aa21260266f90d65b53b9
  • derived/dos.csv — dos_table; SHA-256 b2bbe7e1f52bfb71a212a8ae3682d143a9faa00adfb1a68cf849f0cfdd94b941
  • derived/observables.json — observable_report; SHA-256 8f27a4cd306332ca21e9f16d89dc58b186665f759008c1de15e2e94cdcc6a5c6
  • derived/full-zone-status.json — time_reversal_reduced_zone_result; SHA-256 4bafa7f633726f42f333d723e483e0d025c389c8cfece082f9f9fcd70fe5ca1a
  • output/full-zone/scf.out — full_zone_scf; SHA-256 e7e5d0a752d0b5940c04eac630dc925e4a98c7537010d3d2899a62e84f9797ef
  • output/full-zone/bands-pw.out — time_reversal_reduced_bands_pw; SHA-256 3c25f43a5e4eaa78e35eff57a300ab3c51bd8bb974e34e30c2a20375aad2da5b
  • output/full-zone/bandsx.out — time_reversal_reduced_bandsx; SHA-256 9d4deac9e49b3e33ff3e8bdcdcb4139122074217fd721de134ec1539039cb6e6
  • output/full-zone/si-fullzone.bands.dat — time_reversal_reduced_band_data; SHA-256 46fc87a9741eb6abb6ec527e0374878b2efef191414027dab3d54b070b33fabc
  • figures/convergence-matrix.png — cutoff and k-mesh energy-difference plot; SHA-256 1fd386c9b80a8bc76d37ff7e9abb073aae65079f99b2696e01745e4c1d86e984
  • figures/band-path.png — line-path band plot with solver warning retained; SHA-256 50108e1b6c391380d85f35bc8fae59fa747fee1f053ba4ffdfadbda62e1cdc0f
  • figures/full-zone-bands.png — full-zone occupied and empty band samples; SHA-256 b1fffd7acbe40d02c51b6ba3fe21489766aa1e9d130d1951995a7ceb955c29dd
  • figures/dos.png — tetrahedron density-of-states plot; SHA-256 33f2d775d055c51805eae489a0a1ff3f816e1059760ca42aeded51b1fb965494
  • figures/gamma-response.png — Gamma-point phonon and electronic-response plot; SHA-256 10f3f85fb24856d21ed404bd648b4d3b95d32bb6b12292eecd55319e10bb5257

Evidence boundary

Evidence class: real-execution.

  • Quantum ESPRESSO 7.5 (pw.x, bands.x, dos.x, ph.x recorded output)
  • Python 3.12.11 (stored-output parser)
  • pymatgen-core 2026.7.31 (manual CIF parsing and occupancy checks)
  • spglib 2.7.0 (manual symmetry and primitive-cell checks)

Execution host: Recorded public QE output; no host-private path retained.

Inputs and identity
Recorded as passed within the stated scope. Stored source/input/output identities and generated artifact relationships carry the existing case PASS; the manual preparation source is hash-bound but this parser does not download or redistribute the UPF.
Program completion
Recorded as passed within the stated scope. Each declared stored QE 7.5 stdout has one JOB DONE marker; shell exit codes remain separately unrecorded.
Electronic solver and ionic or structural checks
Warnings or limitations are retained. SCF/relax/restart and Gamma response markers are present, but line-path bands retain c_bands eigenvalue-not-converged warnings
Artifacts and stage ancestry
Recorded as passed within the stated scope. The nominal 8x8x8 SCF, bands, bands.x and 260-point time-reversal-reduced eight-band data are hash-bound and directly parsed.
Observable convergence
Not established by this case. the 3 by 3 total-energy matrix has no accepted observable-specific stable-tail protocol; no DOS, phonon, dielectric, or band convergence evidence
Claim boundary
No material-level claim is made. no fundamental gap, physical stability, dielectric, phonon, or experimental-material conclusion is claimed

What this case supports

  • An assembled set of hash-bound, separately recorded real QE 7.5 stage inputs, outputs, and derived plots.
  • Direct parsing of the recorded 260-point, eight-band time-reversal-reduced sample from the nominal 8x8x8 grid.
  • A fail-closed manual bridge from the exact public COD CIF to the declared two-site QE geometry and exact-hash SSSP archive member.

What this case does not support

  • One continuous historical launcher, shell-exit transcript, case-wide execution interval, or cross-route save-tree ancestry.
  • Pseudopotential transferability or scientific suitability beyond the exact archive/member identity checks.
  • A transferable cutoff or k-mesh recommendation.
  • A converged band gap, DOS, phonon, dielectric, structural-stability, physical-validity, or experimental-material conclusion.

Program completion, solver convergence, observable convergence, and physical interpretation are separate gates. The case check and parser report their tested scope; an absent gate is not implied by a passing earlier one.

Research-workflow context

Use this case together with Research Workflow for the A–E scientific map. The case illustrates one bounded case and its declared routes; it does not prescribe parameters or establish a general material conclusion.

Return to Worked Workflows