Example scripts and generated outputs¶

The repository keeps runnable example inputs under examples/. Local runs still write .out, .system, .molden, .traj, .cube, .png, .csv, or citation files next to the script that produced them; those ad hoc files are local working products and should stay out of commits.

For tutorials and reference pages, the docs also carry curated static bundles under docs/_static/examples/; the root manifest is artifact-index.json. Those bundles are regenerated on vq with the current development build, then copied into the docs site with the input, full stdout.txt, full stderr.txt, matched output files, QVF archives where the example produces them, and vibe-view PNG captures for QVF-backed runs.

Tip

Every text output starts with the runtime banner: a labelled box recording vibe-qc version, codename, git revision, and linked native-library versions. For manuscript or SI work, copy that banner into your paper files alongside the .system manifest. Use the static bundles below as the documented reference outputs; for new exploratory runs, use a scratch directory outside the checkout and commit only the input script or a small data table needed to reproduce the figure.

Source Locations¶

The canonical examples live in:

examples/molecular/, molecule-only HF / DFT / MP2, optimization, vibrations, and cubes.
examples/periodic/, one-dimensional chains, bulk crystals, GPW/GAPW demos, and periodic output formats.
examples/ase_workflows/, ASE-native BFGS, NEB, vibrations, and MD workflows.
examples/ase_compare/, cross-code validation drivers that create comparison tables locally.

Static Reference Bundles¶

Most bundles below were regenerated with scripts/regenerate_doc_examples.py through vq; curated validation fixtures note their own provenance in their README. Each directory includes README.md, artifact-status.json, the copied input script or scripts, and the full text logs available for that run. The root index is artifact-index.json; the vibe-view capture status is screenshot-status.json.

Bundle	Main downloads	Notes
`h2o-rhf`	`out`, `system`, `qvf`, `screenshot`	Closed-shell H2O RHF / `6-31G*`.
`h2o-dft`	`out`, `system`, `qvf`, `screenshot`	H2O RKS-PBE / `6-31G*`.
`h2o-opt`	`out`, `traj`, `qvf`, `screenshot`	ASE/BFGS H2O relaxation.
`h2o-dimer-opt`	`out`, `traj`, `qvf`, `screenshot`	Water-dimer relaxation.
`h2o-trimer-opt`	`out`, `traj`, `qvf`, `screenshot`	Cyclic water-trimer relaxation.
`oh-radical`	`out`, `system`, `qvf`, `screenshot`	Open-shell UHF OH doublet.
`h2o-vibrations`	`out`, `hess`, `qvf`, `screenshot`	Analytic Hessian and ORCA-format Hessian export.
`h2o-cube`	`qvf`, `density cube`, `HOMO cube`, `LUMO cube`, `MO stack`	Cube writer example plus a vibe-view archive carrying the same RHF state.
`h2-tight-canonical-orth`	`out`, `qvf`, `stdout`	Diagnostic script prints its report to stdout and writes the default SCF archive.
`h-chain-uniform`	`out`, `stdout`	Legacy multi-k convergence scan; QVF is deliberately not expected.
`h-chain-peierls`	`out`, `stdout`	Legacy Peierls dimerisation scan; QVF is deliberately not expected.
`h-chain-bands`	`plot`, `stdout`	Legacy Hcore band/DOS figure; QVF is deliberately not expected.
`madelung-constants`	`out`, `stdout`	Legacy Ewald Madelung-constant table; QVF is deliberately not expected.
`nacl-symmetry`	`stdout`, `stderr`	Legacy symmetry-compression diagnostic; QVF is deliberately not expected.
`nh3-umbrella-neb`	`out`, `traj`, `qvf`, `screenshot`	NH3 umbrella-inversion climbing-image NEB.
`chi-ccm-b-qvf`	`README`, `H-chain QVF`, `H2-pair QVF`, `contact sheet`	Curated chi-CCM-B periodic QVF validation fixtures with full `.out`, sanitized `.system`, and vibe-view captures.
`mgo-route-gdf-bipole`	`README`, `GDF QVF`, `BIPOLE QVF`, `GDF density capture`, `BIPOLE structure capture`	MgO primitive RHF/STO-3G `2 x 2 x 2` GDF and symmetry-reduced BIPOLE route fixtures from `vq`; BIPOLE density/DOS optional outputs warned and are not in its QVF.

