Skip to content

kups.application.potential.classical.harmonic

State-binding constructors for harmonic bonded potentials.

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

Parameters may live on the state (state.harmonic_bond_parameters / state.harmonic_angle_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 harmonic_bond_cache / harmonic_angle_cache attribute.

IsCachedHarmonicAngleState

Bases: IsHarmonicAngleGraphState, Protocol

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

Source code in src/kups/application/potential/classical/harmonic.py 
259
260
261
262
263
class IsCachedHarmonicAngleState[Cache](IsHarmonicAngleGraphState, Protocol):
    """:class:`IsHarmonicAngleGraphState` carrying an incremental-update cache (params passed in)."""

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

IsCachedHarmonicBondState

Bases: IsHarmonicBondGraphState, Protocol

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

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

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

IsHarmonicAngleGraphState

Bases: HasBondedParticlesAndSystems, Protocol

Particles, systems, and angle indices for a harmonic angle graph (no parameters).

Source code in src/kups/application/potential/classical/harmonic.py 
245
246
247
248
249
class IsHarmonicAngleGraphState(HasBondedParticlesAndSystems, Protocol):
    """Particles, systems, and angle indices for a harmonic angle graph (no parameters)."""

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

IsHarmonicAngleState

Bases: IsHarmonicAngleGraphState, Protocol

:class:IsHarmonicAngleGraphState that also carries angle parameters on the state.

Source code in src/kups/application/potential/classical/harmonic.py 
252
253
254
255
256
class IsHarmonicAngleState[Params](IsHarmonicAngleGraphState, Protocol):
    """:class:`IsHarmonicAngleGraphState` that also carries angle parameters on the state."""

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

IsHarmonicBondGraphState

Bases: HasBondedParticlesAndSystems, Protocol

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

Source code in src/kups/application/potential/classical/harmonic.py 
55
56
57
58
59
class IsHarmonicBondGraphState(HasBondedParticlesAndSystems, Protocol):
    """Particles, systems, and bond indices for a harmonic bond graph (no parameters)."""

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

IsHarmonicBondState

Bases: IsHarmonicBondGraphState, Protocol

:class:IsHarmonicBondGraphState that also carries bond parameters on the state.

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

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

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

make_harmonic_angle_from_state(
    state: Lens[
        State,
        IsHarmonicAngleState[
            MaybeCached[HarmonicAngleParameters, Any]
        ],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

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

make_harmonic_angle_from_state(
    state: Lens[
        State,
        IsHarmonicAngleState[
            HasCache[
                HarmonicAngleParameters,
                PotentialOut[EmptyType, EmptyType],
            ]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[3]],
    ],
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, P]

make_harmonic_angle_from_state(
    state: Lens[
        State,
        IsHarmonicAngleState[
            HasCache[
                HarmonicAngleParameters,
                PotentialOut[PositionsAndCell, EmptyType],
            ]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[3]],
    ],
    *,
    parameters: None = None,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[State, PositionsAndCell, EmptyType, P]

make_harmonic_angle_from_state(
    state: Lens[State, IsHarmonicAngleGraphState],
    probe: None = None,
    *,
    parameters: HarmonicAngleParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

make_harmonic_angle_from_state(
    state: Lens[State, IsHarmonicAngleGraphState],
    probe: None = None,
    *,
    parameters: HarmonicAngleParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

make_harmonic_angle_from_state(
    state: Lens[
        State,
        IsCachedHarmonicAngleState[
            PotentialOut[EmptyType, EmptyType]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[3]],
    ],
    *,
    parameters: HarmonicAngleParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, P]

make_harmonic_angle_from_state(
    state: Lens[
        State,
        IsCachedHarmonicAngleState[
            PotentialOut[PositionsAndCell, EmptyType]
        ],
    ],
    probe: Probe[
        State,
        P,
        IsGraphProbe[IsBondedParticles, Literal[3]],
    ],
    *,
    parameters: HarmonicAngleParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[State, PositionsAndCell, EmptyType, P]

Create a harmonic angle potential, optionally with incremental updates.

Convenience wrapper around make_harmonic_angle_potential. When probe is None, builds a plain potential from IsHarmonicAngleState. When a probe is provided, builds an incrementally-updated potential from a state with HasCache-wrapped parameters.

Parameters:

Name Type Description Default
state Any

Lens into the sub-state providing particles, cell, and angle indices (plus harmonic_angle_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 HarmonicAngleParameters | None

Constant harmonic angle parameters. When given they are bound with a constant lens and the state need not carry harmonic_angle_parameters; with a probe, the cache is read from state.harmonic_angle_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 harmonic angle Potential.
Source code in src/kups/application/potential/classical/harmonic.py 
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
def make_harmonic_angle_from_state(
    state: Any,
    probe: Any = None,
    *,
    parameters: HarmonicAngleParameters | None = None,
    gradient: Lens[Geometry, PositionsAndCell] | None = None,
) -> Any:
    """Create a harmonic angle potential, optionally with incremental updates.

    Convenience wrapper around
    [make_harmonic_angle_potential][kups.potential.classical.harmonic.make_harmonic_angle_potential].
    When `probe` is `None`, builds a plain potential from
    [IsHarmonicAngleState][kups.application.potential.classical.harmonic.IsHarmonicAngleState].
    When a `probe` is provided, builds an incrementally-updated potential from
    a state with `HasCache`-wrapped parameters.

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

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

make_harmonic_bond_from_state(
    state: Lens[
        State,
        IsHarmonicBondState[
            MaybeCached[HarmonicBondParameters, Any]
        ],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

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

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

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

make_harmonic_bond_from_state(
    state: Lens[State, IsHarmonicBondGraphState],
    probe: None = None,
    *,
    parameters: HarmonicBondParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

make_harmonic_bond_from_state(
    state: Lens[State, IsHarmonicBondGraphState],
    probe: None = None,
    *,
    parameters: HarmonicBondParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

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

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

Create a harmonic bond potential, optionally with incremental updates.

Convenience wrapper around make_harmonic_bond_potential. When probe is None, builds a plain potential from IsHarmonicBondState. When a probe is provided, builds an incrementally-updated potential from a state with HasCache-wrapped parameters.

Parameters:

Name Type Description Default
state Any

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

Constant harmonic bond parameters. When given they are bound with a constant lens and the state need not carry harmonic_bond_parameters; with a probe, the cache is read from state.harmonic_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 harmonic bond Potential.
Source code in src/kups/application/potential/classical/harmonic.py 
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
230
231
232
233
234
235
236
237
238
239
240
241
242
def make_harmonic_bond_from_state(
    state: Any,
    probe: Any = None,
    *,
    parameters: HarmonicBondParameters | None = None,
    gradient: Lens[Geometry, PositionsAndCell] | None = None,
) -> Any:
    """Create a harmonic bond potential, optionally with incremental updates.

    Convenience wrapper around
    [make_harmonic_bond_potential][kups.potential.classical.harmonic.make_harmonic_bond_potential].
    When `probe` is `None`, builds a plain potential from
    [IsHarmonicBondState][kups.application.potential.classical.harmonic.IsHarmonicBondState].
    When a `probe` is provided, builds an incrementally-updated potential from
    a state with `HasCache`-wrapped parameters.

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