Top-level Operations

These operations are available directly from fvdb. Tensor operations accept both torch.Tensor and fvdb.JaggedTensor; see JaggedTensor: Efficient Batching for Variable-Length Data for examples of jagged tensor operations.

Concatenation

fvdb.jcat(jagged_tensors: Sequence[JaggedTensor], dim: int | None = None) → JaggedTensor[source]

Concatenate a sequence of JaggedTensors along a given dimension.

Parameters:

jagged_tensors – The sequence of JaggedTensors to concatenate.
dim – The dimension to concatenate along, optional.

fvdb.gcat(grids: Sequence[GridBatch]) → GridBatch[source]

Concatenate a sequence of grid batches into a single grid batch along the batch dimension.

Parameters:: grids (Sequence[GridBatch]) – Grid batches to concatenate.
Returns:: grid_batch (GridBatch) – A new GridBatch containing all grids from the inputs.

Attention and volume rendering

fvdb.scaled_dot_product_attention(query: JaggedTensor, key: JaggedTensor, value: JaggedTensor, scale: float) → JaggedTensor[source]

Compute scaled dot-product attention over jagged sequences.

Wraps torch.nn.functional.scaled_dot_product_attention() so that it operates on JaggedTensor inputs, where each batch element may have a different sequence length. Internally the jagged tensors are converted to PyTorch nested tensors, attention is computed, and the result is converted back to a JaggedTensor.

The SDP backend (flash, memory-efficient, math, or cuDNN) is chosen automatically based on the context set by torch.nn.attention.sdpa_kernel(). Each backend has different nested tensor requirements, so this function probes the actual backend selection via _fused_sdp_choice and constructs the nested tensors accordingly:

Efficient / cuDNN: zero-copy view into the JaggedTensor buffer
Flash: copy-based nested tensor (required by the kernel)
Math: copy-based nested tensor, made contiguous after transpose

See PyTorch SDPA documentation for details on the underlying attention computation.

Parameters:

query – Query JaggedTensor of shape [B, -1, H, E] where B is the batch size (number of jagged sequences), H is the number of attention heads, and E is the embedding dimension.
key – Key JaggedTensor of shape [B, -1, H, E].
value – Value JaggedTensor of shape [B, -1, H, V] where V is the value dimension. Key and value must share the same sequence lengths.
scale – Scaling factor applied to the dot products before softmax.

Returns:

A JaggedTensor of shape ``[B, -1, H, V]`` containing the attention
output, with the same jagged structure as the query.

fvdb.volume_render(sigmas: Tensor, rgbs: Tensor, delta_ts: Tensor, ts: Tensor, pack_info: Tensor, transmittance_thresh: float) → tuple[Tensor, Tensor, Tensor, Tensor, Tensor][source]

Volume-render per-sample sigmas / rgbs into per-ray outputs.

Performs front-to-back Beer-Lambert compositing along each ray. For a sample s with extinction sigma_s and step length delta_s, the alpha is a_s = 1 - exp(-sigma_s * delta_s), the per-sample weight is w_s = a_s * T_s (where T_s is the accumulated transmittance up to s), and the per-ray outputs are rgb = sum_s w_s * rgb_s, depth = sum_s w_s * t_s, opacity = sum_s w_s. Each ray early-terminates once T <= transmittance_thresh.

All samples for all rays are packed contiguously into the N-dim input tensors; pack_info tells the kernel which contiguous slice belongs to each of the R rays (see below).

Execution paths:

Training / graph-capture path. If autograd is globally enabled and sigmas or rgbs requires grad, this routes through _VolumeRenderFn which runs the kernel with needsBackward=True. The backward-only outputs (depth, ws, total_samples) are fully materialized and saved on the autograd graph, and gradients flow into sigmas and rgbs. delta_ts and ts are non-differentiable inputs even when their requires_grad is set, so they do not on their own select this path.
Inference fast path. Otherwise this calls the C++ forward directly with needsBackward=False. The kernel skips the per-sample ws store (the dominant global-memory traffic savings) and the per-ray depth / total_samples stores, and the host skips the zero-init of the size-N ws buffer. Those three outputs are returned as size-0 placeholder tensors with matching dtype / device. Callers that only consume rgb / opacity (e.g. a pure renderer) see no behavioral change.

