The Burn Book (#625)

README.md

@@ -120,7 +120,7 @@ use burn::tensor::{Tensor, Int};
 
 fn function<B: Backend>(tensor_float: Tensor<B, 2>) {
     let _tensor_bool = tensor_float.clone().equal_elem(2.0); // Tensor<B, 2, Bool>
-    let _tensor_int = tensor_float.argmax(1) // Tensor<B, 2, Int>
+    let _tensor_int = tensor_float.argmax(1); // Tensor<B, 2, Int>
 }
 ```
 

burn-book/.gitignore

@@ -0,0 +1,18 @@
+target
+
+# MacOS temp file
+.DS_Store
+
+book-test
+guide/book
+
+.vscode
+tests/burn-book/book/
+book/
+
+# Ignore Jetbrains specific files.
+.idea/
+
+# Ignore Vim temporary and swap files.
+*.sw?
+*~

burn-book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Wouter Doppenberg"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Burn Book"

burn-book/src/SUMMARY.md

@@ -0,0 +1,33 @@
+[Overview](../../README.md)
+
+[Motivation](./motivation.md)
+
+
+- [Usage](./usage/README.md)
+  - [Installation](./usage/installation.md)
+  - [Quick Start](./usage/quick-start.md)
+- [Concepts](./concepts/README.md)
+  - [Tensors](./concepts/tensors.md)
+  - [Modules](./concepts/modules.md)
+  - [Backend](./concepts/backend.md)
+  - [Configs](./concepts/configs.md)
+  - [Learner](./concepts/learner.md)
+  - [Datasets](./concepts/datasets.md)
+  - [Metrics](./concepts/metrics.md)
+  - [Losses](./concepts/losses.md)
+  - [Optimizers](./concepts/optimizers.md)
+  - [`no_std`](./concepts/no-std.md)
+  - [Advanced](./concepts/advanced/README.md)
+    - [Records](./concepts/advanced/records.md)
+    - [Macros](./concepts/advanced/macros.md)
+- [Examples](./examples/README.md)
+  - [MNIST](./examples/mnist.md)
+  - [MNIST Inference on Web](./examples/mnist-inference-on-web.md)
+  - [Named Tensors](./examples/named-tensors.md)
+  - [ONNX Inference](./examples/onnx-inference.md)
+  - [Text Classification](./examples/text-classification.md)
+  - [Text Generation](./examples/text-generation.md)
+
+[Help](./help.md)
+
+[Contributing](./contributing.md)

burn-book/src/concepts/README.md

@@ -0,0 +1 @@
+# Concepts

burn-book/src/concepts/advanced/README.md

@@ -0,0 +1 @@
+# Advanced

burn-book/src/concepts/advanced/macros.md

@@ -0,0 +1 @@
+# Macros

burn-book/src/concepts/advanced/records.md

@@ -0,0 +1 @@
+# Records

burn-book/src/concepts/backend.md

@@ -0,0 +1,9 @@
+# Backend
+
+Nearly everything in `burn` is based on the `Backend` trait, which enables you to run tensor
+operations using different implementations without having to modify your code. While a backend may
+not necessarily have autodiff capabilities, the `ADBackend` trait specifies when autodiff is needed.
+This trait not only abstracts operations but also tensor, device and element types, providing each
+backend the flexibility they need. It's worth noting that the trait assumes eager mode since `burn`
+fully supports dynamic graphs. However, we may create another API to assist with integrating
+graph-based backends, without requiring any changes to the user's code.

burn-book/src/concepts/configs.md

@@ -0,0 +1,29 @@
+# Configs
+
+The `Config` derive lets you define serializable and deserializable configurations or
+hyper-parameters for your [modules](#module) or any components.
+
+```rust
+use burn::config::Config;
+
+#[derive(Config)]
+pub struct PositionWiseFeedForwardConfig {
+    pub d_model: usize,
+    pub d_ff: usize,
+    #[config(default = 0.1)]
+    pub dropout: f64,
+}
+```
+
+The `Derive` macro also adds useful methods to your config, such as a builder pattern.
+
+```rust
+fn main() {
+    let config = PositionWiseFeedForwardConfig::new(512, 2048);
+    println!("{}", config.d_model); // 512
+    println!("{}", config.d_ff); // 2048
+    println!("{}", config.dropout); // 0.1
+    let config =  config.with_dropout(0.2);
+    println!("{}", config.dropout); // 0.2
+}
+```

burn-book/src/concepts/datasets.md

@@ -0,0 +1 @@
+# Datasets

burn-book/src/concepts/learner.md

@@ -0,0 +1,31 @@
+# Learner
+
+The `Learner` is the main `struct` that let you train a neural network with support for `logging`,
+`metric`, `checkpointing` and more. In order to create a learner, you must use the `LearnerBuilder`.
+
+```rust,ignore
+use burn::train::LearnerBuilder;
+use burn::train::metric::{AccuracyMetric, LossMetric};
+use burn::record::DefaultRecordSettings;
+
+fn main() {
+    let dataloader_train = ...;
+    let dataloader_valid = ...;
+
+    let model = ...;
+    let optim = ...;
+
+    let learner = LearnerBuilder::new("/tmp/artifact_dir")
+        .metric_train_plot(AccuracyMetric::new())
+        .metric_valid_plot(AccuracyMetric::new())
+        .metric_train(LossMetric::new())
+        .metric_valid(LossMetric::new())
+        .with_file_checkpointer::<DefaultRecordSettings>(2)
+        .num_epochs(10)
+        .build(model, optim);
+
+    let _model_trained = learner.fit(dataloader_train, dataloader_valid);
+}
+```
+
+See this [example](https://github.com/burn-rs/burn/tree/main/examples/mnist) for a real usage.

burn-book/src/concepts/losses.md

@@ -0,0 +1 @@
+# Losses

burn-book/src/concepts/metrics.md

@@ -0,0 +1 @@
+# Metrics

burn-book/src/concepts/models.md

@@ -0,0 +1 @@
+# Models

burn-book/src/concepts/modules.md

@@ -0,0 +1,32 @@
+# Modules
+
+The `Module` derive allows you to create your own neural network modules, similar to PyTorch. The
+derive function only generates the necessary methods to essentially act as a parameter container for
+your type, it makes no assumptions about how the forward pass is declared.
+
+```rust
+use burn::nn;
+use burn::module::Module;
+use burn::tensor::backend::Backend;
+
+#[derive(Module, Debug)]
+pub struct PositionWiseFeedForward<B: Backend> {
+    linear_inner: Linear<B>,
+    linear_outer: Linear<B>,
+    dropout: Dropout,
+    gelu: GELU,
+}
+
+impl<B: Backend> PositionWiseFeedForward<B> {
+    pub fn forward<const D: usize>(&self, input: Tensor<B, D>) -> Tensor<B, D> {
+        let x = self.linear_inner.forward(input);
+        let x = self.gelu.forward(x);
+        let x = self.dropout.forward(x);
+
+        self.linear_outer.forward(x)
+    }
+}
+```
+
+Note that all fields declared in the struct must also implement the `Module` trait. The `Tensor`
+struct doesn't implement `Module`, but `Param<Tensor<B, D>>` does.

burn-book/src/concepts/no-std.md

@@ -0,0 +1,15 @@
+## Support for `no_std`
+
+Burn, including its `burn-ndarray` backend, can work in a `no_std` environment, provided `alloc` is
+available for the inference mode. To accomplish this, simply turn off the default features in `burn`
+and `burn-ndarray` (which is the minimum requirement for running the inference mode). You can find a
+reference example in
+[burn-no-std-tests](https://github.com/burn-rs/burn/tree/main/burn-no-std-tests).
+
+The `burn-core` and `burn-tensor` crates also support `no_std` with `alloc`. These crates can be
+directly added as dependencies if necessary, as they are reexported by the `burn` crate.
+
+Please be aware that when using the `no_std` mode, a random seed will be generated at build time if
+one hasn't been set using the `Backend::seed` method. Also, the
+[spin::mutex::Mutex](https://docs.rs/spin/latest/spin/mutex/struct.Mutex.html) is used instead of
+[std::sync::Mutex](https://doc.rust-lang.org/std/sync/struct.Mutex.html) in this mode.

burn-book/src/concepts/optimizers.md

@@ -0,0 +1 @@
+# Optimizers

burn-book/src/concepts/tensors.md

@@ -0,0 +1,25 @@
+# Tensors
+
+At the core of burn lies the `Tensor` struct, which encompasses multiple types of tensors, including
+`Float`, `Int`, and `Bool`. The element types of these tensors are specified by the backend and are
+usually designated as a generic argument (e.g., `NdArrayBackend<f32>`). Although the same struct is
+used for all tensors, the available methods differ depending on the tensor kind. You can specify the
+desired tensor kind by setting the third generic argument, which defaults to `Float`. The first
+generic argument specifies the backend, while the second specifies the number of dimensions.
+
+```rust
+use burn::tensor::backend::Backend;
+use burn::tensor::{Tensor, Int};
+
+fn function<B: Backend>(tensor_float: Tensor<B, 2>) {
+    let _tensor_bool = tensor_float.clone().equal_elem(2.0); // Tensor<B, 2, Bool>
+    let _tensor_int = tensor_float.argmax(1); // Tensor<B, 2, Int>
+}
+```
+
+As demonstrated in the previous example, nearly all operations require owned tensors as parameters,
+which means that calling `Clone` explicitly is necessary when reusing the same tensor multiple
+times. However, there's no need to worry since the tensor's data won't be copied, it will be flagged
+as readonly when multiple tensors use the same allocated memory. This enables backends to reuse
+tensor data when possible, similar to a copy-on-write pattern, while remaining completely
+transparent to the user.

burn-book/src/contributing.md

@@ -0,0 +1 @@
+# Contributing

burn-book/src/examples/README.md

@@ -0,0 +1 @@
+# Examples

burn-book/src/examples/mnist-inference-on-web.md

@@ -0,0 +1 @@
+# MNIST Inference on Web

burn-book/src/examples/mnist.md

@@ -0,0 +1 @@
+# MNIST

burn-book/src/examples/named-tensors.md

@@ -0,0 +1 @@
+# Named Tensors

burn-book/src/examples/onnx-inference.md

@@ -0,0 +1 @@
+# ONNX Inference

burn-book/src/examples/text-classification.md

@@ -0,0 +1 @@
+# Text Classification

burn-book/src/examples/text-generation.md

@@ -0,0 +1 @@
+# Text Generation

burn-book/src/help.md

@@ -0,0 +1 @@
+# Help

burn-book/src/motivation.md

@@ -0,0 +1 @@
+# Motivation

burn-book/src/usage/README.md

@@ -0,0 +1 @@
+# Usage

burn-book/src/usage/installation.md

@@ -0,0 +1 @@
+# Installation

burn-book/src/usage/quick-start.md

@@ -0,0 +1 @@
+# Quick Start