Skip to main content

coeus_nn/rnn/
bidirectional.rs

1// ── Bidirectional recurrent wrapper ──
2
3use crate::module::{prefixed_parameters, Module, ModuleError};
4use crate::rnn::validation;
5use coeus_autograd::Var;
6use coeus_core::Scalar;
7
8/// Bidirectional wrapper over any sequence [`Module`] (e.g. [`Rnn`](super::Rnn),
9/// [`Gru`](super::Gru), [`Lstm`](super::Lstm)).
10///
11/// Runs `forward_module` over the input and `backward_module` over the
12/// time-reversed input, then concatenates the two `[batch, seq, hidden]`
13/// outputs along the hidden axis to `[batch, seq, 2*hidden]` — matching PyTorch
14/// `bidirectional=True`. Generic over the cell type, so no per-cell code: the
15/// reversal and concatenation reuse the tracked `flip`/`cat` autograd ops.
16///
17/// The two sub-modules carry independent parameters (PyTorch likewise learns
18/// separate forward/backward weights).
19#[derive(Clone)]
20pub struct Bidirectional<M> {
21    /// Module applied to the sequence in forward (left-to-right) order.
22    pub forward_module: M,
23    /// Module applied to the time-reversed sequence.
24    pub backward_module: M,
25}
26
27impl<M> Bidirectional<M> {
28    /// Wrap a forward and a (time-reversed) backward sequence module.
29    pub fn new(forward_module: M, backward_module: M) -> Self {
30        Self {
31            forward_module,
32            backward_module,
33        }
34    }
35}
36
37impl<T, B, M> Module<T, B> for Bidirectional<M>
38where
39    T: Scalar,
40    B: coeus_ops::BackendOps<T> + Default,
41    M: Module<T, B>,
42    B::DeviceBuffer<T>:
43        coeus_core::CpuAddressableStorage<T> + coeus_core::CpuAddressableStorageMut<T>,
44{
45    fn parameters(&self) -> Vec<Var<T, B>> {
46        let mut p = self.forward_module.parameters();
47        p.extend(self.backward_module.parameters());
48        p
49    }
50
51    fn named_parameters(&self) -> Vec<coeus_autograd::Parameter<T, B>> {
52        let mut parameters = prefixed_parameters("forward", &self.forward_module);
53        parameters.extend(prefixed_parameters("backward", &self.backward_module));
54        parameters
55    }
56
57    /// `x`: `[batch, seq_len, input_size]` → `[batch, seq_len, 2*hidden_size]`.
58    fn forward(&self, x: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
59        let (batch, sequence) = validation::sequence_layout(x.tensor.shape(), "Bidirectional")?;
60        let fwd = self.forward_module.forward(x)?;
61        validation::child_sequence_output(
62            fwd.tensor.shape(),
63            batch,
64            sequence,
65            "Bidirectional",
66            "forward output",
67        )?;
68        // Reverse along the time axis, run the backward module, then restore order.
69        let rev_x = coeus_autograd::flip(x, 1)?;
70        let bwd_rev = self.backward_module.forward(&rev_x)?;
71        validation::child_sequence_output(
72            bwd_rev.tensor.shape(),
73            batch,
74            sequence,
75            "Bidirectional",
76            "backward output",
77        )?;
78        validation::matching_child_outputs(fwd.tensor.shape(), bwd_rev.tensor.shape())?;
79        let bwd = coeus_autograd::flip(&bwd_rev, 1)?;
80        Ok(coeus_autograd::cat(&[&fwd, &bwd], 2)?)
81    }
82}