Input file documentation

QimPy uses the YAML format for input files. See below for a complete list of settings. Most settings have sensible defaults: start with the Tutorials to see the most commonly used settings and then use the following as a reference for more information on each setting.

Click on each setting to open a more detailed documentation, and also to link to the corresponding entry in the API Reference. In addition to settings listed below, the special keyword include can be used at any level to effectively load another YAML file into that level of the heirarchy.

lattice:                       # Lattice vectors / unit cell definition:
  system: null                 # Specify crystal system and geometry parameters.
  vectors: null                # Three lattice vectors, each with (x, y, z) in bohrs.
  Rbasis: null                 # Real-space basis vectors in columns.
  scale: 1.0                   # Scale factor for lattice vectors.
  compute-stress: no           # Whether to compute and report stress.
  movable: no                  # Whether to move lattice during geometry relaxation / dynamics.
  move-scale: (1.0, 1.0, 1.0)  # Scale factor for moving each lattice vector.
  periodic: (yes, yes, yes)    # Whether each lattice direction is periodic.
  center: (0.0, 0.0, 0.0)      # Center of cell for periodicity break along non-periodic directions.
                              
ions:                          # Ionic positions and pseudopotentials:
  fractional: yes              # Whether to use fractional coordinates for input/output.
  coordinates: null            # List of [symbol, x, y, z, args] for each ion in unit cell.
  pseudopotentials: null       # Pseudopotential filenames or filename templates.
                              
symmetries:                    # Point and space group symmetries:
  tolerance: 1e-06             # Threshold for detecting symmetries.
  override: null               # Override with identity-only or manual list of operations.
                              
electrons:                     # Electronic sub-system:
  k-mesh:                      # Uniform k-point mesh for Brillouin-zone integration:
    offset: (0.0, 0.0, 0.0)    # Offset of k-point mesh in k-mesh coordinates.
    size: (1, 1, 1)            # Number of k per dimension, or minimum supercell size.
    use-inversion: yes         # Whether to use inversion in k-space to reduce k-points.
                              
  k-path:                      # Path of k-points through Brillouin zone:
    dk: 0.0                    # Maximum distance between adjacent points on k-path.
    points: null               # List of special k-points [kx, ky, kz, label] along path.
                              
  spin-polarized: no           # Whether system has spin polarization / magnetization.
  spinorial: no                # Whether to perform relativistic / spin-orbit calculations.
  fillings:                    # Electron occupations and charge / magnetization control:
    charge: 0.0                # Net charge of electrons + ions in e units.
    smearing: gauss            # Smearing method for setting electron occupations.
    sigma: 0.002               # Width of the smearing function in Hartrees.
    kT: null                   # Specify temperature instead of sigma for Fermi smearing.
    mu: nan                    # Electron chemical potential in Hartrees.
    mu-constrain: no           # Whether to hold chemical potential fixed to mu.
    B: 0.0                     # External magnetic field (only for spin-polarized modes).
    M: 0.0                     # Total magnetization (only for spin-polarized modes).
    M-constrain: no            # Whether to hold magnetization fixed to M.
    n-bands: atomic            # Specify number of bands or scheme to determine it.
    n-bands-extra: x0.1        # Number of extra bands retained by diagonalizers.
                              
  basis:                       # Wavefunction basis set (plane waves):
    ke-cutoff: 20.0            # Wavefunction kinetic energy cutoff in Hartrees.
    real-wavefunctions: no     # Whether to use real wavefunctions (instead of complex).
    grid:                      # Override parameters of grid for wavefunction operations:
      ke-cutoff: null          # Kinetic-energy cutoff for grid in Hartrees.
      shape: null              # Explicit grid dimensions [Nx, Ny, Nz].
                              
    fft-block-size: 0          # Number of wavefunction bands to FFT simultaneously.
    mpi-block-size: 0          # Number of wavefunction bands to MPI transfer simultaneously.
                              
  xc:                          # Exchange-correlation functional:
    functional: gga-pbe        # Name or list of names of exchange-correlation functionals.
    plus-U:                    # Optional DFT+U correction:
      U-values: [dict]         # Dictionary of U values by species and orbital names.
                              
  fixed-H:                     # Fix Hamiltonian from checkpoint file of this name.
  save-wavefunction: yes       # Whether to save wavefunction in checkpoint.
  lcao:                        # Linear combination of atomic orbitals parameters:
    energy-threshold: 1e-06    # Energy convergence threshold in Hartrees.
    gradient-threshold: 1e-08  # Subspace-gradient convergence threshold (dimensionless).
                              
  davidson:                    # Davidson diagonalization of Kohm-Sham Hamiltonian:
    n-iterations: 100          # Number of diagonalization iterations.
    eig-threshold: 1e-08       # Convergence threshold on eigenvalues in Hartrees.
                              
  chefsi:                      # CheFSI diagonalization of Kohm-Sham Hamiltonian:
    n-iterations: 100          # Number of diagonalization iterations.
    eig-threshold: 1e-08       # Convergence threshold on eigenvalues in Hartrees.
    filter-order: 10           # Order of the Chebyshev filter.
    init-threshold: 0.1        # Eigenvalue threshold for initial Davidson steps.
                              
  scf:                         # Self-consistent field (SCF) iteration parameters:
    n-iterations: 50           # Number of self-consistent field iterations / cycles.
    energy-threshold: 1e-08    # Energy convergence threshold in Hartrees.
    residual-threshold: 1e-07  # Residual-norm convergence threshold.
    n-consecutive: 2           # Number of consecutive iterations each threshold must be satisfied.
    n-history: 10              # History size for Pulay mixing.
    mix-fraction: 0.5          # Fraction of new variable mixed into current variable.
    mix-fraction-mag: 1.5      # Different mix_fraction for magnetization components.
    q-kerker: 0.8              # Characteristic wavevector for Kerker mixing.
    q-metric: 0.8              # Characteristic wavevector controlling Pulay metric.
    q-kappa: null              # Long-range cutoff wavevector for grand-canonical SCF.
    n-eig-steps: 2             # Number of inner eigenvalue iterations for each SCF cycle.
    eig-threshold: 1e-08       # Convergence threshold on eigenvalues in Hartrees.
    mix-density: yes           # Whether to mix density or potential.
                              
