binny.correlations.topology module

Index-pair and index-tuple topology helpers.

This module provides physics-agnostic utilities for building collections of index correlations and index tuples from one or more sets of integer keys. The focus is on describing common combinatorial topologies that arise when iterating over correlations, blocks, or multi-index objects.

Pairs are described using two indices i and j, while tuples are described using indices i_1, i_2, …, i_n. All outputs are ordered and preserve the order of the input keys. Some topologies treat index positions symmetrically, while others assign a distinct key set to each position.

Supported topologies include full Cartesian products, diagonal selections, and restricted symmetric subsets such as triangular or nondecreasing collections.

binny.correlations.topology.pairs_all(keys: Sequence[int]) → list[tuple[int, int]]

Construct all ordered index correlations from a single key set.

This topology enumerates every possible combination of two indices drawn from the same set. The order of indices matters, so both (i, j) and (j, i) are included whenever i and j are distinct.

Formally, this returns all correlations (i, j) such that i and j are elements of the provided key sequence.

Parameters:

keys – Sequence of integer keys.

Returns:

List of ordered correlations (i, j).

binny.correlations.topology.pairs_cartesian(keys_a: Sequence[int], keys_b: Sequence[int]) → list[tuple[int, int]]

Construct ordered correlations from two distinct key sets.

This topology forms correlations by drawing the first index from one set and the second index from another. The two positions are not interchangeable, and no symmetry is implied.

In index notation, this returns all correlations (i, j) such that i is drawn from the first key set and j is drawn from the second.

Parameters:

• keys_a – Sequence of integer keys for the first index.

• keys_b – Sequence of integer keys for the second index.

Returns:

List of ordered correlations (i, j).

binny.correlations.topology.pairs_diagonal(keys: Sequence[int]) → list[tuple[int, int]]

Construct diagonal index correlations.

This topology keeps only self-correlations, where both indices refer to the same key. It is commonly used when selecting auto-correlations or identity blocks.

In index notation, this returns all correlations (i, i) for i in the key set.

Parameters:

keys – Sequence of integer keys.

Returns:

List of diagonal correlations (i, i).

binny.correlations.topology.pairs_lower_triangle(keys: Sequence[int]) → list[tuple[int, int]]

Construct ordered correlations forming a lower-triangular subset.

This topology is the complement of the upper-triangular selection and retains only those correlations where the first index does not come before the second under the given key ordering.

In index terms, this returns all correlations (i, j) such that i and j are in the key set and i follows or coincides with j in the key order.

Parameters:

keys – Sequence of integer keys defining the ordering.

Returns:

List of ordered correlations (i, j) with i not before j.

binny.correlations.topology.pairs_off_diagonal(keys: Sequence[int]) → list[tuple[int, int]]

Construct all ordered off-diagonal index correlations.

This topology includes every ordered pair except self-correlations. It is useful when diagonal contributions must be excluded while preserving order.

In index notation, this returns all correlations (i, j) such that i and j are in the key set and i differs from j.

Parameters:

keys – Sequence of integer keys.

Returns:

List of ordered off-diagonal correlations (i, j).

binny.correlations.topology.pairs_upper_triangle(keys: Sequence[int]) → list[tuple[int, int]]

Construct ordered correlations forming an upper-triangular subset.

This topology selects a symmetric subset of correlations by keeping only those whose first index does not come after the second under the given key ordering. Each unordered pair appears exactly once.

In index terms, this returns all correlations (i, j) such that i and j are in the key set and i precedes or coincides with j in the key order.

Parameters:

keys – Sequence of integer keys defining the ordering.

Returns:

List of ordered correlations (i, j) with i not after j.

binny.correlations.topology.tuples_all(keys: Sequence[int], n: int) → list[tuple[int, ...]]

Construct all ordered index tuples of fixed length.

This topology enumerates every possible ordered tuple of length n drawn from a single key set. It is the direct higher-order analogue of forming all ordered index correlations.

In index notation, this returns all tuples (i_1, i_2, …, i_n) where each entry is drawn from the key set.

Parameters:

• keys – Sequence of integer keys.

• n – Tuple length.

Returns:

List of ordered n-tuples.

Raises:

ValueError – If n is less than 1.

binny.correlations.topology.tuples_cartesian(keys_list: Sequence[Sequence[int]]) → list[tuple[int, ...]]

Construct ordered tuples from multiple key sequences.

This topology forms tuples by drawing one index from each provided key sequence. Each tuple position has its own independent key domain, and no symmetry between positions is assumed.

In index notation, given key sequences K_1, K_2, …, K_n, this returns all tuples (i_1, i_2, …, i_n) with i_t drawn from K_t for t = 1..n, where n = len(keys_list).

Parameters:

keys_list – Sequence of key sequences, one per tuple position.

Returns:

List of ordered tuples formed from the Cartesian product.

Raises:

ValueError – If keys_list is empty.

binny.correlations.topology.tuples_diagonal(keys: Sequence[int], n: int) → list[tuple[int, ...]]

Construct diagonal index tuples of fixed length.

This topology keeps only tuples where all positions contain the same key. It is useful for selecting purely diagonal or self-coupled contributions in higher-order structures.

In index notation, this returns all tuples (i, i, …, i) of length n for i in the key set.

Parameters:

• keys – Sequence of integer keys.

• n – Tuple length.

Returns:

List of diagonal n-tuples.

Raises:

ValueError – If n is less than 1.

binny.correlations.topology.tuples_nondecreasing(keys: Sequence[int], n: int) → list[tuple[int, ...]]

Construct nondecreasing index tuples of fixed length.

This topology selects a symmetric subset of ordered tuples by requiring that indices do not decrease under the given key ordering. Each unordered combination appears exactly once.

In index notation, this returns all tuples (i_1, i_2, …, i_n) such that i_1 does not come after i_2, and so on through i_n.

Parameters:

• keys – Sequence of integer keys defining the ordering.

• n – Tuple length.

Returns:

List of ordered n-tuples with nondecreasing indices.

Raises:

ValueError – If n is less than 1.