Skip to content

Geometry and samples

A physical calculation starts with an ordered set of atoms and its boundary conditions. Geometry describes that system, including optional input atomic magnetic moments. Sample associates one geometry with named physical quantities and the basis sets needed to interpret them.

A sample can contain both Cartesian quantities, such as energies and forces, and electronic quantities expressed in orbital or real-space form. ElectronicQuantity associates electronic data with a basis role when one is needed. Dataset membership and sample identifiers are managed outside these physical objects.

Geometry dataclass 

Geometry(
    atomic_numbers: ArrayLike,
    positions: ArrayLike,
    cell: ArrayLike | None = None,
    pbc: ArrayLike = False,
    *,
    magmoms: ArrayLike | None = None,
)

Ordered atomic structure with boundary conditions and optional magnetic input.

Atom order is significant and defines the atom indices used by associated physical data.

Parameters:

  • atomic_numbers (ArrayLike) –

    Non-empty positive atomic numbers with shape (n_atoms,).

  • positions (ArrayLike) –

    Cartesian coordinates in Å with shape (n_atoms, 3).

  • cell (ArrayLike | None, default: None ) –

    Cartesian cell vectors in Å as the rows of a (3, 3) matrix. Omission gives a zero matrix. Rows selected by pbc must be linearly independent; inactive rows may be zero.

  • pbc (ArrayLike, default: False ) –

    Boolean periodic-axis flags. A scalar applies to every axis; otherwise the value must have shape (3,). Omission gives no periodic axes.

  • magmoms (ArrayLike | None, default: None ) –

    Optional input atomic magnetic moments in μB. Signed collinear moments have shape (n_atoms,); noncollinear Cartesian moments have shape (n_atoms, 3).

rotated 

rotated(rotation: ArrayLike, *, spin_rotation: bool | ArrayLike = False) -> Geometry

Return the geometry after an active orthogonal transformation.

spin_rotation=False leaves magnetic moments fixed in spin space. True applies the joint axial-vector action det(Q) Q, while a proper 3 × 3 matrix supplies an independent spin rotation. Collinear magnetic moments only support the default fixed spin axis.

Sample dataclass 

Sample(
    geometry: Geometry,
    electronic_quantities: dict[str, ElectronicQuantity] = dict(),
    basis_sets: dict[str, BasisSet] = dict(),
    atomistic_quantities: dict[str, AtomisticQuantity] = dict(),
)

One geometry and its selected atomistic and electronic quantities.

Dataset membership and its stable sample ID are assigned outside this physical object.

ElectronicQuantity dataclass 

ElectronicQuantity(
    data: BlockSparseOrbMatrix
    | HermBlockSparseOrbMatrix
    | OrbMatrix
    | OrbVector
    | Volumetric,
    basis_role: str | None = None,
)

One electronic quantity and the atom-centered basis role it uses.

basis_role is an open string key into Sample.basis_sets. Common conventional names include ao, aux, and paw_coupled.

Neighbor search identifies atom pairs within a chosen cutoff. The resulting connectivity is computed from geometry for a particular use; it is not stored as part of Geometry.

neighbor_list 

neighbor_list(
    quantities: str,
    positions: NDArray[float32] | NDArray[float64],
    cell: NDArray[float32] | NDArray[float64],
    pbc: NDArray[bool_],
    cutoff: float,
    batch_ptr: NDArray[int64] | None = None,
    *,
    algorithm: Literal["auto", "brute_force", "cell_list"] = "auto",
    cpu_threads: int | None = None,
    sorted: bool = False,
    half_list: bool = False,
    include_self: bool = False,
) -> tuple[ndarray, ...]

Build an atomistic neighbor list within a strict distance cutoff.

