Skip to content

kups.application.potential.classical.inversion

State-binding constructors for UFF-style inversion potentials.

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

Parameters may live on the state (state.inversion_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 inversion_cache attribute.

IsCachedInversionGraphState

Bases: IsInversionGraphState, Protocol

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

Source code in src/kups/application/potential/classical/inversion.py 
63
64
65
66
67
class IsCachedInversionGraphState[Cache](IsInversionGraphState, Protocol):
    """:class:`IsInversionGraphState` carrying an incremental-update cache (params passed in)."""

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

IsInversionGraphState

Bases: IsState[IsBondedParticles, HasCell[AnyPeriodicity]], Protocol

Particles, systems, and inversion connectivity (no parameters).

Source code in src/kups/application/potential/classical/inversion.py 
47
48
49
50
51
52
53
class IsInversionGraphState(
    IsState[IsBondedParticles, HasCell[AnyPeriodicity]], Protocol
):
    """Particles, systems, and inversion connectivity (no parameters)."""

    @property
    def inversion_edge_indices(self) -> Index[ParticleId]: ...

IsInversionState

Bases: IsInversionGraphState, Protocol

:class:IsInversionGraphState that also carries inversion parameters.

Source code in src/kups/application/potential/classical/inversion.py 
56
57
58
59
60
class IsInversionState[Params](IsInversionGraphState, Protocol):
    """:class:`IsInversionGraphState` that also carries inversion parameters."""

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

make_inversion_from_state(state, probe=None, *, parameters=None, gradient=None) 

make_inversion_from_state(
    state: Lens[
        State,
        IsInversionState[
            MaybeCached[InversionParameters, Any]
        ],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

make_inversion_from_state(
    state: Lens[
        State,
        IsInversionState[
            MaybeCached[InversionParameters, Any]
        ],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

make_inversion_from_state(
    state: Lens[
        State,
        IsInversionState[
            HasCache[
                InversionParameters,
                PotentialOut[EmptyType, EmptyType],
            ]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[4]],
    ],
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, P]

make_inversion_from_state(
    state: Lens[
        State,
        IsInversionState[
            HasCache[
                InversionParameters,
                PotentialOut[PositionsAndCell, EmptyType],
            ]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[4]],
    ],
    *,
    parameters: None = None,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[State, PositionsAndCell, EmptyType, P]

make_inversion_from_state(
    state: Lens[State, IsInversionGraphState],
    probe: None = None,
    *,
    parameters: InversionParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

make_inversion_from_state(
    state: Lens[State, IsInversionGraphState],
    probe: None = None,
    *,
    parameters: InversionParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

make_inversion_from_state(
    state: Lens[
        State,
        IsCachedInversionGraphState[
            PotentialOut[EmptyType, EmptyType]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[4]],
    ],
    *,
    parameters: InversionParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, P]

make_inversion_from_state(
    state: Lens[
        State,
        IsCachedInversionGraphState[
            PotentialOut[PositionsAndCell, EmptyType]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[4]],
    ],
    *,
    parameters: InversionParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[State, PositionsAndCell, EmptyType, P]

Create an inversion potential, optionally with incremental updates.

Parameters:

Name Type Description Default
state Any

Lens into the sub-state providing particles, cell, inversion indices, and inversion parameters (the latter only when parameters is not given).

 required
probe Any

If provided, detects particle changes and supplies the before/after fixed-edge neighbor lists for incremental updates. Those neighbor lists carry any required update capacity.

 None
parameters InversionParameters | None

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

 None
gradient Lens[Geometry, PositionsAndCell] | None

Relaxation filter Lens[Geometry, PositionsAndCell] selecting the optimizer DOFs. None computes no gradients (the default). Composed with GRAPH_GEOMETRY into the potential's gradient lens.

 None

Returns:

Type Description
Any

Configured inversion Potential.
Source code in src/kups/application/potential/classical/inversion.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
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
def make_inversion_from_state(
    state: Any,
    probe: Any = None,
    *,
    parameters: InversionParameters | None = None,
    gradient: Lens[Geometry, PositionsAndCell] | None = None,
) -> Any:
    """Create an inversion potential, optionally with incremental updates.

    Args:
        state: Lens into the sub-state providing particles, cell, inversion
            indices, and inversion parameters (the latter only when
            ``parameters`` is not given).
        probe: If provided, detects particle changes and supplies the
            before/after fixed-edge neighbor lists for incremental updates.
            Those neighbor lists carry any required update capacity.
        parameters: Constant inversion parameters. When given they are bound
            with a constant lens and the state need not carry
            ``inversion_parameters``; with a ``probe``, the cache is read from
            ``state.inversion_cache``.
        gradient: Relaxation filter ``Lens[Geometry, PositionsAndCell]`` selecting the
            optimizer DOFs. ``None`` computes no gradients (the default). Composed with
            ``GRAPH_GEOMETRY`` into the potential's gradient lens.

    Returns:
        Configured inversion [Potential][kups.core.potential.Potential].
    """
    gradient_lens: Any = EMPTY_LENS
    patch_idx_view: Any = None
    if gradient is not None:
        gradient_lens = GRAPH_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.inversion_parameters.data
                if isinstance(x.inversion_parameters, HasCache)
                else x.inversion_parameters
            )
        )
    cache_view = None
    if probe is not None:
        if parameters is None:
            param_view = state.focus(lambda x: x.inversion_parameters.data)
            cache_view = state.focus(lambda x: x.inversion_parameters.cache)
        else:
            cache_view = state.focus(lambda x: x.inversion_cache)
        patch_idx_view = patch_idx_view or empty_patch_idx_view
    return make_inversion_potential(
        state.focus(lambda x: x.particles),
        state.focus(lambda x: x.inversion_edge_indices),
        state.focus(lambda x: x.systems),
        param_view,
        probe,
        gradient_lens,
        EMPTY_LENS,
        EMPTY_LENS,
        patch_idx_view=patch_idx_view,
        out_cache_lens=cache_view,
    )