verskyt.core¶

Core mathematical functions for Tversky similarity computation.

Module: similarity¶

Core implementation of differentiable Tversky similarity.

Based on “Tversky Neural Networks: Psychologically Plausible Deep Learning with Differentiable Tversky Similarity” (Doumbouya et al., 2025).

class IntersectionReduction(value)[source]¶

Bases: str, Enum

Methods for reducing feature intersections (A ∩ B).

These methods determine how to aggregate feature membership scores when computing the intersection between two objects in the feature space.

PRODUCT¶: Element-wise product of membership scores (default/best performing).

MIN¶: Element-wise minimum of membership scores.

MAX¶: Element-wise maximum of membership scores.

MEAN¶: Element-wise arithmetic mean of membership scores.

GMEAN¶: Element-wise geometric mean of membership scores.

SOFTMIN¶: Differentiable soft minimum using LogSumExp trick.

PRODUCT = 'product'¶

MIN = 'min'¶

MAX = 'max'¶

MEAN = 'mean'¶

GMEAN = 'gmean'¶

SOFTMIN = 'softmin'¶

class DifferenceReduction(value)[source]¶

Bases: str, Enum

Methods for reducing feature differences (A - B).

These methods determine how to compute the distinctive features of one object compared to another, implementing Equations 4 and 5 from the paper.

IGNOREMATCH¶: Only count features present in A but not in B (Equation 4).

SUBSTRACTMATCH¶: Account for magnitude differences in shared features (Equation 5).

IGNOREMATCH = 'ignorematch'¶

SUBSTRACTMATCH = 'substractmatch'¶

compute_feature_membership(x: Tensor, features: Tensor) → Tensor[source]¶

Compute feature membership scores for objects.

This function computes how much each feature from the feature bank is present in each object. The membership score is computed as the dot product between object vectors and feature vectors.

Parameters:

x (torch.Tensor) – Object vectors of shape [batch_size, in_features] or [num_objects, in_features].
features (torch.Tensor) – Feature bank of shape [num_features, in_features].

Returns:

Membership scores of shape [batch_size, num_features] or: [num_objects, num_features]. Higher values indicate stronger presence of the feature in the object.

Return type:

torch.Tensor

Note

Implementation uses Einstein summation for efficient computation: x·fₖ represents the measure of feature fₖ in object x (from paper).

compute_salience(x: Tensor, features: Tensor) → Tensor[source]¶

Compute salience of objects (Equation 2 from paper).

Salience measures the total amount of features present in an object. It is computed as the sum of all positive feature membership scores, representing the psychological notion of an object’s perceptual prominence.

Parameters:

x (torch.Tensor) – Object vectors of shape [batch_size, in_features].
features (torch.Tensor) – Feature bank of shape [num_features, in_features].

Returns:

Salience scores of shape [batch_size]. Higher values: indicate objects with more prominent features.

Return type:

torch.Tensor

Note

Only positive memberships are summed, as negative values indicate absence of features. Implements Equation 2: salience(x) = Σᵢ max(0, x·fᵢ).

tversky_similarity(x: Tensor, prototypes: Tensor, feature_bank: Tensor, alpha: Tensor | float, beta: Tensor | float, theta: float = 1e-07, intersection_reduction: IntersectionReduction | str = 'product', difference_reduction: DifferenceReduction | str = 'substractmatch', normalize_features: bool = False, normalize_prototypes: bool = False) → Tensor[source]¶

Compute Tversky similarity between inputs and prototypes.

This is the core function implementing differentiable Tversky similarity for neural networks. It computes psychologically-motivated similarity scores that account for both common and distinctive features.

The function implements the Tversky Index formulation (Equation 1): TI(a,b) = f(A∩B) / (f(A∩B) + αf(A-B) + βf(B-A))

Where: - f(A∩B): Intersection - features common to both objects - f(A-B): Features distinctive to object A - f(B-A): Features distinctive to object B - α, β: Asymmetry parameters (α=β=0.5 gives Jaccard similarity)

Parameters:

