fpembed 0.1.0__py3-none-any.whl

fpembed/__init__.py

@@ -0,0 +1,32 @@
+"""FPembed — Generalized fingerprint embedding library backed by scikit-fingerprints.
+
+Provides :class:`EmbeddedFingerprintGenerator` for generating compressed
+molecular fingerprints from SMILES, SELFIES, or RDKit Mol objects, plus
+the standalone :func:`compress_fingerprint` compression function and
+lightweight SMILES helpers.
+
+Example:
+    >>> from fpembed import EmbeddedFingerprintGenerator
+    >>> gen = EmbeddedFingerprintGenerator(
+    ...     fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}
+    ... )
+    >>> emb = gen.GetFingerprintFromSmiles("CCO")
+    >>> emb.shape
+    (128,)
+"""
+
+from fpembed.generator import EmbeddedFingerprintGenerator
+from fpembed.compression import compress_fingerprint
+from fpembed.smiles_utils import parse_smiles, canonicalize_smiles
+from fpembed.hashing import fp_params_hash
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EmbeddedFingerprintGenerator",
+    "compress_fingerprint",
+    "parse_smiles",
+    "canonicalize_smiles",
+    "fp_params_hash",
+    "__version__",
+]

fpembed/compression.py

@@ -0,0 +1,154 @@
+"""Fingerprint compression orchestrator.
+
+Routes ``compress_fingerprint()`` calls to the appropriate sub-module
+based on the ``method`` parameter. Supports block-wise weight schemes
+(geometric, linear, log, uniform) and global projection methods
+(hadamard, random_projection).
+
+The default behavior (``method="geometric"``, no ``method_params``)
+produces output identical to the original implementation.
+
+Public API
+----------
+compress_fingerprint : Compress a fingerprint array.
+_is_power_of_two     : Check whether an integer is a power of two.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from fpembed.compression_blockwise import compress_blockwise
+from fpembed.compression_projection import (
+    build_rp_matrix,
+    build_srht_signs,
+    compress_hadamard,
+    compress_random_projection,
+)
+
+_BLOCKWISE_METHODS = {"geometric", "linear", "log", "uniform"}
+_PROJECTION_METHODS = {"hadamard", "random_projection"}
+_ALL_METHODS = _BLOCKWISE_METHODS | _PROJECTION_METHODS
+
+_VALID_PARAMS: dict[str, set[str]] = {
+    "geometric": {"interleave"},
+    "linear": {"interleave"},
+    "log": {"interleave"},
+    "uniform": {"interleave"},
+    "hadamard": {"seed"},
+    "random_projection": {"seed", "sparse"},
+}
+
+_DEFAULT_SEED = 42
+
+
+def _validate_method_params(method: str, method_params: dict) -> None:
+    """Validate method_params keys and value types for the given method."""
+    valid_keys = _VALID_PARAMS[method]
+    unrecognized = set(method_params) - valid_keys
+    if unrecognized:
+        raise ValueError(
+            f"Unrecognized method_params keys {unrecognized} for method "
+            f"'{method}'. Valid keys: {valid_keys}"
+        )
+
+    if "seed" in method_params:
+        seed = method_params["seed"]
+        if not isinstance(seed, int) or isinstance(seed, bool) or seed < 0:
+            raise ValueError(
+                f"seed must be a non-negative integer, got {seed!r}"
+            )
+
+    if "sparse" in method_params:
+        sparse = method_params["sparse"]
+        if not isinstance(sparse, bool):
+            raise ValueError(
+                f"sparse must be a boolean, got {type(sparse).__name__}"
+            )
+
+    if "interleave" in method_params:
+        interleave = method_params["interleave"]
+        if not isinstance(interleave, bool):
+            raise ValueError(
+                f"interleave must be a boolean, got {type(interleave).__name__}"
+            )
+        if interleave and method in _PROJECTION_METHODS:
+            raise ValueError(
+                f"interleave is not applicable to method '{method}'"
+            )
+
+
+def compress_fingerprint(
+    vector: npt.NDArray[Any],
+    size: int,
+    *,
+    method: str = "geometric",
+    method_params: dict | None = None,
+) -> npt.NDArray[np.float64]:
+    """Compress a binary fingerprint into a dense float embedding.
+
+    Parameters
+    ----------
+    vector : ndarray
+        Input fingerprint — ``(L,)`` or ``(N, L)``.
+    size : int
+        Compression factor.
+    method : str
+        Compression method name.
+    method_params : dict or None
+        Method-specific parameters.
+
+    Returns
+    -------
+    ndarray of float64
+        Compressed embedding.
+
+    Raises
+    ------
+    ValueError
+        If *size* is invalid, *method* is unsupported, or *method_params*
+        contains invalid keys/values.
+    """
+    if not isinstance(size, int) or size <= 0:
+        raise ValueError(
+            "Size must be a positive integer. Try size = 16, or size = 32"
+        )
+
+    if method not in _ALL_METHODS:
+        raise ValueError(
+            f"Unsupported method '{method}'. "
+            f"Supported: {', '.join(sorted(_ALL_METHODS))}"
+        )
+
+    if method_params is None:
+        method_params = {}
+
+    _validate_method_params(method, method_params)
+
+    # Block-wise methods
+    if method in _BLOCKWISE_METHODS:
+        interleave = method_params.get("interleave", False)
+        return compress_blockwise(vector, size, scheme=method, interleave=interleave)
+
+    # Projection methods
+    fp_len = vector.shape[-1] if vector.ndim > 1 else vector.shape[0]
+    output_dim = fp_len // size
+
+    if method == "hadamard":
+        seed = method_params.get("seed", _DEFAULT_SEED)
+        signs = build_srht_signs(fp_len, seed)
+        return compress_hadamard(vector, size, signs)
+
+    # method == "random_projection"
+    seed = method_params.get("seed", _DEFAULT_SEED)
+    sparse = method_params.get("sparse", False)
+    matrix = build_rp_matrix(fp_len, output_dim, seed, sparse)
+    return compress_random_projection(vector, matrix)
+
+
+def _is_power_of_two(n: int) -> bool:
+    """Return True if *n* is a positive power of two."""
+    return n > 0 and (n & (n - 1)) == 0

fpembed/compression_blockwise.py

@@ -0,0 +1,105 @@
+"""Block-wise fingerprint compression with pluggable weight schemes.
+
+Provides weight vector construction for geometric, linear, logarithmic,
+and uniform schemes, plus block partitioning (contiguous and interleaved)
+with weighted dot-product reduction.
+
+Public API
+----------
+build_block_weights : Build a normalized weight vector for a given scheme.
+compress_blockwise  : Compress a fingerprint using block-wise weighted dot product.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+_SUPPORTED_SCHEMES = ("geometric", "linear", "log", "uniform")
+
+
+def build_block_weights(
+    block_size: int, scheme: str = "geometric"
+) -> npt.NDArray[np.float64]:
+    """Return a normalized weight vector of length *block_size*.
+
+    Parameters
+    ----------
+    block_size : int
+        Number of bits per block (must be >= 1).
+    scheme : str
+        One of ``"geometric"``, ``"linear"``, ``"log"``, ``"uniform"``.
+
+    Returns
+    -------
+    ndarray of float64
+        1-D array of length *block_size*, summing to 1.0.
+
+    Raises
+    ------
+    ValueError
+        If *scheme* is not recognized.
+    """
+    if scheme == "geometric":
+        # Log-space construction for numerical stability (moved from compression.py)
+        log_weights = np.arange(block_size, dtype=np.float64) - block_size
+        weights = np.exp2(log_weights)
+    elif scheme == "linear":
+        weights = np.arange(1, block_size + 1, dtype=np.float64)
+    elif scheme == "log":
+        weights = np.log2(np.arange(2, block_size + 2, dtype=np.float64))
+    elif scheme == "uniform":
+        return np.full(block_size, 1.0 / block_size, dtype=np.float64)
+    else:
+        raise ValueError(
+            f"Unsupported weight scheme '{scheme}'. "
+            f"Supported: {', '.join(_SUPPORTED_SCHEMES)}"
+        )
+    weights /= weights.sum()
+    return weights
+
+
+def compress_blockwise(
+    vector: npt.NDArray[Any],
+    size: int,
+    scheme: str = "geometric",
+    interleave: bool = False,
+) -> npt.NDArray[np.float64]:
+    """Compress a binary fingerprint using block-wise weighted dot product.
+
+    Parameters
+    ----------
+    vector : ndarray
+        Input fingerprint — ``(L,)`` for single or ``(N, L)`` for batch.
+    size : int
+        Block size (compression factor).
+    scheme : str
+        Weight scheme name.
+    interleave : bool
+        If True, use strided (interleaved) partitioning; if False, contiguous.
+
+    Returns
+    -------
+    ndarray of float64
+        Compressed embedding — ``(1, L//size)`` or ``(N, L//size)``.
+    """
+    single = vector.ndim == 1
+    if single:
+        vector = vector[np.newaxis, :]
+
+    rows, cols = vector.shape
+    n_blocks = cols // size
+
+    weights = build_block_weights(size, scheme)
+
+    if interleave:
+        # Strided: bit[i] → block[i % n_blocks]
+        blocks = vector.reshape(rows, size, n_blocks).transpose(0, 2, 1)
+    else:
+        # Contiguous: bit[i] → block[i // size]
+        blocks = vector.reshape(rows, n_blocks, size)
+
+    embedded: npt.NDArray[np.float64] = np.einsum("ijk,k->ij", blocks, weights)
+    return embedded

