Skip to content

1.2 Match pseudopotentials and numerical orbitals

Version and execution status. Core syntax is checked against the official ABACUS v3.9.0 source documentation and example files, reviewed on 2026-10-05. The release list also contains stable v3.10.1 and 3.11 beta tags; v3.9.0 is this course’s reproducible baseline, not a claim about the newest release. These are unexecuted teaching templates. Initial numerical values are candidates for testing, not certified results. No energies, timings or convergence traces below are measurements.

Schematic radial pseudopotential and numerical orbital with vanishing orbital beyond its cutoff

Open figure at full size

1.2.1 The question: are two silicon files the same model?

Two calculations can both say “silicon LDA” yet use different valence spaces, projector constructions or numerical orbitals. This case turns external data into an explicit part of the model. A pseudopotential removes a chosen core-electron problem and replaces it with an effective operator; a numerical atomic orbital set supplies a finite space for representing the valence states. The first changes the Hamiltonian approximation, while the second changes the variational representation. Their errors must not be conflated.

The practical question is whether a candidate LCAO data pair can represent the same silicon Hamiltonian used in the PW reference. Begin with the complete LCAO silicon parent. Keep geometry, mesh and occupation fixed. Inspect data provenance before trying to interpret an energy discrepancy as “LCAO accuracy.” File suffixes and marketing labels cannot substitute for the actual data headers.

1.2.2 A scoped data-selection delta

Copy all three files from the parent. The only changed block is the external-data declaration below; it is shown for clarity, not as a self-contained STRU. Preserve the rest of the parent’s lattice and atom definitions.

ATOMIC_SPECIES
Si 28.085 Si.pz-vbc.UPF

NUMERICAL_ORBITAL
Si_lda_8.0au_50Ry_2s2p1d

The names Si.pz-vbc.UPF and Si_lda_8.0au_50Ry_2s2p1d are taken from the official silicon example: an LDA pseudopotential and an LDA numerical orbital set. PW requires only the UPF; LCAO requires both. These are external assets, not bundled downloads. Obtain the source-matched files needed for your basis, inspect their headers, save their hashes, and place them in ../data/pseudo/ and, for LCAO, ../data/orbitals/. A file with the same name is not proof of the same content. The input intentionally omits dft_functional, allowing the functional recorded in the UPF to be used. Replacing this model with PBE requires a separately documented, mutually consistent PBE pseudopotential/orbital pair for LCAO; setting dft_functional PBE alone does not recreate that pair.

For a new material, one orbital line is required for each atomic species, in matching species order. Do not add a second orbital line merely because there are two silicon atoms: species count and atom count are different. Preserve original data filenames and distribute a provenance manifest rather than undocumented renamed files.

1.2.3 Audit headers, units and valence

Record the UPF’s element, valence charge, exchange-correlation declaration, pseudopotential type, relativistic treatment, projector channels and generator information where available. A four-valence-electron silicon model implies eight electrons in a neutral two-atom cell; verify that actual valence header before using the arithmetic. Different valence treatments define different total-energy baselines, so absolute total energies are not generally comparable across unrelated pseudopotentials.

For the numerical orbital, record element, functional family, generation cutoff, radial cutoff and the number of radial functions in each angular momentum channel. The source-example name suggests a radial cutoff of 8 bohr and 2s2p1d multiplicities, but the file header is authoritative. For an unpolarized atomic-orbital basis, the number of functions per atom is

\[N_{\mathrm{orb}}=\sum_l n_l(2l+1).\]

If its header confirms two s, two p and one d radial functions, the arithmetic is \(2+2\times3+1\times5=13\) functions per atom. This is an analytic count, not a measured ABACUS output. Confirm the reported basis dimension against the actual installed data. Radial cutoffs are not plane-wave energy cutoffs: 8 bohr and 50 Ry cannot be interchanged.

1.2.4 Build the comparison ladder

First run the source-matched pair with fixed geometry. Then converge the PW reference for exactly the same UPF, functional and k-mesh. Only after that compare an LCAO energy difference, band dispersion or force against the PW value. Test orbital range and multiplicity separately from the integration cutoff; otherwise the reason for an improvement remains ambiguous.

When evaluating a replacement PBE pair, restart this ladder as a different Hamiltonian model. Do not combine an LDA orbital with an arbitrary PBE UPF and call the difference a pure basis effect. Orbital generation may be tied to a particular pseudopotential as well as a functional, so the supplier’s pairing metadata matters. A higher nominal zeta count alone is no guarantee of transferability to compressed cells, unusual coordination or charged states.

Save hashes with a standard local tool such as sha256sum ../data/pseudo/Si.pz-vbc.UPF; this reads public scientific input, not credentials. Archive both the manifest and the exact scientific data when their licenses allow it. A checksum detects content changes but says nothing about physical quality.

1.2.5 An evidence table for accepting a pair

Item Record before running Decision
Element and valence actual UPF header reject wrong element or unintended valence
Functional UPF, orbital metadata, effective input document one consistent baseline
Relativity scalar or fully relativistic channels match the intended spin model
Orbital generation paired UPF, radial range, cutoff reject undocumented pairing
Basis quality property error against converged PW measure; do not assume from filename
Provenance origin, license, SHA-256, release sufficient to reconstruct the run

An empty performance or accuracy field is preferable to inventing a benchmark. If the pair cannot be traced to a generator or documented source, identify that limitation explicitly and find a verified alternative before making a material-property claim.

1.2.6 Pitfalls and two exercises

Do not “repair” an orbital mismatch by increasing ecutwfc: a finer integration grid does not change the orbital’s radial functions. Likewise, a very small SCF residual cannot validate a poor pseudopotential. It only says that the selected approximate problem has been solved consistently enough under the chosen criterion.

  1. Counting exercise. Compare 2s2p1d and a hypothetical header specifying 3s3p2d. How many non-spin-polarized basis functions per atom does each contain? Answer guidance: account for the \((2l+1)\) angular degeneracy; the latter gives \(3+9+10=22\). This is counting only, not evidence that an available file has that content or that it improves a property.
  2. Model-change exercise. You replace an LDA UPF with a PBE one while keeping all other files. Can the new-minus-old total energy quantify orbital error? Answer guidance: no; the Hamiltonian changed. Construct a PW reference with each respective UPF and compare LCAO-to-PW differences within each model. Then separately discuss functional dependence.

Continue to orbital convergence after this data audit, so its scans change the basis rather than inadvertently changing the physics.

1.2.7 Official references and provenance

These references establish file grammar and available options. The explanations, comparison designs, algebraic exercises and figures are original teaching material; no published example energy is presented as a result of this course. Additional learning resources are collected in the course hub references section. The university-linked 2024 guide is supplementary teaching, not a substitute for the pinned input reference.