Getting Started with First-Principles Calculations: The H₂ Molecule from Zero
This article explains how to run your first plane-wave pseudopotential calculation using the simplest possible system: the H₂ molecule. You will learn how to prepare the runtime environment and pseudopotentials, understand every key input parameter (acell, rprim, znucl, natom, typat, xcart, ixc, ecut, kptopt, nkpt), run the calculation and read the output, validate results with convergence tests, and extend the workflow to geometry optimization and binding energy calculations. It also includes a troubleshooting checklist and a roadmap from molecules to solids, giving beginners a reliable foundation for more complex systems such as silicon and metal oxides.
1. Why Start with the H₂ Molecule
First-principles calculations solve material properties from the basic equations of quantum mechanics without relying on empirical parameters. The most widely used approach today is density functional theory (DFT), and in mainstream open-source and commercial packages it is typically implemented as a plane-wave basis set plus pseudopotentials.
Many beginners go straight to solids such as silicon or metal oxides the moment they install one of these packages. The usual outcome is a file that fails to parse, plus a set of numbers whose correctness nobody can judge. A far more effective starting point is the H₂ molecule, for four reasons:
- The system is small. H₂ has only two atoms and two valence electrons. The input file is usually under 20 lines and runs in a few seconds, so you can experiment freely.
- The results can be checked. The experimental equilibrium bond length of H₂ is about 0.74 Å and its dissociation energy about 4.75 eV, so calculated values can be compared item by item.
- The concept coverage is complete. Unit cell and pseudopotentials, atomic coordinates, plane-wave cutoff energy, k-point sampling, and self-consistent convergence all appear even in this tiny system.
- “Simple” does not mean “trap-free.” Once an isolated molecule is placed in a periodically repeated supercell, the supercell size, the cutoff energy, and the k-point settings all affect the result. H₂ is exactly the right vehicle for understanding these pitfalls.
A four-step learning path works well:
- Set up the runtime environment and pseudopotentials.
- Understand each input parameter on its own.
- Run the calculation and interpret the output.
- Confirm the results are trustworthy with convergence tests.
This article follows that order.
2. Preparation Before the Calculation
2.1 Runtime environment and working directory
Plane-wave pseudopotential codes are normally driven from the command line. After building the executable from source or installing it, add the installation path to the PATH environment variable, then type the program name together with a version flag (such as -v) in a terminal. If version information is printed, the environment is working.
Create a dedicated working directory for the calculation and keep both the input file and the output files inside it, so that several jobs do not get mixed up. If you need sample input files, copy them straight out of the code’s test or tutorial directory — these files are the best reference for syntax and parameter conventions.
2.2 Pseudopotentials and how to choose them
A pseudopotential replaces the real combination of nucleus and core electrons with a smoother effective potential. Only the valence electrons are treated explicitly; the core region is frozen. This cuts the computational cost dramatically while preserving the accuracy of the valence wavefunctions.
Three points matter when selecting a pseudopotential:
- Core treatment. The common families are norm-conserving, ultrasoft, and the projector augmented-wave (PAW) method. Norm-conserving pseudopotentials reproduce all-electron results once the cutoff is high enough, have clear physical meaning, and are a good choice for learning. The other two usually need lower cutoffs and suit larger, more expensive systems.
- Exchange-correlation functional. LDA (local density approximation) and GGA (for example PBE) are standard. The functional declared in the input file must match the one used to generate the pseudopotential, otherwise the results are meaningless.
- Relativistic treatment. Heavy elements require relativistic effects, and pseudopotential files state explicitly whether the scalar-relativistic approximation is used. For light elements such as hydrogen this can be ignored.
At the beginner stage, download a norm-conserving, scalar-relativistic LDA set from a public pseudopotential library. File names normally encode the element symbol, the functional, and a version, for example a name containing both “H” and “LDA”.
2.3 Directory conventions and writing the input file
Because a pseudopotential library contains many files, keep them all in one dedicated directory and point the input file at that directory through an environment variable (written as <psp_dirpath> below). Pseudopotential file names are then given relative to that root, so the whole set of input files can be moved between machines without editing.
The input file is plain text, written with any text editor. Two details matter when saving it:
- Save as plain text; either Unix (LF) or Windows (CRLF) line endings work.
- Parameters and file names are case-sensitive. If you add comments in a non-ASCII language, use UTF-8 encoding to avoid garbled text that breaks parsing.
Finally, create an output folder (for example log1). Results and log files are written there, which makes later review easy.
3. Input Parameters Explained One by One
Once preparation is done, find an atomic-structure example in the code’s basic tutorial directory (file names typically start with tbase1, such as tbase1_1), copy it into the current directory, and open it. It describes an isolated H₂ molecule placed at the center of a large box.
3.1 A complete input example
Below is an annotated single-point energy input file for the H₂ molecule, with small modifications to the basic example: the supercell edge is increased from 10 Bohr to 15 Bohr, the exchange-correlation variable ixc is stated explicitly, and an optional geometry-optimization block is added.
# ==================== System setup ====================acell 15 15 15 # Supercell edge, in Bohr; 15 Bohr ~ 7.94 Angstromrprim 1 0 0 # Lattice vectors, identity matrix by default -> orthorhombic box0 1 00 0 1ntypat 1 # Number of element types: hydrogen onlyznucl 1 # Atomic number: 1 for H, must match the Z in the pseudopotentialnatom 2 # Total number of atoms in the supercelltypat 1 1 # Element index of each atom; both atoms are type 1xcart # Atomic coordinates, Cartesian, in Bohr-0.7 0.0 0.0 # First hydrogen atom0.7 0.0 0.0 # Second hydrogen atom# H-H distance = 1.4 Bohr ~ 0.74 Angstrom, close to experiment# ==================== Pseudopotential setup ====================ixc -1012 # Exchange-correlation functional: LDA (Perdew-Wang 92)<psp_dirpath> # Root directory of the pseudopotential library# (e.g. /your/path/pseudos); an environment variable# such as "$ABI_PSPDIR" is recommendedpseudos "H.LDA.ncpp.UPF" # Path and file name relative to that root# (example only; check your own library)# ==================== Plane-wave setup ====================ecut 10 # Plane-wave cutoff energy, in Hartree; 10 Ha ~ 272 eV# ==================== k-point setup ====================kptopt 0 # k-points given manuallynkpt 1 # Number of k-points0.0 0.0 0.0 # Gamma point, in reduced coordinates# ==================== Geometry optimization (optional) ====================# ionmov 2 # Select a structural optimization algorithm# nstep 20 # Maximum number of optimization steps# optcell 0 # Do not optimize the cell# tolmxf 5.0d-5 # Convergence threshold on maximum atomic force (Hartree/Bohr)# toldff 5 # SCF energy difference threshold (in muHa)
Notes:
- Lines beginning with
#are comments. Grouping them into labelled blocks keeps the file readable. <psp_dirpath>and"H.LDA.ncpp.UPF"are placeholders — substitute your actual directory and pseudopotential file name.- The example only shows the minimum parameter set needed for an isolated molecule; a full input file can contain many more optional settings.
- The original example did not set
ixcexplicitly and therefore relied on the default functional (also LDA). Statingixcremoves that ambiguity.
3.2 Supercell and lattice: acell and rprim
acell gives the edge length of the supercell along the three directions, in Bohr. Bond lengths and volumes depend on unit conversion, so these two values are worth memorising:
- 1 Bohr ≈ 0.529 Å
- 1 Ha ≈ 27.211 eV
The 10 Bohr box in the original example is therefore about 5.3 Å; the 15 Bohr box used here (about 7.9 Å) leaves more generous vacuum.
An isolated molecule has no periodicity, so the supercell must be large enough that the periodic images of the molecule in neighbouring cells barely overlap in electron density. Otherwise the images interact spuriously. For a compact molecule such as H₂, roughly 10 Bohr is usually sufficient; molecules with diffuse electrons or a large dipole moment need more vacuum, sometimes together with a dipole correction.
rprim defines the lattice vectors. If omitted, it defaults to the identity matrix: an orthorhombic box with mutually perpendicular axes whose lengths come from acell. For a skewed cell — for instance when studying surface adsorption and one side of the box must be parallel to the surface — rprim has to be rewritten, and the actual edge lengths then follow from both acell and the norms of the vectors in rprim.
3.3 System composition: ntypat, znucl, natom, and typat
Four parameters together describe which atoms the system contains:
ntypat: number of distinct element types. H₂ contains one, so the value is 1.znucl: atomic number of each element, 1 for hydrogen. Values are matched one-to-one, in order, with the pseudopotential list and must agree with theZrecorded inside the pseudopotential file.natom: total number of atoms in the supercell, 2 for H₂.typat: an integer array of lengthnatomthat assigns each atom, in the order the atoms are listed, to an element index. Both H₂ atoms are type 1.
The strict way to write this is with a space between the numbers, i.e. 1 1. The bare 11 used in some tutorial examples relies on the code’s rules for parsing consecutive digits, and becomes ambiguous once there are more element types or indices above 9.
3.4 Atomic coordinates: xcart and xred
There are two ways to specify atomic positions:
xcartgives Cartesian coordinates in Bohr, suitable for isolated molecules and clusters with no obvious symmetry axis.xredgives reduced coordinates (usually in the range 0 to 1) with the lattice vectors as axes, suitable for crystals with symmetry.
In the original example the two hydrogen atoms sit at (-0.7, 0, 0) and (0.7, 0, 0), separated by 1.4 Bohr, or about 0.74 Å, which matches the experimental equilibrium bond length. Computing the total energy at a geometry this close to equilibrium should therefore return a value near the minimum for that structure.
Two reminders:
- The bond length has a strong effect on the energy. Deviating from equilibrium by 0.1 Bohr can raise the energy by tens of mHa, so coordinate precision must not be arbitrary.
- Atomic coordinates should in principle lie inside the supercell; coordinates outside the box or overlapping atoms can cause failures.
3.5 Pseudopotential and exchange-correlation: ixc, pseudos, and the environment variable
The pseudopotential setup has three interrelated parts:
ixcdeclares the functional used in the calculation.-1012corresponds to the Perdew–Wang 92 form of LDA and must match the functional used to generate the pseudopotential.- The environment variable (
<psp_dirpath>, referred to aspp_dirpathin the tutorial) points to the root of the pseudopotential library. It can be set with anexportcommand before launching the calculation, or assigned directly in the input file. pseudoslists the path and file name of each pseudopotential, relative to that root.
For example, the tutorial entry "Psdj_nc_sr_04_pw_std_psp8/H.psp8" is a norm-conserving, scalar-relativistic LDA pseudopotential for hydrogen, consistent with ixc=-1012. As a beginner, start with the standard versions from the official library; when a change is needed, replace the entry in the input file rather than modifying the library itself.
3.6 Plane-wave cutoff energy: ecut
The plane-wave basis set contains all plane waves with kinetic energy below ecut. A higher ecut includes more plane waves, describes the wavefunctions more completely, and brings the total energy closer to the complete-basis-set limit, while the cost grows roughly as a power of ecut. It is therefore the most direct trade-off between accuracy and efficiency.
The “harder” a system — the more violently its wavefunctions oscillate near the core — the higher the required ecut. Light elements with norm-conserving pseudopotentials often need only 10 to 30 Ha, whereas systems containing first-row elements such as oxygen, or all-electron potentials, typically need more.
One point needs clarifying: the claim that “a larger ecut is always more accurate” only holds over a limited range. Once the value is converged, increasing it further barely changes the result and merely wastes time.
For H₂, 10 Ha is usually enough for a reasonable bond length and total energy. At the beginner stage, however, the priority is to master the procedure of cutoff convergence testing (Section 5) rather than to trust any fixed number.
3.7 k-points and the Brillouin zone of an isolated molecule
kptopt controls how k-points are generated: with 0, the user supplies the k-point list and weights explicitly; with other common values, the code builds a grid from the settings provided.
k-point sampling performs the integration over the first Brillouin zone, and the required density depends on the supercell size. The larger the cell along a given direction, the smaller the Brillouin zone in that direction and the fewer k-points needed; shrinking the cell expands the Brillouin zone and produces visible band dispersion.
The supercell of an isolated molecule is large, so its Brillouin zone shrinks almost to a single point and nkpt can be set to 1, using only the Γ point (coordinates 0 0 0). The original example’s decision to sample Γ only, on the grounds that the molecule is isolated, is correct.
A weight column follows the Γ point. The total weight must be 1; with nkpt 1 the weight is always 1 and may be omitted. The full form is:
nkpt 10.0 0.0 0.0 1.0
4. Running the Calculation and Reading the Results
With the input file saved, launch the program from the terminal, passing the input file name and an output file name (with an extension such as .abo). Logs and results are written to the output folder. Read the output in the following order.
4.1 Echo of the parameters
The beginning echoes the pseudopotential information (source, version, functional, valence electrons included), the supercell volume, the cutoff energy, the k-points, the atomic coordinates, and the interatomic distances. This is the fastest place to spot mistakes: if the echo does not match expectations, there is no point reading further.
4.2 The self-consistent iterations
Solving the Kohn–Sham equations requires a self-consistent loop, and the program prints iteration information step by step:
- Total energy, which converges towards a stable value as the iterations proceed;
- Energy difference (delta), the change in total energy between consecutive steps;
- Residual (res2), the difference between the input and output potentials;
- Maximum force, reported for each atom if a structural optimization is running.
Do not judge convergence from the energy difference alone. A tiny change in total energy does not imply that the charge density or the forces have converged.
4.3 Results and order-of-magnitude checks
The program finally prints the total energy together with components such as the total kinetic and exchange-correlation energies. For H₂, a total energy of roughly −1.1 Ha (about −30 eV) is the right order of magnitude; anything very different means the pseudopotential or the coordinates should be checked.
Also verify that the interatomic distance matches the input. If the echoed distance differs from what you intended, the coordinates were written incorrectly.
5. Convergence Tests: From “It Runs” to “It Is Accurate”
A completed single-point calculation only shows that the workflow runs. Whether the result can be trusted depends on convergence tests. The core method is to change one parameter at a time, keep everything else fixed, and watch the target quantities — total energy, bond length, residual forces.
- Cutoff convergence. Fix the supercell and the k-points, set
ecutin turn to 10, 15, 20, 25, and 30 Ha, and record the total energy. When the difference between neighbouring settings falls below about 1 meV, the cutoff can be considered converged. - Vacuum convergence. Fix
ecutand increaseacellfrom 8 to 10, 12, 15, and 18 Bohr, watching the total energy and the bond length. Once the total energy levels off as the box grows, the interaction between periodic images can be neglected. - k-point convergence. For an isolated molecule with a sufficiently large supercell, Γ only is enough. If the system becomes smaller in one direction, as in surface models or thin films, the k-point density along that direction must be checked.
- Geometry-optimization parameters. If an optimization is run, examine the convergence criteria and the maximum number of steps. Loose criteria stop the run too early; tight criteria increase the cost and may prevent convergence altogether.
- Spin settings. H₂ is a closed-shell singlet and needs no spin polarisation. A single H atom, by contrast, requires spin polarisation; without it the result is an unphysical “half-occupied” state.
During testing, keep the pseudopotential and the functional unchanged, otherwise the origin of any change cannot be identified. Record the results in a table listing each parameter, its value, and the corresponding outcome, and keep every input file so the work can be revisited.
6. Further Experiments: Geometry Optimization and Binding Energy
The equilibrium geometry does not have to be set by hand; the program can search for it. Add variables such as ionmov, nstep, and tolmxf to the input file, and the program moves the atoms along the direction of the forces starting from the initial structure, stopping when the maximum atomic force drops below tolmxf.
It is worth starting from an initial bond length between 0.8 and 1.0 Å, slightly off equilibrium, to see whether the program returns to about 0.74 Å. This is an effective check that the optimizer is working.
From there, scan the total energy point by point along the H–H distance to obtain an energy–bond-length curve, which yields the equilibrium bond length and a rough estimate of the vibrational frequency.
To obtain the binding energy, the energy of an isolated H atom is also required:
Etot(H2) and Etot(H)Binding energy E_b = 2 x Etot(H) - Etot(H2)
For the H atom calculation, keep the same box, cutoff, and other settings, and switch on spin polarisation. LDA typically underestimates the equilibrium bond length and overestimates the binding energy. If your results show a systematic deviation from experiment, the cause most likely lies at the level of the functional rather than in a mistyped input parameter.
7. Common Problems and a Troubleshooting Checklist
Beginners most often run into the following:
- “Pseudopotential not found”: the pseudopotential directory variable is unset, or the file name has the wrong case or extension.
- Composition check fails:
znucldoes not match theZrecorded in the pseudopotential. - Overlapping atoms or atoms outside the cell: produces abnormal forces or a calculation that will not converge.
- Parsing errors: hidden characters introduced by saving with a rich-text editor, or misspelled keywords and broken lines.
- Self-consistency not reached: lower
ecuttemporarily to confirm that the system can converge at all, then raise it again step by step. - Implausible results: the echoed interatomic distance differs from the input, or the total energy is clearly the wrong order of magnitude.
When debugging, follow the order “first the parameter echo, then the convergence behaviour, finally the results”. This narrows down the problem layer by layer instead of changing values blindly.
8. Next Steps: From Molecules to Solids
After mastering H₂, the following sequence is a natural continuation:
- Crystal structures. Describe the lattice with lattice vectors (diamond silicon, for example), add a sensible k-point grid, and recompute with the converged
ecutand k-point settings. - Electronic structure. Starting from the self-consistent charge density, run a non-self-consistent band-structure calculation and a density-of-states calculation, then analyse the band gap and the orbital contributions.
- Structural properties. Optimize the lattice constants and atomic positions, then fit an energy–volume curve (an equation of state) to obtain the equilibrium volume and the bulk modulus.
- Functional properties. Phonon calculations and transition-state searches address dynamical behaviour; for strongly correlated systems such as transition-metal oxides, DFT+U or hybrid functionals can be tried.
As the calculations grow, cloud resources help. Elastic compute allows jobs to be submitted in batches and scaled with the workload; object storage keeps input files and pseudopotential data; a log service collects and searches output centrally; and monitoring with alerts catches failed jobs or resource anomalies early. For example, the cloud products offered by Baidu AI Cloud can serve as the resource base for this kind of workflow.
9. Summary
A calculation of the H₂ molecule looks like a few lines of input, yet it concentrates most of the core elements of plane-wave pseudopotential first-principles work:
acellandrprimset the supercell size and therefore decide whether image interactions can be neglected;ntypat,znucl, andtypatdefine the composition and must match the pseudopotentials exactly;xcartgives the atomic positions, and bond-length accuracy translates directly into energy accuracy;ixcand the pseudopotential must describe the same functional;ecutis the trade-off between accuracy and efficiency;kptoptandnkptexpress the relationship between supercell size and Brillouin-zone sampling.
The recommended order is: prepare the environment, understand the parameters, run the calculation, interpret the output, test convergence, then extend the application. Cultivate the habit of saving inputs and outputs and recording test data. Once the foundation is solid with H₂, you can decide, for more complex systems such as silicon or metal oxides, what to compute and how accurate the answer needs to be before it counts as converged.