x (torch.Tensor) – Input tensor of shape [batch_size, in_features].
prototypes (torch.Tensor) – Prototype tensor of shape [num_prototypes, in_features].
feature_bank (torch.Tensor) – Feature bank tensor of shape [num_features, in_features].
alpha (Union[torch.Tensor, float]) – Weight for x’s distinctive features. Higher values make the similarity more sensitive to features in x but not in prototypes. Must be ≥ 0.
beta (Union[torch.Tensor, float]) – Weight for prototype’s distinctive features. Higher values make the similarity more sensitive to features in prototypes but not in x. Must be ≥ 0.
theta (float, optional) – Small constant for numerical stability. Defaults to 1e-7.
intersection_reduction (Union[IntersectionReduction, str], optional) – Method for computing feature intersections. Options: “product” (default/best performing), “min”, “max”, “mean”, “gmean”, “softmin”. Defaults to “product”.
difference_reduction (Union[DifferenceReduction, str], optional) – Method for computing feature differences. Defaults to “substractmatch”.
normalize_features (bool, optional) – Whether to L2-normalize feature vectors. Defaults to False.
normalize_prototypes (bool, optional) – Whether to L2-normalize input and prototype vectors. Defaults to False.

Returns:

Similarity scores of shape [batch_size, num_prototypes].: Values are in [0, 1] range, with 1 indicating perfect similarity.

Return type:

torch.Tensor

Raises:

ValueError – If alpha or beta are negative, or if reduction methods are invalid.

Example

>>> import torch
>>> x = torch.randn(2, 4)  # 2 samples, 4 dimensions
>>> prototypes = torch.randn(3, 4)  # 3 prototypes
>>> features = torch.randn(8, 4)  # 8 features
>>> similarity = tversky_similarity(x, prototypes, features, 0.5, 0.5)
>>> similarity.shape
torch.Size([2, 3])

tversky_contrast_similarity(x: Tensor, prototypes: Tensor, feature_bank: Tensor, alpha: Tensor | float, beta: Tensor | float, theta: Tensor | float = 1.0, intersection_reduction: IntersectionReduction | str = 'product', difference_reduction: DifferenceReduction | str = 'substractmatch') → Tensor[source]¶

Compute Tversky contrast model similarity (alternative formulation).

This function implements the linear combination form of Tversky similarity rather than the normalized ratio form. It may be preferred when working with raw similarity scores or when the denominator normalization is handled elsewhere in the model.

Uses the linear combination from Equation 1: S(a,b) = θf(A∩B) - αf(A-B) - βf(B-A)

Parameters:

x (torch.Tensor) – Input tensor of shape [batch_size, in_features].
prototypes (torch.Tensor) – Prototype tensor of shape [num_prototypes, in_features].
feature_bank (torch.Tensor) – Feature bank tensor of shape [num_features, in_features].
alpha (Union[torch.Tensor, float]) – Weight for x’s distinctive features.
beta (Union[torch.Tensor, float]) – Weight for prototype’s distinctive features.
theta (Union[torch.Tensor, float], optional) – Weight for common features. Defaults to 1.0.
intersection_reduction (Union[IntersectionReduction, str], optional) – Method for computing intersections. Defaults to “product”.
difference_reduction (Union[DifferenceReduction, str], optional) – Method for computing differences. Defaults to “substractmatch”.

Returns:

Similarity scores of shape [batch_size, num_prototypes].: Unlike the Tversky Index, these scores are not bounded to [0,1] and can be negative.

Return type:

torch.Tensor

Note

This formulation is useful when you want the raw contrast scores without normalization, or when combining with other similarity measures.

Classes¶

IntersectionReduction¶

class IntersectionReduction(value)[source]¶

Methods for reducing feature intersections (A ∩ B).

These methods determine how to aggregate feature membership scores when computing the intersection between two objects in the feature space.

PRODUCT¶: Element-wise product of membership scores (default/best performing).

MIN¶: Element-wise minimum of membership scores.

MAX¶: Element-wise maximum of membership scores.

MEAN¶: Element-wise arithmetic mean of membership scores.

GMEAN¶: Element-wise geometric mean of membership scores.

SOFTMIN¶: Differentiable soft minimum using LogSumExp trick.

PRODUCT = 'product'¶

MIN = 'min'¶

MAX = 'max'¶

MEAN = 'mean'¶

GMEAN = 'gmean'¶

SOFTMIN = 'softmin'¶

DifferenceReduction¶

class DifferenceReduction(value)[source]¶

Methods for reducing feature differences (A - B).

These methods determine how to compute the distinctive features of one object compared to another, implementing Equations 4 and 5 from the paper.

IGNOREMATCH¶: Only count features present in A but not in B (Equation 4).

SUBSTRACTMATCH¶: Account for magnitude differences in shared features (Equation 5).

IGNOREMATCH = 'ignorematch'¶

SUBSTRACTMATCH = 'substractmatch'¶

Functions¶

tversky_similarity¶

Compute Tversky similarity between inputs and prototypes.

The function implements the Tversky Index formulation (Equation 1): TI(a,b) = f(A∩B) / (f(A∩B) + αf(A-B) + βf(B-A))

