RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the log1p function do in MATLAB / RunMat?

Y = log1p(X) evaluates log(1 + X) element-wise with high accuracy for values of X close to zero. It mirrors MATLAB semantics across scalars, vectors, matrices, logical arrays, character arrays, and complex inputs.

How does the log1p function behave in MATLAB / RunMat?

  • Logical inputs are promoted to double precision (true -> 1.0, false -> 0.0) before execution.
  • Character arrays are interpreted as their numeric code points and return dense double tensors.
  • Values equal to -1 yield -Inf, matching MATLAB's handling of log(0).
  • Inputs smaller than -1 promote to complex outputs: log1p(-2) returns 0 + iπ.
  • Complex inputs follow MATLAB's definition by computing the natural logarithm of 1 + z.
  • Existing GPU tensors remain on the device when the registered provider implements unary_log1p alongside reduce_min. RunMat queries the device-side minimum to confirm the data stays within the real-valued domain; otherwise it gathers to the host, computes the exact result, and preserves residency metadata.

log1p Function GPU Execution Behaviour

RunMat Accelerate keeps tensors resident on the GPU whenever the provider exposes the unary_log1p hook together with reduce_min. The runtime uses the device-side minimum to ensure that 1 + X stays non-negative; when complex outputs are required or either hook is missing, RunMat automatically gathers the tensor, computes on the CPU using double precision, and returns the result with the expected MATLAB semantics.

Examples of using the log1p function in MATLAB / RunMat

Protecting precision when adding tiny percentages

delta = 1e-12;
value = log1p(delta);

Expected output:

value = 9.999999999995e-13;

Computing 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 = -Inf;

Obtaining 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];

GPU residency in RunMat (Do I need gpuArray?)

In most workflows you do not need to call gpuArray manually. RunMat's auto-offload planner and fusion engine keep data on the GPU when beneficial. When your expression requires complex results (e.g., values smaller than -1), RunMat gathers data to the host automatically and still returns the MATLAB-compatible output. You can call gpuArray and gather explicitly if you wish to mirror MathWorks MATLAB workflows.

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?

Logical values convert to doubles before applying log1p, so log1p([true false]) yields a double array [log(2), 0].

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 the tensor to the host, computes the result in double precision, and returns it. This ensures users always see MATLAB-compatible behavior without manual residency management.

Is double precision guaranteed?

Yes. RunMat stores dense numeric tensors in double precision (f64). GPU providers may choose single precision internally but convert back to double when returning data to the runtime.

Can log1p participate in fusion?

Yes. The fusion planner recognizes log1p as an element-wise op. Providers that support fused kernels can materialize log(1 + x) directly in generated WGSL.

See Also

log, expm1, sin, gpuArray, gather

Source & Feedback