Skip to content

kups.application.potential.classical.ewald

State-binding constructors for Ewald potentials.

These adapters take a :class:~kups.core.lens.Lens into a concrete simulation state and wire its particles, systems, neighbor list, and parameters into the state-agnostic factories in kups.potential.classical.ewald.

Parameters may live on the state (state.ewald_parameters) or be passed directly via parameters=; in the latter case they are bound with a constant lens and the state need not carry a parameter field. For incremental (probe) updates with constant parameters, the cache is read from a conventional ewald_cache attribute.

IsCachedEwaldGraphState

Bases: IsEwaldGraphState, Protocol

:class:IsEwaldGraphState carrying an incremental-update cache (params passed in).

Source code in src/kups/application/potential/classical/ewald.py 
69
70
71
72
73
class IsCachedEwaldGraphState[Cache](IsEwaldGraphState, Protocol):
    """:class:`IsEwaldGraphState` carrying an incremental-update cache (params passed in)."""

    @property
    def ewald_cache(self) -> Cache: ...

IsEwaldGraphState

Bases: IsState[IsEwaldPointData, HasCell[Periodic3D]], IsNeighborListState[IsUniversalNeighborlistParams], Protocol

Particles, systems, and neighbor list for an Ewald graph (no parameters).

Source code in src/kups/application/potential/classical/ewald.py 
54
55
56
57
58
59
class IsEwaldGraphState(
    IsState[IsEwaldPointData, HasCell[Periodic3D]],
    IsNeighborListState[IsUniversalNeighborlistParams],
    Protocol,
):
    """Particles, systems, and neighbor list for an Ewald graph (no parameters)."""

IsEwaldState

Bases: IsEwaldGraphState, Protocol

:class:IsEwaldGraphState that also carries Ewald parameters on the state.

Source code in src/kups/application/potential/classical/ewald.py 
62
63
64
65
66
class IsEwaldState[Params](IsEwaldGraphState, Protocol):
    """:class:`IsEwaldGraphState` that also carries Ewald parameters on the state."""

    @property
    def ewald_parameters(self) -> Params: ...

make_ewald_from_state(state, probe=None, *, parameters=None, gradient=None, include_exclusion_mask=False, composition=None, neighborlist_factory=AdaptiveNeighborList.from_state) 

