`mod feynman_kac`¶

module feynman_kac¶

Target-free Feynman–Kac reconfiguration for cooperative search chains. Target-free Feynman–Kac reconfiguration for cooperative search chains.

A search epoch supplies one validated representative per chain. The selection potential combines within-epoch energy rank, descriptor novelty, and census scarcity. Systematic resampling keeps the chain population fixed, while a family cap prevents a single observed funnel from occupying every slot. Transition-network inference is diagnostic output rather than population evidence. This is a population-management operator, not a Green-function approximation and not an electronic-structure convergence claim.

Functions

fn ascending_fractional_ranks(values: &[f64]) -> Result<Vec<f64>, ReconfigurationError>¶

Fractional ascending ranks with average ranks for ties.

The minimum has rank zero and the maximum has rank one when at least two distinct positions are present. Positive affine changes of units preserve the result.

fn assign_parents_by_packing(occupants: &[PackingOccupant], max_offspring: usize) -> Vec<u32>¶

Assign parents from the shared Keep/Reseed occupancy rule.

crate::catalog::keep_ids decides who may stay on a packing. The family champion is its own parent. Kept extras adopt the champion (better isomer). Everyone else is an extra beyond the cap: they stay self-parented so the client reseeds instead of cloning the well. A destination never receives a parent from a different packing.

fn population_family_position(destinations: &[u32], parents: &[u32], destination: u32) -> Option<PopulationFamilyPosition>¶

Locate a destination within an immutable replica-addressed genealogy.

Malformed vector lengths, absent destinations, and duplicate destination identities return None so a caller cannot silently adopt the wrong parent.

fn population_rejuvenation_draw(seed: u64, epoch: u64, destination: u32, family_ordinal: usize) -> u64¶

Deterministic descriptor-space rejuvenation draw for one offspring.

Destination identity and family ordinal remain explicit even when several offspring share the same parent, preventing cloned chains from requesting the same catalog-space perturbation.

fn rank_population(members: &[PopulationMember]) -> Result<Vec<RankedPopulationMember>, ReconfigurationError>¶

Rank a complete synchronization population in stable input order.

Novelty is ranked directly. Scarcity is ranked through inverse exact basin visits, so a less-visited census basin receives a higher scarcity rank.

fn reconfiguration_plan(evidence: &[BasinEvidence], coefficients: SelectionCoefficients, systematic_offset: f64, max_offspring: usize) -> Result<ReconfigurationPlan, ReconfigurationError>¶

Build a fixed-size, family-capped reconfiguration plan.

systematic_offset lies in [0, 1) and is stored by the caller as part of the coordinator event. Replaying the same snapshot and offset produces the same parent assignment.

Enums

enum EpochSubmissionOutcome¶

Result of submitting one replica’s evidence to a synchronous epoch.

Pending¶

The epoch remains open until every replica the barrier still requires has submitted.

epoch: u64¶: Open synchronization epoch.

submitted: usize¶: Unique replica submissions received.

required: usize¶: Replicas the barrier still waits on.

Ready(PopulationEpochPlan)¶: All replicas submitted and the immutable parent plan is available.

enum ReconfigurationError¶

Invalid evidence or reconfiguration parameters.

InvalidRank¶

An evidence rank is not finite or lies outside the unit interval.

field: &'static str¶: Name of the invalid evidence component.

value: f64¶: Rejected value.

InvalidParameter¶

A scalar parameter is outside its admissible domain.

field: &'static str¶: Name of the invalid parameter.

value: f64¶: Rejected value.

EmptyPopulation¶: Reconfiguration requires at least one chain.

DuplicateReplica¶

One synchronization epoch contains the same replica more than once.

replica: u32¶: Replica repeated in the submitted population.

UnknownReplica¶

A submission names a replica outside the configured population.

replica: u32¶: Replica absent from the configured ensemble.

EpochMismatch¶

A submission does not belong to the collector’s open epoch.

expected: u64¶: Open synchronization epoch.

received: u64¶: Submitted synchronization epoch.

ConflictingSubmission¶

A replica changed its evidence within one immutable epoch.

epoch: u64¶: Synchronization epoch containing the conflict.

replica: u32¶: Replica that changed its submitted evidence.

Structs and Unions

struct BasinEvidence¶

Target-free evidence attached to one chain at a synchronization epoch.

Implementations

impl BasinEvidence¶

Functions

fn energy_rank(self) -> f64¶: Within-epoch energy rank, where zero is best.

fn new(energy_rank: f64, novelty_rank: f64, scarcity_rank: f64) -> Result<Self, ReconfigurationError>¶

Construct evidence from ranks in [0, 1].

Lower energy rank is better. Higher novelty and scarcity ranks are better. Ranks keep selection pressure independent of energy units and cluster-size-dependent energy scale.

fn novelty_rank(self) -> f64¶: Descriptor novelty rank, where one is most novel.

fn scarcity_rank(self) -> f64¶: Census scarcity rank, where one is least sampled.

struct GenealogyDiagnostics¶

Population and genealogy diagnostics at one synchronization epoch.

effective_sample_size: f64¶: Kish effective sample size of the normalized selection weights.

unique_parents: usize¶: Number of source chains represented among the offspring.

max_family_size: usize¶: Largest number of offspring assigned to one source chain.

offspring_variance: f64¶: Population variance of source-chain offspring counts.

struct PackingOccupant¶

Destination replica with packing-family identity and energy.

replica: u32¶: Replica identity.

family: Option<usize>¶: Packing-family index, or none before DECAF assigns one.

energy: f64¶: Occupant energy; lower is deeper.

