{ "category": "Math and trigonometry functions", "display_name": "TANH", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.TANH", "implementation_state": { "answer_bank": { "excel_builds": [ "20430" ], "larger_numeric": 0, "last_bit": 58, "matched": 38970, "other_mismatch": 0, "refused": 0, "rows": 39028, "unread": 0, "worst_ulp": 1 }, "detail": "Everything else matches (39,028 in the answer bank and 3 workbook cells). Last-bit means a finite number within 16 ULP of Excel's.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "close", "state_label": "Close: last-bit deviations remain", "summary": "Close: 58 of 39,031 recorded answers differ in the last bits, worst 1 ULP", "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#L81-L83" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/math::raw", "ported/cosh::cosh_kernel", "ported/excel_numeric::binary_with", "ported/excel_numeric::excel_expm1_internal", "ported/excel_numeric::expm1_internal_graph", "ported/excel_numeric::excel_x87_add", "ported/excel_numeric::excel_x87_sub", "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::sub", "ported/excel_numeric/x87::div", "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", "ported/sinh::sinh_kernel", "ported/tanh::tanh_kernel" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L81-L83", "state": "close", "suite": null, "summary": "Close: 58 of 39,031 recorded answers differ in the last bits, worst 1 ULP" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.TANH.json", "name": "TANH", "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- **`SINH` and `COSH`** — the numerator and denominator of the defining quotient. Note that\n `TANH` is well behaved precisely where `SINH` overflows: the two exponentials that overflow\n individually cancel in the ratio.\n- **`ATANH`** — the inverse, `ATANH(y) = ln((1+y)/(1-y))/2`, with domain `(-1, 1)` and poles at\n both endpoints. The saturation of `TANH` and the singularity of `ATANH` are the same fact seen\n from two sides: once `TANH` has rounded to `1`, the round trip through `ATANH` is lost.\n- **`TAN`** — the circular sibling, `tanh x = -i tan(ix)`. Bounded and pole-free versus\n unbounded and pole-ridden.\n- **`SECH`** — `1 - TANH^2`, and the reciprocal of `COSH`.\n- **Confused with**: `TAN`, by name; and `SIGN`, by shape, since `TANH` of a large argument is\n a smooth saturating stand-in for the sign function. That resemblance is the reason `TANH` is\n the classical neural-network activation.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n`TANH` is the well-conditioned member of its family, but there is exactly one way to get it\nbadly wrong and it is the obvious way.\n\n**Do not compute `TANH` as `SINH(x)/COSH(x)`.** Both intermediates overflow at a moderate\nargument while their ratio remains a perfectly ordinary number near `1`. A naive quotient\nproduces `#NUM!`, an infinity, or a NaN — depending on the host's overflow policy — for\narguments where the answer is simply `1`. The same objection applies to\n`(exp(x) - exp(-x))/(exp(x) + exp(-x))`.\n\n**The standard three-band scheme** (Cody & Waite; `fdlibm`'s `tanh`):\n\n1. **Tiny `|x|`**: return `x` (with the inexact flag raised where the platform cares), because\n the correction is below rounding.\n2. **Small to moderate `|x|`**: use `expm1`. With `t = expm1(2|x|)`, `tanh|x| = t/(t + 2)`; or\n with `t = expm1(-2|x|)`, `tanh|x| = -t/(t + 2)`. The `expm1` form is what keeps relative\n accuracy near zero, where the direct exponential quotient would cancel `1` against `1`.\n3. **Large `|x|`**: return `1` (with the sign applied). There is a well-defined threshold above\n which the correctly rounded result is exactly `1`, and computing anything at all beyond it is\n wasted work — and, if done naively, dangerous.\n\n**Near-zero cancellation, stated precisely.** In `(e^x - e^(-x))/(e^x + e^(-x))` the numerator\nsuffers the same total cancellation as in `SINH`: both exponentials tend to `1` and their\ndifference is `2x`. The denominator is fine. So the relative error of the naive form grows\nwithout bound as `x -> 0`, exactly where the function is most linear and a user is most likely\nto trust it. The `expm1` reformulation is not an optimization; it is the difference between a\ncorrect and an incorrect function on a large part of its useful domain.\n\n**Symmetry.** Odd function: compute on `|x|`, apply the sign. An implementation that does so\ngets exact antisymmetry for free.\n\n**Why `TANH` is easy where `TAN` is hard.** There is no argument reduction. There is no `pi`.\nThere is no cancellation in the reduced argument because there is no reduced argument. Every\ndifficulty `TAN` has comes from mapping the input into a fundamental domain, and `TANH` has no\nfundamental domain to map into. This is worth stating because the two functions are usually\ntaught as siblings, and numerically they have almost nothing in common.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`, always in `(-1, 1)` mathematically — and in floating point, exactly `1` or\n`-1` for arguments beyond the saturation point, because `1 - 2e^(-2x)` rounds to `1` once the\ncorrection falls below half an ULP of `1`.\n\nSmall arguments round-trip: for `|x|` small enough that `x^3/3` is negligible, the correctly\nrounded `tanh x` is `x`, so subnormals pass through.\n\n\n\n### Errors\n\n\n| Error | Condition | Source |\n|---|---|---|\n| `#VALUE!` | The argument does not convert to a number | Shared coercion rules |\n| propagated | An error value in the argument is returned unchanged | Shared coercion rules |\n\n", "sources": "\n- Microsoft, \"TANH function\" —\n \n (signature and the defining formula). **Retrieval for this page was blocked by the upstream\n host; the documented behaviour above is stated as documented behaviour and should be\n re-checked against the article.**\n- Abramowitz & Stegun, *Handbook of Mathematical Functions*, chapter 4 section 4.5 — hyperbolic\n functions, series, identities, and the relation to the circular tangent.\n- Cody & Waite, *Software Manual for the Elementary Functions* — the three-band formulation.\n- `fdlibm` `tanh` and `expm1`; Boost.Math hyperbolic documentation.\n- Handbook projections `data/functions/FUNC.TANH.json` (arity, classification,\n `real_result_policy` with `arg_domain_guard=none` and `non_finite=allow`) and\n `data/presence/FUNC.TANH.json`.\n- Handbook [Coercion and lifting](../model/02-coercion-and-lifting.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 | 42 |\n| 20430 | Windows, 64-bit, CPU not recorded | 39,028 |\n\n- XC-TANH-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\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.TANH.json).", "what-it-does": "\n`TANH(number)` is the hyperbolic tangent:\n\n tanh x = sinh x / cosh x = (e^x - e^(-x)) / (e^x + e^(-x)) = (e^(2x) - 1) / (e^(2x) + 1)\n\n- **Domain**: all real numbers. No poles, no branch cuts, no excluded points. `tanh` is\n meromorphic with poles only at odd multiples of `i*pi/2` — nowhere on the real line. This is\n the sharpest contrast with `TAN`, which has a pole every `pi`.\n- **Range**: the open interval `(-1, 1)`. Strictly increasing, hence a bijection from `R` onto\n `(-1, 1)`, which is why `ATANH` has domain `(-1, 1)` and blows up at both ends.\n- **Parity**: odd.\n- **Asymptotes**: `tanh x -> +1` as `x -> +infinity` and `-> -1` as `x -> -infinity`, and the\n approach is exponential: `1 - tanh x ~ 2 e^(-2x)`.\n- **Series about zero**: `tanh x = x - x^3/3 + 2 x^5/15 - 17 x^7/315 + ...`, radius of\n convergence `pi/2` (the distance to the nearest complex pole). The coefficients are those of\n `tan` with alternating signs, which is the series form of `tanh x = -i tan(ix)`.\n- **Identity**: `1 - tanh^2 x = sech^2 x`, the hyperbolic counterpart of the derivative relation\n for `tan`.\n\nMicrosoft's article gives the signature and states the defining formula. **Retrieval of that\npage for this entry was blocked by the upstream host (HTTP 403), so the documented content is\nstated here as documented behaviour and should be re-checked against the live article.** The\nmathematics above is from the standard literature, not from the article.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `number` | Any real number. Required. | — |\n\nNo units. `TANH` is not an angle function and nothing in the `RADIANS`/`DEGREES` apparatus\napplies to it.\n\n\n" }, "signature": { "display": "TANH(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": "Hyperbolic tangent", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the hyperbolic tangent of a number", "microsoft_url": "https://support.microsoft.com/en-us/office/tanh-function-017222f0-a0c3-4f69-9787-b3202295dc6c" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "TANH" }, { "locale": "bg-BG", "name": "TANH" }, { "locale": "cs-CZ", "name": "TGH" }, { "locale": "da-DK", "name": "TANH" }, { "locale": "de-DE", "name": "TANH" }, { "locale": "el-GR", "name": "TANH" }, { "locale": "en-AU", "name": "TANH" }, { "locale": "en-GB", "name": "TANH" }, { "locale": "en-US", "name": "TANH" }, { "locale": "es-ES", "name": "TANH" }, { "locale": "et-EE", "name": "TANH" }, { "locale": "fi-FI", "name": "TANH" }, { "locale": "fr-FR", "name": "TANH*" }, { "locale": "he-IL", "name": "TANH" }, { "locale": "hr-HR", "name": "TANH" }, { "locale": "hu-HU", "name": "TANH" }, { "locale": "id-ID", "name": "TANH" }, { "locale": "it-IT", "name": "TANH" }, { "locale": "ja-JP", "name": "TANH" }, { "locale": "ko-KR", "name": "TANH" }, { "locale": "lt-LT", "name": "TANH" }, { "locale": "lv-LV", "name": "TANH" }, { "locale": "nb-NO", "name": "TANH" }, { "locale": "nl-NL", "name": "TANH" }, { "locale": "pl-PL", "name": "TANH" }, { "locale": "pt-BR", "name": "TANH" }, { "locale": "pt-PT", "name": "TANH" }, { "locale": "ro-RO", "name": "TANH" }, { "locale": "ru-RU", "name": "TANH" }, { "locale": "sk-SK", "name": "TANH" }, { "locale": "sl-SI", "name": "TANH" }, { "locale": "sr-Latn-RS", "name": "TANH" }, { "locale": "sv-SE", "name": "TANH" }, { "locale": "th-TH", "name": "TANH" }, { "locale": "tr-TR", "name": "TANH Denklemi" }, { "locale": "uk-UA", "name": "TANH" }, { "locale": "vi-VN", "name": "TANH" }, { "locale": "zh-CN", "name": "TANH" }, { "locale": "zh-HK", "name": "TANH" }, { "locale": "zh-TW", "name": "TANH" } ], "signature": { "display": "TANH(number)", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "TANH", "version_marker": null, "xlcall": { "code": "231", "symbol": "xlfTanh" } }, "microsoft": "https://support.microsoft.com/en-us/office/tanh-function-017222f0-a0c3-4f69-9787-b3202295dc6c" }, "try_it": { "formula": "=TANH(1)" }, "url": "https://handbook.dnacalc.com/functions/TANH.html", "variants": [], "versions": [ { "behaviour": "42 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.TANH.json" ] }, { "behaviour": "39,028 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.TANH.json" ] } ] }