neuralqx.utils.misc.graph module¶

find_corner_vertex_keyed(edge_pair)¶

Find the common (corner) vertex where two keyed edges meet.

Each edge is assumed to be in keyed form (a, b, k), where a and b are the endpoint vertices and k is an edge key (e.g. to distinguish parallel edges). The key component is ignored when determining adjacency.

The function returns (True, v) if the two edges share exactly one common vertex v. Otherwise it returns (True, False).

Parameters:: edge_pair (Union[tuple, list]) – Pair of keyed edges, each a 3-tuple/list (a, b, k).
Return type:: tuple[bool, Union[bool, Any]]
Returns:: Tuple (True, corner_vertex) if exactly one corner exists, else (True, False).

get_vertices_from_minimal_loop(minimal_loops)¶

Extract the unique vertices traversed by one or more minimal loops (keyed-edge format).

Minimal loops are expected to be sequences of keyed edges (a, b, k). The key k is ignored and only endpoints (a, b) are used to collect vertices. For each provided loop, the returned vertex list is sorted and duplicates are removed.

Parameters:: minimal_loops (Union[list[Any], tuple[Any]]) – One or more minimal loops in keyed-edge representation.
Return type:: list
Returns:: List of vertex-lists, one per input loop, containing the sorted unique vertices.

get_common_base_vertex(triangulation_pair)¶

Return the common base vertices of a pair of triangulations/minimal loops.

The input is a pair of minimal loops in keyed-edge representation. The function extracts the vertex sets of each loop and returns the intersection (the vertices common to both).

Parameters:: triangulation_pair (tuple[Any, ...]) – Pair of minimal loops (keyed-edge representation).
Return type:: list
Returns:: List of vertices common to both loops.

get_edges_at_base_vertex(minimal_loop, base_vertex)¶

Return the pair of edges in a minimal loop that meet at a given base vertex.

The minimal loop is provided in keyed-edge representation. The function iterates over all unordered pairs of edges and returns the first pair whose corner vertex (shared endpoint, ignoring keys) equals base_vertex.

Parameters:

minimal_loop (list) – Minimal loop (triangulation) as a list of keyed edges (a, b, k).
base_vertex (int) – Vertex at which to find the incident edge pair.

Return type:

Optional[tuple]

Returns:

A 2-tuple of keyed edges that meet at base_vertex, or None if no such pair is found.

get_reversed_keyed_edge(edge, as_list=False)¶

Reverse a keyed edge while keeping the key in the last position.

For an edge (a, b, k), the reversed keyed edge is (b, a, k). If as_list is True, the result is returned as a list instead of a tuple.

Parameters:

edge (Union[tuple, list]) – Keyed edge (a, b, k).
as_list (bool) – If True, return the reversed edge as a list. Defaults to False.

Return type:

tuple

Returns:

Reversed keyed edge with the key preserved as the last element.

get_triplets_key(edges, vertex)¶

Enumerate all ordered edge triplets incident to a given vertex (keyed-edge format).

The function filters the provided keyed edges to those connected to vertex (membership checked against the endpoint portion of the edge, i.e. edge[:-1]), then returns all length-3 permutations of those incident edges.

Parameters:

edges (list[list]) – List of keyed edges of the graph, each of the form (a, b, k).
vertex (int) – Vertex at which to collect incident edge triplets.

Return type:

list[list]

Returns:

List of edge triplets (as lists), containing all permutations of three incident edges.

reorder_edge_triplet_key(edge_triplet, base_vertex)¶

Orient a keyed edge triplet so each edge has the desired direction relative to base_vertex.

The triplet is interpreted positionally:

edge_triplet[0] is treated as an outgoing edge and is oriented to start at base_vertex.
edge_triplet[1] is treated as an incoming edge and is oriented to end at base_vertex.
edge_triplet[2] is treated as a segment edge and is oriented to start at base_vertex.

Whenever an edge must be reversed to satisfy the orientation constraint, a factor of -1 is accumulated. The returned sign is the product of these factors.

Parameters:

edge_triplet (list[list]) – List of three keyed edges (a, b, k).
base_vertex (int) – Vertex with respect to which orientations are enforced.

Return type:

tuple[list[Union[int, list[int], list]], int]

Returns:

Tuple (reordered_triplet, sign) where reordered_triplet is the reoriented triplet and sign is +1 or -1.

find_minimal_loops_with_edges_key(minimal_loop_list, edge_pair)¶

Find all minimal loops that contain a specified pair of keyed edges (up to orientation).

The function checks each minimal loop in minimal_loop_list and includes it if both edges in edge_pair appear in the loop either in the same orientation or reversed (endpoint-flipped, key preserved).

Parameters:

minimal_loop_list (list) – List of minimal loops, each a list of keyed edges (a, b, k).
edge_pair (list) – Pair of keyed edges (as lists/tuples) to search for within each loop.

Return type:

list[list]

Returns:

List of minimal loops that contain both edges in the pair (considering both orientations).

Raises:

ValueError – If the two edges in edge_pair refer to the same edge (possibly reversed).

