runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/atan.js

@@ -0,0 +1,174 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "atan",
+    "category": "math/trigonometry",
+    "keywords": [
+        "atan",
+        "arctangent",
+        "inverse tangent",
+        "trigonometry",
+        "gpu"
+    ],
+    "summary": "Element-wise inverse tangent matching MATLAB semantics for real, logical, character, and complex inputs with GPU fallbacks.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses the provider's unary_atan hook when available; otherwise gathers to the host to stay MATLAB-compatible."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::trigonometry::atan::tests",
+        "integration": "builtins::math::trigonometry::atan::tests::atan_gpu_provider_roundtrip"
+    },
+    "description": "`Y = atan(X)` computes the inverse tangent (in radians) of every element of `X`. The operation runs element-wise, supports real and complex numbers, and honors MATLAB's broadcasting semantics.",
+    "behaviors": [
+        "Works on scalars, vectors, matrices, and N-D tensors, including logical and integer inputs (which are promoted to double precision before evaluation).",
+        "Character arrays are interpreted as their Unicode code points and return dense double arrays of identical shape.",
+        "Complex inputs follow MATLAB's analytic extension `atan(z) = (1/(2i)) * (log(1 + i z) - log(1 - i z))`, ensuring identical branch behavior and NaN/Inf propagation.",
+        "Returns results in radians for real inputs and complex numbers for complex inputs.",
+        "Empty arrays and already scalar values pass straight through while preserving shape."
+    ],
+    "examples": [
+        {
+            "description": "Arctangent of a scalar",
+            "input": "y = atan(1)",
+            "output": "y = 0.7854"
+        },
+        {
+            "description": "Element-wise arctangent of a vector",
+            "input": "x = linspace(-2, 2, 5);\nangles = atan(x)",
+            "output": "angles = [-1.1071  -0.7854         0    0.7854    1.1071]"
+        },
+        {
+            "description": "Computing inverse tangent of every entry in a matrix",
+            "input": "A = [-2 -1 0; 1 2 3];\nY = atan(A)",
+            "output": "Y =\n   -1.1071   -0.7854         0\n    0.7854    1.1071    1.2490"
+        },
+        {
+            "description": "Evaluating `atan` on a complex number",
+            "input": "z = 1 + 2i;\nw = atan(z)",
+            "output": "w = 1.3390 + 0.4024i"
+        },
+        {
+            "description": "Keeping the result on the GPU with `'like'`",
+            "input": "proto = gpuArray.zeros(1, 1);\nG = gpuArray([-3 -1 0 1 3]);\ndeviceResult = atan(G, 'like', proto);\nresult = gather(deviceResult)",
+            "output": "result =\n   -1.2490   -0.7854         0    0.7854    1.2490"
+        },
+        {
+            "description": "Inspecting character codes via inverse tangent",
+            "input": "codes = atan('RUN')",
+            "output": "codes =\n    1.5586    1.5590    1.5580"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use `atan`?",
+            "answer": "Use `atan` whenever you need the element-wise inverse tangent of data expressed in radians—common in signal processing, control systems, and geometric computations."
+        },
+        {
+            "question": "How is `atan` different from `atan2`?",
+            "answer": "`atan` accepts a single input and returns results in `(-π/2, π/2)`. `atan2(y, x)` takes two inputs, uses the signs of both arguments to determine the correct quadrant, and returns values in `(-π, π]`."
+        },
+        {
+            "question": "Does `atan` support complex numbers?",
+            "answer": "Yes. Results match MATLAB's analytic continuation of the inverse tangent and may return complex values even for real inputs when the computation requires it."
+        },
+        {
+            "question": "Can I keep results on the GPU?",
+            "answer": "Yes. Passing `'like', prototype` with a GPU tensor keeps outputs on-device whenever a provider is registered. When the provider lacks `unary_atan`, RunMat computes on the host and returns host data unless you explicitly request GPU residency via `'like'`."
+        },
+        {
+            "question": "What happens with NaN or Inf inputs?",
+            "answer": "NaNs propagate, and infinities map to the appropriate asymptotic limits (`atan(±Inf) = ±π/2`), matching MATLAB's IEEE behavior."
+        }
+    ],
+    "links": [
+        {
+            "label": "atan2",
+            "url": "./atan2"
+        },
+        {
+            "label": "tan",
+            "url": "./tan"
+        },
+        {
+            "label": "asin",
+            "url": "./asin"
+        },
+        {
+            "label": "acos",
+            "url": "./acos"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "acosh",
+            "url": "./acosh"
+        },
+        {
+            "label": "asinh",
+            "url": "./asinh"
+        },
+        {
+            "label": "atanh",
+            "url": "./atanh"
+        },
+        {
+            "label": "cos",
+            "url": "./cos"
+        },
+        {
+            "label": "cosh",
+            "url": "./cosh"
+        },
+        {
+            "label": "sin",
+            "url": "./sin"
+        },
+        {
+            "label": "sinh",
+            "url": "./sinh"
+        },
+        {
+            "label": "tanh",
+            "url": "./tanh"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/trigonometry/atan.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/trigonometry/atan.rs"
+    },
+    "gpu_residency": "Usually you do **not** need to call `gpuArray`. When a provider exposes `unary_atan`, the runtime keeps data on the GPU automatically. If the hook is missing (or if you supply a host `'like'` prototype), RunMat gathers and computes on the CPU, then honors the requested residency so you do not have to manage transfers manually.",
+    "gpu_behavior": [
+        "When RunMat Accelerate is active and the selected provider implements `unary_atan`, the runtime keeps tensors on the GPU and executes the kernel entirely on-device.",
+        "If the provider lacks `unary_atan` (or declines the request), RunMat gathers the data to the host, computes the result with the reference implementation, and then reapplies residency requests such as `'like'` prototypes automatically.",
+        "Fusion planning groups neighboring elementwise operations so downstream kernels can stay on the GPU even if `atan` itself fell back to the CPU."
+    ],
+    "key": "atan",
+    "slug": "atan",
+    "categoryPath": [
+        "math",
+        "trigonometry"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=atan.js.map

package/dist/generated/builtins/atan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atan.js","sourceRoot":"","sources":["../../../src/generated/builtins/atan.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/atan2.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=atan2.d.ts.map

package/dist/generated/builtins/atan2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atan2.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/atan2.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA2LjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/atan2.js

@@ -0,0 +1,192 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "atan2",
+    "category": "math/trigonometry",
+    "keywords": [
+        "atan2",
+        "inverse tangent",
+        "quadrant aware",
+        "gpu",
+        "arctangent"
+    ],
+    "summary": "Quadrant-aware inverse tangent atan2(y, x) with MATLAB-compatible broadcasting.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/atan2.html"
+    ],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Executes on the GPU when the provider implements elem_atan2 for shape-matched inputs; otherwise the runtime gathers operands and falls back to the host."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::trigonometry::atan2::tests",
+        "integration": "builtins::math::trigonometry::atan2::tests::atan2_gpu_provider_roundtrip",
+        "gpu": "builtins::math::trigonometry::atan2::tests::atan2_wgpu_matches_cpu_elementwise"
+    },
+    "description": "`theta = atan2(y, x)` computes the four-quadrant inverse tangent of the point `(x, y)`. It returns angles in radians covering the range `(-pi, pi]`, giving robust results even when `x` is zero.",
+    "behaviors": [
+        "Inputs can be scalars, vectors, matrices, or N-D tensors of real numeric, logical, or character data. MATLAB-style implicit expansion (broadcasting) applies when shapes are compatible.",
+        "`atan2` treats `y` as the numerator and `x` as the denominator: `atan2(Y, X)` equals `atan(Y ./ X)` but keeps the correct quadrant and handles zero denominators.",
+        "Logical inputs are cast to `double`, character arrays use their Unicode code points, and integer inputs are promoted to `double`, mirroring MATLAB promotion rules.",
+        "Complex inputs are **not** supported; MATLAB raises an error and RunMat matches that behaviour.",
+        "`atan2(0, 0)` returns `0`. `atan2(±0, -0)` follows IEEE-754 semantics, matching MATLAB for signed zeros and infinities.",
+        "`atan2(NaN, x)` or `atan2(y, NaN)` returns `NaN`; inputs containing `Inf` combinations follow IEEE-754 quadrant semantics exactly like MATLAB.",
+        "The output always has double precision and the same size as the broadcasted inputs."
+    ],
+    "examples": [
+        {
+            "description": "Computing the polar angle of a point",
+            "input": "theta = atan2(4, 3)",
+            "output": "theta = 0.9273"
+        },
+        {
+            "description": "Determining quadrants for a vector of coordinates",
+            "input": "Y = [-1 0 1];\nX = [-1 -1 -1];\nangles = atan2(Y, X)",
+            "output": "angles = [-2.3562 3.1416 2.3562]"
+        },
+        {
+            "description": "Broadcasting a scalar denominator across a matrix",
+            "input": "A = [1 2 3; 4 5 6];\nangles = atan2(A, 2)",
+            "output": "angles =\n    0.4636    0.7854    0.9828\n    1.1071    1.1903    1.2490"
+        },
+        {
+            "description": "Handling zero numerators and signed zeros",
+            "input": "theta = atan2([0 -0], [-2 0])",
+            "output": "theta = [pi 0]"
+        },
+        {
+            "description": "Executing `atan2` on the GPU",
+            "input": "Gy = gpuArray([1 1; -1 -1]);\nGx = gpuArray([1 -1; 1 -1]);\nangles_gpu = atan2(Gy, Gx);\nangles = gather(angles_gpu)",
+            "output": "angles =\n    0.7854    2.3562\n   -0.7854   -2.3562"
+        },
+        {
+            "description": "Converting character data to angles",
+            "input": "theta = atan2('A', 100)",
+            "output": "theta = 0.5764"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What is the range of values returned by `atan2`?",
+            "answer": "Angles are given in radians and span the open/closed interval `(-pi, pi]`. Use `rad2deg` if you prefer degrees."
+        },
+        {
+            "question": "Can I supply complex inputs?",
+            "answer": "No. MATLAB raises an error for complex inputs, and so does RunMat. Convert complex data to magnitude/phase first if needed."
+        },
+        {
+            "question": "Does `atan2` preserve the shape of the inputs?",
+            "answer": "Yes. After implicit expansion, the output shape matches the broadcasted size of `Y` and `X`."
+        },
+        {
+            "question": "How are logical or character inputs handled?",
+            "answer": "Logical values map to `0` and `1`, and character arrays use their Unicode code point values (as doubles) before computing the angle."
+        },
+        {
+            "question": "What happens when `x` is zero?",
+            "answer": "`atan2` still returns a finite result using the sign of `y`. For example, `atan2(1, 0)` returns `pi/2`, and `atan2(-1, 0)` returns `-pi/2`."
+        },
+        {
+            "question": "Are GPU and CPU results identical?",
+            "answer": "Double-precision providers match CPU results exactly. Single-precision providers can differ by routine IEEE rounding. RunMat automatically promotes to double when materialising host tensors to mirror MATLAB."
+        },
+        {
+            "question": "How can I compute angles in degrees?",
+            "answer": "Call `rad2deg(atan2(y, x))` or multiply the result by `180/pi`."
+        }
+    ],
+    "links": [
+        {
+            "label": "atan",
+            "url": "./atan"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "sin",
+            "url": "./sin"
+        },
+        {
+            "label": "tan",
+            "url": "./tan"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "acos",
+            "url": "./acos"
+        },
+        {
+            "label": "acosh",
+            "url": "./acosh"
+        },
+        {
+            "label": "asin",
+            "url": "./asin"
+        },
+        {
+            "label": "asinh",
+            "url": "./asinh"
+        },
+        {
+            "label": "atanh",
+            "url": "./atanh"
+        },
+        {
+            "label": "cos",
+            "url": "./cos"
+        },
+        {
+            "label": "cosh",
+            "url": "./cosh"
+        },
+        {
+            "label": "sinh",
+            "url": "./sinh"
+        },
+        {
+            "label": "tanh",
+            "url": "./tanh"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/trigonometry/atan2.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/trigonometry/atan2.rs"
+    },
+    "gpu_residency": "RunMat's planner keeps tensors on the GPU whenever profitable. Explicit `gpuArray` calls are optional—use them only when you need to control residency for interoperability. When `elem_atan2` is unavailable, RunMat automatically gathers data to the CPU, performs the computation, and re-uploads results only when downstream consumers demand GPU residency.",
+    "gpu_behavior": [
+        "When both operands already reside on the GPU and the active provider implements the `elem_atan2` hook, RunMat executes the operation entirely on the device without reformatting buffers.",
+        "If shapes require implicit expansion or the provider lacks `elem_atan2`, RunMat transparently gathers both tensors to the host, computes the result with the reference CPU implementation, and continues execution.",
+        "When GPU work completes in single precision (because the provider only exposes 32-bit buffers), RunMat promotes the results to double precision whenever the data is materialised on the host so the observable behaviour still matches MATLAB.",
+        "Fusion-aware expressions (for example, `sin(atan2(y, x))`) can still emit a combined WGSL kernel; the fusion planner recognises `atan2` as a binary elementwise primitive."
+    ],
+    "key": "atan2",
+    "slug": "atan2",
+    "categoryPath": [
+        "math",
+        "trigonometry"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=atan2.js.map

package/dist/generated/builtins/atan2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atan2.js","sourceRoot":"","sources":["../../../src/generated/builtins/atan2.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,mBAAmB;IAC/B,UAAU,EAAE;QACV,OAAO;QACP,iBAAiB;QACjB,gBAAgB;QAChB,KAAK;QACL,YAAY;KACb;IACD,SAAS,EAAE,iFAAiF;IAC5F,YAAY,EAAE;QACZ,sDAAsD;KACvD;IACD,aAAa,EAAE;QACb,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,QAAQ;QACxB,OAAO,EAAE,0JAA0J;KACpK;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,4CAA4C;QACpD,aAAa,EAAE,0EAA0E;QACzF,KAAK,EAAE,gFAAgF;KACxF;IACD,aAAa,EAAE,mMAAmM;IAClN,WAAW,EAAE;QACX,0LAA0L;QAC1L,mKAAmK;QACnK,qKAAqK;QACrK,iGAAiG;QACjG,yHAAyH;QACzH,gJAAgJ;QAChJ,qFAAqF;KACtF;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,sCAAsC;YACrD,OAAO,EAAE,qBAAqB;YAC9B,QAAQ,EAAE,gBAAgB;SAC3B;QACD;YACE,aAAa,EAAE,mDAAmD;YAClE,OAAO,EAAE,sDAAsD;YAC/D,QAAQ,EAAE,kCAAkC;SAC7C;QACD;YACE,aAAa,EAAE,mDAAmD;YAClE,OAAO,EAAE,2CAA2C;YACpD,QAAQ,EAAE,0EAA0E;SACrF;QACD;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,+BAA+B;YACxC,QAAQ,EAAE,gBAAgB;SAC3B;QACD;YACE,aAAa,EAAE,8BAA8B;YAC7C,OAAO,EAAE,sHAAsH;YAC/H,QAAQ,EAAE,sDAAsD;SACjE;QACD;YACE,aAAa,EAAE,qCAAqC;YACpD,OAAO,EAAE,yBAAyB;YAClC,QAAQ,EAAE,gBAAgB;SAC3B;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,kDAAkD;YAC9D,QAAQ,EAAE,iHAAiH;SAC5H;QACD;YACE,UAAU,EAAE,8BAA8B;YAC1C,QAAQ,EAAE,6HAA6H;SACxI;QACD;YACE,UAAU,EAAE,gDAAgD;YAC5D,QAAQ,EAAE,8FAA8F;SACzG;QACD;YACE,UAAU,EAAE,8CAA8C;YAC1D,QAAQ,EAAE,sIAAsI;SACjJ;QACD;YACE,UAAU,EAAE,gCAAgC;YAC5C,QAAQ,EAAE,6IAA6I;SACxJ;QACD;YACE,UAAU,EAAE,oCAAoC;YAChD,QAAQ,EAAE,iNAAiN;SAC5N;QACD;YACE,UAAU,EAAE,sCAAsC;YAClD,QAAQ,EAAE,iEAAiE;SAC5E;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,iEAAiE;QAC1E,KAAK,EAAE,8GAA8G;KACtH;IACD,eAAe,EAAE,oWAAoW;IACrX,cAAc,EAAE;QACd,2LAA2L;QAC3L,qNAAqN;QACrN,iPAAiP;QACjP,4KAA4K;KAC7K;IACD,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,cAAc,EAAE;QACd,MAAM;QACN,cAAc;KACf;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/atanh.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=atanh.d.ts.map

package/dist/generated/builtins/atanh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atanh.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/atanh.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAqLjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/atanh.js

@@ -0,0 +1,186 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "atanh",
+    "category": "math/trigonometry",
+    "keywords": [
+        "atanh",
+        "inverse hyperbolic tangent",
+        "artanh",
+        "trigonometry",
+        "gpu",
+        "complex"
+    ],
+    "summary": "Element-wise inverse hyperbolic tangent with MATLAB-compatible complex promotion and GPU fallbacks.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses the provider's unary_atanh hook when every element satisfies |x| ≤ 1; gathers to the host when complex promotion is required or hooks are unavailable."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::trigonometry::atanh::tests",
+        "integration": "builtins::math::trigonometry::atanh::tests::atanh_gpu_provider_roundtrip"
+    },
+    "description": "`Y = atanh(X)` evaluates the inverse hyperbolic tangent of every element in `X`. Real inputs inside the open interval `(-1, 1)` remain real. Values with `|x| > 1` (including `±Inf`) automatically promote to complex results that match MATLAB's principal branch.",
+    "behaviors": [
+        "Accepts scalars, vectors, matrices, and N-D tensors using MATLAB broadcasting semantics.",
+        "Logical values are promoted to double precision (`true → 1`, `false → 0`) before evaluation. The results follow MATLAB's rules for infinities at the endpoints (`atanh(1) = Inf`, `atanh(-1) = -Inf`).",
+        "Real values with magnitude greater than `1` return complex numbers whose imaginary part is `±π/2`. The runtime automatically promotes the entire tensor to `Value::ComplexTensor` so downstream consumers see the MATLAB-compatible complex result.",
+        "Complex inputs are evaluated with MATLAB's definition `atanh(z) = 0.5 * log((1 + z) / (1 - z))`, including correct handling of branch cuts, NaNs, and infinities.",
+        "Character arrays are treated as their numeric code points and converted to doubles before the inverse hyperbolic tangent is applied.",
+        "Empty arrays return empty outputs with matching shape and type."
+    ],
+    "examples": [
+        {
+            "description": "Inverse hyperbolic tangent of a real scalar",
+            "input": "y = atanh(0.5)",
+            "output": "y = 0.5493"
+        },
+        {
+            "description": "Applying atanh element-wise to a vector",
+            "input": "x = linspace(-0.9, 0.9, 5);\ny = atanh(x)",
+            "output": "y = [-1.4722  -0.4847   0    0.4847   1.4722]"
+        },
+        {
+            "description": "Dealing with values near ±1 in atanh",
+            "input": "A = [0.99  1.0  -1.0; 0.0  0.5  -0.5];\nB = atanh(A)",
+            "output": "B =\n    2.6467        Inf       -Inf\n         0    0.5493    -0.5493"
+        },
+        {
+            "description": "Producing complex outputs for |x| > 1",
+            "input": "values = [2 -3];\nresult = atanh(values)",
+            "output": "result =\n   0.5493 + 1.5708i  -0.3466 + 1.5708i"
+        },
+        {
+            "description": "Computing atanh for complex numbers",
+            "input": "Z = [1 + 2i, -0.5 + 0.75i];\nW = atanh(Z)",
+            "output": "W =\n   0.1733 + 1.1781i  -0.3104 + 0.7232i"
+        },
+        {
+            "description": "Running atanh on GPU arrays",
+            "input": "G = gpuArray(linspace(-0.8, 0.8, 4));\ngpuResult = atanh(G);\nhostResult = gather(gpuResult)",
+            "output": "hostResult = [-1.0986  -0.2733   0.2733   1.0986]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When does `atanh` return complex numbers?",
+            "answer": "Whenever an element has magnitude strictly greater than `1`, including `±Inf`, MATLAB defines the result as complex with an imaginary component of `±π/2`. RunMat mirrors that behaviour exactly."
+        },
+        {
+            "question": "How are the endpoints `±1` handled?",
+            "answer": "`atanh(1)` returns positive infinity and `atanh(-1)` returns negative infinity, matching MATLAB. These values still count as real outputs, so the GPU path can handle them without falling back."
+        },
+        {
+            "question": "What happens with NaN inputs?",
+            "answer": "NaNs propagate through the computation. If the GPU provider supports `unary_atanh`, the operation can remain on the device; otherwise the runtime falls back to the host and returns the same NaN results."
+        },
+        {
+            "question": "Does the GPU path differ in precision from the CPU path?",
+            "answer": "Both paths evaluate the inverse hyperbolic tangent in the provider's precision (`f32` or `f64`). Small rounding differences may occur but stay within MATLAB's tolerance requirements."
+        },
+        {
+            "question": "Can complex inputs stay on the GPU?",
+            "answer": "Not yet. GPU tensor handles represent real buffers. When complex outputs are required (either because the input is complex or a real value exceeds the domain), RunMat promotes the result to `Value::Complex`/`Value::ComplexTensor` on the host so the semantics match MATLAB."
+        },
+        {
+            "question": "Will `atanh` participate in fusion and autodiff?",
+            "answer": "Yes. The builtin registers element-wise fusion metadata so the planner can inline it into fused WGSL kernels, and the same metadata feeds future autodiff tooling."
+        },
+        {
+            "question": "Are logical and integer inputs supported?",
+            "answer": "Yes. They are promoted to doubles before evaluation. Outputs follow MATLAB's double or complex-double conventions depending on the values."
+        },
+        {
+            "question": "What if my provider does not implement `unary_atanh`?",
+            "answer": "RunMat automatically gathers the data, evaluates `atanh` on the CPU, and returns correct results. Consider enabling the in-process provider for development or the WGPU provider for production to keep the operation on the GPU."
+        }
+    ],
+    "links": [
+        {
+            "label": "tanh",
+            "url": "./tanh"
+        },
+        {
+            "label": "asinh",
+            "url": "./asinh"
+        },
+        {
+            "label": "acosh",
+            "url": "./acosh"
+        },
+        {
+            "label": "atan",
+            "url": "./atan"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "acos",
+            "url": "./acos"
+        },
+        {
+            "label": "asin",
+            "url": "./asin"
+        },
+        {
+            "label": "atan2",
+            "url": "./atan2"
+        },
+        {
+            "label": "cos",
+            "url": "./cos"
+        },
+        {
+            "label": "cosh",
+            "url": "./cosh"
+        },
+        {
+            "label": "sin",
+            "url": "./sin"
+        },
+        {
+            "label": "sinh",
+            "url": "./sinh"
+        },
+        {
+            "label": "tan",
+            "url": "./tan"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/trigonometry/atanh.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/trigonometry/atanh.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` manually. The auto-offload planner keeps tensors on the GPU whenever the provider exposes a working `unary_atanh` hook and every element satisfies `|x| ≤ 1`. If any element requires complex promotion or the provider lacks native support, RunMat automatically gathers to the host and still returns MATLAB-compatible results. Manual `gpuArray` / `gather` remains available for workflows that demand explicit residency control.",
+    "gpu_behavior": [
+        "RunMat Accelerate keeps tensors on the GPU when:\n\n1. A provider is registered and implements the `unary_atanh` hook. 2. Every element satisfies `|x| ≤ 1` (allowing the endpoints for the ±Inf behaviour).\n\nThe runtime first calls the provider's `reduce_min`/`reduce_max` hooks to prove that the entire operand stays within the real domain `[-1, 1]`. If those hooks are missing, return an error, or detect a value outside the domain, RunMat gathers the tensor to the host, performs the computation with the CPU reference implementation, and returns MATLAB-accurate complex results. Users do not need to micromanage residency with `gpuArray`/`gather`; the runtime transparently falls back only when necessary."
+    ],
+    "key": "atanh",
+    "slug": "atanh",
+    "categoryPath": [
+        "math",
+        "trigonometry"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=atanh.js.map

package/dist/generated/builtins/atanh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atanh.js","sourceRoot":"","sources":["../../../src/generated/builtins/atanh.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/axis.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=axis.d.ts.map

package/dist/generated/builtins/axis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axis.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/axis.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAgEjB,CAAC;AAEF,eAAe,UAAU,CAAC"}