Skip to main content

coeus_nn/
bilinear.rs

1// ── Bilinear ──
2//
3// out = x1 @ W @ x2.T + b  for feature interaction.
4// W shape: [out_features, in1_features, in2_features]
5
6use crate::module::{Module, ModuleError};
7use coeus_autograd::Var;
8use coeus_core::{Float, MoiraiBackend};
9use coeus_tensor::Tensor;
10
11/// Functional bilinear interaction.
12///
13/// Computes:
14/// `out[n, k] = Σ_{i,j} x1[n,i] * weight[k,i,j] * x2[n,j] + bias[k]`.
15///
16/// # Shapes
17/// - `x1`: `[batch, in1_features]`
18/// - `x2`: `[batch, in2_features]`
19/// - `weight`: `[out_features, in1_features, in2_features]`
20/// - `bias` (optional): `[out_features]`
21/// - Output: `[batch, out_features]`
22///
23/// # Panics
24/// Panics if input shapes are incompatible.
25pub fn bilinear<T: Float + coeus_cpu::RealScalar, B: coeus_ops::BackendOps<T> + Default>(
26    x1: &Var<T, B>,
27    x2: &Var<T, B>,
28    weight: &Var<T, B>,
29    bias: Option<&Var<T, B>>,
30) -> Result<Var<T, B>, B::Error>
31where
32    B::DeviceBuffer<T>:
33        coeus_core::CpuAddressableStorage<T> + coeus_core::CpuAddressableStorageMut<T>,
34{
35    let x1_shape = x1.tensor.shape();
36    let x2_shape = x2.tensor.shape();
37    let w_shape = weight.tensor.shape();
38    assert_eq!(
39        x1_shape.len(),
40        2,
41        "bilinear: x1 must be rank-2 [batch, in1]"
42    );
43    assert_eq!(
44        x2_shape.len(),
45        2,
46        "bilinear: x2 must be rank-2 [batch, in2]"
47    );
48    assert_eq!(
49        w_shape.len(),
50        3,
51        "bilinear: weight must be rank-3 [out, in1, in2]"
52    );
53    let batch = x1_shape[0];
54    let in1 = x1_shape[1];
55    let in2 = x2_shape[1];
56    let out_features = w_shape[0];
57    assert_eq!(x2_shape[0], batch, "bilinear: x1/x2 batch mismatch");
58    assert_eq!(
59        w_shape[1], in1,
60        "bilinear: weight in1 dimension must match x1 feature dimension"
61    );
62    assert_eq!(
63        w_shape[2], in2,
64        "bilinear: weight in2 dimension must match x2 feature dimension"
65    );
66    if let Some(bias) = bias {
67        assert_eq!(
68            bias.tensor.shape(),
69            &[out_features],
70            "bilinear: bias must have shape [out_features]"
71        );
72    }
73
74    let mut out_rows: Vec<Var<T, B>> = Vec::with_capacity(out_features);
75    for k in 0..out_features {
76        let w_k_var = coeus_autograd::slice(weight, &[(k, k + 1), (0, in1), (0, in2)])?;
77        let w_k = coeus_autograd::reshape(&w_k_var, vec![in1, in2])?;
78        let x1w = coeus_autograd::matmul(x1, &w_k)?;
79        let prod = coeus_autograd::mul(&x1w, x2)?;
80        let row = coeus_autograd::sum_axis(&prod, 1)?;
81        out_rows.push(row);
82    }
83    let refs: Vec<&Var<T, B>> = out_rows.iter().collect();
84    let out = coeus_autograd::cat(&refs, 1)?;
85    if let Some(b) = bias {
86        Ok(coeus_autograd::add(&out, b)?)
87    } else {
88        Ok(out)
89    }
90}
91
92/// Bilinear layer: `out[n] = Σ_{ij} x1[n,i] * W[k,i,j] * x2[n,j] + b[k]`
93///
94/// Equivalent to `torch.nn.Bilinear(in1_features, in2_features, out_features)`.
95///
96/// Shapes:
97/// - `x1`: `[batch, in1_features]`
98/// - `x2`: `[batch, in2_features]`
99/// - `W`:  `[out_features, in1_features, in2_features]`
100/// - `b`:  `[out_features]`
101/// - output: `[batch, out_features]`
102#[derive(Clone)]
103pub struct Bilinear<T: Float, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
104    /// Weight tensor: `[out_features, in1_features, in2_features]`.
105    pub weight: Var<T, B>,
106    /// Bias vector: `[out_features]`.
107    pub bias: Option<Var<T, B>>,
108    /// Number of input features for the first operand.
109    pub in1_features: usize,
110    /// Number of input features for the second operand.
111    pub in2_features: usize,
112    /// Number of output features.
113    pub out_features: usize,
114}
115
116impl<T: Float + coeus_cpu::RealScalar, B: coeus_ops::BackendOps<T> + Default> Bilinear<T, B> {
117    /// Create with Xavier-initialized weight and zero bias.
118    ///
119    /// # Errors
120    ///
121    /// Returns an initialization error when the input fan product overflows,
122    /// a fan is zero, or the selected backend cannot initialize the weight.
123    pub fn new(
124        in1_features: usize,
125        in2_features: usize,
126        out_features: usize,
127        bias: bool,
128    ) -> Result<Self, crate::init::InitializationError<B::Error>>
129    where
130        T: coeus_cpu::RealScalar,
131        B: coeus_ops::RandomInitOps<T>,
132    {
133        let backend = B::default();
134        let fan_in = in1_features.checked_mul(in2_features).ok_or(
135            crate::init::InitializationError::FanProductOverflow {
136                lhs_name: "in1_features",
137                lhs: in1_features,
138                rhs_name: "in2_features",
139                rhs: in2_features,
140            },
141        )?;
142        let mut w = Var::new(
143            Tensor::zeros_on([out_features, in1_features, in2_features], &backend)?,
144            true,
145        )?;
146        crate::init::xavier_uniform(&mut w, fan_in, out_features)?;
147        let b = if bias {
148            Some(Var::new(Tensor::zeros_on([out_features], &backend)?, true)?)
149        } else {
150            None
151        };
152        Ok(Self {
153            weight: w,
154            bias: b,
155            in1_features,
156            in2_features,
157            out_features,
158        })
159    }
160
161    /// Forward pass.
162    ///
163    /// Computed as: for each output feature k:
164    ///   `out[n,k] = x1[n,:] @ W[k,:,:] @ x2[n,:].T`
165    /// then optionally adds `b[k]`.
166    pub fn bilinear_forward(&self, x1: &Var<T, B>, x2: &Var<T, B>) -> Result<Var<T, B>, B::Error>
167    where
168        B::DeviceBuffer<T>:
169            coeus_core::CpuAddressableStorage<T> + coeus_core::CpuAddressableStorageMut<T>,
170    {
171        bilinear(x1, x2, &self.weight, self.bias.as_ref())
172    }
173}
174
175impl<T: Float + coeus_cpu::RealScalar, B: coeus_ops::BackendOps<T> + Default> Module<T, B>
176    for Bilinear<T, B>
177where
178    B::DeviceBuffer<T>:
179        coeus_core::CpuAddressableStorage<T> + coeus_core::CpuAddressableStorageMut<T>,
180{
181    fn parameters(&self) -> Vec<Var<T, B>> {
182        let mut p = vec![self.weight.clone()];
183        if let Some(ref b) = self.bias {
184            p.push(b.clone());
185        }
186        p
187    }
188
189    fn forward(&self, x1: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
190        let shape = x1.tensor.shape();
191        if shape.len() != 2 {
192            return Err(ModuleError::InvalidRank {
193                module: "Bilinear",
194                expected: "2",
195                actual: shape.len(),
196            });
197        }
198        let features = shape[1];
199        if features != self.in1_features {
200            return Err(ModuleError::ShapeMismatch {
201                module: "Bilinear",
202                parameter: "input features",
203                expected: vec![self.in1_features],
204                actual: vec![features],
205            });
206        }
207        if features != self.in2_features {
208            return Err(ModuleError::ShapeMismatch {
209                module: "Bilinear",
210                parameter: "self-interaction features",
211                expected: vec![self.in2_features],
212                actual: vec![features],
213            });
214        }
215        let expected_weight = vec![self.out_features, self.in1_features, self.in2_features];
216        if self.weight.tensor.shape() != expected_weight {
217            return Err(ModuleError::ShapeMismatch {
218                module: "Bilinear",
219                parameter: "weight",
220                expected: expected_weight,
221                actual: self.weight.tensor.shape_cloned().to_vec(),
222            });
223        }
224        if let Some(bias) = &self.bias {
225            if bias.tensor.shape() != [self.out_features] {
226                return Err(ModuleError::ShapeMismatch {
227                    module: "Bilinear",
228                    parameter: "bias",
229                    expected: vec![self.out_features],
230                    actual: bias.tensor.shape_cloned().to_vec(),
231                });
232            }
233        }
234        Ok(self.bilinear_forward(x1, x1)?)
235    }
236}