Merge branch 'main' into fsrs-browser

Author: L-M-Sherlock

.github/workflows/check.yml

@@ -26,7 +26,7 @@ jobs:
 
       - uses: dprint/check@v2.2
   build-macos:
-    runs-on: macos-latest
+    runs-on: macos-14
     steps:
       - uses: actions/checkout@v2
 

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "fsrs"
-version = "5.1.0"
+version = "5.2.0"
 authors = ["Open Spaced Repetition"]
 categories = ["algorithms", "science"]
 edition = "2024"
@@ -33,17 +33,17 @@ features = ["std", "train", "ndarray", "sqlite-bundled", "metrics"]
 itertools = "0.14.0"
 log = "0.4"
 ndarray = "0.16.1"
-priority-queue = "=2.5.0"
+priority-queue = "=2.7.0"
 rand = "0.9.2"
-rayon = "1.8.0"
-serde = "1.0.219"
-snafu = "0.8.6"
+rayon = "1.11.0"
+serde = "1.0.228"
+snafu = "0.8.9"
 strum = { version = "0.27.2", features = ["derive"] }
-chrono = { version = "0.4.41", default-features = false, features = ["std", "clock"] }
 chrono-tz = "0.10.4"
 wasm-bindgen = "0.2.91"
 
 [dev-dependencies]
+chrono = { version = "0.4.42", default-features = false, features = ["std", "clock"] }
 criterion = { version = "0.7.0" }
 csv = "1.3.0"
 fern = "0.7.1"

Cargo.toml

@@ -4,7 +4,7 @@
 
 This crate contains a Rust API for training FSRS parameters, and for using them to schedule cards.
 