Parameters:

x (torch.Tensor) – Input tensor of shape [batch_size, in_features].
prototypes (torch.Tensor) – Prototype tensor of shape [num_prototypes, in_features].
feature_bank (torch.Tensor) – Feature bank tensor of shape [num_features, in_features].
alpha (Union[torch.Tensor, float]) – Weight for x’s distinctive features. Higher values make the similarity more sensitive to features in x but not in prototypes. Must be ≥ 0.
beta (Union[torch.Tensor, float]) – Weight for prototype’s distinctive features. Higher values make the similarity more sensitive to features in prototypes but not in x. Must be ≥ 0.
theta (float, optional) – Small constant for numerical stability. Defaults to 1e-7.
intersection_reduction (Union[IntersectionReduction, str], optional) – Method for computing feature intersections. Options: “product” (default/best performing), “min”, “max”, “mean”, “gmean”, “softmin”. Defaults to “product”.
difference_reduction (Union[DifferenceReduction, str], optional) – Method for computing feature differences. Defaults to “substractmatch”.
normalize_features (bool, optional) – Whether to L2-normalize feature vectors. Defaults to False.
normalize_prototypes (bool, optional) – Whether to L2-normalize input and prototype vectors. Defaults to False.

Returns:

Similarity scores of shape [batch_size, num_prototypes].: Values are in [0, 1] range, with 1 indicating perfect similarity.

Return type:

torch.Tensor

Raises:

ValueError – If alpha or beta are negative, or if reduction methods are invalid.

Example

>>> import torch
>>> x = torch.randn(2, 4)  # 2 samples, 4 dimensions
>>> prototypes = torch.randn(3, 4)  # 3 prototypes
>>> features = torch.randn(8, 4)  # 8 features
>>> similarity = tversky_similarity(x, prototypes, features, 0.5, 0.5)
>>> similarity.shape
torch.Size([2, 3])

tversky_contrast_similarity¶

Compute Tversky contrast model similarity (alternative formulation).

Uses the linear combination from Equation 1: S(a,b) = θf(A∩B) - αf(A-B) - βf(B-A)

Parameters:

x (torch.Tensor) – Input tensor of shape [batch_size, in_features].
prototypes (torch.Tensor) – Prototype tensor of shape [num_prototypes, in_features].
feature_bank (torch.Tensor) – Feature bank tensor of shape [num_features, in_features].
alpha (Union[torch.Tensor, float]) – Weight for x’s distinctive features.
beta (Union[torch.Tensor, float]) – Weight for prototype’s distinctive features.
theta (Union[torch.Tensor, float], optional) – Weight for common features. Defaults to 1.0.
intersection_reduction (Union[IntersectionReduction, str], optional) – Method for computing intersections. Defaults to “product”.
difference_reduction (Union[DifferenceReduction, str], optional) – Method for computing differences. Defaults to “substractmatch”.

Returns:

Similarity scores of shape [batch_size, num_prototypes].: Unlike the Tversky Index, these scores are not bounded to [0,1] and can be negative.

Return type:

torch.Tensor

Note

This formulation is useful when you want the raw contrast scores without normalization, or when combining with other similarity measures.

compute_feature_membership¶

compute_feature_membership(x: Tensor, features: Tensor) → Tensor[source]¶

Compute feature membership scores for objects.

This function computes how much each feature from the feature bank is present in each object. The membership score is computed as the dot product between object vectors and feature vectors.

Parameters:

x (torch.Tensor) – Object vectors of shape [batch_size, in_features] or [num_objects, in_features].
features (torch.Tensor) – Feature bank of shape [num_features, in_features].

Returns:

Membership scores of shape [batch_size, num_features] or: [num_objects, num_features]. Higher values indicate stronger presence of the feature in the object.

Return type:

torch.Tensor

Note

Implementation uses Einstein summation for efficient computation: x·fₖ represents the measure of feature fₖ in object x (from paper).

compute_salience¶

compute_salience(x: Tensor, features: Tensor) → Tensor[source]¶

Compute salience of objects (Equation 2 from paper).

Parameters:

x (torch.Tensor) – Object vectors of shape [batch_size, in_features].
features (torch.Tensor) – Feature bank of shape [num_features, in_features].

Returns:

Salience scores of shape [batch_size]. Higher values: indicate objects with more prominent features.

Return type:

torch.Tensor

Note

Only positive memberships are summed, as negative values indicate absence of features. Implements Equation 2: salience(x) = Σᵢ max(0, x·fᵢ).