{ "category": "Math and trigonometry functions", "display_name": "ATAN", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.ATAN", "implementation_state": { "answer_bank": { "excel_builds": [ "20430" ], "larger_numeric": 0, "last_bit": 0, "matched": 181409, "other_mismatch": 0, "refused": 0, "rows": 181409, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 181,409 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 181,412 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#L51-L53", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/atan.rs#L3-L5" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/math::raw", "ported/excel_numeric::atan_with", "ported/excel_numeric::atan_reduced_with", "ported/excel_numeric::excel_atan_reduced", "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" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L51-L53", "state": "matches", "suite": null, "summary": "Matches all 181,412 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ATAN.json", "name": "ATAN", "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- **`ATAN2`** — the four-quadrant version, and the one you usually want. Note Excel's unusual\n argument order: `ATAN2(x_num, y_num)` takes **x first**, the reverse of the C convention. See\n that page.\n- **`TAN`** — the forward function. `TAN(ATAN(x)) = x` to rounding for every `x`;\n `ATAN(TAN(t))` folds `t` into `(-pi/2, pi/2)`.\n- **`ACOT`** — `ACOT(x) = PI()/2 - ATAN(x)` on Excel's documented continuous branch. That identity\n is exact mathematics and a numerically poor program for large `x`; the `ACOT` page is where that\n is worked out.\n- **`ASIN`** and **`ACOS`** — both expressible through `ATAN`, and both harder, because they carry\n a domain restriction and an endpoint singularity that `ATAN` does not.\n- **`ATANH`** — the hyperbolic namesake, and structurally the opposite: bounded domain `(-1, 1)`,\n unbounded range, poles at the ends. `ATAN` is bounded in range and unbounded in domain. The pair\n is a good illustration that a hyperbolic namesake inverts the geometry.\n- **`DEGREES`** — the usual consumer of the result.\n- **`PI`** — the reduction constants, and the reason a two-part split constant appears in the\n numerical notes.\n- **Confused with**: `1/TAN(x)`, which is `COT`; and with `ATAN2`, when the quadrant matters.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n`ATAN` is the easy one, and the reason is structural: the derivative is bounded by 1, so the\nfunction never amplifies an input error, and the range is bounded, so the answer is never so small\nthat relative accuracy becomes precarious — except near zero, where the function is the identity\nand therefore trivially accurate. There is no cancellation anywhere and no overflow anywhere.\n\nThe whole implementation problem is **approximation efficiency**, not stability.\n\n**The Gregory series is unusable directly.** Its convergence rate is governed by `|x|`, and at\n`|x| = 1` it needs a prohibitive number of terms. So every implementation reduces first.\n\n**The two reductions, both from the identities above:**\n\n1. **Reciprocal reduction**, for `|x| > 1`:\n `atan(x) = sign(x) * pi/2 - atan(1/x)`.\n This maps the whole outer half of the domain onto `[-1, 1]`. The subtraction here is safe\n because the answer is near `±pi/2`, not near zero — the exact opposite of the `ACOT` situation.\n2. **Addition-formula reduction**, for the remaining `[0, 1]`:\n split at `tan(pi/12) = 2 - sqrt(3)` and `tan(pi/6)`, and for arguments above the split use\n `atan(x) = pi/6 + atan((x*sqrt(3) - 1)/(x + sqrt(3)))`\n or its `pi/4` analogue. Each application shrinks the working interval, so a short polynomial\n suffices. Cody & Waite give the classical four-interval version; `fdlibm`'s `s_atan.c` is the\n published implementation.\n\n**The split-constant technique.** The reductions add `pi/2`, `pi/4` or `pi/6` at the end. Each of\nthose is irrational and its double approximation carries an error of about `2^-53` relative — which\nis comparable to the final rounding of the answer and would therefore dominate the error budget.\nThe standard fix is to store the constant as an exact-plus-tail pair, `c = c_hi + c_lo`, with\n`c_hi` having trailing zero bits so that additions involving it are exact, and to add `c_lo` last.\nThis is the same device that makes trigonometric argument reduction work, and it is the reason\nimplementations of `ATAN` contain two constants where the mathematics has one.\n\n**Where implementations differ.** Since there is no instability, differences between\nimplementations of `ATAN` are last-bit differences arising from the polynomial coefficients, the\nplacement of the interval boundaries, and whether intermediate arithmetic happened in extended\nprecision. Those are exactly the kinds of difference that identification work in this Handbook's\nupstream record has found elsewhere in the elementary set, and they are invisible to any test that\ncompares to fewer than about sixteen digits.\n\n**Symmetry.** `atan` is odd, so an implementation should fold the sign and get exact antisymmetry.\n`ATAN(x) + ATAN(-x)` being exactly zero is a cheap and complete test of that.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number` — an angle in radians, strictly between `-pi/2` and `pi/2`.\n\n- **Zero** returns zero; an odd implementation preserves the sign of zero.\n- **Subnormals and very small arguments** pass through unchanged, since `atan x = x` to within\n rounding there.\n- **`ATAN(1)`** is `pi/4` and **`ATAN(-1)`** is `-pi/4`; these are the reduction anchors and are\n worth checking in any implementation.\n- **Very large arguments** approach `pi/2`. Because the range is open, no argument should return\n exactly the double nearest `pi/2`... except that, in binary64, the correctly rounded value of\n `atan(x)` *is* that double for all sufficiently large `x`. The mathematical openness of the range\n and the representable range therefore disagree: the function saturates. That is not a defect, it\n is what rounding to a finite grid means, but it is worth stating because it is what makes `ACOT`\n built as `pi/2 - ATAN(x)` fail — see the [ACOT](FUNC.ACOT.md) page.\n- **The largest finite double** returns the double nearest `pi/2`.\n- **Arrays** lift elementwise.\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\nThere is no domain error and no overflow error. `ATAN` is one of the very few surfaces in this\ncategory whose only failures are conversion failures — which is a consequence of a bounded range\nover an unrestricted domain.\n\n\n", "sources": "- Abramowitz & Stegun, *Handbook of Mathematical Functions*, chapter 4 section 4.4 — the\n arctangent: principal range, series, addition formula and continued fraction.\n- Cody & Waite, *Software Manual for the Elementary Functions*, chapter on `ATAN` — the classical\n interval reduction and the split constants.\n- `fdlibm` `s_atan.c` — the published reference implementation.\n- Muller, *Elementary Functions: Algorithms and Implementation* — minimax approximation and\n last-bit behaviour.\n- Handbook projections `data/functions/FUNC.ATAN.json` (arity, `NumToNum` kernel signature,\n `real_result_policy` with `arg_domain_guard=none;non_finite=allow`) and\n `data/presence/FUNC.ATAN.json` (implementing module; no discrepancy, math-deviation or defect\n entries).\n- Handbook [Coercion and lifting](../model/02-coercion-and-lifting.md); related pages\n [ATAN2](FUNC.ATAN2.md) and [ACOT](FUNC.ACOT.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 | 43 |\n| 20430 | Windows, 64-bit, CPU not recorded | 181,409 |\n\n- XC-ATAN-001: build 19929 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.ATAN.json).", "what-it-does": "\n`ATAN(number)` is the principal inverse tangent: the angle in radians whose tangent is *number*.\n\n atan: R -> (-pi/2, pi/2), tan(atan x) = x\n\n- **Domain**: all real numbers. `tan` maps each open interval `(k*pi - pi/2, k*pi + pi/2)` onto the\n whole real line, so the inverse needs a branch choice but no domain restriction.\n- **Range**: the *open* interval `(-pi/2, pi/2)`. The endpoints are approached and never attained;\n `atan(x) -> ±pi/2` only in the limit.\n- **Parity**: odd, exactly. `atan(-x) = -atan(x)`.\n- **Monotonicity**: strictly increasing on the whole line, and bounded — one of the few elementary\n functions that is both.\n- **Derivative**: `d/dx atan x = 1/(1 + x^2)`. Bounded by 1, never zero, smooth everywhere.\n `ATAN` has no singularities, no poles, no branch points on the real line, and no domain edge.\n It is the best-conditioned of the inverse circular functions and that is why it is the one\n everything else is built from.\n- **Series about zero**: `atan x = x - x^3/3 + x^5/5 - x^7/7 + ...` for `|x| <= 1` (the Gregory\n series). It converges glacially near `|x| = 1` — at `x = 1` it is the Leibniz series for `pi/4`,\n famous for needing hundreds of terms per digit — which is why no implementation uses it without\n reduction.\n- **Asymptotics**: `atan x = pi/2 - 1/x + 1/(3x^3) - ...` for large positive `x`.\n- **Key identities**:\n - `atan(x) + atan(1/x) = pi/2` for `x > 0`, and `-pi/2` for `x < 0`. This is the reciprocal\n reduction, and it is what makes large arguments cheap.\n - The addition formula `atan(u) + atan(v) = atan((u+v)/(1-uv))` modulo `pi`, which is the basis\n of every classical range reduction and of the Machin-like formulas for `pi`.\n - `atan(x) = asin(x / sqrt(1 + x^2))`.\n- **Complex continuation**: branch cuts along the imaginary axis outside `[-i, i]` — nothing on the\n real line is cut, which is the exact statement of the unrestricted real domain.\n\nAbramowitz & Stegun cover the arctangent in chapter 4 section 4.4, including the addition formula\nand the continued fraction.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `number` | The tangent of the angle you want. Required. | — |\n\n*The quoted one-line description is Microsoft's text, from its support article .*\n\nThe misunderstood point is the *quadrant*. `ATAN` cannot tell you which quadrant a point is in,\nbecause it receives only a ratio: `ATAN(y/x)` gives the same answer for `(1, 1)` and `(-1, -1)`.\nThat is what `ATAN2` is for, and it is the single most common reason `ATAN` is the wrong function.\n\n\n" }, "signature": { "display": "ATAN(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": "Angle in radians, between -pi/2 and pi/2, whose tangent is the given number", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the arctangent of a number", "microsoft_url": "https://support.microsoft.com/en-us/office/atan-function-50746fa8-630a-406b-81d0-4a2aed395543" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "ATAN" }, { "locale": "bg-BG", "name": "ATAN" }, { "locale": "cs-CZ", "name": "ATAN" }, { "locale": "da-DK", "name": "ARCTAN" }, { "locale": "de-DE", "name": "ARCTAN" }, { "locale": "el-GR", "name": "ATAN" }, { "locale": "en-AU", "name": "ATAN" }, { "locale": "en-GB", "name": "ATAN" }, { "locale": "en-US", "name": "ATAN" }, { "locale": "es-ES", "name": "ATAN" }, { "locale": "et-EE", "name": "ATAN" }, { "locale": "fi-FI", "name": "ATAN" }, { "locale": "fr-FR", "name": "ATAN" }, { "locale": "he-IL", "name": "ATAN" }, { "locale": "hr-HR", "name": "ATAN" }, { "locale": "hu-HU", "name": "ARCTAN" }, { "locale": "id-ID", "name": "ATAN" }, { "locale": "it-IT", "name": "ARCTAN" }, { "locale": "ja-JP", "name": "ATAN" }, { "locale": "ko-KR", "name": "ATAN" }, { "locale": "lt-LT", "name": "ATAN" }, { "locale": "lv-LV", "name": "ATAN" }, { "locale": "nb-NO", "name": "ATAN" }, { "locale": "nl-NL", "name": "BOOGTAN" }, { "locale": "pl-PL", "name": "ATAN" }, { "locale": "pt-BR", "name": "ATAN" }, { "locale": "pt-PT", "name": "ATAN" }, { "locale": "ro-RO", "name": "ATAN" }, { "locale": "ru-RU", "name": "ATAN" }, { "locale": "sk-SK", "name": "ATAN" }, { "locale": "sl-SI", "name": "ATAN" }, { "locale": "sr-Latn-RS", "name": "ATAN" }, { "locale": "sv-SE", "name": "ATAN" }, { "locale": "th-TH", "name": "ATAN" }, { "locale": "tr-TR", "name": "ATAN" }, { "locale": "uk-UA", "name": "ATAN" }, { "locale": "vi-VN", "name": "ATAN" }, { "locale": "zh-CN", "name": "ATAN" }, { "locale": "zh-HK", "name": "ATAN" }, { "locale": "zh-TW", "name": "ATAN" } ], "signature": { "display": "ATAN(number)", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "ATAN", "version_marker": null, "xlcall": { "code": "18", "symbol": "xlfAtan" } }, "microsoft": "https://support.microsoft.com/en-us/office/atan-function-50746fa8-630a-406b-81d0-4a2aed395543" }, "try_it": { "formula": "=ATAN(1)" }, "url": "https://handbook.dnacalc.com/functions/ATAN.html", "variants": [], "versions": [ { "behaviour": "43 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.ATAN.json" ] }, { "behaviour": "181,409 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.ATAN.json" ] } ] }