Hypercube plot
hypercube_plot(output, n_pbits=None, labels=None) (p_kit.visualization) plots a p-circuit's {-1,+1}^n_pbits state space from a sampled +/-1 trajectory. Typical inputs are all_m from Solver.solve(), or a sequence of return_final=True states.
One p-bit can be measured in state -1 or +1. A 3-p-bit system can be measured in any of 2^3 = 8 joint states. Its state space is a literal cube. Each vertex is one possible outcome of measuring all 3 p-bits at once.
Above 3 p-bits, an n-p-bit system's state space is still a cube. It's just an n-dimensional one, a hypercube. Its 2^n vertices connect the same way the 3-cube's do. Two vertices share an edge exactly when they differ in a single p-bit (Hamming distance 1).
You can build the n-cube from two copies of the (n-1)-cube, one for each value of the extra p-bit, with corresponding vertices joined by an edge. That's the recursive construction hypercube_plot uses to draw cubes above n=3 in 3D. Each cube is a nested, shrunk copy, joined vertex-to-vertex to the next.
Above 12 p-bits, 2^n_pbits vertices can no longer be enumerated at all. This page covers that large-n fallback, a 2-or-3-panel statistical view used instead of the exact vertex/edge graph.
What it plots: C(dt) = ⟨m(t)·m(t+dt)⟩ / n_pbits, the average overlap between a state and itself dt samples later. It's compared against a dashed baseline computed by shuffling the trajectory. That baseline shows what "fully decorrelated" looks like for this data.
How to read it:
-
C(0) = 1by definition. A state always matches itself. - How fast the curve drops to the baseline is the system's relaxation time, also called its mixing time. It tells you how many steps of memory the system has.
- A curve that stays elevated well above baseline for a long lag range means the dynamics have real short-term or medium-term memory. A curve that collapses to baseline in 1–2 steps means the state is nearly refreshed every step. In that case, longer-range modeling must come from an explicit memory mechanism, such as concatenating several past states, rather than from the raw dynamics themselves.
Why Hamming distance shows up here: each m_i, m_i' ∈ {-1,+1}, so the product m_i · m_i' is +1 when they agree and -1 when they differ. Summing over all p-bits gives m·m' = (# agreeing) − (# differing) = n − 2·d_H. So the Hamming distance between two states is
d_H(m, m') = (n − m·m') / 2
Dividing by n turns the dot product into the overlap C. That gives d_H(dt) = n_pbits · (1 − C(dt)) / 2. So C(dt) is a rescaled measure of how many hypercube edges separate a state from its own future self. Panel 1 tracks the walk's distance from where it started, on the same hypercube from the intro, as time passes.
What it plots: blue bars show the real trajectory's explained-variance ratio per principal component. Orange bars show the same computation on a null model, where each p-bit's own time series is independently shuffled. That preserves each p-bit's bias and marginal, but destroys all correlation. The title reports the top-3 excess in standard deviations above the null.
How to read it:
- Compare bar heights to judge how much variance concentrates in a few directions versus spreading out.
- Compare the excess in standard deviations, not the raw percentages, to judge whether structure exists at all. The null's error bars are usually tiny. So even a modest-looking height difference can be tens of standard deviations, an unambiguous signal that raw percentages alone would hide.
- When many components are elevated, not just the top two or three, the structure is real but diffuse. It's spread across many directions rather than collapsed onto a low-dimensional manifold. That's normal for a large, fixed, sparse random reservoir. Nothing trains it to organize its own state space; only the readout on top of it is trained.
What it plots: the trajectory projected onto its top-3 PCA directions, colored by a label you supply. One label per sample, for example the token or character id driving that step. This panel only appears when you pass labels.
The title reports a separability ratio: between-group variance divided by within-group variance. A higher ratio means the groups form tighter, more separated clusters. Compare it against the ratio for randomly shuffled labels to judge significance. A ratio near that shuffled baseline, high or low, means no real separation.
How to read it:
- A real organizing variable means knowing a state's label lets you predict roughly where it sits in this 3D projection, and vice versa. States sharing a label cluster together, closer to each other than to states with other labels. That means the label's information is directly recoverable from just 3 coordinates of the raw state. It's a stronger, more visible claim than panel 2's "some structure exists somewhere in 128 dimensions."
- If the separability ratio sits near the shuffled baseline even though panel 2 shows real structure, that doesn't mean there's no structure. It means this particular label isn't what organizes the top-3 PCA directions. The signal may live along different axes, or be tangled up with several labels at once. Try projecting onto a more targeted basis, such as a trained readout's own weight directions, or try a different candidate label, before concluding there's nothing to find.
- If you don't have a natural per-step label, use the variable that's causally closest to what drives each state, such as which input was applied that step, rather than an unrelated auxiliary label. A coarse or indirect grouping, like a category derived from the next output instead of the current input, can dilute a real signal into noise.
| symptom | likely meaning |
|---|---|
| relaxation curve drops to baseline almost immediately | little/no temporal memory in the raw dynamics |
| relaxation curve stays elevated for many lags | real short/medium-term memory |
| PCA bars barely above noise, small std-dev excess | little exploitable low-dimensional structure |
| PCA bars clearly above noise across many components | real but diffuse structure — don't expect a clean 2–3D picture |
| labeled panel shows tight clusters, high separability ratio | that label is a genuine organizing variable |
| labeled panel looks the same as unlabeled, low separability ratio | try a different / more causally direct label before concluding "no structure" |