Add method for rescheduling cards (#138)

* add reschedule_card method

* add tests for new reschedule_card method

* update README

* bump minor 6.1.1 -> 6.2.0

* fix typo

* small fix to README

Author: joshdavham

README.md

@@ -217,10 +217,20 @@ scheduler = Scheduler(optimal_parameters)
 optimal_retention = optimizer.compute_optimal_retention(optimal_parameters)
 
 # initialize a new scheduler with both optimized parameters and retention
-scheduler = Scheduler(optimal_parameters, optimal_retention)
+optimal_scheduler = Scheduler(optimal_parameters, optimal_retention)
 ```
 
-Note: The computed optimal parameters and retention may be slightly different than the numbers computed by Anki for the same set of review logs. This is because the two implementations are slightly different and updated at different times. If you're interested in the official Rust-based Anki implementation, please see [here](https://github.com/open-spaced-repetition/fsrs-rs).
+> [!NOTE]
+> The computed optimal parameters and retention may be slightly different than the numbers computed by Anki for the same set of review logs. This is because the two implementations are slightly different and updated at different times. If you're interested in the official Rust-based Anki implementation, please see [here](https://github.com/open-spaced-repetition/fsrs-rs).
+
+### Reschedule cards after optimization
+
+After creating a new scheduler with optimized parameters, you may want to reschedule/update each of your previous cards with this new scheduler.
+
+```python
+# repeat the following for each of your cards
+rescheduled_card = optimal_scheduler.reschedule_card(card, review_logs_for_that_card)
+```
 
 ## Reference
 

fsrs/scheduler.py

@@ -498,6 +498,45 @@ def review_card(
 
         return card, review_log
 
+    def reschedule_card(self, card: Card, review_logs: list[ReviewLog]) -> Card:
+        """
+        Reschedules/updates the given card with the current scheduler provided that card's review logs.
+
+        If the current card was previously scheduled with a different scheduler, you may want to reschedule/update
+        it as if it had always been scheduled with this current scheduler. For example, you may want to reschedule
+        each of your cards with a new scheduler after computing the optimal parameters with the Optimizer.
+
+        Args:
+            card: The card to be rescheduled/updated.
+            review_logs: A list of that card's review logs (order doesn't matter).
+
+        Returns:
+            A new card that has been rescheduled/updated with this current scheduler.
+
+        Raises:
+            ValueError: If any of the review logs are for a card other than the one specified, this will raise an error.
+
+        """
+
+        for review_log in review_logs:
+            if review_log.card_id != card.card_id:
+                raise ValueError(
+                    f"ReviewLog card_id {review_log.card_id} does not match Card card_id {card.card_id}"
+                )
+
+        review_logs = sorted(review_logs, key=lambda log: log.review_datetime)
+
+        rescheduled_card = Card(card_id=card.card_id, due=card.due)
+
+        for review_log in review_logs:
+            rescheduled_card, _ = self.review_card(
+                card=rescheduled_card,
+                rating=review_log.rating,
+                review_datetime=review_log.review_datetime,
+            )
+
+        return rescheduled_card
+
     def to_dict(
         self,
     ) -> SchedulerDict:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fsrs"
-version = "6.1.1"
+version = "6.2.0"
 description = "Free Spaced Repetition Scheduler"
 readme = "README.md"
 authors = [

tests/test_basic.py

@@ -8,33 +8,34 @@
 import random
 from copy import deepcopy
 import sys
+import re
+
+TEST_RATINGS_1 = (
+    Rating.Good,
+    Rating.Good,
+    Rating.Good,
+    Rating.Good,
+    Rating.Good,
+    Rating.Good,
+    Rating.Again,
+    Rating.Again,
+    Rating.Good,
+    Rating.Good,
+    Rating.Good,
+    Rating.Good,
+    Rating.Good,
+)
 
 
 class TestPyFSRS:
     def test_review_card(self):
         scheduler = Scheduler(enable_fuzzing=False)
 
-        ratings = (
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Again,
-            Rating.Again,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-        )
-
         card = Card()
         review_datetime = datetime(2022, 11, 29, 12, 30, 0, 0, timezone.utc)
 
         ivl_history = []
-        for rating in ratings:
+        for rating in TEST_RATINGS_1:
             card, _ = scheduler.review_card(
                 card=card, rating=rating, review_datetime=review_datetime
             )
@@ -222,24 +223,9 @@ def test_custom_scheduler_args(self):
         card = Card()
         now = datetime(2022, 11, 29, 12, 30, 0, 0, timezone.utc)
 
-        ratings = (
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Again,
-            Rating.Again,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-            Rating.Good,
-        )
         ivl_history = []
 
-        for rating in ratings:
+        for rating in TEST_RATINGS_1:
             card, _ = scheduler.review_card(card, rating, now)
             ivl = (card.due - card.last_review).days
             ivl_history.append(ivl)
@@ -1011,6 +997,150 @@ def test_relearning_card_rate_hard_two_relearning_steps(self):
         assert card.state == State.Review
         assert card.step is None
 
+    def test_reschedule_card_same_scheduler(self):
+        scheduler = Scheduler(enable_fuzzing=False)
+
+        card = Card()
+
+        review_logs = []
+        for rating in TEST_RATINGS_1:
+            card, review_log = scheduler.review_card(
+                card=card, rating=rating, review_datetime=card.due
+            )
+            review_logs.append(review_log)
+
+        rescheduled_card = scheduler.reschedule_card(card=card, review_logs=review_logs)
+
+        assert card is not rescheduled_card
+        assert card == rescheduled_card
+
+    def test_reschedule_card_different_parameters(self):
+        scheduler = Scheduler(enable_fuzzing=False)
+
+        card = Card()
+
+        review_logs = []
+        for rating in TEST_RATINGS_1:
+            card, review_log = scheduler.review_card(
+                card=card, rating=rating, review_datetime=card.due
+            )
+            review_logs.append(review_log)
+
+        DIFFERENT_PARAMETERS = [
+            0.12340357383516173,
+            1.2931,
+            2.397673571899466,
+            8.2956,
+            6.686820427099132,
+            0.45021679958387956,
+            3.077875127553957,
+            0.053520395733247045,
+            1.6539992229052127,
+            0.1466206769107436,
+            0.6300772488850335,
+            1.611965002575047,
+            0.012840136810798864,
+            0.34853762746216305,
+            1.8878958285806287,
+            0.8546376191171063,
+            1.8729,
+            0.6748536823468675,
+            0.20451266082721842,
+            0.22622814695113844,
+            0.46030603398979064,
+        ]
+        assert scheduler.parameters != DIFFERENT_PARAMETERS
+        scheduler_with_different_parameters = Scheduler(parameters=DIFFERENT_PARAMETERS)
+        rescheduled_card = scheduler_with_different_parameters.reschedule_card(
+            card=card, review_logs=review_logs
+        )
+
+        assert card.card_id == rescheduled_card.card_id
+        assert card.state == rescheduled_card.state
+        assert card.step == rescheduled_card.step
+        assert card.stability != rescheduled_card.stability
+        assert card.difficulty != rescheduled_card.difficulty
+        assert card.last_review == rescheduled_card.last_review
+        assert card.due != rescheduled_card.due
+
+    def test_reschedule_card_different_desired_retention(self):
+        scheduler = Scheduler(enable_fuzzing=False)
+
+        card = Card()
+
+        review_logs = []
+        for rating in TEST_RATINGS_1:
+            card, review_log = scheduler.review_card(
+                card=card, rating=rating, review_datetime=card.due
+            )
+            review_logs.append(review_log)
+
+        DIFFERENT_DESIRED_RETENTION = 0.8
+        assert scheduler.desired_retention != DIFFERENT_DESIRED_RETENTION
+        scheduler_with_different_retention = Scheduler(
+            desired_retention=DIFFERENT_DESIRED_RETENTION
+        )
+        rescheduled_card = scheduler_with_different_retention.reschedule_card(
+            card=card, review_logs=review_logs
+        )
+
+        assert card.card_id == rescheduled_card.card_id
+        assert card.state == rescheduled_card.state
+        assert card.step == rescheduled_card.step
+        assert card.stability == rescheduled_card.stability
+        assert card.difficulty == rescheduled_card.difficulty
+        assert card.last_review == rescheduled_card.last_review
+        assert card.due < rescheduled_card.due
+
+    def test_reschedule_card_different_learning_steps(self):
+        scheduler = Scheduler(enable_fuzzing=False)
+
+        card = Card()
+
+        review_logs = []
+        for rating in TEST_RATINGS_1:
+            card, review_log = scheduler.review_card(
+                card=card, rating=rating, review_datetime=card.due
+            )
+            review_logs.append(review_log)
+
+        DIFFERENT_LEARNING_STEPS = [timedelta(minutes=1)] * len(review_logs)
+        assert scheduler.learning_steps != DIFFERENT_LEARNING_STEPS
+        scheduler_with_different_retention = Scheduler(
+            learning_steps=DIFFERENT_LEARNING_STEPS
+        )
+        rescheduled_card = scheduler_with_different_retention.reschedule_card(
+            card=card, review_logs=review_logs
+        )
+
+        assert card.card_id == rescheduled_card.card_id
+        assert card.state != rescheduled_card.state
+        assert card.step != rescheduled_card.step
+        assert card.stability == rescheduled_card.stability
+        assert card.difficulty == rescheduled_card.difficulty
+        assert card.last_review == rescheduled_card.last_review
+        assert card.due > rescheduled_card.due
+
+    def test_reschedule_card_wrong_review_logs(self):
+        scheduler = Scheduler(enable_fuzzing=False)
+
+        card = Card()
+
+        review_logs = []
+        for rating in TEST_RATINGS_1:
+            card, review_log = scheduler.review_card(
+                card=card, rating=rating, review_datetime=card.due
+            )
+            review_logs.append(review_log)
+
+        DIFFERENT_CARD_ID = 123
+        assert card.card_id != DIFFERENT_CARD_ID
+        review_logs[0].card_id = DIFFERENT_CARD_ID
+
+        EXPECTED_ERROR_MESSAGE = f"ReviewLog card_id {DIFFERENT_CARD_ID} does not match Card card_id {card.card_id}"
+        with pytest.raises(ValueError, match=re.escape(EXPECTED_ERROR_MESSAGE)):
+            _ = scheduler.reschedule_card(card=card, review_logs=review_logs)
+
     def test_Optimizer_lazy_loading(self):
         assert "fsrs.scheduler" in sys.modules
         assert "fsrs.card" in sys.modules