-The Free Spaced Repetition Scheduler ([FSRS](https://github.com/open-spaced-repetition/fsrs4anki)) is a modern spaced repetition algorithm. It is based on the [DSR model](https://supermemo.guru/wiki/Three_component_model_of_memory) proposed by [Piotr Wozniak](https://supermemo.guru/wiki/Piotr_Wozniak), the creator of SuperMemo.
+The Free Spaced Repetition Scheduler ([FSRS](https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm)) is a modern spaced repetition algorithm. It springs from [MaiMemo's DHP model](https://www.maimemo.com/paper/), which is a variant of the [DSR model](https://supermemo.guru/wiki/Three_component_model_of_memory) proposed by [Piotr Wozniak](https://supermemo.guru/wiki/Piotr_Wozniak), the creator of SuperMemo.
 
 FSRS-rs is a Rust implementation of FSRS. It is designed to be used in [Anki](https://apps.ankiweb.net/), a popular spaced repetition software. [Anki 23.10](https://github.com/ankitects/anki/releases/tag/23.10) has already integrated FSRS as an alternative scheduler.
 
@@ -14,18 +14,18 @@ For more information about the algorithm, please refer to [the wiki page of FSRS
 
 ## Quickstart
 
-Read up [this](https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Optimal-Retention) to determine the optimal retention for your use case.
+Read [this](https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Optimal-Retention) for an explanation of how to determine the optimal retention for your use case.
 
 ```rust
-// Pick to your liking (see above)
+// Pick whichever percentage is to your liking (see above)
 let optimal_retention = 0.75;
-// Use default parameters/Weights for scheduler
+// Use default parameters/weights for the scheduler
 let fsrs = FSRS::new(Some(&[]))?;
 
 // Create a completely new card
 let day1_states = fsrs.next_states(None, optimal_retention, 0)?;
 
-// Rate as `hard` on first day
+// Rate as `hard` on the first day
 let day1 = day1_states.hard;
 dbg!(&day1); // scheduled as `in 4 days`
 
@@ -39,7 +39,7 @@ dbg!(day3);
 
 ## Online development
 
-go to <https://idx.google.com/import>
+You can use <https://idx.google.com/import>.
 
 ## Local development
 
@@ -64,20 +64,20 @@ to `.git/hooks/pre-commit`, then `chmod +x .git/hooks/pre-commit`
 
 ## Q&A
 
-- What is the difference with [rs-fsrs](https://github.com/open-spaced-repetition/rs-fsrs)
+- What is the difference between `fsrs-rs` and [`rs-fsrs`](https://github.com/open-spaced-repetition/rs-fsrs)
 
-  If you want to schedule the card, use \[lang\]-fsrs or the [bindings](https://github.com/open-spaced-repetition/rs-fsrs?tab=readme-ov-file#bindings),
+  If you only want to schedule cards, use \[lang\]-fsrs or the [bindings](https://github.com/open-spaced-repetition/rs-fsrs?tab=readme-ov-file#bindings).
 
-  If you do the optimization, use this crate or its bindings.
+  If you need to optimize, use this crate or its bindings.
 
-- Why not in one crate but two?
+- Why use two crates instead of one?
 
-  Calculating the weight involves tensor operations. So the initial data type is different(Tensor vs Vec/Slice). In one crate means use `cfg` to change type, which is tedious, so here we keep two versions.
+  Calculating the weights involves tensor operations so the data types are different (Tensor vs Vec/Slice). If we were to use one crate, this would mean using `cfg` to change the variable type, which would be tedious. Because of this, instead we publish two separate crates.
 
-  Another reason is, other languages will be hard to port their version when `Tensor` is used.
+  Another reason is, it would be hard to port to other languages while using `Tensor`s.
 
 - What about the name?
 
-  At first, there are `go-fsrs` and other libraries, so `rs-fsrs` is used.
+  Before this crate was made, `go-fsrs` and other libraries already existed, so the name `rs-fsrs` was chosen.
 
-  Then we want to port the torch version to rust so everyone can calculate on their own devices (tch-rs use libtorch which is too heavy), since the algorithm is called `fsrs`, add `-rs`.
+  Then we wanted to port the torch version to Rust so that everyone could optimize on their own devices (tch-rs uses libtorch which is too heavy). Since the algorithm is called `fsrs`, we add an `-rs` on the end.

README.md

@@ -4,22 +4,47 @@
 use std::hint::black_box;
 use std::iter::repeat;
 
-use criterion::Criterion;
 use criterion::criterion_group;
 use criterion::criterion_main;
+use criterion::{Criterion, Throughput};
 use fsrs::FSRS;
 use fsrs::FSRSReview;
 use fsrs::NextStates;
 use fsrs::{FSRSItem, MemoryState};
 use itertools::Itertools;
 
-pub(crate) fn calc_mem(inf: &FSRS, past_reviews: usize) -> MemoryState {
+pub(crate) fn calc_mem(inf: &FSRS, past_reviews: usize, card_cnt: usize) -> Vec<MemoryState> {
     let review = FSRSReview {
         rating: 3,
         delta_t: 21,
     };
     let reviews = repeat(review).take(past_reviews + 1).collect_vec();
-    inf.memory_state(FSRSItem { reviews }, None).unwrap()
+    (0..card_cnt)
+        .map(|_| {
+            inf.memory_state(
+                FSRSItem {
+                    reviews: reviews.clone(),
+                },
+                None,
+            )
+            .unwrap()
+        })
+        .collect_vec()
+}
+
+pub(crate) fn calc_mem_batch(inf: &FSRS, past_reviews: usize, card_cnt: usize) -> Vec<MemoryState> {
+    let reviews = repeat(FSRSReview {
+        rating: 3,
+        delta_t: 21,
+    })
+    .take(past_reviews)
+    .collect_vec();
+    let items = repeat(FSRSItem {
+        reviews: reviews.clone(),
+    })
+    .take(card_cnt)
+    .collect_vec();
+    inf.memory_state_batch(items, vec![None; card_cnt]).unwrap()
 }
 
 pub(crate) fn next_states(inf: &FSRS) -> NextStates {
@@ -55,8 +80,42 @@ pub fn criterion_benchmark(c: &mut Criterion) {
         2.6646678,
     ]))
     .unwrap();
-    c.bench_function("calc_mem", |b| b.iter(|| black_box(calc_mem(&fsrs, 100))));
+
     c.bench_function("next_states", |b| b.iter(|| black_box(next_states(&fsrs))));
+
+    {
+        let mut single_group = c.benchmark_group("calc_mem");
+        let n_cards = 1000;
+        let n_reviews = 10;
+        single_group.throughput(Throughput::Elements(n_cards));
+        single_group.bench_function(
+            format!("calc_mem n_cards={n_cards}, n_reviews={n_reviews}"),
+            |b| b.iter(|| black_box(calc_mem(&fsrs, n_reviews, n_cards.try_into().unwrap()))),
+        );
+        single_group.finish();
+    }
+
+    {
+        let mut batch_group = c.benchmark_group("calc_mem_batch");
+        for n_cards in [1000, 10_000] {
+            for n_reviews in [10, 100, 200] {
+                batch_group.throughput(Throughput::Elements(n_cards));
+                batch_group.bench_function(
+                    format!("calc_mem_batch n_cards={n_cards}, n_reviews={n_reviews}"),
+                    |b| {
+                        b.iter(|| {
+                            black_box(calc_mem_batch(
+                                &fsrs,
+                                n_reviews,
+                                n_cards.try_into().unwrap(),
+                            ))
+                        })
+                    },
+                );
+            }
+        }
+        batch_group.finish();
+    }
 }
 
 criterion_group!(benches, criterion_benchmark);