Parameters:

sigmas (torch.Tensor) – Per-sample extinction (density) values, floating-point tensor of shape [N], where N is the total number of samples packed across all R rays. Must be on the same device and dtype as rgbs, delta_ts, ts. Differentiable input.
rgbs (torch.Tensor) – Per-sample emitted color, floating-point tensor of shape [N, C] where 1 <= C <= MAX_VOLUME_RENDER_CHANNELS (currently 16). Differentiable input.
delta_ts (torch.Tensor) – Per-sample step length along the ray (delta_s = t_{s+1} - t_s), floating-point tensor of shape [N]. Not differentiable.
ts (torch.Tensor) – Per-sample parametric distance along the ray (typically the interval midpoint) used for depth compositing, floating-point tensor of shape [N]. Not differentiable.
pack_info (torch.Tensor) – CSR-style per-ray offsets into the sample-packed tensors. int64 tensor of shape [R + 1] where R is the number of rays; ray r owns samples in [pack_info[r], pack_info[r + 1]) and pack_info[R] == N. Not differentiable.
transmittance_thresh (float) – Early-termination threshold on the accumulated transmittance T. The inner compositing loop breaks for a ray as soon as T <= transmittance_thresh. Typical values are in the range [1e-4, 1e-2].

Returns:

A 5-tuple `` (rgb, depth, opacity, ws, total_samples) –

rgb (torch.Tensor): Composited per-ray color, floating-point tensor of shape [R, C]. Always materialized.
depth (torch.Tensor): Composited per-ray depth, floating-point tensor of shape [R] on the training path or [0] on the inference fast path.
opacity (torch.Tensor): Accumulated per-ray opacity 1 - T_final, floating-point tensor of shape [R]. Always materialized.
ws (torch.Tensor): Per-sample compositing weight a_s * T_s consumed by the backward pass, floating-point tensor of shape [N] on the training path or [0] on the inference fast path. When materialized, entries past a ray’s early-termination point remain zero (the buffer is zero-initialized on the host).
total_samples (torch.Tensor): Number of samples actually composited for each ray before early termination, int64 tensor of shape [R] on the training path or [0] on the inference fast path.

Note

Callers that need the full set of outputs under no-grad (for example, a diagnostic that wants total_samples) should either run under torch.enable_grad() with sigmas.requires_grad_(True) or rgbs.requires_grad_(True), or call _fvdb_cpp.volume_render_fwd() directly with needsBackward=True. Setting requires_grad on delta_ts or ts does not select this path because no gradient is propagated into those inputs.

Unary tensor operations

fvdb.relu(input: JaggedTensor) → JaggedTensor[source]

fvdb.relu(input: Tensor) → Tensor

Apply ReLU (Rectified Linear Unit) activation function element-wise.

Computes ReLU(x) = max(0, x) for each element in the input tensor.

Parameters:: input (JaggedTensor | Tensor) – Input tensor to apply ReLU to. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with ReLU applied element-wise. Returns the same type as the input.

fvdb.relu_(input: JaggedTensor) → JaggedTensor[source]

fvdb.relu_(input: Tensor) → Tensor

Apply ReLU (Rectified Linear Unit) activation function element-wise in-place.

Computes ReLU(x) = max(0, x) for each element in the input tensor, modifying the input tensor directly.

Parameters:: input (JaggedTensor | Tensor) – Input tensor to apply ReLU to in-place. Can be a regular torch.Tensor or a JaggedTensor. This tensor will be modified.
Returns:: JaggedTensor | Tensor – The modified input tensor with ReLU applied element-wise. Returns the same type as the input.

fvdb.sigmoid(input: JaggedTensor) → JaggedTensor[source]

fvdb.sigmoid(input: Tensor) → Tensor

Apply sigmoid activation function element-wise.

Computes sigmoid(x) = 1 / (1 + exp(-x)) for each element in the input tensor.

Parameters:: input (JaggedTensor | Tensor) – Input tensor to apply sigmoid to. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with sigmoid applied element-wise. Returns the same type as the input. Values are in the range (0, 1).

fvdb.tanh(input: JaggedTensor) → JaggedTensor[source]

