acos — Element-wise inverse cosine with MATLAB-compatible complex promotion and GPU fallbacks.

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 acos works in 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.

How acos runs on the GPU

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.

GPU memory and residency

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.

Examples

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

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.

Related functions to explore

These functions work well alongside acos. Each page has runnable examples you can try in the browser.

asin, cos, sin, gpuArray, gather, acosh, asinh, atan, atan2, atanh, cosh, sinh, tan, tanh

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how acos works, line by line, in Rust.

• View acos.rs on GitHub
• Learn how the runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing