mod packing

module packing

Packing-family identity from per-center SOAP class histograms.

The exact census radius is quench reproducibility. A book cell is the DECAF histogram of per-atom environments, leader-clustered at a fixed radius, merged at PACKING_MERGE. A packing is a single-linkage community of cells at PACKING_LINK, because isomers of one packing spread further from their own reference than a competing packing sits from it: measured on LJ75, the icosahedral shelf reaches L1 0.56 from the ico reference while ico-Marks is 0.4267. No named morphology enters either comparison.

Variables

const ENVIRONMENT_RADIUS: f64

Leader-clustering radius on per-center local_nu3_z rows. Same number as examples/decaf_local_classes.rs and rewrite_2026/data/decaf/decaf_r14.txt.

Single-linkage radius that separates packings on a shared codebook.

A radius from one reference cannot do this. Measured on quenched isomers within (8varepsilon) of each icosahedral floor, against the sealed fixtures (examples/decaf_packing_separator): the LJ75 shelf reaches L1 (0.56) from the ico reference while ico-Marks is (0.4267), so the shelf spread straddles the gap and no ball around ico holds one and not the other. Single linkage separates them instead.

The radius is the same measurement on both sizes. LJ75, 69 shelf isomers plus both fixtures: Marks stands alone from (0.10) through (0.40) while the shelf chains into one component of 64 to 70, and at (0.45) the shelf reaches Marks. LJ38, 154 shelf isomers, where ico-Oh is (1.1579): Oh stands alone throughout, and the shelf chains 58 of 154 at (0.20), 148 at (0.30), 153 at (0.35), 155 at (0.40). Below (0.30) a smaller cluster over-splits, because one atom carries (2/N) of the histogram; above (0.40) the LJ75 shelf swallows Marks. This is the middle of what both sizes allow.

const PACKING_MERGE: f64

Histogram L1 at or below this is one book cell. The cell grain, not the packing grain: a live LJ75 book puts tens of icosahedral cells above it.

const PACKING_MOVE_EPS: f64

Recompute DECAF only when some atom moved more than this. Sits well below ENVIRONMENT_RADIUS and the packing-family grain.

const PACKING_REFERENCE_DRAWS: usize

Wells a chain draws from the shared catalog each time it arms a Leave.

The cloud is the only place chains meet during a quench, and it was fed one structure per checkpoint. That rate does not depend on how many chains are running, so the bias a chain feels is the same on forty-eight chains as on one and the ensemble buys nothing at the minimisation level. The catalog already holds what the others are standing on, and its size does grow with the ensemble, so an arm takes several entries at once and the repulsion scales with chain count. Twelve fills the PACKING_REFERENCE_CAP within a handful of Leaves while staying well under the round trips a checkpoint can afford.

const PACKING_REFERENCE_MERGE: f64

Histogram L1 below which two references are the same well.

The cloud is what the Leave invert repels a quench from, so what it must hold is where the other chains are, not how many packings they amount to. Deduplicating at the cell grain collapses an ensemble sitting in one funnel to a single entry: measured on LJ75 with the cross-chain feed live, the cloud held exactly one reference at 12, 24 and 48 chains alike, so the chains could not push each other apart during minimisation however many of them there were. Only a structure that is numerically the same well is dropped.

const PACKING_SPEC: SoapSpec

DECAF used SoapSpec::default, not the leftover hop spec.

The angular band stays at l_max 3. On 72 LJ75 points (70 shelf isomers and the two references) the book gap is 0.4267 at l_max 3, 0.4533 at 4, and 1.6267 at 6. Marks is alone at link 0.35 for all three. The join moves from 0.45 to 0.50 to 1.50. At l_max 6 and link 0.35 the icosahedral component holds 64 of 72 LJ75 points and 60 of 159 LJ38 points. A wider band is not the production book.

const SEAM_BINS: usize

Bands kept: up to 0.60, past the 0.35 grain and the measured 0.4267 icosahedral-to-Marks separation.

const SEAM_BIN_WIDTH: f64

Width of one seam band, in the DECAF L1 the grain is quoted in.

const SEAM_BURST_SHOTS: usize

