From f8198980975413438b6f965441dc549a0ae88800 Mon Sep 17 00:00:00 2001 From: Wouter Doppenberg Date: Thu, 10 Aug 2023 20:17:23 +0200 Subject: [PATCH] The Burn Book (#625) --- README.md | 2 +- burn-book/.gitignore | 18 ++++++++++ burn-book/book.toml | 6 ++++ burn-book/src/SUMMARY.md | 33 +++++++++++++++++++ burn-book/src/concepts/README.md | 1 + burn-book/src/concepts/advanced/README.md | 1 + burn-book/src/concepts/advanced/macros.md | 1 + burn-book/src/concepts/advanced/records.md | 1 + burn-book/src/concepts/backend.md | 9 +++++ burn-book/src/concepts/configs.md | 29 ++++++++++++++++ burn-book/src/concepts/datasets.md | 1 + burn-book/src/concepts/learner.md | 31 +++++++++++++++++ burn-book/src/concepts/losses.md | 1 + burn-book/src/concepts/metrics.md | 1 + burn-book/src/concepts/models.md | 1 + burn-book/src/concepts/modules.md | 32 ++++++++++++++++++ burn-book/src/concepts/no-std.md | 15 +++++++++ burn-book/src/concepts/optimizers.md | 1 + burn-book/src/concepts/tensors.md | 25 ++++++++++++++ burn-book/src/contributing.md | 1 + burn-book/src/examples/README.md | 1 + .../src/examples/mnist-inference-on-web.md | 1 + burn-book/src/examples/mnist.md | 1 + burn-book/src/examples/named-tensors.md | 1 + burn-book/src/examples/onnx-inference.md | 1 + burn-book/src/examples/text-classification.md | 1 + burn-book/src/examples/text-generation.md | 1 + burn-book/src/help.md | 1 + burn-book/src/motivation.md | 1 + burn-book/src/usage/README.md | 1 + burn-book/src/usage/installation.md | 1 + burn-book/src/usage/quick-start.md | 1 + 32 files changed, 221 insertions(+), 1 deletion(-) create mode 100644 burn-book/.gitignore create mode 100644 burn-book/book.toml create mode 100644 burn-book/src/SUMMARY.md create mode 100644 burn-book/src/concepts/README.md create mode 100644 burn-book/src/concepts/advanced/README.md create mode 100644 burn-book/src/concepts/advanced/macros.md create mode 100644 burn-book/src/concepts/advanced/records.md create mode 100644 burn-book/src/concepts/backend.md create mode 100644 burn-book/src/concepts/configs.md create mode 100644 burn-book/src/concepts/datasets.md create mode 100644 burn-book/src/concepts/learner.md create mode 100644 burn-book/src/concepts/losses.md create mode 100644 burn-book/src/concepts/metrics.md create mode 100644 burn-book/src/concepts/models.md create mode 100644 burn-book/src/concepts/modules.md create mode 100644 burn-book/src/concepts/no-std.md create mode 100644 burn-book/src/concepts/optimizers.md create mode 100644 burn-book/src/concepts/tensors.md create mode 100644 burn-book/src/contributing.md create mode 100644 burn-book/src/examples/README.md create mode 100644 burn-book/src/examples/mnist-inference-on-web.md create mode 100644 burn-book/src/examples/mnist.md create mode 100644 burn-book/src/examples/named-tensors.md create mode 100644 burn-book/src/examples/onnx-inference.md create mode 100644 burn-book/src/examples/text-classification.md create mode 100644 burn-book/src/examples/text-generation.md create mode 100644 burn-book/src/help.md create mode 100644 burn-book/src/motivation.md create mode 100644 burn-book/src/usage/README.md create mode 100644 burn-book/src/usage/installation.md create mode 100644 burn-book/src/usage/quick-start.md diff --git a/README.md b/README.md index 20edfdeac..5074f5749 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,7 @@ use burn::tensor::{Tensor, Int}; fn function(tensor_float: Tensor) { let _tensor_bool = tensor_float.clone().equal_elem(2.0); // Tensor - let _tensor_int = tensor_float.argmax(1) // Tensor + let _tensor_int = tensor_float.argmax(1); // Tensor } ``` diff --git a/burn-book/.gitignore b/burn-book/.gitignore new file mode 100644 index 000000000..409ff3eb0 --- /dev/null +++ b/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? +*~ \ No newline at end of file diff --git a/burn-book/book.toml b/burn-book/book.toml new file mode 100644 index 000000000..5405da02e --- /dev/null +++ b/burn-book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Wouter Doppenberg"] +language = "en" +multilingual = false +src = "src" +title = "The Burn Book" diff --git a/burn-book/src/SUMMARY.md b/burn-book/src/SUMMARY.md new file mode 100644 index 000000000..c8d39aedf --- /dev/null +++ b/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) \ No newline at end of file diff --git a/burn-book/src/concepts/README.md b/burn-book/src/concepts/README.md new file mode 100644 index 000000000..74d42e13c --- /dev/null +++ b/burn-book/src/concepts/README.md @@ -0,0 +1 @@ +# Concepts diff --git a/burn-book/src/concepts/advanced/README.md b/burn-book/src/concepts/advanced/README.md new file mode 100644 index 000000000..931fae06c --- /dev/null +++ b/burn-book/src/concepts/advanced/README.md @@ -0,0 +1 @@ +# Advanced diff --git a/burn-book/src/concepts/advanced/macros.md b/burn-book/src/concepts/advanced/macros.md new file mode 100644 index 000000000..19921943e --- /dev/null +++ b/burn-book/src/concepts/advanced/macros.md @@ -0,0 +1 @@ +# Macros diff --git a/burn-book/src/concepts/advanced/records.md b/burn-book/src/concepts/advanced/records.md new file mode 100644 index 000000000..0b25ddc4b --- /dev/null +++ b/burn-book/src/concepts/advanced/records.md @@ -0,0 +1 @@ +# Records diff --git a/burn-book/src/concepts/backend.md b/burn-book/src/concepts/backend.md new file mode 100644 index 000000000..8f58a64c0 --- /dev/null +++ b/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. diff --git a/burn-book/src/concepts/configs.md b/burn-book/src/concepts/configs.md new file mode 100644 index 000000000..7b69c4b79 --- /dev/null +++ b/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 +} +``` diff --git a/burn-book/src/concepts/datasets.md b/burn-book/src/concepts/datasets.md new file mode 100644 index 000000000..157ea3aad --- /dev/null +++ b/burn-book/src/concepts/datasets.md @@ -0,0 +1 @@ +# Datasets diff --git a/burn-book/src/concepts/learner.md b/burn-book/src/concepts/learner.md new file mode 100644 index 000000000..248b5c87b --- /dev/null +++ b/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::(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. \ No newline at end of file diff --git a/burn-book/src/concepts/losses.md b/burn-book/src/concepts/losses.md new file mode 100644 index 000000000..d4ec96448 --- /dev/null +++ b/burn-book/src/concepts/losses.md @@ -0,0 +1 @@ +# Losses diff --git a/burn-book/src/concepts/metrics.md b/burn-book/src/concepts/metrics.md new file mode 100644 index 000000000..b05321b8f --- /dev/null +++ b/burn-book/src/concepts/metrics.md @@ -0,0 +1 @@ +# Metrics diff --git a/burn-book/src/concepts/models.md b/burn-book/src/concepts/models.md new file mode 100644 index 000000000..91361720e --- /dev/null +++ b/burn-book/src/concepts/models.md @@ -0,0 +1 @@ +# Models diff --git a/burn-book/src/concepts/modules.md b/burn-book/src/concepts/modules.md new file mode 100644 index 000000000..bae19c948 --- /dev/null +++ b/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 { + linear_inner: Linear, + linear_outer: Linear, + dropout: Dropout, + gelu: GELU, +} + +impl PositionWiseFeedForward { + pub fn forward(&self, input: Tensor) -> Tensor { + 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>` does. \ No newline at end of file diff --git a/burn-book/src/concepts/no-std.md b/burn-book/src/concepts/no-std.md new file mode 100644 index 000000000..b07d1e3a7 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/burn-book/src/concepts/optimizers.md b/burn-book/src/concepts/optimizers.md new file mode 100644 index 000000000..68bfaee73 --- /dev/null +++ b/burn-book/src/concepts/optimizers.md @@ -0,0 +1 @@ +# Optimizers diff --git a/burn-book/src/concepts/tensors.md b/burn-book/src/concepts/tensors.md new file mode 100644 index 000000000..588d28d96 --- /dev/null +++ b/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`). 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(tensor_float: Tensor) { + let _tensor_bool = tensor_float.clone().equal_elem(2.0); // Tensor + let _tensor_int = tensor_float.argmax(1); // Tensor +} +``` + +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. diff --git a/burn-book/src/contributing.md b/burn-book/src/contributing.md new file mode 100644 index 000000000..854139a31 --- /dev/null +++ b/burn-book/src/contributing.md @@ -0,0 +1 @@ +# Contributing diff --git a/burn-book/src/examples/README.md b/burn-book/src/examples/README.md new file mode 100644 index 000000000..df635b4e6 --- /dev/null +++ b/burn-book/src/examples/README.md @@ -0,0 +1 @@ +# Examples diff --git a/burn-book/src/examples/mnist-inference-on-web.md b/burn-book/src/examples/mnist-inference-on-web.md new file mode 100644 index 000000000..781ea9ac7 --- /dev/null +++ b/burn-book/src/examples/mnist-inference-on-web.md @@ -0,0 +1 @@ +# MNIST Inference on Web diff --git a/burn-book/src/examples/mnist.md b/burn-book/src/examples/mnist.md new file mode 100644 index 000000000..642960a48 --- /dev/null +++ b/burn-book/src/examples/mnist.md @@ -0,0 +1 @@ +# MNIST diff --git a/burn-book/src/examples/named-tensors.md b/burn-book/src/examples/named-tensors.md new file mode 100644 index 000000000..526003c8a --- /dev/null +++ b/burn-book/src/examples/named-tensors.md @@ -0,0 +1 @@ +# Named Tensors diff --git a/burn-book/src/examples/onnx-inference.md b/burn-book/src/examples/onnx-inference.md new file mode 100644 index 000000000..071355567 --- /dev/null +++ b/burn-book/src/examples/onnx-inference.md @@ -0,0 +1 @@ +# ONNX Inference diff --git a/burn-book/src/examples/text-classification.md b/burn-book/src/examples/text-classification.md new file mode 100644 index 000000000..a4683851e --- /dev/null +++ b/burn-book/src/examples/text-classification.md @@ -0,0 +1 @@ +# Text Classification diff --git a/burn-book/src/examples/text-generation.md b/burn-book/src/examples/text-generation.md new file mode 100644 index 000000000..95fa8b490 --- /dev/null +++ b/burn-book/src/examples/text-generation.md @@ -0,0 +1 @@ +# Text Generation diff --git a/burn-book/src/help.md b/burn-book/src/help.md new file mode 100644 index 000000000..61d37c07a --- /dev/null +++ b/burn-book/src/help.md @@ -0,0 +1 @@ +# Help diff --git a/burn-book/src/motivation.md b/burn-book/src/motivation.md new file mode 100644 index 000000000..6d769339f --- /dev/null +++ b/burn-book/src/motivation.md @@ -0,0 +1 @@ +# Motivation diff --git a/burn-book/src/usage/README.md b/burn-book/src/usage/README.md new file mode 100644 index 000000000..8f04b05ad --- /dev/null +++ b/burn-book/src/usage/README.md @@ -0,0 +1 @@ +# Usage diff --git a/burn-book/src/usage/installation.md b/burn-book/src/usage/installation.md new file mode 100644 index 000000000..25267fe2b --- /dev/null +++ b/burn-book/src/usage/installation.md @@ -0,0 +1 @@ +# Installation diff --git a/burn-book/src/usage/quick-start.md b/burn-book/src/usage/quick-start.md new file mode 100644 index 000000000..05cf8c1fd --- /dev/null +++ b/burn-book/src/usage/quick-start.md @@ -0,0 +1 @@ +# Quick Start