`mod ride_ledger`¶

module ride_ledger¶

Shared same-system scheduling evidence for minimum-mode transition searches. Same-system scheduling and evidence for minimum-mode transition searches.

A ledger belongs to one PES/system-signature coordinator. It never compares energies, basin identifiers, local-environment classes, or outcomes across systems. Replicas communicate by claiming concrete transition experiments and reporting their charged cost and certified result. Failed and duplicate searches remain evidence, preventing the ensemble from blindly repeating work that another live chain has performed.

Variables

const SADDLE_COVERAGE_MAX_UNSEEN_MASS: f64¶: Maximum one-sided unseen-saddle mass accepted as covered.

const SADDLE_COVERAGE_MINIMUM_OBSERVATIONS: u64¶: Minimum stationary observations required for saddle-coverage retirement.

Enums

enum RideDirection¶

One sign of a localized initial mode.

Negative¶: Displace opposite to the generated mode.

Positive¶: Displace along the generated mode.

Traits implemented

impl From<WireRideDirection> for RideDirection¶

enum RideFailure¶

Explicit unsuccessful outcome shared with every replica.

QuenchNotConverged¶: The source quench did not reach its force condition.

SaddleNotConverged¶: Legacy aggregate for a saddle search that did not reach its force condition.

MinimumModeNotConverged¶: Minimum-mode following exhausted its iteration allowance.

PrfoNotConverged¶: Partitioned rational-function refinement exhausted its iteration allowance.

SaddleForceNotConverged¶: Independent saddle certification rejected the final force norm.

ActivationNotEscaped¶: Expanding along the supplied mode did not leave positive curvature.

MinimumModeLostCurvature¶: A force-converged minimum-mode ride no longer had negative curvature.

NoNegativeMode¶: Receiving-side certification found no unstable mode.

HigherIndex¶: Receiving-side certification found more than one unstable mode.

IrcNotConverged¶: An IRC branch did not settle in a minimum.

CollapsedConnection¶: Both IRC branches reached the same exact minimum.

Surface¶: The PES evaluator failed or returned invalid values.

BudgetExhausted¶: The charged-work budget ended during the experiment.

DisconnectedConnection¶: Both downhill branches miss the minimum from which the ride started.

Traits implemented

impl From<WireRideFailure> for RideFailure¶

enum RideLedgerError¶

Invalid source, claim, or report.

EmptyModePortfolio¶: At least one ranked mode is required.

EmptyMethodPortfolio¶: At least one minimum-mode solver is required.

NonfiniteSourceEnergy¶: Source energies must be finite.

EmptyEnvironmentSet¶: A source needs at least one local target.

InvalidEnvironmentRadius¶: Environment clustering needs a finite positive radius.

EmptyEnvironmentFeatures¶: A local descriptor must contain at least one atom and one feature.

EnvironmentFeatureDimension¶

All local descriptors in one codebook use one feature schema.

expected: usize¶: Dimension established by the first observation.

actual: usize¶: Dimension supplied by this observation.

NonfiniteEnvironmentFeature¶: Local descriptor rows must contain only finite values.

UnknownWork(u64)¶: A work identifier is unknown to this ledger.

WrongReplica¶

Only the replica holding a claim may report it.

replica: u32¶: Reporting replica.

work: u64¶: Claimed work identifier.

ConflictingReport(u64)¶: A repeated delivery must carry the same scientific result and cost.

CounterOverflow¶: A monotonic counter cannot be represented.

enum RideOutcome¶

Receiving-side result of a claimed experiment.

Certified¶

An index-one saddle with two exact, distinct IRC endpoints.

saddle: u64¶: Exact saddle identifier within the same system catalogue.

endpoints: [u64; 2]¶: Exact minima connected by the saddle.

Unresolved¶

An index-one saddle whose descent did not expose a distinct edge.

The saddle can be exported to the landscape database and sent to other replicas for deflation even though it contributes no graph edge.

saddle: u64¶: Exact saddle identifier within the same system catalogue.

failure: RideFailure¶: Connectivity failure observed after saddle certification.

Failed(RideFailure)¶: Classified execution failure retained for diagnostics.

Structs and Unions

struct EnvironmentBook¶

Leader-clustered invariant local environments for one system signature.

Implementations

impl EnvironmentBook¶

Functions

fn class_count(&self) -> usize¶: Number of invariant local-environment classes observed in this system.

fn feature(&self, class: u32) -> Option<&[f64]>¶: Invariant feature vector represented by one coordinator-local class.

fn new(radius: f64) -> Result<Self, RideLedgerError>¶: Construct a codebook with a fixed within-system feature radius.