fpembed/compression_projection.py

@@ -0,0 +1,181 @@
+"""Global projection compression methods: SRHT and random projection.
+
+Provides the Fast Walsh-Hadamard Transform (FWHT), Subsampled Randomized
+Hadamard Transform (SRHT) compression, and seeded random projection
+(dense Gaussian and sparse Achlioptas variants).
+
+Public API
+----------
+fwht                        : In-place Fast Walsh-Hadamard Transform.
+build_srht_signs            : Generate random ±1 sign vector for SRHT.
+compress_hadamard           : Compress via SRHT (sign flips → FWHT → truncate).
+build_rp_matrix             : Build a random projection matrix (dense or sparse).
+compress_random_projection  : Compress via matrix multiplication.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+
+def fwht(x: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+    """In-place Fast Walsh-Hadamard Transform (butterfly algorithm).
+
+    Operates in O(L log L) using only additions and subtractions.
+
+    Parameters
+    ----------
+    x : ndarray
+        1-D float64 array of length L (must be a power of 2).
+
+    Returns
+    -------
+    ndarray
+        The same array, modified in-place.
+    """
+    length = len(x)
+    h = 1
+    while h < length:
+        for i in range(0, length, h * 2):
+            for j in range(i, i + h):
+                a = x[j]
+                b = x[j + h]
+                x[j] = a + b
+                x[j + h] = a - b
+        h *= 2
+    return x
+
+
+def build_srht_signs(
+    length: int, seed: int
+) -> npt.NDArray[np.float64]:
+    """Generate a random ±1 sign vector for SRHT.
+
+    Parameters
+    ----------
+    length : int
+        Fingerprint length L.
+    seed : int
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    ndarray of float64
+        1-D array of ±1 values, length L.
+    """
+    rng = np.random.RandomState(seed)
+    return rng.choice([-1.0, 1.0], size=length).astype(np.float64)
+
+
+def compress_hadamard(
+    vector: npt.NDArray[Any],
+    size: int,
+    signs: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]:
+    """Compress using Subsampled Randomized Hadamard Transform.
+
+    Applies sign flips, FWHT, normalization by 1/√L, and truncation to
+    D = L // size dimensions.
+
+    Parameters
+    ----------
+    vector : ndarray
+        Input fingerprint — ``(L,)`` or ``(N, L)``.
+    size : int
+        Compression factor.
+    signs : ndarray
+        Precomputed ±1 sign vector of length L.
+
+    Returns
+    -------
+    ndarray of float64
+        Compressed embedding — ``(1, D)`` or ``(N, D)``.
+    """
+    single = vector.ndim == 1
+    if single:
+        vector = vector[np.newaxis, :]
+
+    rows, cols = vector.shape
+    output_dim = cols // size
+    norm = 1.0 / np.sqrt(cols)
+
+    result = np.empty((rows, output_dim), dtype=np.float64)
+    for i in range(rows):
+        row = vector[i].astype(np.float64) * signs
+        fwht(row)
+        row *= norm
+        result[i] = row[:output_dim]
+
+    return result
+
+
+def build_rp_matrix(
+    fp_length: int,
+    output_dim: int,
+    seed: int,
+    sparse: bool = False,
+) -> npt.NDArray[np.float64]:
+    """Build a random projection matrix R of shape ``(output_dim, fp_length)``.
+
+    Dense Gaussian: ``R[i,j] ~ N(0, 1/D)``.
+    Sparse Achlioptas: ``R[i,j] ∈ {-1, 0, +1}`` with ``P(0) = 2/3``,
+    scaled by ``√(3/D)``.
+
+    Parameters
+    ----------
+    fp_length : int
+        Input dimension L.
+    output_dim : int
+        Output dimension D.
+    seed : int
+        Random seed for reproducibility.
+    sparse : bool
+        If True, use Achlioptas variant.
+
+    Returns
+    -------
+    ndarray of float64
+        2-D array of shape ``(D, L)``.
+    """
+    rng = np.random.RandomState(seed)
+
+    if sparse:
+        # Achlioptas: P(-1) = 1/6, P(0) = 2/3, P(+1) = 1/6
+        raw = rng.choice([-1, 0, 0, 0, 0, 1], size=(output_dim, fp_length))
+        scale = np.sqrt(3.0 / output_dim)
+        return raw.astype(np.float64) * scale
+    else:
+        # Dense Gaussian: N(0, 1/D)
+        std = 1.0 / np.sqrt(output_dim)
+        return rng.randn(output_dim, fp_length).astype(np.float64) * std
+
+
+def compress_random_projection(
+    vector: npt.NDArray[Any],
+    matrix: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]:
+    """Compress using a precomputed random projection matrix.
+
+    Computes ``embedding = vector @ matrix.T``.
+
+    Parameters
+    ----------
+    vector : ndarray
+        Input fingerprint — ``(L,)`` or ``(N, L)``.
+    matrix : ndarray
+        Projection matrix of shape ``(D, L)``.
+
+    Returns
+    -------
+    ndarray of float64
+        Compressed embedding — ``(1, D)`` or ``(N, D)``.
+    """
+    single = vector.ndim == 1
+    if single:
+        vector = vector[np.newaxis, :]
+
+    embedded = vector.astype(np.float64) @ matrix.T
+    return embedded

fpembed/generator.py

@@ -0,0 +1,348 @@
+"""EmbeddedFingerprintGenerator — unified fingerprint class backed by skfp."""
+
+from __future__ import annotations
+
+import functools
+from collections import namedtuple
+from typing import Any, TYPE_CHECKING
+
+import numpy as np
+import numpy.typing as npt
+from rdkit import Chem
+from skfp.fingerprints import (
+    AtomPairFingerprint,
+    ECFPFingerprint,
+    LayeredFingerprint,
+    PatternFingerprint,
+    RDKitFingerprint,
+    TopologicalTorsionFingerprint,
+)
+
+from fpembed.compression import (
+    compress_fingerprint,
+    _is_power_of_two,
+    _ALL_METHODS,
+    _validate_method_params,
+    _DEFAULT_SEED,
+)
+from fpembed.compression_projection import (
+    build_rp_matrix,
+    build_srht_signs,
+    compress_hadamard,
+    compress_random_projection,
+)
+from fpembed.hashing import fp_params_hash
+from fpembed.smiles_utils import canonicalize_smiles, parse_smiles
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+CacheInfo = namedtuple("CacheInfo", ["hits", "misses", "maxsize", "currsize"])
+_EMPTY_CACHE_INFO = CacheInfo(hits=0, misses=0, maxsize=0, currsize=0)
+
+_SUPPORTED_FP_TYPES = (
+    "ecfp", "atom_pair", "topological_torsion", "rdkit", "layered", "pattern",
+)
+
+
+def _build_skfp(fp_type: str, fp_size: int, fp_params: dict) -> Any:
+    """Instantiate the appropriate skfp fingerprint object."""
+    if fp_type == "ecfp":
+        return ECFPFingerprint(
+            fp_size=fp_size, radius=fp_params.get("radius", 2),
+            count=False, n_jobs=1,
+        )
+    if fp_type == "atom_pair":
+        return AtomPairFingerprint(
+            fp_size=fp_size, min_distance=fp_params.get("min_distance", 1),
+            max_distance=fp_params.get("max_distance", 30),
+            count=False, n_jobs=1,
+        )
+    if fp_type == "topological_torsion":
+        return TopologicalTorsionFingerprint(
+            fp_size=fp_size,
+            torsion_atom_count=fp_params.get("torsion_atom_count", 4),
+            count=False, n_jobs=1,
+        )
+    if fp_type == "rdkit":
+        return RDKitFingerprint(
+            fp_size=fp_size, min_path=fp_params.get("min_path", 1),
+            max_path=fp_params.get("max_path", 7), count=False, n_jobs=1,
+        )
+    if fp_type == "layered":
+        return LayeredFingerprint(
+            fp_size=fp_size, min_path=fp_params.get("min_path", 1),
+            max_path=fp_params.get("max_path", 7), n_jobs=1,
+        )
+    return PatternFingerprint(fp_size=fp_size, n_jobs=1)
+
+
+class EmbeddedFingerprintGenerator:
+    """Unified fingerprint generator backed by scikit-fingerprints.
+
+    Supports six fp_types: ecfp, atom_pair, topological_torsion,
+    rdkit, layered, pattern. Compression via log-space weighted mask.
+    """
+
+    __slots__ = (
+        "_fp_type", "_fp_size", "_compression", "_fp_params",
+        "_method", "_method_params", "_projection_cache",
+        "_skfp_fp", "_params_hash", "_cache_size", "_cached_compute",
+    )
+
+    def __init__(
+        self,
+        fp_type: str,
+        fp_size: int,
+        compression: int | None,
+        fp_params: dict | None = None,
+        cache_size: int | None = None,
+        method: str = "geometric",
+        method_params: dict | None = None,
+    ) -> None:
+        if fp_params is None:
+            fp_params = {}
+        if method_params is None:
+            method_params = {}
+        if fp_type not in _SUPPORTED_FP_TYPES:
+            raise ValueError(
+                f"Unsupported fp_type '{fp_type}'. "
+                f"Supported: {', '.join(_SUPPORTED_FP_TYPES)}"
+            )
+        if method not in _ALL_METHODS:
+            raise ValueError(
+                f"Unsupported method '{method}'. "
+                f"Supported: {', '.join(sorted(_ALL_METHODS))}"
+            )
+        _validate_method_params(method, method_params)
+
+        effective: int = 0 if (compression is None or compression == 0) else compression
+        if effective != 0:
+            if not _is_power_of_two(effective):
+                raise ValueError(f"compression must be a power of 2, got {effective}")
+            if effective > fp_size / 2:
+                raise ValueError(
+                    f"compression ({effective}) must be <= fp_size / 2 ({fp_size // 2})"
+                )
+            if fp_size % effective != 0:
+                raise ValueError(
+                    f"fp_size ({fp_size}) must be evenly divisible by compression ({effective})"
+                )
+
+        if method == "hadamard" and not _is_power_of_two(fp_size):
+            raise ValueError("Hadamard method requires fp_size to be a power of 2")
+
+        self._fp_type = fp_type
+        self._fp_size = fp_size
+        self._compression = effective
+        self._fp_params = dict(fp_params)
+        self._method = method
+        self._method_params = dict(method_params)
+        self._cache_size = cache_size
+        self._skfp_fp: Any = _build_skfp(fp_type, fp_size, fp_params)
+
+        # Precompute projection artifacts for projection methods
+        self._projection_cache: Any = None
+        if effective != 0 and method == "hadamard":
+            seed = self._method_params.get("seed", _DEFAULT_SEED)
+            self._projection_cache = build_srht_signs(fp_size, seed)
+        elif effective != 0 and method == "random_projection":
+            seed = self._method_params.get("seed", _DEFAULT_SEED)
+            sparse = self._method_params.get("sparse", False)
+            output_dim = fp_size // effective
+            self._projection_cache = build_rp_matrix(fp_size, output_dim, seed, sparse)
+
+        self._params_hash = fp_params_hash(
+            fp_type, fp_params, method=method, method_params=method_params,
+        )
+        if cache_size is not None:
+            @functools.lru_cache(maxsize=cache_size)
+            def _cached(smiles: str) -> npt.NDArray[np.float64] | None:
+                mol = parse_smiles(smiles)
+                return None if mol is None else self.GetFingerprintAsNumPy(mol)
+            self._cached_compute: Any = _cached
+        else:
+            self._cached_compute = None
+
+    @property
+    def fp_type(self) -> str:
+        """Fingerprint type identifier."""
+        return self._fp_type
+
+    @property
+    def fp_size(self) -> int:
+        """Fingerprint bit-vector length."""
+        return self._fp_size
+
+    @property
+    def compression(self) -> int:
+        """Compression factor (0 means no compression)."""
+        return self._compression
+
+    @property
+    def fp_params(self) -> dict:
+        """Type-specific fingerprint parameters (copy)."""
+        return dict(self._fp_params)
+
+    @property
+    def method(self) -> str:
+        """Compression method name."""
+        return self._method
+
+    @property
+    def method_params(self) -> dict:
+        """Method-specific parameters (copy)."""
+        return dict(self._method_params)
+
+    @property
+    def params_hash(self) -> str:
+        """Read-only 16-char hex hash of fp_type + fp_params."""
+        return self._params_hash
+
+    def _raw_fp(self, mol: Chem.Mol) -> npt.NDArray[np.float64]:
+        return self._skfp_fp.transform([mol]).flatten().astype(np.float64)
+
+    def GetRawFingerprintAsNumPy(self, mol: Chem.Mol) -> npt.NDArray[np.float64]:
+        """Return the raw (uncompressed) fingerprint for a single Mol."""
+        if mol is None:
+            raise ValueError("mol must not be None")
+        return self._raw_fp(mol)
+
+    def GetFingerprintAsNumPy(self, mol: Chem.Mol) -> npt.NDArray[np.float64]:
+        """Return the (optionally compressed) fingerprint for a single Mol."""
+        if mol is None:
+            raise ValueError("mol must not be None")
+        raw = self._raw_fp(mol)
+        if self._compression == 0:
+            return raw
+        # Projection methods: use cached artifacts directly
+        if self._method == "hadamard":
+            return compress_hadamard(raw, self._compression, self._projection_cache).flatten()
+        if self._method == "random_projection":
+            return compress_random_projection(raw, self._projection_cache).flatten()
+        # Block-wise methods: delegate to orchestrator
+        return compress_fingerprint(
+            raw, self._compression,
+            method=self._method, method_params=self._method_params,
+        ).flatten()
+
+    def _out_dim(self) -> int:
+        return self._fp_size // self._compression if self._compression > 0 else self._fp_size
+
+    def GetFingerprintsAsNumPy(
+        self, mols: Sequence[Chem.Mol | None], chunk_size: int | None = None,
+    ) -> tuple[npt.NDArray[np.float64], list[int]]:
+        """Batch fingerprints. Returns (embeddings, invalid_indices)."""
+        if chunk_size is not None and chunk_size <= 0:
+            raise ValueError("chunk_size must be a positive integer or None")
+        total = len(mols)
+        invalid: list[int] = []
+        valid: list[npt.NDArray[np.float64]] = []
+        cs = chunk_size or total
+        for start in range(0, total, cs):
+            for i in range(start, min(start + cs, total)):
+                mol = mols[i]
+                if mol is None:
+                    invalid.append(i)
+                    continue
+                try:
+                    valid.append(self.GetFingerprintAsNumPy(mol))
+                except Exception:
+                    invalid.append(i)
+        if valid:
+            return np.vstack(valid), invalid
+        return np.empty((0, self._out_dim()), dtype=np.float64), invalid
+
+    def GetFingerprintFromSmiles(
+        self, smiles: str, validate: bool = True, canonicalize: bool = True,
+    ) -> npt.NDArray[np.float64] | None:
+        """Generate a fingerprint from a SMILES string."""
+        if validate:
+            if canonicalize:
+                smiles = canonicalize_smiles(smiles) or ""
+                if not smiles:
+                    return None
+            elif parse_smiles(smiles) is None:
+                return None
+        if self._cached_compute is not None:
+            return self._cached_compute(smiles)
+        mol = parse_smiles(smiles)
+        return None if mol is None else self.GetFingerprintAsNumPy(mol)
+
+    def GetFingerprintsFromSmiles(
+        self, smiles_list: Sequence[str],
+        validate: bool = True, canonicalize: bool = True,
+    ) -> tuple[npt.NDArray[np.float64], list[int]]:
+        """Batch fingerprints from SMILES. Returns (embeddings, invalid_indices)."""
+        invalid: list[int] = []
+        valid: list[npt.NDArray[np.float64]] = []
+        for i, smi in enumerate(smiles_list):
+            try:
+                r = self.GetFingerprintFromSmiles(smi, validate=validate, canonicalize=canonicalize)
+            except Exception:
+                r = None
+            if r is None:
+                invalid.append(i)
+            else:
+                valid.append(r)
+        if valid:
+            return np.vstack(valid), invalid
+        return np.empty((0, self._out_dim()), dtype=np.float64), invalid
+
+    def GetFingerprintFromSelfies(
+        self, selfies_str: str, validate: bool = True, canonicalize: bool = True,
+    ) -> npt.NDArray[np.float64] | None:
+        """Generate a fingerprint from a SELFIES string."""
+        import selfies as sf  # type: ignore[import-untyped]
+        try:
+            smiles = sf.decoder(selfies_str)
+        except Exception:
+            return None
+        if smiles is None:
+            return None
+        return self.GetFingerprintFromSmiles(smiles, validate=validate, canonicalize=canonicalize)
+
+    def GetFingerprintsFromSelfies(
+        self, selfies_list: Sequence[str],
+        validate: bool = True, canonicalize: bool = True,
+    ) -> tuple[npt.NDArray[np.float64], list[int]]:
+        """Batch fingerprints from SELFIES. Returns (embeddings, invalid_indices)."""
+        invalid: list[int] = []
+        valid: list[npt.NDArray[np.float64]] = []
+        for i, sel in enumerate(selfies_list):
+            try:
+                r = self.GetFingerprintFromSelfies(sel, validate=validate, canonicalize=canonicalize)
+            except Exception:
+                r = None
+            if r is None:
+                invalid.append(i)
+            else:
+                valid.append(r)
+        if valid:
+            return np.vstack(valid), invalid
+        return np.empty((0, self._out_dim()), dtype=np.float64), invalid
+
+    def clear_cache(self) -> None:
+        """Clear the LRU cache. No-op if caching is disabled."""
+        if self._cached_compute is not None:
+            self._cached_compute.cache_clear()
+
+    def cache_info(self) -> CacheInfo:
+        """Return cache statistics (all zeros when caching is disabled)."""
+        if self._cached_compute is not None:
+            raw = self._cached_compute.cache_info()
+            return CacheInfo(hits=raw.hits, misses=raw.misses, maxsize=raw.maxsize, currsize=raw.currsize)
+        return _EMPTY_CACHE_INFO
+
+    def __repr__(self) -> str:
+        comp = self._compression if self._compression > 0 else None
+        base = (
+            f"EmbeddedFingerprintGenerator(fp_type='{self._fp_type}', "
+            f"fp_size={self._fp_size}, compression={comp}, "
+            f"fp_params={self._fp_params}"
+        )
+        if self._method != "geometric" or self._method_params:
+            base += f", method='{self._method}'"
+            base += f", method_params={self._method_params}"
+        base += ")"
+        return base

fpembed/hashing.py

@@ -0,0 +1,48 @@
+"""Fingerprint parameter hashing for stable cache keys."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+
+def fp_params_hash(
+    fp_type: str,
+    fp_params: dict,
+    *,
+    method: str | None = None,
+    method_params: dict | None = None,
+) -> str:
+    """Compute a 16-char SHA-256 prefix of sorted JSON of {fp_type, **fp_params}.
+
+    Bool values in *fp_params* are normalized to Python ``bool`` before
+    serialization to prevent ``True``/``1`` collisions.
+
+    Args:
+        fp_type: Fingerprint type identifier (e.g. ``"ecfp"``).
+        fp_params: Type-specific fingerprint parameters.
+        method: Compression method name (optional).
+        method_params: Method-specific parameters (optional).
+
+    Returns:
+        A 16-character hexadecimal string.
+    """
+    normalized = {
+        k: int(v) if isinstance(v, bool) else v
+        for k, v in fp_params.items()
+    }
+    payload: dict = {"fp_type": fp_type, **normalized}
+
+    effective_params = method_params or {}
+    if method is not None and not (method == "geometric" and not effective_params):
+        norm_mp = {
+            k: int(v) if isinstance(v, bool) else v
+            for k, v in effective_params.items()
+        }
+        payload["method"] = method
+        if norm_mp:
+            payload["method_params"] = norm_mp
+
+    return hashlib.sha256(
+        json.dumps(payload, sort_keys=True).encode()
+    ).hexdigest()[:16]

