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
//! # Test support
//!
//! What bunsen's own tests are written with, published for the tests of code
//! built on bunsen. This module exists only with the `testing` feature (and
//! in bunsen's own unit tests). The feature also turns on `flex`, the CPU
//! backend behind [`cpu_device`].
//!
//! # Test devices
//!
//! A test takes its device from one of two functions, not from a concrete
//! backend:
//!
//! - [`performance_device`] is for anything that does tensor math. It is the
//! best accelerator that this build of bunsen enables, by feature: `cuda`,
//! then `metal`, then `vulkan`, then `wgpu`. With none of them it is
//! [`cpu_device`]. One suite then runs on whichever backend a developer
//! builds, with no per-backend copies of the tests. `BURN_DEVICE` in the
//! environment overrides the choice, through burn's `Device::default()`.
//! - [`cpu_device`] is `Flex`, the CPU backend, always present under `testing`.
//! It is for trivial plumbing tests: setup and teardown, config round trips,
//! shape bookkeeping. It is not a numerical reference, and a test does not
//! move to it to get trustworthy numbers.
//!
//! A test that trains, or checks a training-only path, calls `.autodiff()` on
//! the device before building its module and inputs.
//!
//! **The CPU fallback is silent.** Without a backend feature on bunsen,
//! `performance_device()` *is* the CPU. A bare `cargo test` builds and passes
//! every test written against it without touching a GPU, so a regression that
//! only an accelerator shows passes too. Run tensor tests with a backend
//! feature: `cargo test -p bunsen --features wgpu`. A dependent forwards it
//! as `bunsen/wgpu`; enabling `burn/wgpu` alone leaves the choice on the CPU.
//!
//! **Tolerances, not bit-exactness.** A test written against
//! `performance_device()` runs on whatever backend the developer has, and
//! backends do not agree bit for bit: kernels reduce in different orders, and
//! the CUDA backend compiles its kernels with fast math (`cubecl`'s CUDA
//! runtime turns `fast_math` on). Compare computed floats within a tolerance,
//! with [`assert_tensors_close`] or [`assert_tensor_close_to_vec`]. Keep exact
//! comparisons for values that are only uploaded, copied or rearranged.
//!
//! To check that two backends agree with each other, or that a result has not
//! drifted from a recorded run, use `bunsen::audit` (the `audit` feature).
//!
//! # Toy fixtures
//!
//! A kit's toy test checks a tiny seeded model against its reference
//! implementation's answers, which `tools/toy_fixture.py` writes into one
//! safetensors file with the weights. [`ToyFixture`] reads the file (the
//! `store` feature), and [`assert_io_close`] compares at the toy
//! tolerance. A decoder is checked through [`DecoderToy`] by
//! [`check_decoder_toy`]: its uncached logits, then a cached decode through
//! every KV cache storage.
//!
//! # Seeded inputs
//!
//! [`seeded_tensor`] draws its values on the host from a seeded RNG, then
//! uploads them, so a seed gives the same values on every backend.
//! `Tensor::random` does not: it uses the backend's own RNG. Use
//! `seeded_tensor` wherever two runs must see the same input: comparisons
//! across backends, stored baselines and golden values.
//!
//! # Device memory
//!
//! A `cargo test` binary runs all its tests in one process, so they share one
//! accelerator memory pool, and `cubecl`'s pools grow without giving pages
//! back on their own. A suite whose tests each load a model can fill the card,
//! and the out-of-memory error then lands in some later test. Bind a
//! [`DeviceMemoryGuard`] at the top of any test that loads a model, and mark
//! the test `#[serial]`. [`release_cached_device_memory`] is the call the
//! guard makes on drop, and its docs explain the page sizing.
//!
//! # Assertions
//!
//! - [`assert_tensors_close`]: two tensors of one shape, within a burn
//! [`Tolerance`](burn::tensor::Tolerance).
//! - [`assert_tensor_close_to_vec`]: a tensor against a row-major host buffer
//! of `f64`, within a `Tolerance`.
//! - [`assert_close_to_vec`]: two host slices, within an absolute tolerance.
//! - [`TensorRecord`]: a reference tensor recorded compactly (shape, sums,
//! strided samples) by a reference implementation,
//! [`assert_matches`](TensorRecord::assert_matches) against it, and
//! [`max_abs_error`](TensorRecord::max_abs_error), the worst sample's
//! distance, which `assert_matches` also returns for a test to report.
//!
//! # Speech
//!
//! Speech scoring is with the speech kits, in
//! [`kits::speech::testing`](crate::kits::speech::testing): word error rates
//! and diarization error rates.
//!
//! # Example
//!
//! A test of real tensor math, as it would sit in a `#[test] #[serial] fn`:
//!
//! ```
//! use bunsen::support::testing::{
//! DeviceMemoryGuard,
//! assert_tensors_close,
//! performance_device,
//! seeded_tensor,
//! };
//! use burn::tensor::{
//! Distribution,
//! Tolerance,
//! };
//!
//! let device = performance_device();
//! let _memory = DeviceMemoryGuard::new(&device);
//!
//! let x = seeded_tensor::<2>(7, [4, 8], Distribution::Default, &device);
//! let y = (x.clone() * 3.0) / 3.0;
//! assert_tensors_close(&y, &x, Tolerance::default());
//! ```
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;