RunMat
GitHub

View all functions

CategoryMath: Trigonometry
GPUYes

What does the acos function do in MATLAB / RunMat?

Y = acos(X) computes the inverse cosine (in radians) of every element of X. Results match MATLAB semantics for real, logical, character, and complex inputs. Real values outside the interval [-1, 1] promote to complex outputs automatically so the mathematical definition remains valid over the complex plane.

How does the acos function behave in MATLAB / RunMat?

  • Operates on scalars, vectors, matrices, and N-D tensors using MATLAB broadcasting rules.
  • Logical inputs convert to double precision (true → 1, false → 0) before applying inverse cosine.
  • Character arrays are interpreted as their numeric code points and return dense double or complex tensors that mirror MATLAB’s output.
  • Real inputs with magnitude greater than 1 yield complex results (acos(2) → 0 - 1.3170i), matching MATLAB’s principal branch.
  • Complex inputs follow MATLAB's definition acos(z) = -i log(z + i sqrt(1 - z^2)), ensuring identical behaviour for branch cuts and special values.
  • NaNs and Infs propagate in the same way MATLAB does, including complex infinities when necessary.

acos Function GPU Execution Behaviour

RunMat Accelerate keeps tensors on the GPU when:

  1. A provider is registered and implements unary_acos as well as the extremum reductions used to confirm the input domain.
  2. Every element is provably within the real domain [-1, 1].

If either condition fails (for example, when a complex result is required or the provider lacks supporting reductions), the runtime gathers the data to the host, computes the MATLAB-compatible answer, and returns the correct result without user intervention. Manual gpuArray / gather calls remain optional for explicit residency control.

Examples of using the acos function in MATLAB / RunMat

Computing the inverse cosine of a scalar angle

y = acos(0.5);

Expected output:

y = 1.0472

Handling values outside [-1, 1] that produce complex results

z = acos(2);

Expected output:

z = 0.0000 - 1.3170i

Applying inverse cosine to every element of a matrix

A = [0 -0.5 0.75; 1 0.25 -0.8];
Y = acos(A);

Expected output:

Y =
    1.5708    2.0944    0.7227
         0    1.3181    2.4981

Using logical input with automatic double promotion

mask = logical([0 1 0 1]);
angles = acos(mask);

Expected output:

angles = [1.5708 0 1.5708 0]

Running acos on a GPU array without explicit transfers

G = gpuArray(linspace(-1, 1, 5));
result_gpu = acos(G);
result = gather(result_gpu);

Expected output:

result = [3.1416 2.0944 1.5708 1.0472 0.0000]

Evaluating inverse cosine of complex numbers

vals = [0.5 + 1i, -0.2 + 0.75i];
w = acos(vals);

Expected output:

w =
   1.2214 - 0.9261i
   1.7307 - 0.7009i

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to call gpuArray explicitly. The fusion planner keeps tensors on the GPU whenever the active provider exposes unary_acos and the values remain within the real domain. When complex promotion is necessary, RunMat gathers the tensor automatically and returns the MATLAB-compatible complex result. Manual residency control remains available for workflows that require it.

FAQ

Why does acos sometimes return complex numbers?

Inputs with magnitude greater than 1 lie outside the real domain, so MATLAB (and RunMat) return complex results computed from the principal branch of the inverse cosine.

Does acos support GPU execution?

Yes. When the provider implements unary_acos and exposes min/max reductions for the domain check, the runtime executes acos entirely on the GPU. Otherwise, it gathers to the host transparently.

How are logical or integer inputs handled?

Logical arrays convert to doubles before evaluation. Integers also promote to double precision so the computation matches MATLAB and avoids overflow concerns.

What happens with NaN or Inf values?

NaNs propagate through the computation. Inputs of ±Inf produce complex infinities exactly as in MATLAB.

Can I keep the result on the GPU if it becomes complex?

Complex results are currently returned on the host because GPU tensor handles represent real data. The runtime gathers automatically and returns Value::Complex or Value::ComplexTensor, preserving correctness.

Does acos fuse with other element-wise operations?

Yes. The fusion planner can emit WGSL kernels that include acos when the provider supports the generated path, allowing fused GPU execution without intermediate buffers.

See Also

asin, cos, sin, gpuArray, gather

Source & Feedback