0
# Utilities and Helpers
1

2
Helper utilities for tensor operations, type conversions, logging setup, and reproducibility management. PyTorch Ignite provides essential utilities that support training workflows and make common operations more convenient.
3

4
## Capabilities
5

6
### Tensor Operations
7

8
Utilities for tensor manipulation and device management.
9

10
```python { .api }
11
def convert_tensor(input_, device=None, non_blocking=False):
12
    """
13
    Convert input to tensor and move to specified device.
14
    
15
    Parameters:
16
    - input_: input data (tensor, numpy array, list, etc.)
17
    - device: target device (torch.device, string, or None)
18
    - non_blocking: whether to use non-blocking transfer
19
    
20
    Returns:
21
    Converted tensor on target device
22
    """
23

24
def to_onehot(indices, num_classes):
25
    """
26
    Convert indices to one-hot encoding.
27
    
28
    Parameters:
29
    - indices: tensor of class indices
30
    - num_classes: total number of classes
31
    
32
    Returns:
33
    One-hot encoded tensor
34
    """
35

36
def apply_to_tensor(input_, func):
37
    """
38
    Apply function to all tensors in nested structure.
39
    
40
    Parameters:
41
    - input_: nested structure containing tensors
42
    - func: function to apply to each tensor
43
    
44
    Returns:
45
    Structure with function applied to all tensors
46
    """
47

48
def apply_to_type(input_, input_type, func):
49
    """
50
    Apply function to all objects of specific type in nested structure.
51
    
52
    Parameters:
53
    - input_: nested structure
54
    - input_type: type to match
55
    - func: function to apply to matched objects
56
    
57
    Returns:
58
    Structure with function applied to matched objects
59
    """
60
```
61

62
### Logging Setup
63

64
Utilities for configuring logging in training workflows.
65

66
```python { .api }
67
def setup_logger(name=None, level=logging.INFO, stream=None, format="%(asctime)s %(name)s %(levelname)s %(message)s", filepath=None, distributed_rank=None):
68
    """
69
    Setup logger with specified configuration.
70
    
71
    Parameters:
72
    - name: logger name (default: None for root logger)
73
    - level: logging level (default: logging.INFO)
74
    - stream: output stream (default: None for sys.stderr)
75
    - format: log message format string
76
    - filepath: path to log file (optional)
77
    - distributed_rank: rank for distributed training (optional)
78
    
79
    Returns:
80
    Configured logger instance
81
    """
82
```
83

84
### Reproducibility
85

86
Utilities for ensuring reproducible training runs.
87

88
```python { .api }
89
def manual_seed(seed):
90
    """
91
    Set manual seed for reproducibility across all relevant libraries.
92
    
93
    Parameters:
94
    - seed: random seed value
95
    
96
    Sets seeds for:
97
    - Python random module
98
    - NumPy random state
99
    - PyTorch random state
100
    - PyTorch CUDA random state (if available)
101
    """
102
```
103

104
## Usage Examples
105

106
### Tensor Conversion and Device Management
107

108
```python
109
from ignite.utils import convert_tensor
110
import torch
111

112
# Convert various inputs to tensors
113
data = [1, 2, 3, 4, 5]
114
tensor_data = convert_tensor(data)  # Convert list to tensor
115

116
# Move to specific device
117
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
118
tensor_on_device = convert_tensor(data, device=device)
119

120
# Non-blocking transfer for performance
121
tensor_nb = convert_tensor(data, device=device, non_blocking=True)
122

123
# Works with numpy arrays
124
import numpy as np
125
np_array = np.array([1.0, 2.0, 3.0])
126
tensor_from_np = convert_tensor(np_array, device=device)
127
```
128

129
### One-Hot Encoding
130

131
```python
132
from ignite.utils import to_onehot
133
import torch
134

135
# Convert class indices to one-hot
136
indices = torch.tensor([0, 1, 2, 1, 0])
137
num_classes = 3
138
onehot = to_onehot(indices, num_classes)
139
print(onehot)
140
# Output: tensor([[1, 0, 0],
141
#                 [0, 1, 0],
142
#                 [0, 0, 1],
143
#                 [0, 1, 0],
144
#                 [1, 0, 0]])
145

146
# Works with batch dimensions
147
batch_indices = torch.tensor([[0, 1], [2, 1]])
148
batch_onehot = to_onehot(batch_indices, num_classes)
149
print(batch_onehot.shape)  # torch.Size([2, 2, 3])
150
```
151

