use unit period map for window

Author: simontreanor

CHANGELOG.md

@@ -8,6 +8,17 @@
 
 ---
 
+## [2.5.4] - 2025-06-04
+
+### Fixed
+
+- The Window field of the amortisation schedule was generated by incrementing the window value each time a scheduled payment was due. This has now been
+modified to use a map of unit periods instead. This is more useful when projecting schedules beyond their original settlement date, and will be useful
+in future updates to support payment mapping. The original purpose of the window was to help analyse payment status (e.g. early/late) but is rather
+crude and will be replaced with more accurate mapping.
+
+---
+
 ## [2.5.3] - 2025-06-04
 
 ### Fixed

src/Amortisation.fs

@@ -748,14 +748,52 @@ module Amortisation =
         let maxAppliedPaymentDay = appliedPayments |> Map.keys |> Seq.max
         let appliedPaymentCount = appliedPayments |> Map.count |> uint
 
+        // get the unit period and project it over the schedule to determine the amortisation windows
+        let unitPeriodMap =
+            match p.Basic.ScheduleConfig with
+            | AutoGenerateSchedule ags ->
+                let paymentSchedule =
+                    UnitPeriod.generatePaymentSchedule
+                        (UnitPeriod.ScheduleLength.MaxDuration(
+                            p.Basic.StartDate,
+                            int maxAppliedPaymentDay * 1<DurationDay>
+                        ))
+                        UnitPeriod.Direction.Forward
+                        ags.UnitPeriodConfig
+                    |> Array.insertAt 0 p.Basic.StartDate
+                    |> Array.indexed
+
+                let dayToUnitPeriodMap =
+                    [| 0 .. int maxAppliedPaymentDay |]
+                    |> Array.map (fun day ->
+                        let day = day * 1<OffsetDay>
+                        let date = OffsetDay.toDate p.Basic.StartDate day
+
+                        let unitPeriodIndex =
+                            paymentSchedule
+                            |> Array.filter (fun (_, paymentDate) -> paymentDate <= date)
+                            |> Array.tryLast
+                            |> Option.map fst
+                            |> Option.defaultValue 0
+
+                        day, unitPeriodIndex
+                    )
+                    |> Map.ofArray
+
+                Some dayToUnitPeriodMap
+            | _ -> None
+
         // generate the amortisation schedule
         let generator ((previousDay, previous), totals) (currentDay, current: AppliedPayment) =
             // determine the window and increment every time a new scheduled payment is due
             let window =
-                if ScheduledPayment.isSome current.ScheduledPayment then
-                    previous.Window + 1
-                else
-                    previous.Window
+                match unitPeriodMap with
+                | Some upm -> upm |> Map.find currentDay
+                | None ->
+                    if ScheduledPayment.isSome current.ScheduledPayment then
+                        previous.Window + 1
+                    else
+                        previous.Window
 
             // get an array of advances
             // note: assumes single advance on day 0 (multiple advances are not currently supported), so this is based purely on the principal

tests/ActualPaymentTests.fs

@@ -775,7 +775,7 @@ module ActualPaymentTests =
                 OffsetDate = Date(2034, 1, 31)
                 Advances = [||]
                 ScheduledPayment = ScheduledPayment.zero
-                Window = 5
+                Window = 135
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
                 GeneratedPayment = NoGeneratedPayment

tests/ActualPaymentTestsExtra.fs

@@ -435,7 +435,7 @@ module ActualPaymentTestsExtra =
                 OffsetDate = Date(2023, 12, 11)
                 Advances = [||]
                 ScheduledPayment = ScheduledPayment.zero
-                Window = 7
+                Window = 15
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
                 GeneratedPayment = NoGeneratedPayment
@@ -772,7 +772,7 @@ module ActualPaymentTestsExtra =
                 OffsetDate = Date(2025, 6, 2)
                 Advances = [||]
                 ScheduledPayment = ScheduledPayment.zero
-                Window = 4
+                Window = 19
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
                 GeneratedPayment = GeneratedValue 0L<Cent>
@@ -796,3 +796,104 @@ module ActualPaymentTestsExtra =
             }
 
         actual |> should equal expected
