circle_bundles.lift_base_points

circle_bundles.lift_base_points(G, cl, base_points, *, seed_fiber=0, seed_cluster=0, return_assigned=False, eps=1e-12, noise_label=-1, assume_two_clusters=True, prefer_edge_shared_indices=True)[source]

Assign consistent signs to representative vectors of points in a double cover (e.g. S^2 -> RP^2). Output is a sign choice ± per point.

Parameters:

  • G (nx.Graph) – Cluster graph with nodes (fiber_index, cluster_label). If edges have attribute ‘indices_shared’, we use that to propagate faster/cleaner.

  • cl ((n_fibers, n_points) int) – Fiberwise cluster labels; noise indicated by noise_label.

  • base_points ((n_points, d) float) – Vector representative for each base point.

  • seed_fiber (ints) – Seed a starting cluster to orient.

  • seed_cluster (ints) – Seed a starting cluster to orient.

  • assume_two_clusters (bool) – If True, we apply the “other label opposite” rule in the seed fiber and enforce that each fiber has <= 2 non-noise labels (when present).

  • return_assigned (bool)

  • eps (float)

  • noise_label (int)

  • prefer_edge_shared_indices (bool)

Returns:

  • oriented ((n_points, d) float) – Flipped representatives.

  • assigned ((n_points,) bool (only if return_assigned=True)) – Which points were oriented during propagation.

Return type:

ndarray | Tuple[ndarray, ndarray]

Notes

  • Noise points are ignored for seeding/propagation.

  • Orientation propagation uses a BFS over cluster nodes in G.