qimpy.lattice.Lattice

class Lattice(*, checkpoint_in=(None, ''), system=None, vectors=None, Rbasis=None, scale=1.0, compute_stress=False, movable=False, move_scale=(1.0, 1.0, 1.0), periodic=(True, True, True), center=(0.0, 0.0, 0.0))

Bases: TreeNode

Real and reciprocal space lattice vectors

Parameters:

checkpoint_in (CheckpointPath)
system (Optional[dict])
vectors (Optional[TensorCompatible])
Rbasis (Tensor)
scale (TensorCompatible)
compute_stress (bool)
movable (bool)
move_scale (Tensor)
periodic (tuple[bool, bool, bool])
center (Tensor)

__init__(*, checkpoint_in=(None, ''), system=None, vectors=None, Rbasis=None, scale=1.0, compute_stress=False, movable=False, move_scale=(1.0, 1.0, 1.0), periodic=(True, True, True), center=(0.0, 0.0, 0.0))

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.

Parameters:

system (dict | None) –

[Input file] 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 None (null in yaml), the unmodified Bravais lattice is selected.

vectors (Tensor | ndarray | float | Sequence[float] | None) – [Input file] 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 (Tensor | ndarray | float | Sequence[float] | None) – [Input file] Real-space basis vectors in columns. Overall, the 3 x 3 transformation from fractional to Cartesian coordinates.
scale (Tensor | ndarray | float | Sequence[float]) – [Input file] 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 (bool) – [Input file] 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 (bool) – [Input file] Whether to move lattice during geometry relaxation / dynamics.
move_scale (Tensor | ndarray | float | Sequence[float]) – [Input file] 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 (tuple[bool, bool, bool]) – [Input file] Whether each lattice direction is periodic. Set to False for some directions for lower-dimensional / no periodicity.
center (Tensor | ndarray | float | Sequence[float]) – [Input file] Center of cell for periodicity break along non-periodic directions. In fractional coordinates, and values along periodic directions are irrelevant.
checkpoint_in (CheckpointPath)

Return type:

None

Methods

`__init__`	Initialize from lattice vectors or lengths and angles.
`add_child`	Construct child object self.`attr_name` of type cls.
`add_child_one_of`	Invoke add_child on one of several child options in args.
`report`	Report lattice vectors, and optionally stress if report_grad.
`requires_grad_`	Set whether gradient with respect to this object is needed.
`save_checkpoint`	Save self and all children in hierarchy to cp_path.
`update`	Update lattice vectors and dependent quantities.

Attributes

`invGbasis`	Inverse of Gbasis.
`invGbasisT`	Inverse transpose of Gbasis.
`invRbasis`	Inverse of Rbasis.
`invRbasisT`	Inverse transpose of Rbasis.
`requires_grad`	Return whether gradient with respect to this object is needed.
`stress`	Cartesian stress tensor [in Eh/a0^3] (3 x 3).
`Rbasis`	Real-space lattice vectors (in columns)
`Gbasis`	Reciprocal-space lattice vectors (in columns)
`volume`	Unit cell volume
`compute_stress`	Whether to compute and report stress
`grad`	= dE/dRbasis @ Rbasis.T
`strain_rate`	Strain rate (for lattice-movable dynamics)
`movable`	Whether lattice can be moved in geometry relaxation / dynamics
`move_scale`	Scale factors to precondition / constrain lattice move
`periodic`	Whether each direction is periodic
`center`	Center (fractional coords) for non-periodic directions
`child_names`	Names of attributes with child objects.
`variant_name`	Version of children having variants (if any)

report(report_grad)

Report lattice vectors, and optionally stress if report_grad.

Parameters:: report_grad (bool)
Return type:: None

requires_grad_(requires_grad=True, clear=False)

Set whether gradient with respect to this object is needed.. If clear, also clear previous gradient / set to zero as needed.

Parameters:

requires_grad (bool)
clear (bool)

Return type:

None

update(Rbasis, report_change=True, center=None)

Update lattice vectors and dependent quantities. If report_change is True, report the relative change of lattice and volume.

Parameters:

Rbasis (Tensor)
report_change (bool)
center (Tensor | None)

Return type:

None

Gbasis: Tensor: Reciprocal-space lattice vectors (in columns)

Rbasis: Tensor: Real-space lattice vectors (in columns)

center: Tensor: Center (fractional coords) for non-periodic directions

compute_stress: bool: Whether to compute and report stress

grad: Tensor

= dE/dRbasis @ Rbasis.T

Type:: Lattice gradient of energy

property invGbasis: Tensor: Inverse of Gbasis.

property invGbasisT: Tensor: Inverse transpose of Gbasis.

property invRbasis: Tensor: Inverse of Rbasis.

property invRbasisT: Tensor: Inverse transpose of Rbasis.

movable: bool: Whether lattice can be moved in geometry relaxation / dynamics

move_scale: Tensor: Scale factors to precondition / constrain lattice move

periodic: tuple[bool, bool, bool]: Whether each direction is periodic

property requires_grad: bool: Return whether gradient with respect to this object is needed.

strain_rate: Tensor | None: Strain rate (for lattice-movable dynamics)

property stress: Tensor: Cartesian stress tensor [in Eh/a0^3] (3 x 3). Converted from grad, which should already have been calculated.

volume: float: Unit cell volume