Add splitwise module: equal/exact/percent/share split strategies with largest-remainder paise arithmetic, derived ledger, greedy and exact debt simplification, concurrency control (13 tests, 12 transcripts)
Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017ic4b4aCTv6BYCer55YdjZ
This commit is contained in:
@@ -0,0 +1,28 @@
|
||||
Four friends, five expenses, four split strategies
|
||||
==================================================
|
||||
|
||||
Expenses (shares in paise-exact rupees)
|
||||
#1 Hotel (equal) paid by asha Rs 12000.00 asha=Rs 3000.00 bala=Rs 3000.00 chitra=Rs 3000.00 dev=Rs 3000.00
|
||||
#2 Dinner (equal, 3 people) paid by bala Rs 100.00 asha=Rs 33.34 bala=Rs 33.33 chitra=Rs 33.33
|
||||
#3 Cab (exact) paid by chitra Rs 900.00 asha=Rs 300.00 bala=Rs 200.00 chitra=Rs 100.00 dev=Rs 300.00
|
||||
#4 Scuba (percent) paid by dev Rs 4000.00 asha=Rs 1600.00 bala=Rs 400.00 chitra=Rs 400.00 dev=Rs 1600.00
|
||||
#5 Groceries (shares 2:1:1) paid by asha Rs 1000.00 asha=Rs 500.00 bala=Rs 250.00 chitra=Rs 250.00
|
||||
|
||||
Net balance per person (positive = the group owes them)
|
||||
asha Rs 7566.66
|
||||
bala -Rs 3783.33
|
||||
chitra -Rs 2883.33
|
||||
dev -Rs 900.00
|
||||
|
||||
Detailed debts, netted pair by pair: 6 payments
|
||||
bala pays asha Rs 3216.66
|
||||
chitra pays asha Rs 2950.00
|
||||
dev pays asha Rs 1400.00
|
||||
bala pays chitra Rs 166.67
|
||||
bala pays dev Rs 400.00
|
||||
chitra pays dev Rs 100.00
|
||||
|
||||
Simplified debts (greedy): 3 payments
|
||||
bala pays asha Rs 3783.33
|
||||
chitra pays asha Rs 2883.33
|
||||
dev pays asha Rs 900.00
|
||||
@@ -0,0 +1,14 @@
|
||||
Why paise in a long, and why largest remainder
|
||||
==============================================
|
||||
|
||||
double: 0.1 + 0.2 = 0.30000000000000004
|
||||
double: ten times 0.10 = 0.9999999999999999
|
||||
|
||||
long, plain division: 10000 paise / 3 = 3333 each; three of them make 9999 paise
|
||||
one paisa has vanished: 1
|
||||
|
||||
largest remainder, Rs 100.00 in 3 equal parts: [3334, 3333, 3333] sum 10000
|
||||
largest remainder, 10 paise in 3 equal parts: [4, 3, 3] sum 10
|
||||
largest remainder, 33.33% / 33.33% / 33.34%: [3333, 3333, 3334] sum 10000
|
||||
largest remainder, shares 2:1:1 of Rs 1000.00: [50000, 25000, 25000] sum 100000
|
||||
largest remainder, Rs 100.00 in 7 equal parts: [1429, 1429, 1429, 1429, 1428, 1428, 1428] sum 10000
|
||||
@@ -0,0 +1,7 @@
|
||||
Seeded property check: 200000 random divisions
|
||||
==============================================
|
||||
|
||||
trials: 200000
|
||||
every trial: shares add up to the total exactly
|
||||
every share: equal to the exact amount rounded down, or one paisa more
|
||||
largest gap above the rounded-down amount: 1 paisa
|
||||
@@ -0,0 +1,16 @@
|
||||
Bad input is rejected before it touches the ledger
|
||||
==================================================
|
||||
|
||||
exact amounts too small -> InvalidSplitException: exact amounts add up to Rs 90.00 but the expense is Rs 100.00
|
||||
percentages add up to 99.99 -> InvalidSplitException: percentages add up to 99.99 but must add up to 100
|
||||
percentage with 3 decimal places -> InvalidSplitException: percent for asha has more than 2 decimal places: 33.333
|
||||
zero shares -> InvalidSplitException: shares for bala must be positive
|
||||
same person listed twice -> InvalidSplitException: duplicate participant in [asha, asha]
|
||||
nobody to split with -> InvalidSplitException: an equal split needs at least one participant
|
||||
participant outside the group -> IllegalArgumentException: esha is not a member of group Goa trip
|
||||
payer outside the group -> IllegalArgumentException: esha is not a member of group Goa trip
|
||||
zero-rupee expense -> IllegalArgumentException: an expense must be positive, got Rs 0.00
|
||||
paying yourself -> IllegalArgumentException: asha cannot pay themselves
|
||||
amount with three decimals -> IllegalArgumentException: not a whole number of paise: 10.005
|
||||
|
||||
After eleven rejected requests: 5 expenses, balances unchanged = true
|
||||
@@ -0,0 +1,16 @@
|
||||
Simplifying debts: pairwise vs greedy vs exact
|
||||
==============================================
|
||||
|
||||
Goa trip: 6 pairwise payments, 3 greedy, 3 exact
|
||||
|
||||
Balances (Rs): a +4, b +3, c +3, d -4, e -6
|
||||
greedy: 4 payments
|
||||
e pays a Rs 4.00
|
||||
d pays b Rs 3.00
|
||||
e pays c Rs 2.00
|
||||
d pays c Rs 1.00
|
||||
exact: 3 payments
|
||||
e pays b Rs 3.00
|
||||
e pays c Rs 3.00
|
||||
d pays a Rs 4.00
|
||||
why: {a, d} cancel exactly (+4 -4) and {b, c, e} cancel exactly (+3 +3 -6), so two separate groups need 1 + 2 = 3 payments
|
||||
@@ -0,0 +1,9 @@
|
||||
1500 seeded random zero-sum balance sets, up to 9 people
|
||||
========================================================
|
||||
|
||||
cases: 1500
|
||||
every case: both simplifiers leave every balance at exactly zero
|
||||
every case: greedy uses at most (people with a balance) - 1 payments
|
||||
every case: the exact simplifier's count equals an independent backtracking search
|
||||
cases where greedy used more payments than exact: 448 of 1500
|
||||
largest difference: 2 payment(s)
|
||||
@@ -0,0 +1,7 @@
|
||||
Exact search cost (timing dependent: figures differ from run to run)
|
||||
====================================================================
|
||||
|
||||
people 10: exact 9 payments in about 4 ms, greedy 9 payments in about 32 microseconds
|
||||
people 14: exact 12 payments in about 18 ms, greedy 13 payments in about 29 microseconds
|
||||
people 18: exact 15 payments in about 46 ms, greedy 17 payments in about 141 microseconds
|
||||
people 20: exact 17 payments in about 97 ms, greedy 18 payments in about 44 microseconds
|
||||
@@ -0,0 +1,45 @@
|
||||
Recording real payments against the ledger
|
||||
==========================================
|
||||
|
||||
Before settling
|
||||
asha Rs 7566.66
|
||||
bala -Rs 3783.33
|
||||
chitra -Rs 2883.33
|
||||
dev -Rs 900.00
|
||||
|
||||
After bala pays asha Rs 3783.33
|
||||
asha Rs 3783.33
|
||||
bala Rs 0.00
|
||||
chitra -Rs 2883.33
|
||||
dev -Rs 900.00
|
||||
pair view after paying the net amount (asha-bala flips direction, because bala paid more than he owed asha directly):
|
||||
asha pays bala Rs 566.67
|
||||
chitra pays asha Rs 2950.00
|
||||
dev pays asha Rs 1400.00
|
||||
bala pays chitra Rs 166.67
|
||||
bala pays dev Rs 400.00
|
||||
chitra pays dev Rs 100.00
|
||||
|
||||
After dev pays asha Rs 1000.00 (Rs 100.00 more than dev owes)
|
||||
asha Rs 2783.33
|
||||
bala Rs 0.00
|
||||
chitra -Rs 2883.33
|
||||
dev Rs 100.00
|
||||
|
||||
Now chitra and dev follow the simplified plan
|
||||
chitra pays asha Rs 2783.33
|
||||
chitra pays dev Rs 100.00
|
||||
|
||||
After the plan
|
||||
asha Rs 0.00
|
||||
bala Rs 0.00
|
||||
chitra Rs 0.00
|
||||
dev Rs 0.00
|
||||
net balances all zero: true
|
||||
pair view still lists 5 debts, because the plan paid net amounts, not the original pairs:
|
||||
asha pays bala Rs 566.67
|
||||
chitra pays asha Rs 166.67
|
||||
dev pays asha Rs 400.00
|
||||
bala pays chitra Rs 166.67
|
||||
bala pays dev Rs 400.00
|
||||
each person's pair debts add up to their net balance: true
|
||||
@@ -0,0 +1,7 @@
|
||||
The ledger is derived: replaying the log rebuilds it exactly
|
||||
============================================================
|
||||
|
||||
expenses replayed: 5
|
||||
settlements replayed: 1
|
||||
net balances equal: true
|
||||
pairwise debts equal: true
|
||||
@@ -0,0 +1,7 @@
|
||||
Eight threads adding expenses to one group
|
||||
==========================================
|
||||
|
||||
expenses added: 40000 (expected 40000)
|
||||
distinct expense ids: 40000, highest id: 40000
|
||||
net balances add up to zero: true
|
||||
replaying the log gives the same balances: true
|
||||
@@ -0,0 +1,6 @@
|
||||
Control: the same idea without a lock (timing dependent: the figure differs every run)
|
||||
======================================================================================
|
||||
|
||||
expected total: 1600000
|
||||
actual total: 740725
|
||||
updates lost: 859275 (always zero or more, and usually well above zero)
|
||||
@@ -0,0 +1,25 @@
|
||||
Pitfalls that look fine until they are not
|
||||
==========================================
|
||||
|
||||
1. new BigDecimal(33.33) = 33.3299999999999982946974341757595539093017578125
|
||||
new BigDecimal("33.33") = 33.33
|
||||
the split rejects the double-built value: percent for asha has more than 2 decimal places: 33.3299999999999982946974341757595539093017578125
|
||||
|
||||
2. 3000 dinners of Rs 100.00 between asha, bala and chitra
|
||||
always the same order: asha Rs 100020.00, bala Rs 99990.00, chitra Rs 99990.00
|
||||
rotating tie offset: asha Rs 100000.00, bala Rs 100000.00, chitra Rs 100000.00
|
||||
|
||||
3. asha pays Rs 600.00 for a gift but is not in the split
|
||||
asha Rs 600.00
|
||||
bala -Rs 300.00
|
||||
chitra -Rs 300.00
|
||||
|
||||
4. default fraction digits: INR 2, JPY 0, KWD 3
|
||||
|
||||
5. an expense of Rs 0.01 split three ways
|
||||
asha Rs 0.00
|
||||
bala Rs 0.00
|
||||
chitra Rs 0.00
|
||||
debts: []
|
||||
|
||||
6. simplifying balances that do not add up to zero: balances do not add up to zero: the sum is Rs 0.01
|
||||
Reference in New Issue
Block a user