{ "category": "Math and trigonometry functions", "display_name": "ATANH", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.ATANH", "implementation_state": { "answer_bank": { "excel_builds": [ "20131", "20228", "20430" ], "larger_numeric": 0, "last_bit": 0, "matched": 22008, "other_mismatch": 0, "refused": 0, "rows": 22008, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 22,008 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 22,011 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#L57-L59", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/atanh.rs#L8-L35" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "ported/excel_numeric::binary_with", "ported/excel_numeric::excel_x87_add", "ported/excel_numeric::excel_x87_sub", "ported/excel_numeric::excel_x87_div", "ported/excel_numeric/x87::add", "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#L57-L59", "state": "matches", "suite": null, "summary": "Matches all 22,011 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ATANH.json", "name": "ATANH", "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- **`TANH`** — the forward function. `ATANH(TANH(t)) = t` for every real `t`, the cleanest round\n trip in the family, and the best oracle-free test on this page.\n- **`FISHER`** — the same formula under a statistical name. `FISHER(r)` and `ATANH(r)` should be\n identical; if they are not, one of them is a separate implementation and that is worth knowing.\n `FISHERINV` is `TANH`.\n- **`ACOTH`** — the complementary-domain partner, `atanh(x) = acoth(1/x)`. Upstream identification\n work treats the two together, and both carry evidence records here.\n- **`ACOSH`** — the third inverse hyperbolic primary. Between `ATANH` on `(-1,1)`, `ACOSH` on\n `[1,infinity)` and `ASINH` on `R`, the family covers the line several times over with different\n shapes.\n- **`ATAN`** — the circular namesake, and structurally the inverse arrangement: `ATAN` has an\n unbounded domain and a bounded range, `ATANH` a bounded domain and an unbounded range.\n- **`CORREL`, `PEARSON`, `RSQ`** — the producers of the arguments that make this function\n statistically interesting.\n- **`LN`** — the substrate of the closed form.\n- **Confused with**: `ATAN`, by name; and with `1/TANH`, which is `COTH`.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n`ATANH`'s hazard is at the *origin*, not at the poles — the opposite of what the graph suggests,\nand the same inversion seen on the `ACOTH` page.\n\n**The small-argument failure.** Evaluate `(1/2) ln((1+x)/(1-x))` for small `x`. The ratio is close\nto `1`, and the answer — which is close to `x` — lives entirely in the digits that the division has\njust rounded away. Concretely: once `|x|` falls below about `2^-53`, the doubles `1+x` and `1-x` are\nboth exactly `1`, the ratio is exactly `1`, its logarithm is exactly `0`, and the naive form returns\nzero for an argument whose `atanh` is the argument itself. The collapse is complete, and it starts\ndegrading long before it becomes total.\n\nThis is why the subnormal pass-through is a *diagnostic*: an implementation that returns the input\nunchanged for a subnormal argument is not using the naive ratio there, and one that returns zero\nis.\n\n**The remedies**, both standard:\n\n1. **`log1p` on a rearranged argument.** `atanh(x) = (1/2) * log1p( 2x / (1 - x) )`. Nothing near\n `1` is formed and nothing is subtracted from `1` except `x`, which is exact. `fdlibm`'s\n `e_atanh.c` uses this form.\n2. **The `log1p` difference.** `atanh(x) = (1/2) * ( log1p(x) - log1p(-x) )`. Symmetric, and it\n makes the oddness manifest — the two terms swap under `x -> -x`, so the result negates exactly.\n3. **The series** for very small `|x|`: `x + x^3/3`, truncated as soon as the cubic term falls below\n the rounding of `x`. Below a threshold, `x` itself is correctly rounded.\n\nHigham's discussion of `log(1+x)` is the standard statement of why the `log1p` primitive exists.\nExcel does not expose `log1p` as a worksheet function, which is why a worksheet-level workaround is\nawkward and why an implementer of this surface must supply it internally.\n\n**Near the poles the naive form is fine.** `(1+x)/(1-x)` is large there, `ln` of a large number is\nwell conditioned, and `1 - x` is exact for doubles near `1` by Sterbenz's lemma. So the correct\nbranch structure is: **naive ratio-log in the outer band, `log1p` form near zero** — the reverse of\nthe intuitive ordering, exactly as for `ACOTH`.\n\n**What is on record upstream.** `EV-MATH-0005` is a **substrate-identification** record for this\nsurface. The identification it carries is a piecewise shape of that kind: a direct ratio-logarithm\nover the main band including the near-pole rows, and a small-argument logarithm-of-one-plus pair\nbelow a threshold, with the threshold placed inside a gap between the two regions' clean bands and\nwith residual rows still open in the switch band itself. The record publishes a per-surface count\nand names the open rows; **its figures are rendered mechanically beside this page and are not\nrestated in this prose**, and its own status text is the authority on what the count does and does\nnot establish. The Handbook publishes it as an upstream identification — a hypothesis with\nsupporting evidence and open residuals — not as a settled fact about Excel.\n\n**The oddness question, which is genuinely open.** The upstream production note for this surface\nstates that the *signed* ratio is evaluated directly rather than by computing on `|x|` and\nrestoring the sign, with the consequence that the negative argument rounds independently and exact\noddness is not guaranteed by construction. A retained test in the same module asserts exact odd\nsymmetry at a specific near-pole witness. Those two statements are not formally contradictory — a\nnon-odd-by-construction implementation can still be odd at particular points — but together they\nleave the general question unresolved, and the Handbook records it as unresolved rather than\npicking a side. It matters: `FISHER`'s statistical use assumes `atanh(-r) = -atanh(r)`, and a\none-ulp asymmetry there is a real, if small, defect.\n\n**Why switch placement dominates.** As with `ACOTH`, two forms that are each individually excellent\nwill disagree in the last bits over the band between their switch points. An implementation that\nplaces its threshold differently from Excel's will differ from Excel on every argument in the gap.\nThat is why identification work here concentrates on locating switches rather than on improving\naccuracy, and it is why the residual rows recorded upstream cluster in exactly that band.\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. These are the poles; there is no value.\n- **Just inside the endpoints** the answer is finite and modest. There is no overflow in this\n function at all, which is worth stating because a function with poles usually has one.\n- **Zero** returns zero, and the sign of zero should survive an odd implementation.\n- **Subnormals and very small arguments** pass through unchanged: `atanh(x) = x` to within rounding.\n This is not automatic — it is *emergent* from the correct small-argument branch and *destroyed*\n by the naive one, which is precisely what makes it a diagnostic. See the numerical notes.\n- **Anything with `|x| >= 1`**, including large magnitudes and anything a text conversion is likely\n to produce, is a domain failure.\n- **Arrays** lift elementwise, with element-local errors on out-of-domain elements.\n\n", "sources": "- Microsoft Learn, \"WorksheetFunction.Atanh method (Excel)\" —\n (retrieved: the\n description, the open `(-1, 1)` domain, and the round trip; **no error code is named there**).\n- Abramowitz & Stegun, *Handbook of Mathematical Functions*, chapter 4 section 4.6 — the closed\n form, series and poles.\n- `fdlibm` `e_atanh.c` — the published `log1p`-based reference implementation.\n- Higham, *Accuracy and Stability of Numerical Algorithms*, chapter 1 — the `log(1+x)` problem.\n- Fisher (1921) — the z-transform, and the reason this surface is also a statistics function.\n- Handbook evidence record `EV-MATH-0005` (subject `FUNC.ATANH`) — a substrate-identification\n record with a per-surface count, an identified piecewise form, and open rows in the switch band.\n- Handbook projections `data/functions/FUNC.ATANH.json` and `data/presence/FUNC.ATANH.json`\n (implementing module; discrepancy and math-deviation catalogue entries; the `BUG-FUNC-027`\n scalar-invocation sweep).\n- Handbook [Coercion and lifting](../model/02-coercion-and-lifting.md); sibling page\n [ACOTH](FUNC.ACOTH.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 | 21 |\n| 20131 | Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics | 350 |\n| 20228 | Windows, 64-bit, CPU not recorded | 20,436 |\n| 20430 | Windows, 64-bit, CPU not recorded | 1,224 |\n\n- XC-ATANH-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-ATANH-002: 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-ATANH-003: build 20131 versus build 20228; 6 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-ATANH-004: build 20131 versus build 20430; 3 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-ATANH-005: build 20228 versus build 20430; 2 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.ATANH.json).", "what-it-does": "\n`ATANH(number)` is the inverse hyperbolic tangent.\n\n atanh x = (1/2) * ln( (1 + x) / (1 - x) ), -1 < x < 1\n\n- **Domain**: the *open* interval `(-1, 1)`. `tanh` maps `R` bijectively onto `(-1, 1)`, so the\n inverse is defined exactly there and needs no branch choice. Microsoft's Learn reference states\n the domain as \"between -1 and 1 (excluding -1 and 1)\".\n- **Range**: all real numbers.\n- **Parity**: odd, exactly, as mathematics. `atanh(-x) = -atanh(x)`. Whether an *implementation*\n preserves that to the last bit is a separate question, and on this surface it is a live one — see the\n numerical notes.\n- **Monotonicity**: strictly increasing on the whole domain.\n- **Poles**: logarithmic singularities at both endpoints. `atanh(x) -> +infinity` as `x -> 1-` and\n `-> -infinity` as `x -> -1+`. The growth is slow: even one ulp inside an endpoint the value is\n only around 18.4, so *nothing overflows anywhere in this function*. The poles are real and\n numerically harmless.\n- **Derivative**: `d/dx atanh x = 1/(1 - x^2)`, which is at least 1 everywhere and unbounded at the\n endpoints.\n- **Series about zero**: `atanh x = x + x^3/3 + x^5/5 + x^7/7 + ...` for `|x| < 1`. For small `x`,\n `atanh x -> x`, so subnormals pass through unchanged.\n- **Near the poles**: with `x = 1 - t`, `atanh(1 - t) = (1/2) ln(2/t) + O(t)`.\n- **Relations**: `atanh x = acoth(1/x)` (complementary domain — see [ACOTH](FUNC.ACOTH.md));\n `atanh x = asinh( x / sqrt(1 - x^2) )`; and `atanh(tanh t) = t` for every real `t`, which is the\n round trip Microsoft's Learn reference states.\n- **Complex continuation**: branch cuts along `(-infinity, -1]` and `[1, +infinity)` — the exact\n complement of the real domain, and the mirror image of `ACOTH`'s cut.\n\nAbramowitz & Stegun give the closed form in chapter 4 section 4.6.\n\n### Why this function matters beyond hyperbolic geometry\n\n`ATANH` is **Fisher's z-transform**. For a sample correlation coefficient `r`, `z = atanh(r)` is\napproximately normally distributed with variance `1/(n-3)` — the variance-stabilising transform\nFisher introduced in 1921, and the standard route to a confidence interval for a correlation.\nExcel exposes it twice: as `ATANH`, and as `FISHER`, whose entire content is the same formula.\nThat makes `ATANH` a statistics function wearing a hyperbolic name, and it means its accuracy near\n`|x| = 1` has consequences for confidence intervals on strong correlations.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `number` | Any real number strictly between -1 and 1. Required. | — |\n\nMicrosoft's Learn reference gives both the description and the constraint: the number must be\nbetween -1 and 1, excluding the endpoints.\n\nThe misunderstood position is the openness of the interval. Readers who arrive with a correlation\ncoefficient of exactly `1` — which happens whenever a column is regressed against itself — get an\nerror, and that error is mathematically correct: the transform of a perfect correlation is\ninfinite.\n\n\n" }, "signature": { "display": "ATANH(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 tangent", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the inverse hyperbolic tangent of a number", "microsoft_url": "https://support.microsoft.com/en-us/office/atanh-function-3cd65768-0de7-4f1d-b312-d01c8c930d90" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "ATANH" }, { "locale": "bg-BG", "name": "ATANH" }, { "locale": "cs-CZ", "name": "ARCTGH" }, { "locale": "da-DK", "name": "ARCTANH" }, { "locale": "de-DE", "name": "ATANH" }, { "locale": "el-GR", "name": "ATANH" }, { "locale": "en-AU", "name": "ATANH" }, { "locale": "en-GB", "name": "ATANH" }, { "locale": "en-US", "name": "ATANH" }, { "locale": "es-ES", "name": "ATANH" }, { "locale": "et-EE", "name": "ATANH" }, { "locale": "fi-FI", "name": "ATANH" }, { "locale": "fr-FR", "name": "ATANH*" }, { "locale": "he-IL", "name": "ATANH" }, { "locale": "hr-HR", "name": "ATANH" }, { "locale": "hu-HU", "name": "ATANH" }, { "locale": "id-ID", "name": "ATANH" }, { "locale": "it-IT", "name": "ATANH" }, { "locale": "ja-JP", "name": "ATANH" }, { "locale": "ko-KR", "name": "ATANH" }, { "locale": "lt-LT", "name": "ATANH" }, { "locale": "lv-LV", "name": "ATANH" }, { "locale": "nb-NO", "name": "ATANH" }, { "locale": "nl-NL", "name": "ATANH" }, { "locale": "pl-PL", "name": "ATANH" }, { "locale": "pt-BR", "name": "ATANH" }, { "locale": "pt-PT", "name": "ATANH" }, { "locale": "ro-RO", "name": "ATANH" }, { "locale": "ru-RU", "name": "ATANH" }, { "locale": "sk-SK", "name": "ATANH" }, { "locale": "sl-SI", "name": "ATANH" }, { "locale": "sr-Latn-RS", "name": "ATANH" }, { "locale": "sv-SE", "name": "ARCTANH" }, { "locale": "th-TH", "name": "ATANH" }, { "locale": "tr-TR", "name": "ATANH işlevi" }, { "locale": "uk-UA", "name": "ATANH" }, { "locale": "vi-VN", "name": "ATANH" }, { "locale": "zh-CN", "name": "ATANH" }, { "locale": "zh-HK", "name": "ATANH" }, { "locale": "zh-TW", "name": "ATANH" } ], "signature": { "display": "ATANH(number)", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "ATANH", "version_marker": null, "xlcall": { "code": "234", "symbol": "xlfAtanh" } }, "microsoft": "https://support.microsoft.com/en-us/office/atanh-function-3cd65768-0de7-4f1d-b312-d01c8c930d90" }, "try_it": { "formula": "=ATANH(0.5)" }, "url": "https://handbook.dnacalc.com/functions/ATANH.html", "variants": [], "versions": [ { "behaviour": "21 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.ATANH.json" ] }, { "behaviour": "350 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.ATANH.json" ] }, { "behaviour": "20,436 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.ATANH.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.ATANH.json" ] } ] }