reorder_minimal_loop_key(minimal_loop, edge_pair)¶

Reorder and reorient a keyed minimal loop to start/end with a specified edge pair.

Given a minimal loop (a cyclic sequence of keyed edges) and a pair of keyed edges [start, end], this function constructs a new path that:

begins with start,
follows the loop in consistent orientation by matching consecutive endpoints, and
ends with end,

while reversing intermediate edges as needed so that each edge starts at the current vertex. The function ensures the chosen end edge is oriented to share the base vertex with the start edge (i.e. the start’s first vertex matches the end’s second vertex), if not, end is reversed before path construction.

Parameters:

minimal_loop (list[list[int]]) – Minimal loop as a list of keyed edges (a, b, k).
edge_pair (list[list[int]]) – Two keyed edges [start, end] specifying the first and last edges of the reordered loop.

Return type:

list[list[int]]

Returns:

Reordered minimal loop (list of keyed edges) starting with start and ending with end.

Raises:

ValueError – If the remaining edges cannot be connected into a continuous path.

detect_edge_orientation_key(graph, edge, graph_shift)¶

Determine holonomy operator type for an edge relative to an underlying graph orientation.

The edge is shifted by graph_shift (using neuralqx.utils.misc.arithmetic.minus_key()) and checked for membership in graph.edges. If present, the edge is classified as "creation", otherwise it is classified as "annihilation".

Parameters:

graph – Graph object providing an edges container for membership testing.
edge (list) – Keyed edge (a, b, k) (as a list/tuple) whose orientation is to be classified.
graph_shift (int) – Constant shift applied to the edge endpoints prior to membership testing.

Return type:

str

Returns:

Either "creation" or "annihilation".

create_dressed_minimal_loop_key(graph, minimal_loop, graph_shift)¶

Attach holonomy-operator metadata to each edge in a keyed minimal loop.

For each edge in minimal_loop, the function determines the operator type using detect_edge_orientation_key() and returns a new “dressed” representation where each entry is a pair:

the keyed edge as a tuple (a, b, k), and
a metadata dict containing {"type": <creation|annihilation>, "key": k}.

Parameters:

graph – Graph object providing an edges container for membership testing.
minimal_loop (list[list]) – Minimal loop as a list of keyed edges (a, b, k).
graph_shift (int) – Constant shift applied when classifying each edge’s operator type.

Return type:

list[tuple[tuple[Any, Any, Any], dict[str, str | Any]]]

Returns:

Dressed minimal loop as a list of ((a, b, k), metadata) entries.

count_contributing_triplets_key(levi_civita_dict, triplets)¶

Count edge triplets with positive Levi-Civita contribution.

The function counts how many edge triplets in triplets have Levi-Civita value ε(e₁, e₂, e₃) = +1 according to levi_civita_dict. Triplets are stringified as str(tuple(triplet)) for lookup.

This count is used as the contributing-triplets factor (often denoted T) in regularized Euclidean Thiemann-type constructions.

Parameters:

levi_civita_dict (dict) – Dictionary mapping stringified edge triplets to Levi-Civita values.
triplets (list) – List of edge triplets to test.

Return type:

int

Returns:

Number of triplets with Levi-Civita value equal to +1.

get_ml_graph_shift_key(minimal_loop, mapping, adjoint=False)¶

Split a dressed minimal loop into holonomy and adjoint-holonomy edge lists.

The input minimal_loop is expected to be in “dressed” form where each element contains a keyed edge and a metadata dict with a "type" field. Edges tagged as "creation" are collected under "h" and all others under "ha" after applying mapping to the keyed edge.

If adjoint is True, the roles of "h" and "ha" are swapped in the returned dict.

Parameters:

minimal_loop (list[tuple[int, int, dict]]) – Dressed minimal loop entries of the form (edge, meta) where meta["type"] indicates operator type.
mapping (callable) – Callable applied to each keyed edge prior to insertion into the output lists.
adjoint (bool) – If True, swap the returned lists under keys "h" and "ha".

Return type:

dict

Returns:

Dict with keys "h" and "ha" containing the mapped edge lists.

get_true_edge_triplet(edge_list, G)¶

Reorient an edge triplet so every edge is present in G.edges.

For each edge in edge_list, the function checks membership in G.edges. If the edge is not present, it is replaced by its reversed keyed form (endpoint-flipped, key preserved).

Parameters:

edge_list (Union[List, Tuple]) – Iterable of keyed edges to be checked/reoriented.
G (AbstractGraph) – Graph providing an edges container for membership testing.

Return type:

Tuple

Returns:

Tuple of keyed edges where each edge is guaranteed to be in G.edges.

reduce_permutations(perms)¶

Reduce a list of 3-edge permutations by identifying swap-equivalent entries.

Given permutations of triplets (a, b, c), this function removes duplicates where the last edge c is the same and the first two edges are swapped, i.e. it keeps only one of (a, b, c) and (b, a, c) for each pair.

Parameters:: perms (List) – List of ordered triplets (permutations) of three edges.
Returns:: Filtered list where swap-equivalent triplets differing only by the order of the first two edges have been removed.