152
### Applying Functions to Nested Structures
153

154
```python
155
from ignite.utils import apply_to_tensor, apply_to_type
156
import torch
157

158
# Apply function to all tensors in nested structure
159
data = {
160
    'input': torch.randn(10, 5),
161
    'target': torch.randint(0, 2, (10,)),
162
    'metadata': {
163
        'weights': torch.ones(10),
164
        'info': 'some string'
165
    }
166
}
167

168
# Move all tensors to GPU
169
gpu_data = apply_to_tensor(data, lambda x: x.cuda() if torch.cuda.is_available() else x)
170

171
# Apply function to specific types
172
def double_tensors(x):
173
    return x * 2
174

175
doubled_data = apply_to_type(data, torch.Tensor, double_tensors)
176

177
# Custom type matching
178
class CustomClass:
179
    def __init__(self, value):
180
        self.value = value
181

182
data_with_custom = {
183
    'tensor': torch.randn(5),
184
    'custom': CustomClass(42),
185
    'nested': {
186
        'another_custom': CustomClass(24)
187
    }
188
}
189

190
def modify_custom(obj):
191
    obj.value *= 2
192
    return obj
193

194
modified_data = apply_to_type(data_with_custom, CustomClass, modify_custom)
195
```
196

197
### Logger Setup
198

199
```python
200
from ignite.utils import setup_logger
201
import logging
202

203
# Basic logger setup
204
logger = setup_logger()
205
logger.info("This is a basic log message")
206

207
# Custom logger with specific level
208
debug_logger = setup_logger(name="debug_logger", level=logging.DEBUG)
209
debug_logger.debug("Debug message")
210

211
# Logger with file output
212
file_logger = setup_logger(
213
    name="file_logger",
214
    level=logging.INFO,
215
    filepath="training.log",
216
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
217
)
218
file_logger.info("This will be written to training.log")
219

220
# Distributed training logger (only logs on rank 0)
221
import ignite.distributed as idist
222

223
dist_logger = setup_logger(
224
    name="distributed_logger",
225
    distributed_rank=idist.rank()
226
)
227
dist_logger.info("This only appears on rank 0")
228
```
229

230
### Reproducible Training
231

232
```python
233
from ignite.utils import manual_seed
234

235
# Set seed for reproducibility
236
manual_seed(42)
237

238
# Now all random operations will be reproducible
239
import torch
240
import numpy as np
241
import random
242

243
# These will produce the same results across runs
244
torch_random = torch.randn(3, 3)
245
np_random = np.random.randn(3, 3)
246
py_random = random.random()
247

248
# For complete reproducibility in training
249
manual_seed(42)
250
torch.backends.cudnn.deterministic = True
251
torch.backends.cudnn.benchmark = False
252

253
# Your training code here - results will be reproducible
254
```
255

256
### Integration with Training Loops
257

258
```python
259
from ignite.engine import Engine, Events
260
from ignite.utils import convert_tensor, setup_logger
261

262
# Setup logger for training
263
logger = setup_logger(name="trainer")
264

265
def train_step(engine, batch):
266
    model.train()
267
    optimizer.zero_grad()
268
    
269
    # Use convert_tensor for device management
270
    x, y = batch
271
    x = convert_tensor(x, device=device, non_blocking=True)
272
    y = convert_tensor(y, device=device, non_blocking=True)
273
    
274
    y_pred = model(x)
275
    loss = criterion(y_pred, y)
276
    loss.backward()
277
    optimizer.step()
278
    
279
    return loss.item()
280

281
trainer = Engine(train_step)
282

283
@trainer.on(Events.EPOCH_COMPLETED)
284
def log_results(engine):
285
    logger.info(f"Epoch {engine.state.epoch} completed")
286

287
# Set reproducible seed before training
288
manual_seed(42)
289
trainer.run(train_loader, max_epochs=10)
290
```
291

292
### Batch Processing Utilities
293

294
```python
295
from ignite.utils import apply_to_tensor
296
import torch
297

298
def prepare_batch(batch, device=None, non_blocking=False):
299
    """Custom batch preparation function."""
300
    # Move all tensors in batch to device
301
    def move_to_device(tensor):
302
        if device is not None:
303
            return tensor.to(device, non_blocking=non_blocking)
304
        return tensor
305
    
306
    return apply_to_tensor(batch, move_to_device)
307

308
# Use in training
309
def train_step(engine, batch):
310
    batch = prepare_batch(batch, device=device, non_blocking=True)
311
    # ... rest of training step
312
```