coeus-nn 0.14.0

Neural-network layers and operators for Coeus.
Documentation
// ── Sequential module combinator ──
//
// Sequential<T, B> chains a runtime-dynamic list of boxed modules.
// `dyn Module<T, B>` is justified here by condition (1) in the architecture rules:
// the concrete layer types are genuinely unknown at compile time and type erasure
// is the domain requirement for a user-constructable heterogeneous module stack.

use crate::module::{prefixed_parameters, Module, ModuleError};
use coeus_autograd::Var;
use coeus_core::{ComputeBackend, MoiraiBackend, Scalar};

/// A sequential container that chains modules.
///
/// `forward` passes the output of each module as the input to the next.
///
/// # Example
/// ```rust,ignore
/// let mut seq = Sequential::<f64>::new();
/// seq.add(Linear::new(64, 128, true));
/// seq.add(ReLU);
/// seq.add(Linear::new(128, 10, true));
/// let output = seq.forward(&input).expect("valid Sequential input");
/// ```
pub struct Sequential<T: Scalar, B: ComputeBackend + Default = MoiraiBackend> {
    /// Type-erased module list. dyn dispatch is justified: types are unknown at compile time.
    layers: Vec<Box<dyn Module<T, B>>>,
}

impl<T: Scalar, B: ComputeBackend + Default> Sequential<T, B> {
    /// Create an empty Sequential.
    pub fn new() -> Self {
        Self { layers: Vec::new() }
    }

    /// Append a module to the end of the sequence.
    ///
    /// Returns `&mut Self` to enable method chaining.
    pub fn add<M: Module<T, B> + 'static>(&mut self, module: M) -> &mut Self {
        self.layers.push(Box::new(module));
        self
    }

    /// Return the number of modules in this sequential.
    #[inline]
    pub fn len(&self) -> usize {
        self.layers.len()
    }

    /// Return true if this sequential has no modules.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.layers.is_empty()
    }
}

impl<T: Scalar, B: ComputeBackend + Default> Default for Sequential<T, B> {
    fn default() -> Self {
        Self::new()
    }
}

impl<T: Scalar, B: ComputeBackend + Default> Module<T, B> for Sequential<T, B> {
    fn parameters(&self) -> Vec<Var<T, B>> {
        self.layers.iter().flat_map(|m| m.parameters()).collect()
    }

    fn named_parameters(&self) -> Vec<coeus_autograd::Parameter<T, B>> {
        self.layers
            .iter()
            .enumerate()
            .flat_map(|(index, module)| {
                prefixed_parameters(&format!("layers.{index}"), module.as_ref())
            })
            .collect()
    }

    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
        self.layers
            .iter()
            .try_fold(input.clone(), |x, module| module.forward(&x))
    }

    fn train(&mut self, mode: bool) {
        for m in &mut self.layers {
            m.train(mode);
        }
    }

    fn load_parameters(&mut self, params: &[Var<T, B>]) {
        let mut offset = 0;
        for m in &mut self.layers {
            let n = m.parameters().len();
            m.load_parameters(&params[offset..offset + n]);
            offset += n;
        }
    }
}

/// A compile-time static sequential container that chains modules.
///
/// Chaining is achieved via nested `StaticSeq<H, T>` structs created using
/// the `ModuleExt::append` builder method. Evaluation is fully monomorphized
/// at compile-time by the Rust compiler, eliminating all dynamic dispatch.
///
/// # Example
/// ```rust,ignore
/// let model = Linear::new(64, 128)
///     .append(ReLU)
///     .append(Linear::new(128, 10));
/// let output = model.forward(&input).expect("valid Chain input");
/// ```
#[derive(Clone, Copy, Debug)]
pub struct StaticSeq<H, T>(pub H, pub T);

impl<
        ScalarType: Scalar,
        B: ComputeBackend + Default,
        H: Module<ScalarType, B>,
        T: Module<ScalarType, B>,
    > Module<ScalarType, B> for StaticSeq<H, T>
{
    #[inline]
    fn parameters(&self) -> Vec<Var<ScalarType, B>> {
        let mut params = self.0.parameters();
        params.extend(self.1.parameters());
        params
    }

    fn named_parameters(&self) -> Vec<coeus_autograd::Parameter<ScalarType, B>> {
        let mut parameters = prefixed_parameters("head", &self.0);
        parameters.extend(prefixed_parameters("tail", &self.1));
        parameters
    }

    #[inline]
    fn forward(
        &self,
        input: &Var<ScalarType, B>,
    ) -> Result<Var<ScalarType, B>, ModuleError<B::Error>> {
        let out = self.0.forward(input)?;
        self.1.forward(&out)
    }

    #[inline]
    fn train(&mut self, mode: bool) {
        self.0.train(mode);
        self.1.train(mode);
    }

    #[inline]
    fn load_parameters(&mut self, params: &[Var<ScalarType, B>]) {
        let n0 = self.0.parameters().len();
        self.0.load_parameters(&params[..n0]);
        self.1.load_parameters(&params[n0..]);
    }
}

/// Extension trait for all `Module`s, enabling fluent construction of `StaticSeq` chains.
pub trait ModuleExt<T: Scalar, B: ComputeBackend + Default>: Module<T, B> {
    /// Append another module to the end of the sequence.
    fn append<M: Module<T, B>>(self, next: M) -> StaticSeq<Self, M>
    where
        Self: Sized;
}

impl<T: Scalar, B: ComputeBackend + Default, M: Module<T, B>> ModuleExt<T, B> for M {
    #[inline]
    fn append<Next: Module<T, B>>(self, next: Next) -> StaticSeq<Self, Next> {
        StaticSeq(self, next)
    }
}