neuralqx.utils.symmetries package

class GraphSymmetries(edges, *, max_permutation_edges=10, allow_key_permutations=True, max_total_key_permutations=16384)

Bases: object

Compute permutations, cycles, and automorphisms of an oriented multigraph with parallel edges.

The input edges are oriented and may include parallel edges distinguished by an integer key. For structural computations (permutations / cycles / automorphisms), edge orientation is ignored by converting edges to a canonical, orientation-agnostic form (via _canon_edge). However, the original oriented domain is preserved for indexing and for the concrete permutation objects returned.

Key permutations:

If allow_key_permutations is enabled, automorphisms may additionally permute the keys within each unordered vertex pair, i.e. within each multiedge bucket connecting the same two vertices. This can greatly increase the number of automorphisms, so a cap max_total_key_permutations is used to avoid combinatorial blow-up.

The class lazily computes and caches:

  • permutations: edge permutations (up to a size cap)

  • cycles: cyclic shifts of the canonical edge ordering

  • automorphisms: structure-preserving vertex maps (plus optional within-pair key permutations)

  • graph_symmetries: concatenation of the above

Parameters:

  • edges (Iterable[Tuple[int, int, int]]) – Iterable of oriented keyed edges. Orientation is ignored for structure but preserved in the returned symmetry objects’ domain.

  • max_permutation_edges (int) – If the number of unique canonical edges exceeds this value, permutations returns only the identity (avoids factorial growth).

  • allow_key_permutations (bool) – If True, automorphisms include permutations of keys within each unordered vertex pair when there are multiple parallel edges.

  • max_total_key_permutations (int) – Upper bound on the total number of combinations of per-pair key permutations for a given vertex automorphism. If this cap is exceeded, key permutations fall back to identity per pair.

Raises:

ValueError – If no edges are provided, or if duplicate keys occur within an unordered vertex pair.

Subpackages

Submodules