1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
// SPDX-License-Identifier: AGPL-3.0-or-later
//! Huber Loss - GPU-accelerated robust regression loss
//!
//! **Deep Debt Principles**:
//! - ✅ Pure WGSL implementation (uses existing shader!)
//! - ✅ Safe Rust wrapper (no unsafe code)
//! - ✅ Hardware-agnostic via WebGPU
//! - ✅ Complete implementation (production-ready for robust regression)
//!
//! ## Algorithm
//!
//! ```text
//! Huber(x, y, δ) = 0.5 * (x - y)² if |x - y| ≤ δ
//! = δ * (|x - y| - 0.5 * δ) otherwise
//! ```
//!
//! **Parameters**:
//! - `delta`: Threshold for switching from quadratic (MSE) to linear (MAE)
//!
//! **Key Properties**:
//! - Robust to outliers (less sensitive than MSE)
//! - Smooth at zero (differentiable everywhere)
//! - Quadratic for small errors, linear for large errors
//! - Standard in reinforcement learning (DQN)
//!
//! **Used By**: DQN, robust regression, outlier-resistant training
//!
//! ## Usage
//!
//! ```rust,ignore
//! use barracuda::tensor::Tensor;
//!
//! let predictions = Tensor::randn(vec![1000]).await?;
//! let targets = Tensor::randn(vec![1000]).await?;
//!
//! let loss = predictions.huber_loss(&targets, 1.0)?; // delta=1.0
//! ```
use crate::device::compute_pipeline::ComputeDispatch;
use crate::error::{BarracudaError, Result};
use crate::tensor::Tensor;
/// f64 is the canonical source — math is universal, precision is silicon.
const SHADER_F64: &str = include_str!("../shaders/loss/huber_loss_f64.wgsl");
/// f32 variant derived from f64 via precision downcast.
static SHADER_F32: std::sync::LazyLock<String> =
std::sync::LazyLock::new(|| SHADER_F64.to_string());
#[repr(C)]
#[derive(Copy, Clone, Debug, bytemuck::Pod, bytemuck::Zeroable)]
struct HuberLossParams {
delta: f32,
reduction_mode: u32,
size: u32,
_padding: u32,
}
/// Huber loss for robust regression (quadratic for small errors, linear for large).
pub struct HuberLoss {
predictions: Tensor,
targets: Tensor,
delta: f32,
}
impl HuberLoss {
fn wgsl_shader() -> &'static str {
&SHADER_F32
}
/// Execute Huber loss computation and return the result tensor.
///
/// # Errors
///
/// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
/// readback fails (e.g. device lost or out of memory).
pub fn execute(self) -> Result<Tensor> {
let device = self.predictions.device();
let size = self.predictions.shape().iter().product::<usize>();
let params = HuberLossParams {
delta: self.delta,
reduction_mode: 0, // mean reduction
size: size as u32,
_padding: 0,
};
let output_buffer = device.device.create_buffer(&wgpu::BufferDescriptor {
label: Some("huber_loss_output"),
size: (size * std::mem::size_of::<f32>()) as u64,
usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
mapped_at_creation: false,
});
let params_buffer = device.create_uniform_buffer("huber_loss_params", ¶ms);
ComputeDispatch::new(device, "huber_loss")
.shader(Self::wgsl_shader(), "main")
.storage_read(0, self.predictions.buffer())
.storage_read(1, self.targets.buffer())
.storage_rw(2, &output_buffer)
.uniform(3, ¶ms_buffer)
.dispatch_1d(size as u32)
.submit()?;
Ok(Tensor::from_buffer(
output_buffer,
self.predictions.shape().to_vec(),
device.clone(),
))
}
}
// ═══════════════════════════════════════════════════════════════
// TENSOR API INTEGRATION
// ═══════════════════════════════════════════════════════════════
impl Tensor {
/// Huber loss for robust regression (less sensitive to outliers than MSE)
///
/// **Deep Debt**: Essential for robust regression and reinforcement learning
///
/// # Arguments
/// - `targets`: Ground truth values [same shape as predictions]
/// - `delta`: Threshold for switching from quadratic to linear (typically 1.0)
///
/// # Returns
/// - Loss tensor [same shape as input]
///
/// # Example
/// ```rust,ignore
/// // DQN-style Huber loss
/// let loss = predictions.huber_loss(&targets, 1.0)?;
///
/// // More sensitive to outliers (larger delta)
/// let loss = predictions.huber_loss(&targets, 2.0)?;
/// ```
///
/// # Note
/// - `delta=1.0`: Standard for DQN (Deep Q-Network)
/// - Small delta: More robust (less outlier influence)
/// - Large delta: Closer to MSE behavior
/// - Combines MSE (small errors) + MAE (large errors)
///
/// # Errors
///
/// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
/// readback fails (e.g. device lost or out of memory).
pub fn huber_loss(self, targets: &Self, delta: f32) -> Result<Self> {
// Validate shapes match
if self.shape() != targets.shape() {
return Err(BarracudaError::shape_mismatch(
self.shape().to_vec(),
targets.shape().to_vec(),
));
}
// Validate delta is positive
if delta <= 0.0 {
return Err(BarracudaError::invalid_op(
"HuberLoss",
format!("delta must be positive, got {delta}"),
));
}
let op = HuberLoss {
predictions: self,
targets: targets.clone(),
delta,
};
op.execute()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test]
async fn test_huber_loss_small_errors() {
let device = crate::device::test_pool::get_test_device().await;
// Small errors (< delta): should use quadratic (MSE-like)
let predictions = Tensor::from_vec_on(vec![1.0, 2.0, 3.0, 4.0], vec![4], device.clone())
.await
.unwrap();
let targets = Tensor::from_vec_on(vec![1.1, 2.1, 2.9, 3.9], vec![4], device.clone())
.await
.unwrap();
let result = predictions.huber_loss(&targets, 1.0).unwrap();
let loss = result.to_vec().unwrap();
assert_eq!(loss.len(), 4);
// All errors = 0.1, which is < delta=1.0
// Loss should be 0.5 * 0.1^2 = 0.005
for &l in &loss {
assert!((l - 0.005).abs() < 1e-5, "Expected 0.005, got {l}");
}
}
#[tokio::test]
async fn test_huber_loss_large_errors() {
let device = crate::device::test_pool::get_test_device().await;
// Large errors (> delta): should use linear (MAE-like)
let predictions = Tensor::from_vec_on(vec![1.0, 2.0], vec![2], device.clone())
.await
.unwrap();
let targets = Tensor::from_vec_on(vec![3.0, 5.0], vec![2], device.clone())
.await
.unwrap();
let result = predictions.huber_loss(&targets, 1.0).unwrap();
let loss = result.to_vec().unwrap();
assert_eq!(loss.len(), 2);
// Error 1: |1-3| = 2 > delta=1, loss = 1*(2 - 0.5*1) = 1.5
assert!(
(loss[0] - 1.5).abs() < 1e-5,
"Expected 1.5, got {}",
loss[0]
);
// Error 2: |2-5| = 3 > delta=1, loss = 1*(3 - 0.5*1) = 2.5
assert!(
(loss[1] - 2.5).abs() < 1e-5,
"Expected 2.5, got {}",
loss[1]
);
}
}