fsrs-rs Documentation

To add FSRS to your Rust project, use cargo add fsrs. If you are following the scheduling examples, you will also need the chrono crate to manage review timestamps.

cargo add fsrs

# Required for tracking review times in examples
chrono = { version = "0.4", default-features = false, features = ["std", "clock"] }

If you are migrating from an SM-2 based system, you can initialize a MemoryState using the last known SM-2 ease_factor and interval via memory_state_from_sm2.

To reconstruct the full FSRS state, you can then replay the partial review history using the memory_state method, passing the SM-2 derived state as the Some(initial_state) argument.

use fsrs::{FSRS, FSRSItem, FSRSReview};

let fsrs = FSRS::default();
let sm2_retention = 0.9;
let ease_factor = 2.5;
let interval = 10.0;

let initial_state = fsrs.memory_state_from_sm2(ease_factor, interval, sm2_retention)?;

let reviews = vec![
    FSRSReview { rating: 3, delta_t: 5 },
    FSRSReview { rating: 4, delta_t: 10 },
];

let memory_state = fsrs.memory_state(
    FSRSItem { reviews },
    Some(initial_state),
)?;

The crate includes an experimental optimizer for the FSRS6 Cost ADR policy. This searches for a 15-parameter cost-conditioned desired-retention policy.

To run the training example, you must enable the experimental_cost_adr feature:

cargo run --release --features experimental_cost_adr --example cost_adr

You can pass command-line arguments to the example to override simulation defaults:

• --days: Simulation duration.
• --deck: Number of cards in the deck.
• --pop: Population size.
• --gen: Number of generations.

Example command:

cargo run --release --features experimental_cost_adr --example cost_adr -- --days 90 --deck 2000 --pop 8 --gen 5

The fsrs-rs crate provides several key modules for spaced repetition scheduling, training, and simulation:

• model: Contains the FSRS struct (the main model) and check_and_fill_parameters.
• inference: Provides types for understanding card progress and state, including ItemState, MemoryState, ItemProgress, and NextStates. It also includes functions like current_retrievability.
• training: Used to optimize model parameters based on review history via compute_parameters and TrainingConfig.
• dataset: Defines the data structures for reviews and items, specifically FSRSItem and FSRSReview.
• simulation: Allows for simulating long-term scheduling outcomes using simulate and various configuration types like SimulatorConfig and Card.

When the simulation hits a review_limit, you can use a review_priority_fn to decide which cards to prioritize. This is useful for simulating different study strategies (e.g., prioritizing high-difficulty cards vs. low-stability cards).

The function receives a &Card and returns an i32 score. Higher scores indicate higher priority.

Common Strategies:

• High Difficulty First: |card| -(card.difficulty * 100.0) as i32 (Note: negative because higher score = higher priority).
• High Retrievability First: |card| (card.retrievability() * 1000.0) as i32.
• Low Stability First: |card| (card.stability * 100.0) as i32.
• Early Due First: |card| card.scheduled_due() as i32.

// Example: Prioritizing cards with low stability
config.review_priority_fn = Some(ReviewPriorityFn::new(|card: &Card| {
    (card.stability * 100.0) as i32
}));

If you need to monitor the training process (e.g., for a UI), you can pass a shared CombinedProgressState into ComputeParametersInput.

CombinedProgressState manages multiple ProgressState objects (one for each training split) and provides methods to check if training is finished or if an abort has been requested via want_abort.

use std::sync::{Arc, Mutex};
// ...
let progress = Arc::new(Mutex::new(CombinedProgressState::default()));

// Pass this 'progress' into your ComputeParametersInput

You can create an FSRS instance using default parameters (optimized for average learning habits) or by providing a custom set of parameters.

To use default parameters:

use fsrs::FSRS;

let fsrs = FSRS::default();

To use custom parameters, pass a slice of f32 to FSRS::new(). The length of the slice determines how the parameters are interpreted (e.g., 0, 17, 19, or 21 elements). If the slice is empty, it defaults to the standard 21 parameters.

use fsrs::FSRS;

let custom_params = [
    0.212, 1.2931, 2.3065, 8.2956, 6.4133, 0.8334, 3.0194,
    0.001, 1.8722, 0.1666, 0.796, 1.4835, 0.0614, 0.2629,
    1.6483, 0.6014, 1.8729, 0.5425, 0.0912, 0.0658, 0.1542
];

let fsrs = FSRS::new(&custom_params).expect("Custom parameters should be valid");

The CostAdrEvaluationConfig struct defines how a policy is evaluated against a baseline.

Key fields:

• cost_weights: A vector of cost weights to test the policy against.
• baseline_desired_retentions: A vector of target retentions used to establish the baseline performance.
• seed: Optional seed for reproducible evaluations.

let evaluation_config = CostAdrEvaluationConfig {
    cost_weights: vec![0.0, 1.0, 2.0, 4.0],
    baseline_desired_retentions: vec![0.5, 0.6, 0.7, 0.8, 0.9],
    seed: Some(42),
};

The TrainingConfig struct allows you to fine-tune the optimization process. The default values are:

• num_epochs: 5
• batch_size: 512
• seed: 2023
• learning_rate: 0.04
• max_seq_len: 256
• gamma: 1.0 (L2 regularization strength)

Note: batch_size must be greater than 0, and learning_rate and gamma must be finite values.

let config = TrainingConfig {
    num_epochs: 10,
    batch_size: 128,
    seed: 42,
    learning_rate: 0.01,
    max_seq_len: 128,
    gamma: 0.5,
};