tweaks

FluxML · Oct 8, 2022 · 45735b9 · 45735b9
1 parent 018ebbc
commit 45735b9
Show file tree

Hide file tree

Showing 8 changed files with 23 additions and 15 deletions.
diff --git a/docs/src/assets/oneminute.png b/docs/src/assets/oneminute.png
diff --git a/docs/src/destructure.md b/docs/src/destructure.md
@@ -1,7 +1,7 @@
-# Flat vs. Nested Structures
+# [Flat vs. Nested Structures](@id man-destructure)
 
 
-A Flux model is a nested structure, with parameters stored within many layers. Sometimes you may want a flat representation of them, to interact with functions expecting just one vector. This is provided by `destructure`.
+A Flux model is a nested structure, with parameters stored within many layers. Sometimes you may want a flat representation of them, to interact with functions expecting just one vector. This is provided by `destructure`:
 
 ```julia
 julia> model = Chain(Dense(2=>1, tanh), Dense(1=>1))
@@ -20,9 +20,9 @@ Chain(
 )                   # Total: 4 arrays, 5 parameters, 276 bytes.
 ```
 
-This can be used within gradient computations. For instance, this computes the Hessian `∂²L/∂θᵢ∂θⱼ` of some loss function, with respect to all parameters of the Flux model. The resulting matrix has off-diagonal entries, which cannot really be expressed in a nested structure:
+Both `destructure` and the `Restructure` function can be used within gradient computations. For instance, this computes the Hessian `∂²L/∂θᵢ∂θⱼ` of some loss function, with respect to all parameters of the Flux model. The resulting matrix has off-diagonal entries, which cannot really be expressed in a nested structure:
 
-```
+```julia
 julia> x = rand(Float32, 2, 16);
 
 julia> grad = gradient(m -> sum(abs2, m(x)), model)  # nested gradient

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -4,7 +4,7 @@ Flux is a library for machine learning. It comes "batteries-included" with many
 
 * **Doing the obvious thing**. Flux has relatively few explicit APIs for features like regularisation or embeddings. Instead, writing down the mathematical form will work – and be fast.
 * **Extensible by default**. Flux is written to be highly extensible and flexible while being performant. Extending Flux is as simple as using your own code as part of the model you want - it is all [high-level Julia code](https://github.com/FluxML/Flux.jl/blob/ec16a2c77dbf6ab8b92b0eecd11661be7a62feef/src/layers/recurrent.jl#L131). When in doubt, it’s well worth looking at [the source](https://github.com/FluxML/Flux.jl/). If you need something different, you can easily roll your own.
-* **Play nicely with others**. Flux works well with Julia libraries from [data frames](https://github.com/JuliaComputing/JuliaDB.jl) and [images](https://github.com/JuliaImages/Images.jl) to [differential equation solvers](https://github.com/JuliaDiffEq/DifferentialEquations.jl), so you can easily build complex data processing pipelines that integrate Flux models.
+* **Play nicely with others**. Flux works well with Julia libraries from [images](https://github.com/JuliaImages/Images.jl) to [differential equation solvers](https://github.com/JuliaDiffEq/DifferentialEquations.jl), so you can easily build complex data processing pipelines that integrate Flux models.
 
 ## Installation
 

diff --git a/docs/src/models/basics.md b/docs/src/models/basics.md
@@ -1,4 +1,4 @@
-# How Flux Works: Gradients and Layers
+# [How Flux Works: Gradients and Layers](@id man-basics)
 
 ## Taking Gradients
 

diff --git a/docs/src/models/losses.md b/docs/src/models/losses.md
@@ -1,4 +1,4 @@
-# Loss Functions
+# [Loss Functions](@id man-losses)
 
 Flux provides a large number of common loss functions used for training machine learning models.
 They are grouped together in the `Flux.Losses` module.

diff --git a/docs/src/models/overview.md b/docs/src/models/overview.md
@@ -1,4 +1,4 @@
-# Flux Overview: Fitting a Straight Line
+# [Flux Overview: Fitting a Straight Line](@id man-overview)
 
 Flux is a pure Julia ML stack that allows you to build predictive models. Here are the steps for a typical Flux program:
 

diff --git a/docs/src/models/quickstart.md b/docs/src/models/quickstart.md
@@ -1,4 +1,4 @@
-# A Neural Network in One Minute
+# [A Neural Network in One Minute](@id man-quickstart)
 
 If you have used neural networks before, then this simple example might be helpful for seeing how the major parts of Flux work together. Try pasting the code into the REPL prompt.
 
@@ -47,9 +47,9 @@ mean((out2[1,:] .> 0.5) .== truth)  # accuracy 94% so far!
 ```
 using Plots  # to draw the above figure
 
-p_true = Plots.scatter(noisy[1,:], noisy[2,:], zcolor=truth, legend=false, title="True classification")
-p_raw = Plots.scatter(noisy[1,:], noisy[2,:], zcolor=out1[1,:], label="", title="Untrained network")
-p_done = Plots.scatter(noisy[1,:], noisy[2,:], zcolor=out2[1,:], legend=false, title="Trained network")
+p_true = scatter(noisy[1,:], noisy[2,:], zcolor=truth, title="True classification", legend=false)
+p_raw =  scatter(noisy[1,:], noisy[2,:], zcolor=out1[1,:], title="Untrained network", label="", clims=(0,1))
+p_done = scatter(noisy[1,:], noisy[2,:], zcolor=out2[1,:], title="Trained network", legend=false)
 
 plot(p_true, p_raw, p_done, layout=(1,3), size=(1000,330))
 ```
@@ -66,6 +66,14 @@ Some things to notice in this example are:
 
 * The `model` can be called like a function, `y = model(x)`. It encapsulates the parameters (and state).
 
-* But the model does not contain the loss function, nor the optimisation rule. Instead `Adam()` stores between iterations the momenta it needs.
+* But the model does not contain the loss function, nor the optimisation rule. Instead the [`Adam()`](@ref Adam) object stores between iterations the momenta it needs.
 
-* The function `train!` likes data as an iterator generating Tuples. You can use lower-level functions instead.
+* The function [`train!`](@ref) likes data as an iterator generating `Tuple`s, here produced by [`DataLoader`](@ref). This mutates both the `model` and the optimiser state inside `opt`.
+
+There are other ways to train Flux models, for more control than `train!` provides:
+
+* Within Flux, you can easily write a training loop, calling [`gradient`](@ref) and [`update!`](@ref).
+
+* For a lower-level way, see the package [Optimisers.jl](https://github.com/FluxML/Optimisers.jl).
+
+* For higher-level ways, see [FluxTraining.jl](https://github.com/FluxML/FluxTraining.jl) and [FastAI.jl](https://github.com/FluxML/FastAI.jl).
diff --git a/docs/src/training/training.md b/docs/src/training/training.md
@@ -1,4 +1,4 @@
-# Training
+# [Training](@id man-training)
 
 To actually train a model we need four things: