kups.core.typing ¶

class ExclusionId(int):
    """Sentinel type for exclusion group indices."""

class GroupId(int):
    """Sentinel type for molecular group indices."""

@runtime_checkable
class HasAtomicNumbers(Protocol):
    """Protocol for entities with atomic numbers.

    Attributes:
        atomic_numbers: Array of atomic numbers for each atom.
    """

    @property
    def atomic_numbers(self) -> Array: ...

@runtime_checkable
class HasBarostatFriction(Protocol):
    r"""Protocol for systems with Langevin friction on the cell DOFs.

    Per-component friction $\gamma_{\alpha\beta}$ governing the
    Ornstein–Uhlenbeck thermostat on [`cell_momentum`][kups.core.typing.HasCellMomentum].
    Lower-triangular.

    Attributes:
        barostat_friction: Cell friction tensor $\gamma$ (units: 1/time),
            shape ``(..., 3, 3)``, lower-triangular.
    """

    @property
    def barostat_friction(self) -> Array: ...

@runtime_checkable
class HasBarostatMass(Protocol):
    r"""Protocol for systems with a fictitious cell mass tensor.

    Per-component mass $M_{\alpha\beta}$ of the cell DOFs, set from the
    Gao–Fang–Wang formula
    $M_{\alpha\beta} = 3\det(h_0)\,(\tau/2\pi)^2 / (\kappa (h_0)_{\alpha\alpha}^2)$
    (Eq. 14–15 of the paper) at construction time. Lower-triangular to
    match [`cell_momentum`][kups.core.typing.HasCellMomentum].

    Attributes:
        barostat_mass: Cell mass tensor $M$ (units: mass·length²),
            shape ``(..., 3, 3)``, lower-triangular.
    """

    @property
    def barostat_mass(self) -> Array: ...

@runtime_checkable
class HasCache[Data, Cache](Protocol):
    """Protocol for objects carrying primary data alongside a cache."""

    @property
    def data(self) -> Data: ...
    @property
    def cache(self) -> Cache: ...

@runtime_checkable
class HasCell(Protocol, Generic[_P_co]):
    """Protocol for entities with cell parameters.

    Generic over the periodicity literal ``P``, mirroring
    [Cell][kups.core.cell.Cell]. Narrowing example:
    ``HasCell[Periodic3D]`` for systems requiring fully-periodic cells.

    Attributes:
        cell: Cell parameters for each system.
    """

    @property
    def cell(self) -> Cell[_P_co]: ...

@runtime_checkable
class HasCellMomentum(Protocol):
    r"""Protocol for systems with an extended-variable cell-momentum tensor.

    Conjugate momentum of the lower-triangular cell-vector matrix
    [`cell.vectors`][kups.core.cell.Cell.vectors]. Stored as a
    ``(..., 3, 3)`` lower-triangular array (strict-upper entries are
    zero and ignored). Used by extended-variable NPT integrators such as
    Gao–Fang–Wang BAOAB NPT Langevin.

    Attributes:
        cell_momentum: Cell momentum $p^h$ (units: mass·length/time),
            shape ``(..., 3, 3)``, lower-triangular.
    """

    @property
    def cell_momentum(self) -> Array: ...

@runtime_checkable
class HasCharges(Protocol):
    """Protocol for entities with charge data.

    Attributes:
        charges: Array of charges for each entity (e.g., atoms).
    """

    @property
    def charges(self) -> Array: ...

@runtime_checkable
class HasCompressibility(Protocol):
    r"""Protocol for systems with isothermal compressibility.

    Attributes:
        compressibility: Isothermal compressibility $\beta$ (units: length³/energy).
    """

    @property
    def compressibility(self) -> Array: ...

@runtime_checkable
class HasCutoff(Protocol):
    """Protocol for entities with a distance cutoff.

    Attributes:
        cutoff: Cutoff distance (units: length).
    """

    @property
    def cutoff(self) -> Array: ...

@runtime_checkable
class HasExclusionIndex(Protocol):
    """Protocol for entities with exclusion group index.

    Attributes:
        exclusion: Index mapping particles to exclusion groups.
    """

    @property
    def exclusion(self) -> Index[ExclusionId]: ...

@runtime_checkable
class HasForces(Protocol):
    """Protocol for entities with force data.

    Attributes:
        forces: Array of forces for each entity (e.g., atoms).
    """

    @property
    def forces(self) -> Array: ...

@runtime_checkable
class HasFrictionCoefficient(Protocol):
    r"""Protocol for systems with Langevin friction coefficient.

    Attributes:
        friction_coefficient: Friction coefficient $\gamma$ (units: 1/time).
    """

    @property
    def friction_coefficient(self) -> Array: ...

@runtime_checkable
class HasGroupIndex(Protocol):
    """Protocol for entities with molecular group index.

    Attributes:
        group: Index mapping particles to molecular groups.
    """

    @property
    def group(self) -> Index[GroupId]: ...

@runtime_checkable
class HasInclusionIndex(Protocol):
    """Protocol for entities with inclusion group index.

    Attributes:
        inclusion: Index mapping particles to inclusion groups.
    """

    @property
    def inclusion(self) -> Index[InclusionId]: ...

@runtime_checkable
class HasIntegratorParams[P](Protocol):
    r"""Protocol for systems carrying bundled integrator control parameters.

    Attributes:
        integrator_params: Control knobs consumed by the chosen integrator
            (time step, thermostat/barostat coupling parameters). Concrete shape
            of ``P`` matches one of the integrator-specific protocols defined
            in :mod:`kups.md.integrators`.
    """

    @property
    def integrator_params(self) -> P: ...

@runtime_checkable
class HasLabels(Protocol):
    """Protocol for entities with string labels.

    Attributes:
        labels: Species identifier for each group (e.g., molecule type).
    """

    @property
    def labels(self) -> Index[Label]: ...

