{ "category": "Math and trigonometry functions", "display_name": "ACOTH", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.ACOTH", "implementation_state": { "answer_bank": { "excel_builds": [ "20131", "20228", "20430" ], "larger_numeric": 0, "last_bit": 0, "matched": 269996, "other_mismatch": 0, "refused": 0, "rows": 269996, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 269,996 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 269,999 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#L47-L47", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/acoth.rs#L12-L37", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/acoth.rs#L39-L64" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/math::unary", "ported/excel_numeric::binary_with", "ported/excel_numeric::excel_x87_add", "ported/excel_numeric::excel_x87_mul", "ported/excel_numeric::excel_x87_div", "ported/excel_numeric/x87::mul", "ported/excel_numeric/x87::add", "ported/excel_numeric/x87::div" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L47-L47", "state": "matches", "suite": null, "summary": "Matches all 269,999 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ACOTH.json", "name": "ACOTH", "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- **`ATANH`** — the reciprocal partner and the complementary domain: `acoth(x) = atanh(1/x)`\n wherever both are defined, `ATANH` on `(-1, 1)` and `ACOTH` on `|x| > 1`. Upstream identification\n work treats the two together for exactly this reason, and both carry evidence records here.\n- **`COTH`** — the forward function. `COTH(ACOTH(x)) = x` to rounding on the domain;\n `ACOTH(COTH(t)) = t` for every nonzero `t`.\n- **`ACOSH`** — shares the exclusion of the unit interval, but only on one side: `ACOSH` takes\n `[1, infinity)`, `ACOTH` takes `|x| > 1`. They differ at exactly `x = 1`, where `ACOSH` is\n defined and zero and `ACOTH` is not defined at all.\n- **`ACOT`** — the circular namesake, and unlike `ACOTH` it has no domain restriction whatsoever.\n The pair is a good illustration that a hyperbolic namesake is not a variant: it is a different\n function with a different domain and a different shape.\n- **`LN`** — the substrate of the closed form, and the source of the large-argument hazard.\n- **Confused with**: `1/COTH(x)`, and with `ATANH`, whose domain is the exact complement.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n`ACOTH` has one serious hazard, and it is at the far end of the domain rather than at the poles —\nthe opposite of what the function's shape suggests.\n\n**The large-argument cancellation.** Evaluate `(1/2) ln((x+1)/(x-1))` for large `x`. The ratio\n`(x+1)/(x-1)` tends to `1`, and `ln` of a value near `1` is the canonical accuracy disaster: the\ninformation about the answer lives entirely in the digits of the ratio that the division has just\nrounded away. Concretely, once `x` exceeds about `2^53`, the doubles `x+1` and `x-1` are the same\nnumber, the ratio is exactly `1`, and the naive form returns exactly zero — where the true answer\nis approximately `1/x`, a perfectly representable positive number. The failure begins long before\nthat: relative accuracy degrades steadily from around `x = 10`.\n\n**The remedies**, both standard:\n\n1. **Reciprocate.** `acoth(x) = atanh(1/x)`, and `1/x` is small, so an accurate small-argument\n `atanh` delivers full relative accuracy right down to the subnormals. This is the single most\n effective change and it costs one division.\n2. **Use `log1p` on the difference form.** `atanh(u) = (1/2)(log1p(u) - log1p(-u))` with\n `u = 1/x`, which never forms a quantity near `1` and never takes a logarithm of one. Higham's\n treatment of `log(1+x)` is the standard reference for why the `log1p` primitive exists at all.\n\nNear the poles, by contrast, the naive form is fine: `(x+1)/(x-1)` is large there, `ln` of a large\nnumber is well conditioned, and the only subtlety is that `x - 1` must be computed from a double\nargument that is already close to `1` — which Sterbenz's lemma makes exact.\n\n**So the correct branch structure is the reverse of the intuitive one**: use the direct ratio-log\n*near* the poles, where the ratio is far from one, and the reciprocal `atanh` form *far* from\nthem, where the ratio is close to one. An implementation that uses one form everywhere is wrong at\none end or the other.\n\n**Why the switch point matters more here than usual.** Because the two forms disagree in the last\nbits over a whole band, any implementation that places its switch differently from Excel's will\ndiffer from Excel on every argument in the gap between the two placements — even though both forms\nare individually excellent. This is the characteristic signature of a piecewise elementary\nfunction, and it is why identification work on this family concentrates on locating switches rather\nthan on improving accuracy.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`.\n\n- **`x = 1` and `x = -1`** are *not* in the domain and are rejected. The interval is open; these\n are the poles.\n- **Anything strictly inside `(-1, 1)`**, including zero and every subnormal, is a domain failure.\n Readers arriving from `ATANH` — whose domain is exactly this interval — get this wrong in both\n directions.\n- **Just outside `±1`** the answer is finite and modest. There is no overflow near the poles,\n because the growth is logarithmic: the largest magnitude reachable from a double argument is\n around 18.4, attained one ulp outside `1`.\n- **Large magnitudes** decay towards zero like `1/x`, and the result reaches into the subnormal\n range at the top of the double domain. This is the region where relative accuracy is hard to\n keep, and where the two candidate evaluation forms visibly differ.\n- **Arrays** lift elementwise, with out-of-domain elements erroring element-locally.\n\n", "sources": "- Microsoft Learn, \"WorksheetFunction.Acoth method (Excel)\" —\n (retrieved: the\n description and argument wording; **no domain constraint and no error condition are stated\n there**).\n- Abramowitz & Stegun, *Handbook of Mathematical Functions*, chapter 4 section 4.6 — the closed\n form, the excluded interval, and the relation to `atanh`.\n- Kahan, *Branch Cuts for Complex Elementary Functions* — the branch structure of `acoth` and why\n its cut is the closed unit interval.\n- Higham, *Accuracy and Stability of Numerical Algorithms*, chapter 1 — the `log(1+x)` problem\n behind the large-argument remedy.\n- Handbook evidence record `EV-MATH-0006` (subjects include `FUNC.ACOTH`) — an open-discrepancy\n record with a per-surface count, an upstream severity and maturity, and open rows. Its figures\n and warnings are rendered with the record.\n- Handbook projections `data/functions/FUNC.ACOTH.json` (arity, lift profile, `real_result_policy`\n with `arg_domain_guard=none;non_finite=allow`) and `data/presence/FUNC.ACOTH.json` (implementing\n module; entries in the discrepancy and math-deviation catalogues and in the `BUG-FUNC-027`\n scalar-invocation sweep).\n- Handbook [Coercion and lifting](../model/02-coercion-and-lifting.md); sibling page\n [ATANH](FUNC.ATANH.md).\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 | 26 |\n| 20131 | Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics | 56 |\n| 20228 | Windows, 64-bit, CPU not recorded | 239,774 |\n| 20430 | Windows, 64-bit, CPU not recorded | 1,224 |\n\n- XC-ACOTH-001: build 19929 versus build 20131; 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-ACOTH-002: build 19929 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-ACOTH-003: 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-ACOTH-004: build 20131 versus build 20228; 9 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-ACOTH-005: 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- XC-ACOTH-006: build 20228 versus build 20430; 4 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.ACOTH.json).", "what-it-does": "\n`ACOTH(number)` is the inverse hyperbolic cotangent.\n\n acoth x = (1/2) * ln( (x + 1) / (x - 1) ) = atanh(1/x), |x| > 1\n\n- **Domain**: `|x| > 1`, that is `(-infinity, -1) ∪ (1, +infinity)`. The closed interval\n `[-1, 1]` is excluded: `coth` maps `R \\ {0}` onto exactly `|y| > 1`, so no real argument in the\n unit interval has a real inverse hyperbolic cotangent. This is the *complement* of `ATANH`'s\n domain, and the two functions partition the real line between them but for the two endpoints.\n- **Range**: `(-infinity, 0) ∪ (0, +infinity)` — every nonzero real, with zero itself unattained.\n `acoth` never returns zero, because `coth` never equals zero.\n- **Parity**: odd. `acoth(-x) = -acoth(x)`. This is exact mathematics and, as the identification\n work in this family has shown for its sibling, not something an implementation gets for free.\n- **Poles**: logarithmic singularities at `x = 1+` (where `acoth -> +infinity`) and `x = -1-`\n (where `acoth -> -infinity`). Approach from *inside* the interval is not possible; there is\n nothing there.\n- **Asymptotics**: `acoth(x) = 1/x + 1/(3x^3) + 1/(5x^5) + ...` for `|x| > 1`. As\n `|x| -> infinity` the function decays like `1/x` and reaches into the subnormals. This is the\n half of the domain where all the numerical difficulty lives.\n- **Near the poles**: with `x = 1 + t`, `acoth(1 + t) = (1/2) * ln(2/t) + O(t)`. The growth is\n logarithmic, so even an argument one ulp above `1` produces only a modest number — around 18.\n The function is far better behaved at its poles than its poles suggest.\n- **Derivative**: `d/dx acoth x = 1/(1 - x^2)`, which is negative on the whole domain (so `acoth`\n is decreasing on each branch) and finite everywhere except at the excluded endpoints.\n- **Complex continuation**: the branch cut is the closed interval `[-1, 1]` — exactly the excluded\n real domain. `ATANH`'s cuts are the two outer rays. The two functions have complementary cuts,\n which is the precise statement of the complementary-domain observation above.\n\nAbramowitz & Stegun give the closed form in chapter 4 section 4.6; Kahan's branch-cut paper is the\nstandard treatment of why the cut sits where it does.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `number` | The hyperbolic cotangent of the value you want. Required. | — |\n\nThat description is Microsoft's, from the Learn reference: \"the hyperbolic cotangent of the angle\nthat you want\".\n\n" }, "signature": { "display": "ACOTH(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": "Inverse of the hyperbolic cotangent", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the hyperbolic arccotangent of a number", "microsoft_url": "https://support.microsoft.com/en-us/office/acoth-function-cc49480f-f684-4171-9fc5-73e4e852300f" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "ACOTH" }, { "locale": "bg-BG", "name": "ACOTH" }, { "locale": "cs-CZ", "name": "ACOTH" }, { "locale": "da-DK", "name": "ARCCOTH" }, { "locale": "de-DE", "name": "ACOTH" }, { "locale": "el-GR", "name": "ACOTH" }, { "locale": "en-AU", "name": "ACOTH" }, { "locale": "en-GB", "name": "ACOTH" }, { "locale": "en-US", "name": "ACOTH" }, { "locale": "es-ES", "name": "ACOTH" }, { "locale": "et-EE", "name": "ACOTH" }, { "locale": "fi-FI", "name": "ACOTH" }, { "locale": "fr-FR", "name": "ACOTH" }, { "locale": "he-IL", "name": "ACOTH" }, { "locale": "hr-HR", "name": "ACOTH" }, { "locale": "hu-HU", "name": "ARCCOTH" }, { "locale": "id-ID", "name": "ACOTH" }, { "locale": "it-IT", "name": "ACOTH" }, { "locale": "ja-JP", "name": "ACOTH" }, { "locale": "ko-KR", "name": "ACOTH" }, { "locale": "lt-LT", "name": "ACOTH" }, { "locale": "lv-LV", "name": "ACOTH" }, { "locale": "nb-NO", "name": "ACOTH" }, { "locale": "nl-NL", "name": "ACOTH" }, { "locale": "pl-PL", "name": "ACOTH" }, { "locale": "pt-BR", "name": "ACOTH" }, { "locale": "pt-PT", "name": "ACOTH" }, { "locale": "ro-RO", "name": "ACOTH" }, { "locale": "ru-RU", "name": "ACOTH" }, { "locale": "sk-SK", "name": "ACOTH" }, { "locale": "sl-SI", "name": "ACOTH" }, { "locale": "sr-Latn-RS", "name": "ACOTH" }, { "locale": "sv-SE", "name": "ARCCOTH" }, { "locale": "th-TH", "name": "ACOTH" }, { "locale": "tr-TR", "name": "ACOTH" }, { "locale": "uk-UA", "name": "ACOTH" }, { "locale": "vi-VN", "name": "ACOTH" }, { "locale": "zh-CN", "name": "ACOTH" }, { "locale": "zh-HK", "name": "ACOTH" }, { "locale": "zh-TW", "name": "ACOTH" } ], "signature": { "display": "ACOTH(number)", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "ACOTH", "version_marker": null, "xlcall": { "code": "549", "symbol": "xlfAcoth" } }, "microsoft": "https://support.microsoft.com/en-us/office/acoth-function-cc49480f-f684-4171-9fc5-73e4e852300f" }, "try_it": { "formula": "=ACOTH(2)" }, "url": "https://handbook.dnacalc.com/functions/ACOTH.html", "variants": [], "versions": [ { "behaviour": "26 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.ACOTH.json" ] }, { "behaviour": "56 captured inputs are indexed for this environment. Capture dates: 2026-07-12 to 2026-07-12. 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.ACOTH.json" ] }, { "behaviour": "239,774 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.ACOTH.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.ACOTH.json" ] } ] }