RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the pow2 function do in MATLAB / RunMat?

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.

pow2 Function GPU Execution Behaviour

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.

Examples of using the pow2 function 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 (rounded):

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 = [5.9874e+41 1.2946e+42 2.7992e+42];

GPU residency in RunMat (Do I need gpuArray?)

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.

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