grid:                          # Charge-density grid:
  ke-cutoff: null              # Kinetic-energy cutoff for grid in Hartrees.
  shape: null                  # Explicit grid dimensions [Nx, Ny, Nz].
                              
geometry:                      # Geometry actions such as relaxation and dynamics:
  fixed:                       # Electronic optimization only at a fixed geometry:
                              
  relax:                       # Geometry relaxation of ions, and optionally, also the lattice:
    n-iterations: 20           # Maximum number of iterations.
    energy-threshold: 5e-05    # Convergence threshold on energy change in Eh.
    fmax-threshold: 0.0005     # Convergence threshold on maximum force in Eh/a0.
    stress-threshold: 1e-05    # Convergence threshold on |stress| (stress tensor norm) in Eh/a0^3.
    n-consecutive: 1           # Number of consecutive iterations each threshold must be satisfied.
    method: l-bfgs             # Relaxation algorithm: L-BFGS, CG or Gradient.
    cg-type: polak-ribiere     # CG variant: Polak-Ribiere, Fletcher-Reeves or Hestenes-Stiefel.
    line-minimize: auto        # Line minimization scheme: Auto, Constant, Quadratic, Wolfe.
    n-history: 15              # Maximum history size (only used for L-BFGS).
    converge-on: all           # Converge on 'any', 'all' or a specific number of thresholds.
    drag-wavefunctions: yes    # Whether to drag atomic components of wavefunctions.
    save-history: yes          # Whether to save history along the trajectory.
                              
  dynamics:                    # Molecular dynamics of ions, and optionally, also the lattice:
    dt: [float]                # Time step.
    n-steps: [int]             # Number of MD steps.
    thermostat:                # Thermostat/barostat method:
      nve:                     # No thermostat (or barostat), i.e. NVE ensemble:
                              
      nose-hoover:             # Nose-Hoover thermostat and/or barostat:
        chain-length-T: 3      # Nose-Hoover chain length for thermostat.
        chain-length-P: 3      # Nose-Hoover chain length for barostat.
                              
      berendsen:               # Berendsen velocity-rescaling thermostat and/or barostat:
        B0: 2.200 GPa          # Characteristic bulk modulus for Berendsen barostat.
                              
      langevin:                # Langevin stochastic thermostat and/or barostat:
                              
    seed: 1234                 # Random seed for initial velocities.
    T0: 298.000 K              # Initial temperature / temperature set point.
    P0: 1.000 bar              # Pressure set point for NPT, if lattice.movable is True.
    stress0: null              # Stress set point for N-stress-T, if lattice.movable is True.
    t-damp-T: 50.000 fs        # Thermostat damping time.
    t-damp-P: 100.000 fs       # Barostat damping time.
    drag-wavefunctions: yes    # Whether to drag atomic components of wavefunctions.
    save-history: yes          # Whether to save history along the trajectory.
                              
export:                        # Export data for other codes:
  bgw:                         # BerkeleyGW export:
    filename: [string]         # Filename for BerkeleyGW output.
                              
checkpoint: null               # Checkpoint file to read at start-up.
checkpoint-out: null           # Checkpoint file to write.

Component classes: