YouTipPytorch Torch Nan_To_Num
## PyTorch `torch.nan_to_num`
The `torch.nan_to_num` function in PyTorch is a utility used to replace `NaN` (Not a Number), positive infinity (`inf`), and negative infinity (`-inf`) values in a tensor with specified, finite numerical values.
This function is highly useful during data preprocessing and model training to prevent numerical instability, such as gradient explosions or propagation of undefined values.
---
## Syntax
```python
torch.nan_to_num(input, nan=0.0, posinf=None, neginf=None, *, out=None) -> Tensor
```
### Parameter Details
| Parameter | Type | Required/Optional | Description |
| :--- | :--- | :--- | :--- |
| `input` | `Tensor` | **Required** | The input tensor containing values to be replaced. |
| `nan` | `Number` | Optional | The value to replace `NaN` with. Default is `0.0`. |
| `posinf` | `Number` | Optional | The value to replace positive infinity (`inf`) with. If set to `None` (default), positive infinity is replaced with the greatest finite value representable by the input tensor's data type. |
| `neginf` | `Number` | Optional | The value to replace negative infinity (`-inf`) with. If set to `None` (default), negative infinity is replaced with the lowest finite value representable by the input tensor's data type. |
| `out` | `Tensor` | Optional | The output tensor. |
---
## Code Examples
### Example 1: Basic Usage (Replacing NaN and Infinities)
In this example, we replace `NaN` with `0.0`, and let PyTorch automatically handle positive and negative infinity values by replacing them with the maximum and minimum representable values for the tensor's data type (`float32`).
```python
import torch
# Create a tensor containing NaN, positive infinity, and negative infinity
x = torch.tensor([1.0, float('nan'), 3.0, float('inf'), float('-inf')])
# Replace NaN with 0.0, and let infinities default to their type limits
result = torch.nan_to_num(x, nan=0.0)
print("Original Tensor:")
print(x)
print("\nProcessed Tensor:")
print(result)
```
**Output:**
```text
Original Tensor:
tensor([ 1.0000, nan, 3.0000, inf, -inf])
Processed Tensor:
tensor([ 1.0000e+00, 0.0000e+00, 3.0000e+00, 3.4028e+38, -3.4028e+38])
```
---
### Example 2: Custom Values for Infinities
You can also specify custom values to replace positive and negative infinities instead of using the data type limits.
```python
import torch
# Create a tensor with NaN and infinity values
x = torch.tensor([2.5, float('nan'), float('inf'), float('-inf')])
# Replace NaN with 0.0, posinf with 999.0, and neginf with -999.0
result = torch.nan_to_num(x, nan=0.0, posinf=999.0, neginf=-999.0)
print(result)
```
**Output:**
```text
tensor([ 2.5000, 0.0000, 999.0000, -999.0000])
```
---
### Example 3: In-Place Operation
If you want to modify the tensor in-place to save memory, you can use the in-place version of the function: `torch.nan_to_num_` (with a trailing underscore).
```python
import torch
x = torch.tensor([1.2, float('nan'), float('inf')])
# Modify the tensor in-place
x.nan_to_num_(nan=-1.0, posinf=100.0)
print(x)
```
**Output:**
```text
tensor([ 1.2000, -1.0000, 100.0000])
```
---
## Considerations
1. **Data Type Limits**: When `posinf` and `neginf` are not specified (left as `None`), they default to the maximum and minimum values of the tensor's data type. For example:
* For `torch.float32`, `posinf` becomes $\approx 3.40282 \times 10^{38}$.
* For `torch.float16`, `posinf` becomes $65504$.
2. **Integer Tensors**: Since integer tensors cannot represent `NaN`, `inf`, or `-inf`, calling `torch.nan_to_num` on an integer tensor will return the input tensor unchanged.
3. **Gradients**: This operation is differentiable. However, gradients flowing back through replaced values will be zero.