Source code for microscopic_gating.types

"""
Type definitions and protocols for the microscopic gating package.

This module defines the core type aliases and protocols used throughout
the package, enabling flexible composition of different isotherm and
geometry models.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Protocol

import numpy as np


ArrayLike = np.ndarray
"""Type alias for array-like inputs (numpy arrays, lists, or scalars)."""


class Isotherm(Protocol):
    """
    Protocol for adsorption isotherms.

    Any class implementing this protocol can be used with the gating
    models, allowing flexible substitution of different adsorption models.
    """

    def theta(self, phi: ArrayLike) -> ArrayLike:
        """
        Calculate occupancy fraction.

        Parameters
        ----------
        phi : ArrayLike
            Bulk concentration.

        Returns
        -------
        theta : ArrayLike
            Occupancy fraction in [0, 1], same shape as `phi`.
        """
        ...


class ContactProbability(Protocol):
    """
    Protocol for contact/capture geometry factors.

    Implementations provide the mean contact probability <chi> that
    accounts for geometric constraints on bridge formation.
    """

    def mean_contact(self) -> float:
        """
        Return the mean contact probability.

        Returns
        -------
        chi_mean : float
            Mean contact probability <chi> in [0, 1].
        """
        ...


@dataclass(frozen=True)
class SitePairCount:
    """
    Number of potentially accessible site pairs.

    This dataclass encapsulates the combinatorial factor for bridge
    formation based on available binding sites.

    Parameters
    ----------
    M : int
        Number of binding sites on the particle.
    N_acc : int
        Number of accessible binding sites on the network
        (geometry-dependent).

    Attributes
    ----------
    N_pair : int
        Total site pair count, calculated as M * N_acc.

    Examples
    --------
    >>> site_pairs = SitePairCount(M=10, N_acc=5)
    >>> site_pairs.N_pair
    50
    """

    M: int
    N_acc: int

    @property
    def N_pair(self) -> int:
        r"""
        Calculate total site pair count.

        Returns
        -------
        N_pair : int
            Product :math:`M \\times N_{\text{acc}}`.
        """
        return self.M * self.N_acc