Struct Sampler 

pub struct Sampler { /* private fields */ }

A small, seedable xorshift64* generator. Not cryptographically secure – sampling doesn’t need that – but reproducible given a seed, which greedy argmax already was for free.

Implementations

impl Sampler

pub fn new(seed: u64) -> Self

pub fn xtc_roll(&mut self, params: &SamplingParams) -> Option<f32>

The one uniform draw XTC needs for this token, or None when XTC cannot fire for these parameters.

XTC is the only sampler in the chain that is itself stochastic (llama_sample_xtc_apply draws from its own std::mt19937, src/llama-sampler.cpp:2146), which is why the chain below takes the roll as an argument instead of owning an RNG: the chain is also what sampling_distribution runs for speculative verification, and a filter that drew its own randomness there would make “the distribution the sampler draws from” a different distribution every time it was asked.

The draw is skipped when XTC cannot fire, and that is not an optimisation. Every draw advances the seeded stream, so drawing unconditionally would shift every subsequent token of every existing seeded generation, on every run that never asked for XTC. SamplingParams::xtc_can_fire is the single predicate this and [Candidates::xtc] share.

pub fn sample( &mut self, logits: &[f32], params: &SamplingParams, history: PenaltyWindow<'_>, ) -> usize

Samples one token id from logits, given params and the PenaltyWindow the penalties look back over. Falls back to plain greedy argmax when params.temperature <= 0.0.

history is a window and not a slice on purpose: it carries the PROMPT as well as the generated tokens, which is what llama.cpp penalises over. See crate::penalty_window.

A length-1 logits vector is treated as a precomputed greedy token id (logits[0] as usize) — used by the Metal dense-stack path that returns GPU argmax instead of downloading the full vocab.

pub fn sample_with_mask( &mut self, logits: &[f32], params: &SamplingParams, history: PenaltyWindow<'_>, mask: Option<LogitMask<'_>>, ) -> usize

Like Self::sample, but optionally zeroes disallowed logits via mask before argmax / nucleus sampling (used for JSON-object mode).

pub fn uniform(&mut self) -> f32

A uniform draw in [0.0, 1.0).

Exposed because speculative decoding’s accept test is a coin flip against p_target(x) / p_draft(x) rather than a draw from a distribution, and it must come off the same seeded stream as every other draw in the run or a “reproducible given a seed” generation stops being reproducible.

pub fn sample_from(&mut self, probs: &[f32]) -> usize

Draws one index from an already-normalised distribution.

Split out of Self::sample_with_mask so speculative decoding can sample from a distribution it had to compute anyway (the rejection rule needs p_target itself, not just a draw from it) and still go through exactly the same draw as ordinary sampling. Two separate copies of this loop would be two chances to be subtly non-lossless.