Attempts spent from a doorway while the fluctuation is hot.

The burst is Hop.sharedRound with n attempts against one live structure: the traced conversion took one hop, so the round probability is large exactly here, and the burst multiplies attempts at the only moment that is true. A stale restart measured 0 of 16; the difference between the two is the whole finding.

const SEAM_DOORWAY_GAP: f64

Gap past which an accepted structure is doorway-shaped.

Measured on the traced winning seed: the crossing was one 0.7467 fluctuation, past the grain and past the Marks separation, while ordinary shelf wandering stays under about 0.3. The threshold sits above the wandering and below the measured doorway.

const SEAM_DOORWAY_WINDOW: f64

Energy above the floor past which a far structure is a melt, not a doorway. The traced doorway sat 1.86 eps above the floor of its moment; the median structure past the doorway gap sat twelve above. Six keeps every doorway-like record seen and rejects the melts.

const SEAM_WINDOW: f64

Energy above the incumbent floor past which a structure is a melt rather than a stage of the road. The ico-Marks saddles sit 8.69 and 7.48 eps above the shelf; a 12 eps window keeps every on-road intermediate and rejects the crushed geometries the old 0.35 Cartesian kick produced at +30 and worse.

Functions

fn credit_packing_deposit(coordinates: &[f64], amount: f64)

Record that amount of bias now stands on the well nearest coordinates, so the next hill there can be scaled by what is already deposited.

fn deliver_frontier_post(gap: f64, energy: f64, coordinates: Vec<f64>)

Hand the hop loop one frontier post another chain walked to. The exchange layer calls this on arrivals; the run loop folds them into its seam ladder, which is how the ensemble’s population reaches every stage of the road (Hop.cloning_dominates).

fn different_decaf_family(origin: &[f64], trial: &[f64]) -> bool

Whether trial is a different DECAF packing family from origin.

One throwaway book: observe origin, then histogram trial against that codebook. Occupancy Leave accepts a quench only when this is true. Leftover-SOAP off-well is not a family change.

fn different_packing_family(origin: &[f64], trial: &[f64]) -> bool

leaves_packing against the packings this replica holds on file.

fn drain_frontier_arrivals() -> Vec<(f64, f64, Vec<f64>)>

Drain the arrived frontier posts since the last call.

fn include_packing_reference(coordinates: &[f64])

Include one remotely observed well in the reference cloud without crediting another arrival, and evict from the packing that can spare it.

The cloud is what the Leave invert repels a quench from, so it holds wells rather than packings: an ensemble of 48 chains in one funnel has to push against 48 positions, not against the single packing they collectively occupy. Only a numerically identical well is dropped, at PACKING_REFERENCE_MERGE.

Over the cap the oldest member of the largest community goes, so a community with one member survives: it is the only record that packing exists, and dropping it would let the run rediscover it as new.

fn leaves_packing(origin: &[f64], trial: &[f64], references: &[Vec<f64>]) -> bool

Whether trial sits in a packing that origin and references do not.

One throwaway book over every structure, single linkage at PACKING_LINK, then the community of the trial against the community of the origin. With no references this is the pairwise form: the trial does not chain to the origin.

fn leftover_arrivals_saturated(arrivals: impl IntoIterator<Item = u64>) -> bool

Good–Turing on leftover-well arrivals. n is arrivals, not hops.

fn offer_frontier_post(gap: f64, energy: f64, coordinates: &[f64])

Queue one raw excursion state for the shared frontier ladder. The hop loop calls this at the moment a doorway-shaped structure is accepted; the exchange layer drains and ships at wave cadence.

fn offer_known_minimum(energy: f64, coordinates: &[f64])

Hand the hop loop a minimum some chain has already validated, so its return screen can recognise a descent into that basin and refund the rest of the relaxation.

The reallocation bound closes every channel about where the crossing is; this is the channel about where the chains have been, which they know perfectly. The screen already stops trials returning to the chain’s own position at a measured 37 force calls per hop against 228 unscreened; sharing widens the recognised set, and recognition is monotone in it – Hop.shared_recognition_cheapens – while the acceptance still sees a real quenched energy for the basin, so the per-attempt rate is untouched.

