qimpy.lattice.Lattice

class Lattice(*, checkpoint_in=(None, ''), system=None, modification=None, a=None, b=None, c=None, alpha=None, beta=None, gamma=None, vector1=None, vector2=None, vector3=None, scale=Default(1.0), compute_stress=Default(False), movable=Default(False), move_scale=Default((1.0, 1.0, 1.0)), periodic=Default((True, True, True)), center=Default((0.0, 0.0, 0.0)))

Bases: TreeNode

Real and reciprocal space lattice vectors

Parameters:

• checkpoint_in (CheckpointPath) –

• system (Optional[str]) –

• modification (Optional[str]) –

• a (Optional[float]) –

• b (Optional[float]) –

• c (Optional[float]) –

• alpha (Optional[float]) –

• beta (Optional[float]) –

• gamma (Optional[float]) –

• vector1 (Optional[Sequence[float]]) –

• vector2 (Optional[Sequence[float]]) –

• vector3 (Optional[Sequence[float]]) –

• scale (Union[float, Sequence[float], Default[float]]) –

• compute_stress (bool) –

• movable (bool) –

• move_scale (Tensor) –

• periodic (tuple[bool, bool, bool]) –

• center (Tensor) –

__init__(*, checkpoint_in=(None, ''), system=None, modification=None, a=None, b=None, c=None, alpha=None, beta=None, gamma=None, vector1=None, vector2=None, vector3=None, scale=Default(1.0), compute_stress=Default(False), movable=Default(False), move_scale=Default((1.0, 1.0, 1.0)), periodic=Default((True, True, True)), center=Default((0.0, 0.0, 0.0)))

Initialize from lattice vectors or lengths and angles. Either specify a lattice system and optional modification, along with any corresponding required lengths (a, b, c) and angles (alpha, beta, gamma), or explicitly specity all three lattice vectors vector1, vector2 and vector3. Optionally, scale lattice vectors by a single or separate factors.

Parameters:

• system (str | None) –

  [Input file] Specify crystal system and geometry parameters. Options include:

  • cubic (specify a),

  • tetragonal (specify a, c)

  • orthorhombic (specify a, b, c)

  • hexagonal (specify a, c)

  • rhombohedral (specify a, alpha)

  • monoclinic (specify a, b, c, beta)

  • triclinic (specify a, b, c, alpha, beta, gamma)

• modification (str | None) –

  [Input file] Specify modification of lattice. Options include:

  • body-centered (only for orthorhombic, tetragonal or cubic)

  • face-centered (only for orthorhombic or cubic)

  • base-centered (only for monoclinic)

• a (float | None) – [Input file] First lattice vector length in bohrs.

• b (float | None) – [Input file] Second lattice vector length in bohrs.

• c (float | None) – [Input file] Third lattice vector length in bohrs.

• alpha (float | None) – [Input file] Angle between b and c in degrees.

• beta (float | None) – [Input file] Angle between c and a in degrees.

• gamma (float | None) – [Input file] Angle between a and b in degrees.

• vector1 (Sequence[float] | None) – [Input file] First lattice vector (x1, y1, z1) in bohrs.

• vector2 (Sequence[float] | None) – [Input file] Second lattice vector (x2, y2, z2) in bohrs.

• vector3 (Sequence[float] | None) – [Input file] Third lattice vector (x3, y3, z3) in bohrs.

• scale (float | Sequence[float] | Default[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 | Default[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 | Default[bool]) – [Input file] Whether to move lattice during geometry relaxation / dynamics.

• move_scale (Sequence[float] | Default[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] | Default[tuple[bool, bool, bool]]) – [Input file] Whether each lattice direction is periodic. Set to False for some directions for lower-dimensional / no periodicity.

• center (Sequence[float] | Default[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.

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