RunMat
GitHub

View all functions

CategoryMath: Trigonometry
GPUYes

What does the acosh function do in MATLAB / RunMat?

Y = acosh(X) evaluates the inverse hyperbolic cosine of each element in X. Real inputs greater than or equal to 1 stay real; values below 1 automatically promote to complex results that match MATLAB's principal branch.

How does the acosh function behave in MATLAB / RunMat?

  • Accepts scalars, vectors, matrices, and N-D tensors with MATLAB broadcasting semantics.
  • Logical inputs are promoted to double precision (true → 1, false → 0) before evaluation.
  • Character arrays are interpreted as their numeric code points. If any element is less than 1, the result becomes a complex array, mirroring MATLAB.
  • Real values in [1, ∞) return real outputs computed by acosh.
  • Real values in (-∞, 1) produce complex results: the runtime returns Value::Complex or Value::ComplexTensor so that downstream code sees the same behaviour as MATLAB.
  • Complex inputs follow MATLAB's definition acosh(z) = \log(z + \sqrt{z-1}\sqrt{z+1}), including NaN/Inf handling on branch cuts.
  • Special values propagate exactly like MATLAB: acosh(NaN) = NaN, acosh(Inf) = Inf, and acosh(-Inf) = Inf + i·π.

acosh Function GPU Execution Behaviour

RunMat Accelerate keeps tensors on the GPU when:

  1. A provider is registered and implements the unary_acosh hook.
  2. Every element is provably within the real domain (that is, all elements ≥ 1).
  3. All inputs are finite; NaN or -Inf values force a host fallback so complex promotion and branch-cut semantics remain correct.

The runtime calls reduce_min on the active provider to perform this domain check. If the provider does not expose the hook, the reduction fails, or any element violates the conditions above, RunMat falls back to the host, evaluates acosh with the CPU reference implementation, and returns results identical to MATLAB. This ensures correctness without forcing users to manually gather tensors.

Examples of using the acosh function in MATLAB / RunMat

Inverse hyperbolic cosine of a scalar greater than one

y = acosh(1.5);

Expected output:

y = 0.9624

Applying acosh to each element of a vector

x = [1 1.5 2 4];
y = acosh(x);

Expected output:

y = [0 0.9624 1.31696 2.06344]

Handling elements below one that produce complex results

values = [0.5 1 2];
z = acosh(values);

Expected output:

z =
   0.0000 + 1.0472i   0.0000 + 0.0000i   1.31696 + 0.0000i

Computing acosh on GPU-resident data when the domain stays real

G = gpuArray(linspace(1, 5, 5));
result_gpu = acosh(G);
result = gather(result_gpu);

Expected output:

result = [0 1.31696 1.76275 2.06344 2.29243]

Evaluating acosh for complex numbers

z = [1 + 2i, -2 + 0.5i];
w = acosh(z);

Expected output:

w =
   1.5286 + 1.1437i
   1.3090 + 2.3910i

Working with character arrays (mix of complex and real results)

C = char([0 65]);   % includes a code point below 1
Y = acosh(C);

Expected output:

Y =
   0.0000 + 1.5708i   4.8675 + 0.0000i

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to call gpuArray manually. The auto-offload planner keeps tensors on the GPU whenever the provider exposes unary_acosh and the input stays within the real domain. When complex promotion is needed, RunMat gathers automatically and still returns MATLAB-compatible results. Manual gpuArray / gather remains available for workflows that require explicit residency control.

FAQ

Why does acosh sometimes return complex numbers?

The real-valued inverse hyperbolic cosine is only defined for x ≥ 1. Inputs below that range require complex results, so RunMat (like MATLAB) promotes them automatically.

Can acosh run entirely on the GPU?

Yes—when all elements are ≥ 1 and the provider implements unary_acosh, the runtime executes the operation on the GPU. Otherwise, it falls back to the host transparently.

How are NaN or Inf values handled?

acosh(NaN) returns NaN. Positive infinity stays real infinity. Negative infinity produces the same complex result as MATLAB (Inf + i·π).

Do logical and integer inputs work?

Yes. They are promoted to double precision before evaluation. The output is a dense double (or complex double) array following MATLAB semantics.

Can I keep complex results on the GPU?

Currently, GPU tensors represent real data. When complex outputs are required, the runtime gathers to the host and returns Value::Complex / Value::ComplexTensor for correctness.

Does acosh participate in fusion?

Yes. The fusion planner treats acosh as an element-wise operation and can inline it into fused WGSL kernels when the provider supports the generated code.

What tolerance does the runtime use to decide GPU fallback?

Any element below 1 triggers a host fallback so the runtime can return the correct complex result. This mirrors MATLAB exactly instead of relying on GPU intrinsics that would otherwise yield NaN.

Can acosh be differentiated automatically?

Yes. Marking it as an element-wise builtin ensures future autodiff tooling can reuse the same metadata to generate gradients.

See Also

asinh, tanh, cosh, gpuArray, gather

Source & Feedback