runmat 0.3.6 → 0.4.1

package/dist/generated/builtins/load.js

@@ -0,0 +1,139 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "load",
+    "category": "io/mat",
+    "keywords": [
+        "load",
+        "mat",
+        "workspace",
+        "io",
+        "matlab load",
+        "regex load"
+    ],
+    "summary": "Load variables from a MATLAB-compatible MAT-file into the workspace or return them as a struct.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/load.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Files are read on the host. When auto-offload is enabled, planners may later promote tensors to the GPU; no provider hooks are required at load time."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::mat::load::tests",
+        "integration": [
+            "builtins::io::mat::load::tests::load_selected_variables",
+            "builtins::io::mat::load::tests::load_regex_selection"
+        ]
+    },
+    "description": "`load` reads variables from a MAT-file (Level-5 layout) and brings them into the current workspace. Like MATLAB, it can either populate variables directly or return a struct containing the loaded data.",
+    "behaviors": [
+        "`load filename` reads every variable stored in `filename.mat` and assigns them into the caller's workspace. When no extension is supplied, `.mat` is appended automatically. Set `RUNMAT_LOAD_DEFAULT_PATH` to override the default `matlab.mat` target when no filename argument is provided.",
+        "`S = load(filename)` loads the file but returns a struct instead of modifying the workspace. The struct fields mirror the variables stored in the MAT-file.",
+        "`load(filename, 'A', 'B')` restricts the operation to the listed variable names. String scalars, char vectors, string arrays, or cell arrays of character vectors are accepted.",
+        "`load(filename, '-regexp', '^foo', 'bar$')` selects variables whose names match any of the supplied regular expressions.",
+        "Repeated names are deduplicated so that the last occurrence wins, mirroring MATLAB's behavior.",
+        "Unsupported data classes trigger descriptive errors. RunMat currently supports double and complex numeric arrays, logical arrays, character arrays, string arrays (stored as cell-of-char data), structs, and cells whose elements are composed of the supported types.",
+        "Files saved on platforms that produce little-endian Level-5 MAT-files (MATLAB's default) are supported. Big-endian and compressed (`miCOMPRESSED`) files currently report an error."
+    ],
+    "examples": [
+        {
+            "description": "Load the entire file into the workspace",
+            "input": "weights = [0.5, 1.0, 1.5];\nsave('results.mat', 'weights');\nload('results.mat');\ndisp(norm(weights))"
+        },
+        {
+            "description": "Load a subset of variables by name",
+            "input": "time = 0:0.25:1;\nstate = [0, 0.5, 0.8, 0.6, 0.3];\nsave('sim_state.mat', 'time', 'state');\nload('sim_state.mat', 'state', 'time');\nplot(time, state)"
+        },
+        {
+            "description": "Load variables using regular expressions",
+            "input": "layer_1 = ones(4, 4);\nlayer_2 = ones(8, 8);\nsave('checkpoint.mat', 'layer_1', 'layer_2');\nload('checkpoint.mat', '-regexp', '^layer_\\d+$')"
+        },
+        {
+            "description": "Capture loaded variables in a struct without altering the workspace",
+            "input": "x = 3.14;\ny = 2.72;\nsave('snapshot.mat', 'x', 'y');\nS = load('snapshot.mat');\ndisp(fieldnames(S))"
+        },
+        {
+            "description": "Combine explicit names and regex filters",
+            "input": "config = struct('lr', 0.01);\nweights_conv = randn(3, 3);\nweights_fc = randn(4, 2);\nsave('model.mat', 'config', 'weights_conv', 'weights_fc');\nmodel = load('model.mat', 'config', '-regexp', '^weights_(conv|fc)')"
+        },
+        {
+            "description": "Honour a custom default filename",
+            "input": "x = 0;\nsave(fullfile(tempdir, 'autosave.mat'), 'x');\nsetenv('RUNMAT_LOAD_DEFAULT_PATH', fullfile(tempdir, 'autosave.mat'));\nload()"
+        },
+        {
+            "description": "Load character and string data",
+            "input": "labels = 'hello';\nsave('strings.mat', 'labels');\nvalues = load('strings.mat', 'labels');\ndisp(values.labels)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `load` support ASCII text files?",
+            "answer": "No. RunMat (like MATLAB) restricts the `load` builtin in modern releases to MAT-files. Text and delimited files should be read using `readmatrix`, `readtable`, or other file I/O utilities such as `fileread`."
+        },
+        {
+            "question": "How are structures handled?",
+            "answer": "Structure scalars are reconstructed as `struct` values whose fields match the MAT-file content. Nested structs, cells, logical arrays, and numeric data are all supported."
+        },
+        {
+            "question": "Will `load` overwrite existing variables?",
+            "answer": "Yes. When you call `load` without capturing the output struct, any variables with matching names in the caller's workspace are overwritten with the values from the MAT-file."
+        },
+        {
+            "question": "What happens if a requested variable is missing?",
+            "answer": "RunMat raises a descriptive error: `load: variable 'foo' was not found in the file`. This mirrors MATLAB's behavior."
+        },
+        {
+            "question": "Can I load into a different workspace?",
+            "answer": "Use MATLAB-compatible functions such as `assignin` (when available) if you need to populate a different scope explicitly. The `load` builtin itself targets the caller workspace by default."
+        },
+        {
+            "question": "How are GPU arrays handled?",
+            "answer": "GPU-resident values are serialised to host data when saved. Loading the resulting MAT-file produces standard host arrays. Downstream acceleration is handled automatically by RunMat Accelerate."
+        },
+        {
+            "question": "How do I detect which variables were loaded?",
+            "answer": "Use the struct form: `info = load(filename);` and then inspect `fieldnames(info)` or `isfield` to programmatically check what was present in the MAT-file."
+        }
+    ],
+    "links": [
+        {
+            "label": "save",
+            "url": "./save"
+        },
+        {
+            "label": "who",
+            "url": "./who"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/mat/load.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/mat/load.rs"
+    },
+    "gpu_residency": "No manual action is required. `load` always creates host values. When the auto-offload planner decides that downstream computations benefit from GPU execution, it will promote tensors automatically. You can still call `gpuArray` on loaded variables explicitly if you want to pin them to the device immediately.",
+    "gpu_behavior": [
+        "`load` always reads data on the host. The resulting values start on the CPU. When RunMat Accelerate is active, auto-offload heuristics may later decide to promote tensors to the GPU if they participate in accelerated expressions, but no provider hooks are required during the `load` operation itself. GPU-resident variables that were saved earlier are gathered back to host memory as part of file serialisation, so loading them produces standard host values."
+    ],
+    "key": "load",
+    "slug": "load",
+    "categoryPath": [
+        "io",
+        "mat"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=load.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../../src/generated/builtins/load.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,MAAM;IACf,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE;QACV,MAAM;QACN,KAAK;QACL,WAAW;QACX,IAAI;QACJ,aAAa;QACb,YAAY;KACb;IACD,SAAS,EAAE,iGAAiG;IAC5G,YAAY,EAAE;QACZ,qDAAqD;KACtD;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,uJAAuJ;KACjK;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,gCAAgC;QACxC,aAAa,EAAE;YACb,yDAAyD;YACzD,sDAAsD;SACvD;KACF;IACD,aAAa,EAAE,2MAA2M;IAC1N,WAAW,EAAE;QACX,gSAAgS;QAChS,6JAA6J;QAC7J,iLAAiL;QACjL,0HAA0H;QAC1H,gGAAgG;QAChG,yQAAyQ;QACzQ,qLAAqL;KACtL;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,yCAAyC;YACxD,OAAO,EAAE,wGAAwG;SAClH;QACD;YACE,aAAa,EAAE,oCAAoC;YACnD,OAAO,EAAE,yJAAyJ;SACnK;QACD;YACE,aAAa,EAAE,0CAA0C;YACzD,OAAO,EAAE,gJAAgJ;SAC1J;QACD;YACE,aAAa,EAAE,qEAAqE;YACpF,OAAO,EAAE,uGAAuG;SACjH;QACD;YACE,aAAa,EAAE,0CAA0C;YACzD,OAAO,EAAE,wNAAwN;SAClO;QACD;YACE,aAAa,EAAE,kCAAkC;YACjD,OAAO,EAAE,uIAAuI;SACjJ;QACD;YACE,aAAa,EAAE,gCAAgC;YAC/C,OAAO,EAAE,iHAAiH;SAC3H;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,iNAAiN;SAC5N;QACD;YACE,UAAU,EAAE,6BAA6B;YACzC,QAAQ,EAAE,4KAA4K;SACvL;QACD;YACE,UAAU,EAAE,2CAA2C;YACvD,QAAQ,EAAE,+KAA+K;SAC1L;QACD;YACE,UAAU,EAAE,kDAAkD;YAC9D,QAAQ,EAAE,sHAAsH;SACjI;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,8LAA8L;SACzM;QACD;YACE,UAAU,EAAE,6BAA6B;YACzC,QAAQ,EAAE,kMAAkM;SAC7M;QACD;YACE,UAAU,EAAE,8CAA8C;YAC1D,QAAQ,EAAE,4JAA4J;SACvK;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,qDAAqD;QAC9D,KAAK,EAAE,kGAAkG;KAC1G;IACD,eAAe,EAAE,wTAAwT;IACzU,cAAc,EAAE;QACd,4cAA4c;KAC7c;IACD,KAAK,EAAE,MAAM;IACb,MAAM,EAAE,MAAM;IACd,cAAc,EAAE;QACd,IAAI;QACJ,KAAK;KACN;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/log.js

@@ -0,0 +1,226 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "log",
+    "category": "math/elementwise",
+    "keywords": [
+        "log",
+        "natural logarithm",
+        "elementwise",
+        "gpu",
+        "complex"
+    ],
+    "summary": "Natural logarithm 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 implementation when the provider lacks unary_log or when the result requires complex values."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::log::tests",
+        "integration": "builtins::math::elementwise::log::tests::log_gpu_provider_roundtrip",
+        "gpu": "builtins::math::elementwise::log::tests::log_wgpu_matches_cpu_elementwise"
+    },
+    "description": "`Y = log(X)` computes the natural logarithm of every element in `X`, extending MATLAB semantics to real, logical, character, and complex inputs. Negative real values are promoted to complex results so that `log(-1)` yields `0 + iπ`.",
+    "behaviors": [
+        "`log(X)` applies the operation element-wise with MATLAB broadcasting rules.",
+        "Logical values convert to doubles (`true → 1.0`, `false → 0.0`) before the logarithm is taken.",
+        "Character arrays are interpreted as their numeric code points and return dense double tensors.",
+        "Negative real values produce complex results: `log([-1 1])` returns `[0 + iπ, 0]`.",
+        "Complex inputs follow MATLAB's definition: `log(a + bi) = log(|a + bi|) + i·atan2(b, a)`.",
+        "`log(0)` returns `-Inf`, matching MATLAB's handling of the logarithm singularity at zero."
+    ],
+    "examples": [
+        {
+            "description": "Natural log of a positive scalar",
+            "input": "y = log(exp(3))",
+            "output": "y = 3"
+        },
+        {
+            "description": "Understanding log of zero",
+            "input": "value = log(0)",
+            "output": "value = -Inf"
+        },
+        {
+            "description": "Taking the logarithm of negative values",
+            "input": "data = [-1 -2 -4];\nresult = log(data)",
+            "output": "result = [0.0000 + 3.1416i, 0.6931 + 3.1416i, 1.3863 + 3.1416i]"
+        },
+        {
+            "description": "Applying log to complex numbers",
+            "input": "z = [1+2i, -1+pi*i];\nw = log(z)",
+            "output": "w = [0.8047 + 1.1071i, 1.1447 + 1.2626i]"
+        },
+        {
+            "description": "Element-wise log on a matrix living on the GPU",
+            "input": "G = gpuArray([1 2; 4 8]);\nout = log(G);\nresult = gather(out)",
+            "output": "result = [0.0000 0.6931; 1.3863 2.0794]"
+        },
+        {
+            "description": "Logging character codes from a string",
+            "input": "C = 'ABC';\nvalues = log(C)",
+            "output": "values = [4.1744 4.1897 4.2047]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use the `log` function?",
+            "answer": "Use `log` whenever you need the natural logarithm of your data—for example, to linearize exponential growth, compute likelihoods, or transform multiplicative relationships into additive ones."
+        },
+        {
+            "question": "What happens if the input contains zeros?",
+            "answer": "`log(0)` returns negative infinity (`-Inf`). Entire tensors follow the same rule element-wise."
+        },
+        {
+            "question": "How are negative real numbers handled?",
+            "answer": "Negative values automatically promote to complex results: `log(-x)` returns `log(x) + iπ`. This matches MATLAB behaviour and avoids losing information compared with returning `NaN`."
+        },
+        {
+            "question": "What about tiny floating-point noise producing small negative numbers?",
+            "answer": "Values that are numerically negative (e.g., `-1e-15`) are treated just like other negatives and promote to complex outputs. Use `abs` or `max` to clip values if you require a purely real result."
+        },
+        {
+            "question": "Does the GPU implementation support complex outputs?",
+            "answer": "Providers currently operate on real buffers. When complex results are required, RunMat gathers data to the host to compute the exact result and keeps residency metadata consistent."
+        },
+        {
+            "question": "Does `log` accept complex inputs directly?",
+            "answer": "Yes. Complex scalars and tensors follow the MATLAB definition using magnitude and phase (`log(|z|) + i·angle(z)`)."
+        }
+    ],
+    "links": [
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "abs",
+            "url": "./abs"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "conj",
+            "url": "./conj"
+        },
+        {
+            "label": "double",
+            "url": "./double"
+        },
+        {
+            "label": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "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/log.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/log.rs"
+    },
+    "gpu_residency": "You typically do **not** need to call `gpuArray` yourself. The auto-offload planner tracks residency and keeps tensors on the GPU when profitable. When your expression produces complex results (e.g., negative inputs to `log`), RunMat will gather the data automatically and still return exactly the MATLAB-compatible output. You can force explicit residency with `gpuArray` and `gather` if you want to mirror MathWorks MATLAB workflows.",
+    "gpu_behavior": [
+        "RunMat Accelerate keeps tensors on the GPU when the active provider implements `unary_log` *and* `reduce_min`. The runtime queries the device-side minimum to confirm that all values are non-negative, so positive datasets stay resident and can participate in fused elementwise kernels. When complex outputs are required or the provider cannot supply these hooks, RunMat gathers the tensor to the host, computes the exact MATLAB-compatible result (including complex promotion), updates residency metadata, and returns the host-resident value."
+    ],
+    "key": "log",
+    "slug": "log",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=log.js.map

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

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

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

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

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

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

package/dist/generated/builtins/log10.js

@@ -0,0 +1,221 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "log10",
+    "category": "math/elementwise",
+    "keywords": [
+        "log10",
+        "base-10 logarithm",
+        "elementwise",
+        "magnitude",
+        "gpu"
+    ],
+    "summary": "Base-10 logarithm 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 implementation when the provider lacks unary_log10 or when the result requires complex values."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::log10::tests",
+        "integration": "builtins::math::elementwise::log10::tests::log10_gpu_provider_roundtrip",
+        "gpu": "builtins::math::elementwise::log10::tests::log10_wgpu_matches_cpu_elementwise"
+    },
+    "description": "`Y = log10(X)` computes the base-10 logarithm of every element in `X`, following MATLAB's numeric semantics for real, logical, character, and complex inputs. Negative real values promote to complex results so that you can analyze magnitudes without losing phase information.",
+    "behaviors": [
+        "`log10` operates element-wise with MATLAB broadcasting rules.",
+        "Logical inputs convert to doubles (`true → 1.0`, `false → 0.0`) before the logarithm is applied.",
+        "Character arrays are interpreted as their numeric code points and return dense double tensors.",
+        "`log10(0)` returns `-Inf`, matching MATLAB's handling of the logarithm singularity at zero.",
+        "Negative real values promote to complex results: `log10(-10)` returns `1 + i·π/ln(10)`.",
+        "Complex inputs follow MATLAB's definition: `log10(z) = log(z) / ln(10)`."
+    ],
+    "examples": [
+        {
+            "description": "Finding the order of magnitude of a number",
+            "input": "value = log10(1000)",
+            "output": "value = 3"
+        },
+        {
+            "description": "Computing base-10 logarithms of a matrix",
+            "input": "A = [1 10 100; 0.1 0.01 0.001];\nB = log10(A)",
+            "output": "B = [0 1 2; -1 -2 -3]"
+        },
+        {
+            "description": "Understanding how `log10` handles zero",
+            "input": "z = log10(0)",
+            "output": "z = -Inf"
+        },
+        {
+            "description": "Working with negative inputs using complex results",
+            "input": "neg = [-10 -100];\nout = log10(neg)",
+            "output": "out = [1.0000 + 1.3644i, 2.0000 + 1.3644i]"
+        },
+        {
+            "description": "Running `log10` on GPU-resident data",
+            "input": "G = gpuArray([1 10 1000]);\nresult = log10(G);\nhost = gather(result)",
+            "output": "host = [0 1 3]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use `log10` instead of `log`?",
+            "answer": "Use `log10` when you want base-10 magnitudes, such as for decibel calculations or scientific notation. Use `log` (natural logarithm) for exponential growth/decay or calculus contexts."
+        },
+        {
+            "question": "What happens if an element is zero?",
+            "answer": "`log10(0)` returns negative infinity (`-Inf`), matching MATLAB behavior."
+        },
+        {
+            "question": "How does `log10` handle negative real numbers?",
+            "answer": "Negative values promote to complex numbers with an imaginary component of `π/ln(10)`. This preserves phase information instead of producing `NaN`."
+        },
+        {
+            "question": "Can I pass complex inputs to `log10`?",
+            "answer": "Yes. Complex scalars and tensors are handled as `log(z) / ln(10)`, matching MATLAB exactly."
+        },
+        {
+            "question": "Does the GPU implementation support complex outputs?",
+            "answer": "Current providers operate on real buffers. When complex outputs are required, RunMat gathers the tensor to the host while keeping fusion metadata consistent."
+        },
+        {
+            "question": "Is `log10` numerically stable for very small or large values?",
+            "answer": "Yes. The implementation promotes to 64-bit doubles throughout and clamps tiny imaginary parts to zero, mirroring MATLAB's behavior for well-conditioned inputs."
+        }
+    ],
+    "links": [
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "abs",
+            "url": "./abs"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "conj",
+            "url": "./conj"
+        },
+        {
+            "label": "double",
+            "url": "./double"
+        },
+        {
+            "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": "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": "times",
+            "url": "./times"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/log10.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/log10.rs"
+    },
+    "gpu_residency": "You typically do **not** need to call `gpuArray` yourself. The auto-offload planner keeps tensors on the GPU when profitable and the result stays real. When complex results are required, RunMat automatically gathers the data to the host to produce the precise MATLAB-compatible answer. Use `gpuArray`/`gather` only when you want to mirror MathWorks MATLAB workflows explicitly.",
+    "gpu_behavior": [
+        "RunMat Accelerate keeps tensors on the GPU when the active provider implements `unary_log10` and the data is known to stay in the real domain. If complex outputs are required (for example, negative inputs) or the provider lacks the hook, RunMat gathers the tensor to the host, computes the exact MATLAB-compatible result, updates residency metadata, and returns the host-resident value."
+    ],
+    "key": "log10",
+    "slug": "log10",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=log10.js.map

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

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

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

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

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

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