log1p — Compute log(1 + X) elementwise with near-zero accuracy.
Y = log1p(X) computes the natural logarithm of one plus each element while retaining accuracy near zero and applying principal-branch complex promotion where required.
Syntax
Y = log1p(X)Inputs
X- Type
Any- Required
- Yes
- Description
- Single or double real/complex input; integer, logical, and character forms are RunMat-only extensions.
Returns
Y- Type
NumericArray- Description
- Elementwise log(1+X) result, promoted to complex when a real value is below -1.
Errors
RunMat:log1p:InvalidInput- When
- Input cannot be interpreted as supported numeric, logical, or character data.
- Message
log1p: invalid input
RunMat:log1p:Internal- When
- Internal tensor construction or provider interaction fails.
- Message
log1p: internal error
RunMat:log1p:TooManyOutputs- When
- More than one output is requested.
- Message
log1p: too many output arguments
Behavior
Y = log1p(X) evaluates log(1 + X) elementwise without the cancellation introduced by forming 1 + X near zero. It preserves shape and the single or double precision of floating-point input.
A real value equal to -1 maps to negative infinity. Real values below -1 promote to principal-branch complex output. Complex values compute the natural logarithm of 1 + z.
Fixed-width integer, logical, and character inputs are separate RunMat extensions. They produce double or complex double, and MATLAB compatibility mode rejects each extension with its structured compatibility error.
Integer extension inputs must lie in the inclusive exact binary64 interval [-2^53, 2^53]; RunMat rejects a wider value before conversion.
GPU execution
Supported real tensors can remain on their exact provider through minimum-reduction and unary-log1p operations. Provider results are validated for non-aliasing, shape, storage, precision, device, and owner.
Complex input, real-to-complex promotion, and typed unsupported operations gather through the owner and restore the result when representable. Other provider failures remain errors. Explicit real gpuArray input that requires complex promotion is available only in RunMat compatibility mode.
log1p is not fused because replacing it with a raw log(1 + X) expression would violate its near-zero accuracy contract.
Examples
Preserve single precision and array pages
input = reshape(single([0 exp(1)-1]), [1 1 2]);
result = log1p(input);Retain accuracy for a tiny increment
delta = 1e-12;
value = log1p(delta)Expected output:
value = 9.999999999995e-13Convert percentage changes into log-growth factors
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]Evaluate the branch point at negative one
y = log1p(-1)Expected output:
y = -InfPromote values below negative one to complex results
data = [-2 -3 -5];
result = log1p(data)Expected output:
result = [0.0000 + 3.1416i 0.6931 + 3.1416i 1.3863 + 3.1416i]Apply log1p to provider-resident data
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 close to zero. It avoids the significant-digit loss caused by rounding 1 + X before taking the logarithm.
Does log1p preserve shape?⌄
Yes. The result has the same shape as the input.
How are logical arrays handled?⌄
Logical values convert to double only in RunMat compatibility mode; MATLAB compatibility mode rejects the extension.
What happens for values below -1?⌄
Real values below -1 promote to principal-branch complex results for log(1 + X).
How does log1p handle complex values?⌄
Complex scalars and arrays compute the principal natural logarithm of 1 + z.
What happens when a provider lacks unary_log1p?⌄
RunMat gathers through the exact owner, computes on the host in the required class, and restores the result when that provider can represent it. Genuine provider failures remain errors.
Is double precision always used?⌄
No. Double input returns double and single input returns single. Integer, logical, and character extensions enter the double domain.
Can log1p participate in fusion?⌄
Not currently. A fused log(1 + X) replacement would lose the near-zero accuracy that defines log1p.
What is the inverse of log1p?⌄
Use expm1(Y), which computes exp(Y) - 1 accurately near zero. The two functions form a numerically stable pair up to floating-point rounding.
Where is log1p commonly useful?⌄
Typical uses include small financial returns, log-probability calculations, perturbation terms, entropy and softplus gradients, and accurate evaluation of log(1 - p) as log1p(-p).
How much accuracy can direct log(1 + X) lose?⌄
When X approaches machine precision, forming 1 + X can discard most or all of X before the logarithm runs. log1p avoids that intermediate rounding and remains accurate near zero.
Related Math functions
Elementwise
abs · angle · besselj · bsxfun · complex · conj · double · eps · erf · erfcinv · exp · expm1 · flintmax · gamma · gammaln · heaviside · hypot · imag · int16 · int32 · int64 · int8 · intmax · intmin · ldivide · log · log10 · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · times · typecast · uint16 · uint32 · uint64 · uint8
Optim
acceptancesa · annealingboltz · annealingfast · coneprog · crossoverarithmetic · crossoverheuristic · crossoverintermediate · crossoverlaplace · crossoverscattered · crossoversinglepoint · crossovertwopoint · eqnproblem · EquationProblem.solve · EquationProblem.subsasgn · EquationProblem.subsref · evaluate · fgoalattain · fitscalingprop · fitscalingrank · fitscalingshiftlinear · fitscalingtop · fminbnd · fmincon · fminimax · fminsearch · fminunc · fseminf · fsolve · fzero · ga · gacreationlinearfeasible · gacreationnonlinearfeasible · gacreationsobol · gacreationuniform · gacreationuniformint · gaplotbestf · gaplotbestindiv · gaplotdistance · gaplotexpectation · gaplotgenealogy · gaplotmaxconstr · gaplotrange · gaplotscorediversity · gaplotscores · gaplotselection · gaplotstopping · integerConstraint · integral · intlinprog · linprog · lsqcurvefit · lsqlin · LsqlinWarmStart.subsasgn · LsqlinWarmStart.subsref · lsqnonlin · lsqnonneg · mutationadaptfeasible · mutationgaussian · mutationpositivebasis · mutationpower · mutationuniform · optimexpr · optimget · OptimizationConstraint.evaluate · OptimizationConstraint.subsasgn · OptimizationConstraint.subsref · OptimizationExitflag.double · OptimizationExitflag.eq · OptimizationExitflag.ne · OptimizationExitflag.string · OptimizationExpression.acos · OptimizationExpression.acosh · OptimizationExpression.acot · OptimizationExpression.acoth · OptimizationExpression.acsc · OptimizationExpression.acsch · OptimizationExpression.asec · OptimizationExpression.asech · OptimizationExpression.asin · OptimizationExpression.asinh · OptimizationExpression.atan · OptimizationExpression.atanh · OptimizationExpression.cat · OptimizationExpression.cos · OptimizationExpression.cosh · OptimizationExpression.cot · OptimizationExpression.coth · OptimizationExpression.csc · OptimizationExpression.csch · OptimizationExpression.ctranspose · OptimizationExpression.cumprod · OptimizationExpression.cumsum · OptimizationExpression.diag · OptimizationExpression.diff · OptimizationExpression.dot · OptimizationExpression.eq · OptimizationExpression.evaluate · OptimizationExpression.exp · OptimizationExpression.ge · OptimizationExpression.horzcat · OptimizationExpression.ldivide · OptimizationExpression.le · OptimizationExpression.log · OptimizationExpression.mean · OptimizationExpression.minus · OptimizationExpression.mldivide · OptimizationExpression.mpower · OptimizationExpression.mrdivide · OptimizationExpression.mtimes · OptimizationExpression.norm · OptimizationExpression.plus · OptimizationExpression.power · OptimizationExpression.prod · OptimizationExpression.rdivide · OptimizationExpression.reshape · OptimizationExpression.sec · OptimizationExpression.sech · OptimizationExpression.sin · OptimizationExpression.sinh · OptimizationExpression.sqrt · OptimizationExpression.subsasgn · OptimizationExpression.subsref · OptimizationExpression.sum · OptimizationExpression.tan · OptimizationExpression.tanh · OptimizationExpression.times · OptimizationExpression.trace · OptimizationExpression.transpose · OptimizationExpression.uminus · OptimizationExpression.uplus · OptimizationExpression.vertcat · OptimizationExpression.zeros · OptimizationExpression.zerosLike · OptimizationProblem.solve · OptimizationProblem.subsasgn · OptimizationProblem.subsref · OptimizationVariable.subsasgn · OptimizationVariable.subsref · optimoptions · optimplotconstrviolation · optimplotfirstorderopt · optimplotfunccount · optimplotfval · optimplotfvalconstr · optimplotmilp · optimplotstepsize · optimplotx · optimproblem · optimset · optimvar · optimwarmstart · particleswarm · patternsearch · psplotbestf · psplotbestx · psplotfuncount · psplotmaxconstr · psplotmeshsize · pswcreationuniform · pswplotbestf · quad · quadprog · QuadprogWarmStart.subsasgn · QuadprogWarmStart.subsref · saplotbestf · saplotbestx · saplotf · saplotstopping · saplottemperature · saplotx · savemilpsolutions · secondordercone · selectionremainder · selectionroulette · selectionstochunif · selectiontournament · selectionuniform · simulannealbnd · solve · surrogateopt · surrogateoptplot · temperatureboltz · temperatureexp · temperaturefast
Trigonometry
acos · acosd · acosh · acotd · acscd · asecd · asin · asind · asinh · atan · atan2 · atan2d · atand · 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
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Interpolation
griddedInterpolant · griddedInterpolant.subsref · interp1 · interp1q · interp2 · pchip · ppval · spline
Integer Division
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.