pgcuts.losses

Loss functions for probabilistic graph cut optimization.

PRCut losses

class pgcuts.losses.PRCutGradLoss(*args, **kwargs)

PRCut loss with analytical gradient.

Uses the analytical gradient to construct a surrogate loss for backpropagation.

Parameters:

• args (Any)

• kwargs (Any)

forward(w_mat, p_l, p_r, ov_p, n)

Compute surrogate PRCut loss.

Parameters:

• w_mat – Weight tensor, shape (a, b).

• p_l – Left probabilities, shape (a, k).

• p_r – Right probabilities, shape (b, k).

• ov_p – Cluster likelihood, shape (k,).

• n – Number of samples.

Returns:

Scalar loss.

Return type:

Tensor

class pgcuts.losses.PRCutBatchLoss(num_clusters, gamma)

PRCut batch estimate with EMA tracking.

Maintains running estimate of cluster probabilities.

Parameters:

• num_clusters (int)

• gamma (float)

__init__(num_clusters, gamma)

Initialize PRCutBatchLoss.

Parameters:

• num_clusters (int) – Number of clusters.

• gamma (float) – EMA decay rate.

Return type:

None

update_cluster_p(probs)

Update cluster probability estimates.

Parameters:

probs (Tensor) – Assignment probs, shape (n, k).

Return type:

None

property cluster_likelihood: Tensor

Return current cluster likelihood.

forward(w_mat, p_l, p_r)

Compute PRCut batch loss.

Parameters:

• w_mat – Weight tensor, shape (a, b).

• p_l – Left probabilities, shape (a, k).

• p_r – Right probabilities, shape (b, k).

Returns:

Scalar loss.

Return type:

Tensor

class pgcuts.losses.SimplexL2Loss(*args, **kwargs)

Simplex L2 regularization loss.

Parameters:

• args (Any)

• kwargs (Any)

forward(probs, ov_p)

Compute simplex L2 loss.

Parameters:

• probs (Tensor) – Assignment probs, shape (n, k).

• ov_p (Tensor) – Cluster likelihood, shape (k,).

Returns:

Scalar loss.

Return type:

Tensor

H-RCut loss

class pgcuts.losses.HyCutLoss(m, b=1.0, c=2.0, ema_decay=0.9)

Hypergeometric envelope loss for graph cuts.

Uses 2F1(-m, b; c; z) as an upper bound on the expected graph cut.

Parameters:

• m (int)

• b (float)

• c (float)

• ema_decay (float)

__init__(m, b=1.0, c=2.0, ema_decay=0.9)

Initialize HyCutLoss.

Parameters:

• m (int) – Polynomial degree for 2F1.

• b (float) – Second parameter of 2F1.

• c (float) – Third parameter of 2F1.

• ema_decay (float) – EMA decay for cluster proportions.

Return type:

None

forward(p_left, log_p_right, weights, alphas)

Compute the HyCut loss.

Parameters:

• p_left (Tensor) – Softmax probs, shape (E, K).

• log_p_right (Tensor) – Log-softmax probs, shape (E, K).

• weights (Tensor) – Edge weights, shape (E,).

• alphas (Tensor) – EMA cluster proportions, shape (K,).

Returns:

Tuple of (loss, updated_alphas).

Return type:

Tuple[Tensor, Tensor]

RatioCut / NCut losses

class pgcuts.losses.pncut.RatioCutLoss(n, ema_decay=0.0)

Probabilistic RatioCut with hyp envelope.

H_l = 2F1(-m, 1; 2; alpha_bar_l).

Parameters:

• n (int)

• ema_decay (float)

__init__(n, ema_decay=0.0)

Initialize RatioCutLoss.

Parameters:

• n (int) – Dataset size (used as polynomial degree).

• ema_decay (float) – EMA decay for alpha tracking.

Return type:

None

forward(w_mat, probs, alpha_ema=None)

Compute RatioCut envelope loss.

Parameters:

• w_mat (Tensor) – Adjacency matrix, shape (n, n).

• probs (Tensor) – Assignment probs, shape (n, K).

• alpha_ema (Tensor | None) – Running means, shape (K,).

Returns:

(loss, updated_alpha_bar).

Return type:

Tuple[Tensor, Tensor]

class pgcuts.losses.pncut.NCutLoss(degrees, num_bins=16, binning='equal', ema_decay=0.0)

Probabilistic NCut with Holder-binned envelope.

Phi varies per vertex, unlike RatioCut.

Parameters:

• degrees (ndarray)

• num_bins (int)

• binning (str)

• ema_decay (float)

__init__(degrees, num_bins=16, binning='equal', ema_decay=0.0)

Initialize NCutLoss.

Parameters:

• degrees (ndarray) – Vertex degrees, shape (n,).

• num_bins (int) – Number of Holder bins.

• binning (str) – ‘equal’ or ‘log_kmeans’.

• ema_decay (float) – EMA decay for per-bin tracking.

Return type:

None

compute_phi(q, alpha_bars, m)

Compute per-vertex Holder envelope.

Parameters:

• q (Tensor) – Per-vertex degrees, shape (num_v,).

• alpha_bars (Tensor) – Per-bin means, shape (d, K).

• m (int) – Polynomial degree for 2F1.

Returns:

Phi values, shape (num_v, K).

Return type:

Tensor

forward(w_mat, probs, alpha_bars_ema=None)

Compute NCut envelope loss.

Parameters:

• w_mat (Tensor) – Adjacency matrix, shape (n, n).

• probs (Tensor) – Assignment probs, shape (n, K).

• alpha_bars_ema (Tensor | None) – Running per-bin means, shape (d, K).

Returns:

(loss, updated_alpha_bars).

Return type:

Tuple[Tensor, Tensor]

Binning utilities

pgcuts.losses.pncut.equal_size_bins(degrees, num_bins)

Partition vertices into equal-size bins.

Parameters:

• degrees (ndarray)

• num_bins (int)

Return type:

List[dict]

pgcuts.losses.pncut.log_kmeans_bins(degrees, num_bins)

Partition vertices via K-Means on log-degrees.

Parameters:

• degrees (ndarray)

• num_bins (int)

Return type:

List[dict]

pgcuts.losses.pncut.compute_ncut_bin_phi(q_stars, alpha_bars, beta_stars, bin_weights, m)

Compute per-bin envelope Phi (without 1/q).

Parameters:

• q_stars (Tensor) – Per-bin degrees, shape (d,).

• alpha_bars (Tensor) – Per-bin means, shape (d, K).

• beta_stars (Tensor) – Per-bin exponents, shape (d,).

• bin_weights (Tensor) – Holder weights, shape (d,).

• m (int) – Polynomial degree.

Returns:

Phi values, shape (d, K).

Return type:

Tensor