Skip to content

kups.application.potential.classical.morse

State-binding constructors for Morse bond potentials.

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

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

IsCachedMorseBondGraphState

Bases: IsMorseBondGraphState, Protocol

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

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

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

IsMorseBondGraphState

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

Particles, systems, and bond indices for a Morse bond (no parameters).

Source code in src/kups/application/potential/classical/morse.py 
47
48
49
50
51
52
53
class IsMorseBondGraphState(
    IsState[IsBondedParticles, HasCell[AnyPeriodicity]], Protocol
):
    """Particles, systems, and bond indices for a Morse bond (no parameters)."""

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

IsMorseBondState

Bases: IsMorseBondGraphState, Protocol

:class:IsMorseBondGraphState that also carries Morse bond parameters.

Source code in src/kups/application/potential/classical/morse.py 
56
57
58
59
60
class IsMorseBondState[Params](IsMorseBondGraphState, Protocol):
    """:class:`IsMorseBondGraphState` that also carries Morse bond parameters."""

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

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

make_morse_bond_from_state(
    state: Lens[
        State,
        IsMorseBondState[
            MaybeCached[MorseBondParameters, Any]
        ],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

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

make_morse_bond_from_state(
    state: Lens[
        State,
        IsMorseBondState[
            HasCache[
                MorseBondParameters,
                PotentialOut[EmptyType, EmptyType],
            ]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[2]],
    ],
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, P]

make_morse_bond_from_state(
    state: Lens[
        State,
        IsMorseBondState[
            HasCache[
                MorseBondParameters,
                PotentialOut[PositionsAndCell, EmptyType],
            ]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[2]],
    ],
    *,
    parameters: None = None,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[State, PositionsAndCell, EmptyType, P]

make_morse_bond_from_state(
    state: Lens[State, IsMorseBondGraphState],
    probe: None = None,
    *,
    parameters: MorseBondParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

make_morse_bond_from_state(
    state: Lens[State, IsMorseBondGraphState],
    probe: None = None,
    *,
    parameters: MorseBondParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

make_morse_bond_from_state(
    state: Lens[
        State,
        IsCachedMorseBondGraphState[
            PotentialOut[EmptyType, EmptyType]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[2]],
    ],
    *,
    parameters: MorseBondParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, P]

make_morse_bond_from_state(
    state: Lens[
        State,
        IsCachedMorseBondGraphState[
            PotentialOut[PositionsAndCell, EmptyType]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[2]],
    ],
    *,
    parameters: MorseBondParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[State, PositionsAndCell, EmptyType, P]

Create a Morse bond potential from a typed state, optionally with incremental updates.

Parameters:

Name Type Description Default
state Any

Lens into the sub-state providing particles, cell, and bond indices (plus morse_bond_parameters 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 MorseBondParameters | None

Constant Morse bond parameters. When given they are bound with a constant lens and the state need not carry morse_bond_parameters; with a probe, the cache is read from state.morse_bond_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 Morse bond Potential.
Source code in src/kups/application/potential/classical/morse.py 
162
163
164
165
166
167
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
def make_morse_bond_from_state(
    state: Any,
    probe: Any = None,
    *,
    parameters: MorseBondParameters | None = None,
    gradient: Lens[Geometry, PositionsAndCell] | None = None,
) -> Any:
    """Create a Morse bond potential from a typed state, optionally with incremental updates.

    Args:
        state: Lens into the sub-state providing particles, cell, and bond
            indices (plus ``morse_bond_parameters`` 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 Morse bond parameters. When given they are bound
            with a constant lens and the state need not carry
            ``morse_bond_parameters``; with a ``probe``, the cache is read from
            ``state.morse_bond_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 Morse bond [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.morse_bond_parameters.data
                if isinstance(x.morse_bond_parameters, HasCache)
                else x.morse_bond_parameters
            )
        )
    cache_view = None
    if probe is not None:
        if parameters is None:
            param_view = state.focus(lambda x: x.morse_bond_parameters.data)
            cache_view = state.focus(lambda x: x.morse_bond_parameters.cache)
        else:
            cache_view = state.focus(lambda x: x.morse_bond_cache)
        patch_idx_view = patch_idx_view or empty_patch_idx_view
    return make_morse_bond_potential(
        state.focus(lambda x: x.particles),
        state.focus(lambda x: x.bond_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,
    )