{
  "category": "Financial functions",
  "display_name": "YIELD",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.YIELD",
  "implementation_state": {
    "answer_bank": {
      "excel_builds": [
        "20228",
        "20527"
      ],
      "larger_numeric": 424,
      "last_bit": 95,
      "matched": 14,
      "other_mismatch": 0,
      "refused": 0,
      "rows": 533,
      "unread": 0,
      "worst_ulp": 4395513236313605
    },
    "detail": "Of 625 recorded answers (533 in the answer bank and 92 workbook cells), 561 do not match: 455 differ by more than 16 ULP, 100 differ by at most 16 ULP, 6 differ in kind or value.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "differs",
    "state_label": "Known larger differences",
    "summary": "Known larger differences on 561 of 625 recorded answers",
    "workbook_corpus": {
      "cells": 92,
      "larger_numeric": 31,
      "last_bit": 5,
      "matched": 50,
      "other_mismatch": 6,
      "worst_ulp": 4
    }
  },
  "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/bonds.rs#L128-L136",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/bond_core_family.rs#L314-L326",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/bond_core_family.rs#L378-L425",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/bond_core_family.rs#L558-L597"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "catalogue/bonds::basis",
        "catalogue/bonds::yield_date",
        "catalogue/bonds::bond_out",
        "catalogue/financial::required_number",
        "catalogue/financial::required_num",
        "catalogue/financial::date_1900",
        "locale::days_from_civil",
        "locale::civil_from_days",
        "locale::excel_serial_from_ymd",
        "locale::ymd_from_excel_serial",
        "ported/bond_core_family::max_serial",
        "ported/bond_core_family::derr",
        "ported/bond_core_family::dyear",
        "ported/bond_core_family::dim",
        "ported/bond_core_family::act",
        "ported/bond_core_family::basis",
        "ported/bond_core_family::freq",
        "ported/bond_core_family::dser",
        "ported/bond_core_family::pos",
        "ported/bond_core_family::rate",
        "ported/bond_core_family::addm",
        "ported/bond_core_family::d360us",
        "ported/bond_core_family::d360eu",
        "ported/bond_core_family::dc",
        "ported/bond_core_family::dd",
        "ported/bond_core_family::ctx",
        "ported/bond_core_family::period",
        "ported/bond_core_family::excel_bond_pow",
        "ported/bond_core_family::pcomp_disc",
        "ported/bond_core_family::map_bond_core_error_to_ws",
        "ported/day_count_common::days_in_month",
        "ported/day_count_common::us_30_360",
        "ported/excel_numeric::binary_with",
        "ported/excel_numeric::excel_pow_chain",
        "ported/excel_numeric::excel_x87_mul",
        "ported/excel_numeric/x87::mul",
        "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"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/bonds.rs#L128-L136",
      "state": "differs",
      "suite": null,
      "summary": "Known larger differences on 561 of 625 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.YIELD.json",
  "name": "YIELD",
  "notes": [],
  "schema": "efh.function-reference/v1",
  "section_order": [
    "what-it-does",
    "try-it",
    "quirks",
    "how-to-implement",
    "version-differences",
    "alternatives"
  ],
  "sections": {
    "alternatives": "\n[PRICE](FUNC.PRICE.md) performs the inverse calculation; [ODDFPRICE](FUNC.ODDFPRICE.md) and [ODDLPRICE](FUNC.ODDLPRICE.md) handle irregular coupons.\n\n\n",
    "how-to-implement": "\nAfter validating dates, positive price/redemption, nonnegative coupon rate and the frequency/basis, build the coupon schedule and remaining count N. The current code uses three distinct routes, all with ordinary binary64 arithmetic.\n\n1. For an on-coupon settlement with N>1 and both price and redemption exactly 100, return the coupon rate when its coupon amount is finite. This par shortcut has its own retained controls; it is not evidence of the general solver’s accuracy.\n2. For N=1, calculate coupon `C=100*rate/frequency`, coupon denominator E, accrued span A and the **direct** settlement-to-next-coupon span S using the current day-count helpers. Return `(((redemption+C)/(price+C*A/E))-1)*frequency*E/S`, preserving the source’s left-to-right multiplication and division. This one-coupon YIELD span differs from PRICE’s use of derived `E-A` where the calendar rules distinguish them.\n3. For N>1, solve the internal clean-price callback for the supplied target price. Its schedule quantities use the derived settlement complement, but its current discount leaf is the runtime `crt_pow`, whereas the public PRICE route uses its newer integer and x87-chain helper. Calling public PRICE unconditionally would also reject the negative trial yields that this solver needs to probe.\n\nThe current general solver starts at `lo=-frequency+1e-10`; an unevaluable lower endpoint is treated as infinite price. Start hi at one and double it, up to eighty times, until its internal price is no greater than target. Reject an unreachable target or propagate an unhandled evaluation error.\n\nBisect with ordinary arithmetic midpoint `(lo+hi)/2` for up to 2,200 iterations. Return an exact-price midpoint immediately. Otherwise move lo upward when its price is above target and hi downward when below. Stop when the midpoint can no longer lie strictly between the stored bounds, then choose the endpoint with smaller absolute price residual; a tie chooses hi. This is an arithmetic-midpoint search, distinct from the encoding-midpoint distribution inverses.\n\nFor the one-coupon example, C=3, A=90, E=180 and S=90. The first ratio is `103/101.5`; subtracting one and multiplying by `2*180/90=4` gives about `0.0591133005`.\n\nMicrosoft documents a one-coupon formula and a hundred-iteration Newton method for longer bonds. The current candidate instead uses the bisection route above. Its internal price callback, root selection, return rounding and remaining report differences are not fully identified. The pinned source’s explicit split between PRICE and YIELD is a limit to retain, rather than an algebraic identity to remove.\n\n\n",
    "quirks": "\nBasis defaults to zero: 0 US 30/360, 1 actual/actual, 2 actual/360, 3 actual/365, 4 European 30/360. Dates and selectors are truncated under their documented rules. Use DATE values rather than locale-dependent date text. Settlement must precede maturity; negative coupon rate, invalid frequency/basis or nonpositive redemption gives `#NUM!`. Price must be positive. The one-coupon and multiple-coupon branches use different formulas.\n\n\n",
    "sources": "\n- [Microsoft: YIELD function](https://support.microsoft.com/en-us/excel/functions/yield-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/bond_core_family.rs); implementation steps and the limits identified in the text.\n- [Stored LN/product/EXP discount chain](https://github.com/DnaCalc/DnaCalc/blob/da3ecc4fb19a3a5529708c311d0e8f05688ac165/crates/calc-func/src/ported/excel_numeric/mod.rs); `excel_pow_chain`, separate from runtime pow.\n- [COUPDAYSNC’s retained internal/public difference](FUNC.COUPDAYSNC.md); the published coupon-day quantity is not an unconditional replacement for PRICE’s internal complement.\n\n",
    "try-it": "\n`=YIELD(DATE(2027,1,1),DATE(2028,1,1),0.06,100,100,2,0)` is about `0.06`. This on-coupon par bond takes the current exact par shortcut, rather than needing a generic numerical inversion.\n\n`=YIELD(DATE(2027,4,1),DATE(2027,7,1),0.06,100,100,2,0)` is about `0.0591133005`. The final coupon is three and accrued interest is 1.5, so the clean price of 100 corresponds to an invested dirty amount of 101.5.\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| 20228 | Windows, 64-bit, CPU not recorded | 504 |\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.YIELD.json).",
    "what-it-does": "\n`YIELD(settlement,maturity,rate,pr,redemption,frequency,[basis])` solves an annual yield from a coupon security’s clean price per 100 face value. Rate is the annual coupon rate; frequency is one, two or four payments per year.\n\n\n"
  },
  "signature": {
    "display": "YIELD(settlement, maturity, rate, pr, redemption, frequency, [basis])",
    "parameters": [
      {
        "description": null,
        "name": "settlement",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "maturity",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "rate",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "pr",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "redemption",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "frequency",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "basis",
        "optional": true,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 7,
        "min": 6
      },
      "category": "Financial functions",
      "classification": {
        "arg_preparation_profile": "ValuesOnlyPreAdapter",
        "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": "Yield of a security with periodic coupons",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns the yield on a security that pays periodic interest",
        "microsoft_url": "https://support.microsoft.com/en-us/office/yield-function-f5f5ca43-c4bd-434f-8bd2-ed3c9727a4fe"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "العائد"
        },
        {
          "locale": "bg-BG",
          "name": "ДОБИВ"
        },
        {
          "locale": "cs-CZ",
          "name": "YIELD"
        },
        {
          "locale": "da-DK",
          "name": "AFKAST"
        },
        {
          "locale": "de-DE",
          "name": "RENDITE"
        },
        {
          "locale": "el-GR",
          "name": "ΑΠΟΔΟΣΗ"
        },
        {
          "locale": "en-AU",
          "name": "YIELD"
        },
        {
          "locale": "en-GB",
          "name": "YIELD"
        },
        {
          "locale": "en-US",
          "name": "YIELD"
        },
        {
          "locale": "es-ES",
          "name": "RENDTO"
        },
        {
          "locale": "et-EE",
          "name": "YIELD"
        },
        {
          "locale": "fi-FI",
          "name": "TUOTTO"
        },
        {
          "locale": "fr-FR",
          "name": "RENDEMENT.TITRE"
        },
        {
          "locale": "he-IL",
          "name": "YIELD"
        },
        {
          "locale": "hr-HR",
          "name": "YIELD"
        },
        {
          "locale": "hu-HU",
          "name": "HOZAM"
        },
        {
          "locale": "id-ID",
          "name": "HASIL"
        },
        {
          "locale": "it-IT",
          "name": "REND"
        },
        {
          "locale": "ja-JP",
          "name": "YIELD"
        },
        {
          "locale": "ko-KR",
          "name": "YIELD"
        },
        {
          "locale": "lt-LT",
          "name": "YIELD"
        },
        {
          "locale": "lv-LV",
          "name": "ATDEVE"
        },
        {
          "locale": "nb-NO",
          "name": "AVKAST"
        },
        {
          "locale": "nl-NL",
          "name": "OPBRENGST"
        },
        {
          "locale": "pl-PL",
          "name": "PLON"
        },
        {
          "locale": "pt-BR",
          "name": "RENDIMENTO"
        },
        {
          "locale": "pt-PT",
          "name": "LUCRO"
        },
        {
          "locale": "ro-RO",
          "name": "PRODUCȚIE"
        },
        {
          "locale": "ru-RU",
          "name": "ДОХОД"
        },
        {
          "locale": "sk-SK",
          "name": "VÝNOS"
        },
        {
          "locale": "sl-SI",
          "name": "YIELD"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "YIELD"
        },
        {
          "locale": "sv-SE",
          "name": "AVKASTNING"
        },
        {
          "locale": "th-TH",
          "name": "YIELD"
        },
        {
          "locale": "tr-TR",
          "name": "ÖDEME"
        },
        {
          "locale": "uk-UA",
          "name": "ПРИБУТОК"
        },
        {
          "locale": "vi-VN",
          "name": "HOA LỢI"
        },
        {
          "locale": "zh-CN",
          "name": "YIELD"
        },
        {
          "locale": "zh-HK",
          "name": "YIELD"
        },
        {
          "locale": "zh-TW",
          "name": "YIELD"
        }
      ],
      "signature": {
        "display": "YIELD(settlement, maturity, rate, pr, redemption, frequency, [basis])",
        "parameters": [
          {
            "description": null,
            "name": "settlement",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "maturity",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "rate",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "pr",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "redemption",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "frequency",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "basis",
            "optional": true,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "YIELD",
      "version_marker": null,
      "xlcall": {
        "code": "442",
        "symbol": "xlfYield"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/yield-function-f5f5ca43-c4bd-434f-8bd2-ed3c9727a4fe"
  },
  "try_it": {
    "formula": "=YIELD(DATE(2027,1,1),DATE(2028,1,1),0.06,100,100,2,0)"
  },
  "url": "https://handbook.dnacalc.com/functions/YIELD.html",
  "variants": [],
  "versions": [
    {
      "behaviour": "504 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.YIELD.json"
      ]
    }
  ]
}