+
+    [<Fact>]
+    let ActualPaymentTestExtra009 () =
+        let title = "ActualPaymentTestExtra009"
+
+        let description =
+            "Over-refund should not lead to large final interest adjustment; 00224840cd8a"
+
+        let parameters: Parameters = {
+            Basic = {
+                EvaluationDate = Date(2025, 6, 2)
+                StartDate = Date(2023, 8, 29)
+                Principal = 250_00L<Cent>
+                ScheduleConfig =
+                    AutoGenerateSchedule {
+                        UnitPeriodConfig = Monthly(1, 2023, 9, 23)
+                        ScheduleLength = PaymentCount 4
+                    }
+                PaymentConfig = {
+                    LevelPaymentOption = LowerFinalPayment
+                    Rounding = RoundUp
+                }
+                FeeConfig = ValueNone
+                InterestConfig = {
+                    Method = Interest.Method.AddOn
+                    StandardRate = Interest.Rate.Daily <| Percent 0.8m
+                    Cap = {
+                        TotalAmount = Amount.Percentage(Percent 100m, Restriction.NoLimit)
+                        DailyAmount = Amount.Percentage(Percent 0.8m, Restriction.NoLimit)
+                    }
+                    Rounding = RoundDown
+                    AprMethod = Apr.CalculationMethod.UnitedKingdom 3
+                }
+            }
+            Advanced = {
+                PaymentConfig = {
+                    ScheduledPaymentOption = AsScheduled
+                    Minimum = NoMinimumPayment
+                    Timeout = 0<DurationDay>
+                }
+                FeeConfig = ValueNone
+                ChargeConfig = None
+                InterestConfig = {
+                    InitialGracePeriod = 0<DurationDay>
+                    PromotionalRates = [||]
+                    RateOnNegativeBalance = Interest.Rate.Annual <| Percent 8m
+                }
+                SettlementDay = SettlementDay.SettlementOnEvaluationDay
+                TrimEnd = false
+            }
+        }
+
+        let actual =
+            let actualPayments =
+                Map [
+                    25<OffsetDay>, [| ActualPayment.quickConfirmed 120_50L<Cent> |]
+                    55<OffsetDay>, [| ActualPayment.quickConfirmed 120_50L<Cent> |]
+                    86<OffsetDay>, [| ActualPayment.quickConfirmed 120_50L<Cent> |]
+                    116<OffsetDay>, [| ActualPayment.quickConfirmed 120_50L<Cent> |]
+                    388<OffsetDay>,
+                    [|
+                        ActualPayment.quickConfirmed -0_63L<Cent>
+                        ActualPayment.quickConfirmed -56_42L<Cent>
+                    |]
+                ]
+
+            let schedules = amortise parameters actualPayments
+            schedules |> Schedule.outputHtmlToFile folder title description parameters ""
+            schedules.AmortisationSchedule.ScheduleItems |> Map.maxKeyValue
+
+        let expected =
+            573<OffsetDay>,
+            {
+                OffsetDayType = OffsetDayType.SettlementDay
+                OffsetDate = Date(2025, 6, 2)
+                Advances = [||]
+                ScheduledPayment = ScheduledPayment.zero
+                Window = 21
+                PaymentDue = 0L<Cent>
+                ActualPayments = [||]
+                GeneratedPayment = GeneratedValue 1_91L<Cent>
+                NetEffect = 1_91L<Cent>
+                PaymentStatus = Generated
+                BalanceStatus = ClosedBalance
+                ActuarialInterest = 1_28.52m<Cent>
+                NewInterest = 1_28m<Cent>
+                NewCharges = [||]
+                PrincipalPortion = 63L<Cent>
+                FeePortion = 0L<Cent>
+                InterestPortion = 1_28L<Cent>
+                ChargesPortion = 0L<Cent>
+                FeeRebate = 0L<Cent>
+                PrincipalBalance = 0L<Cent>
+                FeeBalance = 0L<Cent>
+                InterestBalance = 0m<Cent>
+                ChargesBalance = 0L<Cent>
+                SettlementFigure = 0L<Cent>
+                FeeRebateIfSettled = 0L<Cent>
+            }
+
+        actual |> should equal expected

tests/EdgeCaseTests.fs

@@ -845,7 +845,7 @@ module EdgeCaseTests =
                 OffsetDate = Date(2024, 4, 5)
                 Advances = [||]
                 ScheduledPayment = ScheduledPayment.zero
-                Window = 4
+                Window = 11
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
                 GeneratedPayment = NoGeneratedPayment

tests/QuoteTests.fs

@@ -741,7 +741,7 @@ module QuoteTests =
                 OffsetDate = startDate.AddDays 181
                 Advances = [||]
                 ScheduledPayment = ScheduledPayment.zero
-                Window = 10
+                Window = 13
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
                 GeneratedPayment = GeneratedValue 1311_67L<Cent>
@@ -834,7 +834,7 @@ module QuoteTests =
                 OffsetDate = startDate.AddDays 388
                 Advances = [||]
                 ScheduledPayment = ScheduledPayment.zero
-                Window = 11
+                Window = 27
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
                 GeneratedPayment = GeneratedValue 1261_73L<Cent>
@@ -1664,7 +1664,7 @@ module QuoteTests =
                 OffsetDate = Date(2024, 2, 5)
                 Advances = [||]
                 ScheduledPayment = ScheduledPayment.zero
-                Window = 5
+                Window = 15
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
                 GeneratedPayment = GeneratedValue -72_80L<Cent>