Theory

circle_bundles is a toolkit for analyzing and coordinatizing high-dimensional datasets which approximately arise as noisy samples from the total spaces of circle bundles.

This page provides a brief overview of the underlying theory and the algorithms implemented in the package. For a complete theoretical development and proofs, see the accompanying paper [TP25].

Introduction

We use the term circle bundle to refer to any fiber bundle whose fiber is the circle \(\mathbb{S}^1\), not necessarily a principal bundle.

Up to isomorphism, circle bundles over a metric space \(B\) are completely classified by a pair of characteristic classes:

  • the orientation class \(\mathrm{sw}_1 \in H^1(B; \mathbb{Z}_2)\), and

  • the (twisted) Euler class \(\tilde e \in H^2(B; \widetilde{\mathbb{Z}})\),

Crucially, these invariants admit formulations that can be recovered from purely local data. A nonzero characteristic class indicates that the bundle is non-trivial, in the sense that its total space \(E\) is not homeomorphic to the product \(B \times \mathbb{S}^1\). Only trivial bundles admit global circular coordinate systems.

In general, any circle bundle over a compact metric space can be realized as the pullback of the tautological circle bundle

\[V(2,d) \times_{O(2)} \mathbb{S}^1 \;\longrightarrow\; \mathrm{Gr}(2,d),\]

for sufficiently large \(d\). When the total space \(E\) is a low-dimensional manifold embedded in \(\mathbb{R}^D\) with \(D\) large, it is often possible to choose \(d\) such that \(2d \ll D\). This perspective underlies the topology-respecting dimensionality reduction methods implemented in circle_bundles.

In [TP25], the authors introduce the notion of a discrete approximate circle bundle, together with algorithms for estimating characteristic classes and for constructing global coordinate systems that respect the inferred topology. The circle_bundles package implements several of these algorithms.

Algorithms

Overview

Given a dataset \(X\) equipped with a projection \(\pi : X \to B\) and a finite open cover \(\mathcal{U} = \{U_j\}_{j=1}^n\) of the base space, the pipeline proceeds in three main stages:

  1. Cocycle fitting (local trivializations and transition matrices),

  2. Classification (estimation of characteristic classes),

  3. Coordinatization (construction of global bundle coordinates).

Each stage is described in detail below.

Cocycle Fitting

Given a family of local circular coordinate functions

\[f_j : \pi^{-1}(U_j) \to \mathbb{S}^1,\]

the goal is to estimate transition matrices \(\Omega_{jk} \in O(2)\) such that

\[f_j(x) \;\approx\; \Omega_{jk} f_k(x), \quad x \in \pi^{-1}(U_j \cap U_k).\]

This is formulated as a least-squares Procrustes problem over \(O(2)\) on each overlap.

A corresponding weight function

\[w : N(\mathcal{U})^{(1)} \to [0,\infty)\]

is defined by measuring the mean squared alignment error on overlaps. These weights quantify the reliability of each transition and induce a filtration on the nerve of the cover.

Classification

The weight function \(w\) induces a weights filtration \(\{W^r\}_{r \ge 0}\) on the nerve \(N(\mathcal{U})\), where \(W^r\) denotes the maximal subcomplex whose 1-skeleton consists of edges with weight at most \(r\).

Given the simplicial \(O(2)\)-valued cocycle \(\Omega\) and the weights \(w\), the algorithm computes cochains

\[\mathrm{sw}_1 \in C^1(N(\mathcal{U}); \mathbb{Z}_2), \qquad \tilde e \in C^2(N(\mathcal{U}); \mathbb{Z}),\]

representing estimates of the orientation class and twisted Euler class, respectively.

The cobirth and codeath of these classes with respect to the filtration \(\{W^r\}\) are computed. When well-defined, the twisted Euler number (up to sign) is also extracted at the cobirth scale.

Coordinatization

Let \((b_{\mathrm{sw}_1}, d_{\mathrm{sw}_1})\) and \((b_{\tilde e}, d_{\tilde e})\) denote the lifetimes of the estimated characteristic classes.

For a given weight threshold \(r\), the base space is cut along unreliable overlaps to produce a modified space \(B^r\) with an induced cover \(\mathcal{U}^r\) satisfying

\[N(\mathcal{U}^r) = W^r.\]

  • For \(r \le \min\{b_{\mathrm{sw}_1}, b_{\tilde e}\}\), a classifying map

    \[\mathrm{cl}^r : B^r \to \mathrm{Gr}(2,d)\]

    is constructed, together with an associated bundle map

    \[F^r : X \to V(2,d) \times_{O(2)} \mathbb{S}^1 \subset \mathbb{R}^{2d}.\]

  • For \(r \le \min\{d_{\mathrm{sw}_1}, d_{\tilde e}\}\), the bundle over \(B^r\) is trivial, and a global trivialization

    \[F^r : X \to B^r \times \mathbb{S}^1\]

    is produced.

Algorithm 1: Local Trivializations and Transition Matrices

Inputs

  • Dataset \(X\) (point cloud or distance matrix)

  • Projection \(\pi : X \to B\) and good open cover \(\mathcal{U}\)

  • Binary membership array encoding \(\pi(x_m) \in U_j\)

Optional inputs:

  • Local circular coordinates \(\{f_j\}\)

  • Choice of local coordinate algorithm (default: PCA2 or UMAP2)

Outputs

  • Local circular coordinates \(\{f_j\}\)

  • Transition matrices \(\{\Omega_{jk} \in O(2)\}\)

  • Weight function \(w : N(\mathcal{U})^{(1)} \to [0,\infty)\)

Algorithm 2: Characteristic Classes

Inputs

  • Injective weight function \(w\)

  • Simplicial \(O(2)\)-valued 1-cochain \(\Omega\)

Outputs

  • Cochains \(\mathrm{sw}_1\) and \(\tilde e\)

  • Cobirth and codeath scales

  • Twisted Euler number (when defined)

Algorithm 3: Pullback Bundle Coordinates

Inputs

  • Dataset \(X\)

  • Cover membership array

  • Local circular coordinates \(\{f_j\}\)

  • Transition matrices \(\{\Omega_{jk}\}\)

  • Partition of unity subordinate to \(\mathcal{U}\)

  • Weight function \(w\)

  • Threshold \(r\)

Outputs

  • Classifying map \(\mathrm{cl}^r\) and bundle map \(F^r\)

  • Global trivialization when it exists