{ "category": "Financial functions", "display_name": "RATE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.RATE", "implementation_state": { "answer_bank": { "excel_builds": [ "20131", "20228", "20527", "?" ], "larger_numeric": 339, "last_bit": 20, "matched": 5, "other_mismatch": 13, "refused": 0, "rows": 377, "unread": 0, "worst_ulp": 8956533079650969310 }, "detail": "Of 470 recorded answers (377 in the answer bank and 93 workbook cells), 416 do not match: 374 differ by more than 16 ULP, 20 differ by at most 16 ULP, 22 differ in kind or value.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "differs", "state_label": "Known larger differences", "summary": "Known larger differences on 416 of 470 recorded answers", "workbook_corpus": { "cells": 93, "larger_numeric": 35, "matched": 49, "other_mismatch": 9 } }, "implementations": [ { "commit": "9e1884369a678158dd82d3d74188daf986995e87", "flavour": "excel-compatibility-candidate", "language": "Rust", "name": "CalcFunc", "own_code": [ "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/financial.rs#L180-L184" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/financial::tv_out", "catalogue/financial::timing", "ported/excel_numeric::backend::sqrt", "ported/excel_numeric::binary_with", "ported/excel_numeric::excel_pow_positive", "ported/excel_numeric::excel_pow_chain", "ported/excel_numeric::excel_x87_mul", "ported/excel_numeric::excel_x87_recip", "ported/excel_numeric/x87::mul", "ported/excel_numeric/x87::recip", "ported/excel_numeric/x87_chains::pow2_positive", "ported/excel_numeric/x87_chains::pow2", "ported/excel_numeric/x87_chains::exp_ext", "ported/excel_numeric/x87_chains::exp_with", "ported/excel_numeric/x87_chains::excel_exp", "ported/excel_numeric/x87_chains::log_with", "ported/excel_numeric/x87_chains::excel_log", "ported/financial_time_value_family::PaymentTiming::factor", "ported/financial_time_value_family::validate_finite", "ported/financial_time_value_family::growth", "ported/financial_time_value_family::annuity_term", "ported/financial_time_value_family::balance_equation", "ported/financial_time_value_family::values_bracket_root", "ported/financial_time_value_family::bisect_rate_bracket", "ported/financial_time_value_family::search_rate_bracket_from_zero", "ported/financial_time_value_family::rate", "ported/financial_time_value_family::polish_root", "ported/financial_time_value_family::rate_root", "ported/power_fn::exact_integer_magnitude", "ported/power_fn::accept_negative_base_odd_root", "ported/power_fn::binexp_positive", "ported/power_fn::power_kernel" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/financial.rs#L180-L184", "state": "differs", "suite": null, "summary": "Known larger differences on 416 of 470 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.RATE.json", "name": "RATE", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n[IRR](FUNC.IRR.md) accepts varying periodic flows; [XIRR](FUNC.XIRR.md) uses dates; [PMT](FUNC.PMT.md) computes a payment for a supplied rate.\n\n\n", "how-to-implement": "\nThe following is the current candidate’s algorithm, rather than an identified Excel iteration schedule. Its residual and stopping stages are distinct from PMT’s measured discount route.\n\n### Residual\n\nWith ordinary binary64 arithmetic, at `abs(r)<1e-12` use `F(r)=fv+pv+pmt*n`. Otherwise obtain `g=POWER(1+r,n)` through the current growth helper, set `timing=1` for end payments or `1+r` for beginning payments, form `term=timing*(g-1)/r`, and evaluate `F(r)=fv+pv*g+pmt*term` in that association. Reject invalid growth or nonfinite results. This small-rate band belongs to the RATE residual; PMT’s exact-zero branch does not replace it.\n\n### Search\n\n1. Start with the pair `(0,F(0))` and `(guess,F(guess))`, defaulting guess to 0.1. The current domain bound is `-0.999999999`; calls at or below it need the source’s explicit boundary/error handling.\n2. Accept a search residual with magnitude at most `1e-7`. If two successive residuals have opposite signs, bisect that endpoint pair for at most 64 steps, accepting the same residual threshold. After those steps the helper also accepts a bracket width at most `1e-12`.\n3. Otherwise take a secant step `next=r-F(r)*(r-prev)/(F(r)-F(prev))`. If the residual difference’s magnitude is at most `1e-12`, use a finite-difference Newton slope instead: `h=max(abs(r),1)*1e-6`, sample at `max(r-h,domain_bound)` and `r+h`, and divide the residual difference by the actual sample separation. A slope of magnitude at most `1e-12` fails.\n4. Permit twenty search iterations. A nonfinite next rate or one at/below the domain bound leaves that loop. If no acceptable root was found, the source searches from zero: positive rates start at `max(abs(guess),0.1)` and double; negative probes move halfway from the current rate toward minus one. Each side has a limit of 64 probes, and a found sign change uses the bisection helper. Evaluation errors still propagate.\n\n### Refinement and remaining limits\n\nA successful seed then gets up to sixty central-difference Newton refinements. Here the sampling width is `h=max(abs(r),1e-4)*1e-6`, distinct from the fallback width above. Stop at a stored-rate fixpoint, invalid next rate, failed residual or noncontracting step. At the latter boundary the source keeps whichever candidate has the smaller absolute residual.\n\nFor the one-period example, F(0) is minus 250 and F(0.1) minus 150. Their secant line reaches r=0.25, whose residual is zero. Longer or nearly flat problems need the remaining phases; a small currency residual alone does not guarantee a similarly small rate error.\n\nThe source retains a counterexample at `RATE(360,-1073.64,200000)`: its polished result bits `0x3f71110b20485718` remain 55 representable steps below the recorded Excel target `0x3f71110b2048574f`. Root selection, the residual’s arithmetic and Excel’s full stopping rules remain open. These candidate steps provide something concrete to implement and compare without claiming whole-function agreement.\n\n\n", "quirks": "\nThe equation may have no acceptable root or more than one root; guess and search behaviour can affect the answer. Nonconvergence gives `#NUM!` under the documented policy. A returned monthly rate times twelve is a nominal annual calculation, not a change of the function’s period units.\n\nMicrosoft describes convergence within `0.0000001` after at most twenty iterations. That is the public stopping description, not a specification of every step in the current alternative solver. Comparing the returned residual alone does not establish Excel's root-selection or stopping behavior.\n\n\n", "sources": "\n- [Microsoft: RATE function](https://support.microsoft.com/en-us/excel/functions/rate-function), opened 6 November 2026; syntax, documented argument rules and errors.\n- [DnaCalc implementation](https://github.com/DnaCalc/DnaCalc/blob/da3ecc4fb19a3a5529708c311d0e8f05688ac165/crates/calc-func/src/ported/financial_time_value_family.rs); implementation steps and the limits identified in the text.\n\n", "try-it": "\n`=RATE(1,-1250,1000)` is about `0.25`. With one end-period payment the equation is `1000*(1+r)-1250=0`, so r is one quarter. The output is per payment period, not automatically annual.\n\n\n", "version-differences": "The recorded environments below distinguish a reading from a same-input comparison. Counts describe captured inputs in each environment; overlapping captures and comparisons are not totals of unique worksheet calls.\n\n| Excel 16.0 build | Platform and CPU | Captured inputs |\n|---|---|---:|\n| 20131 | Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics | 105 |\n| 20228 | Windows, 64-bit, CPU not recorded | 256 |\n\nThe record contains no same-input comparison between these environments. Reading different inputs on different builds does not establish either a version change or cross-build agreement.\n\n[Recorded environments and comparison details](https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.RATE.json).", "what-it-does": "\n`RATE(nper,pmt,pv,[fv],[type],[guess])` solves the periodic rate of a fixed-payment annuity. Future value defaults to zero, type zero pays at period end, and the documented default guess is 0.1.\n\n\n" }, "signature": { "display": "RATE(nper, pmt, pv, [fv], [type], [guess])", "parameters": [ { "description": null, "name": "nper", "optional": false, "repeats": false }, { "description": null, "name": "pmt", "optional": false, "repeats": false }, { "description": null, "name": "pv", "optional": false, "repeats": false }, { "description": null, "name": "fv", "optional": true, "repeats": false }, { "description": null, "name": "type", "optional": true, "repeats": false }, { "description": null, "name": "guess", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 6, "min": 3 }, "category": "Financial functions", "classification": { "arg_preparation_profile": "RefsVisibleInAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "None", "host_interaction_class": "None", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Interest rate per period that makes the payments match the present and future values", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the interest rate per period of an annuity", "microsoft_url": "https://support.microsoft.com/en-us/office/rate-function-9f665657-4a7e-4bb7-a030-83fc59e748ce" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "RATE" }, { "locale": "bg-BG", "name": "RATE" }, { "locale": "cs-CZ", "name": "ÚROKOVÁ.MÍRA" }, { "locale": "da-DK", "name": "RENTE" }, { "locale": "de-DE", "name": "ZINS" }, { "locale": "el-GR", "name": "RATE" }, { "locale": "en-AU", "name": "RATE" }, { "locale": "en-GB", "name": "RATE" }, { "locale": "en-US", "name": "RATE" }, { "locale": "es-ES", "name": "TASA" }, { "locale": "et-EE", "name": "RATE" }, { "locale": "fi-FI", "name": "KORKO" }, { "locale": "fr-FR", "name": "TAUX" }, { "locale": "he-IL", "name": "RATE" }, { "locale": "hr-HR", "name": "RATE" }, { "locale": "hu-HU", "name": "RÁTA" }, { "locale": "id-ID", "name": "RATE" }, { "locale": "it-IT", "name": "TASSO" }, { "locale": "ja-JP", "name": "RATE" }, { "locale": "ko-KR", "name": "RATE" }, { "locale": "lt-LT", "name": "RATE" }, { "locale": "lv-LV", "name": "RATE" }, { "locale": "nb-NO", "name": "RENTE" }, { "locale": "nl-NL", "name": "RENTE" }, { "locale": "pl-PL", "name": "RATE" }, { "locale": "pt-BR", "name": "TAXA" }, { "locale": "pt-PT", "name": "TAXA" }, { "locale": "ro-RO", "name": "DIVERSE" }, { "locale": "ru-RU", "name": "СТАВКА" }, { "locale": "sk-SK", "name": "RATE" }, { "locale": "sl-SI", "name": "RATE" }, { "locale": "sr-Latn-RS", "name": "RATE" }, { "locale": "sv-SE", "name": "RÄNTA" }, { "locale": "th-TH", "name": "RATE" }, { "locale": "tr-TR", "name": "FAİZ_ORANI" }, { "locale": "uk-UA", "name": "RATE" }, { "locale": "vi-VN", "name": "RATE" }, { "locale": "zh-CN", "name": "RATE" }, { "locale": "zh-HK", "name": "RATE" }, { "locale": "zh-TW", "name": "RATE" } ], "signature": { "display": "RATE(nper, pmt, pv, [fv], [type], [guess])", "parameters": [ { "description": null, "name": "nper", "optional": false, "repeats": false }, { "description": null, "name": "pmt", "optional": false, "repeats": false }, { "description": null, "name": "pv", "optional": false, "repeats": false }, { "description": null, "name": "fv", "optional": true, "repeats": false }, { "description": null, "name": "type", "optional": true, "repeats": false }, { "description": null, "name": "guess", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "RATE", "version_marker": null, "xlcall": { "code": "60", "symbol": "xlfRate" } }, "microsoft": "https://support.microsoft.com/en-us/office/rate-function-9f665657-4a7e-4bb7-a030-83fc59e748ce" }, "try_it": { "formula": "=RATE(1,-1250,1000)" }, "url": "https://handbook.dnacalc.com/functions/RATE.html", "variants": [], "versions": [ { "behaviour": "105 captured inputs are indexed for this environment. Capture dates: 2026-07-11 to 2026-07-11. This is a reading count, not a comparison with another build.", "excel_build": "16.0 build 20131", "platform": "Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.RATE.json" ] }, { "behaviour": "256 captured inputs are indexed for this environment. Capture dates: 2026-08-09 to 2026-08-09. This is a reading count, not a comparison with another build.", "excel_build": "16.0 build 20228", "platform": "Windows, 64-bit, CPU not recorded", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.RATE.json" ] } ] }