fvdb.tanh(input: Tensor) → Tensor

Apply hyperbolic tangent (tanh) activation function element-wise.

Computes tanh(x) = (exp(x) - exp(-x)) / (exp(x) + exp(-x)) for each element.

Parameters:: input (JaggedTensor | Tensor) – Input tensor to apply tanh to. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with tanh applied element-wise. Returns the same type as the input. Values are in the range (-1, 1).

fvdb.exp(input: JaggedTensor) → JaggedTensor[source]

fvdb.exp(input: Tensor) → Tensor

Compute the exponential of each element.

Computes exp(x) = e^x for each element in the input tensor.

Parameters:: input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with exponential applied element-wise. Returns the same type as the input.

fvdb.log(input: JaggedTensor) → JaggedTensor[source]

fvdb.log(input: Tensor) → Tensor

Compute the natural logarithm of each element.

Computes log(x) = ln(x) for each element in the input tensor.

Parameters:: input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with natural logarithm applied element-wise. Returns the same type as the input.

fvdb.sqrt(input: JaggedTensor) → JaggedTensor[source]

fvdb.sqrt(input: Tensor) → Tensor

Compute the square root of each element.

Computes sqrt(x) = x^(1/2) for each element in the input tensor.

Parameters:: input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with square root applied element-wise. Returns the same type as the input.

fvdb.floor(input: JaggedTensor) → JaggedTensor[source]

fvdb.floor(input: Tensor) → Tensor

Round each element down to the nearest integer.

Computes floor(x), returning the largest integer less than or equal to x for each element.

Parameters:: input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with floor applied element-wise. Returns the same type as the input.

fvdb.ceil(input: JaggedTensor) → JaggedTensor[source]

fvdb.ceil(input: Tensor) → Tensor

Round each element up to the nearest integer.

Computes ceil(x), returning the smallest integer greater than or equal to x for each element.

Parameters:: input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with ceiling applied element-wise. Returns the same type as the input.

fvdb.round(input: JaggedTensor) → JaggedTensor[source]

fvdb.round(input: Tensor) → Tensor

Round each element to the nearest integer.

Computes round(x), returning the nearest integer to x. For values exactly halfway between two integers, rounds to the nearest even integer.

Parameters:: input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
Returns:: JaggedTensor | Tensor – Output with rounding applied element-wise. Returns the same type as the input.

fvdb.nan_to_num(input: JaggedTensor, nan: float = 0.0, posinf: float | None = None, neginf: float | None = None) → JaggedTensor[source]

fvdb.nan_to_num(input: Tensor, nan: float = 0.0, posinf: float | None = None, neginf: float | None = None) → Tensor

Replace NaN, positive infinity, and negative infinity values with specified numbers.

Replaces NaN values with the nan argument, positive infinity with posinf, and negative infinity with neginf.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
nan (float) – The value to replace NaN with. Default is 0.0.
posinf (float | None) – The value to replace positive infinity with. If None, uses the maximum representable value for the dtype.
neginf (float | None) – The value to replace negative infinity with. If None, uses the minimum representable value for the dtype.

Returns:

JaggedTensor | Tensor – Output with NaN and infinity values replaced. Returns the same type as the input.

fvdb.clamp(input: JaggedTensor, min: float | None = None, max: float | None = None) → JaggedTensor[source]

fvdb.clamp(input: Tensor, min: float | None = None, max: float | None = None) → Tensor

Clamp all elements to be within the range [min, max].

Values smaller than min are set to min. Values larger than max are set to max.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
min (float | None) – Lower bound. If None, no lower bound is applied.
max (float | None) – Upper bound. If None, no upper bound is applied.

Returns:

JaggedTensor | Tensor – Output with values clamped to [min, max]. Returns the same type as the input.

Binary tensor operations

fvdb.add(input: JaggedTensor, other: JaggedTensor | Tensor | float | int, *, out: JaggedTensor | None = None) → JaggedTensor[source]

fvdb.add(input: Tensor, other: Tensor | float | int, *, out: Tensor | None = None) → Tensor

Add two tensors element-wise or add a scalar to each element.

