Crate rbp_clustering 

Hierarchical k-means clustering for strategic abstraction.

This module reduces the 3.1 trillion unique poker situations into a tractable number of strategically-equivalent buckets. The abstraction proceeds street-by-street, clustering hands based on their distributions over next-street outcomes.

Pipeline

1. River — Cluster by raw equity (win probability against random hands)
2. Turn — Cluster by distribution over river buckets
3. Flop — Cluster by distribution over turn buckets
4. Preflop — Cluster by distribution over flop buckets

Core Types

• Layer — A clustering layer mapping observations to abstract buckets
• Histogram — Distribution over child buckets for a given hand
• Lookup — Precomputed observation → bucket mapping
• Metric — Pairwise EMD distances between buckets

Algorithms

• Elkan — Accelerated k-means with triangle inequality bounds
• Sinkhorn — Entropic optimal transport for EMD computation
• Absorb — Incremental centroid updates during clustering

Persistence

• Artifacts — Serialization of clustering results to PostgreSQL
• Distances — Precomputed distance matrices for online lookup

Structs

Artifacts

Bundle of outputs from clustering a single street.

Bins

A zero-allocation distribution over abstraction buckets.

Bounds

Per-point metadata for Elkan’s accelerated k-means algorithm.

ClusterAbs

Newtype wrapper for Abstraction that implements Support. Used for optimal transport calculations in clustering.

Distances

Dense triangular storage for pairwise distances between abstractions.

EMD

Test fixture for EMD property verification.

Equity

Distance metric for river equity distributions.

Future

Transition model mapping abstractions to next-street histograms.

Heuristic

Greedy heuristic for optimal transport (bipartite matching).

Layer

A clustering layer that maps poker hand isomorphisms to abstract buckets.

Lookup

Mapping from hand isomorphisms to abstraction buckets.

Pair

Compact identifier for an unordered pair of abstractions.

Phi

Zero-allocation potential array for Sinkhorn iteration.

Sinkhorn

Entropic optimal transport via Sinkhorn iteration.

TestLayer

Test layer implementing Elkan trait for algorithm verification.

Enums

Histogram

A distribution over abstraction buckets for a specific street.

Metric

Distance metric between abstractions for a specific street.

Potential

Dual potential for optimal transport computation.

Constants

N_FLOP

N_PREF

Street-specific histogram sizes derived from clustering parameters. Each value is Street::n_abstractions() for that street.

N_RIVE

N_TURN

TRI_FLOP

TRI_PREF

Triangular array sizes: K*(K-1)/2 for each street’s cluster count. These give the number of unique unordered pairs of abstractions.

TRI_TURN

Traits

Absorb

Trait for k-means centroid computation via incremental aggregation.

Elkan

Triangle-inequality accelerated k-means clustering.

Type Aliases

BinsFlop

BinsPref

Type aliases for street-specific bin arrays.

BinsRive

BinsTurn

DistFlop

DistPref

DistTurn

PhiFlop

PhiPref

Street-specific potential type aliases.

PhiRive

PhiTurn