Skip to content

kups.application.utils.particles

Shared particle data structures and ASE loading utilities.

Particles

Particle state shared across simulation types.

Attributes:

Name Type Description
positions Array

Cartesian coordinates in the lower-triangular frame, shape (n_atoms, 3).
masses Array

Atomic masses (amu), shape (n_atoms,).
atomic_numbers Array

Atomic numbers, shape (n_atoms,).
charges Array

Partial charges, shape (n_atoms,).
labels Index[Label]

Per-atom string labels.
system Index[SystemId]

Index mapping each particle to a system.
Source code in src/kups/application/utils/particles.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@dataclass
class Particles:
    """Particle state shared across simulation types.

    Attributes:
        positions: Cartesian coordinates in the lower-triangular frame, shape (n_atoms, 3).
        masses: Atomic masses (amu), shape (n_atoms,).
        atomic_numbers: Atomic numbers, shape (n_atoms,).
        charges: Partial charges, shape (n_atoms,).
        labels: Per-atom string labels.
        system: Index mapping each particle to a system.
    """

    positions: Array
    masses: Array
    atomic_numbers: Array
    charges: Array
    labels: Index[Label]
    system: Index[SystemId]

    @property
    def inclusion(self) -> Index[InclusionId]:
        """System index re-labeled as InclusionId."""
        return Index(tuple(map(InclusionId, self.system.keys)), self.system.indices)

inclusion property

System index re-labeled as InclusionId.

default_exclusion(n)

Build a default per-particle exclusion index (each atom excludes itself).

Parameters:

Name Type Description Default
n int

Number of particles.

 required

Returns:

Type Description
Index[ExclusionId]

Index mapping each particle to a unique ExclusionId.
Source code in src/kups/application/utils/particles.py 
49
50
51
52
53
54
55
56
57
58
def default_exclusion(n: int) -> Index[ExclusionId]:
    """Build a default per-particle exclusion index (each atom excludes itself).

    Args:
        n: Number of particles.

    Returns:
        Index mapping each particle to a unique ExclusionId.
    """
    return Index.integer(jnp.arange(n), n=n, label=ExclusionId)

particles_from_ase(atoms)

Build particle data and cell from an ASE Atoms object or file path.

Results are cached when atoms is a file path.

Parameters:

Name Type Description Default
atoms Atoms | str | Path

ASE Atoms object, or a file path (str/Path) readable by ase.io.read.

 required

Returns:

Type Description
Table[ParticleId, Particles]

Tuple of (particles, cell, uc_transform) where uc_transform
Cell[AnyPeriodicity]

rotates Cartesian positions into the lower-triangular frame.
Source code in src/kups/application/utils/particles.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def particles_from_ase(
    atoms: ase.Atoms | str | Path,
) -> tuple[
    Table[ParticleId, Particles], Cell[AnyPeriodicity], Callable[[Array], Array]
]:
    """Build particle data and cell from an ASE Atoms object or file path.

    Results are cached when ``atoms`` is a file path.

    Args:
        atoms: ASE Atoms object, or a file path (str/Path) readable by
            ``ase.io.read``.

    Returns:
        Tuple of (particles, cell, uc_transform) where uc_transform
        rotates Cartesian positions into the lower-triangular frame.
    """
    if isinstance(atoms, (str, Path)):
        return _particles_from_path(atoms)
    return _particles_from_atoms(atoms)