make_ewald_from_state(
    state: Lens[
        State,
        IsEwaldState[MaybeCached[EwaldParameters, Any]],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: None = None,
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[
        State, IsChargedTemplate
    ]
    | None = None,
    neighborlist_factory: NeighborListFactory[
        IsEwaldState[MaybeCached[EwaldParameters, Any]]
    ] = ...,
) -> EwaldPotential[
    State, EmptyType, EmptyType, Patch[Any]
]

make_ewald_from_state(
    state: Lens[
        State,
        IsEwaldState[MaybeCached[EwaldParameters, Any]],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: Lens[Geometry, PositionsAndCell],
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[
        State, IsChargedTemplate
    ]
    | None = None,
    neighborlist_factory: NeighborListFactory[
        IsEwaldState[MaybeCached[EwaldParameters, Any]]
    ] = ...,
) -> EwaldPotential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

make_ewald_from_state(
    state: Lens[
        State,
        IsEwaldState[
            HasCache[
                EwaldParameters,
                EwaldCache[EmptyType, EmptyType],
            ]
        ],
    ],
    probe: Probe[
        State, P, IsParticleProbe[IsEwaldPointData]
    ],
    *,
    parameters: None = None,
    gradient: None = None,
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[
        State, IsChargedTemplate
    ]
    | None = None,
    neighborlist_factory: NeighborListFactory[
        IsEwaldState[
            HasCache[
                EwaldParameters,
                EwaldCache[EmptyType, EmptyType],
            ]
        ]
    ] = ...,
) -> EwaldPotential[State, EmptyType, EmptyType, P]

make_ewald_from_state(
    state: Lens[
        State,
        IsEwaldState[
            HasCache[
                EwaldParameters,
                EwaldCache[PositionsAndCell, EmptyType],
            ]
        ],
    ],
    probe: Probe[
        State, P, IsParticleProbe[IsEwaldPointData]
    ],
    *,
    parameters: None = None,
    gradient: Lens[Geometry, PositionsAndCell],
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[
        State, IsChargedTemplate
    ]
    | None = None,
    neighborlist_factory: NeighborListFactory[
        IsEwaldState[
            HasCache[
                EwaldParameters,
                EwaldCache[PositionsAndCell, EmptyType],
            ]
        ]
    ] = ...,
) -> EwaldPotential[State, PositionsAndCell, EmptyType, P]

make_ewald_from_state(
    state: Lens[State, IsEwaldGraphState],
    probe: None = None,
    *,
    parameters: EwaldParameters,
    gradient: None = None,
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[
        State, IsChargedTemplate
    ]
    | None = None,
    neighborlist_factory: NeighborListFactory[
        IsEwaldGraphState
    ] = ...,
) -> EwaldPotential[
    State, EmptyType, EmptyType, Patch[Any]
]

make_ewald_from_state(
    state: Lens[State, IsEwaldGraphState],
    probe: None = None,
    *,
    parameters: EwaldParameters,
    gradient: Lens[Geometry, PositionsAndCell],
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[
        State, IsChargedTemplate
    ]
    | None = None,
    neighborlist_factory: NeighborListFactory[
        IsEwaldGraphState
    ] = ...,
) -> EwaldPotential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

make_ewald_from_state(
    state: Lens[
        State,
        IsCachedEwaldGraphState[
            EwaldCache[EmptyType, EmptyType]
        ],
    ],
    probe: Probe[
        State, P, IsParticleProbe[IsEwaldPointData]
    ],
    *,
    parameters: EwaldParameters,
    gradient: None = None,
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[
        State, IsChargedTemplate
    ]
    | None = None,
    neighborlist_factory: NeighborListFactory[
        IsCachedEwaldGraphState[
            EwaldCache[EmptyType, EmptyType]
        ]
    ] = ...,
) -> EwaldPotential[State, EmptyType, EmptyType, P]

make_ewald_from_state(
    state: Lens[
        State,
        IsCachedEwaldGraphState[
            EwaldCache[PositionsAndCell, EmptyType]
        ],
    ],
    probe: Probe[
        State, P, IsParticleProbe[IsEwaldPointData]
    ],
    *,
    parameters: EwaldParameters,
    gradient: Lens[Geometry, PositionsAndCell],
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[
        State, IsChargedTemplate
    ]
    | None = None,
    neighborlist_factory: NeighborListFactory[
        IsCachedEwaldGraphState[
            EwaldCache[PositionsAndCell, EmptyType]
        ]
    ] = ...,
) -> EwaldPotential[State, PositionsAndCell, EmptyType, P]

Create an Ewald potential from a typed state, optionally with incremental updates.

When probe is None, builds a static potential by extracting components directly from the state. When a probe is provided, the potential supports incremental (cached) evaluation via the probe's patch mechanism.

Parameters:

Name Type Description Default
state Any

Lens focusing on the Ewald state (particles, systems, neighborlist, plus ewald_parameters when parameters is not given).

 required
probe Any

Probe for incremental updates. None for a static potential.

 None
parameters EwaldParameters | None

Constant Ewald parameters. When given they are bound with a constant lens and the state need not carry ewald_parameters; with a probe, the cache is read from state.ewald_cache.

 None
gradient Lens[Geometry, Any] | None

Relaxation filter Lens[Geometry, PositionsAndCell] selecting the optimizer DOFs to differentiate. Composed with the PointCloud-to-Geometry adapter; None computes no gradients.

 None
include_exclusion_mask bool

Whether to include the exclusion correction term in the returned potential.

 False
composition RigidBodyComposition[Any, IsChargedTemplate] | None

Optional rigid-body templates and counts for energy-only self and exclusion terms.

 None

Returns:

Type Description
Any

An EwaldPotential combining short-range, long-range,
Any

self-energy, and (optionally) exclusion-correction terms.
Source code in src/kups/application/potential/classical/ewald.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
def make_ewald_from_state(
    state: Any,
    probe: Any = None,
    *,
    parameters: EwaldParameters | None = None,
    gradient: Lens[Geometry, Any] | None = None,
    include_exclusion_mask: bool = False,
    composition: RigidBodyComposition[Any, IsChargedTemplate] | None = None,
    neighborlist_factory: NeighborListFactory[Any] = AdaptiveNeighborList.from_state,
) -> Any:
    """Create an Ewald potential from a typed state, optionally with incremental updates.

    When ``probe`` is ``None``, builds a static potential by extracting
    components directly from the state.  When a probe is provided, the
    potential supports incremental (cached) evaluation via the probe's
    patch mechanism.

    Args:
        state: Lens focusing on the Ewald state (particles, systems,
            neighborlist, plus ``ewald_parameters`` when ``parameters`` is not
            given).
        probe: Probe for incremental updates. ``None`` for a static
            potential.
        parameters: Constant Ewald parameters. When given they are bound with a
            constant lens and the state need not carry ``ewald_parameters``;
            with a ``probe``, the cache is read from ``state.ewald_cache``.
        gradient: Relaxation filter ``Lens[Geometry, PositionsAndCell]`` selecting
            the optimizer DOFs to differentiate. Composed with the
            ``PointCloud``-to-``Geometry`` adapter; ``None`` computes no
            gradients.
        include_exclusion_mask: Whether to include the exclusion
            correction term in the returned potential.
        composition: Optional rigid-body templates and counts for
            energy-only self and exclusion terms.

    Returns:
        An ``EwaldPotential`` combining short-range, long-range,
        self-energy, and (optionally) exclusion-correction terms.
    """
    gradient_lens: Any = EMPTY_LENS
    patch_idx_view = empty_patch_idx_view
    if gradient is not None:
        gradient_lens = POINTCLOUD_GEOMETRY.nest(gradient)
        patch_idx_view = position_and_cell_idx_view
    if parameters is not None:
        param_view = const_lens(parameters)
    else:
        param_view = state.focus(
            lambda x: (
                x.ewald_parameters.data
                if isinstance(x.ewald_parameters, HasCache)
                else x.ewald_parameters
            )
        )
    cache_view = None
    if probe is not None:
        if parameters is None:
            param_view = state.focus(lambda x: x.ewald_parameters.data)
            cache_view = state.focus(lambda x: x.ewald_parameters.cache)
        else:
            cache_view = state.focus(lambda x: x.ewald_cache)

    def neighborlist_view(s: Any) -> NeighborList[Literal[2]]:
        return neighborlist_factory(state(s), param_view(s).cutoff)

    return make_ewald_potential(
        state.focus(lambda x: x.particles),
        state.focus(lambda x: x.systems),
        neighborlist_view,
        param_view,
        cache_view,
        probe,
        gradient_lens,
        EMPTY_LENS,
        EMPTY_LENS,
        patch_idx_view=patch_idx_view,
        include_exclusion_mask=include_exclusion_mask,
        composition=composition,
    )