nvalchemi.data.transforms.make_supercell#

nvalchemi.data.transforms.make_supercell(data, repeats, *, extensive_keys=DEFAULT_EXTENSIVE_SYSTEM_KEYS, intensive_keys=DEFAULT_INTENSIVE_SYSTEM_KEYS, drop_keys=())[source]#

Return data tiled repeats times along each lattice vector.

The tiling follows ase.Atoms.repeat(). Copies are laid out copy-major, with the first lattice vector’s index running slowest. Each copy is offset by an integer combination of the lattice vectors, and the cell is scaled along each axis. Node-level fields are repeated with the positions, so every atom of a copy keeps the field value of the site it came from. A system-level field is multiplied by the copy count when it is in extensive_keys, carried unchanged when it is in intensive_keys, and refused otherwise. An unclassified field is refused because a supercell scored under a field that does not scale with it would report the mismatch as the model’s error. Edge-level fields, the dense neighbor tensors (neighbor_matrix, neighbor_matrix_shifts, num_neighbors), and any field in drop_keys are left out for the consumer to rebuild: a neighbor index copied into another cell would still point into the first.

Parameters:
  • data (AtomicData) – Periodic structure to replicate, left unmodified.

  • repeats (Sequence[int]) – Three positive replication factors along the lattice vectors. An integral float or a one-element tensor is accepted as a count; a fractional value is refused rather than truncated.

  • extensive_keys (Collection[str], optional) – System-level fields multiplied by the copy count. Default DEFAULT_EXTENSIVE_SYSTEM_KEYS.

  • intensive_keys (Collection[str], optional) – System-level fields carried unchanged. Default DEFAULT_INTENSIVE_SYSTEM_KEYS.

  • drop_keys (Collection[str], optional) – Node- or system-level fields left out of the supercell. Default ().

Returns:

The supercell, carrying every field of data the tiling defines.

Return type:

AtomicData

Raises:

ValueError – If repeats is not three positive integers, if data carries no cell, or if a system-level field is in neither extensive_keys nor intensive_keys and not dropped.

Examples

>>> import torch
>>> from nvalchemi.data import AtomicData
>>> from nvalchemi.data.transforms import make_supercell
>>> data = AtomicData(
...     positions=torch.zeros(1, 3),
...     atomic_numbers=torch.tensor([18]),
...     cell=torch.eye(3).unsqueeze(0) * 4.0,
...     pbc=torch.tensor([[True, True, True]]),
... )
>>> supercell = make_supercell(data, (2, 1, 1))
>>> supercell.positions
tensor([[0., 0., 0.],
        [4., 0., 0.]])
>>> supercell.cell[0, 0]
tensor([8., 0., 0.])