{
"title": "log2",
"category": "math/elementwise",
"keywords": [
"log2",
"base-2 logarithm",
"elementwise",
"gpu",
"complex"
],
"summary": "Base-2 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_log2 or when complex results are required."
},
"fusion": {
"elementwise": true,
"reduction": false,
"max_inputs": 1,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::math::elementwise::log2::tests",
"integration": "builtins::math::elementwise::log2::tests::log2_gpu_provider_roundtrip",
"gpu": "builtins::math::elementwise::log2::tests::log2_wgpu_matches_cpu_elementwise"
},
"description": "`Y = log2(X)` computes the base-2 logarithm of every element in `X`, following MATLAB's semantics for real, logical, character, and complex inputs. Negative real values promote to complex results so that `log2(-1)` yields `0 + i·π/ln(2)`.",
"behaviors": [
"`log2` 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 of the same shape.",
"`log2(0)` returns `-Inf`; positive infinity stays `Inf`; `NaN` propagates unchanged.",
"Negative real values promote to complex results: `log2([-1 1])` returns `[0 + i·π/ln(2), 0]`.",
"Complex inputs follow MATLAB's definition `log2(z) = log(z) / ln(2)` and clamp subnormal imaginary parts to zero for readability."
],
"examples": [
{
"description": "Computing base-2 logarithms of powers of two",
"input": "values = [1 2 4 8];\npowers = log2(values)",
"output": "powers = [0 1 2 3]"
},
{
"description": "Understanding how `log2` handles zero",
"input": "z = log2(0)",
"output": "z = -Inf"
},
{
"description": "Working with negative inputs using complex results",
"input": "neg = [-1 -2];\nout = log2(neg)",
"output": "out = [0.0000 + 4.5324i 1.0000 + 4.5324i]"
},
{
"description": "Checking power-of-two exponents for matrix sizes",
"input": "A = [64 128; 256 512];\nexponents = log2(A)",
"output": "exponents = [6 7; 8 9]"
},
{
"description": "Running `log2` on GPU-resident data",
"input": "G = gpuArray([1 4 16 64]);\nresult = log2(G);\nhost = gather(result)",
"output": "host = [0 2 4 6]"
},
{
"description": "Applying `log2` to character codes",
"input": "C = 'ABC';\nvalues = log2(C)",
"output": "values = [6.0224 6.0444 6.0661]"
}
],
"faqs": [
{
"question": "When should I use `log2` instead of `log` or `log10`?",
"answer": "Use `log2` when you care about binary scalings—such as signal-processing bit widths, FFT sizes, or exponent analysis. Use `log` (natural logarithm) for exponential growth/decay and `log10` for decimal magnitudes."
},
{
"question": "What happens if an element is zero?",
"answer": "`log2(0)` returns negative infinity (`-Inf`), matching MATLAB behavior."
},
{
"question": "How does `log2` handle negative real numbers?",
"answer": "Negative values promote to complex numbers with an imaginary component of `Ï€/ln(2)`. This preserves phase information instead of producing `NaN`."
},
{
"question": "Can I pass complex inputs to `log2`?",
"answer": "Yes. Complex scalars and tensors are handled as `log(z) / ln(2)`, 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 `log2` 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": "log10",
"url": "./log10"
},
{
"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": "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/log2.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/log2.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_log2` and the data is known to remain 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."
]
}