log1p — Compute log(1+x) accurately in MATLAB and RunMat.
Y = log1p(X) evaluates log(1 + X) element-wise with improved near-zero accuracy for floating-point inputs and principal-branch complex promotion. Integer, logical, character, and explicit-GPU real-to-complex forms are separately gated RunMat extensions.
Syntax
Y = log1p(X)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Numeric, logical, char, or complex input. |
Returns
| Name | Type | Description |
|---|---|---|
Y | NumericArray | Elementwise log(1+x) result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:log1p:InvalidInput | Input cannot be interpreted as numeric, logical, char, or complex data. | log1p: invalid input |
RunMat:log1p:Internal | Internal tensor construction or provider interaction failed. | log1p: internal error |
How log1p works
- In RunMat extension mode, logical inputs are promoted to double precision (
true -> 1.0,false -> 0.0) before execution; compatibility mode rejects this extension. - In RunMat extension mode, character arrays are interpreted as their numeric code points and return dense double tensors; compatibility mode rejects this extension.
- Integer input is a RunMat-only extension. All eight integer classes are accepted only when every value is exactly representable in binary64, and the result is double or complex double.
- Values equal to
-1yield-Inf, matching MATLAB's handling oflog(0). - Inputs smaller than
-1promote to complex outputs:log1p(-2)returns0 + iπ. - Complex inputs follow MATLAB's definition by computing the natural logarithm of
1 + z. - Existing real GPU tensors remain on the device when their exact owner implements
unary_log1palongsidereduce_min. Other paths gather through that owner, compute on the host, and restore the result when its class and precision are representable.
Does RunMat run log1p on the GPU?
RunMat Accelerate uses the exact owning provider's reduce_min to determine whether resident real data stays in the real domain, then validates any unary_log1p output for non-aliasing, shape, device, owner, storage, and precision. Fallbacks download through that owner, compute on the host, and restore when representable while preserving provenance. log1p is intentionally excluded from fusion to retain its near-zero accuracy.
GPU memory and residency
RunMat resolves the exact provider that owns a resident input. Real data can stay on device through reduce_min and unary_log1p; integer, logical, complex, unsupported-hook, and real-to-complex paths gather through that owner and restore the correctly typed result when representable. Explicit gpuArray input that requires real-to-complex promotion is a RunMat-only extension and is rejected in compatibility mode.
Examples
Protecting precision when adding tiny percentages
delta = 1e-12;
value = log1p(delta)Expected output:
value = 9.999999999995e-13Computing log-growth factors from percentage changes
rates = [-0.25 -0.10 0 0.10 0.25];
growth = log1p(rates)Expected output:
growth = [-0.2877 -0.1054 0 0.0953 0.2231]Handling the branch cut at x = -1
y = log1p(-1)Expected output:
y = -InfObtaining complex results for inputs less than -1
data = [-2 -3 -5];
result = log1p(data)Expected output:
result = [0.0000 + 3.1416i, 0.6931 + 3.1416i, 1.3863 + 3.1416i]Executing log1p on GPU arrays with automatic residency
G = gpuArray(linspace(-0.5, 0.5, 5));
out = log1p(G);
realResult = gather(out)Expected output:
realResult = [-0.6931 -0.2877 0 0.2231 0.4055]Using log1p with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how log1p changes the result.
Run a small log1p example, explain the result, then change one input and compare the output.
FAQ
When should I prefer log1p over log(1 + x)?⌄
Use log1p whenever x can be very close to zero. It avoids catastrophic cancellation and matches MATLAB's high-accuracy results for tiny magnitudes.
Does log1p change my tensor's shape?⌄
No. The output has the same shape as the input, subject to MATLAB broadcasting semantics.
How are logical arrays handled?⌄
In RunMat extension mode, logical values convert to doubles before applying log1p, so log1p([true false]) yields a double array [log(2), 0]. Compatibility mode rejects logical input.
What about inputs smaller than -1?⌄
Values less than -1 promote to complex results (log(1 + x) on the complex branch), matching MATLAB's behavior.
How does log1p interact with complex numbers?⌄
Complex scalars and tensors compute log(1 + z) using the principal branch, returning both real and imaginary parts just like MATLAB.
What happens when the GPU provider lacks unary_log1p?⌄
RunMat gathers through the input's exact owner, computes on the host in the input's floating class, and restores the result to that owner when representable; otherwise it returns the correctly typed host value.
Is double precision guaranteed?⌄
No single rule applies to every input: double input produces double output and single input preserves single precision. Integer, logical, and character extensions produce double-domain output.
Can log1p participate in fusion?⌄
Not currently. Fusion is disabled because replacing log1p(x) with a raw fused log(1 + x) would lose the near-zero accuracy that defines this function.
What's the inverse of log1p?⌄
— Use expm1(y), which computes exp(y) - 1 accurately for small y. Together log1p and expm1 are the numerically-stable pair for working with quantities near zero: expm1(log1p(x)) == x up to floating-point rounding.
What are typical applications of log1p?⌄
— Anywhere you evaluate log(1 + x) for small x: compounding tiny financial returns (log1p(r) ≈ r but exact), log-probabilities that bump away from 1, physics corrections where x is a perturbation, entropy and softplus gradients, and computing log(1 - p) as log1p(-p) for p near zero.
How much more accurate is log1p(x) than log(1 + x) for tiny x?⌄
— For x = 1e-15, log(1 + x) returns roughly 1.11e-16 (pure rounding noise from forming 1 + x), while log1p(x) returns 1e-15 correctly. The relative error of log(1 + x) grows without bound as x -> 0; log1p stays accurate to the last bit.
Related Math functions
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
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 log1p is executed, line by line, in Rust.
- View the source for log1p 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.