RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the power function do in MATLAB / RunMat?

Y = power(A, B) (or A .^ B) raises each element of A to the corresponding element of B using MATLAB's implicit-expansion rules. Scalars broadcast automatically, and complex inputs produce complex outputs that match MATLAB behaviour.

How does the power function behave in MATLAB / RunMat?

  • Supports scalars, vectors, matrices, and N-D tensors with the same shape or compatible singleton dimensions. Size mismatches raise the standard MATLAB error.
  • Logical and character inputs are promoted to double precision before powering ('A'.^2 uses the Unicode code points of the characters).
  • Complex bases and/or exponents follow the analytic identity z.^w = exp(w * log(z)), so negative bases with fractional exponents return complex results instead of NaN.
  • Empty tensors propagate emptiness; the result uses the broadcasted size.
  • The optional 'like', prototype arguments mirror the numeric flavour and residency (host vs gpuArray) of prototype, just like MATLAB.

power Function GPU Execution Behaviour

  • When both operands are gpuArrays with identical shapes, RunMat calls the provider's elem_pow hook. The WGPU backend uses a fused WGSL kernel, and the in-process provider executes on host data without leaving the GPU abstraction.
  • If only one operand lives on the GPU and the other is a scalar, RunMat materialises a device buffer for the scalar and still uses elem_pow.
  • Implicit expansion, complex operands, and providers that lack elem_pow automatically fall back to the host implementation. Results respect 'like' residency hints, re-uploading to the GPU when requested.

Examples of using the power function in MATLAB / RunMat

Raise a scalar to a power

y = power(2, 5);

Expected output:

y = 32

Compute element-wise powers of a matrix

A = [1 2 3; 4 5 6];
B = power(A, 2);

Expected output:

B =
     1     4     9
    16    25    36

Broadcast exponents across rows

base = (1:3)';
exponent = [1 2 3];
result = power(base, exponent);

Expected output:

result =
     1     1     1
     2     4     8
     3     9    27

Generate complex powers from negative bases

values = power([-2 -1 0 1 2], 0.5);

Expected output (rounded):

values = [0.0000 + 1.4142i, 0.0000 + 1.0000i, 0, 1, 1.4142]

Keep GPU results with a 'like' prototype

proto = gpuArray.zeros(1, 1, 'single');
x = [1 2 3];
y = [2 3 4];
devicePowers = power(x, y, 'like', proto);
result = gather(devicePowers);

Expected output:

devicePowers =
  1x3 gpuArray  single
     1     8    81
result =
     1     8    81

Convert character codes before powering

codes = power('ABC', 2);

Expected output:

codes = [4225 4356 4489]

GPU residency in RunMat (Do I need gpuArray?)

Most workflows do not require manual gpuArray calls. RunMat's auto-offload and fusion planner keep chains of element-wise operations on the GPU whenever the provider can satisfy them. When an operation needs a fallback (implicit expansion, complex inputs, or unsupported kernels), RunMat transparently gathers to the host, computes the MATLAB-accurate result, and honours any 'like' residency hints you supplied.

FAQ

Does power support MATLAB implicit expansion?

Yes. Singleton dimensions expand automatically, and size mismatches raise a dimension error with the usual MATLAB wording.

What numeric type does power return?

Real inputs produce doubles. Results promote to complex doubles whenever the exponentiation would leave the real line (for example (-2).^0.5 or complex exponents).

Can I mix scalars and arrays?

Absolutely. Scalars broadcast to match the other operand. This includes scalar gpuArrays.

What happens if only one operand is on the GPU?

If the other operand is a scalar, RunMat keeps everything on the GPU. Otherwise, it gathers the device operand, performs the computation on the host, and returns a host tensor (unless 'like' instructs the runtime to re-upload the result).

Does power modify the inputs in-place?

No. The builtin always allocates a fresh tensor (or complex tensor). Fusion can eliminate temporary allocations when the expression continues with other element-wise operations.

Can I force the result to stay on the GPU?

Yes—pass 'like', gpuArrayPrototype. The runtime mirrors the residency of the prototype and uploads the result when necessary.

See Also

.^ operator, times, rdivide, ldivide, pow2, gpuArray, gather

Source & Feedback