Struct LinUcb 

pub struct LinUcb { /* private fields */ }

Available on crate feature bandit only.

LinUCB contextual multi-armed bandit.

Maintains a per-arm ridge-regression model and selects the arm with the highest upper confidence bound on the expected reward for the given context.

Examples

use rill_ml::bandit::{ContextualBandit, LinUcb, LinUcbConfig};
use rand::SeedableRng;
use rand_chacha::ChaCha8Rng;

let mut config = LinUcbConfig::default();
config.alpha = 1.0;
config.arm_count = 2;
config.feature_count = 2;
let mut bandit = LinUcb::new(config).unwrap();
let mut rng = ChaCha8Rng::seed_from_u64(0);

let context = [0.5, 0.8];
let arm = bandit.select(&context, &mut rng).unwrap();
bandit.update(arm, &context, 1.0).unwrap();
assert_eq!(bandit.samples_seen(), 1);

Implementations

impl LinUcb

pub fn new(config: LinUcbConfig) -> Result<Self, RillError>

Create a new LinUCB bandit from the given configuration.

Errors

Returns RillError::InvalidArmCount if arm_count is zero. Returns RillError::InvalidFeatureCount if feature_count is zero. Returns RillError::InvalidParameter if alpha is not finite and positive.

pub const fn alpha(&self) -> f64

The exploration parameter alpha.

pub fn a_matrix(&self, arm: usize) -> Result<&[Vec<f64>], RillError>

Borrow the A matrix for a specific arm (diagnostic).

Errors

Returns RillError::InvalidArm if arm is out of range.

pub fn b_vector(&self, arm: usize) -> Result<&[f64], RillError>

Borrow the b vector for a specific arm (diagnostic).

Errors

Returns RillError::InvalidArm if arm is out of range.

pub fn validate(&self) -> Result<(), RillError>

Validate all persisted state invariants.

This is also run automatically during deserialization.

pub fn score_arm( &self, arm: usize, context: &[f64], ) -> Result<LinUcbArmScore, RillError>

Compute the explainable UCB score for one arm.

The returned exploration bonus already includes alpha.

pub fn score_all( &self, context: &[f64], ) -> Result<Vec<LinUcbArmScore>, RillError>

Compute explainable UCB scores for every arm.

pub fn select_with_scores( &self, context: &[f64], rng: &mut impl Rng, ) -> Result<(usize, Vec<LinUcbArmScore>), RillError>

Select an arm with the existing randomized tie-break and return every score used by that decision.

pub fn select_deterministic(&self, context: &[f64]) -> Result<usize, RillError>

Select deterministically, resolving exact score ties to the lowest arm index. This does not change the randomized ContextualBandit::select contract and is intended for replay and audit paths.

pub fn condition_diagnostics( &self, arm: usize, ) -> Result<LinUcbConditionDiagnostics, RillError>

Return a bounded numerical condition diagnostic for one arm.

Trait Implementations

impl Clone for LinUcb

fn clone(&self) -> LinUcb

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ContextualBandit for LinUcb

fn arm_count(&self) -> usize

The number of arms (actions) available.

fn feature_count(&self) -> usize

The number of features in the context vector.

fn samples_seen(&self) -> u64

How many total samples the bandit has observed.

fn select( &self, context: &[f64], rng: &mut impl Rng, ) -> Result<usize, RillError>

Select an arm given the context vector, using the provided RNG.

fn update( &mut self, arm: usize, context: &[f64], reward: f64, ) -> Result<(), RillError>

Update the bandit with the observed reward for a previously selected arm.

fn reset(&mut self)

Reset the bandit to its initial (no-data) state.

impl Debug for LinUcb

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.