fn observe(&mut self, features: ArrayView2<'_, f64>) -> Result<Vec<EnvironmentTarget>, RideLedgerError>¶

Assign every atom and return one representative for each present class.

Rows must be rotation/permutation-invariant local features produced by the caller’s descriptor contract. Classes are coordinator-local and therefore cannot identify or compare environments from another PES.

struct EnvironmentTarget¶

One representative atom for a local-environment class.

class: u32¶: Coordinator-local environment class.

atom: u32¶: Representative atom in the source structure.

struct RideArm¶

Scientific identity of one transition-search arm.

source_basin: u64¶: Exact source minimum.

environment_class: u32¶: Source-local environment class selected for perturbation.

mode_rank: u16¶: Ranked localized mode seed.

direction: RideDirection¶: Sign of the initial displacement.

method: RideMethod¶: Minimum-mode solver.

struct RideCredit¶

Credit assigned by the coordinator rather than trusted from a worker.

certified_connection: bool¶: Whether receiving-side certification accepted a physical connection.

degenerate_rearrangement: bool¶: Whether both branches are distinct representatives of one exact basin.

failure: Option<RideFailure>¶: Typed negative evidence, absent for a certified connection.

novel_saddle: bool¶: Whether this report introduced a previously unseen exact saddle.

novel_edge: bool¶: Whether this report introduced a previously unseen endpoint pair.

total_charged_evaluations: u64¶: Producer plus receiving-side PES evaluations charged for this report.

struct RideLedger¶

Append-only shared evidence and exclusive live claims for one PES.

Implementations

impl RideLedger¶

Functions

fn active_attempts(&self) -> usize¶: Number of exclusive claims held by live replicas.

fn active_order(&self, work: u64) -> Option<&RideWorkOrder>¶: Active order identified by its coordinator-issued work id.

fn certified_connections(&self) -> u64¶: Number of reports containing a certified index-one connection.

fn charged_evaluations(&self) -> u64¶: PES evaluations charged to completed experiments.

fn claim(&mut self, replica: u32, seed: u64) -> Option<RideWorkOrder>¶

Claim an experiment using only balanced action-space tie breaking.

The coordinator uses Self::claim_ranked for scientific selection. This convenience path assigns least-exposed environment, mode, and exact arms without interpreting saddle or edge outcomes as rewards.

fn claim_arm(&mut self, replica: u32, seed: u64, selected: &RideArm) -> Option<RideWorkOrder>¶

Claim one exact action chosen by an external joint-batch allocator.

An active arm remains exclusive, while retrying from the replica that already holds work returns its existing order unchanged.

fn claim_ranked(&mut self, replica: u32, seed: u64, scores: &BTreeMap<RideArm, f64>) -> Option<RideWorkOrder>¶

Claim the unheld action with the largest minimum-information score.

Scores are supplied by a terminal-energy model outside the network ledger. Exposure counts break exact score ties so concurrent chains do not repeat one action. Saddle identity, edge novelty, and connectivity never enter the ordering.

fn claimable_arms(&self) -> Vec<(RideArm, u32)>¶: Unheld action portfolio with each representative atom.

fn completed_attempts(&self) -> u64¶: Number of completed transition experiments.

fn has_claimable_work(&self) -> bool¶: Whether at least one portfolio arm is not held by a live replica.

fn new(portfolio: RidePortfolio) -> Self¶: Create an empty ledger for one coordinator-owned system signature.

fn register_source(&mut self, source: RideSource) -> Result<(), RideLedgerError>¶

Add one exact source minimum or refresh its energy.

The first complete local-environment observation fixes the source’s portfolio. Re-observing the same exact basin may refine its energy and representative atom for an existing class, but cannot append classes produced by numerical drift around the same minimum.

fn release(&mut self, replica: u32) -> Option<RideWorkOrder>¶: Release a replica’s unfinished claim without fabricating an outcome.

fn report(&mut self, replica: u32, work: u64, charged_evaluations: u64, outcome: RideOutcome) -> Result<RideCredit, RideLedgerError>¶

Report charged cost and a certified or classified result.

Repeated delivery of the same completed report is idempotent. Novelty is computed from the canonical endpoint pair held by the coordinator.

fn saddle_coverage(&self) -> SaddleCoverage¶: Good–Turing/Esty evidence from exact saddle reobservations.

fn unique_degenerate_rearrangements(&self) -> usize¶: Number of exact saddles returning to a symmetry-equivalent basin.

fn unique_edges(&self) -> usize¶: Number of unique exact endpoint pairs.

fn unique_saddles(&self) -> usize¶: Number of unique exact index-one saddles.

struct RidePortfolio¶

Finite initial portfolio crossed with every source environment and sign.

Implementations

impl RidePortfolio¶

Functions

fn methods(&self) -> &[RideMethod]¶: Minimum-mode solvers in deterministic scheduling order.

fn mode_ranks(&self) -> u16¶: Number of initial mode ranks explored for each environment and method.

fn new(mode_ranks: u16, mut methods: Vec<RideMethod>) -> Result<Self, RideLedgerError>¶: Construct a portfolio with mode ranks 0..mode_ranks.

struct RideSource¶

A quenched minimum eligible for transition exploration.

basin: u64¶: Exact basin identifier within one system catalogue.

energy: f64¶: PES energy used only to order sources within this system.

environments: Vec<EnvironmentTarget>¶: Distinct local environments and representative atoms.

struct RideWorkOrder¶

One exclusive assignment to a live replica.

id: u64¶: Monotonic coordinator-local experiment identifier.

replica: u32¶: Replica holding the exclusive claim.

arm: RideArm¶: Scientific arm being evaluated.

representative_atom: u32¶: Atom representing the arm’s local-environment class.

attempt: u64¶: One-based attempt number for this arm.

seed: u64¶: Caller-controlled deterministic random seed.

struct SaddleCoverage¶

Exact-saddle Good–Turing/Esty coverage evidence for one PES.

observations: u64¶: Successful stationary-saddle observations, including reobservations.

singletons: u64¶: Exact saddles observed once.

doubletons: u64¶: Exact saddles observed twice.

unseen_mass_upper: Option<f64>¶: One-sided Esty upper bound on unseen saddle mass.

saturated: bool¶: Whether the observation floor and unseen-mass condition both hold.

mod ride_ledger¶

`mod ride_ledger`¶