neuralqx.graph.core.utils.embedding module

Randomisation utilities for non planar graph embeddings.

This module provides helper functionality to generate a random embedding for a graph whose vertices are already expressed as coordinate tuples. The intended use case is to assign fresh coordinates to an existing non planar edge list while preserving the graph connectivity and edge labels.

A non planar edge is assumed to have the form

\[e = \bigl((x_1,y_1,z_1),(x_2,y_2,z_2),k\bigr)\]

where the first two entries identify the endpoints via their current coordinates and the third entry is an arbitrary edge label or key \(k\).

The randomisation replaces every vertex coordinate \((x,y,z)\) by an independent sample

\[(X,Y,Z) \sim \mathcal N(\mu,\sigma^2)\times\mathcal N(\mu,\sigma^2)\times\mathcal N(\mu,\sigma^2)\]

and returns both the rewritten edge list and the mapping from original vertices to the new coordinates.

randomize_graph_coordinates(edges, mean=0.0, std=5.0, seed=None)

Randomise the coordinates of every vertex in a non planar edge list.

The input is a list of edges of the form

\[\bigl((x_1,y_1,z_1),(x_2,y_2,z_2),k\bigr)\]

Vertices are identified by their coordinate tuples in the input. The function collects the set of unique vertex tuples and assigns each a new coordinate triple sampled from a Gaussian distribution with mean mean and standard deviation std, independently for each Cartesian component.

The output preserves edge labels exactly, and rewrites only the endpoint coordinates.

Parameters:

  • edges (List) – List of non planar edges. Each entry must be a triple (v1, v2, label) where v1 and v2 are coordinate tuples and label is an edge label or key that is preserved.

  • mean (float) – Mean \(\mu\) of the Gaussian used for each coordinate component.

  • std (float) – Standard deviation \(\sigma\) of the Gaussian used for each component.

  • seed (Optional[int]) – Optional integer seed for NumPy’s RNG for reproducible embeddings.

Returns:

Tuple (edges_randomised, coords_map) where edges_randomised is the rewritten edge list with new coordinates and coords_map maps each original vertex tuple to its new coordinate tuple.