@runtime_checkable
class HasLogActivity(Protocol):
    """Protocol for entities with chemical activity parameters.

    Attributes:
        log_activity: Natural log of chemical activity per species [dimensionless],
            shape `(n_systems, n_species)`.
    """

    @property
    def log_activity(self) -> Array: ...

@runtime_checkable
class HasMasses(Protocol):
    """Protocol for entities with mass data.

    Attributes:
        masses: Array of masses for each entity (e.g., atoms).
    """

    @property
    def masses(self) -> Array: ...

@runtime_checkable
class HasMinimumScaleFactor(Protocol):
    r"""Protocol for systems with minimum barostat scale factor.

    Attributes:
        minimum_scale_factor: Minimum scaling factor $\mu_{\text{min}}$ (dimensionless).
    """

    @property
    def minimum_scale_factor(self) -> Array: ...

@runtime_checkable
class HasMomenta(Protocol):
    """Protocol for entities with momentum data.

    Attributes:
        momenta: Array of momenta for each entity (e.g., atoms).
    """

    @property
    def momenta(self) -> Array: ...

@runtime_checkable
class HasMotifAndSystemIndex(HasMotifIndex, HasSystemIndex, Protocol):
    """Protocol for entities with both motif and system indices."""

@runtime_checkable
class HasMotifIndex(Protocol):
    """Protocol for entities with molecular motif index.

    Attributes:
        motif: Index mapping particles to motif templates.
    """

    @property
    def motif(self) -> Index[MotifId]: ...

@runtime_checkable
class HasPositions(Protocol):
    """Protocol for entities with position data.

    Attributes:
        positions: Array of positions for each entity (e.g., atoms).
    """

    @property
    def positions(self) -> Array: ...

@runtime_checkable
class HasPositionsAndAtomicNumbers(HasPositions, HasAtomicNumbers, Protocol):
    """Protocol for entities with both position and atomic number data."""

    ...

@runtime_checkable
class HasPositionsAndGroupIndex(HasPositions, HasGroupIndex, Protocol):
    """Protocol for entities with both position data and group index."""

@runtime_checkable
class HasPositionsAndLabels(HasPositions, HasLabels, Protocol):
    """Protocol for entities with both position and label data."""

    ...

@runtime_checkable
class HasPositionsAndSystemIndex(HasPositions, HasSystemIndex, Protocol):
    """Protocol for entities with both position data and system index."""

@runtime_checkable
class HasPotentialEnergy(Protocol):
    r"""Protocol for systems with a potential energy.

    Attributes:
        potential_energy: Potential energy in eV.
    """

    @property
    def potential_energy(self) -> Array: ...

@runtime_checkable
class HasPressureCouplingTime(Protocol):
    r"""Protocol for systems with barostat coupling time constant.

    Attributes:
        pressure_coupling_time: Barostat time constant $\tau_P$ (units: time).
    """

    @property
    def pressure_coupling_time(self) -> Array: ...

@runtime_checkable
class HasStressTensor(Protocol):
    r"""Protocol for systems with computed virial stress tensor.

    Attributes:
        stress_tensor: Virial stress tensor $\mathbf{W}$ (units: energy).
    """

    @property
    def stress_tensor(self) -> Array: ...

@runtime_checkable
class HasSystemIndex(Protocol):
    """Protocol for entities with simulation system index.

    Attributes:
        system: Index mapping entities to independent simulation boxes.
    """

    @property
    def system(self) -> Index[SystemId]: ...

@runtime_checkable
class HasTargetPressure(Protocol):
    r"""Protocol for systems with target pressure for barostat.

    Attributes:
        target_pressure: Target pressure $P_0$ (units: energy/length³).
    """

    @property
    def target_pressure(self) -> Array: ...

@runtime_checkable
class HasTemperature(Protocol):
    """Protocol for entities with temperature parameters.

    Attributes:
        temperature: Temperature array [energy units], shape `(n_systems,)`.
    """

    @property
    def temperature(self) -> Array: ...

@runtime_checkable
class HasThermalEnergy(Protocol):
    r"""Protocol for systems with target thermal energy.

    Attributes:
        thermal_energy: Thermal energy $k_B T$ (units: energy).
    """

    @property
    def thermal_energy(self) -> Array: ...

@runtime_checkable
class HasThermostatTimeConstant(Protocol):
    r"""Protocol for systems with thermostat coupling time constant.

    Attributes:
        thermostat_time_constant: Thermostat time constant $\tau$ (units: time).
    """

    @property
    def thermostat_time_constant(self) -> Array: ...

@runtime_checkable
class HasTimeStep(Protocol):
    r"""Protocol for systems with integration time step.

    Attributes:
        time_step: Time step $\Delta t$ (units: time).
    """

    @property
    def time_step(self) -> Array: ...

@runtime_checkable
class HasVelocities(Protocol):
    """Protocol for entities with velocity data.

    Attributes:
        velocities: Array of velocities for each entity (e.g., atoms).
    """

    @property
    def velocities(self) -> Array: ...

@runtime_checkable
class HasWeights(Protocol):
    """Protocol for entities with weight/mass data.

    Attributes:
        weights: Array of weights/masses for each entity (e.g., atoms).
    """

    @property
    def weights(self) -> Array: ...

class InclusionId(int):
    """Sentinel type for inclusion group indices."""

class Label(str):
    """Sentinel type for species/molecule string labels."""

class MotifId(int):
    """Sentinel type for motif template indices."""

class MotifParticleId(int):
    """Sentinel type for motif particle indices."""

class ParticleId(int):
    """Sentinel type for particle indices."""

class SystemId(int):
    """Sentinel type for simulation system indices."""