Parameters:

  • quantities (str) –

    String selecting the returned quantities and their order. The supported characters are "i" for source indices, "j" for target indices, "P" for paired indices, "S" for integer cell shifts, "d" for distances, and "D" for displacement vectors. Characters may be repeated. An empty string returns an empty tuple.

  • positions (NDArray[float32] | NDArray[float64]) –

    Atomic Cartesian positions. For one structure, use an (n_atoms, 3) NumPy array. For a batch, concatenate all positions into (n_total_atoms, 3). The dtype must be float32 or float64. All values must be finite.

  • cell (NDArray[float32] | NDArray[float64]) –

    Cartesian cell vectors stored as rows. Use shape (3, 3) when batch_ptr is None and (n_structures, 3, 3) for a batch. Its floating dtype must match positions. All values must be finite. For every nonempty structure, the rows enabled by pbc must be linearly independent; inactive rows and the full cell may be rank deficient.

  • pbc (NDArray[bool_]) –

    Periodic boundary flags for the three cell rows. Use shape (3,) for one structure and (n_structures, 3) for a batch. The dtype must be bool.

  • cutoff (float) –

    Strict, finite, positive distance cutoff. positions, cell, and cutoff must use the same length unit.

  • batch_ptr (NDArray[int64] | None, default: None ) –

    Optional int64 structure boundaries in the concatenated positions, with shape (n_structures + 1,). It must start at zero, be nondecreasing, and end at n_total_atoms. None denotes one structure and is equivalent to [0, n_atoms]. Its dtype must be int64.

  • algorithm (Literal['auto', 'brute_force', 'cell_list'], default: 'auto' ) –

    Search method. "auto" (default) selects a backend- appropriate method. "brute_force" exhaustively checks every relevant atom pair. "cell_list" partitions space so that atoms only inspect nearby regions.

  • cpu_threads (int | None, default: None ) –

    Number of CPU threads used by this call, including the calling thread. A positive integer explicitly selects the thread count. None uses the conservative CPU default of one thread. CPU workers are reused across calls.

  • sorted (bool, default: False ) –

    If True, sort pairs by source index. The order of target indices and cell shifts within each source is unspecified. The default is False.

  • half_list (bool, default: False ) –

    If False (default), return the full directed list. If True, retain the lexicographically smaller of (source, target, Sx, Sy, Sz) and (target, source, -Sx, -Sy, -Sz).

  • include_self (bool, default: False ) –

    Whether to include exactly one zero-shift self pair (i, i, [0, 0, 0]) for every atom. The default is False.

Returns:

  • ndarray –

    A tuple containing one array for each character in quantities, in

  • ... –

    the same order. If n_edges pairs are found:

  • tuple[ndarray, ...] –
    • i and j have dtype int64 and shape (n_edges,).
  • tuple[ndarray, ...] –
    • P has dtype int64 and shape (n_edges, 2); its columns are
  • tuple[ndarray, ...] –

    source and target.

  • tuple[ndarray, ...] –
    • S has dtype int32 and shape (n_edges, 3) and translates
  • tuple[ndarray, ...] –

    the target image.

  • tuple[ndarray, ...] –
    • d has the input floating dtype and shape (n_edges,).
  • tuple[ndarray, ...] –
    • D has the input floating dtype and shape (n_edges, 3).
  • tuple[ndarray, ...] –

    For pair k in structure b, D[k] is

  • tuple[ndarray, ...] –

    positions[target[k]] - positions[source[k]] + S[k] @ cell[b].

  • tuple[ndarray, ...] –

    For a single structure, use cell directly.

Raises:

  • TypeError –

    If quantities or algorithm is not a string; cpu_threads is neither None nor a Python int; or a boolean option is not a Python bool.

  • ValueError –

    If quantities contains an unsupported character; algorithm is unsupported; or frontend shapes, dtypes, batch_ptr, cutoff, cpu_threads, periodic cells, or host-validated index/resource bounds are invalid.

  • RuntimeError –

    If the required native CPU extension is missing; if native search discovers nonfinite positions or a representative wrap/output shift outside its integer range; if an explicitly requested cell list cannot safely process the input; or if backend execution otherwise fails.

Note

The result contains atom-image pairs whose squared distance is strictly less than cutoff**2. half_list=False returns both directions: pair (source, target, S) has reverse pair (target, source, -S). A zero-shift self pair is controlled only by include_self. Periodic self-images remain ordinary cutoff pairs, and multiple periodic images are retained. Pairs never cross structures, shifts along inactive pbc axes are zero. Output order is unspecified unless sorted=True.

Example 
>>> import numpy as np
>>> from elfes.physics import neighbor_list
>>> positions = np.array([[0.0, 0.0, 0.0], [0.8, 0.0, 0.0]])
>>> cell = np.eye(3) * 4.0
>>> pbc = np.zeros(3, dtype=np.bool_)
>>> pairs, shifts, distances = neighbor_list(
...     "PSd", positions, cell, pbc, cutoff=1.0
... )
>>> pairs.shape, shifts.shape, distances.tolist()
((2, 2), (2, 3), [0.8, 0.8])