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 | — | Single/double real or complex input; integer, logical, and character forms are RunMat-only extensions. |
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 |
RunMat:acosh:TooManyOutputs | More than one output is requested. | acosh: too many output arguments |
How acosh works
- Accepts scalars, vectors, matrices, and N-D tensors with MATLAB broadcasting semantics.
- 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 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 a provider implements unary_acosh and reduce_min proves that every element lies in the real domain. 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 auto-offload planner keeps documented floating inputs on the GPU whenever the provider exposes unary_acosh and the input stays within the real domain. 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 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.8638iComputing inverse hyperbolic cosine values from character codes
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. Unsupported real-domain hooks use an owner-preserving fallback.
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?⌄
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-hyperbolic-cosine computation boundary.
Can I keep complex results on the GPU?⌄
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.
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 · 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 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.