YouTip

## PyTorch `torch.combinations` Tutorial The `torch.combinations` function in PyTorch is a utility used to compute all possible $r$-length combinations of elements from a 1D input tensor. It is highly useful in tasks involving combinatorics, graph generation, pair-wise distance calculations, and feature engineering. --- ## Function Definition ```python torch.combinations(input, r=2, with_replacement=False) ``` ### Parameters | Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | `input` | *Tensor* | Required | A 1D tensor containing the elements to combine. | | `r` | *int* | `2` | The length of each combination (the number of elements to choose). | | `with_replacement` | *bool* | `False` | If `True`, elements can be repeated within a single combination (combinations with replacement). If `False`, elements in each combination must be unique. | ### Return Value * **Tensor**: A 2D tensor of shape $(N, r)$, where $N$ is the total number of possible combinations, and each row represents a unique combination. --- ## Code Examples The following examples demonstrate how to use `torch.combinations` for standard combinations, higher-order combinations, and combinations with replacement. ```python import torch # Define a 1D input tensor x = torch.tensor([1, 2, 3, 4]) print("Input Tensor:", x) # 1. Compute all 2-element combinations (r=2, without replacement) result_r2 = torch.combinations(x, r=2) print("\n2-element combinations (r=2):") print(result_r2) # Output: # tensor([[1, 2], # [1, 3], # [1, 4], # [2, 3], # [2, 4], # [3, 4]]) # 2. Compute all 3-element combinations (r=3, without replacement) result_r3 = torch.combinations(x, r=3) print("\n3-element combinations (r=3):") print(result_r3) # Output: # tensor([[1, 2, 3], # [1, 2, 4], # [1, 3, 4], # [2, 3, 4]]) # 3. Compute 2-element combinations with replacement (with_replacement=True) result_with_replacement = torch.combinations(x, r=2, with_replacement=True) print("\n2-element combinations with replacement:") print(result_with_replacement) # Output: # tensor([[1, 1], # [1, 2], # [1, 3], # [1, 4], # [2, 2], # [2, 3], # [2, 4], # [3, 3], # [3, 4], # [4, 4]]) ``` --- ## Important Considerations 1. **Input Dimensionality**: `torch.combinations` only accepts **1D tensors** as input. Passing a multi-dimensional tensor will result in a `RuntimeError`. 2. **Memory Consumption**: The number of combinations grows exponentially with the size of the input tensor and the value of `r`. For an input of size $n$, the number of combinations without replacement is given by the binomial coefficient: $$\binom{n}{r} = \frac{n!}{r!(n-r)!}$$ Be cautious when using large tensors or large values of `r`, as this can easily lead to Out-Of-Memory (OOM) errors. 3. **Order of Elements**: The combinations are generated in lexicographical order based on the indices of the input tensor.