YouTip

## PyTorch torch.trapz `torch.trapz` is a PyTorch function used to compute the numerical integration of a set of values using the trapezoidal rule. It is an alias for `torch.trapezoid`, and both functions share identical behavior and performance. --- ### Mathematical Background The trapezoidal rule approximates the region under the graph of a function $f(x)$ as a trapezoid and calculates its area. For a sequence of points $(x_i, y_i)$, the integral is approximated as: $$\int_{a}^{b} f(x) \, dx \approx \sum_{i=1}^{N-1} \frac{y_i + y_{i+1}}{2} (x_{i+1} - x_i)$$ --- ### Syntax ```python torch.trapz(y, x=None, dx=1.0, dim=-1) ``` ### Parameter Descriptions * **`y`** *(Tensor)*: The values of the function to integrate (the dependent variable). * **`x`** *(Tensor, optional)*: The points at which the function `y` is evaluated (the independent variable). If provided, the spacing between adjacent points is computed as $x_{i+1} - x_i$. It must have the same shape as `y` along the integration dimension, or be 1-dimensional with a length equal to the size of `y` along `dim`. * **`dx`** *(float, optional)*: The constant spacing between sample points. This parameter is only used if `x` is not provided. The default value is `1.0`. * **`dim`** *(int, optional)*: The dimension along which to integrate. By default, this is the last dimension (`-1`). --- ## Code Examples ### Example 1: Integration with Constant Spacing (`dx`) When your data points are evenly spaced, you can specify the spacing using the `dx` parameter. ```python import torch # Define the function values (y) y = torch.tensor([1.0, 2.0, 3.0, 4.0]) # Perform trapezoidal integration with a uniform spacing of dx = 1.0 result = torch.trapz(y, dx=1.0) print("Trapezoidal integration result (trapz):", result) # torch.trapezoid is the preferred alias and yields the exact same result result2 = torch.trapezoid(y, dx=1.0) print("Trapezoidal integration result (trapezoid):", result2) ``` **Output:** ```text Trapezoidal integration result (trapz): tensor(7.5000) Trapezoidal integration result (trapezoid): tensor(7.5000) ``` *Explanation of the calculation:* $$\text{Area} = \frac{1.0 + 2.0}{2}(1.0) + \frac{2.0 + 3.0}{2}(1.0) + \frac{3.0 + 4.0}{2}(1.0) = 1.5 + 2.5 + 3.5 = 7.5$$ --- ### Example 2: Integration with Non-Uniform Spacing (`x`) If your sample points are not evenly spaced, you can pass the coordinate tensor `x` explicitly. ```python import torch # Function values y = torch.tensor([1.0, 4.0, 9.0]) # Non-uniformly spaced coordinates x = torch.tensor([0.0, 1.0, 3.0]) # Integrate along the specified coordinates result = torch.trapz(y, x=x) print("Integration with non-uniform spacing:", result) ``` **Output:** ```text Integration with non-uniform spacing: tensor(15.5000) ``` *Explanation of the calculation:* $$\text{Area} = \frac{1.0 + 4.0}{2}(1.0 - 0.0) + \frac{4.0 + 9.0}{2}(3.0 - 1.0) = 2.5(1) + 6.5(2) = 2.5 + 13.0 = 15.5$$ --- ### Example 3: Multi-Dimensional Integration You can perform integration along a specific dimension of a multi-dimensional tensor using the `dim` parameter. ```python import torch # A 2D tensor of shape (2, 3) y = torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]) # Integrate along the columns (dim=-1, which is the default) result_dim_cols = torch.trapz(y, dx=1.0, dim=-1) # Integrate along the rows (dim=0) result_dim_rows = torch.trapz(y, dx=1.0, dim=0) print("Integration along columns (dim=-1):", result_dim_cols) print("Integration along rows (dim=0):", result_dim_rows) ``` **Output:** ```text Integration along columns (dim=-1): tensor([4., 10.]) Integration along rows (dim=0): tensor([2.5000, 3.5000, 4.5000]) ``` --- ## Considerations and Best Practices 1. **Deprecation Warning**: While `torch.trapz` is widely used, PyTorch documentation recommends using `torch.trapezoid` in newer codebases as it aligns with standard mathematical naming conventions. 2. **Dimensionality**: The output tensor will have one fewer dimension than the input tensor `y`, as the dimension specified by `dim` is compressed during integration. 3. **Performance**: Both `torch.trapz` and `torch.trapezoid` support GPU acceleration. If your tensors are on a CUDA device, the integration will run on the GPU automatically.