# Utility Modules

The utility modules provide monitoring, profiling, and optimization tools for RAPiD feature extraction.

## MemoryMonitor

Real-time memory usage monitoring during RAPiD computation.

### Methods

#### `start_monitoring()`

Starts monitoring memory usage.

#### `stop_monitoring()`

Stops monitoring and returns memory statistics.

#### `get_memory_usage()`

Returns current memory usage information.

### Example

```python
from rapid_seg.utils import MemoryMonitor

# Initialize monitor
monitor = MemoryMonitor()

# Start monitoring
monitor.start_monitoring()

# Perform RAPiD computation
calculator = RAPiDCalculator(device="cuda")
features = calculator.compute_rapid_features(coordinates, reflectivity, k=8)

# Stop monitoring and get results
stats = monitor.stop_monitoring()
print(f"Peak memory usage: {stats.peak_memory_mb:.2f} MB")
print(f"Average memory usage: {stats.avg_memory_mb:.2f} MB")
```

## MemoryProfiler

Detailed memory profiling with allocation tracking.

### Methods

#### `profile_function(func, *args, **kwargs)`

Profiles memory usage of a specific function.

**Parameters:**
- `func`: Function to profile
- `*args, **kwargs`: Function arguments

**Returns:**
- Memory profile results

#### `get_memory_breakdown()`

Returns detailed memory usage breakdown by component.

### Example

```python
from rapid_seg.utils import MemoryProfiler

profiler = MemoryProfiler()

# Profile RAPiD computation
def compute_features():
    return calculator.compute_rapid_features(coordinates, reflectivity, k=8)

results = profiler.profile_function(compute_features)
print(f"Memory allocated: {results.total_allocated_mb:.2f} MB")
print(f"Memory freed: {results.total_freed_mb:.2f} MB")
```

## Memory Requirements Estimation

### `estimate_memory_requirements(n_points, k, batch_size, precision="float32")`

Estimates memory requirements for RAPiD computation.

**Parameters:**
- `n_points`: Number of points in the point cloud
- `k`: Number of nearest neighbors
- `batch_size`: Processing batch size
- `precision`: Data precision

**Returns:**
- Estimated memory requirements in MB

### Example

```python
from rapid_seg.utils import estimate_memory_requirements

# Estimate memory for large point cloud
memory_mb = estimate_memory_requirements(
    n_points=100000,
    k=8,
    batch_size=32,
    precision="float32"
)

print(f"Estimated memory requirement: {memory_mb:.2f} MB")

# Check if system has enough memory
if memory_mb > available_memory_mb:
    print("Warning: Insufficient memory available")
    # Adjust batch size or k value
```

## RAPiD Computation Monitoring

### `monitor_rapid_computation(calculator, coordinates, reflectivity, k)`

Monitors RAPiD computation with comprehensive metrics.

**Parameters:**
- `calculator`: RAPiDCalculator instance
- `coordinates`: Point cloud coordinates
- `reflectivity`: Reflectivity values
- `k`: Number of neighbors

**Returns:**
- Computation metrics and memory usage

### Example

```python
from rapid_seg.utils import monitor_rapid_computation

# Monitor computation with detailed metrics
metrics = monitor_rapid_computation(calculator, coordinates, reflectivity, k=8)

print(f"Computation time: {metrics.computation_time:.3f} seconds")
print(f"Memory usage: {metrics.memory_usage_mb:.2f} MB")
print(f"GPU utilization: {metrics.gpu_utilization:.1f}%")
print(f"Throughput: {metrics.points_per_second:.0f} points/second")
```

## Performance Optimization Utilities

### Batch Size Optimization

```python
from rapid_seg.utils import optimize_batch_size

# Find optimal batch size for available memory
optimal_batch_size = optimize_batch_size(
    n_points=50000,
    k=8,
    available_memory_mb=8000,
    precision="float32"
)

print(f"Optimal batch size: {optimal_batch_size}")
```

### Device Selection

```python
from rapid_seg.utils import select_optimal_device

# Automatically select best available device
device = select_optimal_device(
    preferred_device="cuda",
    fallback_device="cpu",
    memory_requirement_mb=4000
)

print(f"Selected device: {device}")
```

## Logging and Debugging

The utility modules include comprehensive logging:

```python
import logging
from rapid_seg.utils import setup_logging

# Setup logging for debugging
setup_logging(level=logging.DEBUG, log_file="rapid_debug.log")

# Monitor will now log detailed information
monitor = MemoryMonitor()
monitor.start_monitoring()
```

## Integration with External Tools

### TensorBoard Integration

```python
from rapid_seg.utils import TensorBoardLogger

# Log metrics to TensorBoard
logger = TensorBoardLogger(log_dir="./logs")
logger.log_memory_usage(peak_memory_mb, avg_memory_mb)
logger.log_computation_time(computation_time)
```

### CSV Export

```python
from rapid_seg.utils import export_metrics_to_csv

# Export performance metrics
export_metrics_to_csv(
    metrics_list,
    output_file="rapid_performance.csv"
)
```