FSRS 6 (#104)

* update scheduler to fsrs6

* slight update to optimizer code for fsrs6 compatability

* update tests

* update minimum stability value

* update tests

* remove Card.get_retrievability() method in favor of Scheduler.get_card_retrievability() method

* bump major 5.1.4 -> 6.0.0

* update README

* update short term stability update code

* fix test_memo_state unit test

* update optimizer unit tests

Author: joshdavham

README.md

@@ -97,26 +97,28 @@ from datetime import timedelta
 # note: the following arguments are also the defaults
 scheduler = Scheduler(
     parameters = (
-            0.40255,
-            1.18385,
-            3.173,
-            15.69105,
-            7.1949,
-            0.5345,
-            1.4604,
-            0.0046,
-            1.54575,
-            0.1192,
-            1.01925,
-            1.9395,
-            0.11,
-            0.29605,
-            2.2698,
-            0.2315,
-            2.9898,
-            0.51655,
-            0.6621,
-        ),
+            0.2172,
+            1.1771,
+            3.2602,
+            16.1507,
+            7.0114,
+            0.57,
+            2.0966,
+            0.0069,
+            1.5261,
+            0.112,
+            1.0178,
+            1.849,
+            0.1133,
+            0.3127,
+            2.2934,
+            0.2191,
+            3.0004,
+            0.7536,
+            0.3332,
+            0.1437,
+            0.2,
+    ),
     desired_retention = 0.9,
     learning_steps = (timedelta(minutes=1), timedelta(minutes=10)),
     relearning_steps = (timedelta(minutes=10),),
@@ -127,7 +129,7 @@ scheduler = Scheduler(
 
 #### Explanation of parameters
 
-`parameters` are a set of 19 model weights that affect how the FSRS scheduler will schedule future reviews. If you're not familiar with optimizing FSRS, it is best not to modify these default values.
+`parameters` are a set of 21 model weights that affect how the FSRS scheduler will schedule future reviews. If you're not familiar with optimizing FSRS, it is best not to modify these default values.
 
 `desired_retention` is a value between 0 and 1 that sets the desired minimum retention rate for cards when scheduled with the scheduler. For example, with the default value of `desired_retention=0.9`, a card will be scheduled at a time in the future when the predicted probability of the user correctly recalling that card falls to 90%. A higher `desired_retention` rate will lead to more reviews and a lower rate will lead to fewer reviews.
 
@@ -150,7 +152,7 @@ You can still specify custom datetimes, but they must use the UTC timezone.
 You can calculate the current probability of correctly recalling a card (its 'retrievability') with
 
 ```python
-retrievability = card.get_retrievability()
+retrievability = scheduler.get_card_retrievability(card)
 
 print(f"There is a {retrievability} probability that this card is remembered.")
 # > There is a 0.94 probability that this card is remembered.

fsrs/__init__.py

@@ -12,6 +12,7 @@
     ReviewLog,
     State,
     DEFAULT_PARAMETERS,
+    STABILITY_MIN,
 )
 
 from .optimizer import Optimizer
@@ -24,4 +25,5 @@
     "State",
     "Optimizer",
     "DEFAULT_PARAMETERS",
+    "STABILITY_MIN",
 ]

fsrs/fsrs.py

@@ -20,31 +20,32 @@
 from random import random
 import time
 
+STABILITY_MIN = 0.001
+
 DEFAULT_PARAMETERS = (
-    0.40255,
-    1.18385,
-    3.173,
-    15.69105,
-    7.1949,
-    0.5345,
-    1.4604,
-    0.0046,
-    1.54575,
-    0.1192,
-    1.01925,
-    1.9395,
-    0.11,
-    0.29605,
-    2.2698,
-    0.2315,
-    2.9898,
-    0.51655,
-    0.6621,
+    0.2172,
+    1.1771,
+    3.2602,
+    16.1507,
+    7.0114,
+    0.57,
+    2.0966,
+    0.0069,
+    1.5261,
+    0.112,
+    1.0178,
+    1.849,
+    0.1133,
+    0.3127,
+    2.2934,
+    0.2191,
+    3.0004,
+    0.7536,
+    0.3332,
+    0.1437,
+    0.2,
 )
 
-DECAY = -0.5
-FACTOR = 0.9 ** (1 / DECAY) - 1
-
 FUZZ_RANGES = [
     {
         "start": 2.5,
@@ -211,29 +212,6 @@ def from_dict(source_dict: dict[str, int | float | str | None]) -> Card:
             last_review=last_review,
         )
 
-    def get_retrievability(self, current_datetime: datetime | None = None) -> float:
-        """
-        Calculates the Card object's current retrievability for a given date and time.
-
-        The retrievability of a card is the predicted probability that the card is correctly recalled at the provided datetime.
-
-        Args:
-            current_datetime (datetime): The current date and time
-
-        Returns:
-            float: The retrievability of the Card object.
-        """
-
-        if self.last_review is None:
-            return 0
-
-        if current_datetime is None:
-            current_datetime = datetime.now(timezone.utc)
-
-        elapsed_days = max(0, (current_datetime - self.last_review).days)
-
-        return (1 + FACTOR * elapsed_days / self.stability) ** DECAY
-
 
 class ReviewLog:
     """
@@ -363,6 +341,9 @@ def __init__(
         self.maximum_interval = maximum_interval
         self.enable_fuzzing = enable_fuzzing
 
+        self._DECAY = -self.parameters[20]
+        self._FACTOR = 0.9 ** (1 / self._DECAY) - 1
+
     def __repr__(self) -> str:
         return (
             f"{self.__class__.__name__}("
@@ -374,6 +355,32 @@ def __repr__(self) -> str:
             f"enable_fuzzing={self.enable_fuzzing})"
         )
 
+    def get_card_retrievability(
+        self, card: Card, current_datetime: datetime | None = None
+    ) -> float:
+        """
+        Calculates a Card object's current retrievability for a given date and time.
+
+        The retrievability of a card is the predicted probability that the card is correctly recalled at the provided datetime.
+
+        Args:
+            card (Card): The card whose retriebility is to be calculated
+            current_datetime (datetime): The current date and time
+
+        Returns:
+            float: The retrievability of the Card object.
+        """
+
+        if card.last_review is None:
+            return 0
+
+        if current_datetime is None:
+            current_datetime = datetime.now(timezone.utc)
+
+        elapsed_days = max(0, (current_datetime - card.last_review).days)
+
+        return (1 + self._FACTOR * elapsed_days / card.stability) ** self._DECAY
+
     def review_card(
         self,
         card: Card,
@@ -436,8 +443,9 @@ def review_card(
                 card.stability = self._next_stability(
                     difficulty=card.difficulty,
                     stability=card.stability,
-                    retrievability=card.get_retrievability(
-                        current_datetime=review_datetime
+                    retrievability=self.get_card_retrievability(
+                        card,
+                        current_datetime=review_datetime,
                     ),
                     rating=rating,
                 )
@@ -510,8 +518,9 @@ def review_card(
                 card.stability = self._next_stability(
                     difficulty=card.difficulty,
                     stability=card.stability,
-                    retrievability=card.get_retrievability(
-                        current_datetime=review_datetime
+                    retrievability=self.get_card_retrievability(
+                        card,
+                        current_datetime=review_datetime,
                     ),
                     rating=rating,
                 )
@@ -551,7 +560,8 @@ def review_card(
                     difficulty=card.difficulty,
                     stability=card.stability,
                     retrievability=card.get_retrievability(
-                        current_datetime=review_datetime
+                        scheduler_parameters=self.parameters,
+                        current_datetime=review_datetime,
                     ),
                     rating=rating,
                 )
@@ -691,9 +701,9 @@ def _clamp_difficulty(self, difficulty: float) -> float:
 
     def _clamp_stability(self, stability: float) -> float:
         if isinstance(stability, (float, int)):
-            stability = max(stability, 0.01)
+            stability = max(stability, STABILITY_MIN)
         else:  # type(stability) is torch.Tensor
-            stability = stability.clamp(min=0.01)
+            stability = stability.clamp(min=STABILITY_MIN)
 
         return stability
 
@@ -714,8 +724,8 @@ def _initial_difficulty(self, rating: Rating) -> float:
         return initial_difficulty
 
     def _next_interval(self, stability: float) -> int:
-        next_interval = (stability / FACTOR) * (
-            (self.desired_retention ** (1 / DECAY)) - 1
+        next_interval = (stability / self._FACTOR) * (
+            (self.desired_retention ** (1 / self._DECAY)) - 1
         )
 
         next_interval = round(float(next_interval))  # intervals are full days
@@ -729,9 +739,19 @@ def _next_interval(self, stability: float) -> int:
         return next_interval
 
     def _short_term_stability(self, stability: float, rating: Rating) -> float:
-        short_term_stability = stability * (
+        short_term_stability_increase = (
             math.e ** (self.parameters[17] * (rating - 3 + self.parameters[18]))
-        )
+        ) * (stability ** -self.parameters[19])
+
+        if rating in (Rating.Good, Rating.Easy):
+            if isinstance(short_term_stability_increase, (float, int)):
+                short_term_stability_increase = max(short_term_stability_increase, 1.0)
+            else:  # type(short_term_stability_increase) is torch.Tensor
+                short_term_stability_increase = short_term_stability_increase.clamp(
+                    min=1.0
+                )
+
+        short_term_stability = stability * short_term_stability_increase
 
         short_term_stability = self._clamp_stability(short_term_stability)
 

fsrs/optimizer.py

@@ -5,7 +5,7 @@
 This module defines the optional Optimizer class.
 """
 
-from .fsrs import Card, ReviewLog, Scheduler, Rating, DEFAULT_PARAMETERS
+from .fsrs import Card, ReviewLog, Scheduler, Rating, DEFAULT_PARAMETERS, STABILITY_MIN
 import math
 from datetime import datetime, timezone
 from copy import deepcopy
@@ -19,14 +19,13 @@
     import pandas as pd
 
     # weight clipping
-    S_MIN = 0.01
     INIT_S_MAX = 100.0
     lower_bounds = torch.tensor(
         [
-            S_MIN,
-            S_MIN,
-            S_MIN,
-            S_MIN,
+            STABILITY_MIN,
+            STABILITY_MIN,
+            STABILITY_MIN,
+            STABILITY_MIN,
             1.0,
             0.1,
             0.1,
@@ -42,6 +41,8 @@
             1.0,
             0.0,
             0.0,
+            0.0,
+            0.1,
         ],
         dtype=torch.float64,
     )
@@ -66,6 +67,8 @@
             6.0,
             2.0,
             2.0,
+            0.8,
+            0.8,
         ],
         dtype=torch.float64,
     )
@@ -162,7 +165,9 @@ def _compute_batch_loss(self, parameters: list[float]) -> float:
                     if i == 0:
                         card = Card(card_id=card_id, due=x_date)
 
-                    y_pred_retrievability = card.get_retrievability(x_date)
+                    y_pred_retrievability = scheduler.get_card_retrievability(
+                        card=card, current_datetime=x_date
+                    )
                     y_retrievability = torch.tensor(
                         y_retrievability, dtype=torch.float64
                     )
@@ -322,7 +327,9 @@ def _update_parameters(
                             card = Card(card_id=card_id, due=x_date)
 
                         # predicted target
-                        y_pred_retrievability = card.get_retrievability(x_date)
+                        y_pred_retrievability = scheduler.get_card_retrievability(
+                            card=card, current_datetime=x_date
+                        )
                         y_retrievability = torch.tensor(
                             y_retrievability, dtype=torch.float64
                         )

pyproject.toml

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