Expand readme, link to Lux.jl (#73)

* expand readme

* where's mr clippy when you need him?

* Apply suggestions from code review

Co-authored-by: Carlo Lucibello <[email protected]>
Co-authored-by: Kyle Daruwalla <[email protected]>

Co-authored-by: Carlo Lucibello <[email protected]>
Co-authored-by: Kyle Daruwalla <[email protected]>

Author: 3 people

README.md

@@ -20,14 +20,37 @@
 Optimisers.jl defines many standard gradient-based optimisation rules, and tools for applying them to deeply nested models.
 
 This is the future of training for [Flux.jl](https://github.com/FluxML/Flux.jl) neural networks,
-but it can be used separately on anything understood by [Functors.jl](https://github.com/FluxML/Functors.jl).
+and the present for [Lux.jl](https://github.com/avik-pal/Lux.jl).
+But it can be used separately on anything understood by [Functors.jl](https://github.com/FluxML/Functors.jl).
 
 ## Installation
 
 ```julia
-]add Optimisers
+] add Optimisers
 ```
 
 ## Usage
 
-Find out more about using Optimisers.jl [in the docs](https://fluxml.ai/Optimisers.jl/dev/).
+The core idea is that optimiser state (such as momentum) is explicitly handled.
+It is initialised by `setup`, and then at each step, `update` returns both the new
+state, and the model with its trainable parameters adjusted:
+
+```julia
+state = Optimisers.setup(Optimisers.ADAM(), model)  # just once
+
+state, model = Optimisers.update(state, model, grad)  # at every step
+```
+
+For models with deeply nested layers containing the parameters (like [Flux.jl](https://github.com/FluxML/Flux.jl) models),
+this state is a similarly nested tree.
+The function `destructure` collects all the trainable parameters into one vector,
+and returns this along with a function to re-build a similar model:
+
+```julia
+vector, re = Optimisers.destructure(model)
+
+model2 = re(2 .* vector)
+```
+
+[The documentation](https://fluxml.ai/Optimisers.jl/dev/) explains usage in more detail,
+describes all the optimization rules, and shows how to define new ones.