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
//! # `burn`-Adjacent Infrastructure
//!
//! `bunsen::burner` is the infrastructure layer: the pieces that sit
//! *next to* `burn` itself, not on top of its tensor surface. Where
//! [`crate::blocks`] gives you new `Module`s and [`crate::kits`] gives
//! you whole models, `burner` gives you the tooling for working with
//! `burn` modules and optimizers at a level `burn`'s default
//! surface doesn't expose.
//!
//! Most code that uses `bunsen` won't import from `burner` at all. You
//! reach for it when you need to:
//!
//! - **introspect a model** generically — the reflection layer in
//! [`module::reflection`] turns a `Module` into a queryable XML document with
//! an `XPath` query API, for "select every rank-2 weight under the
//! transformer blocks" problems;
//! - **compose optimizers** — [`optim::GroupOptimizerPlan`] builds a
//! `burn` `ModuleOptimizer` that mounts multiple optimizers on a single
//! module (e.g. Muon for matrix parameters, `AdamW` for the rest), each
//! driving a disjoint group of parameters, and a `ModuleLrScheduler` with
//! per-group learning-rate selectors;
//! - **build modules from configs** — [`module::ModuleInit`] is the
//! Config → Module step that bunsen's configs implement, and
//! [`module::ToStructureConfig`] lowers a policy config to its structure
//! config. Both are in [`crate::prelude`];
//! - **exit cleanly** from a program that uses a device —
//! [`device::DeviceSession`] waits for the device's queued work before the
//! process's exit handlers run, which the wgpu backends need on NVIDIA's
//! Vulkan driver;
//! - **carry tensor metadata** in non-generic code paths —
//! [`descriptors::TensorParamDesc`] captures the metadata of any
//! `Param<Tensor<R, K>>` (its `ParamId`, `Shape`, rank, dtype, kind) without
//! carrying the generics that the underlying tensor type does.
//!
//! The reflection and group-optimizer pieces compose: the canonical
//! pattern is to walk a model with `XmlModuleTree`, slice it into
//! parameter groups with `XPath`, and hand the groups to a
//! `GroupOptimizerPlan`.
//!
//! ## Map of the module
//!
//! - [`device`] — [`DeviceSession`](device::DeviceSession), a device that
//! waits for its queued work when it goes away, so a program exits with its
//! device idle.
//! - [`dtypes`] — what a device does with each float dtype (store,
//! compute, accelerate), and what burn does with an op on mixed float dtypes.
//! - [`descriptors`] — serializable, generics-free descriptors of
//! tensors, parameters, and comparison tolerances: the vocabulary that
//! reflection, audit, and [`tensor::dynamic`] use to describe tensors.
//! - [`module`] — module-side helpers: [`ModuleInit`](module::ModuleInit)
//! and [`ToStructureConfig`](module::ToStructureConfig) (the config
//! lifecycle), a block's float dtypes ([`InputDTypes`](module::InputDTypes),
//! [`CoercesInput`](module::CoercesInput),
//! [`ResultDType`](module::ResultDType) and
//! [`DTypeWrapped`](module::DTypeWrapped)), [`HasDType`](module::HasDType)
//! for the values that are not blocks, [`DTypeMapper`](module::DTypeMapper)
//! (cast a module's float parameters to one `DType`), and (under `features =
//! ["reflection"]`) the XML/XPath reflection layer.
//! - [`optim`] — optimizer extensions (under `features = ["train"]`).
//! Headlined by `GroupOptimizerPlan` and the `OptimizerGroup` / `LrSelector`
//! building blocks.
//! - [`tensor`] — tensor helpers that don't fit neatly in [`crate::ops`]:
//! `Tensor` and `TensorData` extension traits, and [`tensor::dynamic`]'s
//! type- and rank-erased [`DynTensor`](tensor::dynamic::DynTensor) with its
//! named-binding [`DynTensorEnv`](tensor::dynamic::DynTensorEnv).
//! - [`distribution`] —
//! [`DistributionDisplayAdapter`](distribution::DistributionDisplayAdapter),
//! which lets a `burn::tensor::Distribution` field appear in a module or
//! config display (used by [`NoiseConfig`](crate::ops::noise::NoiseConfig)).
//!
//! ## Tensor Extensions
//!
//! [`tensor`] provides extension traits that add utility methods directly
//! onto `burn::Tensor` values — in scope after
//! `use bunsen::burner::tensor::*;` or `use bunsen::prelude::*;`:
//!
//! - [`TensorOpExt`](tensor::TensorOpExt) — all tensor kinds: `swap`
//! (exchange two tensors in place), `replace_with` (replace a tensor with a
//! function of itself, which owns it meanwhile), and `copy_slice` (copy one
//! slice of a tensor onto another).
//! - [`TensorOrderedOpExt`](tensor::TensorOrderedOpExt) — ordered (`Int`,
//! `Float`) tensors: [`in_range`](tensor::TensorOrderedOpExt::in_range) and
//! [`in_range_scalar`](tensor::TensorOrderedOpExt::in_range_scalar) for
//! elementwise `[start, end)` range checks producing `Bool` masks.
//! - [`TensorBoolOpExt`](tensor::TensorBoolOpExt) — `Bool` tensors:
//! `count_dim` / `count_dims` to count `true` elements along one or more
//! dimensions (negative indexing supported).