Computes input + other element-wise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to add. Can be a tensor (with broadcasting) or a scalar.
out (JaggedTensor | Tensor | None) – Optional output tensor. If provided, the result is written to this tensor.

Returns:

JaggedTensor | Tensor – Sum of input and other. Returns the same type as the input tensor.

fvdb.sub(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.sub(input: Tensor, other: Tensor | float | int) → Tensor

Subtract two tensors element-wise or subtract a scalar from each element.

Computes input - other element-wise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to subtract. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Difference of input and other. Returns the same type as the input tensor.

fvdb.mul(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.mul(input: Tensor, other: Tensor | float | int) → Tensor

Multiply two tensors element-wise or multiply each element by a scalar.

Computes input * other element-wise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to multiply by. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Product of input and other. Returns the same type as the input tensor.

fvdb.true_divide(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.true_divide(input: Tensor, other: Tensor | float | int) → Tensor

Divide two tensors element-wise or divide each element by a scalar.

Computes input / other element-wise using true (floating-point) division. Always returns a floating-point result, even for integer inputs. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – Input tensor (numerator). Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Divisor. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Quotient of input and other. Returns the same type as the input tensor.

fvdb.floor_divide(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.floor_divide(input: Tensor, other: Tensor | float | int) → Tensor

Divide two tensors element-wise and round down to the nearest integer.

Computes floor(input / other) element-wise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – Input tensor (numerator). Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Divisor. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Floor division result. Returns the same type as the input tensor.

fvdb.remainder(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.remainder(input: Tensor, other: Tensor | float | int) → Tensor

Compute the element-wise remainder of division.

Computes the remainder of input / other element-wise. The result has the same sign as the divisor (other). Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – Input tensor (numerator). Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Divisor. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Remainder of input divided by other. Returns the same type as the input tensor.

fvdb.pow(input: JaggedTensor, exponent: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.pow(input: Tensor, exponent: Tensor | float | int) → Tensor

Raise each element to the power of an exponent.

Computes input^exponent element-wise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – Base tensor. Can be a regular torch.Tensor or a JaggedTensor.
exponent (JaggedTensor | Tensor | float | int) – Exponent. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Result of raising input to the given exponent. Returns the same type as the input tensor.

fvdb.maximum(input: JaggedTensor, other: JaggedTensor) → JaggedTensor[source]

fvdb.maximum(input: Tensor, other: Tensor) → Tensor

Compute the element-wise maximum of two tensors.

Compares corresponding elements and returns the larger value for each position. Supports broadcasting.

Parameters:

input (JaggedTensor | Tensor) – First input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor) – Second input tensor. Can be a regular torch.Tensor or a JaggedTensor.

Returns:

JaggedTensor | Tensor – Element-wise maximum of input and other. Returns the same type as the input tensor.

fvdb.minimum(input: JaggedTensor, other: JaggedTensor) → JaggedTensor[source]

fvdb.minimum(input: Tensor, other: Tensor) → Tensor

Compute the element-wise minimum of two tensors.

Compares corresponding elements and returns the smaller value for each position. Supports broadcasting.

Parameters:

input (JaggedTensor | Tensor) – First input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor) – Second input tensor. Can be a regular torch.Tensor or a JaggedTensor.

Returns:

JaggedTensor | Tensor – Element-wise minimum of input and other. Returns the same type as the input tensor.

Comparisons

fvdb.eq(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.eq(input: Tensor, other: Tensor | float | int) → Tensor

Compute element-wise equality comparison.

Compares corresponding elements and returns True where input equals other, False otherwise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – First input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to compare against. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Boolean tensor with element-wise equality results. Returns the same type as the input tensor.

fvdb.ne(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.ne(input: Tensor, other: Tensor | float | int) → Tensor

Compute element-wise inequality comparison.

Compares corresponding elements and returns True where input does not equal other, False otherwise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – First input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to compare against. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Boolean tensor with element-wise inequality results. Returns the same type as the input tensor.

fvdb.lt(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.lt(input: Tensor, other: Tensor | float | int) → Tensor

Compute element-wise less than comparison.

Compares corresponding elements and returns True where input is less than other, False otherwise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – First input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to compare against. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Boolean tensor with element-wise less than results. Returns the same type as the input tensor.

fvdb.le(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.le(input: Tensor, other: Tensor | float | int) → Tensor

Compute element-wise less than or equal comparison.

Compares corresponding elements and returns True where input is less than or equal to other, False otherwise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – First input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to compare against. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Boolean tensor with element-wise less than or equal results. Returns the same type as the input tensor.

fvdb.gt(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.gt(input: Tensor, other: Tensor | float | int) → Tensor

Compute element-wise greater than comparison.

Compares corresponding elements and returns True where input is greater than other, False otherwise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – First input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to compare against. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Boolean tensor with element-wise greater than results. Returns the same type as the input tensor.

fvdb.ge(input: JaggedTensor, other: JaggedTensor | Tensor | float | int) → JaggedTensor[source]

fvdb.ge(input: Tensor, other: Tensor | float | int) → Tensor

Compute element-wise greater than or equal comparison.

Compares corresponding elements and returns True where input is greater than or equal to other, False otherwise. Supports broadcasting when both inputs are tensors.

Parameters:

input (JaggedTensor | Tensor) – First input tensor. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor | float | int) – Value to compare against. Can be a tensor (with broadcasting) or a scalar.

Returns:

JaggedTensor | Tensor – Boolean tensor with element-wise greater than or equal results. Returns the same type as the input tensor.

fvdb.where(condition: JaggedTensor, input: JaggedTensor, other: JaggedTensor) → JaggedTensor[source]

fvdb.where(condition: Tensor, input: Tensor, other: Tensor) → Tensor

Select elements from input or other based on condition.

Returns a tensor where each element is selected from input if the corresponding element in condition is True, otherwise from other. Supports broadcasting.

Parameters:

condition (JaggedTensor | Tensor) – Boolean tensor determining which values to select. Can be a regular torch.Tensor or a JaggedTensor.
input (JaggedTensor | Tensor) – Values selected where condition is True. Can be a regular torch.Tensor or a JaggedTensor.
other (JaggedTensor | Tensor) – Values selected where condition is False. Can be a regular torch.Tensor or a JaggedTensor.

Returns:

JaggedTensor | Tensor – Tensor with elements selected based on condition. Returns the same type as the condition tensor.

Reductions

A JaggedTensor must keep its leading (element) dimension, so pass an explicit trailing dimension. dim=None reduces every dimension and is only valid for a torch.Tensor:

feats = fvdb.JaggedTensor([torch.rand(4, 3), torch.rand(2, 3)])
fvdb.sum(feats, dim=-1)  # JaggedTensor whose jdata has shape (6,)
fvdb.sum(feats)          # RuntimeError: would drop the primary jagged dimension

fvdb.sum(input: JaggedTensor, dim: int | tuple[int, ...] | None = None, keepdim: bool = False, *, dtype: dtype | None = None) → JaggedTensor[source]

fvdb.sum(input: Tensor, dim: int | tuple[int, ...] | None = None, keepdim: bool = False, *, dtype: dtype | None = None) → Tensor

Compute the sum of elements.

Returns the sum of all elements, or sums along specified dimensions.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
dim (int | tuple[int, ...] | None) – Dimension(s) along which to reduce. Can be a single dimension or tuple of dimensions. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension(s) with size 1. Default is False.
dtype (torch.dtype | None) – Desired output dtype. If None, uses the dtype of the input.

Returns:

JaggedTensor | Tensor – Sum of elements. Returns the same type as the input tensor.

fvdb.mean(input: JaggedTensor, dim: int | tuple[int, ...] | None = None, keepdim: bool = False, *, dtype: dtype | None = None) → JaggedTensor[source]

fvdb.mean(input: Tensor, dim: int | tuple[int, ...] | None = None, keepdim: bool = False, *, dtype: dtype | None = None) → Tensor

Compute the mean (average) of elements.

Returns the mean of all elements, or means along specified dimensions.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
dim (int | tuple[int, ...] | None) – Dimension(s) along which to reduce. Can be a single dimension or tuple of dimensions. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension(s) with size 1. Default is False.
dtype (torch.dtype | None) – Desired output dtype. If None, uses the dtype of the input.

Returns:

JaggedTensor | Tensor – Mean of elements. Returns the same type as the input tensor.

fvdb.amax(input: JaggedTensor, dim: int | tuple[int, ...] | None = None, keepdim: bool = False) → JaggedTensor[source]

fvdb.amax(input: Tensor, dim: int | tuple[int, ...] | None = None, keepdim: bool = False) → Tensor

Compute the maximum value of elements.

Returns the maximum value of all elements, or maximum values along specified dimensions.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
dim (int | tuple[int, ...] | None) – Dimension(s) along which to reduce. Can be a single dimension or tuple of dimensions. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension(s) with size 1. Default is False.

Returns:

JaggedTensor | Tensor – Maximum value(s). Returns the same type as the input tensor.

fvdb.amin(input: JaggedTensor, dim: int | tuple[int, ...] | None = None, keepdim: bool = False) → JaggedTensor[source]

fvdb.amin(input: Tensor, dim: int | tuple[int, ...] | None = None, keepdim: bool = False) → Tensor

Compute the minimum value of elements.

Returns the minimum value of all elements, or minimum values along specified dimensions.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
dim (int | tuple[int, ...] | None) – Dimension(s) along which to reduce. Can be a single dimension or tuple of dimensions. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension(s) with size 1. Default is False.

Returns:

JaggedTensor | Tensor – Minimum value(s). Returns the same type as the input tensor.

fvdb.argmax(input: JaggedTensor, dim: int | None = None, keepdim: bool = False) → JaggedTensor[source]

fvdb.argmax(input: Tensor, dim: int | None = None, keepdim: bool = False) → Tensor

Return the indices of the maximum value(s).

Returns the index of the maximum value, or indices along a specified dimension.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
dim (int | None) – Dimension along which to find the maximum. If None, returns the index of the maximum value in the flattened tensor (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension with size 1. Default is False.

Returns:

JaggedTensor | Tensor – Indices of maximum value(s). Returns the same type as the input tensor.

fvdb.argmin(input: JaggedTensor, dim: int | None = None, keepdim: bool = False) → JaggedTensor[source]

fvdb.argmin(input: Tensor, dim: int | None = None, keepdim: bool = False) → Tensor

Return the indices of the minimum value(s).

Returns the index of the minimum value, or indices along a specified dimension.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
dim (int | None) – Dimension along which to find the minimum. If None, returns the index of the minimum value in the flattened tensor (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension with size 1. Default is False.

Returns:

JaggedTensor | Tensor – Indices of minimum value(s). Returns the same type as the input tensor.

fvdb.all(input: JaggedTensor, dim: int | None = None, keepdim: bool = False) → JaggedTensor[source]

fvdb.all(input: Tensor, dim: int | None = None, keepdim: bool = False) → Tensor

Test if all elements evaluate to True.

Returns True if all elements are True (or non-zero), either over the entire tensor or along a specified dimension.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor. Typically boolean, but numeric types are also supported (0 is False, non-zero is True).
dim (int | None) – Dimension along which to reduce. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension with size 1. Default is False.

Returns:

JaggedTensor | Tensor – Boolean tensor with result of all() reduction. Returns the same type as the input tensor.

fvdb.any(input: JaggedTensor, dim: int | None = None, keepdim: bool = False) → JaggedTensor[source]

fvdb.any(input: Tensor, dim: int | None = None, keepdim: bool = False) → Tensor

Test if any element evaluates to True.

Returns True if any element is True (or non-zero), either over the entire tensor or along a specified dimension.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor. Typically boolean, but numeric types are also supported (0 is False, non-zero is True).
dim (int | None) – Dimension along which to reduce. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension with size 1. Default is False.

Returns:

JaggedTensor | Tensor – Boolean tensor with result of any() reduction. Returns the same type as the input tensor.

fvdb.norm(input: JaggedTensor, p: float | str = 2, dim: int | tuple[int, ...] | None = None, keepdim: bool = False, *, dtype: dtype | None = None) → JaggedTensor[source]

fvdb.norm(input: Tensor, p: float | str = 2, dim: int | tuple[int, ...] | None = None, keepdim: bool = False, *, dtype: dtype | None = None) → Tensor

Compute the p-norm of elements.

Returns the p-norm of all elements, or p-norms along specified dimensions. Common values include p=2 (Euclidean norm), p=1 (Manhattan norm), p=’fro’ (Frobenius norm).

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
p (float | str) – The order of the norm. Can be a float or ‘fro’ (Frobenius), ‘nuc’ (nuclear). Default is 2.
dim (int | tuple[int, ...] | None) – Dimension(s) along which to reduce. Can be a single dimension or tuple of dimensions. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
keepdim (bool) – Whether to keep the reduced dimension(s) with size 1. Default is False.
dtype (torch.dtype | None) – Desired output dtype. If None, uses the dtype of the input.

Returns:

JaggedTensor | Tensor – p-norm of elements. Returns the same type as the input tensor.

fvdb.var(input: JaggedTensor, dim: int | tuple[int, ...] | None = None, unbiased: bool = True, keepdim: bool = False) → JaggedTensor[source]

fvdb.var(input: Tensor, dim: int | tuple[int, ...] | None = None, unbiased: bool = True, keepdim: bool = False) → Tensor

Compute the variance of elements.

Returns the variance of all elements, or variances along specified dimensions. Uses Bessel’s correction (dividing by N-1) when unbiased=True.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
dim (int | tuple[int, ...] | None) – Dimension(s) along which to reduce. Can be a single dimension or tuple of dimensions. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
unbiased (bool) – Whether to use Bessel’s correction (divide by N-1 instead of N). Default is True.
keepdim (bool) – Whether to keep the reduced dimension(s) with size 1. Default is False.

Returns:

JaggedTensor | Tensor – Variance of elements. Returns the same type as the input tensor.

fvdb.std(input: JaggedTensor, dim: int | tuple[int, ...] | None = None, unbiased: bool = True, keepdim: bool = False) → JaggedTensor[source]

fvdb.std(input: Tensor, dim: int | tuple[int, ...] | None = None, unbiased: bool = True, keepdim: bool = False) → Tensor

Compute the standard deviation of elements.

Returns the standard deviation of all elements, or standard deviations along specified dimensions. Uses Bessel’s correction (dividing by N-1) when unbiased=True.

Parameters:

input (JaggedTensor | Tensor) – Input tensor. Can be a regular torch.Tensor or a JaggedTensor.
dim (int | tuple[int, ...] | None) – Dimension(s) along which to reduce. Can be a single dimension or tuple of dimensions. If None, reduces all dimensions (torch.Tensor only; a JaggedTensor must keep its leading dimension, so pass dim=-1 or another trailing dimension).
unbiased (bool) – Whether to use Bessel’s correction (divide by N-1 instead of N). Default is True.
keepdim (bool) – Whether to keep the reduced dimension(s) with size 1. Default is False.

Returns:

JaggedTensor | Tensor – Standard deviation of elements. Returns the same type as the input tensor.

Space-filling curves

fvdb.morton(ijk)

Encode integer coordinates in xyz Morton (Z-order) order.

Parameters:: ijk (torch.Tensor) – Coordinates of shape (N, 3) and dtype torch.int32 on CPU or CUDA.
Returns:: Codes of shape (N,) and dtype torch.int64 on the input device.
Return type:: torch.Tensor

fvdb.hilbert(ijk)

Encode integer coordinates in xyz Hilbert order.

Parameters:: ijk (torch.Tensor) – Coordinates of shape (N, 3) and dtype torch.int32 on CPU or CUDA.
Returns:: Codes of shape (N,) and dtype torch.int64 on the input device.
Return type:: torch.Tensor

NanoVDB metadata

class fvdb.NanoVDBGridMetadata

Read-only metadata for a grid stored in a NanoVDB file. Obtain instances with fvdb.functional.read_nanovdb_metadata() without loading voxel data.

name: Grid name stored in the file, as a string.

type: NanoVDB grid type as a string, for example float, Vec3f, or OnIndex.

grid_class: NanoVDB grid class as a string, for example SDF or FOG.

voxel_count: Number of active voxels, as an integer.

voxel_size: Voxel size in world units, as a tuple of three floats.

index_bbox_min: Inclusive minimum of the index-space bounding box, as a tuple of three integers.

index_bbox_max: Inclusive maximum of the index-space bounding box, as a tuple of three integers.