fn packing_communities(histograms: &[Vec<f64>]) -> Vec<usize>

packing_link_labels at PACKING_LINK.

fn packing_community_count(histograms: &[Vec<f64>]) -> usize

Distinct packings among histograms.

fn packing_distance(left: &[f64], right: &[f64]) -> f64

L1 distance between two normalized histograms, zero-padded to a common length.

fn packing_fingerprint(coordinates: &[f64]) -> Option<Vec<f64>>

Histogram of one structure against a throwaway codebook. Tests that compare two structures must share a book; use PackingBook.

Single-linkage community labels at radius, in first-appearance order.

Packing identity is a community of book cells, not a ball around one reference: quenched isomers of one packing spread further from their own reference than a competing packing sits from it. Chaining through the cells the book already holds is what keeps the isomer shelf together and still leaves a genuinely different packing on its own.

fn packing_reference_book() -> Vec<PackingReference>

The cloud with its arrival counts and standing bias.

fn packing_references() -> Vec<Vec<f64>>

Packings on file for this replica, as structures.

fn packing_seam_gap(floor: &[f64], trial: &[f64]) -> f64

DECAF distance from the run’s floor to a trial, in the L1 the grain and the seam bands are quoted in. NaN when either histogram cannot be built, which no band accepts.

fn packing_vector(coordinates: &[f64]) -> Array1<f64>

Dense histogram used by tests that do not hold a coordinator book.

fn remember_packing_reference(coordinates: &[f64])

Record one local arrival in the reference cloud.

A matching well gains one configurational-entropy visit. A novel well is included with its first arrival and follows the same bounded-cloud policy as include_packing_reference.

fn same_packing(left: &[f64], right: &[f64]) -> bool

Whether two histograms belong to one packing family.

fn set_packing_references(references: Vec<Vec<f64>>)

Publish the packings on file. Keeps the newest PACKING_REFERENCE_CAP.

Arrival counts start at one: a well on file has been arrived on once by construction, and a zero count would read as an impossible packing rather than as a rare one.

fn take_frontier_posts() -> Vec<(f64, f64, Vec<f64>)>

Drain the queued outgoing frontier posts for shipping.

fn take_known_minima() -> Vec<(f64, Vec<f64>)>

Drain the minima offered since the last call, for the run loop to fold into its screen bank at its own cadence.

Structs and Unions

struct GoodTuringSample

Good–Turing sample: n arrivals, n1 singletons, n2 doubletons.

n: u64

Independent draws (leftover-well arrivals, not hops).

n1: u64

Types seen exactly once.

n2: u64

Types seen exactly twice. Chao1 uses this.

Implementations

impl GoodTuringSample

Functions

fn chao1_complete(self) -> bool

Chao1 completeness of the packing codebook: no singletons, so (hat S_{mathrm{Chao1}}=S_{mathrm{obs}}). Leftover SOAP still uses Self::saturated (hatch-stable coverage).

fn chao1_unseen(self) -> Option<f64>

Chao, A. (1984), Scand. J. Statist. 11:265-270: unseen-family lower bound (n_1^2/(2n_2)).

Zero when (n_1=0). Unbounded when (n_1>0) and (n_2=0).

fn from_counts(arrivals: impl IntoIterator<Item = u64>) -> Self

Collapse a multiplicity list to n, n1, and n2. Zero counts drop.

fn saturated(self) -> bool

Production floor and unseen-mass ceiling. Leftover-SOAP dwell.

fn unseen(self) -> Option<f64>

Estimated probability the next draw is a new type.

struct PackingBook

Leader-clustered environment codebook and packing-family visits.

Implementations

impl PackingBook

Functions

fn certificate_family_count<I, C>(&self, structures: I) -> usize
where
    I: IntoIterator<Item = C>,
    C: AsRef<[f64]>

Family count occupancy may retire on. Leftover-SOAP Good–Turing plus two singleton DECAF slots is not two occupied funnels.

fn credit_well(&mut self, family: usize)

Credit one leftover-SOAP well arrival to this packing family.

