Lattice input documentation

Initialize from lattice vectors or lengths and angles. Either specify a lattice system with any required lengths, angles and modifications, or a set of vectors, or as the basis matrix Rbasis. Exactly one among system, vectors and Rbasis must be specified.

Note that vectors amounts to specifying the vectors in rows in a way that may be common in other codes/interfaces, while Rbasis amounts to specifying them in columns, in the form they are stored internally.

Optionally, scale lattice vectors by a single or separate factors.

Used to initialize class qimpy.lattice.Lattice.

YAML template:

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.

Parameters:

system

Type: dict or null, Default: null

Specify crystal system and geometry parameters. This must be a dictionary matching one of the following patterns (denoted using YAML input-file syntax, and where [ ] indicates optional):

system:
  name: cubic  # all angles are 90 degrees
  a: <value>  # each lattice vector length in bohrs
  [modification: body-centered | face-centered]

system:
  name: tetragonal  # all angles are 90 degrees
  a: <value>  # first two lattice vector lengths in bohrs
  c: <value>  # third lattice vector length in bohrs
  [modification: body-centered]

system:
  name: orthorhombic  # all angles are 90 degrees
  a: <value>  # first lattice vector length in bohrs
  b: <value>  # second lattice vector length in bohrs
  c: <value>  # third lattice vector length in bohrs
  [modification: body-centered | face-centered | base-centered]

system:
  name: hexagonal  # angles are 90, 90 and 120 degrees
  a: <value>  # first two lattice vector lengths in bohrs
  c: <value>  # third lattice vector length in bohrs

system:
  name: rhombohedral
  a: <value>  # each lattice vector length in bohrs
  alpha: <value>  # in radians, all angles equal

system:
  name: monoclinic
  a: <value>  # first lattice vector length in bohrs
  b: <value>  # second lattice vector length in bohrs
  c: <value>  # third lattice vector length in bohrs
  beta: <value>  # angle between a and c in radians, rest 90 degrees
  [modification: base-centered]

system:
  name: triclinic
  a: <value>  # first lattice vector length in bohrs
  b: <value>  # second lattice vector length in bohrs
  c: <value>  # third lattice vector length in bohrs
  alpha: <value>  # angle between b and c in radians
  beta: <value>  # angle between a and c in radians
  gamma: <value>  # angle between a and b in radians

Note that all lengths are in bohrs and angles are in radians. In the input file, use units like Angstrom or nm explicitly for lengths, and deg explicitly for angles, if needed. If the optional modification is unspecified or null (null in yaml), the unmodified Bravais lattice is selected.

vectors

Type: <class ‘torch.Tensor’> or <class ‘numpy.ndarray’> or float or list of float, or null, Default: null

Three lattice vectors, each with (x, y, z) in bohrs. The input is essentially a 3 x 3 matrix, with the vectors in rows.

Rbasis

Type: <class ‘torch.Tensor’> or <class ‘numpy.ndarray’> or float or list of float, or null, Default: null

Real-space basis vectors in columns. Overall, the 3 x 3 transformation from fractional to Cartesian coordinates.

scale

Type: <class ‘torch.Tensor’> or <class ‘numpy.ndarray’> or float or list of float, Default: 1.0

Scale factor for lattice vectors. Either a single number that uniformly scales all lattice vectors or separate factor \([s_1, s_2, s_3]\) for each lattice vector.

compute-stress

Type: bool, Default: no

Whether to compute and report stress. Enable to report stress regardless of whether lattice is movable. (Stresses are always computed when lattice is movable.)

movable

Type: bool, Default: no

Whether to move lattice during geometry relaxation / dynamics.

move-scale

Type: <class ‘torch.Tensor’> or <class ‘numpy.ndarray’> or float or list of float, Default: (1.0, 1.0, 1.0)

Scale factor for moving each lattice vector. Set to zero for some directions to constrain lattice relaxation or dynamics. Can also adjust the magnitude to precondition lattice motion relative to the ions (internal coordinates).

periodic

Type: bool or bool or bool, Default: (yes, yes, yes)

Whether each lattice direction is periodic. Set to no for some directions for lower-dimensional / no periodicity.

center

Type: <class ‘torch.Tensor’> or <class ‘numpy.ndarray’> or float or list of float, Default: (0.0, 0.0, 0.0)

Center of cell for periodicity break along non-periodic directions. In fractional coordinates, and values along periodic directions are irrelevant.