{ "category": "Financial functions", "display_name": "IRR", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.IRR", "implementation_state": { "answer_bank": { "excel_builds": [ "20131", "20228", "?" ], "larger_numeric": 299, "last_bit": 95, "matched": 323, "other_mismatch": 17, "refused": 0, "rows": 734, "unread": 0, "worst_ulp": 9195100997775460447 }, "detail": "Of 765 recorded answers (734 in the answer bank and 31 workbook cells), 424 do not match: 308 differ by more than 16 ULP, 96 differ by at most 16 ULP, 20 differ in kind or value.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "differs", "state_label": "Known larger differences", "summary": "Known larger differences on 424 of 765 recorded answers", "workbook_corpus": { "cells": 31, "larger_numeric": 9, "last_bit": 1, "matched": 18, "other_mismatch": 3, "worst_ulp": 16 } }, "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#L228-L251", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L81-L120", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L198-L213", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L215-L231", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L274-L277", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L279-L281", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L283-L333", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L335-L376", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L483-L512", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cashflow_rate_family.rs#L514-L525" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/financial::resolved", "catalogue/financial::cash_err", "catalogue/financial::guess", "ported/cashflow_rate_family::numeric_from_cell", "ported/cashflow_rate_family::scalar_number_from_eval", "ported/cashflow_rate_family::validate_cashflows", "ported/cashflow_rate_family::bounded_rate_solve", "ported/cashflow_rate_family::polish_rate", "ported/cashflow_rate_family::map_cashflow_rate_error_to_ws" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/financial.rs#L228-L251", "state": "differs", "suite": null, "summary": "Known larger differences on 424 of 765 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.IRR.json", "name": "IRR", "notes": [ { "basis": "40 recorded readings: seven direct non-numbers and NA() as values, each with five guesses (none, 0.1, \"x\", NA(), empty).", "documentation": null, "evidence": [ { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheets ql001 to ql040", "note": "40 recorded readings", "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-list-controls.capture.json", "repository": "DnaCalc" } ], "functions": [ "FUNC.IRR" ], "inferred": null, "kind": "quirk", "note_id": "FN-IRR-001", "open": [ "A reference to one cell holding the same values answers differently. Those readings are not in a published capture, so this note covers direct values only." ], "recorded_on": "2026-11-04", "repros": [ { "call": "=IRR(\"2\")", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet ql006, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-list-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=IRR(TRUE)", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet ql026, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-list-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=IRR(\"2\",\"x\")", "correct": null, "excel": { "bits": null, "display": "#VALUE!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet ql008, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-list-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=IRR(\"2\",NA())", "correct": null, "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet ql009, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-list-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=IRR(\"2\",)", "correct": null, "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet ql010, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-list-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=IRR(NA())", "correct": null, "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet ql036, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-list-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=IRR(NA(),\"x\")", "correct": null, "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet ql038, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-list-controls.capture.json", "repository": "DnaCalc" } } ], "schema": "efh.function-note/v1", "statement": "Text or a logical typed directly as the values argument of IRR is not an error of type: \"\", \"2\", \"x\", \"0\", \"-2\", TRUE and FALSE all give #NUM!, never #VALUE!. The guess is read anyway, and its error wins: with any of those values, a guess of \"x\" gives #VALUE! and a guess of NA() gives #N/A, while 0.1 or an empty guess leaves #NUM!. A direct error in values wins over the guess: IRR(NA(),\"x\") is #N/A.", "status": "measured", "title": "IRR with a direct non-number gives #NUM!, and the guess is still checked" } ], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n[XIRR](FUNC.XIRR.md) uses actual dates. [RATE](FUNC.RATE.md) assumes one repeated payment; [NPV](FUNC.NPV.md) evaluates a supplied periodic rate. [MIRR](FUNC.MIRR.md) uses separate financing and reinvestment rates.\n\n\n\n\n", "how-to-implement": "\nCollect admitted numbers in order and validate their signs. The current internal residual forms `base=1+r` with ordinary binary64 arithmetic, evaluates the runtime `crt_pow(base,i)` for each index, divides the corresponding flow and adds forward. Its domain excludes rates at/below `-0.999999999`. This residual is not the public NPV wrapper’s repeated-factor loop.\n\n### Two admitted flows\n\nThe current route iterates in `q=1+r`, rather than returning the closed-form ratio immediately:\n\n1. Set `current=1+guess`, `previous=1`, and `previous_value=F(0)`.\n2. Evaluate `value=F(current-1)`. If it differs from previous_value, use secant step `value*(current-previous)/(value-previous_value)`. If equal, use the analytic derivative and step `value/Fprime(current-1)`; a zero derivative fails.\n3. Set `next=current-step`. If its stored bits equal current, return `next-1`. Otherwise move the previous state forward and repeat, for at most twenty iterations. Failure gives `#NUM!`.\n\nFor `-1000,1250`, the mathematical q is 1.25 and returned rate one quarter. The q-space iteration and final subtraction still matter to less convenient low-bit results.\n\n### More than two flows\n\nThe current bounded candidate starts from zero and guess, tries secant steps, then analytic Newton steps when a secant is unavailable, and otherwise halves a positive rate or restarts at 0.1. Its search permits 100 iterations with residual magnitude at most `1e-8`. A successful seed gets up to 64 analytic Newton refinements, stopping at a stored-rate fixpoint or noncontracting step.\n\nPublication then scans sixteen adjacent binary64 rates on each side for a smaller absolute residual. It locates both ends of the contiguous equal-absolute-residual plateau by doubling the distance in ordered-rate encodings and bisecting after leaving the plateau. If that plateau spans zero it returns zero; otherwise it returns the midpoint **encoding**, decoded as a rate. This is distinct from averaging the endpoint numbers.\n\nFor negative rates, the current ordered key complements all bits of a negative binary64 value; for a nonnegative value it sets the high bit. This gives a monotone key and keeps the two zero representations adjacent. Decode with the inverse transformation. Plateau search has bounded distance probes and bisections and can fail rather than scan indefinitely.\n\nThe residual producer, root-selection basins, return plateaus and remaining recorded numerical differences remain open. Matching a small residual or a mathematical closed form alone does not identify Excel’s private solver or certify this function.\n\n\n", "quirks": "\nMicrosoft requires at least one positive and one negative value. It ignores text, logicals and empty cells in an array/reference, so a missing amount and numeric zero have different timing effects. Supply the flows in their intended sequence.\n\nThe current collector accepts a row or column vector and gives `#REF!` for a rectangle with both dimensions above one. A contained error becomes `#VALUE!`, whereas a whole-argument scalar error preserves its code. These are current source rules, not a claim about every Excel input route.\n\nMicrosoft documents twenty tries, accuracy within 0.00001 percent and `#NUM!` on nonconvergence. The current candidate has distinct two-flow and general routes; its later refinement and publication rules should not be mistaken for that entire private iteration schedule.\n\n\n", "sources": "\n- [Microsoft: IRR function](https://support.microsoft.com/en-us/excel/functions/irr-function), opened 7 November 2026; syntax, documented argument rules and errors.\n- [DnaCalc implementation](https://github.com/DnaCalc/DnaCalc/blob/da3ecc4fb19a3a5529708c311d0e8f05688ac165/crates/calc-func/src/ported/cashflow_rate_family.rs); implementation steps and the limits identified in the text.\n- [Remaining solver failures](https://github.com/DnaCalc/DnaCalc/blob/da3ecc4fb19a3a5529708c311d0e8f05688ac165/docs/generated/problem-functions.md); source-specific counts, without a whole-function equality claim.\n\n", "try-it": "\n`=IRR({-1000,1250})` returns about `0.25`: one period turns a thousand outflow into 1250 inflow.\n\n`=IRR({-1000,0,1250})` is about `0.1180339887`. The explicit zero preserves a second period, giving `(1+r)^2=1.25`. An ignored blank would remove that position.\n\n`=IRR({-100,230,-132},0.05)` is about `0.1`; a guess of `0.3` leads to about `0.2` in the current route. Both mathematical roots solve `100*(1+r)^2-230*(1+r)+132=0`.\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 | 217 |\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.IRR.json).", "what-it-does": "\n`IRR(values,[guess])` returns a periodic rate that makes an ordered cash-flow series’ present value zero. The first admitted flow occurs at time zero; later flows occur at equally spaced periods. Amounts can vary. Guess defaults to 0.1.\n\nThe mathematical equation is `sum(c_i/(1+r)^i)=0`, with zero-based i. A series with several sign changes can have multiple acceptable roots.\n\n\n" }, "signature": { "display": "IRR(values, [guess])", "parameters": [ { "description": null, "name": "values", "optional": false, "repeats": false }, { "description": null, "name": "guess", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 2, "min": 1 }, "category": "Financial functions", "classification": { "arg_preparation_profile": "RefsVisibleInAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "RefOnly", "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": "Rate at which a series of periodic cash flows has a net present value of zero", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the internal rate of return for a series of cash flows", "microsoft_url": "https://support.microsoft.com/en-us/office/irr-function-64925eaa-9988-495b-b290-3ad0c163c1bc" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "IRR" }, { "locale": "bg-BG", "name": "IRR" }, { "locale": "cs-CZ", "name": "IRR" }, { "locale": "da-DK", "name": "IA" }, { "locale": "de-DE", "name": "IKV" }, { "locale": "el-GR", "name": "IRR" }, { "locale": "en-AU", "name": "IRR" }, { "locale": "en-GB", "name": "IRR" }, { "locale": "en-US", "name": "IRR" }, { "locale": "es-ES", "name": "TIR" }, { "locale": "et-EE", "name": "IRR" }, { "locale": "fi-FI", "name": "SISÄINEN.KORKO" }, { "locale": "fr-FR", "name": "IRR" }, { "locale": "he-IL", "name": "IRR" }, { "locale": "hr-HR", "name": "IRR (internal rate of return, interna stopa povrata)" }, { "locale": "hu-HU", "name": "BMR" }, { "locale": "id-ID", "name": "IRR" }, { "locale": "it-IT", "name": "TIR.COST" }, { "locale": "ja-JP", "name": "IRR" }, { "locale": "ko-KR", "name": "IRR" }, { "locale": "lt-LT", "name": "IRR" }, { "locale": "lv-LV", "name": "IRR" }, { "locale": "nb-NO", "name": "IR" }, { "locale": "nl-NL", "name": "IR" }, { "locale": "pl-PL", "name": "IRR" }, { "locale": "pt-BR", "name": "IRR" }, { "locale": "pt-PT", "name": "TIR" }, { "locale": "ro-RO", "name": "IRR" }, { "locale": "ru-RU", "name": "ВСД" }, { "locale": "sk-SK", "name": "IRR" }, { "locale": "sl-SI", "name": "IRR" }, { "locale": "sr-Latn-RS", "name": "IRR" }, { "locale": "sv-SE", "name": "IR" }, { "locale": "th-TH", "name": "IRR" }, { "locale": "tr-TR", "name": "İÇ_VERİM_ORANI" }, { "locale": "uk-UA", "name": "IRR" }, { "locale": "vi-VN", "name": "IRR" }, { "locale": "zh-CN", "name": "IRR" }, { "locale": "zh-HK", "name": "IRR" }, { "locale": "zh-TW", "name": "IRR" } ], "signature": { "display": "IRR(values, [guess])", "parameters": [ { "description": null, "name": "values", "optional": false, "repeats": false }, { "description": null, "name": "guess", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "IRR", "version_marker": null, "xlcall": { "code": "62", "symbol": "xlfIrr" } }, "microsoft": "https://support.microsoft.com/en-us/office/irr-function-64925eaa-9988-495b-b290-3ad0c163c1bc" }, "try_it": { "formula": "=IRR({-1000,1250})" }, "url": "https://handbook.dnacalc.com/functions/IRR.html", "variants": [], "versions": [ { "behaviour": "=IRR(\"2\") returned #NUM!. =IRR(TRUE) returned #NUM!. 5 further recorded controls are attached. Inputs were supplied through formula literals. These are controls from this environment, not a same-input comparison with another build.", "excel_build": "16.0.20527.20088", "observations": [ { "call": "=IRR(\"2\")", "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" }, { "call": "=IRR(TRUE)", "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" }, { "call": "=IRR(\"2\",\"x\")", "excel": { "bits": null, "display": "#VALUE!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" }, { "call": "=IRR(\"2\",NA())", "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" }, { "call": "=IRR(\"2\",)", "excel": { "bits": null, "display": "#NUM!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" }, { "call": "=IRR(NA())", "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" }, { "call": "=IRR(NA(),\"x\")", "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" } ], "platform": "Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/3345a87/content/notes/FN-IRR-001.json" ] }, { "behaviour": "217 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.IRR.json" ] } ] }