fn families_saturated(&self) -> bool

Chao1 completeness of leftover-well arrivals per DECAF family. Hop re-observes are not draws. Leftover SOAP still uses the unseen-mass ceiling; packing does not.

fn family_of(&self, histogram: &[f64]) -> Option<usize>

Family index without mutating visit counts.

fn histogram(&self, coordinates: &[f64]) -> Option<Vec<f64>>

Normalized class histogram against the current codebook.

Unseen environments share one extra bin so a query cannot mutate the book. Visit/offer is what grows the codebook. A structure whose atoms have not moved by PACKING_MOVE_EPS reuses the last histogram; DECAF cannot change family on that displacement.

fn novelty(&self, histogram: &[f64]) -> f64

L1 to the nearest family that is not this histogram’s family.

fn observe(&mut self, coordinates: &[f64]) -> Option<usize>

Grow the environment codebook from this structure, then count it toward a packing family.

fn occupied_among<I, C>(&self, structures: I) -> usize
where
    I: IntoIterator<Item = C>,
    C: AsRef<[f64]>

Distinct rematched packings among live structures.

fn occupied_family_count(&self) -> usize

Occupied DECAF families on file. Visit count, not leftover-SOAP basin count. Empty until observe records a histogram.

fn occupied_histograms(&self) -> Vec<(usize, Vec<f64>)>

Histogram of each occupied packing family, in family-index order.

One row per book cell with visits, not one row per live replica. The landfold floor folds these, so a packing extras have Left still sits on the map.

fn occupied_packings_among<I, C>(&self, structures: I) -> usize
where
    I: IntoIterator<Item = C>,
    C: AsRef<[f64]>

Distinct packings among live structures, at PACKING_LINK.

Self::occupied_among counts book cells, and isomers of one packing hold tens of them, so counting cells against a packing floor certifies a second funnel that is not there.

fn occupied_well_counts(&self) -> Vec<u64>

Leftover-well counts of occupied families, in family-index order.

Discrete packing (F/kT = -ln(n/n_{max})) uses these, not hop re-observes.

fn unseen_share(&self, coordinates: &[f64]) -> Option<f64>

Share of this structure’s atoms whose local environment matches no cell the book has grown: census surprisal at the cell grain, straight from the descriptor.

The packing gap sums how many atoms changed class and discards which classes, so a crossing into genuinely new environments and a shuffle among the shelf’s old ones read alike. This is the half the gap discards, computed by the machinery the book already runs: the query histogram folds unseen environments into one bin, and the bin’s mass is the answer. No template, no prototype, no reference structure – the codebook is the run’s own history, which is what makes it a coordinate any system carries.

fn version(&self) -> u64

Changes to the book since it was created.

fn visits(&self, family: usize) -> u64

Exact observations assigned to one packing family.

fn well_sample(&self) -> GoodTuringSample

Leftover-well arrivals credited to packing families.

fn well_visits_of(&self, family: usize) -> u64

Leftover-well arrivals credited to one packing family.

fn with_spec(spec: SoapSpec) -> Self

Codebook whose rows are local_nu3_z at spec.

struct PackingPave

Paving pile kept per packing community rather than per basin.

The hop acceptance already walks a biased landscape, but the pile it reads is crate::bias::BasinBias, keyed on the cluster fingerprint. Every icosahedral isomer therefore opens its own account, and the icosahedral shelf of LJ75 carries hundreds of minima that the live book splits into about thirty-two DECAF families. A deposit of 0.25 eps a visit, fragmented that far, never approaches the 8.69 eps between the funnels: the mechanism that could make the funnel expensive never sees it as one place.

Nor can a single walk leave it. Measured from the sealed icosahedral minimum, twenty-four raw quenches dropped along a transformed trajectory reaching 1.87 in DECAF distance, against a Marks separation of 0.4267, every one returned to the floor. What does reach Marks is plain hopping, over a sequence of ordinary moves. So the pile has to tilt the hopping, and to do that it has to be keyed at the grain where icosahedral is one packing.

