acos — Element-wise inverse cosine in MATLAB and RunMat, with complex promotion outside [-1, 1].
Y = acos(X) computes the inverse cosine (in radians) of each element in X. Real values in [-1, 1] return real outputs; values outside that interval promote to complex outputs, consistent with MATLAB behavior.
Syntax
Y = acos(X)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Single/double real or complex input; integer, logical, and character forms are RunMat-only extensions. |
Returns
| Name | Type | Description |
|---|---|---|
Y | Any | Element-wise inverse cosine result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:acos:InvalidInput | Input cannot be interpreted as supported numeric/char/complex data. | acos: invalid input |
RunMat:acos:Internal | Internal gather/reduction/conversion/allocation flow failed. | acos: internal error |
RunMat:acos:TooManyOutputs | More than one output is requested. | acos: too many output arguments |
How acos works
- Operates on scalars, vectors, matrices, and N-D tensors using MATLAB broadcasting rules.
- The documented table and timetable overloads are not yet implemented in RunMat.
- Documented single inputs preserve native single or complex-single storage; double inputs preserve double or complex-double storage.
- Typed-integer, logical, and character inputs are RunMat-only extensions. They enter an explicit double computation boundary and preserve input shape.
- Real inputs with magnitude greater than
1yield 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.
Does RunMat run acos on the GPU?
RunMat Accelerate keeps tensors on the GPU when a provider implements unary_acos and the extremum reductions prove that every element lies in [-1, 1]. Missing floating hooks use an owner-preserving gather fallback. Real resident input that requires complex promotion is rejected in MATLAB-compatible modes and is an explicit RunMat-only extension that restores the complex result to the owning provider.
GPU memory and residency
The fusion planner keeps documented floating inputs on the GPU whenever the active provider exposes unary_acos and the values remain within the real domain. Unsupported hooks use owner-preserving fallback. RunMat mode also permits real resident input that requires complex promotion and restores the complex result to the same provider.
Examples
Computing the inverse cosine of a scalar angle
y = acos(0.5)Expected output:
y = 1.0472Handling values outside [-1, 1] that produce complex results
z = acos(2)Expected output:
z = 0.0000 - 1.3170iApplying 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.4981Computing inverse cosine values from logical input
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.7009iUsing acos with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how acos changes the result.
Run a small acos example, explain the result, then change one input and compare the output.
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. Unsupported real-domain hooks use an owner-preserving fallback.
How are logical or integer inputs handled?⌄
They are outside the documented single/double data domain. RunMat mode retains logical and all-eight-class integer inputs as explicit extensions and converts them to double at the inverse-cosine computation boundary.
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?⌄
The public GPU contract requires potentially complex results to start from explicitly complex input. RunMat mode additionally supports real resident input that needs complex promotion, gathering and re-uploading the complex result to the same provider.
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 Math functions
Trigonometry
acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how acos is executed, line by line, in Rust.
- View the source for acos in Rust on GitHub
- Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.