{ "category": "Math and trigonometry functions", "display_name": "ACOS", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.ACOS", "implementation_state": { "answer_bank": { "excel_builds": [ "20430" ], "larger_numeric": 0, "last_bit": 0, "matched": 13962, "other_mismatch": 0, "refused": 0, "rows": 13962, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 13,962 in the answer bank and 3 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 13,965 recorded answers", "workbook_corpus": { "cells": 3, "matched": 3 } }, "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#L44-L44", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/acos.rs#L3-L13" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/math::unary", "ported/asin::asin_kernel", "ported/excel_numeric::atan_with", "ported/excel_numeric::atan_reduced_with", "ported/excel_numeric::binary_with", "ported/excel_numeric::excel_x87_sub", "ported/excel_numeric::excel_x87_mul", "ported/excel_numeric::excel_x87_div", "ported/excel_numeric::excel_atan_reduced", "ported/excel_numeric::excel_sqrt_staged", "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/x87::atan", "ported/excel_numeric/x87::atan_reduced", "ported/excel_numeric/x87::mul", "ported/excel_numeric/x87::sub", "ported/excel_numeric/x87::div" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L44-L44", "state": "matches", "suite": null, "summary": "Matches all 13,965 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ACOS.json", "name": "ACOS", "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- **`ASIN`** — the complementary partner, via `ACOS(x) + ASIN(x) = PI()/2`. Where `ASIN` is odd\n and increasing, `ACOS` is neither odd nor increasing; the pair is not interchangeable with a\n sign flip.\n- **`ATAN`** and **`ATAN2`** — the other route to an angle. `acos(x) = atan2(x, sqrt(1-x^2))` in\n Excel's `x`-first argument order, and that form is better conditioned near the endpoints than\n `ACOS` computed from a series.\n- **`COS`** — the forward function. `COS(ACOS(x)) = x` holds to rounding on the whole domain;\n `ACOS(COS(t))` recovers `t` only for `t` in `[0, pi]`, and folds every other `t` into that\n interval.\n- **`ACOSH`** — the hyperbolic namesake, and a genuinely different function: its domain is\n `[1, +infinity)`, exactly the region where `ACOS` stops being defined. The two domains touch at\n the single point `x = 1`, where both are zero.\n- **`DEGREES`** — the usual consumer of the result.\n- **`IMCOS`** and the complex family — where the branch cuts stop being a footnote.\n- **Confused with**: `ACOT`, whose range is also stated as 0 to pi. Two different functions with\n the same stated range is a real trap, and the discriminator is the domain: `ACOS` takes\n `[-1, 1]`, `ACOT` takes everything.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n`ACOS` is a well-conditioned function in the middle of its domain and an ill-conditioned one at\nboth ends, and every implementation question is about the ends.\n\n**The endpoint problem, stated exactly.** Write `x = 1 - t`. Then `acos(x) ~ sqrt(2t)`. A relative\nerror `eps` in `t` becomes a relative error `eps/2` in the answer — that part is benign. The\nproblem is upstream: when `x` is a double near `1`, forming `1 - x` is exact by Sterbenz's lemma,\nbut *the information was already lost* if `x` itself came from a computation. The spacing of\ndoubles near `1` is about `2^-52`, so the smallest nonzero `acos` reachable from a double argument\nis around `2^-26` — roughly `1.5e-8`. Half the exponent range of the answer is simply unreachable.\nThis is intrinsic to the argument being a cosine, not a defect of any implementation, and it is\nwhy numerical geometry code computes angles from `ATAN2` of a cross product and dot product rather\nthan from `ACOS` of a normalised dot product.\n\n**The complementary identity as a trap.** `acos(x) = pi/2 - asin(x)` is exact in mathematics and\ncatastrophic in floating point for `x` near `1`: `asin(x)` is then near `pi/2`, and the\nsubtraction of two nearly equal quantities destroys the relative accuracy of a result that is\nitself near zero. An implementation of `ACOS` built on `ASIN` this way is accurate near `x = -1`\nand wrong near `x = +1`. The mirror trap catches `ASIN` built on `ACOS`. Cody & Waite state the\nrule: compute whichever of the pair is *large* directly, and get the small one another way.\n\n**The standard remedies**, in the form the reference implementations use:\n\n1. **Split the domain at `|x| = 1/2`.** For `|x| <= 1/2`, evaluate a rational (minimax)\n approximation to `asin` and set `acos(x) = pi/2 - asin(x)`; here both terms are comparable in\n size and the subtraction is harmless.\n2. **For `x` in `(1/2, 1]`, reduce by the half-angle identity**: `acos(x) = 2 * asin(sqrt((1-x)/2))`.\n The argument of the inner `asin` is small, so the accurate small-argument branch does the work,\n and the square root supplies the endpoint behaviour exactly.\n3. **For `x` in `[-1, -1/2)`, use the reflection** `acos(x) = pi - acos(-x)` to move onto the\n branch above. This subtraction is safe because the result is near `pi`, not near zero.\n4. **Never evaluate `sqrt(1 - x*x)`** near the endpoints. The product `x*x` rounds, and the\n subtraction then loses bits that `(1-x)*(1+x)` retains. The factored form is the standard\n substitute and costs one extra multiply.\n\n`fdlibm`'s `e_acos.c` is the canonical published implementation of exactly this structure.\n\n**Correct rounding.** `ACOS` is not correctly rounded in any mainstream library; the usual quality\ntarget is under one ulp over the domain, with the last-bit behaviour near the endpoints being the\npart that differs between vendors. That is where a comparison against Excel would be expected to\nfind its residuals, and no such comparison exists here.\n\n**Symmetry as a self-test.** `ACOS(x) + ACOS(-x)` should be `PI()` and `ACOS(x) + ASIN(x)` should\nbe `PI()/2`. Neither will hold to the last bit for every `x` in any implementation — but *how*\nthey fail is a fingerprint of the branch structure, and it is measurable without an oracle.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number` — an angle in radians in `[0, pi]`.\n\n- **The endpoints** `-1` and `1` are *in* the domain and return `pi` and `0` respectively. This is\n a closed interval; an implementation that tests `|x| < 1` rather than `|x| <= 1` gets both\n endpoints wrong, and they are the two arguments users are most likely to pass.\n- **Just outside the endpoints.** A value one ulp beyond `1` is a domain failure. This matters far\n more than it sounds, because the natural producer of `ACOS` arguments is a normalised dot\n product, and rounding routinely pushes such a quotient a bit past `1`. Formulas that compute an\n angle between vectors need to clamp before calling `ACOS`; without a clamp they fail on exactly\n the parallel-vector case they were written for.\n- **Zero** returns `pi/2`, and the smallest subnormals also return `pi/2` — the function is flat\n enough there that every subnormal maps to the same double.\n- **Large magnitudes** are domain failures, including every value that a text-to-number conversion\n might plausibly produce.\n- **Arrays** lift elementwise, and an out-of-domain element produces an element-local error rather\n than collapsing the whole result — the provisional scalar-lift policy described in the coercion\n chapter, with `ACOS` named there as a canonical example of it.\n\n", "sources": "- Microsoft Learn, \"WorksheetFunction.Acos method (Excel)\" —\n (retrieved:\n description, the `-1` to `1` argument constraint, the `0` to `pi` radian range, and the\n degrees-conversion remark).\n- Abramowitz & Stegun, *Handbook of Mathematical Functions*, chapter 4 section 4.4 — inverse\n circular functions: principal ranges, the complementary and reflection identities, and series.\n- Cody & Waite, *Software Manual for the Elementary Functions*, chapter on `ASIN`/`ACOS` — the\n domain split and the square-root reduction.\n- `fdlibm` `e_acos.c` — the published reference implementation of the near-endpoint branch.\n- Handbook projections `data/functions/FUNC.ACOS.json` (arity,\n `UnaryNumericScalarOrArrayElementwise` lift profile, `real_result_policy` with\n `arg_domain_guard=none;non_finite=allow`) and `data/presence/FUNC.ACOS.json`.\n- Handbook [Coercion and lifting](../model/02-coercion-and-lifting.md) — the elementwise lift and\n the element-local error policy, where `ASIN`-style domain errors are the worked example.\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 | 17 |\n| 20430 | Windows, 64-bit, CPU not recorded | 13,962 |\n\n- XC-ACOS-001: build 19929 versus build 20430; 5 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.ACOS.json).", "what-it-does": "\n`ACOS(number)` is the principal inverse cosine: the angle in radians whose cosine is *number*.\n\n acos: [-1, 1] -> [0, pi], cos(acos x) = x\n\n- **Domain**: the closed interval `[-1, 1]`. Outside it there is no real angle whose cosine is\n *number*, and the function is undefined over the reals.\n- **Range**: `[0, pi]`, the principal branch. Microsoft's Learn reference states this range\n explicitly: the returned angle is given in radians in the range 0 to pi.\n- **Monotonicity**: strictly *decreasing*. `acos(-1) = pi`, `acos(0) = pi/2`, `acos(1) = 0`. It is\n the only one of the three inverse circular primaries that runs downhill, which is a frequent\n source of sign errors when it is substituted for `ASIN`.\n- **Reflection**: `acos(-x) = pi - acos(x)`. The function is neither even nor odd; it is\n antisymmetric about the point `(0, pi/2)`.\n- **Complementary identity**: `acos(x) + asin(x) = pi/2` exactly, for every `x` in the domain.\n This is the single most useful relation on the page and it is also, in floating point, a\n liability — see the numerical notes.\n- **Derivative**: `d/dx acos x = -1 / sqrt(1 - x^2)`, which is finite in the interior and blows up\n at both endpoints. The graph meets `x = 1` and `x = -1` with a vertical tangent.\n- **Endpoint behaviour**: near `x = 1`, `acos(x) = sqrt(2(1-x)) * (1 + (1-x)/12 + ...)`. The\n square root is the whole story of this function's numerics: the answer near the endpoints is\n governed by the square root of a quantity that itself has to be computed by subtraction.\n- **Series about zero**: `acos x = pi/2 - (x + x^3/6 + 3x^5/40 + ...)`, that is, `pi/2` minus the\n arcsine series. Convergence is slow near the endpoints, which is why nobody implements it this\n way.\n- **Complex continuation** (relevant to the `IM*` family, not to this surface): `acos` extends to\n the complex plane with branch cuts along `(-infinity, -1]` and `[1, +infinity)`. The real\n function's domain is exactly the complement of those cuts on the real axis, which is why the\n domain restriction is not arbitrary.\n\nAbramowitz & Stegun treat the inverse circular functions in chapter 4 section 4.4, including the\nprincipal-range conventions used above.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `number` | The cosine of the angle you want. Required. | — |\n\nMicrosoft's Learn reference describes the argument as \"the cosine of the angle you want, and must\nbe from -1 to 1\".\n\nThe commonly misunderstood point is not the slot but the units of the *result*: `ACOS` returns\nradians. Readers who work in degrees need `DEGREES(ACOS(x))`, and the Learn reference gives the\nsame advice in the form \"multiply it by 180/PI()\".\n\n\n" }, "signature": { "display": "ACOS(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": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Angle in radians, from 0 to pi, whose cosine is the given number", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the arccosine of a number", "microsoft_url": "https://support.microsoft.com/en-us/office/acos-function-cb73173f-d089-4582-afa1-76e5524b5d5b" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "ACOS" }, { "locale": "bg-BG", "name": "ACOS" }, { "locale": "cs-CZ", "name": "ACOS" }, { "locale": "da-DK", "name": "ARCCOS" }, { "locale": "de-DE", "name": "ARCCOS" }, { "locale": "el-GR", "name": "ACOS" }, { "locale": "en-AU", "name": "ACOS" }, { "locale": "en-GB", "name": "ACOS" }, { "locale": "en-US", "name": "ACOS" }, { "locale": "es-ES", "name": "ACOS" }, { "locale": "et-EE", "name": "ACOS" }, { "locale": "fi-FI", "name": "ACOS" }, { "locale": "fr-FR", "name": "ACOS" }, { "locale": "he-IL", "name": "ACOS" }, { "locale": "hr-HR", "name": "ACOS" }, { "locale": "hu-HU", "name": "ARCCOS" }, { "locale": "id-ID", "name": "ACOS" }, { "locale": "it-IT", "name": "ARCCOS" }, { "locale": "ja-JP", "name": "ACOS" }, { "locale": "ko-KR", "name": "ACOS" }, { "locale": "lt-LT", "name": "ACOS" }, { "locale": "lv-LV", "name": "ACOS" }, { "locale": "nb-NO", "name": "ACOS" }, { "locale": "nl-NL", "name": "BOOGCOS" }, { "locale": "pl-PL", "name": "ACOS" }, { "locale": "pt-BR", "name": "ACOS" }, { "locale": "pt-PT", "name": "ACOS" }, { "locale": "ro-RO", "name": "ACOS" }, { "locale": "ru-RU", "name": "ACOS" }, { "locale": "sk-SK", "name": "ACOS" }, { "locale": "sl-SI", "name": "ACOS" }, { "locale": "sr-Latn-RS", "name": "ACOS" }, { "locale": "sv-SE", "name": "ACOS" }, { "locale": "th-TH", "name": "ACOS" }, { "locale": "tr-TR", "name": "ACOS" }, { "locale": "uk-UA", "name": "ACOS" }, { "locale": "vi-VN", "name": "ACOS" }, { "locale": "zh-CN", "name": "ACOS" }, { "locale": "zh-HK", "name": "ACOS" }, { "locale": "zh-TW", "name": "ACOS" } ], "signature": { "display": "ACOS(number)", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "ACOS", "version_marker": null, "xlcall": { "code": "99", "symbol": "xlfAcos" } }, "microsoft": "https://support.microsoft.com/en-us/office/acos-function-cb73173f-d089-4582-afa1-76e5524b5d5b" }, "try_it": { "formula": "=ACOS(1)" }, "url": "https://handbook.dnacalc.com/functions/ACOS.html", "variants": [], "versions": [ { "behaviour": "17 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.ACOS.json" ] }, { "behaviour": "13,962 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.ACOS.json" ] } ] }