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
//! Provider-selected mean cross-entropy capability.
use coeus_core::{ComputeBackend, Layout, Scalar};
/// Mean cross-entropy forward and additive-backward dispatch.
///
/// Backends choose their provider through the implementation: CPU backends
/// call Leto over borrowed storage, while accelerator backends call
/// Hephaestus over device-resident buffers.
pub trait CrossEntropyOps<T: Scalar>: ComputeBackend {
/// Provider-native target representation retained for backward.
type Targets: Send + Sync + 'static;
/// Validate and retain one target index per batch row.
///
/// # Errors
///
/// Returns a typed backend error when a target cannot be represented by
/// the selected provider.
fn prepare_cross_entropy_targets(
&self,
targets: &[usize],
) -> Result<Self::Targets, Self::Error>;
/// Write mean loss and saved probabilities without changing providers.
///
/// # Errors
///
/// Returns a typed validation, preparation, or dispatch failure. Provider
/// validation completes before either destination changes.
#[expect(
clippy::too_many_arguments,
reason = "the method carries the complete provider forward contract"
)]
fn cross_entropy_forward(
&self,
logits: &Self::DeviceBuffer<T>,
logits_layout: &Layout,
targets: &Self::Targets,
loss: &mut Self::DeviceBuffer<T>,
loss_layout: &Layout,
probabilities: &mut Self::DeviceBuffer<T>,
probabilities_layout: &Layout,
) -> Result<(), Self::Error>;
/// Add the mean-reduced logit gradient into caller-owned storage.
///
/// # Errors
///
/// Returns a typed validation, preparation, or dispatch failure. Provider
/// validation completes before the destination changes.
#[expect(
clippy::too_many_arguments,
reason = "the method carries the complete provider backward contract"
)]
fn cross_entropy_backward_accumulate(
&self,
output_gradient: &Self::DeviceBuffer<T>,
output_gradient_layout: &Layout,
probabilities: &Self::DeviceBuffer<T>,
probabilities_layout: &Layout,
targets: &Self::Targets,
logit_gradient: &mut Self::DeviceBuffer<T>,
logit_gradient_layout: &Layout,
) -> Result<(), Self::Error>;
}