fpembed/py.typed

@@ -0,0 +1 @@
+

fpembed/smiles_utils.py

@@ -0,0 +1,63 @@
+"""SMILES/molecule helper functions for the FPembed package."""
+
+from __future__ import annotations
+
+from rdkit import Chem
+from rdkit import rdBase
+
+# Suppress RDKit warnings for invalid SMILES (handled via return values)
+rdBase.DisableLog("rdApp.error")
+rdBase.DisableLog("rdApp.*")
+
+
+def parse_smiles(smiles: str) -> Chem.Mol | None:
+    """Convert a SMILES string to an RDKit Mol object.
+
+    Returns ``None`` for any input that RDKit cannot parse, without raising
+    an exception.
+
+    Args:
+        smiles: A SMILES string representing a molecule.
+
+    Returns:
+        An RDKit Mol object, or ``None`` if the input is invalid.
+
+    Examples:
+        >>> parse_smiles("CCO")  # ethanol
+        <rdkit.Chem.rdchem.Mol object at ...>
+        >>> parse_smiles("not_a_molecule") is None
+        True
+    """
+    try:
+        return Chem.MolFromSmiles(smiles)
+    except Exception:
+        return None
+
+
+def canonicalize_smiles(smiles: str) -> str | None:
+    """Canonicalize a SMILES string.
+
+    Parses the input with RDKit and returns the canonical SMILES form.
+    Returns ``None`` for any input that cannot be parsed or canonicalized.
+
+    Args:
+        smiles: A SMILES string to canonicalize.
+
+    Returns:
+        The canonical SMILES string, or ``None`` if the input is invalid.
+
+    Examples:
+        >>> canonicalize_smiles("OCC")
+        'CCO'
+        >>> canonicalize_smiles("c1ccccc1")
+        'c1ccccc1'
+        >>> canonicalize_smiles("invalid") is None
+        True
+    """
+    try:
+        mol = Chem.MolFromSmiles(smiles)
+        if mol is None:
+            return None
+        return Chem.MolToSmiles(mol)
+    except Exception:
+        return None

