acosh — Element-wise inverse hyperbolic cosine in MATLAB and RunMat, with complex promotion for x < 1.
Y = acosh(X) evaluates the inverse hyperbolic cosine of each element in X. Real inputs greater than or equal to 1 remain real, while values below 1 promote to complex outputs following the MATLAB/RunMat principal branch.
Syntax
Y = acosh(X)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input scalar, array, char array, complex value, or gpuArray. |
Returns
| Name | Type | Description |
|---|---|---|
Y | Any | Element-wise inverse hyperbolic cosine result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:acosh:InvalidInput | Input cannot be interpreted as supported numeric/char/complex data. | acosh: invalid input |
RunMat:acosh:Internal | Internal gather/reduction/conversion/allocation/provider flow failed. | acosh: internal error |
How acosh works
- 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 byacosh. - Real values in
(-∞, 1)produce complex results: the runtime returnsValue::ComplexorValue::ComplexTensorso 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, andacosh(-Inf) = Inf + i·π.
Does RunMat run acosh on the GPU?
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.
GPU memory and residency
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.
Examples
Inverse hyperbolic cosine of a scalar greater than one
y = acosh(1.5)Expected output:
y = 0.9624Applying 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.0000iComputing 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.76274 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.3618 + 2.8638iWorking 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.0000iUsing acosh with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how acosh changes the result.
Run a small acosh example, explain the result, then change one input and compare the output.
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.
Related Math functions
Trigonometry
acos · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · deg2rad · rad2deg · sin · sind · sinh · tan · tand · tanh
Elementwise
abs · angle · complex · conj · double · exp · expm1 · factorial · gamma · hypot · imag · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · sign · single · sqrt · times
Reduction
all · any · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · mean · median · min · nnz · prod · std · sum · trapz · var
Structure
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how acosh is executed, line by line, in Rust.
- View the source for acosh 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.