RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

pow2 — Compute 2.^X or scale mantissas by binary exponents with MATLAB-compatible semantics.

Y = pow2(X) computes the element-wise power-of-two 2.^X. With two inputs, Z = pow2(F, E) returns the element-wise product F .* 2.^E, mirroring MATLAB's ldexp-style scaling.

How does the pow2 function behave in MATLAB / RunMat?

  • Accepts scalars, vectors, matrices, and N-D tensors with MATLAB's implicit expansion (broadcasting).
  • Logical inputs are promoted to double before applying 2.^X.
  • Character arrays operate on their Unicode code points and return dense double tensors.
  • Complex exponents yield complex outputs using the identity 2^z = exp(z * ln(2)).
  • pow2(F, E) supports scalar expansion on either argument and raises a dimension mismatch error when expansion is impossible.
  • Empty tensors propagate emptiness with the correct MATLAB-visible shape.

GPU behavior

When tensors already reside on the GPU, RunMat Accelerate tries the following:

1. **Unary form (pow2(X)):** Calls the provider hook unary_pow2. If the hook is unavailable, the runtime gathers X, computes on the host, and returns a CPU-resident tensor. 2. **Binary form (pow2(F, E)):** Calls pow2_scale(F, E) when both operands share identical shapes. Providers can implement a fused kernel (see the WGPU backend for an example). If the hook is missing or shapes require implicit expansion, RunMat gathers both tensors and performs the CPU implementation, guaranteeing MATLAB-compatible semantics.

Future providers can extend pow2_scale to support in-device broadcasting. Until then, fallbacks kick in transparently without user involvement.

GPU residency

Explicit gpuArray calls are rarely needed. The acceleration planner keeps tensors on the GPU whenever providers handle unary_pow2 / pow2_scale. When hooks are missing, the runtime gathers data, executes on the CPU, and continues seamlessly. You can still use gpuArray / gather to mirror MATLAB workflows or to interoperate with custom kernels.

Examples of using pow2 in MATLAB / RunMat

Compute power-of-two for scalar exponents

y = pow2(3)

Expected output:

y = 8

Apply pow2 to a vector of exponents

exponents = [-1 0 1 2];
values = pow2(exponents)

Expected output:

values = [0.5 1 2 4]

Scale mantissas by binary exponents

mantissa = [0.75 1.5];
exponent = [4 5];
scaled = pow2(mantissa, exponent)

Expected output:

scaled = [12 48]

Use complex exponents with pow2

z = pow2(1 + 2i)

Expected output:

z = -0.3667 + 0.8894i

Run pow2 on GPU arrays

G = gpuArray([1 2 3]);
result_gpu = pow2(G);
result = gather(result_gpu)

Expected output:

result = [2 4 8]

Convert characters to power-of-two values

codes = pow2('ABC')

Expected output:

codes = [3.6893e+19 7.3787e+19 1.4757e+20]

FAQ

Does pow2 overflow for large exponents?

Results follow IEEE arithmetic. Very large positive exponents produce Inf; very negative exponents underflow to zero.

How are logical inputs handled?

Logical values convert to doubles (true → 1, false → 0) before applying the power.

Can I mix scalars and arrays?

Yes. MATLAB's implicit expansion applies: singleton dimensions expand to match the other operand.

What happens with complex inputs?

Complex exponents and/or mantissas produce complex outputs using exp((re + i·im) * ln(2)).

Will GPU and CPU results differ?

Double-precision providers match CPU results bit-for-bit. Single-precision providers may differ by expected floating-point round-off.

Does pow2(F,E) allocate a new array?

Yes. The builtin returns a fresh tensor (or complex tensor). Fusion can remove intermediates when the expression is part of a larger GPU kernel.

Can I use pow2 for bit shifting?

Yes. pow2(F, E) mirrors ldexp, scaling mantissas by powers of two. Integer mantissas reproduce MATLAB's bit-shift style scaling in floating point.

See also

exp, log2, log, gpuArray, gather

Source & Feedback