fpembed-0.1.0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: fpembed
+Version: 0.1.0
+Summary: Generalized fingerprint embedding library
+License-Expression: MIT
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: rdkit==2026.3.1
+Requires-Dist: numpy==2.2.6
+Requires-Dist: selfies==1.0.2
+Requires-Dist: scikit-fingerprints==2.0.0
+Provides-Extra: app
+Requires-Dist: nicegui>=3.8.0; extra == "app"
+Requires-Dist: optuna>=3.1.0; extra == "app"
+Requires-Dist: pyyaml>=6.0; extra == "app"
+Requires-Dist: altair>=5.0; extra == "app"
+Requires-Dist: pandas>=1.5.2; extra == "app"
+Requires-Dist: scikit-learn>=1.2.0; extra == "app"
+Requires-Dist: tqdm>=4.64.1; extra == "app"
+Dynamic: license-file

fpembed-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+fpembed/__init__.py,sha256=aicXqkvkMOwA6sU1nnn-7DFBqF_cB27nk4G2CAmqMao,1030
+fpembed/compression.py,sha256=V3WkgeYblVpOMcgJIma1gieE8DFtfIIaTe6QmUf9yQE,4751
+fpembed/compression_blockwise.py,sha256=KmGVsgbaxaT-77pyURGAn3Gdqq_0G81vpgwpNFpXz6U,3134
+fpembed/compression_projection.py,sha256=zx6U-gqqWje4OtXQMovXA8PrBYfZezm0q4PbYycbmxQ,4780
+fpembed/generator.py,sha256=20PikSUcoDVtb0SIWj7qu78yT4zqR2JIf-YSg58LeAs,13275
+fpembed/hashing.py,sha256=l2glvBBgxKNzRRNXlc_6-OdMW1126rvkw_8GFVlih5Y,1424
+fpembed/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fpembed/smiles_utils.py,sha256=MnvnPRexwhA_-JLKLgXRXk72Cibf3LHaax02jrH3lyg,1670
+fpembed-0.1.0.dist-info/licenses/LICENSE,sha256=_M7NYM9qJY7gueiMrR51K-1DQ4VG6x06T1uR9nEVmCE,1094
+fpembed-0.1.0.dist-info/METADATA,sha256=1Kd0_SOiMAk_cFVH2B6ZZxWCt1dtVf68ygFpU0Ro7rE,681
+fpembed-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fpembed-0.1.0.dist-info/top_level.txt,sha256=V7Uu_OVnu-a4YO2BjhhuiVz4bJ3Q9_zicZAgpCqhf4c,8
+fpembed-0.1.0.dist-info/RECORD,,

fpembed-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fpembed-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Markovskii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fpembed-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fpembed