mod landscape_graph

module landscape_graph

Spectral referee over the explored landscape’s transition graph. Spectral referee over the explored landscape.

The catalog and census name basins; observed transitions between them form a weighted graph. The second normalized-Laplacian eigenvalue measures how metastable the explored landscape is, and a Cheeger sweep over its eigenvector selects the lowest-conductance cut in that spectral ordering. An absorbing-chain solve prices the expected number of transitions to reach a chosen set of basins. Together these answer the questions a coordinator faces at an epoch boundary: is the ensemble confined, where is the seam, which pair of basins deserves a bridge, and is local work still worth its price.

Everything is dense arithmetic on a graph no larger than the catalog capacity, so no external eigensolver or sparse machinery appears.

Enums

enum GraphError

Invalid graph query.

UnknownBasin

The queried basin has never been observed.

TooSmall

The query needs at least two basins.

BadAbsorbingSet

The absorbing set must be nonempty and proper.

Eigensolver

The symmetric Laplacian eigensolve did not return a decomposition.

Structs and Unions

struct LandscapeGraph

Weighted transition graph over census basins.

Implementations

impl LandscapeGraph

Functions

fn is_empty(&self) -> bool

Whether no basin has been observed.

fn len(&self) -> usize

Number of basins observed.

fn new() -> Self

An empty graph.

fn observe_basin(&mut self, basin: u64) -> usize

Ensure a basin is present, without any edge.

fn observe_crossing(&mut self, a: u64, b: u64, weight: f64)

Record an observed transition between two basins with a weight. The graph is undirected: confinement is a property of the seam, not of the direction it was crossed in.

fn passage_times(&self, targets: &[u64]) -> Result<HashMap<u64, f64>, GraphError>

Expected number of transitions from every basin to reach any basin of targets, treating observed crossing weights as rates of a discrete jump chain. Basins in targets price at zero; a basin with no path prices at infinity. This is the referee’s stall arithmetic: when the cheapest passage to anywhere new exceeds the remaining budget, local work in the current community is not worth its price.

fn spectral_split(&self) -> Result<SpectralSplit, GraphError>

The spectral split of the landscape, or an error below two basins.

A dense symmetric eigensolve returns the second normalized-Laplacian eigenpair. Every prefix in the degree-corrected Fiedler ordering is evaluated, and the minimum-conductance prefix defines the split. Disconnected graphs are partitioned along whole connected components, avoiding the arbitrary basis inside a degenerate zero eigenspace.

struct SpectralSplit

The two most weakly coupled communities of the explored landscape.

algebraic_connectivity: f64

Second-smallest normalized-Laplacian eigenvalue.

left: Vec<u64>

Basins in the selected Fiedler-sweep prefix.

right: Vec<u64>

Basins in the complementary suffix.

conductance: f64

Cut weight over the smaller side’s volume: the conductance of the split, small when the two communities rarely exchange.

representatives: (u64, u64)

The best-anchored representative on each side: the basin with the largest observed incident weight. Bridges commission between representatives, not between arbitrary members.