Skip to content

1.1 Understand INPUT, STRU and KPT

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.

INPUT, STRU and KPT physical data contract, with real-cell and reciprocal-mesh geometry

Open figure at full size

1.1.1 The question: which files define the physical problem?

Before asking ABACUS for an energy, ask whether another person can reconstruct the same crystal and Hamiltonian. INPUT selects the calculation and numerical representation; STRU defines species, external data, lattice and atoms; KPT defines reciprocal-space sampling. None is an interchangeable copy of VASP’s input files. The first task is a static, nonmagnetic, two-atom diamond-silicon primitive cell, with fixed ions and a deliberately modest trial mesh. It is a file-reading exercise before it is an accuracy exercise.

A complete specification also includes the executable version, compilation libraries, external pseudopotential data and, for LCAO, numerical orbitals. Changing any of these may change the result. Write a short run manifest with the file hash, file provenance, version tag and intended observable. Avoid “default settings” as a description: defaults differ between basis types and releases, and are not automatically suitable for silicon.

Prerequisites and installation boundary. You need a working ABACUS executable, a supported operating environment, scientific data files, a text editor and enough local memory for the tiny examples. Installation is a separate task: follow the official v3.9.0 installation documentation, selecting the serial or MPI libraries that match the intended solver. A Windows reader can prepare files locally but should not assume this Linux MPI launch works in ordinary PowerShell; use an already authorized compatible Linux environment. This lesson neither installs software nor changes a cluster environment.

Before an authorized calculation, record the distribution/release tag or source Git commit, binary SHA-256 and linked-library/build manifest supplied with the installation. During that calculation, retain the startup banner in the log as confirmation of the actual executable used. Do not assume an undocumented abacus --version flag is harmless in an older release: this course does not depend on that flag or invoke the executable to probe it. Public input files and their checksums can be inspected without launching electronic structure calculations. Once a working installation and source-matched data are available, the three-file example below is ready for the learner’s own controlled test.

1.1.2 A complete three-file example

INPUT 

INPUT_PARAMETERS
suffix si_pw
calculation scf
basis_type pw
ntype 1
pseudo_dir ../data/pseudo
ecutwfc 60
scf_thr 1e-9
scf_nmax 150
nspin 1
smearing_method fixed
mixing_type broyden
mixing_beta 0.4
ks_solver cg
out_chg 1 10

STRU 

ATOMIC_SPECIES
Si 28.085 Si.pz-vbc.UPF

LATTICE_CONSTANT
10.2

LATTICE_VECTORS
0.0 0.5 0.5
0.5 0.0 0.5
0.5 0.5 0.0

ATOMIC_POSITIONS
Direct
Si
0.0
2
0.00 0.00 0.00 0 0 0
0.25 0.25 0.25 0 0 0

KPT 

K_POINTS
0
Gamma
4 4 4 0 0 0

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.

1.1.3 Decode the lattice and coordinates

LATTICE_CONSTANT is in bohr. The lattice vectors printed here are dimensionless multiples of that scale, whereas Direct positions are fractional coordinates in the primitive vectors. Do not interpret the second atom’s 0.25 0.25 0.25 as angstroms or as Cartesian fractions of the conventional cell. With the vectors above it becomes \((a/4,a/4,a/4)\) in conventional Cartesian coordinates, where \(a=10.2\) bohr. The nearest-neighbor distance is therefore

\[d=\frac{\sqrt{3}}{4}a.\]

The determinant of the dimensionless lattice matrix is \(1/4\), so the primitive volume is \(V=a^3/4\), not \(a^3\). These algebraic relations can be checked without running a simulation. Convert lengths using approximately \(1\) bohr \(=0.529177\) angstrom. The flags after each position control movable coordinate components in structural tasks; 0 0 0 deliberately freezes these atoms. The species-level 0.0 line initializes magnetization, not atomic charge.

K_POINTS, 0, Gamma, and the mesh line are part of KPT grammar. Here 0 chooses an automatically generated mesh, not zero physical k-points. The three final zeros are shifts. Symmetry may reduce the 64 full-grid points to a smaller irreducible set, so never infer a broken mesh merely because the log reports fewer points.

1.1.4 Run audit and output map

Prepare a new case directory and retain the three original inputs. On an already configured local Linux installation, a possible launch is shown below. Adapt the executable and MPI launcher to the installed build; this command is an instruction for the learner, not something run in preparing this course. Never submit an unfamiliar example directly to a production queue.

OMP_NUM_THREADS=1 mpirun -np 2 abacus > screen.log 2>&1

Read screen.log and OUT.<suffix>/running_scf.log. Confirm the actual version, basis, cell, species, pseudopotential, occupation method and electronic iteration status before collecting a final energy. In this baseline the final-energy marker is !FINAL_ETOT_IS, reported in eV. Its presence alone is insufficient: an unsuccessful SCF can still leave an energy-like value. Retain the complete electronic trace and any warnings. out_chg 1 10 requests a real-space density cube at ten-digit output precision; it does not tighten the electronic convergence. For the non-spin-polarized examples, inspect SPIN1_CHG.cube only after convergence has been established. Before launching, verify that relative paths are resolved from the run directory. The pseudo_dir path is joined to each species filename in STRU. Do not assume a shell’s previous directory or an editor’s project directory is the run directory. Preserve original inputs and program-written input records, but distinguish their meanings: the v3.9.0 output reference warns that OUT./INPUT can contain initial defaults rather than actual effective settings. Verify accepted parameters from the running log instead of treating the generated file as authoritative.

1.1.5 Acceptance without invented results

Check Evidence to record Acceptance rule
Physical cell lattice matrix, atom count, nearest distance two Si atoms and intended primitive geometry
External files readable file paths and hashes exact intended UPF; no silent substitutions
Units input scale and conversion note bohr versus fractional coordinates distinguished
Electronic result residual trace and status explicit successful convergence
Accuracy cutoff and mesh scans deferred to Chapter 2, not assumed

Leave the energy entry blank until a real run has passed these checks. A successful parser only establishes syntactic validity. An energy with many printed decimal places can still describe the wrong cell or an unconverged basis. The point of this lesson is to make such mistakes visible before a lengthy calculation.

1.1.6 Pitfalls and exercises

Common failures include copying a conventional-cell k-mesh to a primitive cell without checking reciprocal lengths, putting angstrom-valued lattice entries under a bohr scale, and treating movement flags as magnetic data. A missing pseudopotential should be fixed by identifying the correct data, not by renaming a convenient unrelated UPF.

  1. Coordinate exercise. Transform the second atom to Cartesian coordinates and calculate the primitive-cell volume algebraically. Answer guidance: multiply its fractional row by the three lattice vectors; sum all three components before multiplying by \(a\). Use the determinant for volume and convert bohr cubed to angstrom cubed only at the end.
  2. File-contract exercise. Move the run directory down one level. Which paths require reconsideration? Answer guidance: the geometry does not change, but the relative pseudo_dir and orbital_dir paths may. Resolve them against the new working directory, then compare hashes. A path repair must not change the physical asset.

Once this audit is complete, continue to the PW silicon calculation, where numerical errors and the physical limitations of LDA are separated.

1.1.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.