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
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
use ;
use crate::;
/// 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<B, 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,
/// },
/// prelude::Backend,
/// };
///
/// #[derive(Config, Debug)]
/// pub struct WideStructureConfig {
/// pub layer: LinearConfig,
/// }
///
/// impl<B: Backend> ModuleInit<B, Wide<B>> for WideStructureConfig {
/// fn try_init(
/// &self,
/// device: &B::Device,
/// ) -> BunsenResult<Wide<B>> {
/// Ok(Wide {
/// layer: self.layer.init(device),
/// })
/// }
/// }
///
/// #[derive(Module, Debug)]
/// pub struct Wide<B: Backend> {
/// layer: Linear<B>,
/// }
///
/// #[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<B: Backend> ModuleInit<B, Wide<B>> for WideContractConfig {
/// fn try_init(
/// &self,
/// device: &B::Device,
/// ) -> BunsenResult<Wide<B>> {
/// self.try_to_structure()?.try_init(device)
/// }
/// }
/// ```
///
/// [`ResNetContractConfig`]: crate::kits::images::resnet::ResNetContractConfig
/// [`ResNetStructureConfig`]: crate::kits::images::resnet::ResNetStructureConfig
/// [`SileroVadSignalConfig`]: crate::kits::speech::silero_vad::blocks::SileroVadSignalConfig
/// [`SileroVadStftConfig`]: crate::kits::speech::silero_vad::blocks::SileroVadStftConfig
/// [`SileroVadStructureConfig`]: crate::kits::speech::silero_vad::blocks::SileroVadStructureConfig
/// [`to_stft`]: crate::kits::speech::silero_vad::blocks::SileroVadSignalConfig::to_stft
/// [`SwinTransformerV2ContractConfig`]: crate::kits::images::swin::v2::SwinTransformerV2ContractConfig
/// A policy config inits through its structure config.