asin — Element-wise inverse sine in MATLAB and RunMat, with complex promotion outside [-1, 1].
Y = asin(X) computes the inverse sine (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 = asin(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 sine result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:asin:InvalidInput | Input cannot be interpreted as supported numeric/char/complex data. | asin: invalid input |
RunMat:asin:Internal | Internal gather/reduction/conversion/allocation flow failed. | asin: internal error |
RunMat:asin:TooManyOutputs | More than one output is requested. | asin: too many output arguments |
How asin works
- Accepts scalars, vectors, matrices, and N-D tensors and applies the operation element-wise with 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
1produce complex results identical to MATLAB (asin(1.2) → 1.5708 - 0.6224i). - Complex inputs follow MATLAB's principal branch definitions using
asin(z) = -i log(iz + sqrt(1 - z^2)). - NaNs and infinities propagate according to IEEE arithmetic and match MATLAB's edge cases.
Does RunMat run asin on the GPU?
RunMat Accelerate keeps tensors on the GPU when a provider implements unary_asin, reduce_min, and reduce_max and the 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_asin and the inputs remain within [-1, 1]. 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
Inverse sine of a scalar angle
y = asin(0.5)Expected output:
y = 0.5236Inverse sine of values greater than one (complex output)
z = asin(1.2)Expected output:
z = 1.5708 - 0.6224iCompute arcsine of every element in a matrix
A = [0 -0.5 0.75; 1 0.25 -0.8];
Y = asin(A)Expected output:
Y =
0 -0.5236 0.8481
1.5708 0.2527 -0.9273Computing inverse sine values from logical input
mask = logical([0 1 1 0]);
angles = asin(mask)Expected output:
angles = [0 1.5708 1.5708 0]Computing asin on a GPU array and keeping the result on device
G = gpuArray(linspace(-1, 1, 5));
result_gpu = asin(G);
result = gather(result_gpu)Expected output:
result = [-1.5708 -0.5236 0 0.5236 1.5708]Evaluating inverse sine of complex numbers
vals = [1+2i, -0.5+0.75i];
w = asin(vals)Expected output:
w =
0.4271 + 1.5286i
-0.3983 + 0.7433iUsing asin with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how asin changes the result.
Run a small asin example, explain the result, then change one input and compare the output.
FAQ
Why does asin sometimes return complex numbers?⌄
MATLAB (and RunMat) define inverse sine on the complex plane. Real inputs with magnitude greater than 1 lie outside the real domain, so the correct answer is complex. RunMat matches MATLAB's principal branch, yielding identical results.
Does asin support GPU execution?⌄
Yes. When a provider implements unary_asin and exposes reduction hooks for bounds checking, the runtime executes asin entirely on the device. If complex promotion is required, RunMat gathers to the host to stay mathematically correct.
How does asin treat logical or integer inputs?⌄
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-sine computation boundary.
What happens with NaN or Inf values?⌄
NaNs propagate through the computation. Inputs of ±Inf produce complex infinities consistent with MATLAB's handling of special values.
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.
Why does asin of a character array return numeric arrays?⌄
Character arrays are interpreted as their Unicode code points, converted to doubles, and then the inverse sine is applied. Any element outside [-1, 1] may promote the whole array to complex— matching MATLAB behaviour.
Does asin fuse with surrounding element-wise operations?⌄
Yes. The fusion planner can emit fused WGSL kernels that include asin as long as the provider supports the generated code path. When fused, asin participates in GPU auto-offload decisions like other unary operations.
Are there precision differences between CPU and GPU paths?⌄
Both CPU and GPU implementations operate in the provider's precision (f32 or f64). Results match within normal floating-point error tolerances. For values near the domain boundary ±1, minor rounding differences may appear but stay within MATLAB compatibility requirements.
Related Math functions
Trigonometry
acos · acosh · 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 asin is executed, line by line, in Rust.
- View the source for asin 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.