runmat 0.3.5 → 0.4.0

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

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

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

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

package/dist/generated/builtins/abs.js

@@ -0,0 +1,245 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "abs",
+    "category": "math/elementwise",
+    "keywords": [
+        "abs",
+        "absolute value",
+        "magnitude",
+        "complex",
+        "gpu"
+    ],
+    "summary": "Absolute value or magnitude of scalars, vectors, matrices, or N-D tensors.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Falls back to the host when the active provider lacks unary_abs or when complex tensors must be gathered."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::abs::tests",
+        "integration": "builtins::math::elementwise::abs::tests::abs_gpu_provider_roundtrip"
+    },
+    "description": "`y = abs(x)` returns the absolute value of real inputs and the magnitude (modulus) of complex inputs. For tensors, the operation is applied element-wise following MATLAB's broadcasting rules.",
+    "behaviors": [
+        "Real scalars, vectors, matrices, and N-D tensors are mapped to their element-wise absolute values.",
+        "Complex inputs return the magnitude `sqrt(real(x).^2 + imag(x).^2)`, matching MATLAB semantics.",
+        "Logical inputs are promoted to doubles (`true → 1.0`, `false → 0.0`) before taking the absolute value.",
+        "Character arrays are converted to double arrays of code point magnitudes, just like MATLAB.",
+        "String arrays are not supported and raise an error (`abs` only accepts numeric, logical, or char inputs).",
+        "NaN values remain NaN; the function does not change IEEE NaN propagation rules."
+    ],
+    "examples": [
+        {
+            "description": "Getting the absolute value of a scalar",
+            "input": "y = abs(-42)",
+            "output": "y = 42"
+        },
+        {
+            "description": "Taking the absolute value of a vector",
+            "input": "v = [-2 -1 0 1 2];\nresult = abs(v)",
+            "output": "result = [2 1 0 1 2]"
+        },
+        {
+            "description": "Measuring complex magnitudes",
+            "input": "z = [3+4i, 1-1i];\nmagnitudes = abs(z)",
+            "output": "magnitudes = [5 1.4142]"
+        },
+        {
+            "description": "Working with matrices on the GPU",
+            "input": "G = randn(2048, 2048, \"gpuArray\");\npositive = abs(G)"
+        },
+        {
+            "description": "Using `abs` with logical arrays",
+            "input": "mask = logical([0 1 0; 1 0 1]);\nnumeric = abs(mask)",
+            "output": "numeric = [0 1 0; 1 0 1]"
+        },
+        {
+            "description": "Converting characters to numeric codes",
+            "input": "c = 'ABC';\ncodes = abs(c)",
+            "output": "codes = [65 66 67]"
+        },
+        {
+            "description": "Chaining `abs` inside fused expressions",
+            "input": "x = linspace(-2, 2, 5);\ny = abs(x) + x.^2"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `abs` change NaN values?",
+            "answer": "No. `abs(NaN)` returns `NaN`, consistent with IEEE arithmetic and MATLAB behaviour."
+        },
+        {
+            "question": "What happens to complex numbers?",
+            "answer": "RunMat returns the magnitude `sqrt(real(x).^2 + imag(x).^2)`, identical to MATLAB."
+        },
+        {
+            "question": "Can I call `abs` on string arrays?",
+            "answer": "No. Like MATLAB, `abs` only accepts numeric, logical, or character inputs. Use `double(string)` if you need code points."
+        },
+        {
+            "question": "Does `abs` work with sparse arrays?",
+            "answer": "Sparse support is planned but not yet implemented; inputs are densified today."
+        },
+        {
+            "question": "Is GPU execution exact?",
+            "answer": "Device execution follows IEEE semantics for the provider's precision (`single` or `double`). F32 backends may incur small rounding differences compared to CPU double."
+        },
+        {
+            "question": "How do I keep results on the GPU?",
+            "answer": "Avoid calling `gather` unless you need host data. The planner keeps device tensors resident whenever possible."
+        },
+        {
+            "question": "Does `abs` allocate new memory?",
+            "answer": "Yes. The builtin returns a new tensor; fusion may in-place combine kernels to reduce allocations when safe."
+        },
+        {
+            "question": "Can I use `abs` with logical masks?",
+            "answer": "Yes. Logical inputs are promoted to doubles (0 or 1) before applying `abs`, just like MATLAB."
+        }
+    ],
+    "links": [
+        {
+            "label": "sin",
+            "url": "./sin"
+        },
+        {
+            "label": "sum",
+            "url": "./sum"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "conj",
+            "url": "./conj"
+        },
+        {
+            "label": "double",
+            "url": "./double"
+        },
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "log2",
+            "url": "./log2"
+        },
+        {
+            "label": "minus",
+            "url": "./minus"
+        },
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "rdivide",
+            "url": "./rdivide"
+        },
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "sign",
+            "url": "./sign"
+        },
+        {
+            "label": "single",
+            "url": "./single"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        },
+        {
+            "label": "times",
+            "url": "./times"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/abs.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/abs.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` explicitly. RunMat's fusion planner and Accelerate layer track residency automatically, keeping tensors on the GPU whenever device execution is beneficial. Explicit `gpuArray`/`gather` calls remain available for MATLAB compatibility or when you need deterministic residency control (e.g., integrating with third-party GPU kernels).",
+    "gpu_behavior": [
+        "**Hook available:** The absolute value is computed directly on the device with no host transfers.",
+        "**Hook missing or unsupported dtype:** RunMat gathers the tensor to host memory, performs the CPU absolute value logic (including complex magnitudes), and optionally re-uploads downstream.\n\nComplex tensors are currently handled on the host because the in-process and WGPU providers emit real-valued magnitudes. Device providers are encouraged to add fused complex support."
+    ],
+    "key": "abs",
+    "slug": "abs",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=abs.js.map

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

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

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

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

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

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

package/dist/generated/builtins/accept.js

@@ -0,0 +1,151 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "accept",
+    "category": "io/net",
+    "keywords": [
+        "accept",
+        "tcpserver",
+        "tcpclient",
+        "socket",
+        "networking"
+    ],
+    "summary": "Accept a pending client connection on a TCP server.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/accept.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Networking runs on the host CPU. GPU-resident metadata is gathered automatically before accepting connections."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::net::accept::tests",
+        "integration": "builtins::io::net::accept::tests::accept_establishes_client_connection"
+    },
+    "description": "`accept(server)` waits for a pending TCP connection on the socket created by `tcpserver`. When a client connects, the builtin returns a MATLAB-compatible struct that mirrors the `tcpclient` object. The struct tracks connection metadata (remote address, port, byte order, and timeout settings) and holds an opaque identifier that other RunMat networking builtins use to operate on the live socket.",
+    "behaviors": [
+        "The first argument must be the struct returned from `tcpserver`. RunMat validates that the struct contains a `__tcpserver_id` field and raises `RunMat:accept:InvalidTcpServer` when the identifier is missing or no longer points to an active listener.",
+        "By default, `accept` uses the timeout configured when the server was created (`Timeout` name-value pair on `tcpserver`). You can override it per call with `accept(server, \"Timeout\", seconds)`. The timeout must be non-negative; the builtin raises `RunMat:accept:InvalidNameValue` when the value is NaN, negative, or non-scalar.",
+        "Successful calls return immediately with a struct whose fields mirror MATLAB’s `tcpclient` properties (`Address`, `Port`, `NumBytesAvailable`, `BytesAvailableFcn`, `ByteOrder`, `Timeout`, `UserData`, and `Connected`). The struct also contains hidden fields `__tcpserver_id` and `__tcpclient_id` so higher-level builtins can operate on the live socket.",
+        "If no client connects before the timeout expires, the builtin raises `RunMat:accept:Timeout`.",
+        "When the underlying OS reports an accept failure (for example, because the socket closed), the builtin raises `RunMat:accept:AcceptFailed` with the platform error message.",
+        "Networking occurs on the host CPU. If the server struct or timeout value lives on the GPU, RunMat gathers it to the host automatically before waiting for connections."
+    ],
+    "examples": [
+        {
+            "description": "Accepting a localhost client connection",
+            "input": "srv = tcpserver(\"127.0.0.1\", 0);\nport = srv.ServerPort;\ntcpclient(\"127.0.0.1\", port);\nclient = accept(srv);\ndisp(client.Address)\ndisp(client.Port)",
+            "output": "127.0.0.1\n55000    % varies per run"
+        },
+        {
+            "description": "Overriding the timeout for a single accept call",
+            "input": "srv = tcpserver(\"0.0.0.0\", 0, \"Timeout\", 10);\ntry\n    client = accept(srv, \"Timeout\", 0.25);\ncatch err\n    disp(err.identifier)\nend",
+            "output": "RunMat:accept:Timeout"
+        },
+        {
+            "description": "Inspecting connection metadata after accepting a client",
+            "input": "srv = tcpserver(\"::1\", 45000);\ntcpclient(\"::1\", 45000);\nclient = accept(srv);\nfprintf(\"Remote peer %s:%d\\\\n\", client.Address, client.Port);\nfprintf(\"Byte order: %s\\\\n\", client.ByteOrder)",
+            "output": "Remote peer ::1:51432\nByte order: little-endian"
+        },
+        {
+            "description": "Handling multiple queued clients sequentially",
+            "input": "srv = tcpserver(\"127.0.0.1\", 47000);\ntcpclient(\"127.0.0.1\", 47000);\ntcpclient(\"127.0.0.1\", 47000);\nclient1 = accept(srv);\nclient2 = accept(srv);\nfprintf(\"First connection from %s\\\\n\", client1.Address);\nfprintf(\"Second connection from %s\\\\n\", client2.Address)",
+            "output": "First connection from 127.0.0.1\nSecond connection from 127.0.0.1"
+        },
+        {
+            "description": "Using the returned identifier with other networking builtins",
+            "input": "srv = tcpserver(\"127.0.0.1\", 52000);\ntcpclient(\"127.0.0.1\", 52000);\nclient = accept(srv);\nclientId = client.__tcpclient_id;\nfprintf(\"Opaque client identifier: %d\\\\n\", clientId)",
+            "output": "Opaque client identifier: 42   % identifier value varies per run"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What happens if the server struct is invalid or already closed?",
+            "answer": "RunMat reports `RunMat:accept:InvalidTcpServer`. Ensure you pass the struct returned by `tcpserver` and that the server is still active."
+        },
+        {
+            "question": "Can I accept multiple clients with the same server?",
+            "answer": "Yes. Call `accept` repeatedly; each successful call registers a new client and returns its own struct while keeping the listener active."
+        },
+        {
+            "question": "How do I change the timeout globally?",
+            "answer": "Configure it when creating the server (`tcpserver(..., \"Timeout\", seconds)`). You can override it per call with `accept(srv, \"Timeout\", value)` if needed."
+        },
+        {
+            "question": "Does RunMat support IPv6 clients?",
+            "answer": "Yes. The builtin accepts IPv4 or IPv6 clients and records their string representation in the returned struct’s `Address` field."
+        },
+        {
+            "question": "Is there a queue limit for pending connections?",
+            "answer": "The OS backlog applies. If the queue is full, new clients may be refused before `accept` sees them. Increase the backlog with OS-level tuning if needed."
+        },
+        {
+            "question": "Can I use `accept` in parallel workers?",
+            "answer": "Yes. The listener must exist in the worker where you call `accept`, just like MATLAB. Future high-level helpers will coordinate cross-worker sharing."
+        },
+        {
+            "question": "How do I close the accepted client?",
+            "answer": "Use forthcoming networking close helpers (or invoke platform APIs directly). Dropping the struct does not close the socket automatically; RunMat networking builtins reference the opaque identifier."
+        },
+        {
+            "question": "What does `NumBytesAvailable` represent?",
+            "answer": "It mirrors MATLAB: the number of bytes buffered and ready to read. Initially zero; reading functions update it as data arrives."
+        },
+        {
+            "question": "Does the builtin support TLS?",
+            "answer": "Not yet. TLS will be layered on top of the same client identifier once RunMat’s TLS provider lands."
+        }
+    ],
+    "links": [
+        {
+            "label": "tcpserver",
+            "url": "./tcpserver"
+        },
+        {
+            "label": "close",
+            "url": "./close"
+        },
+        {
+            "label": "read",
+            "url": "./read"
+        },
+        {
+            "label": "readline",
+            "url": "./readline"
+        },
+        {
+            "label": "tcpclient",
+            "url": "./tcpclient"
+        },
+        {
+            "label": "write",
+            "url": "./write"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/io/net/accept.rs",
+        "url": "crates/runmat-runtime/src/builtins/io/net/accept.rs"
+    },
+    "gpu_residency": "No. TCP sockets run on the host, and `accept` gathers any GPU-resident scalars or structs before waiting for a connection. Keeping metadata on the GPU offers no benefit, and the builtin always returns CPU-resident structs with identifiers that reference host networking resources.",
+    "gpu_behavior": [
+        "`accept` does not involve the GPU. Any inputs that originate on the GPU are gathered before validation to make sure socket operations run on the host. The returned struct is always CPU-resident. No acceleration-provider hooks are required for this builtin, and future GPU-aware networking features will continue to gather metadata automatically while keeping sockets on the host."
+    ],
+    "key": "accept",
+    "slug": "accept",
+    "categoryPath": [
+        "io",
+        "net"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=accept.js.map

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

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

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

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

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

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

package/dist/generated/builtins/acos.js

@@ -0,0 +1,177 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "acos",
+    "category": "math/trigonometry",
+    "keywords": [
+        "acos",
+        "inverse cosine",
+        "arccos",
+        "trigonometry",
+        "gpu"
+    ],
+    "summary": "Element-wise inverse cosine 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_acos hook when reduce_min / reduce_max confirm every element stays within [-1, 1]; gathers to host for complex promotion or when hooks are unavailable."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::trigonometry::acos::tests",
+        "integration": "builtins::math::trigonometry::acos::tests::acos_gpu_provider_roundtrip"
+    },
+    "description": "`Y = acos(X)` computes the inverse cosine (in radians) of every element of `X`. Results match MATLAB semantics for real, logical, character, and complex inputs. Real values outside the interval `[-1, 1]` promote to complex outputs automatically so the mathematical definition remains valid over the complex plane.",
+    "behaviors": [
+        "Operates on scalars, vectors, matrices, and N-D tensors using MATLAB broadcasting rules.",
+        "Logical inputs convert to double precision (`true → 1`, `false → 0`) before applying inverse cosine.",
+        "Character arrays are interpreted as their numeric code points and return dense double or complex tensors that mirror MATLAB’s output.",
+        "Real inputs with magnitude greater than `1` yield complex results (`acos(2) → 0 - 1.3170i`), matching MATLAB’s principal branch.",
+        "Complex inputs follow MATLAB's definition `acos(z) = -i log(z + i sqrt(1 - z^2))`, ensuring identical behaviour for branch cuts and special values.",
+        "NaNs and Infs propagate in the same way MATLAB does, including complex infinities when necessary."
+    ],
+    "examples": [
+        {
+            "description": "Computing the inverse cosine of a scalar angle",
+            "input": "y = acos(0.5)",
+            "output": "y = 1.0472"
+        },
+        {
+            "description": "Handling values outside [-1, 1] that produce complex results",
+            "input": "z = acos(2)",
+            "output": "z = 0.0000 - 1.3170i"
+        },
+        {
+            "description": "Applying inverse cosine to every element of a matrix",
+            "input": "A = [0 -0.5 0.75; 1 0.25 -0.8];\nY = acos(A)",
+            "output": "Y =\n    1.5708    2.0944    0.7227\n         0    1.3181    2.4981"
+        },
+        {
+            "description": "Using logical input with automatic double promotion",
+            "input": "mask = logical([0 1 0 1]);\nangles = acos(mask)",
+            "output": "angles = [1.5708 0 1.5708 0]"
+        },
+        {
+            "description": "Running `acos` on a GPU array without explicit transfers",
+            "input": "G = gpuArray(linspace(-1, 1, 5));\nresult_gpu = acos(G);\nresult = gather(result_gpu)",
+            "output": "result = [3.1416 2.0944 1.5708 1.0472 0.0000]"
+        },
+        {
+            "description": "Evaluating inverse cosine of complex numbers",
+            "input": "vals = [0.5 + 1i, -0.2 + 0.75i];\nw = acos(vals)",
+            "output": "w =\n   1.2214 - 0.9261i\n   1.7307 - 0.7009i"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Why does `acos` sometimes return complex numbers?",
+            "answer": "Inputs with magnitude greater than `1` lie outside the real domain, so MATLAB (and RunMat) return complex results computed from the principal branch of the inverse cosine."
+        },
+        {
+            "question": "Does `acos` support GPU execution?",
+            "answer": "Yes. When the provider implements `unary_acos` and exposes min/max reductions for the domain check, the runtime executes `acos` entirely on the GPU. Otherwise, it gathers to the host transparently."
+        },
+        {
+            "question": "How are logical or integer inputs handled?",
+            "answer": "Logical arrays convert to doubles before evaluation. Integers also promote to double precision so the computation matches MATLAB and avoids overflow concerns."
+        },
+        {
+            "question": "What happens with NaN or Inf values?",
+            "answer": "NaNs propagate through the computation. Inputs of `±Inf` produce complex infinities exactly as in MATLAB."
+        },
+        {
+            "question": "Can I keep the result on the GPU if it becomes complex?",
+            "answer": "Complex results are currently returned on the host because GPU tensor handles represent real data. The runtime gathers automatically and returns `Value::Complex` or `Value::ComplexTensor`, preserving correctness."
+        },
+        {
+            "question": "Does `acos` fuse with other element-wise operations?",
+            "answer": "Yes. The fusion planner can emit WGSL kernels that include `acos` when the provider supports the generated path, allowing fused GPU execution without intermediate buffers."
+        }
+    ],
+    "links": [
+        {
+            "label": "asin",
+            "url": "./asin"
+        },
+        {
+            "label": "cos",
+            "url": "./cos"
+        },
+        {
+            "label": "sin",
+            "url": "./sin"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "acosh",
+            "url": "./acosh"
+        },
+        {
+            "label": "asinh",
+            "url": "./asinh"
+        },
+        {
+            "label": "atan",
+            "url": "./atan"
+        },
+        {
+            "label": "atan2",
+            "url": "./atan2"
+        },
+        {
+            "label": "atanh",
+            "url": "./atanh"
+        },
+        {
+            "label": "cosh",
+            "url": "./cosh"
+        },
+        {
+            "label": "sinh",
+            "url": "./sinh"
+        },
+        {
+            "label": "tan",
+            "url": "./tan"
+        },
+        {
+            "label": "tanh",
+            "url": "./tanh"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/trigonometry/acos.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/trigonometry/acos.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` explicitly. The fusion planner keeps tensors on the GPU whenever the active provider exposes `unary_acos` and the values remain within the real domain. When complex promotion is necessary, RunMat gathers the tensor automatically and returns the MATLAB-compatible complex result. Manual residency control remains available for workflows that require it.",
+    "gpu_behavior": [
+        "RunMat Accelerate keeps tensors on the GPU when:\n\n1. A provider is registered and implements `unary_acos` as well as the extremum reductions used to confirm the input domain. 2. Every element is provably within the real domain `[-1, 1]`.\n\nIf either condition fails (for example, when a complex result is required or the provider lacks supporting reductions), the runtime gathers the data to the host, computes the MATLAB-compatible answer, and returns the correct result without user intervention. Manual `gpuArray` / `gather` calls remain optional for explicit residency control."
+    ],
+    "key": "acos",
+    "slug": "acos",
+    "categoryPath": [
+        "math",
+        "trigonometry"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=acos.js.map

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

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

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

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

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

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