The cost is a map lookup per hop. A basin’s community is decided once, the first time that basin is seen, by the same single linkage the book uses; afterwards the hop reads the pile by basin id.

Implementations

impl PackingPave

Functions

fn arrivals(&self) -> &[u64]

Arrivals recorded per community, for the census and the report.

fn communities(&self) -> usize

Communities opened so far.

fn community(&mut self, basin: u64, coordinates: &[f64]) -> usize

The community basin belongs to, deciding it if this is the first time that basin has been seen.

A structure joins the first community whose representative it does not leave, which is single linkage at PACKING_LINK against one member. That is the same rule leaves_packing applies and the same one the book folds with.

fn deposit(&mut self, basin: u64, coordinates: &[f64], w0: f64, gamma: f64, temp: f64)

Add one arrival on the community holding basin.

The increment is \(w_0+T\ln n\), the fixed height plus the configurational entropy of a packing reached \(n\) ways, scaled by \(e^{-V/((\gamma-1)T)}\) so the pile converges on \(-\frac{\gamma-1}{\gamma}F\) rather than growing without bound. That is the rule crate::bias::WellTemperedBias already deposits by, with the entropic term the fixed height leaves out.

fn new() -> Self

An empty pile.

fn piles(&self) -> &[f64]

Standing pile per community.

fn potential(&self, basin: u64) -> f64

Standing bias on the community holding basin, or zero for a basin never seen.

struct PackingReference

One well the Leave repels a quench from.

The coordinates are what the invert needs. The other two fields are what tells a run how expensive the well is rather than how deep it is: a packing the ensemble keeps arriving on is entropically stabilised, and its free-energy depth exceeds its potential depth by the temperature times the log of its arrivals.

coordinates: Vec<f64>

Quenched structure.

visits: u32

Arrivals on this well, never zero once it is on file. The configurational entropy of the packing is the log of this.

deposit: f64

Bias already deposited here, so a later hill can be scaled down by what is already standing.

struct SeamBank

Shared frontier along the seam out of the occupied packing.

The crossing to another packing is a staged rare event: measured on LJ75, no single move leaves the icosahedral community, and the chains that reach the Marks decahedron pass it as a sequence of about ten thousand ordinary accepted hops. A chain that reaches a partly converted intermediate and falls back has learned where the seam is, and throwing that structure away makes every other chain start the climb from the floor again: n chains that do not share partial progress deliver expected frontier mass \(n\,p^k\) over a \(k\)-stage road, exponentially small in the depth.

The bank keeps the lowest-energy representative in each band of DECAF distance from the run’s own floor. A stuck chain restarts from the furthest banked structure instead of from the floor, which restores each occupied stage to full population before the next attempt and holds the frontier arrival rate at \(n\,p\) per stage, constant in the depth (Hop.cloning_dominates in proofs/lean/Hop/SeamLadder.lean). Nothing here touches the acceptance rule: geometry, quench and Metropolis stay raw, which is what Hop.road_priced requires – a penalty standing on the road multiplies every stage and can only lose, and 0 of 16 against 2 of 16 on paired seeds is that theorem measured.

Implementations

impl SeamBank

Functions

fn bin_of(gap: f64) -> Option<usize>

The band a gap falls in, None below the first rung.

fn frontier(&self) -> Option<(usize, f64, &[f64])>

The furthest banked structure, with its band index.

fn new() -> Self

An empty bank.

fn occupied(&self) -> usize

Bands currently holding a representative.

fn offer(&mut self, gap: f64, energy: f64, coordinates: &[f64]) -> bool

Offer one accepted, quenched structure at gap from the floor. Returns whether it advanced or improved the frontier.

fn restart(&self, epsilon: f64, u: f64) -> Option<(usize, f64, &[f64])>

A restart point: the frontier with weight 1 - epsilon, otherwise one of the other occupied bands, chosen by the unit draw u.

Restarting only from the top band trusts one structure, and a single poisoned representative – a banked geometry whose forward probability is zero – stalls the ladder with any number of episodes left. Splitting the restart keeps the advance probability positive whenever any banked band can still move, which is Hop.eps_greedy_positive: the frontier term may contribute nothing and the mix still advances.