Skip to content

kups.application.potential.classical.dihedral

State-binding constructors for dihedral/torsion potentials.

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

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

IsCachedDihedralGraphState

Bases: IsDihedralGraphState, Protocol

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

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

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

IsDihedralGraphState

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

Particles, systems, and dihedral indices (no parameters).

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

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

IsDihedralState

Bases: IsDihedralGraphState, Protocol

:class:IsDihedralGraphState that also carries dihedral parameters.

Source code in src/kups/application/potential/classical/dihedral.py 
55
56
57
58
59
class IsDihedralState[Params](IsDihedralGraphState, Protocol):
    """:class:`IsDihedralGraphState` that also carries dihedral parameters."""

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

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

make_dihedral_from_state(
    state: Lens[
        State,
        IsDihedralState[
            MaybeCached[DihedralParameters, Any]
        ],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

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

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

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

make_dihedral_from_state(
    state: Lens[State, IsDihedralGraphState],
    probe: None = None,
    *,
    parameters: DihedralParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

make_dihedral_from_state(
    state: Lens[State, IsDihedralGraphState],
    probe: None = None,
    *,
    parameters: DihedralParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

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

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

Create a dihedral 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 dihedral indices (plus dihedral_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 DihedralParameters | None

Constant dihedral parameters. When given they are bound with a constant lens and the state need not carry dihedral_parameters; with a probe, the cache is read from state.dihedral_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 dihedral Potential.
Source code in src/kups/application/potential/classical/dihedral.py 
161
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
def make_dihedral_from_state(
    state: Any,
    probe: Any = None,
    *,
    parameters: DihedralParameters | None = None,
    gradient: Lens[Geometry, PositionsAndCell] | None = None,
) -> Any:
    """Create a dihedral potential from a typed state, optionally with incremental updates.

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