bunsen 0.42.0

bunsen is a batteries included common library for burn
Documentation
use burn::{
    module::Module,
    tensor::Device,
};

use crate::{
    burner::module::ModuleInit,
    errors::{
        BunsenResult,
        WithOkOrPanic,
    },
};

/// Lowers an upper *policy* config to the structure config that builds its
/// module.
///
/// The config-side twin of [`ModuleInit`]. Where `ModuleInit` turns a config
/// into a module, `ToStructureConfig` turns a policy config
/// (`FooContractConfig` and the like) into the unrolled `FooStructureConfig` of
/// a Stacked Config family. [`ModuleInit`'s Stacked Config
/// section](ModuleInit#stacked-config) describes the shape and carries a
/// compiled example of both pathways.
///
/// [`Structure`](Self::Structure) names the *lowest* structure config: the one
/// that implements `ModuleInit`. A policy that refines another policy still
/// names that structure config directly; the step from one policy to the next
/// stays an inherent method.
///
/// In the crate:
///
/// - [`ResNetContractConfig`] is the single-policy case, lowering to
///   [`ResNetStructureConfig`].
/// - [`SileroVadSignalConfig`] and [`SileroVadStftConfig`] are two chained
///   policies. The inherent [`to_stft`] refines the first into the second, and
///   both name [`SileroVadStructureConfig`] as their `Structure`.
/// - [`SwinTransformerV2ContractConfig`] has a fallible lowering: its
///   `try_to_structure` is where the policy is validated, and it returns an
///   [`Illegal`](crate::errors::BunsenErrorKind::Illegal) error for stages that
///   do not fit the input or the window.
///
/// The trait is in [`crate::prelude`], next to `ModuleInit`.
///
/// # `init` for free
///
/// Every implementor gets `ModuleInit<M>` for each module `M` its structure
/// config builds, through a blanket impl whose `try_init` is
/// `self.try_to_structure()?.try_init(device)`. So `policy.init(&device)` and
/// `policy.to_structure().init(&device)` build the same module.
///
/// The blanket impl cannot be overridden: a type that implements both this
/// trait and `ModuleInit` is a conflicting-implementations error (E0119). That
/// is on purpose. A policy builds its module only through its structure
/// config, so the two pathways cannot drift apart. Per-policy logic, including
/// validation, belongs in [`try_to_structure`](Self::try_to_structure).
///
/// ```compile_fail,E0119
/// use bunsen::prelude::*;
/// use burn::{
///     config::Config,
///     module::Module,
///     nn::{
///         Linear,
///         LinearConfig,
///     },
/// };
///
/// #[derive(Config, Debug)]
/// pub struct WideStructureConfig {
///     pub layer: LinearConfig,
/// }
///
/// impl ModuleInit<Wide> for WideStructureConfig {
///     fn try_init(
///         &self,
///         device: &Device,
///     ) -> BunsenResult<Wide> {
///         Ok(Wide {
///             layer: self.layer.init(device),
///         })
///     }
/// }
///
/// #[derive(Module, Debug)]
/// pub struct Wide {
///     layer: Linear,
/// }
///
/// #[derive(Config, Debug)]
/// pub struct WideContractConfig {
///     pub width: usize,
/// }
///
/// impl ToStructureConfig for WideContractConfig {
///     type Structure = WideStructureConfig;
///
///     fn try_to_structure(&self) -> BunsenResult<WideStructureConfig> {
///         Ok(WideStructureConfig::new(LinearConfig::new(
///             self.width,
///             2 * self.width,
///         )))
///     }
/// }
///
/// // error[E0119]: conflicting implementations of trait `ModuleInit<_, Wide<_>>`
/// impl ModuleInit<Wide> for WideContractConfig {
///     fn try_init(
///         &self,
///         device: &Device,
///     ) -> BunsenResult<Wide> {
///         self.try_to_structure()?.try_init(device)
///     }
/// }
/// ```
///
/// [`ResNetContractConfig`]: crate::kits::images::resnet::ResNetContractConfig
/// [`ResNetStructureConfig`]: crate::kits::images::resnet::ResNetStructureConfig
/// [`SileroVadSignalConfig`]: crate::kits::speech::vad::silero_vad::blocks::SileroVadSignalConfig
/// [`SileroVadStftConfig`]: crate::kits::speech::vad::silero_vad::blocks::SileroVadStftConfig
/// [`SileroVadStructureConfig`]: crate::kits::speech::vad::silero_vad::blocks::SileroVadStructureConfig
/// [`to_stft`]: crate::kits::speech::vad::silero_vad::blocks::SileroVadSignalConfig::to_stft
/// [`SwinTransformerV2ContractConfig`]: crate::kits::images::swin::v2::SwinTransformerV2ContractConfig
pub trait ToStructureConfig {
    /// The structure config this policy lowers to.
    type Structure;

    /// Lowers this policy to its structure config, or reports why the policy
    /// is invalid.
    fn try_to_structure(&self) -> BunsenResult<Self::Structure>;

    /// Lowers this policy to its structure config, panicking with the error's
    /// message if [`try_to_structure`](Self::try_to_structure) fails.
    fn to_structure(&self) -> Self::Structure {
        self.try_to_structure().ok_or_panic()
    }
}

/// A policy config inits through its structure config.
impl<M, C> ModuleInit<M> for C
where
    M: Module,
    C: ToStructureConfig,
    C::Structure: ModuleInit<M>,
{
    fn try_init(
        &self,
        device: &Device,
    ) -> BunsenResult<M> {
        self.try_to_structure()?.try_init(device)
    }
}