asin — Compute elementwise principal inverse sine in radians with value-dependent complex promotion.
asin preserves floating precision and shape, promotes out-of-domain real values to the principal complex result, and retains supported provider residency.
Syntax
Y = asin(X)Inputs
X- Type
Any- Required
- Yes
- Description
- Single or double real/complex input; integer, logical, and character forms are RunMat-only extensions.
Returns
Y- Type
NumericArray- Description
- Elementwise principal inverse-sine result in radians.
Errors
RunMat:asin:InvalidInput- When
- Input is not a supported numeric, logical, or character value.
- Message
asin: invalid input
RunMat:asin:Internal- When
- Internal reduction, gather, conversion, allocation, or provider restoration failed.
- Message
asin: internal error
RunMat:asin:TooManyOutputs- When
- More than one output is requested.
- Message
asin: too many output arguments
Behavior
asin(X) computes the principal inverse sine of each element in radians. Real values in [-1, 1] return real results. A real value outside that interval produces a complex result; if any element of a real array requires promotion, the whole result uses complex storage.
Real and complex single input returns single-precision storage, while real and complex double input returns double precision. The operation preserves scalar, vector, matrix, empty, and N-D shape. Complex input follows the principal branch of the analytic inverse sine. NaN and infinity follow the corresponding floating and complex arithmetic.
RunMat extensions
RunMat mode accepts all eight real fixed-width integer classes, logical arrays, and character arrays. These forms cross an explicit binary64 computation boundary and return double or complex double. Character elements are interpreted as Unicode scalar values; values above one therefore produce complex results.
Explicit gpuArray real input that requires a complex result is also a RunMat extension. MATLAB compatibility modes require potentially complex gpuArray input to be explicitly complex. Strings, sparse arrays, typed complex integers, direct table/timetable overloads, and tall containers are rejected. Execution-owned distributed arrays use the catalog's unary mapping policy.
GPU execution and fusion
Automatic placement of host floating arrays is available for values proven to remain in the real domain. Arrays outside that domain or containing NaN retain the host route. Automatic residency does not impose gpuArray-specific compatibility restrictions: an automatically resident input that needs complex output returns the host complex result. The owner-preserving GPU behavior below applies to explicitly resident input.
For floating real input, RunMat checks the domain with provider reductions. Values proven to remain in [-1, 1] can use the provider's unary inverse-sine operation and stay resident. Missing hooks and results that require complex promotion gather through the input's owner, compute on the host, and return to that same owner and device.
Fusion is disabled because a real-only shader expression would return NaN where the language requires complex promotion. Provider execution remains available for calls whose runtime domain probe proves that every value is in [-1, 1].
Examples
Compute inverse sine of a scalar
y = asin(0.5)Expected output:
y = 0.5236Promote real input outside the unit interval
z = asin(1.2)Expected output:
z = 1.5708 - 0.6224iApply inverse sine elementwise
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.9273Evaluate logical values in RunMat mode
mask = logical([0 1 1 0]);
angles = asin(mask)Expected output:
angles = [0 1.5708 1.5708 0]Keep an in-domain result on its provider
G = gpuArray(linspace(-1, 1, 5));
resultGpu = asin(G);
result = gather(resultGpu)Expected output:
result = [-1.5708 -0.5236 0 0.5236 1.5708]Evaluate complex input on the principal branch
values = [1+2i, -0.5+0.75i];
w = asin(values)Expected output:
w is a 1-by-2 complex row vectorUsing 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?⌄
The principal inverse sine is defined on the complex plane. A real input outside [-1, 1] has no real inverse-sine value, so the result is complex.
Does asin support GPU execution?⌄
Yes. In-domain floating input can use a provider's inverse-sine and reduction operations. Other supported resident forms use owner-preserving host fallback.
How does asin treat logical or integer input?⌄
RunMat mode accepts them as explicit extensions. Their values convert to double at the inverse-sine algorithm boundary, and the result is double or complex double.
What happens with NaN or Inf?⌄
NaN propagates. Positive and negative infinity produce the principal complex results defined by the floating complex implementation.
Can a complex result remain provider-resident?⌄
In RunMat mode, yes. The runtime gathers real input that needs promotion, computes the complex result on the host, and uploads it to the original owner and device.
Why does asin of a character array return numeric data?⌄
Character input is a RunMat extension that applies inverse sine to each Unicode scalar value. The output is therefore double or complex double rather than character data.
Does asin fuse with surrounding operations?⌄
No. The current fusion contract keeps asin as a boundary because real input can require complex output. In-domain provider execution is still available outside fusion.
Can CPU and GPU results differ slightly?⌄
They can differ within the normal error of the selected floating precision and provider implementation, especially near the domain endpoints.
Related Math functions
Trigonometry
acos · acosd · acosh · acotd · acscd · asecd · asind · asinh · atan · atan2 · atan2d · atand · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Elementwise
abs · angle · besselj · bsxfun · complex · conj · double · eps · erf · erfcinv · exp · expm1 · flintmax · gamma · gammaln · heaviside · hypot · imag · int16 · int32 · int64 · int8 · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · times · typecast · uint16 · uint32 · uint64 · uint8
Optim
acceptancesa · annealingboltz · annealingfast · coneprog · crossoverarithmetic · crossoverheuristic · crossoverintermediate · crossoverlaplace · crossoverscattered · crossoversinglepoint · crossovertwopoint · eqnproblem · EquationProblem.solve · EquationProblem.subsasgn · EquationProblem.subsref · evaluate · fgoalattain · fitscalingprop · fitscalingrank · fitscalingshiftlinear · fitscalingtop · fminbnd · fmincon · fminimax · fminsearch · fminunc · fseminf · fsolve · fzero · ga · gacreationlinearfeasible · gacreationnonlinearfeasible · gacreationsobol · gacreationuniform · gacreationuniformint · gaplotbestf · gaplotbestindiv · gaplotdistance · gaplotexpectation · gaplotgenealogy · gaplotmaxconstr · gaplotrange · gaplotscorediversity · gaplotscores · gaplotselection · gaplotstopping · integerConstraint · integral · intlinprog · linprog · lsqcurvefit · lsqlin · LsqlinWarmStart.subsasgn · LsqlinWarmStart.subsref · lsqnonlin · lsqnonneg · mutationadaptfeasible · mutationgaussian · mutationpositivebasis · mutationpower · mutationuniform · optimexpr · optimget · OptimizationConstraint.evaluate · OptimizationConstraint.subsasgn · OptimizationConstraint.subsref · OptimizationExitflag.double · OptimizationExitflag.eq · OptimizationExitflag.ne · OptimizationExitflag.string · OptimizationExpression.acos · OptimizationExpression.acosh · OptimizationExpression.acot · OptimizationExpression.acoth · OptimizationExpression.acsc · OptimizationExpression.acsch · OptimizationExpression.asec · OptimizationExpression.asech · OptimizationExpression.asin · OptimizationExpression.asinh · OptimizationExpression.atan · OptimizationExpression.atanh · OptimizationExpression.cat · OptimizationExpression.cos · OptimizationExpression.cosh · OptimizationExpression.cot · OptimizationExpression.coth · OptimizationExpression.csc · OptimizationExpression.csch · OptimizationExpression.ctranspose · OptimizationExpression.cumprod · OptimizationExpression.cumsum · OptimizationExpression.diag · OptimizationExpression.diff · OptimizationExpression.dot · OptimizationExpression.eq · OptimizationExpression.evaluate · OptimizationExpression.exp · OptimizationExpression.ge · OptimizationExpression.horzcat · OptimizationExpression.ldivide · OptimizationExpression.le · OptimizationExpression.log · OptimizationExpression.mean · OptimizationExpression.minus · OptimizationExpression.mldivide · OptimizationExpression.mpower · OptimizationExpression.mrdivide · OptimizationExpression.mtimes · OptimizationExpression.norm · OptimizationExpression.plus · OptimizationExpression.power · OptimizationExpression.prod · OptimizationExpression.rdivide · OptimizationExpression.reshape · OptimizationExpression.sec · OptimizationExpression.sech · OptimizationExpression.sin · OptimizationExpression.sinh · OptimizationExpression.sqrt · OptimizationExpression.subsasgn · OptimizationExpression.subsref · OptimizationExpression.sum · OptimizationExpression.tan · OptimizationExpression.tanh · OptimizationExpression.times · OptimizationExpression.trace · OptimizationExpression.transpose · OptimizationExpression.uminus · OptimizationExpression.uplus · OptimizationExpression.vertcat · OptimizationExpression.zeros · OptimizationExpression.zerosLike · OptimizationProblem.solve · OptimizationProblem.subsasgn · OptimizationProblem.subsref · OptimizationVariable.subsasgn · OptimizationVariable.subsref · optimoptions · optimplotconstrviolation · optimplotfirstorderopt · optimplotfunccount · optimplotfval · optimplotfvalconstr · optimplotmilp · optimplotstepsize · optimplotx · optimproblem · optimset · optimvar · optimwarmstart · particleswarm · patternsearch · psplotbestf · psplotbestx · psplotfuncount · psplotmaxconstr · psplotmeshsize · pswcreationuniform · pswplotbestf · quad · quadprog · QuadprogWarmStart.subsasgn · QuadprogWarmStart.subsref · saplotbestf · saplotbestx · saplotf · saplotstopping · saplottemperature · saplotx · savemilpsolutions · secondordercone · selectionremainder · selectionroulette · selectionstochunif · selectiontournament · selectionuniform · simulannealbnd · solve · surrogateopt · surrogateoptplot · temperatureboltz · temperatureexp · temperaturefast
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
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Interpolation
griddedInterpolant · griddedInterpolant.subsref · interp1 · interp1q · interp2 · pchip · ppval · spline
Integer Division
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.