diff options
| -rw-r--r-- | gnosis-algorithm.el | 58 |
1 files changed, 43 insertions, 15 deletions
diff --git a/gnosis-algorithm.el b/gnosis-algorithm.el index 90ea7d5..cee1d13 100644 --- a/gnosis-algorithm.el +++ b/gnosis-algorithm.el @@ -1,12 +1,14 @@ ;;; gnosis-algorithm.el --- Spaced Repetition Algorithm for Gnosis -*- lexical-binding: t; -*- -;; Copyright (C) 2023 Thanos Apollo +;; Copyright (C) 2023-2024 Thanos Apollo ;; Author: Thanos Apollo <[email protected]> ;; Keywords: extensions ;; URL: https://git.thanosapollo.org/gnosis ;; Version: 0.0.1 +;; Package-Requires: ((emacs "29.1")) + ;; This program is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or @@ -24,9 +26,24 @@ ;; Handles date calculation as well as ef & interval calculations. -;; This file contains the algorithm for the spaced repetition system used in Gnosis. -;; Gnosis algorithm is inspired by the SM-2 algorithm used in Anki, but has been -;; modified to fit the needs of Gnosis. +;; Gnosis implements a highly customizable algorithm, inspired by SM-2. +;; Gnosis algorithm does not use user's subjective rating of a note to +;; determine the next review interval, but instead uses the user's +;; success or failure in recalling the answer of a note. + +;; Each gnosis note has an ef (easiness factor), which is a list of 3 +;; values. The last value is the total ef for a note, which will be +;; used to determine the next interval upon a successful answer recall, +;; the second value is the ef-decrease value, this value will be +;; subtracted from the the total ef upon failure to recall the answer of +;; a note, the first value is the ef increase, will be added to the +;; total ef upon a successful recall. + +;; Each gnosis deck has a gnosis-algorithm-ef-threshold, it's an +;; integer value that refers to the consecutive success or failures to +;; recall an answer. Upon reaching the threshold, gnosis-algorithm-ef-decrease +;; or gnosis-algorithm-ef-increase will be applied to the ef-increase or +;; ef-decrease of note. ;;; Code: @@ -34,7 +51,7 @@ (require 'calendar) (defcustom gnosis-algorithm-interval '(1 3) - "Gnosis initial interval for successful reviews. + "Gnosis initial interval for initial successful reviews. First item: First interval, Second item: Second interval." @@ -44,11 +61,9 @@ Second item: Second interval." (defcustom gnosis-algorithm-ef '(0.35 0.30 1.3) "Gnosis easiness factor. -First item : Increase factor -Second item: Decrease factor -Third item : Starting total ef - -Note: Starting total ef should not be above 3.0" +First item : Increase value +Second item: Decrease value +Third item : Total ef" :group 'gnosis :type '(list float)) @@ -57,18 +72,22 @@ Note: Starting total ef should not be above 3.0" Used to calcuate new interval for failed questions. -NOTE: Do not change this value above 1" +NOTE: This value should be less than 1.0." :group 'gnosis :type 'float) (defcustom gnosis-algorithm-ef-increase 0.1 - "Increase ef increase value by this amount for every + "Value to increase ef increase value with. + +Increase ef-increase value by this amount for every `gnosis-algorithm-ef-threshold' number of successful reviews." :group 'gnosis :type 'float) (defcustom gnosis-algorithm-ef-decrease 0.2 - "Decrease ef decrease value by this amount for every + "Value to decrease ef decrease value with. + +Decrease ef decrease value by this amount for every `gnosis-algorithm-ef-threshold' number of failed reviews." :group 'gnosis :type 'float) @@ -114,7 +133,7 @@ DATE format must be given as (year month day)." (cl-defun gnosis-algorithm-next-ef (&key ef success increase decrease threshold c-successes c-failures) - "Returns the new EF, (increase-value decrease-value total-value) + "Return the new EF, (increase-value decrease-value total-value) Calculate the new e-factor given existing EF and SUCCESS, either t or nil. @@ -146,7 +165,16 @@ by DECREASE." (cl-defun gnosis-algorithm-next-interval (&key last-interval ef success successful-reviews failure-factor initial-interval) - "Calculate next interval." + "Calculate next interval. + +LAST-INTERVAL: number of days since last review +EF: Easiness factor +SUCCESS: t if review was successful, nil otherwise +SUCCESSFUL-REVIEWS: number of successful reviews +FAILURE-FACTOR: factor to multiply last interval by if review was unsuccessful +INITIAL-INTERVAL: list of initial intervals for initial successful +reviews. Will be used to determine the next interval for the first 2 +successful reviews." (cl-assert (< gnosis-algorithm-ff 1) "Value of `gnosis-algorithm-ff' must be lower than 1") ;; This should only occur in testing env or when the user has made breaking changes. (cl-assert (> (nth 2 ef) 1) "Total ef value must be above 1") |