comp-chem/cp2k
1
0
Fork 0
mirror of https://github.com/cp2k/cp2k.git synced 2026-07-28 22:25:32 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
cp2k/docs/methods/electronic_structure/molecular_orbitals.md
SY Wang 1425815bee
Add documentation of MO output (#5370)
2026-06-12 15:06:33 +02:00

448 lines
18 KiB
Markdown
Raw Permalink Blame History

# Molecular orbitals output
CP2K can write Kohn--Sham molecular orbital (MO) information in several formats. These outputs serve
different purposes: some are convenient for quick inspection in the standard output, some are
intended for visualization, and some provide enough basis-set information for external
post-processing.
The most useful choices are:
- **Text MO information** ([&MO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO)): inspect MO energies,
occupations, and AO coefficients in the output file. This is useful for small systems or
debugging, but files can become large if eigenvectors are printed.
- **Molden file** ([&MO_MOLDEN](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_MOLDEN)): visualize Gamma-only
orbitals with external tools. Molden output is not available for k-point calculations, but CP2K
can optionally write cell and pseudopotential metadata.
- **K-point MO dump** ([&MO_KP](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_KP)): export MO information for
k-point calculations in the CP2K-specific `.mokp` text format, including k-points, eigenvalues,
occupations, complex MO coefficients, and AO information.
- **TREXIO file** ([&TREXIO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.TREXIO)): export orbital information
in TREXIO HDF5 format for interoperability with quantum-chemistry post-processing tools. This
requires TREXIO support in the CP2K build.
- **MO cube files** ([&MO_CUBES](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES)): visualize selected
orbitals on a real-space grid. This is useful for frontier-orbital plots, but may produce many
large files.
- **MO openPMD files** ([&MO_OPENPMD](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD)): write
grid-based orbital data in openPMD format. This is more suitable for structured, possibly large
grid data than plain cube files.
## Text MO information
The [&MO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO) print section writes MO information to a text file.
It is most useful when you want to inspect a limited number of orbitals, their energies,
occupations, and optionally their AO coefficients.
```text
&FORCE_EVAL
&DFT
&PRINT
&MO
ENERGIES T
OCCUPATION_NUMBERS T
COEFFICIENTS F
MO_INDEX_RANGE 1 -1
NDIGITS 6
&END MO
&END PRINT
&END DFT
&END FORCE_EVAL
```
Useful controls include:
- [ENERGIES](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO.ENERGIES),
[OCCUPATION_NUMBERS](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO.OCCUPATION_NUMBERS), and
[COEFFICIENTS](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO.COEFFICIENTS): choose which parts of the MO
information are printed.
- [MO_INDEX_RANGE](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO.MO_INDEX_RANGE): restrict the printed orbital
range. Use `-1` as the last index to print all available orbitals.
- [CARTESIAN](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO.CARTESIAN): print coefficients in the Cartesian
basis instead of the default spherical basis.
- [CARTESIAN_OVERLAP](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO.CARTESIAN_OVERLAP): print the Cartesian
overlap matrix together with Cartesian MO coefficients.
For diagonalization calculations, unoccupied orbitals must be available through
[ADDED_MOS](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.ADDED_MOS). For OT calculations, CP2K can generate the
requested virtual orbitals for printing through the OT eigensolver.
### Interpreting MO energies and energy gaps
The MO energies printed by CP2K are one-particle eigenvalues of the chosen electronic-structure
method. They are useful for comparing orbital orderings, occupations, frontier orbitals, and
k-point-resolved band structures. However, they should not in general be interpreted as directly
measurable quantities. Experimental observables such as ionization potentials, electron affinities,
redox potentials, optical excitation energies, and quasiparticle gaps involve total-energy
differences, many-body effects, structural or environmental relaxation, or other physical
contributions that are not captured by a simple one-particle eigenvalue alone.
For finite systems, the HOMO--LUMO gap is the difference between the lowest unoccupied and highest
occupied MO eigenvalues. For periodic k-point calculations, the relevant band gap is obtained by
comparing the valence-band maximum and conduction-band minimum over all k-points and spin channels;
the minimum gap may be indirect. In metallic or smeared calculations, occupations around the Fermi
level can make a HOMO--LUMO or band-gap interpretation ambiguous.
The numerical value of an eigenvalue gap depends on the exchange-correlation functional, basis set,
pseudopotential, spin treatment, k-point sampling, and the number and quality of available
unoccupied states.
```{tip}
The overall phase of an individual molecular orbital is arbitrary. Therefore, a sign flip of a
single MO, or a phase rotation in a complex k-point calculation, is not by itself a physical
difference. Post-processing tools and regression tests should compare phase-invariant quantities
when appropriate.
```
## Molden file for Gamma-only calculations
[&MO_MOLDEN](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_MOLDEN) writes the orbitals in Molden format. This
is the most convenient format for visualizing molecular orbitals from Gamma-only calculations.
```text
&FORCE_EVAL
&DFT
&PRINT
&MO_MOLDEN
NDIGITS 9
UNIT ANGSTROM
WRITE_CELL T
WRITE_PSEUDO T
MARK_GHOST T
NLUMO 5
&END MO_MOLDEN
&END PRINT
&END DFT
&END FORCE_EVAL
```
The Molden format was originally designed for molecular systems. CP2K therefore adds optional
metadata that is useful for periodic or pseudopotential calculations:
- [WRITE_CELL](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_MOLDEN.WRITE_CELL): write a `[Cell]` block with
the simulation-cell vectors.
- [WRITE_PSEUDO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_MOLDEN.WRITE_PSEUDO): write a `[Pseudo]` block
with effective nuclear charges.
- [MARK_GHOST](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_MOLDEN.MARK_GHOST): mark ghost atoms in the
`[Atoms]` block by setting their atomic number to zero.
- [NLUMO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_MOLDEN.NLUMO): include a selected number of unoccupied
orbitals. `0` means no virtual orbitals, and `-1` means all available virtual orbitals.
- [GTO_KIND](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_MOLDEN.GTO_KIND): choose spherical or Cartesian
Gaussian functions. The default is spherical.
A shortened Molden file written with `WRITE_CELL` and `WRITE_PSEUDO` looks like:
```text
[Molden Format]
[Cell] Angs
3.574965 0.000000 0.000000
0.000000 3.574965 0.000000
0.000000 0.000000 3.574965
[Atoms] Angs
C 1 6 0.000000 -0.000000 0.000000
C 2 6 2.681237 0.893728 2.681237
...
[Pseudo]
C 1 4
C 2 4
...
[GTO]
1 0
s 5 1.00
5.605330752 0.111532882
2.113016391 0.153142194
...
[MO]
Ene= -3.5996287670E-01
Spin= Alpha
Occup= 2.0000000
1 2.155619005E-01
2 1.904995482E-03
...
```
Here `[Cell]` and `[Pseudo]` are CP2K extensions to the original Molden format. The `[GTO]` block
contains the Gaussian basis information, and the `[MO]` block contains the orbital energy, spin,
occupation, and AO coefficients of each printed orbital.
```{note}
`WRITE_PSEUDO` already writes the effective nuclear charge of ghost atoms as zero. Therefore,
`MARK_GHOST` is mainly needed when a visualization or post-processing tool relies on the atomic
number in the `[Atoms]` block rather than the `[Pseudo]` block.
```
```{note}
Molden output is not available for k-point calculations. Use
[&MO_KP](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_KP) instead.
```
## K-point MO output: `.mokp`
From version 2026.2, CP2K starts to write `.mokp` text format for k-point calculations through
[&MO_KP](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_KP). This format is intended for post-processing tools
that need the k-point-resolved MO coefficients together with enough AO information to interpret
them.
```text
&FORCE_EVAL
&DFT
&PRINT
&MO_KP
AO_EXPORT_TYPE GTO_BASIS
NDIGITS 9
UNIT ANGSTROM
&END MO_KP
&END PRINT
&END DFT
&END FORCE_EVAL
```
The two AO export modes target different post-processing workflows:
- `AO_EXPORT_TYPE GTO_BASIS` writes a compact GTO basis definition. The post-processing code
reconstructs the overlap matrix, including its k-point dependence.
- `AO_EXPORT_TYPE OVERLAP_MATRIX` writes the explicit overlap matrix $S(k)$ for each k-point. This
produces larger files but avoids reconstructing the AO overlap externally.
A `.mokp` file contains:
- cell vectors, atomic positions, nuclear charges, effective nuclear charges, and AO ranges;
- the k-point list and k-point weights;
- eigenvalues and occupations for each k-point and spin channel;
- real and, when needed, imaginary parts of the MO coefficient matrix;
- either a GTO basis definition or explicit overlap matrices, controlled by
[AO_EXPORT_TYPE](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_KP.AO_EXPORT_TYPE).
A shortened `.mokp` file looks like:
```text
# CP2K_KPOINT_MO_DUMP, Version 2.0
# All energies in Hartree, lengths in Angstrom, k-points in fractional reciprocal coords
# DIMENSIONS: natom nspins nao nkp = 8 1 104 14
# NMO = 20
# USE_REAL_WFN = F
# AO_EXPORT_TYPE = GTO_BASIS
# SPARSE_THRESHOLD = 1.00000E-09
# CELL_VECTORS [Angstrom]
3.574965 0.000000 0.000000
0.000000 3.574965 0.000000
0.000000 0.000000 3.574965
# ATOM_LIST: Atom_ID Element Z_nuc Z_eff X [Ang] Y [Ang] Z [Ang] First_AO Last_AO
1 C 6 4 0.000000 -0.000000 0.000000 1 13
...
# KPOINT_LIST: ikp kx ky kz weight
1 -3.33333333E-01 -3.33333333E-01 -3.33333333E-01 7.40740741E-02
...
# GTO_BASIS (spherical, MOLDEN convention for contraction coefficients)
1 0
s 5 1.00
5.605330752E+00 1.115328819E-01
...
# BEGIN_KPOINT_SPIN ikp ispin = 1 1
# EIGENVALUES
-2.634414483E-01 -1.634039635E-01 -1.633988780E-01 -1.633988754E-01
...
# OCCUPATIONS
2.000000000E+00 2.000000000E+00 2.000000000E+00 2.000000000E+00
...
# MO_COEFF_RE (Sparse: mo_index ao_index value)
1 1 1.152519336E-01
1 2 6.519198415E-03
...
# MO_COEFF_IM (Sparse: mo_index ao_index value)
1 1 -1.607824559E-01
1 2 -8.895941146E-03
...
```
```{note}
`&MO_KP` is only active for k-point calculations. For Gamma-only calculations, use `&MO_MOLDEN`,
`&MO`, or `&MO_CUBES` depending on the intended use.
```
## TREXIO HDF5 file
```{important}
Printing TREXIO file requires CP2K to be built with
[TREXIO](../../technologies/libraries.md#trexio-unified-computational-chemistry-format) and
[HDF5](../../technologies/libraries.md#hdf5) support.
```
[&TREXIO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.TREXIO) writes orbital information in the
[TREXIO](https://trex-coe.github.io/trexio/) format. CP2K writes the HDF5 backend and appends the
`.h5` suffix to the requested filename. If
[FILENAME](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.TREXIO.FILENAME) is not set explicitly, the output file
is named `<PROJECT>-TREXIO.h5`.
```text
&FORCE_EVAL
&DFT
&PRINT
&TREXIO
FILENAME orbitals
CARTESIAN F
&END TREXIO
&END PRINT
&END DFT
&END FORCE_EVAL
```
Useful controls include:
- [FILENAME](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.TREXIO.FILENAME): choose the body of the `.h5` output
filename.
- [CARTESIAN](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.TREXIO.CARTESIAN): store the MOs in the Cartesian
basis instead of the default spherical basis.
- [FULL_KPOINT_GRID](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.TREXIO.FULL_KPOINT_GRID): for symmetry-reduced
k-point calculations, export MOs on the full unreduced k-point grid instead of only the
irreducible grid.
- [REUSE_SCF_MOS](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.TREXIO.REUSE_SCF_MOS): when `FULL_KPOINT_GRID` is
active, try to reconstruct the full-grid MO coefficients from the symmetry-reduced SCF orbitals
before falling back to a full-grid diagonalization.
The resulting file, here `orbitals.h5`, stores the information in a structured binary format rather
than as a plain text file. It contains system metadata, nuclear coordinates and effective charges,
cell and periodic-boundary information, electron numbers, basis and AO metadata, and canonical MO
information such as MO coefficients, energies, occupations, and spin labels. For k-point
calculations, CP2K also writes the k-point information and, when needed, the imaginary part of the
MO coefficients.
A TREXIO file is binary, so the useful "file output example" is its HDF5 layout rather than raw text
content. For example, inspecting the file with an HDF5 tool shows groups and datasets such as:
```shell
$ h5ls orbitals.h5
metadata Group
nucleus Group
cell Group
pbc Group
electron Group
state Group
basis Group
ao Group
ecp Group
mo Group
$ h5ls orbitals.h5/mo
coefficient Dataset {ao_num, mo_num}
energy Dataset {mo_num}
occupation Dataset {mo_num}
spin Dataset {mo_num}
type Dataset {...}
...
```
## MO cube files
[&MO_CUBES](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES) writes selected orbitals on a real-space grid
in [cube format](https://paulbourke.net/dataformats/cube/). This is mainly useful for visualizing
frontier orbitals, defect states, adsorbate states, or localized molecular orbitals.
```text
&FORCE_EVAL
&DFT
&PRINT
&MO_CUBES
NHOMO 2
NLUMO 5
STRIDE 2 2 2
&END MO_CUBES
&END PRINT
&END DFT
&END FORCE_EVAL
```
Useful controls include:
- [NHOMO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES.NHOMO) and
[NLUMO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES.NLUMO): choose how many occupied and unoccupied
orbitals are written.
- [HOMO_LIST](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES.HOMO_LIST): request specific occupied
orbitals and override `NHOMO`.
- [STRIDE](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES.STRIDE): reduce the grid resolution to make
files smaller. The default value is `2 2 2`, so only every second grid point is written along each
direction, corresponding to about one eighth of the native grid points.
- [MAX_FILE_SIZE_MB](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES.MAX_FILE_SIZE_MB): let CP2K choose a
suitable stride to limit cube-file size.
- [WRITE_CUBE](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES.WRITE_CUBE): compute eigenvalues while
suppressing cube-file writing when set to false.
Each selected orbital is written to a separate cube file. The file name contains the MO index and
spin channel, for example `PROJECT-WFN_00016_1-1_0.cube` for MO 16, spin 1. A shortened cube file
looks like:
```text
-Quickstep-
WAVEFUNCTION 16 spin 1 i.e. HOMO - 0
8 0.000000 0.000000 0.000000
36 0.187500 0.000000 0.000000
36 0.000000 0.187500 0.000000
36 0.000000 0.000000 0.187500
6 0.000000 0.000000 -0.000000 0.000000
6 0.000000 2.681237 0.893728 2.681237
...
1.23456E-07 -2.34567E-07 3.45678E-07 -4.56789E-07 5.67890E-07 -6.78901E-07
...
```
The first two lines are comments. The following lines define the grid origin, grid dimensions, and
grid vectors, followed by the atom list and then the real-space values of the selected orbital.
```{note}
CP2K writes the real-space orbital values in fixed-width `E13.5` fields following the
[Gaussian cube file convention](https://gaussian.com/cubegen/). Some downstream cube-file parsers
assume this fixed-width layout rather than only whitespace-separated floating-point values, so the
formatting should be preserved when cube files are post-processed or rewritten.
```
Cube files can become very large, especially for large cells or when many orbitals are requested.
For large grid-based orbital data, [&MO_OPENPMD](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD) may be
more appropriate.
## MO openPMD file
```{important}
Printing openPMD file requires CP2K to be built with
[openPMD](../../technologies/libraries.md#openpmd-structured-output) support.
```
[&MO_OPENPMD](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD) writes selected molecular orbitals on the
real-space grid in the openPMD format. Similar to
[&MO_CUBES](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES), it is mainly intended for grid-based
visualization or post-processing of selected orbitals rather than for exporting AO-basis MO
coefficients. Compared with plain cube files, openPMD is better suited for structured and
potentially large data, supports parallel I/O through the openPMD backend, and can store the data in
formats such as ADIOS2 BP files depending on the openPMD configuration.
```text
&FORCE_EVAL
&DFT
&PRINT
&MO_OPENPMD
NHOMO 1
NLUMO 5
STRIDE 2 2 2
&END MO_OPENPMD
&END PRINT
&END DFT
&END FORCE_EVAL
```
The most relevant options are [NHOMO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD.NHOMO),
[NLUMO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD.NLUMO), and
[HOMO_LIST](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD.HOMO_LIST), which select the orbitals to be
written. [STRIDE](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD.STRIDE) reduces the grid resolution
and therefore the output size. More advanced openPMD runtime options can be passed through
[OPENPMD_CFG](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD.OPENPMD_CFG) or
[OPENPMD_CFG_FILE](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD.OPENPMD_CFG_FILE).
## Choosing an output format
- Use [&MO_MOLDEN](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_MOLDEN) when the calculation is Gamma-only
and the goal is visualization in common molecular-orbital viewers.
- Use [&MO_KP](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_KP) when the calculation uses k-points and a
post-processing tool needs k-point-resolved coefficients.
- Use [&TREXIO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.TREXIO) when a structured HDF5 orbital file is
needed for interoperability with external quantum-chemistry tools.
- Use [&MO_CUBES](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_CUBES) or
[&MO_OPENPMD](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO_OPENPMD) for real-space visualization of a small
number of selected orbitals.
- Use [&MO](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.MO) for compact textual inspection and debugging.
Reference in a new issue View git blame Copy permalink