Skip to content

kups.application.potential.classical.cosine_angle

State-binding constructors for cosine angle potentials.

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

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

IsCachedCosineAngleGraphState

Bases: IsCosineAngleGraphState, Protocol

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

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

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

IsCosineAngleGraphState

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

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

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

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

IsCosineAngleState

Bases: IsCosineAngleGraphState, Protocol

:class:IsCosineAngleGraphState that also carries parameters on the state.

Source code in src/kups/application/potential/classical/cosine_angle.py 
56
57
58
59
60
class IsCosineAngleState[Params](IsCosineAngleGraphState, Protocol):
    """:class:`IsCosineAngleGraphState` that also carries parameters on the state."""

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

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

make_cosine_angle_from_state(
    state: Lens[
        State,
        IsCosineAngleState[
            MaybeCached[CosineAngleParameters, Any]
        ],
    ],
    probe: None = None,
    *,
    parameters: None = None,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

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

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

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

make_cosine_angle_from_state(
    state: Lens[State, IsCosineAngleGraphState],
    probe: None = None,
    *,
    parameters: CosineAngleParameters,
    gradient: None = None,
) -> Potential[State, EmptyType, EmptyType, Patch[Any]]

make_cosine_angle_from_state(
    state: Lens[State, IsCosineAngleGraphState],
    probe: None = None,
    *,
    parameters: CosineAngleParameters,
    gradient: Lens[Geometry, PositionsAndCell],
) -> Potential[
    State, PositionsAndCell, EmptyType, Patch[Any]
]

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

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

Create a cosine angle 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 angle indices (plus cosine_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 CosineAngleParameters | None

Constant cosine angle parameters. When given they are bound with a constant lens and the state need not carry cosine_angle_parameters; with a probe, the cache is read from state.cosine_angle_cache.

 None
gradient Lens[Geometry, PositionsAndCell] | None

Relaxation filter selecting the optimizer DOFs as a Lens[Geometry, PositionsAndCell]. Defaults to no gradients.

 None

Returns:

Type Description
Any

Configured cosine angle Potential.
Source code in src/kups/application/potential/classical/cosine_angle.py 
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
230
def make_cosine_angle_from_state(
    state: Any,
    probe: Any = None,
    *,
    parameters: CosineAngleParameters | None = None,
    gradient: Lens[Geometry, PositionsAndCell] | None = None,
) -> Any:
    """Create a cosine angle potential from a typed state, optionally with incremental updates.

    Args:
        state: Lens into the sub-state providing particles, cell, and angle
            indices (plus ``cosine_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 cosine angle parameters. When given they are bound
            with a constant lens and the state need not carry
            ``cosine_angle_parameters``; with a ``probe``, the cache is read from
            ``state.cosine_angle_cache``.
        gradient: Relaxation filter selecting the optimizer DOFs as a
            ``Lens[Geometry, PositionsAndCell]``. Defaults to no gradients.

    Returns:
        Configured cosine 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.cosine_angle_parameters.data
                if isinstance(x.cosine_angle_parameters, HasCache)
                else x.cosine_angle_parameters
            )
        )
    cache_view = None
    if probe is not None:
        if parameters is None:
            param_view = state.focus(lambda x: x.cosine_angle_parameters.data)
            cache_view = state.focus(lambda x: x.cosine_angle_parameters.cache)
        else:
            cache_view = state.focus(lambda x: x.cosine_angle_cache)
        patch_idx_view = patch_idx_view or empty_patch_idx_view
    return make_cosine_angle_potential(
        state.focus(lambda x: x.particles),
        state.focus(lambda x: x.cosine_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,
    )