RunMat
GitHub

View all functions

CategoryMath: Trigonometry
GPUYes

What does the asin function do in MATLAB / RunMat?

Y = asin(X) computes the inverse sine (in radians) of every element of X. Results follow MATLAB semantics for real, logical, character, and complex inputs. Real values outside the [-1, 1] interval transparently promote to complex outputs so that the mathematical definition remains exact.

How does the asin function behave in MATLAB / RunMat?

  • Accepts scalars, vectors, matrices, and N-D tensors and applies the operation element-wise with MATLAB broadcasting rules.
  • Logical inputs convert to doubles (true → 1.0, false → 0.0) before the inverse sine is taken.
  • Character arrays are interpreted as their numeric code points and return dense double or complex tensors, depending on the result.
  • Real inputs with magnitude greater than 1 produce 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.

asin Function GPU Execution Behaviour

RunMat Accelerate keeps tensors on the GPU when:

  1. A provider is registered and implements unary_asin, reduce_min, and reduce_max.
  2. The runtime can prove that every element lies within the real domain [-1, 1].

If any of those hooks are missing, or if the bounds check cannot run (for example, because the provider does not support the min/max reductions for the current tensor layout), RunMat falls back to the host implementation automatically so the results remain correct.

When either condition fails—most notably when the input requires complex promotion—the runtime gathers the data to the host, computes the MATLAB-compatible result, and returns a host-resident (or complex) value. This mirrors MATLAB's behaviour without forcing users to manually call gpuArray or gather.

Examples of using the asin function in MATLAB / RunMat

Inverse sine of a scalar angle

y = asin(0.5);

Expected output:

y = 0.5236

Inverse sine of values greater than one (complex output)

z = asin(1.2);

Expected output:

z = 1.5708 - 0.6224i

Compute 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.9273

Handling logical input with automatic double promotion

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.7854 0 0.7854 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.4829 + 0.7676i

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 the unary_asin hook and the inputs remain within [-1, 1]. When complex promotion is required, RunMat gathers the data and returns the correct complex result automatically. Manual gpuArray / gather calls remain available for workflows that need explicit residency control.

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?

Logical arrays convert to doubles (0 or 1). Integers convert to double precision before evaluation, mirroring MATLAB and avoiding overflow. The final result is double or complex depending on the data.

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?

Complex results are currently returned on the host because GPU tensor handles represent real data. The runtime gathers automatically and returns Value::Complex/Value::ComplexTensor, guaranteeing correct MATLAB semantics.

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.

See Also

sin, acos, atan, gpuArray, gather

Source & Feedback