Disperse Siblings

The dispersal of siblings requires several steps:

1. Obtaining the range of due dates available for dispersal (get_due_range):

   • First, it calculates a new interval (new_ivl) for the card based on its stability and desired retention. The new interval is capped at maximum_interval.
   • If the new interval is less than or equal to 2.5, it returns the currently scheduled due date as the minimum and maximum range of the available due dates. This implies that the disperse_siblings function doesn't affect the due date of the cards with new_ivl ≤ 2.5d.
   • Then, for the remaining cards, it calculates the fuzz range (min_ivl, max_ivl) for the new interval using the get_fuzz_range function defined in utils.py.
   • If the card is not overdue, the range of due dates (due_range) is calculated by adding the min_ivl and max_ivl (from get_fuzz_range) to the last review date. The due_range is not allowed to take dates in the past, which can happen if the weights/ desired retention / maximum interval were changed. This condition is important because cards can't be reviewed by going the past and dispersal should ensure that cards are maximally spaced taking this fact into consideration.
   • If the card is currently overdue but the maximum due date that can be assigned to it (based on fuzz) is in the future, the function returns the remaining range of due dates (from today to maximum possible due date) as the due_range.
   • For the remaining cards, it returns the currently scheduled due date as the due_range. This implies that the disperse_siblings function doesn't affect the due date of the cards that are currently overdue and have no part of their due range in the future.

2. Obtaining the latest review date of the siblings: This is obtained through the get_due_range and disperse(siblings) functions.

   • Firstly, the last review dates of all the cards are calculated.
   • Then, among siblings, the maximum of these dates is calculated to obtain the latest review date (latest_review). The importance of this is to ensure that the due dates of the cards are not only maximally separated from them but also from the most recent review date. To achieve this, we consider a pseudo-sibling with due date equal to the latest review date of a sibling and no fuzzing allowed.

3. Maximizing the gap between the siblings:

   • Firstly, allocate_ranges function assigns a random due date to each card within its due range.
   • Then it enters a loop where it repeatedly tries to increase the minimum gap between due times. It does this by calling attempt_to_achieve_min_gap with an increasing target minimum gap until no improvement can be found.
   • If an improvement is found, it updates the best allocation found so far and resets the number of attempts. If no improvement is found, it randomly adjusts some of the due times and tries again.

4. maximize_siblings_due_gap: This is the main function that takes a dictionary mapping card IDs to their due ranges. It calls the allocate_ranges function to get the optimal allocation of due times for each card.

5. get_dues_bordering_min_gap: This function identifies the due times that are bordering the minimum gap. If the minimum gap is zero, it returns all due times with more than one range. Otherwise, it returns all due times where the gap to the next due time is equal to the minimum gap.

6. get_min_gap: This function calculates the minimum gap between any two due times. It sorts the due times and then iterates through them, updating the minimum gap whenever a smaller one is found.

7. attempt_to_achieve_min_gap: This function tries to adjust the due times to achieve a target minimum gap. It creates a new dictionary of due times and ranges, and then iterates through the current due times, adjusting them as necessary to meet the target minimum gap.

In simple terms, this algorithm works by repeatedly trying to increase the minimum gap between any two card reviews. It does this by adjusting the review times within their allowed ranges until no further improvement can be found.