-
🦀 Packages, Crates and Modules
- -You might be wondering why we use the `guide` prefix to bring the different modules we just -implemented into scope. Instead of including the code in the current guide in a single file, we -separated it into different files which group related code into _modules_. The `guide` is simply the -name we gave to our _crate_, which contains the different files. Below is a brief explanation of the -different parts of the Rust module system. - -A **package** is a bundle of one or more crates that provides a set of functionality. A package -contains a `Cargo.toml` file that describes how to build those crates. Burn is a package. - -A **crate** is a compilation unit in Rust. It could be a single file, but it is often easier to -split up crates into multiple _modules_ and possibly multiple files. A crate can come in one of two -forms: a binary crate or a library crate. When compiling a crate, the compiler first looks in the -crate root file (usually `src/lib.rs` for a library crate or `src/main.rs` for a binary crate). Any -module declared in the crate root file will be inserted in the crate for compilation. For this demo -example, we will define a library crate where all the individual modules (model, data, training, -etc.) are listed inside `src/lib.rs` as follows: - -``` -pub mod data; -pub mod inference; -pub mod model; -pub mod training; -``` - -A **module** lets us organize code within a crate for readability and easy reuse. Modules also allow -us to control the _privacy_ of items. The `pub` keyword used above, for example, is employed to make -a module publicly available inside the crate. - -The entry point of our program is the `main` function, defined in the `examples/guide.rs` file. The -file structure for this example is illustrated below: - -``` -guide -├── Cargo.toml -├── examples -│ └── guide.rs -└── src - ├── data.rs - ├── inference.rs - ├── lib.rs - ├── model.rs - └── training.rs -``` - -The source for this guide can be found in our -[GitHub repository](https://github.com/tracel-ai/burn/tree/main/examples/guide) which can be used to -run this basic workflow example end-to-end.\ - -- In this example, we use the `Wgpu` backend which is compatible with any operating system and will use the GPU. For other options, see the Burn README. This backend type takes the graphics api, the float type and the int type as generic arguments that will be used during the training. By leaving @@ -87,6 +34,12 @@ the model (the number of digit classes is 10 and the hidden dimension is 512), t configuration which in our case will be the default Adam configuration, and the device which can be obtained from the backend. -When running the example, we can see the training progression through a basic CLI dashboard: +You can now train your freshly created model with the command: + +```console +cargo run --release +``` + +When running the example, you should see the training progression through a basic CLI dashboard:
diff --git a/burn-book/src/basic-workflow/inference.md b/burn-book/src/basic-workflow/inference.md
index 8f422d7f45..4c170414ff 100644
--- a/burn-book/src/basic-workflow/inference.md
+++ b/burn-book/src/basic-workflow/inference.md
@@ -35,3 +35,18 @@ Finally we can init the model with the configuration and the record. For simplic
same batcher used during the training to pass from a MnistItem to a tensor.
By running the infer function, you should see the predictions of your model!
+
+Add the call to `infer` to the `main.rs` file after the `train` function call:
+
+```rust , ignore
+ crate::inference::infer::+Note that each time you create a new file in the `src` directory you also need to add explicitly this +module to the `main.rs` file. For instance after creating the `model.rs`, you need to add the following +at the top of the main file: + +```rust , ignore +mod model; +``` + Next, we need to instantiate the model for training. ```rust , ignore diff --git a/burn-book/src/getting-started.md b/burn-book/src/getting-started.md index 6db75852fe..eb8d6005db 100644 --- a/burn-book/src/getting-started.md +++ b/burn-book/src/getting-started.md @@ -199,14 +199,86 @@ For the sake of simplicity, the subsequent chapters of this book will all use th -## Running examples +## Explore examples + +In the [next chapter](./basic-workflow) you'll have the opportunity to implement the whole Burn +`guide` example yourself in a step by step manner. Many additional Burn examples are available in the -[examples](https://github.com/tracel-ai/burn/tree/main/examples) directory. To run an example, please refer -to its README.md for the specific command to execute. +[examples](https://github.com/tracel-ai/burn/tree/main/examples) directory. Burn examples are +organized as library crates with one or more examples that are executable binaries. An example +can then be executed using the following cargo command line in the root of the Burn repository: + +```bash +cargo run --example
+`.
+
+Below is an file tree of a typical Burn example package:
+
+```
+examples/burn-example
+├── Cargo.toml
+├── examples
+│ ├── example1.rs
+│ ├── example2.rs
+│ └── ...
+└── src
+ ├── lib.rs
+ ├── module1.rs
+ ├── module2.rs
+ └── ...
+```
+
+
🦀 About Rust crates
+ +Each Burn example is a **package** which are subdirectories of the `examples` directory. A package +is composed of one or more **crates**. + +A package is a bundle of one or more crates that provides a set of functionality. A package +contains a `Cargo.toml` file that describes how to build those crates. + +A crate is a compilation unit in Rust. It could be a single file, but it is often easier to +split up crates into multiple **modules**. + +A module lets us organize code within a crate for readability and easy reuse. Modules also allow +us to control the _privacy_ of items. For instance the `pub(crate)` keyword is employed to make +a module publicly available inside the crate. In the snippet below there are four modules declared, +two of them are public and visible to the users of the crates, one of them is public inside the crate +only and crate users cannot see it, at last one is private when there is no keyword. +These modules can be single files or a directory with a `mod.rs` file inside. + +```rust, ignore +pub mod data; +pub mod inference; +pub(crate) mod model; +mod training; +``` + +A crate can come in one of two forms: a **binary crate** or a **library crate**. When compiling a crate, +the compiler first looks in the crate root file (`src/lib.rs` for a library crate and `src/main.rs` +for a binary crate). Any module declared in the crate root file will be inserted in the crate for +compilation. + +All Burn examples are library crates and they can contain one or more executable examples that +uses the library. We even have some Burn examples that uses the library crate of other examples. + +The examples are unique files under the `examples` directory. Each file produces an executable file +with the same name. Each example can then be executed with `cargo run --example+ +For more information on each example, see their respective `README.md` file. + +
Note that some examples use the
[`datasets` library by HuggingFace](https://huggingface.co/docs/datasets/index) to download the
datasets required in the examples. This is a Python library, which means that you will need to
install Python before running these examples. This requirement will be clearly indicated in the
example's README when applicable.
+
+
+
diff --git a/examples/guide/examples/guide.rs b/examples/guide/examples/guide.rs
index f00610e1af..0ddc70e460 100644
--- a/examples/guide/examples/guide.rs
+++ b/examples/guide/examples/guide.rs
@@ -1,26 +1,16 @@
-use burn::{
- backend::{wgpu::AutoGraphicsApi, Autodiff, Wgpu},
- data::dataset::Dataset,
- optim::AdamConfig,
-};
-use guide::{model::ModelConfig, training::TrainingConfig};
+//
+// Note: If you are following the Burn Book guide this file can be ignored.
+//
+// This example file is added only for convenience and consistency so that
+// the guide example can be executed like any other examples using:
+//
+// cargo run --release --example guide
+//
+use std::process::Command;
fn main() {
- type MyBackend = Wgpu