neuralqx.graph.core.utils.checks module

Validation and normalisation helpers for GraphHandler edge data.

These utilities enforce a consistent internal representation for graph edges and vertex labels before higher level graph construction begins.

Two vertex labelling conventions are supported.

  • Planar graphs use integer vertex labels, typically \(v \in \{0,\dots,N-1\}\).

  • Non planar graphs use tuple labels, typically coordinates such as \((x,y,z)\).

Multi edges are supported through an explicit integer key \(k\), so an edge is represented as \((u, v, k)\). The key disambiguates distinct edges that share the same endpoints, which is required for multigraphs and for constructing the line graph dual where original edges become dual vertices.

The functions in this module perform the following tasks.

  • Validate edge tuple lengths and key types.

  • Ensure that all edges are either keyed or unkeyed, never a mixture.

  • Insert a default key of 0 when keys are omitted and there is no ambiguity.

  • Detect inconsistent vertex label types and classify the edge set as planar or non planar.

  • Relabel non planar vertex objects to contiguous integer labels while preserving keys.

validate_and_insert_keys(edges)

Validate an edge list and ensure an explicit integer key is present on every edge.

Edges may be provided as either 2 tuples (u, v) or 3 tuples (u, v, key).

Rules enforced.

  • If any edge is provided with a key, then every edge must be provided with a key.

  • Keys must be integers.

  • If keys are omitted, a default key of 0 is inserted.

  • If keys are omitted and the same endpoint pair occurs more than once, the input is ambiguous and an error is raised. In that case, keys must be provided explicitly to distinguish multi edges.

This function does not reorder or canonicalise endpoints. Duplicate detection is based on the ordered pair (u, v) exactly as provided.

Parameters:

edges (List[Union[List, Tuple]]) – List of edges as (u, v) or (u, v, key) entries.

Return type:

List[Tuple]

Returns:

List of normalised edges as 3 tuples (u, v, key) with integer keys.

Raises:

  • TypeError – If any key is not an integer.

  • TypeError – If keyed and unkeyed edges are mixed in the same input list.

  • ValueError – If an edge has an unsupported length.

  • ValueError – If an unkeyed duplicate endpoint pair (u, v) is detected.

check_vertex_type_consistency(edges)

Classify an edge list as planar or non planar by inspecting vertex label types.

This function inspects the endpoint objects u and v appearing in each edge.

  • If every vertex label is an int, the graph is classified as "planar".

  • If every vertex label is a tuple, the graph is classified as "non-planar".

  • If both types appear, the input is considered inconsistent and an error is raised.

Only the first two entries of each edge are used. A key, if present, is ignored.

Parameters:

edges – Iterable of edges where each edge has at least two items.

Returns:

The string "planar" or "non-planar".

Raises:

  • ValueError – If any edge has fewer than two entries.

  • ValueError – If both integer and tuple vertex types are present.

get_vertices_from_edges(edges)

Extract the set of unique vertices from an edge list.

Each edge is expected to have at least two entries, interpreted as the endpoints u and v. Any additional entries, such as a key, are ignored. The returned list is sorted using Python’s default ordering for the vertex objects.

This is intended for two common cases.

  • Planar graphs where vertices are integers and sorting is well defined.

  • Non planar graphs where vertices are tuples and lexicographic sorting provides a stable ordering.

Parameters:

edges – Iterable of edges with endpoints in positions 0 and 1.

Returns:

Sorted list of distinct vertex labels.

Raises:

ValueError – If any edge has fewer than two entries.