\n
![](\"https://raw.githubusercontent.com/tracel-ai/burn/main/assets/logo-burn-neutral.webp\")
\n\n[](https://discord.gg/uPEBbYYDB6)\n[](https://crates.io/crates/burn)\n[](https://crates.io/crates/burn)\n[](https://burn.dev/docs/burn)\n[](https://github.com/tracel-ai/burn/actions/workflows/test.yml)\n[](#license)\n[](https://deepwiki.com/tracel-ai/burn)\n\n[
![](\"https://www.runblaze.dev/ci-blaze-powered.png\")
](https://www.runblaze.dev)\n\n---\n\n**Burn is a next generation Tensor Library and Deep Learning Framework that doesn't compromise on\n
flexibility, efficiency and portability.**\n\n
\n
\n\nBurn is both a tensor library and a deep learning framework optimized for numerical computing, model\ninference and model training. Burn leverages Rust to perform optimizations normally only available\nin static-graph frameworks, offering optimal speed without impacting flexibility.\n\n## Backend\n\n
\n
![](\"https://raw.githubusercontent.com/tracel-ai/burn/main/assets/backend-chip.png\")
\n\nBurn strives to be as fast as possible on as many hardwares as possible, with robust\nimplementations. We believe this flexibility is crucial for modern needs where you may train your\nmodels in the cloud, then deploy on customer hardwares, which vary from user to user.\n\n
\n\n### Supported Backends\n\nMost backends support all operating systems, so we don't mention them in the tables below.\n\n**GPU Backends:**\n\n| | CUDA | ROCm | Metal | Vulkan | WebGPU | LibTorch |\n| ------- | ---- | ---- | ----- | ------ | ------ | -------- |\n| Nvidia | ☑️ | - | - | ☑️ | ☑️ | ☑️ |\n| AMD | - | ☑️ | - | ☑️ | ☑️ | ☑️ |\n| Apple | - | - | ☑️ | - | ☑️ | ☑️ |\n| Intel | - | - | - | ☑️ | ☑️ | - |\n| Qualcom | - | - | - | ☑️ | ☑️ | - |\n| Wasm | - | - | - | - | ☑️ | - |\n\n**CPU Backends:**\n\n| | Cpu (CubeCL) | NdArray | LibTorch |\n| ------ | ------------ | ------- | -------- |\n| X86 | ☑️ | ☑️ | ☑️ |\n| Arm | ☑️ | ☑️ | ☑️ |\n| Wasm | - | ☑️ | - |\n| no-std | - | ☑️ | - |\n\n
\n\nCompared to other frameworks, Burn has a very different approach to supporting many backends. By\ndesign, most code is generic over the Backend trait, which allows us to build Burn with swappable\nbackends. This makes composing backend possible, augmenting them with additional functionalities\nsuch as autodifferentiation and automatic kernel fusion.\n\n
\n\nAutodiff: Backend decorator that brings backpropagation to any backend 🔄\n
\n
\n\nContrary to the aforementioned backends, Autodiff is actually a backend _decorator_. This means that\nit cannot exist by itself; it must encapsulate another backend.\n\nThe simple act of wrapping a base backend with Autodiff transparently equips it with\nautodifferentiation support, making it possible to call backward on your model.\n\n```rust\nuse burn::backend::{Autodiff, Wgpu};\nuse burn::tensor::{Distribution, Tensor};\n\nfn main() {\n type Backend = Autodiff;\n\n let device = Default::default();\n\n let x: Tensor = Tensor::random([32, 32], Distribution::Default, &device);\n let y: Tensor = Tensor::random([32, 32], Distribution::Default, &device).require_grad();\n\n let tmp = x.clone() + y.clone();\n let tmp = tmp.matmul(x);\n let tmp = tmp.exp();\n\n let grads = tmp.backward();\n let y_grad = y.grad(&grads).unwrap();\n println!(\"{y_grad}\");\n}\n```\n\nOf note, it is impossible to make the mistake of calling backward on a model that runs on a backend\nthat does not support autodiff (for inference), as this method is only offered by an Autodiff\nbackend.\n\nSee the [Autodiff Backend README](./crates/burn-autodiff/README.md) for more details.\n\n \n\n
\n\nFusion: Backend decorator that brings kernel fusion to all first-party backends\n
\n
\n\nThis backend decorator enhances a backend with kernel fusion, provided that the inner backend\nsupports it. Note that you can compose this backend with other backend decorators such as Autodiff.\nAll first-party accelerated backends (like WGPU and CUDA) use Fusion by default (`burn/fusion`\nfeature flag), so you typically don't need to apply it manually.\n\n```rust\n#[cfg(not(feature = \"fusion\"))]\npub type Cuda = CubeBackend;\n\n#[cfg(feature = \"fusion\")]\npub type Cuda = burn_fusion::Fusion>;\n```\n\nOf note, we plan to implement automatic gradient checkpointing based on compute bound and memory\nbound operations, which will work gracefully with the fusion backend to make your code run even\nfaster during training, see [this issue](https://github.com/tracel-ai/burn/issues/936).\n\nSee the [Fusion Backend README](./crates/burn-fusion/README.md) for more details.\n\n \n\n
\n\nRouter (Beta): Backend decorator that composes multiple backends into a single one\n
\n
\n\nThat backend simplifies hardware operability, if for instance you want to execute some operations on\nthe CPU and other operations on the GPU.\n\n```rust\nuse burn::tensor::{Distribution, Tensor};\nuse burn::backend::{\n NdArray, Router, Wgpu, ndarray::NdArrayDevice, router::duo::MultiDevice, wgpu::WgpuDevice,\n};\n\nfn main() {\n type Backend = Router<(Wgpu, NdArray)>;\n\n let device_0 = MultiDevice::B1(WgpuDevice::DiscreteGpu(0));\n let device_1 = MultiDevice::B2(NdArrayDevice::Cpu);\n\n let tensor_gpu =\n Tensor::::random([3, 3], burn::tensor::Distribution::Default, &device_0);\n let tensor_cpu =\n Tensor::::random([3, 3], burn::tensor::Distribution::Default, &device_1);\n}\n\n```\n\n \n\n
\n\nRemote (Beta): Backend decorator for remote backend execution, useful for distributed computations\n
\n
\n\nThat backend has two parts, one client and one server. The client sends tensor operations over the\nnetwork to a remote compute backend. You can use any first-party backend as server in a single line\nof code:\n\n```rust\nfn main_server() {\n // Start a server on port 3000.\n burn::server::start::(Default::default(), 3000);\n}\n\nfn main_client() {\n // Create a client that communicate with the server on port 3000.\n use burn::backend::{Autodiff, RemoteBackend};\n\n type Backend = Autodiff;\n\n let device = RemoteDevice::new(\"ws://localhost:3000\");\n let tensor_gpu =\n Tensor::::random([3, 3], Distribution::Default, &device);\n}\n\n```\n\n \n\n
\n\n## Training & Inference\n\n
\n
![](\"https://raw.githubusercontent.com/tracel-ai/burn/main/assets/ember-wall.png\")
\n\nThe whole deep learning workflow is made easy with Burn, as you can monitor your training progress\nwith an ergonomic dashboard, and run inference everywhere from embedded devices to large GPU\nclusters.\n\nBurn was built from the ground up with training and inference in mind. It's also worth noting how\nBurn, in comparison to frameworks like PyTorch, simplifies the transition from training to\ndeployment, eliminating the need for code changes.\n\n
\n\n
\n\n
\n\n**Click on the following sections to expand 👇**\n\n
\n\nTraining Dashboard 📈\n
\n
\n\nAs you can see in the previous video (click on the picture!), a new terminal UI dashboard based on\nthe [Ratatui](https://github.com/ratatui-org/ratatui) crate allows users to follow their training\nwith ease without having to connect to any external application.\n\nYou can visualize your training and validation metrics updating in real-time and analyze the\nlifelong progression or recent history of any registered metrics using only the arrow keys. Break\nfrom the training loop without crashing, allowing potential checkpoints to be fully written or\nimportant pieces of code to complete without interruption 🛡\n\n \n\n
\n\nONNX Support 🐫\n
\n
\n\nBurn supports importing ONNX (Open Neural Network Exchange) models through the\n[burn-onnx](https://github.com/tracel-ai/burn-onnx) crate, allowing you to easily port models from\nTensorFlow or PyTorch to Burn. The ONNX model is converted into Rust code that uses Burn's native\nAPIs, enabling the imported model to run on any Burn backend (CPU, GPU, WebAssembly) and benefit\nfrom all of Burn's optimizations like automatic kernel fusion.\n\nOur ONNX support is further described in\n[this section of the Burn Book 🔥](https://burn.dev/books/burn/onnx-import.html).\n\n> **Note**: This crate is in active development and currently supports a\n> [limited set of ONNX operators](https://github.com/tracel-ai/burn-onnx/blob/main/SUPPORTED-ONNX-OPS.md).\n\n \n\n
\n\nImporting PyTorch or Safetensors Models 🚚\n
\n
\n\nYou can load weights from PyTorch or Safetensors formats directly into your Burn-defined models.\nThis makes it easy to reuse existing models while benefiting from Burn's performance and deployment\nfeatures.\n\nLearn more in the [Saving & Loading Models](https://burn.dev/books/burn/saving-and-loading.html)\nsection of the Burn Book.\n\n \n\n
\n\nInference in the Browser 🌐\n
\n
\n\nSeveral of our backends can run in WebAssembly environments: NdArray for CPU execution, and WGPU for\nGPU acceleration via WebGPU. This means that you can run inference directly within a browser. We\nprovide several examples of this:\n\n- [MNIST](./examples/mnist-inference-web) where you can draw digits and a small convnet tries to\n find which one it is! 2️⃣ 7️⃣ 😰\n- [Image Classification](https://github.com/tracel-ai/burn-onnx/tree/main/examples/image-classification-web)\n where you can upload images and classify them! 🌄\n\n \n\n
\n\nEmbedded: no_std support ⚙️\n
\n
\n\nBurn's core components support [no_std](https://docs.rust-embedded.org/book/intro/no-std.html). This\nmeans it can run in bare metal environment such as embedded devices without an operating system.\n\n> As of now, only the NdArray backend can be used in a _no_std_ environment.\n\n \n\n
\n\n### Benchmarks\n\nTo evaluate performance across different backends and track improvements over time, we provide a\ndedicated benchmarking suite.\n\nRun and compare benchmarks using [burn-bench](https://github.com/tracel-ai/burn-bench).\n\n> ⚠️ **Warning** When using one of the `wgpu` backends, you may encounter compilation errors related\n> to recursive type evaluation. This is due to complex type nesting within the `wgpu` dependency\n> chain. To resolve this issue, add the following line at the top of your `main.rs` or `lib.rs`\n> file:\n>\n> ```rust\n> #![recursion_limit = \"256\"]\n> ```\n>\n> The default recursion limit (128) is often just below the required depth (typically 130-150) due\n> to deeply nested associated types and trait bounds.\n\n## Getting Started\n\n
\n
![](\"https://raw.githubusercontent.com/tracel-ai/burn/main/assets/ember-walking.png\")
\n\nJust heard of Burn? You are at the right place! Just continue reading this section and we hope you\ncan get on board really quickly.\n\n
\n\n
\n\nThe Burn Book 🔥\n
\n
\n\nTo begin working effectively with Burn, it is crucial to understand its key components and\nphilosophy. This is why we highly recommend new users to read the first sections of\n[The Burn Book 🔥](https://burn.dev/books/burn/). It provides detailed examples and explanations\ncovering every facet of the framework, including building blocks like tensors, modules, and\noptimizers, all the way to advanced usage, like coding your own GPU kernels.\n\n> The project is constantly evolving, and we try as much as possible to keep the book up to date\n> with new additions. However, we might miss some details sometimes, so if you see something weird,\n> let us know! We also gladly accept Pull Requests 😄\n\n \n\n
\n\nExamples 🙏\n
\n
\n\nLet's start with a code snippet that shows how intuitive the framework is to use! In the following,\nwe declare a neural network module with some parameters along with its forward pass.\n\n```rust\nuse burn::nn;\nuse burn::module::Module;\nuse burn::tensor::backend::Backend;\n\n#[derive(Module, Debug)]\npub struct PositionWiseFeedForward {\n linear_inner: nn::Linear,\n linear_outer: nn::Linear,\n dropout: nn::Dropout,\n gelu: nn::Gelu,\n}\n\nimpl PositionWiseFeedForward {\n pub fn forward(&self, input: Tensor) -> Tensor {\n let x = self.linear_inner.forward(input);\n let x = self.gelu.forward(x);\n let x = self.dropout.forward(x);\n\n self.linear_outer.forward(x)\n }\n}\n```\n\nWe have a somewhat large amount of [examples](./examples) in the repository that shows how to use\nthe framework in different scenarios.\n\nFollowing [the book](https://burn.dev/books/burn/):\n\n- [Basic Workflow](./examples/guide) : Creates a custom CNN `Module` to train on the MNIST dataset\n and use for inference.\n- [Custom Training Loop](./examples/custom-training-loop) : Implements a basic training loop instead\n of using the `Learner`.\n- [Custom WGPU Kernel](./examples/custom-wgpu-kernel) : Learn how to create your own custom\n operation with the WGPU backend.\n\nAdditional examples:\n\n- [Custom CSV Dataset](./examples/custom-csv-dataset) : Implements a dataset to parse CSV data for a\n regression task.\n- [Regression](./examples/simple-regression) : Trains a simple MLP on the California Housing dataset\n to predict the median house value for a district.\n- [Custom Image Dataset](./examples/custom-image-dataset) : Trains a simple CNN on custom image\n dataset following a simple folder structure.\n- [Custom Renderer](./examples/custom-renderer) : Implements a custom renderer to display the\n [`Learner`](./building-blocks/learner.md) progress.\n- [Image Classification Web](./examples/image-classification-web) : Image classification web browser\n demo using Burn, WGPU and WebAssembly.\n- [MNIST Inference on Web](./examples/mnist-inference-web) : An interactive MNIST inference demo in\n the browser. The demo is available [online](https://burn.dev/demo/).\n- [MNIST Training](./examples/mnist) : Demonstrates how to train a custom `Module` (MLP) with the\n `Learner` configured to log metrics and keep training checkpoints.\n- [PyTorch Import Inference](./examples/import-model-weights) : Imports a PyTorch model pre-trained\n on MNIST to perform inference on a sample image with Burn.\n- [Text Classification](./examples/text-classification) : Trains a text classification transformer\n model on the AG News or DbPedia dataset. The trained model can then be used to classify a text\n sample.\n- [Text Generation](./examples/text-generation) : Trains a text generation transformer model on the\n DbPedia dataset.\n- [Wasserstein GAN MNIST](./examples/wgan) : Trains a WGAN model to generate new handwritten digits\n based on MNIST.\n\nFor more practical insights, you can clone the repository and run any of them directly on your\ncomputer!\n\n \n\n
\n\nPre-trained Models 🤖\n
\n
\n\nWe keep an updated and curated list of models and examples built with Burn, see the\n[tracel-ai/models repository](https://github.com/tracel-ai/models) for more details.\n\nDon't see the model you want? Don't hesitate to open an issue, and we may prioritize it. Built a\nmodel using Burn and want to share it? You can also open a Pull Request and add your model under the\ncommunity section!\n\n \n\n
\n\nWhy use Rust for Deep Learning? 🦀\n
\n
\n\nDeep Learning is a special form of software where you need very high level abstractions as well as\nextremely fast execution time. Rust is the perfect candidate for that use case since it provides\nzero-cost abstractions to easily create neural network modules, and fine-grained control over memory\nto optimize every detail.\n\nIt's important that a framework be easy to use at a high level so that its users can focus on\ninnovating in the AI field. However, since running models relies so heavily on computations,\nperformance can't be neglected.\n\nTo this day, the mainstream solution to this problem has been to offer APIs in Python, but rely on\nbindings to low-level languages such as C/C++. This reduces portability, increases complexity and\ncreates frictions between researchers and engineers. We feel like Rust's approach to abstractions\nmakes it versatile enough to tackle this two languages dichotomy.\n\nRust also comes with the Cargo package manager, which makes it incredibly easy to build, test, and\ndeploy from any environment, which is usually a pain in Python.\n\nAlthough Rust has the reputation of being a difficult language at first, we strongly believe it\nleads to more reliable, bug-free solutions built faster (after some practice 😅)!\n\n \n\n
\n\n> **Deprecation Note**
Since `0.14.0`, the internal structure for tensor data has changed. The\n> previous `Data` struct was deprecated and officially removed since `0.17.0` in favor of the new\n> `TensorData` struct, which allows for more flexibility by storing the underlying data as bytes and\n> keeping the data type as a field. If you are using `Data` in your code, make sure to switch to\n> `TensorData`.\n\n\n\n
\n\nLoading Model Records From Previous Versions ⚠️\n
\n
\n\nIn the event that you are trying to load a model record saved in a version older than `0.14.0`, make\nsure to use a compatible version (`0.14`, `0.15` or `0.16`) with the `record-backward-compat`\nfeature flag.\n\n```\nfeatures = [..., \"record-backward-compat\"]\n```\n\nOtherwise, the record won't be deserialized correctly and you will get an error message. This error\nwill also point you to the backward compatible feature flag.\n\nThe backward compatibility was maintained for deserialization when loading records. Therefore, as\nsoon as you have saved the record again it will be saved according to the new structure and you can\nupgrade back to the current version\n\nPlease note that binary formats are not backward compatible. Thus, you will need to load your record\nin a previous version and save it in any of the other self-describing record format (e.g., using the\n`NamedMpkFileRecorder`) before using a compatible version (as described) with the\n`record-backward-compat` feature flag.\n\n \n\n## Community\n\n
\n
![](\"https://raw.githubusercontent.com/tracel-ai/burn/main/assets/ember-community.png\")
\n\nIf you are excited about the project, don't hesitate to join our\n[Discord](https://discord.gg/uPEBbYYDB6)! We try to be as welcoming as possible to everybody from\nany background. You can ask your questions and share what you built with the community!\n\n
\n\n
\n\n**Contributing**\n\nBefore contributing, please read the [Contributing Guidelines](./CONTRIBUTING.md) and our\n[Code of Conduct](./CODE-OF-CONDUCT.md). The [Contributor Book](https://burn.dev/contributor-book/)\ncovers architecture, environment setup, and guides for common tasks.\n\n## Status\n\nBurn is currently in active development, and there will be breaking changes. While any resulting\nissues are likely to be easy to fix, there are no guarantees at this stage.\n\n## License\n\nBurn is distributed under the terms of both the MIT license and the Apache License (Version 2.0).\nSee [LICENSE-APACHE](./LICENSE-APACHE) and [LICENSE-MIT](./LICENSE-MIT) for details. Opening a pull\nrequest is assumed to signal agreement with these licensing terms.\n\n
![\"Burn](\"https://raw.githubusercontent.com/tracel-ai/burn/main/assets/burn-train-tui.png\")
\n ![\"Alt](\"./training-output.png\" "\\"a")
\n"
},
{
"path": "burn-book/src/basic-workflow/data.md",
"content": "# Data\n\nTypically, one trains a model on some dataset. Burn provides a library of very useful dataset\nsources and transformations, such as Hugging Face dataset utilities that allow to download and store\ndata into an SQLite database for extremely efficient data streaming and storage. For this guide\nthough, we will use the MNIST dataset from `burn::data::dataset::vision` which requires no external\ndependency.\n\nTo iterate over a dataset efficiently, we will define a struct which will implement the `Batcher`\ntrait. The goal of a batcher is to map individual dataset items into a batched tensor that can be\nused as input to our previously defined model.\n\nLet us start by defining our dataset functionalities in a file `src/data.rs`. We shall omit some of\nthe imports for brevity, but the full code for following this guide can be found at\n`examples/guide/` [directory](https://github.com/tracel-ai/burn/tree/main/examples/guide).\n\n```rust , ignore\nuse burn::{\n data::{dataloader::batcher::Batcher, dataset::vision::MnistItem},\n prelude::*,\n};\n\n\n#[derive(Clone, Default)]\npub struct MnistBatcher {}\n```\n\nThis batcher is pretty straightforward, as it only defines a struct that will implement the\n`Batcher` trait. The trait is generic over the `Backend` trait, which includes an associated type\nfor the device, as not all backends expose the same devices. As an example, the Libtorch-based\nbackend exposes `Cuda(gpu_index)`, `Cpu`, `Vulkan` and `Metal` devices, while the ndarray backend\nonly exposes the `Cpu` device.\n\nNext, we need to actually implement the batching logic.\n\n```rust , ignore\n# use burn::{\n# data::{dataloader::batcher::Batcher, dataset::vision::MnistItem},\n# prelude::*,\n# };\n#\n# #[derive(Clone, Default)]\n# pub struct MnistBatcher {}\n#\n#[derive(Clone, Debug)]\npub struct MnistBatch![\"Burn](\"./dataset.png\" "\\"Burn")
\n\nAlthough we have conveniently implemented the\n[`MnistDataset`](https://github.com/tracel-ai/burn/blob/main/crates/burn-dataset/src/vision/mnist.rs)\nused in the guide, we'll go over its implementation to demonstrate how the `Dataset` and `Batcher`\ntraits are used.\n\nThe [MNIST dataset](http://yann.lecun.com/exdb/mnist/) of handwritten digits has a training set of\n60,000 examples and a test set of 10,000 examples. A single item in the dataset is represented by a\n\\\\(28 \\times 28\\\\) pixels black-and-white image (stored as raw bytes) with its corresponding label\n(a digit between \\\\(0\\\\) and \\\\(9\\\\)). This is defined by the `MnistItemRaw` struct.\n\n```rust, ignore\n# #[derive(Deserialize, Debug, Clone)]\nstruct MnistItemRaw {\n pub image_bytes: Vec