{
  "category": "Math and trigonometry functions",
  "display_name": "COS",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.COS",
  "implementation_state": {
    "answer_bank": {
      "excel_builds": [
        "20131",
        "20228",
        "20430",
        "20527",
        "?"
      ],
      "larger_numeric": 0,
      "last_bit": 0,
      "matched": 3684,
      "other_mismatch": 0,
      "refused": 0,
      "rows": 3684,
      "unread": 0,
      "worst_ulp": 0
    },
    "detail": "Recorded: 3,684 in the answer bank and 27 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 3,711 recorded answers",
    "workbook_corpus": {
      "cells": 27,
      "matched": 27
    }
  },
  "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/math.rs#L60-L62",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/cos.rs#L3-L7"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "catalogue/math::raw",
        "ported/excel_numeric::cos_with",
        "ported/excel_numeric::excel_cos",
        "ported/excel_numeric/soft87::pack_raw",
        "ported/excel_numeric/soft87::zero",
        "ported/excel_numeric/soft87::inf",
        "ported/excel_numeric/soft87::pack",
        "ported/excel_numeric/soft87::ext_pi",
        "ported/excel_numeric/soft87::ext_one",
        "ported/excel_numeric/soft87::ext_abs",
        "ported/excel_numeric/soft87::ext_chs"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L60-L62",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 3,711 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.COS.json",
  "name": "COS",
  "notes": [],
  "schema": "efh.function-reference/v1",
  "section_order": [
    "what-it-does",
    "try-it",
    "quirks",
    "how-to-implement",
    "version-differences",
    "alternatives"
  ],
  "sections": {
    "alternatives": "\n### Relationships\n\n\n- **`SIN`, `TAN`** — the other two published primaries. `EV-MATH-0004` treats all six circular\n  functions as one identification problem, and it is the right way to read them.\n- **`SEC`** — the reciprocal, `1/COS`. `EV-MATH-0004` records that the reciprocal surfaces are\n  built from the *published* primaries, which matters: see the numerical notes.\n- **`ACOS`** — the inverse, principal branch `[0, π]`. `ACOS(COS(x))` recovers `x` only on\n  `[0, π]`; elsewhere it returns the folded representative.\n- **[COSH](FUNC.COSH.md)** — the hyperbolic partner, `cosh x = cos(ix)`. The name is the only\n  thing they share computationally: `COSH` overflows and has no reduction problem, `COS` cannot\n  overflow and has nothing *but* a reduction problem.\n- **`RADIANS`, [DEGREES](FUNC.DEGREES.md)** — the unit converters that stand between this\n  function and most spreadsheet users.\n- **`IMCOS`** — the complex-argument version, which needs `COS`, `SIN`, `COSH` and `SINH`\n  together.\n- **`PI()`** — the constant whose rounding sets the error at every \"should be zero\" point.\n\n\n",
    "how-to-implement": "\n### Numerical notes\n\n\nCosine is the textbook case where the interesting error is committed *before* the approximation\nstarts.\n\n**The reduction problem.** To evaluate `cos x` you write `x = k·(π/2) + r` with `|r| ≤ π/4`,\nthen use a polynomial in `r` and a quadrant rule. Since `π/2` is irrational, computing `r`\nrequires the true `π/2` to enough bits. If the reduction uses a `π/2` stored to `p` bits, the\ncomputed `r` carries an absolute error of roughly `|x| · 2^-p`, and because `cos` has unit\nderivative near its zeros, that absolute error passes straight into the result. For `|x|` near\n`2^30` and a 64-bit stored constant the reduced argument can be wrong in its leading bits;\nby `|x|` near `2^60` it can be entirely noise.\n\nThe three standard answers:\n\n1. **Cody & Waite** two- or three-part reduction: split the constant into exactly representable\n   pieces and accumulate `x - k·π/2` in stages. Cheap, and correct only up to a stated argument\n   magnitude, which the authors state.\n2. **Payne–Hanek** infinite-precision reduction: multiply by a long stored expansion of `2/π`\n   and keep only the fractional part. Correct for every finite double, at real cost. This is\n   what a `math-correct` flavour must do.\n3. **Hardware reduction** — the x87 `FPREM1` instruction reduces against a `π` stored in ROM to\n   66 bits. Fast, and its accuracy ceiling is that constant.\n\n**What the evidence says.** `EV-MATH-0004` is a substrate identification covering all six\ncircular surfaces, each scored individually. It names the substrate as the x87\n`FSIN`/`FPTAN` chain with `FPREM1` argument reduction against the 64-bit ROM `π`, and it\nrecords that Cody–Waite reduction against extended `π` is *ruled out* — the pre-sign-off\ncatalogue row recorded large argument-reduction drift in the moderate-to-large range, which is\nthe fingerprint of a limited-precision reduction constant rather than a bad polynomial. The\nfigures live in the evidence layer and render beside this page. The record also carries a\nhost-CPU microcode caveat on `FPREM1`/`FSIN`/`FPTAN`: an answer produced through those\ninstructions is a property of the CPU as much as of the software, so this surface's last bits\nare platform-scoped by construction.\n\n**The polynomial half is the easy half.** Once `|r| ≤ π/4`, a minimax polynomial in `r²` of\nmodest degree delivers well under an ulp; A&S 4.3.98–4.3.99 gives the classical coefficient\nsets, fdlibm's `__kernel_cos` is the standard modern reference, and correctly-rounded\nimplementations (CRlibm, and the CORE-MATH successors) show the achievable target.\n\n**A note for anyone building `SEC` or comparing against it**: computing `1/COS(x)` from the\n*published* (already rounded to binary64) cosine double-rounds — the cosine's own error is\ninverted along with the value. That is a different function from a directly-evaluated secant,\nand `EV-MATH-0004` records the reciprocal construction explicitly.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nReturns `Number` in `[-1, 1]`.\n\n- **Zero** — `COS(0) = 1` exactly, and that is the one value the function returns exactly for\n  a reason rather than by luck.\n- **Large arguments** — mathematically well defined and, for a double argument, a perfectly\n  determinate real number: a double *is* an exact rational, so `cos` of it has one true value.\n  The question is only whether an implementation computes it. See below.\n- **`COS(PI())`** — not exactly `-1`, for the same reason `COS(PI()/2)` is not exactly `0`.\n- **Overflow is impossible.** The output is bounded, so the `non_finite=num` half of the\n  real-result policy can only fire because of the argument guard, never because of the value.\n- **Degrees.** The single most common wrong answer from this function is a correct cosine of\n  the wrong angle. Microsoft's page pre-empts it; the Handbook repeats it.\n\n\n\n### Errors\n\n\nMicrosoft's `COS` page documents no error conditions. The shared call model supplies the rest:\nnon-numeric text in the numeric slot surfaces `#VALUE!`, and an error value in the argument\npropagates. The mechanically rendered battery beside this page shows the boundary probes.\n\nIf the `circular_trig_overflow` guard noted above corresponds to Excel behaviour, a large enough\nargument would produce `#NUM!` — an outcome Microsoft's page does not document for `COS`. That\nis stated here as an open question, not as behaviour.\n\n\n",
    "sources": "- Handbook evidence record `EV-MATH-0004` — the six-surface trigonometric identification, the\n  `FPREM1`-against-ROM-`π` substrate, the reciprocal construction of `SEC`/`CSC`/`COT`, the\n  ruled-out Cody–Waite reduction, and the host-CPU microcode caveat. Read its reader warning.\n- Abramowitz & Stegun, chapter 4.3 — circular functions, series, and approximations.\n- Cody & Waite, *Software Manual for the Elementary Functions* — classical reduction.\n- Payne & Hanek (1983) — infinite-precision radian reduction.\n- Muller, *Elementary Functions: Algorithms and Implementation* — reduction error analysis and\n  worst cases; fdlibm `__kernel_cos` as the standard polynomial reference.\n- Handbook, [Coercion and lifting](../model/02-coercion-and-lifting.md).\n- Handbook projections `data/functions/FUNC.COS.json` (the `arg_domain_guard=circular_trig_overflow`\n  and `non_finite=num` axis values) and `data/presence/FUNC.COS.json`.\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| 19929 | Windows, bitness not recorded, CPU not recorded | 32 |\n| 20131 | Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics | 913 |\n| 20228 | Windows, 64-bit, CPU not recorded | 1,540 |\n| 20430 | Windows, 64-bit, CPU not recorded | 1,224 |\n\n- XC-COS-001: build 19929 versus build 20430; 1 same-input pairs, 0 differing answers. Compared axes: excel-build. Numeric answers were compared by their recorded binary64 bits; other answers by typed value.\n- XC-COS-002: build 20131 versus build 20228; 1 same-input pairs, 0 differing answers. Compared axes: excel-build. Numeric answers were compared by their recorded binary64 bits; other answers by typed value.\n- XC-COS-003: build 20131 versus build 20430; 1 same-input pairs, 0 differing answers. Compared axes: excel-build. Numeric answers were compared by their recorded binary64 bits; other answers by typed value.\n\nAgreement on these compared inputs does not establish agreement on unmeasured inputs.\n\n[Recorded environments and comparison details](https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.COS.json).",
    "what-it-does": "\n`COS(number)` returns the cosine of an angle **in radians**. Microsoft's page says exactly that,\nand adds the conversion note: use `RADIANS(x)` or multiply degrees by `PI()/180`.\n\nThe mathematics, as A&S chapter 4.3 states it:\n\n    cos z = (e^{iz} + e^{-iz}) / 2\n    cos x = 1 - x²/2! + x⁴/4! - x⁶/6! + …          (convergent for all x)\n\n| Property | Statement |\n|---|---|\n| Domain | all real `x` (mathematically; see the guard note below) |\n| Range | `[-1, 1]`, attained |\n| Parity | even: `cos(-x) = cos(x)` |\n| Period | `2π`, and `cos(x + π) = -cos(x)` |\n| Zeros | `x = π/2 + kπ`, all simple — **none of them is a binary64 number** |\n| Pythagorean identity | `cos²x + sin²x = 1` |\n| Phase shift | `cos x = sin(x + π/2)` |\n| Derivative | `d/dx cos x = -sin x` |\n| Entire | no poles, no branch cuts anywhere in the complex plane |\n\nThe row that carries the most practical weight is the one about zeros. `π/2` is irrational, so\nno double is exactly a zero of the cosine; `COS(PI()/2)` is not zero and cannot honestly be\nexpected to be. What it *is* equals, to first order, the distance from the double `PI()/2` to\nthe true `π/2` — which makes it a direct readout of how well the constant is rounded, not a\ndefect in the cosine.\n\nThere is no analytic difficulty in cosine anywhere. It is entire, it is bounded, and its\nTaylor series converges everywhere. **The entire numerical problem is argument reduction**, and\nthat is the subject of the numerical notes.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Notes |\n|---|---|---|\n| `number` | The angle in radians. Required. | Microsoft states no magnitude constraint on this page |\n\n"
  },
  "signature": {
    "display": "COS(number)",
    "parameters": [
      {
        "description": null,
        "name": "number",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 1,
        "min": 1
      },
      "category": "Math and trigonometry functions",
      "classification": {
        "arg_preparation_profile": "ValuesOnlyPreAdapter",
        "coercion_lift_profile": "UnaryNumericScalarOrArrayElementwise",
        "determinism_class": "Deterministic",
        "error_collapse_profile": "None",
        "fec_dependency_profile": "None",
        "host_interaction_class": "None",
        "kernel_signature_class": "NumToNum",
        "rich_value_usage": "RichBlind",
        "surface_fec_dependency_profile": "RefOnly",
        "thread_safety_class": "SafePure",
        "volatility_class": "NonVolatile"
      },
      "descriptions": {
        "long": null,
        "short": "Cosine of an angle in radians",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns the cosine of a number",
        "microsoft_url": "https://support.microsoft.com/en-us/office/cos-function-0fb808a5-95d6-4553-8148-22aebdce5f05"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "COS"
        },
        {
          "locale": "bg-BG",
          "name": "COS"
        },
        {
          "locale": "cs-CZ",
          "name": "COS"
        },
        {
          "locale": "da-DK",
          "name": "COS"
        },
        {
          "locale": "de-DE",
          "name": "COS"
        },
        {
          "locale": "el-GR",
          "name": "COS"
        },
        {
          "locale": "en-AU",
          "name": "COS"
        },
        {
          "locale": "en-GB",
          "name": "COS"
        },
        {
          "locale": "en-US",
          "name": "COS"
        },
        {
          "locale": "es-ES",
          "name": "COS"
        },
        {
          "locale": "et-EE",
          "name": "COS"
        },
        {
          "locale": "fi-FI",
          "name": "COS"
        },
        {
          "locale": "fr-FR",
          "name": "COS"
        },
        {
          "locale": "he-IL",
          "name": "COS"
        },
        {
          "locale": "hr-HR",
          "name": "COS"
        },
        {
          "locale": "hu-HU",
          "name": "COS"
        },
        {
          "locale": "id-ID",
          "name": "COS"
        },
        {
          "locale": "it-IT",
          "name": "COS"
        },
        {
          "locale": "ja-JP",
          "name": "COS"
        },
        {
          "locale": "ko-KR",
          "name": "COS"
        },
        {
          "locale": "lt-LT",
          "name": "COS"
        },
        {
          "locale": "lv-LV",
          "name": "COS"
        },
        {
          "locale": "nb-NO",
          "name": "COS"
        },
        {
          "locale": "nl-NL",
          "name": "COS"
        },
        {
          "locale": "pl-PL",
          "name": "COS"
        },
        {
          "locale": "pt-BR",
          "name": "COS"
        },
        {
          "locale": "pt-PT",
          "name": "COS"
        },
        {
          "locale": "ro-RO",
          "name": "COS"
        },
        {
          "locale": "ru-RU",
          "name": "COS"
        },
        {
          "locale": "sk-SK",
          "name": "COS"
        },
        {
          "locale": "sl-SI",
          "name": "COS"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "COS"
        },
        {
          "locale": "sv-SE",
          "name": "COS"
        },
        {
          "locale": "th-TH",
          "name": "COS"
        },
        {
          "locale": "tr-TR",
          "name": "COS"
        },
        {
          "locale": "uk-UA",
          "name": "COS"
        },
        {
          "locale": "vi-VN",
          "name": "COS"
        },
        {
          "locale": "zh-CN",
          "name": "COS"
        },
        {
          "locale": "zh-HK",
          "name": "COS"
        },
        {
          "locale": "zh-TW",
          "name": "COS"
        }
      ],
      "signature": {
        "display": "COS(number)",
        "parameters": [
          {
            "description": null,
            "name": "number",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "COS",
      "version_marker": null,
      "xlcall": {
        "code": "16",
        "symbol": "xlfCos"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/cos-function-0fb808a5-95d6-4553-8148-22aebdce5f05"
  },
  "try_it": {
    "formula": "=COS(1)"
  },
  "url": "https://handbook.dnacalc.com/functions/COS.html",
  "variants": [],
  "versions": [
    {
      "behaviour": "32 captured inputs are indexed for this environment. Capture dates are not recorded. This is a reading count, not a comparison with another build.",
      "excel_build": "16.0 build 19929",
      "platform": "Windows, bitness not recorded, CPU not recorded",
      "sources": [
        "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.COS.json"
      ]
    },
    {
      "behaviour": "913 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.COS.json"
      ]
    },
    {
      "behaviour": "1,540 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.COS.json"
      ]
    },
    {
      "behaviour": "1,224 captured inputs are indexed for this environment. Capture dates: 2026-09-29 to 2026-09-29. This is a reading count, not a comparison with another build.",
      "excel_build": "16.0 build 20430",
      "platform": "Windows, 64-bit, CPU not recorded",
      "sources": [
        "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.COS.json"
      ]
    }
  ]
}