Running Examples¶

From the checkout root, use the project virtual environment:

.venv/bin/python examples/molecular/input-h2o-rhf.py

Many examples intentionally write beside themselves because that is the most convenient pattern when the script is copied into a project directory. If you run from the repository, remove the generated files before committing:

find examples -type f \
  \( -name '*.out' -o -name '*.system' -o -name '*.molden' \
     -o -name '*.traj' -o -name '*.cube' -o -name '*.png' \
     -o -name '*.csv' -o -name '*.references' -o -name '*.bibtex' \
     -o -name '*.hess' -o -name '*.engrad' -o -name 'stdout.txt' \
     -o -name 'stderr.txt' -o -name '*.population.txt' \
     -o -name '*.population.json' \) -delete

Molecular Examples¶

Script	Generates	Expected result
`input-h2o-rhf.py`	`output-h2o-rhf.*`	closed-shell H2O RHF / 6-31G*
`input-h2o-dft.py`	`output-h2o-dft.*`	H2O RKS-PBE / 6-31G*
`input-oh-radical.py`	`output-oh-radical.*`	open-shell UHF doublet with alpha/beta orbital blocks
`input-h2o-opt.py`	`output-h2o-opt.*`	ASE/BFGS H2O relaxation
`input-h2o-dimer-opt.py`	`output-h2o-dimer-opt.*`	water-dimer relaxation
`input-h2o-trimer-opt.py`	`output-h2o-trimer-opt.*`	cyclic water-trimer relaxation
`input-h2o-cube.py`	`output-h2o-cube.`, `output-h2o-.cube`	QVF archive plus density, HOMO, LUMO, and multi-orbital cube files
`input-h2o-vibrations.py`	`output-h2o-vibrations.*`	analytic Hessian and ORCA-format Hessian export

Periodic Examples¶

Script	Generates	Expected result
`input-h-chain-uniform.py`	`output-h-chain-uniform.out`	k-mesh convergence table for a 1D H2 chain
`input-h-chain-peierls.py`	`output-h-chain-peierls.out`	Peierls dimerisation scan
`input-h-chain-bands.py`	`output-h-chain-bands.png`	H-chain band structure and DOS figure
`input-madelung-constants.py`	`output-madelung-constants.out`	Ewald Madelung-constant table
`input-nacl-sto3g-dft.py`	`output-nacl-sto3g-dft.*`	debug-friendly NaCl RKS-LDA periodic run
`input-xsf-bxsf-nacl.py`	`output-nacl-xsf.*`	XSF/BXSF structure and band-grid export

ASE Workflows¶

Script	Generates	Expected result
`optimize-via-ase-bfgs.py`	trajectory, log, and convergence plot	ASE BFGS relaxation driven by `vibeqc.ase.VibeQC`
`vibrations-via-ase-vibrations.py`	displacement cache and summary text	finite-difference vibrational analysis
`nh3-neb-via-ase.py`	MEP table, plot, and trajectory	ammonia umbrella-inversion NEB
`md-water-nve.py`	time-series CSV, plot, and trajectory	NVE energy-conservation diagnostic
`surface-h2-pt111-singlepoint.py`	local Pt(111) + H2 XYZ fixture	periodic ASE geometry setup without launching SCF

Cross-Validation¶

The comparison examples in examples/ase_compare/ and examples/regression/ are source drivers. They may create ORCA, PySCF, CRYSTAL, GPAW, or CP2K logs when those programs are available, but the generated logs are not committed. Keep the input decks and small JSON/data summaries; regenerate bulky output locally when you need to audit a number.

Output File Reference¶

For the meaning of each output family, see Input scripts and output files. For run-directory hygiene, including why examples should normally be copied outside the checkout before production work, see Good practices.