struct PopulationEpochPlan¶

Replica-addressed reconfiguration result for one complete epoch.

Implementations

impl PopulationEpochPlan¶

Functions

fn destinations(&self) -> &[u32]¶: Destination replicas in stable ascending order.

fn diagnostics(&self) -> GenealogyDiagnostics¶: Weight and realized-family diagnostics.

fn epoch(&self) -> u64¶: Synchronization epoch represented by this immutable plan.

fn parents(&self) -> &[u32]¶: Parent replica for each destination at the same index.

fn weights(&self) -> &[f64]¶: Normalized source weights in destination/source replica order.

struct PopulationFamilyPosition¶

Stable position of one destination within its realized parent family.

Implementations

impl PopulationFamilyPosition¶

Functions

fn family_size(self) -> usize¶: Number of destinations assigned to this parent.

fn ordinal(self) -> usize¶: Zero-based position among destinations sharing the same parent.

fn parent(self) -> u32¶: Source replica assigned to this destination.

struct PopulationMember¶

Raw coordinator evidence for one replica at a synchronization epoch.

Implementations

impl PopulationMember¶

Functions

fn new(replica: u32, energy: f64, novelty: f64, basin_visits: f64) -> Result<Self, ReconfigurationError>¶: Construct one member from fresh energy, descriptor novelty, and the exact visit count of its immutable census basin.

fn replica(self) -> u32¶: Replica identity within the isolated ensemble.

struct RankedPopulationMember¶

One replica and its coordinator-derived rank evidence.

Implementations

impl RankedPopulationMember¶

Functions

fn evidence(self) -> BasinEvidence¶: Target-free rank evidence derived across the complete population.

fn replica(self) -> u32¶: Replica identity retained from the raw epoch evidence.

struct ReconfigurationPlan¶

Replayable fixed-population assignment for one synchronization epoch.

Implementations

impl ReconfigurationPlan¶

Functions

fn diagnostics(&self) -> GenealogyDiagnostics¶: Selection and realized-genealogy diagnostics.

fn parents(&self) -> &[usize]¶: Parent source index for every destination chain.

fn weights(&self) -> &[f64]¶: Normalized selection weights in source-chain order.

struct SelectionCoefficients¶

Coefficients of the bounded logarithmic selection potential.

energy: f64¶: Pressure toward lower within-epoch energy rank.

novelty: f64¶: Pressure toward descriptor novelty.

scarcity: f64¶: Pressure toward census scarcity.

log_weight_clip: f64¶: Maximum log-weight difference retained before exponentiation.

Implementations

impl SelectionCoefficients¶

Traits implemented

impl Default for SelectionCoefficients¶

struct SynchronousPopulation¶

Coordinator-owned barrier and replay state for fixed-population epochs.

Implementations

impl SynchronousPopulation¶

Functions

fn abstain(&mut self, epoch: u64, replica: u32) -> Result<EpochSubmissionOutcome, ReconfigurationError>¶

Record that a replica will not submit to the open epoch.

A replica reaches this when the barrier arrives and its own state yields no validated representative. Announcing it releases the replicas already waiting, which otherwise poll until their budgets drain, because the barrier requires everyone and a replica that cannot submit never arrives.

fn attach(&mut self, replica: u32) -> Result<(), ReconfigurationError>¶: Add a replica to the roster at runtime, live from now on.

fn completed_plan(&self, epoch: u64) -> Option<&PopulationEpochPlan>¶: Immutable plan for a completed epoch, if that epoch closed.

fn live_replicas(&self) -> Vec<u32>¶: Replicas currently counted live, in configured order.

fn mark_live(&mut self, replica: u32) -> Result<(), ReconfigurationError>¶

Declare that replica is an active walker the barrier waits on.

Unknown identities, including replicas outside the configured roster, return ReconfigurationError::UnknownReplica. A replica already in the live set is accepted again.

fn new(replicas: impl IntoIterator<Item = u32>, coefficients: SelectionCoefficients, max_offspring: usize, seed: u64) -> Result<Self, ReconfigurationError>¶

Construct a collector for one isolated ensemble.

The live roster starts empty, so the barrier waits on every configured replica until a submit sees a nonempty live set or a replica retires.

fn open_epoch(&self) -> u64¶: Epoch currently accepting one submission from every replica.

fn open_requirement(&self) -> usize¶: Replicas the open epoch still requires, after abstentions and retirement from the live roster.

fn retire(&mut self, replica: u32) -> Result<(), ReconfigurationError>¶

Remove replica from the live roster so the barrier no longer waits for it.

Retirement is an abstention from the open epoch: the replica is not a required destination and any submission it already made is dropped. A replica that is already retired is accepted again. Unknown identities return ReconfigurationError::UnknownReplica.

If every live replica has retired and nobody remains to submit, the open epoch closes vacantly so the barrier does not stay open.

fn submit(&mut self, epoch: u64, member: PopulationMember) -> Result<EpochSubmissionOutcome, ReconfigurationError>¶

Submit one replica’s member to the open epoch.

Completes the epoch when every replica the barrier still requires has submitted; a repeat of an identical submission is answered from the completed record.

fn tick(&mut self) -> Result<Option<EpochSubmissionOutcome>, ReconfigurationError>¶: Advance the coordinator clock by one tick, closing the open epoch when its quorum stands past the deadline.

fn with_quorum(mut self, quorum: f64, deadline_ticks: u64) -> Result<Self, ReconfigurationError>¶: Close epochs on quorum of the required roster once deadline_ticks coordinator ticks have passed since the epoch’s first submission.

mod feynman_kac¶

`mod feynman_kac`¶