started the burn developer book

contributor-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?
+*~

contributor-book/.prettierrc.json

@@ -0,0 +1,4 @@
+{
+ "printWidth": 100,
+ "proseWrap": "always"
+}

contributor-book/LICENSE-APACHE

@@ -0,0 +1 @@
+../LICENSE-APACHE

contributor-book/LICENSE-MIT

@@ -0,0 +1 @@
+../LICENSE-MIT

contributor-book/book.toml

@@ -0,0 +1,16 @@
+[book]
+authors = [
+ "Wouter Doppenberg",
+ "Nathaniel Simard",
+ "Louis Fortier-Dubois",
+ "Dilshod Tadjibaev",
+ "Guillaume Lagrange",
+ "Joshua Ferguson",
+]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Burn Developer Book 🔥"
+
+[output.html]
+mathjax-support = true

contributor-book/src/SUMMARY.md

@@ -0,0 +1,14 @@
+- [Overview](./overview.md)
+- [How to Read This Book](./how-to-read-this-book.md)
+- [Getting Started](./getting-started/ReadMe.md)
+ - [setting up the environment](./getting-started/setting-up-the-environment.md)
+ - [configuring your editor(optional)](./getting-started/configuring-your-editor.md)
+ - [testing](./getting-started/testing.md)
+- [Architecture Overview](./project-architecture/ReadMe.md)
+ - [Modules](./project-architecture/module.md)
+ - [Serialization](./project-architecture/serialization.md)
+ - [Tensor](./project-architecture/tensor.md)
+ - [Backend](./project-architecture/backend.md)
+- [Guides for Contributors](./guides/ReadMe.md)
+ - [adding a new operation to burn](./guides/adding-a-new-operation-to-burn.md)
+- [Issue related to adding operators](./frequently-encountered-issues/issues-while-adding-ops.md)

contributor-book/src/frequently-encountered-issues/Readme.md

@@ -0,0 +1,3 @@
+# Frequently Encountered Issues
+
+This is a collection of issues people have encountered and asked about on the discord, and is separate from the guides since it often involves a wall of text that is only relevant to a small subset of contributors.

contributor-book/src/frequently-encountered-issues/issues-while-adding-ops.md

