Skip to content

kups.potential.common.geometry

Geometric-view types shared by gradient filters and the gradient machinery.

Geometry is the Table-based projection of any carrier's particles and systems (per-particle position + system index, per-system cell). A relaxation filter is a Lens[Geometry, U] selecting the optimizer's degrees of freedom; the concrete filters live in kups.application.potential.filter, while the adapters that build a Geometry from a carrier live with their carriers (GRAPH_GEOMETRY in kups.potential.common.graph, pointcloud_geometry in kups.potential.classical.ewald).

Geometry

Bases: NamedTuple

Shared domain of geometric gradient lenses, built from any carrier.

Source code in src/kups/potential/common/geometry.py 
33
34
35
36
37
class Geometry(NamedTuple):
    """Shared domain of geometric gradient lenses, built from any carrier."""

    particles: Table[ParticleId, PositionsAndSystemIndex]
    systems: Table[SystemId, Cell[AnyPeriodicity]]

PositionsAndCell

Bases: NamedTuple

Optimizer DOFs / gradient payload of the standard cell filters.

positions is a per-particle table of DOF coordinates (∂E/∂r when this carries a gradient); cell is a per-system table of the cell (its frame parameters carrying ∂E/∂h for a gradient).

Source code in src/kups/potential/common/geometry.py 
40
41
42
43
44
45
46
47
48
49
class PositionsAndCell(NamedTuple):
    """Optimizer DOFs / gradient payload of the standard cell filters.

    ``positions`` is a per-particle table of DOF coordinates (``∂E/∂r`` when this
    carries a gradient); ``cell`` is a per-system table of the cell (its frame
    parameters carrying ``∂E/∂h`` for a gradient).
    """

    positions: Table[ParticleId, Array]
    cell: Table[SystemId, Cell[AnyPeriodicity]]

PositionsAndSystemIndex

Bases: NamedTuple

Per-particle geometric data: cartesian positions + system assignment.

Source code in src/kups/potential/common/geometry.py 
26
27
28
29
30
class PositionsAndSystemIndex(NamedTuple):
    """Per-particle geometric data: cartesian positions + system assignment."""

    positions: Array
    system: Index[SystemId]

position_and_cell_idx_view(state)

Patch index structure matching the PositionsAndCell filter codomain.

The per-particle system index masks the position rows and the systems index masks every Cell leaf.

Source code in src/kups/potential/common/geometry.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
@no_type_check
def position_and_cell_idx_view(
    state: IsStateWithParticlesAndCell,
) -> PotentialOut[PositionsAndCell, EmptyType]:
    """Patch index structure matching the ``PositionsAndCell`` filter codomain.

    The per-particle system index masks the position rows and the systems index
    masks every ``Cell`` leaf.
    """
    return PotentialOut(
        empty_patch_idx_view(state).total_energies,
        PositionsAndCell(state.particles.data.system, state.systems.index),
        EMPTY,
    )