From aef4ceb10dd62dcd0f06e611485ab32635ba7c58 Mon Sep 17 00:00:00 2001 From: Harrison Booth <73434116+Harrison-Booth@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:39:57 -0600 Subject: [PATCH] RATE follows Excel's iteration (#2502) fix(functions): RATE follows Excel's iteration RATE used Newton with fallbacks and a bracketing search, so it found roots Excel doesn't and missed the last iterate Excel returns. It now follows Excel's solver as observed with synthetic inputs: a secant iteration from the guess and the guess moved 0.001 toward a larger equation value, at most 200 steps, stopping when a step is under 1e-7 and the equation is within 1e-7 of zero (or as close as its terms allow), with the result more than 1e-7 above -100%. After 200 steps the last iterate is kept if it is within a looser 1e-4. Subnormal steps flush to zero as in Excel. RATE(5,0,-100,0) is now -0.999999409145182 like Excel (was #NUM!), and RATE(4,0,-0.0001,100) is #NUM! like Excel (was 30.62). A guess at or below -1 is #VALUE!. IRR and XIRR keep their solver. RATE test: compare with a relative tolerance, not exact equality ROADMAP: keep the progress log in descending date order RATE: pin Excel's #NUM! for a fractional nper with a guess near -1 --- ROADMAP.md | 2 + crates/functions/src/financial/tests.rs | 76 +++++++++++++++++++++++ crates/functions/src/financial/tvm.rs | 82 ++++++++++++++++++++++--- docs/function-parity.md | 6 +- 4 files changed, 156 insertions(+), 10 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index c4ac8517e..9ba40b023 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -187,6 +187,7 @@ Ranked; estimates in Opus 5.5 agent-hours. Detail and the full beta-gate list in | 2026-10-15 | Row auto-fit counts a cell's line breaks only when the cell wraps, as Excel does: a file whose unwrapped cells hold multi-line text no longer opens with tall rows (typing a break still turns wrap on and grows the row) | | 2026-10-14 | Set precision as displayed is applied: with the option on, formula results, spills and numbers typed or reformatted are stored as their number format shows them and formulas calculate from those values; `formulas.calculationOptions` gains `precisionAsDisplayed` (turning it on rounds existing constants; locked constants on a protected sheet keep their value; numbers written to a new sheet are rounded too) (#1343) | | 2026-10-14 | Lookups (MATCH, XMATCH, VLOOKUP, HLOOKUP, XLOOKUP, LOOKUP) compare numbers exactly like Excel, so a computed key such as `=0.1+0.2` no longer finds 0.3; `=` and COUNTIF/SUMIF keep their 15-digit comparison | +| 2026-10-14 | RATE matches Excel's solver: the same last iterate for slowly converging cases (about -100% when the future value is 0, instead of `#NUM!`) and `#NUM!` where Excel's iteration can't reach a very large rate | | 2026-10-14 | Functions: EOMONTH, EDATE, WORKDAY, NETWORKDAYS, YEARFRAC, WEEKNUM, the bond and coupon functions, DISC, BIN2DEC, IM* and the other Analysis ToolPak functions give `#VALUE!` for a reference to more than one cell in a value argument, as Excel 365 does, instead of spilling; array constants and computed arrays still lift | | 2026-10-14 | Protect Sheet on a protected sheet: Home › Format, its keytips (HOP, RPS) and the tab menu now read Unprotect Sheet… and unprotect (straight away without a password); a protected sheet that forbids selecting locked (or unlocked) cells is enforced for clicks, arrows and Go To, and the Protect Sheet dialog has the select options (#1346) | | 2026-10-14 | `.xls` (Excel 97-2003) files open with their formatting: fonts, solid and pattern fills, borders (with diagonals), alignment (rotation, indent, wrap, shrink), locked and hidden cells, the workbook's custom colour palette, its Normal font and its user-defined cell styles | @@ -321,6 +322,7 @@ Ranked; estimates in Opus 5.5 agent-hours. Detail and the full beta-gate list in | 2026-10-14 | minor | XLSX dynamic-array `cm` metadata kept on save; progress log row | | 2026-10-14 | minor | Progress log: spill anchor reading its old spill area | | 2026-10-14 | minor | Progress log: formulas reading an array that loses a spill conflict | +| 2026-10-14 | trivial | Progress log: RATE follows Excel's iteration | | 2026-10-13 | trivial | Progress log: More Colors… and Recent Colors in the colour menus (#928) | | 2026-10-13 | minor | Multi-level category axes (read, drawn, written); progress log row | | 2026-10-13 | trivial | Progress log: shared pictures written once on XLSX export (#985) | diff --git a/crates/functions/src/financial/tests.rs b/crates/functions/src/financial/tests.rs index a12e31022..011d8f3da 100644 --- a/crates/functions/src/financial/tests.rs +++ b/crates/functions/src/financial/tests.rs @@ -33,6 +33,82 @@ fn tvm() { is_err(ev("CUMIPMT", vec![n(0.01), n(360.0), n(125000.0), n(1.0), n(1.0), n(2.0)]), CellError::Num); } +/// RATE with the given arguments, as a number or an error. +fn rate_of(args: &[f64]) -> Value { + ev("RATE", args.iter().map(|x| n(*x)).collect()) +} + +#[track_caller] +fn rate_is(args: &[f64], expected: f64) { + close_tol(rate_of(args), expected, 1e-15); +} + +/// Expected values observed in Excel 365 with these synthetic inputs. +#[test] +fn rate_follows_excel_iteration() { + // No payments and a zero future value: the answer is -100%, which the iteration + // approaches without reaching. Excel returns the last iterate, bit for bit. + rate_is(&[5.0, 0.0, -100.0, 0.0], -0.999_999_409_145_182_5); + rate_is(&[3.0, 0.0, -50.0, 0.0], -0.999_999_744_782_979_9); + rate_is(&[10.0, 0.0, -1.0, 0.0], -0.999_998_741_101_371_3); + rate_is(&[5.0, 0.0, -100.0, 0.0, 0.0, 0.5], -0.999_999_408_783_809_4); + rate_is(&[5.0, 0.0, -100.0, 0.0, 0.0, -0.99], -0.999_999_411_730_630_3); + // Second starting point goes the other way when the equation is positive at the guess. + rate_is(&[5.0, 0.0, 100.0, 0.0], -0.999_999_409_810_240_3); + rate_is(&[5.0, 0.0, -100.0, 1e-29], -0.999_999_260_333_075_4); + rate_is(&[5.0, 0.0, -100.0, 1e4], 1.511_886_431_510_563_3); + rate_is(&[4.0, 0.0, -1.0, 100.0], 2.162_277_660_168_009); + // Within 1e-7 by step but not by value: Excel keeps going. + rate_is(&[5.0, 0.0, -1e25, 0.0], -0.999_999_628_525_605_1); + // 200 steps without converging: the last iterate when it is within 1e-4, else #NUM!. + rate_is(&[20.0, 0.0, -1.0, 0.0], -0.999_112_071_912_539_3); + rate_is(&[36.0, 0.0, -1.0, 0.0, 0.0, -0.994], -0.999_875_315_309_626_9); + is_err(rate_of(&[12.0, 0.0, -1.0, 0.0]), CellError::Num); + is_err(rate_of(&[25.0, 0.0, -1.0, 0.0]), CellError::Num); + is_err(rate_of(&[20.0, 0.0, -1e60, 0.0]), CellError::Num); + // Large rates the iteration can't reach are #NUM! in Excel. + is_err(rate_of(&[4.0, 0.0, -0.0001, 100.0]), CellError::Num); + is_err(rate_of(&[5.0, 0.0, -100.0, 1e5]), CellError::Num); + is_err(rate_of(&[10.0, -300.0, 1000.0]), CellError::Num); + // ...but are found from a closer guess. + rate_is(&[4.0, 0.0, -0.1, 100.0, 0.0, 4.0], 4.623_413_251_903_489); + close_tol(rate_of(&[10.0, -300.0, 1000.0, 0.0, 0.0, 0.3]), 0.273_198_424_105_560_4, 1e-12); + // Converging on a rate at or below -100% (or within 1e-7 of it) is #NUM!. + is_err(rate_of(&[1.0, 0.0, -1.0, 0.0]), CellError::Num); + is_err(rate_of(&[10.0, -1000.0, 1000.0]), CellError::Num); + is_err(rate_of(&[1.0, 0.0, -100.0, 1e-5]), CellError::Num); + rate_is(&[1.0, 0.0, -100.0, 2e-5], -0.999_999_8); + is_err(rate_of(&[5.0, 0.0, -1e30, 0.0]), CellError::Num); + is_err(rate_of(&[0.5, 0.0, -1.0, 0.0]), CellError::Num); + // A value that never gets near zero is #NUM!, however small the step. + is_err(rate_of(&[4.0, 0.0, 100.0, 100.0]), CellError::Num); + is_err(rate_of(&[4.0, 0.0, -1e-12, 1e-6]), CellError::Num); + rate_is(&[4.0, 0.0, -1e-14, 1e-8], 0.099_000_000_283_235_72); + // Subnormal steps are flushed to zero. + rate_is(&[3.0, 0.0, -1e-305, 0.0], 0.101); + is_err(rate_of(&[4.0, 0.0, 0.0, 100.0]), CellError::Num); + // Guess at or below -1 is #VALUE!; type is 0 or anything else (1). + is_err(rate_of(&[10.0, -100.0, 1000.0, 0.0, 0.0, -1.0]), CellError::Value); + is_err(rate_of(&[0.0, -100.0, 1000.0]), CellError::Num); + // Excel does not step the second point back to -1: a fractional nper with a guess near -1 is #NUM! + // even though a root exists at -0.99, and the same case from a guess of -0.99 finds it. + is_err(rate_of(&[0.5, 0.0, -1.0, 0.1, 0.0, -0.9995]), CellError::Num); + is_err(rate_of(&[0.5, 0.0, -1.0, 0.1, 0.0, -0.5]), CellError::Num); + close_tol(rate_of(&[0.5, 0.0, -1.0, 0.1, 0.0, -0.99]), -0.99, 1e-7); + assert_eq!(rate_of(&[10.0, -100.0, 1000.0, 0.0, 2.0]), rate_of(&[10.0, -100.0, 1000.0, 0.0, 1.0])); + // Ordinary loans, and large amounts that can't get within 1e-7 of zero. + close_tol(rate_of(&[360.0, -1000.0, 150000.0]), 0.005_850_253_376_759_637, 1e-11); + close_tol(rate_of(&[360.0, -1000.0, 150000.0, 0.0, 1.0]), 0.005_898_953_457_098_463, 1e-11); + close_tol(rate_of(&[1000.0, -1e6, 1e8]), 0.009_999_522_655_994_865, 1e-12); + close_tol(rate_of(&[360.0, -1e9, 1.5e11]), 0.005_850_253_376_759_668, 1e-12); + close_tol(rate_of(&[10.0, -50.0, 1000.0]), -0.109_560_293_684_682_5, 1e-14); + // Roots at 0% come out as rounding noise in both, so only the absolute size matters. + match rate_of(&[10.0, -100.0, 1000.0]) { + Value::Number(x) => assert!(x.abs() < 1e-8, "{x}"), + other => panic!("{other:?}"), + } +} + /// PMT within about 4 ULPs of Excel's (Value2 of synthetic probes; libm differs by an ULP across /// platforms). The old `(1 + rate)^nper` form was 25 to 91 ULPs off on these, enough to flip a loan schedule's final `IF(p - SUM(r) > 0, ...)`. #[test] diff --git a/crates/functions/src/financial/tvm.rs b/crates/functions/src/financial/tvm.rs index 872e7cbeb..d8aa2f997 100644 --- a/crates/functions/src/financial/tvm.rs +++ b/crates/functions/src/financial/tvm.rs @@ -218,21 +218,85 @@ fn solve_rate(f: impl Fn(f64) -> f64, guess: f64) -> R { Err(CellError::Num) } +/// RATE's equation at rate `r`: the loan and the payments grown to the end of the term, plus +/// `fv`. RATE returns the rate where it is zero. The second value is the size of its terms, to +/// judge how close to zero the first can get in floating point. +fn rate_equation(r: f64, np: f64, pmt: f64, pv: f64, fv: f64, typ: f64) -> (f64, f64) { + if r == 0.0 { + return (pv + pmt * np + fv, pv.abs() + (pmt * np).abs() + fv.abs()); + } + let p = (1.0 + r).powf(np); + let (a, b) = (pv * p, pmt * (1.0 / r + typ) * (p - 1.0)); + (a + b + fv, a.abs() + b.abs() + fv.abs()) +} + +/// Excel works with subnormal numbers flushed to zero: a secant step that underflows doesn't +/// move. Observed with RATE(3,0,-1E-305,0), which is 0.101 (the second starting point). +fn flush_subnormal(x: f64) -> f64 { + if x.abs() < f64::MIN_POSITIVE { 0.0 } else { x } +} + +/// Excel's RATE solver, reconstructed by observing Excel with synthetic inputs (not from its +/// code; its documentation says only "iteration", 20 steps and 0.0000001): +/// +/// - A secant iteration starting at the guess and at the guess moved 0.001 toward a larger +/// value of the equation, for at most 200 steps. +/// - It stops at the first iterate that moved less than 1e-7 and where the equation is within +/// 1e-7 of zero (or as close as its terms allow, for very large amounts). Excel returns that +/// iterate, not the exact root, so a slowly converging case such as no payments and a zero +/// future value (exact answer -100%) gives a rate just above -1. +/// - The result must be above -1 by more than the tolerance; otherwise it is #NUM!. +/// - After 200 steps without that, Excel still returns the last iterate if it is within a +/// looser 1e-4 (step, equation value and distance above -1); otherwise #NUM!. So a root the +/// iteration can't reach (a very large rate) is #NUM! even though it exists. +fn rate_solve(f: impl Fn(f64) -> (f64, f64), guess: f64) -> R { + const STEPS: usize = 200; + const TOL: f64 = 1e-7; + const LOOSE: f64 = 1e-4; + let eval = |x: f64| { + let (y, size) = f(x); + if y.is_finite() { Ok((y, size)) } else { Err(CellError::Num) } + }; + let near_zero = |y: f64, size: f64| y.abs() < TOL || y.abs() <= 1e-12 * size; + let (mut x0, (mut f0, _)) = (guess, eval(guess)?); + let mut x1 = if f0 < 0.0 { guess + 0.001 } else { guess - 0.001 }; + let (mut f1, mut size1) = eval(x1)?; + for _ in 0..STEPS { + let den = flush_subnormal(f1 - f0); + if den == 0.0 { + // The secant is flat: done if the iteration had already settled. + if (x1 - x0).abs() < TOL && near_zero(f1, size1) && x1 - TOL > -1.0 { + return Ok(x1); + } + return Err(CellError::Num); + } + let x2 = x1 - flush_subnormal(f1 * (x1 - x0)) / den; + if !x2.is_finite() { + return Err(CellError::Num); + } + let (f2, size2) = eval(x2)?; + if (x2 - x1).abs() < TOL && near_zero(f2, size2) { + return if x2 - TOL > -1.0 { Ok(x2) } else { Err(CellError::Num) }; + } + (x0, f0, x1, f1, size1) = (x1, f1, x2, f2, size2); + } + if (x1 - x0).abs() < LOOSE && f1.abs() < LOOSE && x1 - LOOSE > -1.0 { + return Ok(x1); + } + Err(CellError::Num) +} + pub(super) fn rate(a: &[Arg], _c: &mut dyn Ctx) -> R { let (np, pmt, pv) = (num(a, 0)?, num(a, 1)?, num(a, 2)?); let (fv, typ, guess) = (opt_num(a, 3, 0.0)?, type_arg(a, 4)?, opt_num(a, 5, 0.1)?); if np <= 0.0 { return Err(CellError::Num); } - let f = |r: f64| { - if r.abs() < 1e-12 { - pv + pmt * np + fv - } else { - let p = (1.0 + r).powf(np); - pv * p + pmt * (1.0 + r * typ) * (p - 1.0) / r + fv - } - }; - num_val(solve_rate(f, guess)?) + // Excel: a guess at or below -100% is #VALUE!, not #NUM!. + if guess <= -1.0 { + return Err(CellError::Value); + } + num_val(rate_solve(|r| rate_equation(r, np, pmt, pv, fv, typ), guess)?) } pub(super) fn npv(a: &[Arg], _c: &mut dyn Ctx) -> R { diff --git a/docs/function-parity.md b/docs/function-parity.md index 608e045e7..55d4ce49f 100644 --- a/docs/function-parity.md +++ b/docs/function-parity.md @@ -111,7 +111,10 @@ assertions each, but there is no conformance suite against Excel-computed result reports keep finding edge cases: MIN() with no arguments (#138), COUNTBLANK past the used range (#137, and past 16,384 cells #1010, fixed 10-14 for bounded references), ROUND at 15 digits and DATE(1900,2,29) (fixed 10-09), SUMIF sum-range sizing (fixed 10-09). Statistical distributions and financial functions with iterative solvers (RATE, IRR, -XIRR, YIELD) are the highest-risk for last-digit differences. +XIRR, YIELD) are the highest-risk for last-digit differences. RATE follows Excel's own iteration, reconstructed from observation (secant from the guess and the guess ± 0.001, at most 200 steps, +stop within 1e-7 by step and value, a looser 1e-4 check after 200 steps), so it returns the same +iterate as Excel where convergence is slow (about -100% for `RATE(n,0,-pv,0)`) and `#NUM!` where +Excel's solver gives up (very large rates); roots at 0% differ only by rounding noise (under 1e-7). TEXT() and cell display share `crates/numfmt`; checked against Excel-cached results in number- and text-format test workbooks (352 TEXT cells), all match: @@ -178,6 +181,7 @@ Positive fractional inputs still truncate, and signed zero remains valid. Covere | 2026-10-14 | minor | Set precision as displayed: results, spills and typed or reformatted numbers are stored as their format shows them when the option is on (#1343) | | 2026-10-14 | minor | Number-to-text (`&`, CONCAT, TEXTJOIN, VALUETOTEXT, the IM functions' complex text, and also formula printing, pivot and chart labels) rounds to 15 significant digits before choosing decimal or scientific, so `=(1E15-0.5)&""` is `1E+15`, not `1000000000000000`; and below 1 it switches to scientific when the decimal would be longer than 21 characters (sign not counted), as Excel caches IMCSCH/IMEXP/IMTAN results: `1.28233995888454E-06`, so `9.99999999999999E-09` (was `0.00000001`), but `0.0000692361330972509`. Only 15-digit positive mantissas are Excel-verified; the limit for shorter mantissas and for negatives is inferred | | 2026-10-14 | minor | Bounded references up to 1,048,576 cells (`D3:AZ400`) keep their full shape instead of stopping at the used range, so `SUMPRODUCT(D3:AZ400*B3:B400,(A3:A400=x)*(D1:AZ1=y))` broadcasts like Excel and `ROWS`, `COUNTBLANK` and `--(r="")` count the blanks; references that run to the edge of the sheet (`A:A`) still stop at the used range (#1010) | +| 2026-10-14 | minor | RATE follows Excel's iteration (secant, 200 steps, 1e-7 by step and value): `RATE(5,0,-100,0)` is -0.999999409145182 like Excel instead of `#NUM!`, `RATE(4,0,-0.0001,100)` is `#NUM!` like Excel instead of 30.62 | | 2026-10-13 | minor | Legacy formulas from files (no dynamic-array metadata) evaluate with implicit intersection: cells differing from Excel's cached values 68,964 → 49,866 across 4,224 test-corpus workbooks (none gets more) | | 2026-10-13 | minor | Clear reports changed stored cells sparsely, including those beyond the first million coordinates; dependent formulas and removed spills update, while clearing empty merges still unblocks spills (#1032) | | 2026-10-12 | minor | GETPIVOTDATA added: 514 / 523 by name, 505 working |