@@ -0,0 +1,28 @@
+# Issues encountered while adding ops
+
+Most issues were fairly straight forward, and I was able to play whack-a-bug until I hit ones were I needed outside help (on the discord channels), so I'll share some of the ones that had me stumped enough to ask for help in case you too encounter them.
+
+## Off by .000001 errors
+
+```sh
+---- fusion::base::tests::maxmin::tests::test_mean_dim_2d stdout ---- thread 'fusion::base::tests::maxmin::tests::test_mean_dim_2d' panicked at burn-wgpu/src/fusion/base.rs:185:5: assertion `left == right` failed left: Data { value: [1.0, 4.0], shape: Shape { dims: [2, 1] } } right: Data { value: [0.99999994, 3.9999998], shape: Shape { dims: [2, 1] } } ----
+
+tests::maxmin::tests::test_mean_dim_2d stdout ---- thread 'tests::maxmin::tests::test_mean_dim_2d' panicked at burn-wgpu/src/lib.rs:49:5: assertion `left == right` failed left: Data { value: [1.0, 4.0], shape: Shape { dims: [2, 1] } } right: Data { value: [0.99999994, 3.9999998], shape: Shape { dims: [2, 1] } }
+```
+
+If you encounter this, swap out the `assert_eq!` in the failing test for `tensor1.assert_approx_eq` with `3` as the second argument.
+
+## Mismatched types and missing functions
+
+```sh
+error[E0308]: mismatched types --> {burn_dir}/target/debug/build/onnx-tests-fed12aaf3671687f/out/model/pow.rs:48:45 | 48 | let pow1_out1 = input1.clone().powf(input1); | ---- ^^^^^^ expected `f32`, found `Tensor<B, 4>` | | | arguments to this method are incorrect | = note: expected type `f32` found struct `Tensor<B, 4>` 
+
+note: method defined here --> {burn_dir}/burn-tensor/src/tensor/api/float.rs:65:12 | 65 | pub fn powf(self, value: f32) -> Self { | ^^^^ 
+
+error[E0599]: no method named `powf_scalar` found for struct `Tensor` in the current scope --> {burn_dir}/target/debug/build/onnx-tests-fed12aaf3671687f/out/model/pow.rs:50:35 | 50 | let pow2_out1 = pow1_out1.powf_scalar(cast1_out1); | ^^^^^^^^^^^ method not found in `Tensor<B, 4>` 
+
+error[E0599]: no method named `powi` found for struct `Tensor` in the current scope --> {burn_dir}/target/debug/build/onnx-tests-fed12aaf3671687f/out/model/pow_int.rs:49:40 | 49 | let pow1_out1 = input1.clone().powi(input1); | ^^^^ method not found in `Tensor<B, 4, Int>` Some errors have detailed explanations: E0308, E0599. 
+For more information about an error, try `rustc --explain E0308`. error: could not compile `onnx-tests` (test "onnx_tests") due to 3 previous errors
+```
+
+So if you are getting this, you probably didn't impl your operator for the actual Tensor struct. I wasn't aware of the existence or role of `burn-tensor/src/tensor/api/numeric.rs`, and had first defined just the Ops for the Int and Float tensors, that coupled with `powf` existing prior to the PR though for scalar values(which had been renamed, just not in the right place), led to this confusing issue where it looked like the function was found, but the type was wrong. If that's the case, make sure that it's implemented for the appropriate type, in this case `Float` under [burn-tensor/src/tensor/api/numeric.rs](https://github.com/tracel-ai/burn/blob/4ca3e31601228952bb1c1492bc9cd2adf15b5cf1/burn-tensor/src/tensor/api/numeric.rs#L2186), and calling the `TensorOp.foo_op` defined under [burn-tensor/src/ops/tensor.rs](https://github.com/tracel-ai/burn/blob/4ca3e31601228952bb1c1492bc9cd2adf15b5cf1/burn-tensor/src/tensor/ops/tensor.rs#L873)

contributor-book/src/getting-started/ReadMe.md

@@ -0,0 +1,3 @@
+# Getting Started
+
+This section is for setting up the environment and how to do basic development tasks such as running tests and checking your code before committing.

contributor-book/src/getting-started/configuring-your-editor.md

@@ -0,0 +1,24 @@
+# Configuring your editor
+
+These are not required, and most of this isn't specific to Burn, but it's definitely helpful if you haven't already done it.
+
+## VSCode
+
+1. Install the following extensions:
+
+- [rust-lang.rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
+- [tamasfe.even-better-toml](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
+- [serayuzgur.crates](https://marketplace.visualstudio.com/items?itemName=serayuzgur.crates)
+- [vadimcn.vscode-lldb](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
+
+2. Open `Command Palette` with Ctrl+Shift+P or F1 and type `LLDB: Generate Launch Configurations from Cargo.toml` then select it, this will generate a file that should be saved as `.vscode/launch.json`.
+
+3. Now you can enable breakpoint on code through IDE and then start debugging the library/binary you want, such as the following example:
+
+<div align="center">
+<img src="./assets/debug-options-vscode.png" width="700px"/>
+<div align="left">
+
+4. If you're creating a new library or binary, keep in mind to repeat the step 2 to always keep a fresh list of targets.
+
+## Have another editor? Open a PR!

contributor-book/src/getting-started/setting-up-the-environment.md

@@ -0,0 +1,32 @@
+# setting up the environment
+
+There are a couple of tools that need to be installed, and commands to be familiar with, depending on what part of the project you plan on contributing to. This section should be up to date with current project practices (as of 2024-01-26)
+
+## General
+
+there are a few commands you want to run prior to any commit for a non-draft PR:
+
+1. `cargo clippy --fix --allow-dirty`, this will run clippy and fix any issues it can, the allow dirty flag is required whenever you have uncommitted changes
+2. `cargo fmt --all`, this will run rustfmt on all files in the project
+3. `./run_checks.sh all`, this is a script located in the project root that builds and tests the project. It is required that this pass prior to merging a PR. Fair warning, running these tests can take a while[^2].
+
+## Updating the burn semver version
+
+To bump for the next version, install `cargo-edit` if its not on your system, and use this command:
+
+```sh
+cargo set-version --bump minor
+```
+
+## Contributing to the Burn (Developer) Book
+
+Both the Burn book and the burn developer book are built with mdbook. To install mdbook, run the following command[^1]:
+
+```bash
+cargo install mdbook
+```
+
+also instead of running `./run_checks.sh all`, you can run `./run_checks.sh typo` to only check for misspellings. This will install [typo](https://crates.io/crates/typos-cli), and if any are encountered you should be able to run `typo -w /path/to/book` to fix them.
+
+[^1]: You might also want to install [cargo-update](https://github.com/nabijaczleweli/cargo-update) to easily keep your tools up to date, though it is in no way required.
+[^2]: if your system is running into issues with memory and you are on linux you may want to switch to a [virtual console](https://wiki.archlinux.org/title/Linux_console#Virtual_consoles) to run the tests. To do this, press `ctrl+alt+f3` to switch to a virtual console(and log in), and either `ctrl+alt+f2` or `ctrl+alt+f1` to switch back to your graphical session.

contributor-book/src/getting-started/testing.md

@@ -0,0 +1,19 @@
+# testing
+
+## Test for TensorOps
+
+the following examples use matrix multiplication operation
+
+Test for Tensor operations (as in given this input, expect it match or approximate this output) are defined only in [`burn-tensor/src/test/ops`](https://github.com/tracel-ai/burn/blob/b9bd42959b0d3e755a25e383cb5b38beb25559b8/burn-tensor/src/tests/ops/matmul.rs#L1) and not in the backends, with the exception of `burn-autodiff`. These test are added to the `testgen_all` macro rule in [`burn-tensor/src/test/mod.rs`](https://github.com/tracel-ai/burn/blob/b9bd42959b0d3e755a25e383cb5b38beb25559b8/burn-tensor/src/tests/mod.rs#L59). This is then propagated to the existing backends without any additional work.
+
+### Test for Autodiff
+
+the following examples use the power operation
+
+Test for autodiff go under [burn-autodiff/src/tests/foo.rs](https://github.com/tracel-ai/burn/blob/4ca3e31601228952bb1c1492bc9cd2adf15b5cf1/burn-autodiff/src/tests/pow.rs#L31) (replacing foo for whatever makes sense for your op), and for tensor operations both the left and right side need to be verified. The easiest way to do this, is to
+
+1. use small tensors with simple values
+2. pop open a terminal and launch `ipython` import `numpy` (or just use [google colab](https://colab.google/) if you don't have the packages installed and don't want to install them), and do the calculations by hand.
+3. comparing the actual to expected output for lhs, rhs and regular operation
+
+generally, it seems preferable to use `actual_output_tensor.to_data().assert_approx_eq(&expected_tensor_data,3)` to `assert_eq!(...` due to occasional hiccups with floating point calculations.

contributor-book/src/guides/ReadMe.md

@@ -0,0 +1,3 @@
+# Guides for Contributors
+
+The following guides are meant to help contributors trying to accomplish specific tasks, such as adding a new operations to Burn or generating test models for burn-import.