From 98d55f72c68c165019e6003e51dc8d1870289f02 Mon Sep 17 00:00:00 2001 From: zeptodoctor <44736852+zeptodoctor@users.noreply.github.com> Date: Mon, 2 Mar 2020 12:52:32 +0000 Subject: [PATCH] build based on ddab979 --- dev/community/index.html | 2 +- dev/data/dataloader/index.html | 30 +++++++++++++++++++++ dev/data/onehot/index.html | 4 +-- dev/ecosystem/index.html | 9 +++++++ dev/gpu/index.html | 8 +++--- dev/index.html | 2 +- dev/models/basics/index.html | 4 +-- dev/models/layers/index.html | 27 +++++++++---------- dev/models/nnlib/index.html | 23 ++++++++++++++++ dev/models/recurrence/index.html | 2 +- dev/models/regularisation/index.html | 6 ++--- dev/performance/index.html | 4 +-- dev/saving/index.html | 4 +-- dev/search/index.html | 2 +- dev/search_index.js | 2 +- dev/training/optimisers/index.html | 40 +++++++++++++--------------- dev/training/training/index.html | 13 +++++---- 17 files changed, 121 insertions(+), 61 deletions(-) create mode 100644 dev/data/dataloader/index.html create mode 100644 dev/ecosystem/index.html create mode 100644 dev/models/nnlib/index.html diff --git a/dev/community/index.html b/dev/community/index.html index bbbb28cb..ea76941f 100644 --- a/dev/community/index.html +++ b/dev/community/index.html @@ -6,4 +6,4 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) ga('create', 'UA-36890222-9', 'auto'); ga('send', 'pageview'); -
Community

Community

All Flux users are welcome to join our community on the Julia forum, or the slack (channel #machine-learning). If you have questions or issues we'll try to help you out.

If you're interested in hacking on Flux, the source code is open and easy to understand – it's all just the same Julia code you work with normally. You might be interested in our intro issues to get started.

+
Community

Community

All Flux users are welcome to join our community on the Julia forum, or the slack (channel #machine-learning). If you have questions or issues we'll try to help you out.

If you're interested in hacking on Flux, the source code is open and easy to understand – it's all just the same Julia code you work with normally. You might be interested in our intro issues to get started.

diff --git a/dev/data/dataloader/index.html b/dev/data/dataloader/index.html new file mode 100644 index 00000000..868f9e9b --- /dev/null +++ b/dev/data/dataloader/index.html @@ -0,0 +1,30 @@ + +DataLoader · Flux
DataLoader

DataLoader

Flux provides the DataLoader type in the Flux.Data module to handle iteration over mini-batches of data.

Flux.Data.DataLoader — Type.
DataLoader(data...; batchsize=1, shuffle=false, partial=true)

An object that iterates over mini-batches of data, each mini-batch containing batchsize observations (except possibly the last one).

Takes as input one or more data tensors, e.g. X in unsupervised learning, X and Y in supervised learning. The last dimension in each tensor is considered to be the observation dimension.

If shuffle=true, shuffles the observations each time iterations are re-started. If partial=false, drops the last mini-batch if it is smaller than the batchsize.

Example usage:

Xtrain = rand(10, 100)
+dtrain = DataLoader(Xtrain, batchsize=2) 
+# iterate over 50 mini-batches
+for x in dtrain: 
+    @assert size(x) == (10, 2)
+    ...
+end
+
+Xtrain = rand(10, 100)
+Ytrain = rand(100)
+dtrain = DataLoader(Xtrain, Ytrain, batchsize=2, shuffle=true) 
+for epoch in 1:100
+    for (x, y) in dtrain: 
+        @assert size(x) == (10, 2)
+        @assert size(y) == (2,)
+        ...
+    end
+end
+
+# train for 10 epochs
+using IterTools: ncycle 
+Flux.train!(loss, ps, ncycle(dtrain, 10), opt)
source
diff --git a/dev/data/onehot/index.html b/dev/data/onehot/index.html index 7e730f14..2bcadbaf 100644 --- a/dev/data/onehot/index.html +++ b/dev/data/onehot/index.html @@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) ga('create', 'UA-36890222-9', 'auto'); ga('send', 'pageview'); -
One-Hot Encoding

One-Hot Encoding

It's common to encode categorical variables (like true, false or cat, dog) in "one-of-k" or "one-hot" form. Flux provides the onehot function to make this easy.

julia> using Flux: onehot, onecold
+
One-Hot Encoding
One-Hot Encoding
It's common to encode categorical variables (like true, false or cat, dog) in "one-of-k" or "one-hot" form. Flux provides the onehot function to make this easy.
julia> using Flux: onehot, onecold
 
 julia> onehot(:b, [:a, :b, :c])
 3-element Flux.OneHotVector:
@@ -37,4 +37,4 @@ julia> onecold(ans, [:a, :b, :c])
 3-element Array{Symbol,1}:
   :b
   :a
-  :b
Note that these operations returned OneHotVector and OneHotMatrix rather than Arrays. OneHotVectors behave like normal vectors but avoid any unnecessary cost compared to using an integer index directly. For example, multiplying a matrix with a one-hot vector simply slices out the relevant row of the matrix under the hood.

+  :b

Note that these operations returned OneHotVector and OneHotMatrix rather than Arrays. OneHotVectors behave like normal vectors but avoid any unnecessary cost compared to using an integer index directly. For example, multiplying a matrix with a one-hot vector simply slices out the relevant row of the matrix under the hood.

diff --git a/dev/ecosystem/index.html b/dev/ecosystem/index.html new file mode 100644 index 00000000..57518a2f --- /dev/null +++ b/dev/ecosystem/index.html @@ -0,0 +1,9 @@ + +The Julia Ecosystem · Flux
The Julia Ecosystem

The Julia Ecosystem

One of the main strengths of Julia lies in an ecosystem of packages globally providing a rich and consistent user experience.

This is a non-exhaustive list of Julia packages, nicely complementing Flux in typical machine learning and deep learning workflows:

This tight integration among Julia pakages is shown in some of the examples in the model-zoo repository.

diff --git a/dev/gpu/index.html b/dev/gpu/index.html index 5178af98..1ac63785 100644 --- a/dev/gpu/index.html +++ b/dev/gpu/index.html @@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) ga('create', 'UA-36890222-9', 'auto'); ga('send', 'pageview'); -
GPU Support

GPU Support

NVIDIA GPU support should work out of the box on systems with CUDA and CUDNN installed. For more details see the CuArrays readme.

GPU Usage

Support for array operations on other hardware backends, like GPUs, is provided by external packages like CuArrays. Flux is agnostic to array types, so we simply need to move model weights and data to the GPU and Flux will handle it.

For example, we can use CuArrays (with the cu converter) to run our basic example on an NVIDIA GPU.

(Note that you need to have CUDA available to use CuArrays – please see the CuArrays.jl instructions for more details.)

using CuArrays
+
GPU Support
GPU Support
NVIDIA GPU support should work out of the box on systems with CUDA and CUDNN installed. For more details see the CuArrays readme.
GPU Usage
Support for array operations on other hardware backends, like GPUs, is provided by external packages like CuArrays. Flux is agnostic to array types, so we simply need to move model weights and data to the GPU and Flux will handle it.
For example, we can use CuArrays (with the cu converter) to run our basic example on an NVIDIA GPU.
(Note that you need to have CUDA available to use CuArrays – please see the CuArrays.jl instructions for more details.)
using CuArrays
 
 W = cu(rand(2, 5)) # a 2×5 CuArray
 b = cu(rand(2))
@@ -17,7 +17,7 @@ loss(x, y) = sum((predict(x) .- y).^2)
 x, y = cu(rand(5)), cu(rand(2)) # Dummy data
 loss(x, y) # ~ 3
Note that we convert both the parameters (W, b) and the data set (x, y) to cuda arrays. Taking derivatives and training works exactly as before.
If you define a structured model, like a Dense layer or Chain, you just need to convert the internal parameters. Flux provides fmap, which allows you to alter all parameters of a model at once.
d = Dense(10, 5, σ)
 d = fmap(cu, d)
-d.W # Tracked CuArray
+d.W # CuArray
 d(cu(rand(10))) # CuArray output
 
 m = Chain(Dense(10, 5, σ), Dense(5, 2), softmax)
@@ -34,7 +34,7 @@ julia> x = rand(10) |> gpu
  0.511655
 
 julia> m(x)
-Tracked 5-element CuArray{Float32,1}:
+5-element CuArray{Float32,1}:
  -0.30535
  ⋮
  -0.618002
The analogue cpu is also available for moving models and data back off of the GPU.
julia> x = rand(10) |> gpu
@@ -47,4 +47,4 @@ julia> x |> cpu
 10-element Array{Float32,1}:
  0.235164
  ⋮
- 0.192538

+ 0.192538
diff --git a/dev/index.html b/dev/index.html index 1e6f6145..54741c05 100644 --- a/dev/index.html +++ b/dev/index.html @@ -6,4 +6,4 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) ga('create', 'UA-36890222-9', 'auto'); ga('send', 'pageview'); -
Home

Flux: The Julia Machine Learning Library

Flux is a library for machine learning. It comes "batteries-included" with many useful tools built in, but also lets you use the full power of the Julia language where you need it. We follow a few key principles:

Installation

Download Julia 1.0 or later, if you haven't already. You can add Flux from using Julia's package manager, by typing ] add Flux in the Julia prompt.

If you have CUDA you can also run ] add CuArrays to get GPU support; see here for more details.

Learning Flux

There are several different ways to learn Flux. If you just want to get started writing models, the model zoo gives good starting points for many common ones. This documentation provides a reference to all of Flux's APIs, as well as a from-scratch introduction to Flux's take on models and how they work. Once you understand these docs, congratulations, you also understand Flux's source code, which is intended to be concise, legible and a good reference for more advanced concepts.

+
Home

Flux: The Julia Machine Learning Library

Flux is a library for machine learning. It comes "batteries-included" with many useful tools built in, but also lets you use the full power of the Julia language where you need it. We follow a few key principles:

Installation

Download Julia 1.0 or later, if you haven't already. You can add Flux from using Julia's package manager, by typing ] add Flux in the Julia prompt.

If you have CUDA you can also run ] add CuArrays to get GPU support; see here for more details.

Learning Flux

There are several different ways to learn Flux. If you just want to get started writing models, the model zoo gives good starting points for many common ones. This documentation provides a reference to all of Flux's APIs, as well as a from-scratch introduction to Flux's take on models and how they work. Once you understand these docs, congratulations, you also understand Flux's source code, which is intended to be concise, legible and a good reference for more advanced concepts.

diff --git a/dev/models/basics/index.html b/dev/models/basics/index.html index c82c5c67..b364afba 100644 --- a/dev/models/basics/index.html +++ b/dev/models/basics/index.html @@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) ga('create', 'UA-36890222-9', 'auto'); ga('send', 'pageview'); -
Basics

Model-Building Basics

Taking Gradients

Flux's core feature is taking gradients of Julia code. The gradient function takes another Julia function f and a set of arguments, and returns the gradient with respect to each argument. (It's a good idea to try pasting these examples in the Julia terminal.)

julia> using Flux
+
Basics
Model-Building Basics
Taking Gradients
Flux's core feature is taking gradients of Julia code. The gradient function takes another Julia function f and a set of arguments, and returns the gradient with respect to each argument. (It's a good idea to try pasting these examples in the Julia terminal.)
julia> using Flux
 
 julia> f(x) = 3x^2 + 2x + 1;
 
@@ -110,4 +110,4 @@ model2(rand(10)) # => 2-element vector
This quickly starts to
 
 m(rand(10))

Likewise, Chain will happily work with any Julia function.

m = Chain(x -> x^2, x -> x+1)
 
-m(5) # => 26

Layer helpers

Flux provides a set of helpers for custom layers, which you can enable by calling

Flux.@functor Affine

This enables a useful extra set of functionality for our Affine layer, such as collecting its parameters or moving it to the GPU.

+m(5) # => 26

Layer helpers

Flux provides a set of helpers for custom layers, which you can enable by calling

Flux.@functor Affine

This enables a useful extra set of functionality for our Affine layer, such as collecting its parameters or moving it to the GPU.

Utility functions

Flux provides some utility functions to help you generate models in an automated fashion.

outdims enables you to calculate the spatial output dimensions of layers like Conv when applied to input images of a given size. Currently limited to the following layers:

Missing docstring.

Missing docstring for outdims. Check Documenter's build log for details.

diff --git a/dev/models/layers/index.html b/dev/models/layers/index.html index 80c0d134..1a91405f 100644 --- a/dev/models/layers/index.html +++ b/dev/models/layers/index.html @@ -6,47 +6,46 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) ga('create', 'UA-36890222-9', 'auto'); ga('send', 'pageview'); -
Model Reference

Basic Layers

These core layers form the foundation of almost all neural networks.

Flux.Chain — Type.
Chain(layers...)

Chain multiple layers / functions together, so that they are called in sequence on a given input.

m = Chain(x -> x^2, x -> x+1)
+
Model Reference
Basic Layers
These core layers form the foundation of almost all neural networks.
Flux.Chain — Type.
Chain(layers...)
Chain multiple layers / functions together, so that they are called in sequence on a given input.
m = Chain(x -> x^2, x -> x+1)
 m(5) == 26
 
 m = Chain(Dense(10, 5), Dense(5, 2))
 x = rand(10)
-m(x) == m[2](m[1](x))
Chain also supports indexing and slicing, e.g. m[2] or m[1:end-1]. m[1:3](x) will calculate the output of the first three layers.
source
Flux.Dense — Type.
Dense(in::Integer, out::Integer, σ = identity)
Creates a traditional Dense layer with parameters W and b.
y = σ.(W * x .+ b)
The input x must be a vector of length in, or a batch of vectors represented as an in × N matrix. The out y will be a vector or batch of length out.
julia> d = Dense(5, 2)
+m(x) == m[2](m[1](x))
Chain also supports indexing and slicing, e.g. m[2] or m[1:end-1]. m[1:3](x) will calculate the output of the first three layers.
source
Flux.Dense — Type.
Dense(in::Integer, out::Integer, σ = identity)
Creates a traditional Dense layer with parameters W and b.
y = σ.(W * x .+ b)
The input x must be a vector of length in, or a batch of vectors represented as an in × N matrix. The out y will be a vector or batch of length out.
julia> d = Dense(5, 2)
 Dense(5, 2)
 
 julia> d(rand(5))
 Tracked 2-element Array{Float64,1}:
   0.00257447
-  -0.00449443
source
Convolution and Pooling Layers
These layers are used to build convolutional neural networks (CNNs).
Flux.Conv — Type.
Conv(size, in=>out)
+  -0.00449443
source
Convolution and Pooling Layers
These layers are used to build convolutional neural networks (CNNs).
Flux.Conv — Type.
Conv(size, in=>out)
 Conv(size, in=>out, relu)
Standard convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.
Example: Applying Conv layer to a 1-channel input using a 2x2 window size,          giving us a 16-channel output. Output is activated with ReLU.
size = (2,2)
 in = 1
 out = 16
-Conv((2, 2), 1=>16, relu)
Data should be stored in WHCN order (width, height, # channels, # batches). In other words, a 100×100 RGB image would be a 100×100×3×1 array, and a batch of 50 would be a 100×100×3×50 array.
Takes the keyword arguments pad, stride and dilation.
source
Flux.MaxPool — Type.
MaxPool(k)
Max pooling layer. k stands for the size of the window for each dimension of the input.
Takes the keyword arguments pad and stride.
source
Flux.MeanPool — Type.
MeanPool(k)
Mean pooling layer. k stands for the size of the window for each dimension of the input.
Takes the keyword arguments pad and stride.
source
Flux.DepthwiseConv — Type.
DepthwiseConv(size, in=>out)
-DepthwiseConv(size, in=>out, relu)
Depthwise convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively. Note that out must be an integer multiple of in.
Data should be stored in WHCN order. In other words, a 100×100 RGB image would be a 100×100×3 array, and a batch of 50 would be a 100×100×3×50 array.
Takes the keyword arguments pad, stride and dilation.
source
Flux.ConvTranspose — Type.
ConvTranspose(size, in=>out)
-ConvTranspose(size, in=>out, relu)
Standard convolutional transpose layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.
Data should be stored in WHCN order. In other words, a 100×100 RGB image would be a 100×100×3 array, and a batch of 50 would be a 100×100×3×50 array.
Takes the keyword arguments pad, stride and dilation.
source
Flux.CrossCor — Type.
CrossCor(size, in=>out)
+Conv((2, 2), 1=>16, relu)
Data should be stored in WHCN order (width, height, # channels, batch size). In other words, a 100×100 RGB image would be a 100×100×3×1 array, and a batch of 50 would be a 100×100×3×50 array.
Takes the keyword arguments pad, stride and dilation.
source
Flux.MaxPool — Type.
MaxPool(k)
Max pooling layer. k stands for the size of the window for each dimension of the input.
Takes the keyword arguments pad and stride.
source
Flux.MeanPool — Type.
MeanPool(k)
Mean pooling layer. k stands for the size of the window for each dimension of the input.
Takes the keyword arguments pad and stride.
source
Flux.DepthwiseConv — Type.
DepthwiseConv(size, in=>out)
+DepthwiseConv(size, in=>out, relu)
Depthwise convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively. Note that out must be an integer multiple of in.
Data should be stored in WHCN order. In other words, a 100×100 RGB image would be a 100×100×3 array, and a batch of 50 would be a 100×100×3×50 array.
Takes the keyword arguments pad, stride and dilation.
source
Flux.ConvTranspose — Type.
ConvTranspose(size, in=>out)
+ConvTranspose(size, in=>out, relu)
Standard convolutional transpose layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.
Data should be stored in WHCN order. In other words, a 100×100 RGB image would be a 100×100×3 array, and a batch of 50 would be a 100×100×3×50 array.
Takes the keyword arguments pad, stride and dilation.
source
Flux.CrossCor — Type.
CrossCor(size, in=>out)
 CrossCor(size, in=>out, relu)
Standard cross convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.
Example: Applying CrossCor layer to a 1-channel input using a 2x2 window size,          giving us a 16-channel output. Output is activated with ReLU.
size = (2,2)
 in = 1
 out = 16
-CrossCor((2, 2), 1=>16, relu)
Data should be stored in WHCN order (width, height, # channels, # batches). In other words, a 100×100 RGB image would be a 100×100×3×1 array, and a batch of 50 would be a 100×100×3×50 array.
Takes the keyword arguments pad, stride and dilation.
source
Recurrent Layers
Much like the core layers above, but can be used to process sequence data (as well as other kinds of structured data).
Flux.RNN — Function.
RNN(in::Integer, out::Integer, σ = tanh)
The most basic recurrent layer; essentially acts as a Dense layer, but with the output fed back into the input each time step.
source
Flux.LSTM — Function.
LSTM(in::Integer, out::Integer)
Long Short Term Memory recurrent layer. Behaves like an RNN but generally exhibits a longer memory span over sequences.
See this article for a good overview of the internals.
source
Flux.GRU — Function.
GRU(in::Integer, out::Integer)
Gated Recurrent Unit layer. Behaves like an RNN but generally exhibits a longer memory span over sequences.
See this article for a good overview of the internals.
source
Flux.Recur — Type.
Recur(cell)
Recur takes a recurrent cell and makes it stateful, managing the hidden state in the background. cell should be a model of the form:
h, y = cell(h, x...)
For example, here's a recurrent network that keeps a running total of its inputs.
accum(h, x) = (h+x, x)
+CrossCor((2, 2), 1=>16, relu)
Data should be stored in WHCN order (width, height, # channels, # batches). In other words, a 100×100 RGB image would be a 100×100×3×1 array, and a batch of 50 would be a 100×100×3×50 array.
Takes the keyword arguments pad, stride and dilation.
source
Recurrent Layers
Much like the core layers above, but can be used to process sequence data (as well as other kinds of structured data).
Flux.RNN — Function.
RNN(in::Integer, out::Integer, σ = tanh)
The most basic recurrent layer; essentially acts as a Dense layer, but with the output fed back into the input each time step.
source
Flux.LSTM — Function.
LSTM(in::Integer, out::Integer)
Long Short Term Memory recurrent layer. Behaves like an RNN but generally exhibits a longer memory span over sequences.
See this article for a good overview of the internals.
source
Flux.GRU — Function.
GRU(in::Integer, out::Integer)
Gated Recurrent Unit layer. Behaves like an RNN but generally exhibits a longer memory span over sequences.
See this article for a good overview of the internals.
source
Flux.Recur — Type.
Recur(cell)
Recur takes a recurrent cell and makes it stateful, managing the hidden state in the background. cell should be a model of the form:
h, y = cell(h, x...)
For example, here's a recurrent network that keeps a running total of its inputs.
accum(h, x) = (h+x, x)
 rnn = Flux.Recur(accum, 0)
 rnn(2) # 2
 rnn(3) # 3
 rnn.state # 5
 rnn.(1:10) # apply to a sequence
-rnn.state # 60
source
Other General Purpose Layers
These are marginally more obscure than the Basic Layers. But in contrast to the layers described in the other sections are not readily grouped around a particular purpose (e.g. CNNs or RNNs).
Flux.Maxout — Type.
Maxout(over)
Maxout is a neural network layer, which has a number of internal layers, which all have the same input, and the maxout returns the elementwise maximium of the internal layers' outputs.
Maxout over linear dense layers satisfies the univeral approximation theorem.
Reference: Ian J. Goodfellow, David Warde-Farley, Mehdi Mirza, Aaron Courville, and Yoshua Bengio.
  1. Maxout networks.
In Proceedings of the 30th International Conference on International Conference on Machine Learning - Volume 28 (ICML'13), Sanjoy Dasgupta and David McAllester (Eds.), Vol. 28. JMLR.org III-1319-III-1327. https://arxiv.org/pdf/1302.4389.pdf
source
Flux.SkipConnection — Type.
SkipConnection(layers, connection)
Creates a Skip Connection, of a layer or Chain of consecutive layers plus a shortcut connection. The connection function will combine the result of the layers with the original input, to give the final output.
The simplest 'ResNet'-type connection is just SkipConnection(layer, +), and requires the output of the layers to be the same shape as the input. Here is a more complicated example:
m = Conv((3,3), 4=>7, pad=(1,1))
+rnn.state # 60
source
Other General Purpose Layers
These are marginally more obscure than the Basic Layers. But in contrast to the layers described in the other sections are not readily grouped around a particular purpose (e.g. CNNs or RNNs).
Flux.Maxout — Type.
Maxout(over)
Maxout is a neural network layer, which has a number of internal layers, which all have the same input, and the maxout returns the elementwise maximium of the internal layers' outputs.
Maxout over linear dense layers satisfies the univeral approximation theorem.
Reference: Ian J. Goodfellow, David Warde-Farley, Mehdi Mirza, Aaron Courville, and Yoshua Bengio.
  1. Maxout networks.
In Proceedings of the 30th International Conference on International Conference on Machine Learning - Volume 28 (ICML'13), Sanjoy Dasgupta and David McAllester (Eds.), Vol. 28. JMLR.org III-1319-III-1327. https://arxiv.org/pdf/1302.4389.pdf
source
Flux.SkipConnection — Type.
SkipConnection(layers, connection)
Creates a Skip Connection, of a layer or Chain of consecutive layers plus a shortcut connection. The connection function will combine the result of the layers with the original input, to give the final output.
The simplest 'ResNet'-type connection is just SkipConnection(layer, +), and requires the output of the layers to be the same shape as the input. Here is a more complicated example:
m = Conv((3,3), 4=>7, pad=(1,1))
 x = ones(5,5,4,10);
 size(m(x)) == (5, 5, 7, 10)
 
 sm = SkipConnection(m, (mx, x) -> cat(mx, x, dims=3))
-size(sm(x)) == (5, 5, 11, 10)
source
Activation Functions
Non-linearities that go between layers of your model. Most of these functions are defined in NNlib but are available by default in Flux.
Note that, unless otherwise stated, activation functions operate on scalars. To apply them to an array you can call σ.(xs), relu.(xs) and so on.
NNlib.σ — Function.
σ(x) = 1 / (1 + exp(-x))
Classic sigmoid activation function.
NNlib.relu — Function.
relu(x) = max(0, x)
Rectified Linear Unit activation function.
NNlib.leakyrelu — Function.
leakyrelu(x) = max(0.01x, x)
Leaky Rectified Linear Unit activation function. You can also specify the coefficient explicitly, e.g. leakyrelu(x, 0.01).
NNlib.elu — Function.
elu(x, α = 1) =
-  x > 0 ? x : α * (exp(x) - 1)
Exponential Linear Unit activation function. See Fast and Accurate Deep Network Learning by Exponential Linear Units. You can also specify the coefficient explicitly, e.g. elu(x, 1).
NNlib.swish — Function.
swish(x) = x * σ(x)
Self-gated activation function. See Swish: a Self-Gated Activation Function.
Normalisation & Regularisation
These layers don't affect the structure of the network but may improve training times or reduce overfitting.
Flux.BatchNorm — Type.
BatchNorm(channels::Integer, σ = identity;
+size(sm(x)) == (5, 5, 11, 10)
source
Normalisation & Regularisation
These layers don't affect the structure of the network but may improve training times or reduce overfitting.
Flux.BatchNorm — Type.
BatchNorm(channels::Integer, σ = identity;
           initβ = zeros, initγ = ones,
-          ϵ = 1e-8, momentum = .1)
Batch Normalization layer. The channels input should be the size of the channel dimension in your data (see below).
Given an array with N dimensions, call the N-1th the channel dimension. (For a batch of feature vectors this is just the data dimension, for WHCN images it's the usual channel dimension.)
BatchNorm computes the mean and variance for each each W×H×1×N slice and shifts them to have a new mean and variance (corresponding to the learnable, per-channel bias and scale parameters).
See Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift.
Example:
m = Chain(
+          ϵ = 1e-8, momentum = .1)
Batch Normalization layer. The channels input should be the size of the channel dimension in your data (see below).
Given an array with N dimensions, call the N-1th the channel dimension. (For a batch of feature vectors this is just the data dimension, for WHCN images it's the usual channel dimension.)
BatchNorm computes the mean and variance for each each W×H×1×N slice and shifts them to have a new mean and variance (corresponding to the learnable, per-channel bias and scale parameters).
Use testmode! during inference.
See Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift.
Example:
m = Chain(
   Dense(28^2, 64),
   BatchNorm(64, relu),
   Dense(64, 10),
   BatchNorm(10),
-  softmax)
source
Flux.Dropout — Type.
Dropout(p, dims = :)
A Dropout layer. For each input, either sets that input to 0 (with probability p) or scales it by 1/(1-p). The dims argument is to specified the unbroadcasted  dimensions, i.e. dims=1 does dropout along columns and dims=2 along rows. This is  used as a regularisation, i.e. it reduces overfitting during training. see also dropout.
source
Flux.AlphaDropout — Type.
AlphaDropout(p)
A dropout layer. It is used in Self-Normalizing Neural Networks. (https://papers.nips.cc/paper/6698-self-normalizing-neural-networks.pdf) The AlphaDropout layer ensures that mean and variance of activations remains the same as before.
source
Flux.LayerNorm — Type.
LayerNorm(h::Integer)
A normalisation layer designed to be used with recurrent hidden states of size h. Normalises the mean/stddev of each input before applying a per-neuron gain/bias.
source
Flux.GroupNorm — Type.
Group Normalization. This layer can outperform Batch-Normalization and Instance-Normalization.
GroupNorm(chs::Integer, G::Integer, λ = identity;
+  softmax)
source
Flux.Dropout — Type.
Dropout(p, dims = :)
A Dropout layer. In the forward pass, applies the dropout function on the input.
Does nothing to the input once testmode! is false.
source
Flux.dropout — Function.
dropout(p, dims = :)
Dropout function. For each input, either sets that input to 0 (with probability p) or scales it by 1/(1-p). The dims argument is to specify the unbroadcasted dimensions, i.e. dims=1 does dropout along columns and dims=2 along rows. This is used as a regularisation, i.e. it reduces overfitting during training. 
See also Dropout.
source
Flux.AlphaDropout — Type.
AlphaDropout(p)
A dropout layer. It is used in Self-Normalizing Neural Networks. (https://papers.nips.cc/paper/6698-self-normalizing-neural-networks.pdf) The AlphaDropout layer ensures that mean and variance of activations remains the same as before.
Does nothing to the input once testmode! is false.
source
Flux.LayerNorm — Type.
LayerNorm(h::Integer)
A normalisation layer designed to be used with recurrent hidden states of size h. Normalises the mean/stddev of each input before applying a per-neuron gain/bias.
source
Flux.GroupNorm — Type.
Group Normalization. This layer can outperform Batch-Normalization and Instance-Normalization.
GroupNorm(chs::Integer, G::Integer, λ = identity;
           initβ = (i) -> zeros(Float32, i), initγ = (i) -> ones(Float32, i),
-          ϵ = 1f-5, momentum = 0.1f0)
$chs$ is the number of channels, the channel dimension of your input. For an array of N dimensions, the (N-1)th index is the channel dimension.
$G$ is the number of groups along which the statistics would be computed. The number of channels must be an integer multiple of the number of groups.
Example:
m = Chain(Conv((3,3), 1=>32, leakyrelu;pad = 1),
-          GroupNorm(32,16)) # 32 channels, 16 groups (G = 16), thus 2 channels per group used
Link : https://arxiv.org/pdf/1803.08494.pdf
source
Cost Functions
Missing docstring.
Missing docstring for mse. Check Documenter's build log for details.
Missing docstring.
Missing docstring for crossentropy. Check Documenter's build log for details.
Missing docstring.
Missing docstring for logitcrossentropy. Check Documenter's build log for details.
Missing docstring.
Missing docstring for binarycrossentropy. Check Documenter's build log for details.
Missing docstring.
Missing docstring for logitbinarycrossentropy. Check Documenter's build log for details.
Missing docstring.
Missing docstring for kldivergence. Check Documenter's build log for details.
Missing docstring.
Missing docstring for poisson. Check Documenter's build log for details.
Missing docstring.
Missing docstring for hinge. Check Documenter's build log for details.

+          ϵ = 1f-5, momentum = 0.1f0)

$chs$ is the number of channels, the channel dimension of your input. For an array of N dimensions, the (N-1)th index is the channel dimension.

$G$ is the number of groups along which the statistics would be computed. The number of channels must be an integer multiple of the number of groups.

Use testmode! during inference.

Example:

m = Chain(Conv((3,3), 1=>32, leakyrelu;pad = 1),
+          GroupNorm(32,16)) # 32 channels, 16 groups (G = 16), thus 2 channels per group used

Link : https://arxiv.org/pdf/1803.08494.pdf

source

Testmode

Many normalisation layers behave differently under training and inference (testing). By default, Flux will automatically determine when a layer evaluation is part of training or inference. Still, depending on your use case, it may be helpful to manually specify when these layers should be treated as being trained or not. For this, Flux provides testmode!. When called on a model (e.g. a layer or chain of layers), this function will place the model into the mode specified.

Flux.testmode! — Function.
testmode!(m, mode = true)

Set a layer or model's test mode (see below). Using :auto mode will treat any gradient computation as training.

Note: if you manually set a model into test mode, you need to manually place it back into train mode during training phase.

Possible values include:

  • false for training
  • true for testing
  • :auto or nothing for Flux to detect the mode automatically
source
Flux.trainmode! — Function.
trainmode!(m, mode = true)

Set a layer of model's train mode (see below). Symmetric to testmode! (i.e. `trainmode!(m, mode) == testmode!(m, !mode)).

Note: if you manually set a model into train mode, you need to manually place it into test mode during testing phase.

Possible values include:

  • true for training
  • false for testing
  • :auto or nothing for Flux to detect the mode automatically
source

Cost Functions

Flux.mse — Function.
mse(ŷ, y)

Return the mean squared error sum((ŷ .- y).^2) / length(y).

source
Flux.crossentropy — Function.
crossentropy(ŷ, y; weight=1)

Return the crossentropy computed as -sum(y .* log.(ŷ) .* weight) / size(y, 2).

See also logitcrossentropy, binarycrossentropy.

source
Flux.logitcrossentropy — Function.
logitcrossentropy(ŷ, y; weight=1)

Return the crossentropy computed after a softmax operation:

-sum(y .* logsoftmax(ŷ) .* weight) / size(y, 2)

See also crossentropy, binarycrossentropy.

source
Flux.binarycrossentropy — Function.
binarycrossentropy(ŷ, y; ϵ=eps(ŷ))

Return -y*log(ŷ + ϵ) - (1-y)*log(1-ŷ + ϵ). The ϵ term provides numerical stability.

Typically, the prediction ŷ is given by the output of a sigmoid activation.

source
Flux.logitbinarycrossentropy — Function.
logitbinarycrossentropy(ŷ, y)

logitbinarycrossentropy(ŷ, y) is mathematically equivalent to binarycrossentropy(σ(ŷ), y) but it is more numerically stable.

See also binarycrossentropy, sigmoid, logsigmoid.

source
Flux.kldivergence — Function.
kldivergence(ŷ, y)

KLDivergence is a measure of how much one probability distribution is different from the other. It is always non-negative and zero only when both the distributions are equal everywhere. KL Divergence.

source
Flux.poisson — Function.
poisson(ŷ, y)

Poisson loss function is a measure of how the predicted distribution diverges from the expected distribution. Poisson Loss.

source
Flux.hinge — Function.
hinge(ŷ, y)

Measures the loss given the prediction ŷ and true labels y (containing 1 or -1). Hinge Loss.

source
diff --git a/dev/models/nnlib/index.html b/dev/models/nnlib/index.html new file mode 100644 index 00000000..ce4d529c --- /dev/null +++ b/dev/models/nnlib/index.html @@ -0,0 +1,23 @@ + +NNlib · Flux
NNlib

NNlib

Flux re-exports all of the functions exported by the NNlib package.

Activation Functions

Non-linearities that go between layers of your model. Note that, unless otherwise stated, activation functions operate on scalars. To apply them to an array you can call σ.(xs), relu.(xs) and so on.

NNlib.elu — Function.
elu(x, α = 1) =
+  x > 0 ? x : α * (exp(x) - 1)

Exponential Linear Unit activation function. See Fast and Accurate Deep Network Learning by Exponential Linear Units. You can also specify the coefficient explicitly, e.g. elu(x, 1).

NNlib.gelu — Function.
gelu(x) = 0.5x*(1 + tanh(√(2/π)*(x + 0.044715x^3)))

Gaussian Error Linear Unit activation function.

NNlib.leakyrelu — Function.
leakyrelu(x) = max(0.01x, x)

Leaky Rectified Linear Unit activation function. You can also specify the coefficient explicitly, e.g. leakyrelu(x, 0.01).

NNlib.logcosh — Function.
logcosh(x)

Return log(cosh(x)) which is computed in a numerically stable way.

NNlib.logsigmoid — Function.
logσ(x)

Return log(σ(x)) which is computed in a numerically stable way.

julia> logσ(0)
+-0.6931471805599453
+julia> logσ.([-100, -10, 100])
+3-element Array{Float64,1}:
+ -100.0
+  -10.000045398899218
+   -3.720075976020836e-44
NNlib.sigmoid — Function.
σ(x) = 1 / (1 + exp(-x))

Classic sigmoid activation function.

NNlib.relu — Function.
relu(x) = max(0, x)

Rectified Linear Unit activation function.

NNlib.selu — Function.
selu(x) = λ * (x ≥ 0 ? x : α * (exp(x) - 1))
+
+λ ≈ 1.0507
+α ≈ 1.6733

Scaled exponential linear units. See Self-Normalizing Neural Networks.

NNlib.softplus — Function.
softplus(x) = log(exp(x) + 1)

See Deep Sparse Rectifier Neural Networks.

NNlib.softsign — Function.
softsign(x) = x / (1 + |x|)

See Quadratic Polynomials Learn Better Image Features.

NNlib.swish — Function.
swish(x) = x * σ(x)

Self-gated activation function. See Swish: a Self-Gated Activation Function.

Softmax

NNlib.softmax — Function.
softmax(xs) = exp.(xs) ./ sum(exp.(xs))

Softmax takes log-probabilities (any real vector) and returns a probability distribution that sums to 1.

If given a matrix it will by default (dims=1) treat it as a batch of vectors, with each column independent. Keyword dims=2 will instead treat rows independently, etc.

julia> softmax([1,2,3.])
+3-element Array{Float64,1}:
+  0.0900306
+  0.244728
+  0.665241
NNlib.logsoftmax — Function.
logsoftmax(xs) = log.(exp.(xs) ./ sum(exp.(xs)))

Computes the log of softmax in a more numerically stable way than directly taking log.(softmax(xs)). Commonly used in computing cross entropy loss.

Pooling

Missing docstring.

Missing docstring for NNlib.maxpool. Check Documenter's build log for details.

Missing docstring.

Missing docstring for NNlib.meanpool. Check Documenter's build log for details.

Convolution

Missing docstring.

Missing docstring for NNlib.conv. Check Documenter's build log for details.

Missing docstring.

Missing docstring for NNlib.depthwiseconv. Check Documenter's build log for details.

diff --git a/dev/models/recurrence/index.html b/dev/models/recurrence/index.html index cbb8250e..beb11484 100644 --- a/dev/models/recurrence/index.html +++ b/dev/models/recurrence/index.html @@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) ga('create', 'UA-36890222-9', 'auto'); ga('send', 'pageview'); -
Recurrence

Recurrent Models

Recurrent Cells

In the simple feedforward case, our model m is a simple function from various inputs xᵢ to predictions yᵢ. (For example, each x might be an MNIST digit and each y a digit label.) Each prediction is completely independent of any others, and using the same x will always produce the same y.

y₁ = f(x₁)
+
Recurrence
Recurrent Models
Recurrent Cells
In the simple feedforward case, our model m is a simple function from various inputs xᵢ to predictions yᵢ. (For example, each x might be an MNIST digit and each y a digit label.) Each prediction is completely independent of any others, and using the same x will always produce the same y.
y₁ = f(x₁)
 y₂ = f(x₂)
 y₃ = f(x₃)
 # ...
Recurrent networks introduce a hidden state that gets carried over each time we run the model. The model now takes the old h as an input, and produces a new h as output, each time we run it.
h = # ... initial state ...
diff --git a/dev/models/regularisation/index.html b/dev/models/regularisation/index.html
index 76400dd9..882bc48b 100644
--- a/dev/models/regularisation/index.html
+++ b/dev/models/regularisation/index.html
@@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 
 ga('create', 'UA-36890222-9', 'auto');
 ga('send', 'pageview');
-
Regularisation
Regularisation
Applying regularisation to model parameters is straightforward. We just need to apply an appropriate regulariser, such as norm, to each model parameter and add the result to the overall loss.
For example, say we have a simple regression.
using Flux: crossentropy
+
Regularisation
Regularisation
Applying regularisation to model parameters is straightforward. We just need to apply an appropriate regulariser, such as norm, to each model parameter and add the result to the overall loss.
For example, say we have a simple regression.
using Flux: crossentropy
 m = Dense(10, 5)
 loss(x, y) = crossentropy(softmax(m(x)), y)
We can regularise this by taking the (L2) norm of the parameters, m.W and m.b.
using LinearAlgebra
 
@@ -17,7 +17,7 @@ loss(x, y) = crossentropy(softmax(m(x)), y) + penalty()
When work
  param([0.0, 0.0, 0.0, 0.0, 0.0])
 
 julia> sum(norm, params(m))
-26.01749952921026 (tracked)
Here's a larger example with a multi-layer perceptron.
m = Chain(
+26.01749952921026
Here's a larger example with a multi-layer perceptron.
m = Chain(
   Dense(28^2, 128, relu),
   Dense(128, 32, relu),
   Dense(32, 10), softmax)
@@ -26,7 +26,7 @@ loss(x, y) = crossentropy(m(x), y) + sum(norm, params(m))
 
 loss(rand(28^2), rand(10))
One can also easily add per-layer regularisation via the activations function:
julia> using Flux: activations
 
-julia> c = Chain(Dense(10,5,σ),Dense(5,2),softmax)
+julia> c = Chain(Dense(10, 5, σ), Dense(5, 2), softmax)
 Chain(Dense(10, 5, σ), Dense(5, 2), softmax)
 
 julia> activations(c, rand(10))
diff --git a/dev/performance/index.html b/dev/performance/index.html
index 6fed8815..1bd44661 100644
--- a/dev/performance/index.html
+++ b/dev/performance/index.html
@@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 
 ga('create', 'UA-36890222-9', 'auto');
 ga('send', 'pageview');
-
Performance Tips
Performance Tips
All the usual Julia performance tips apply. As always profiling your code is generally a useful way of finding bottlenecks. Below follow some Flux specific tips/reminders.
Don't use more precision than you need.
Flux works great with all kinds of number types. But often you do not need to be working with say Float64 (let alone BigFloat). Switching to Float32 can give you a significant speed up, not because the operations are faster, but because the memory usage is halved. Which means allocations occur much faster. And you use less memory.
Make sure your activation and loss functions preserve the type of their inputs
Not only should your activation and loss functions be type-stable, they should also preserve the type of their inputs.
A very artificial example using an activation function like
    my_tanh(x) = Float64(tanh(x))
will result in performance on Float32 input orders of magnitude slower than the normal tanh would, because it results in having to use slow mixed type multiplication in the dense layers. Similar situations can occur in the loss function during backpropagation.
Which means if you change your data say from Float64 to Float32 (which should give a speedup: see above), you will see a large slow-down
This can occur sneakily, because you can cause type-promotion by interacting with a numeric literals. E.g. the following will have run into the same problem as above:
    leaky_tanh(x) = 0.01x + tanh(x)
While one could change your activation function (e.g. to use 0.01f0x) to avoid this when ever your inputs change, the idiomatic (and safe way) is to use oftype.
    leaky_tanh(x) = oftype(x/1, 0.01)x + tanh(x)
Evaluate batches as Matrices of features, rather than sequences of Vector features
While it can sometimes be tempting to process your observations (feature vectors) one at a time e.g.
function loss_total(xs::AbstractVector{<:Vector}, ys::AbstractVector{<:Vector})
+
Performance Tips
Performance Tips
All the usual Julia performance tips apply. As always profiling your code is generally a useful way of finding bottlenecks. Below follow some Flux specific tips/reminders.
Don't use more precision than you need.
Flux works great with all kinds of number types. But often you do not need to be working with say Float64 (let alone BigFloat). Switching to Float32 can give you a significant speed up, not because the operations are faster, but because the memory usage is halved. Which means allocations occur much faster. And you use less memory.
Make sure your activation and loss functions preserve the type of their inputs
Not only should your activation and loss functions be type-stable, they should also preserve the type of their inputs.
A very artificial example using an activation function like
    my_tanh(x) = Float64(tanh(x))
will result in performance on Float32 input orders of magnitude slower than the normal tanh would, because it results in having to use slow mixed type multiplication in the dense layers. Similar situations can occur in the loss function during backpropagation.
Which means if you change your data say from Float64 to Float32 (which should give a speedup: see above), you will see a large slow-down
This can occur sneakily, because you can cause type-promotion by interacting with a numeric literals. E.g. the following will have run into the same problem as above:
    leaky_tanh(x) = 0.01x + tanh(x)
While one could change your activation function (e.g. to use 0.01f0x) to avoid this when ever your inputs change, the idiomatic (and safe way) is to use oftype.
    leaky_tanh(x) = oftype(x/1, 0.01)x + tanh(x)
Evaluate batches as Matrices of features, rather than sequences of Vector features
While it can sometimes be tempting to process your observations (feature vectors) one at a time e.g.
function loss_total(xs::AbstractVector{<:Vector}, ys::AbstractVector{<:Vector})
     sum(zip(xs, ys)) do (x, y_target)
         y_pred = model(x) #  evaluate the model
         return loss(y_pred, y_target)
@@ -17,4 +17,4 @@ y_batch = reduce(hcat, ys)
 function loss_total(x_batch::Matrix, y_batch::Matrix)
     y_preds = model(x_batch)
     sum(loss.(y_preds, y_batch))
-end
When doing this kind of concatenation use reduce(hcat, xs) rather than hcat(xs...). This will avoid the splatting penalty, and will hit the optimised reduce method.

+end
When doing this kind of concatenation use reduce(hcat, xs) rather than hcat(xs...). This will avoid the splatting penalty, and will hit the optimised reduce method.

diff --git a/dev/saving/index.html b/dev/saving/index.html
index 14b87ed5..ec74f405 100644
--- a/dev/saving/index.html
+++ b/dev/saving/index.html
@@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 
 ga('create', 'UA-36890222-9', 'auto');
 ga('send', 'pageview');
-
Saving & Loading
Saving and Loading Models
You may wish to save models so that they can be loaded and run in a later session. The easiest way to do this is via BSON.jl.
Save a model:
julia> using Flux
+
Saving & Loading
Saving and Loading Models
You may wish to save models so that they can be loaded and run in a later session. The easiest way to do this is via BSON.jl.
Save a model:
julia> using Flux
 
 julia> model = Chain(Dense(10,5,relu),Dense(5,2),softmax)
 Chain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)
@@ -47,4 +47,4 @@ evalcb = throttle(30) do
   # Show loss
   @save "model-checkpoint.bson" model
 end
This will update the "model-checkpoint.bson" file every thirty seconds.
You can get more advanced by saving a series of models throughout training, for example
@save "model-$(now()).bson" model
will produce a series of models like "model-2018-03-06T02:57:10.41.bson". You could also store the current test set loss, so that it's easy to (for example) revert to an older copy of the model if it starts to overfit.
@save "model-$(now()).bson" model loss = testloss()
You can even store optimiser state alongside the model, to resume training exactly where you left off.
opt = ADAM()
-@save "model-$(now()).bson" model opt

+@save "model-$(now()).bson" model opt

diff --git a/dev/search/index.html b/dev/search/index.html
index ac5ac983..4ffaf9d4 100644
--- a/dev/search/index.html
+++ b/dev/search/index.html
@@ -6,4 +6,4 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 
 ga('create', 'UA-36890222-9', 'auto');
 ga('send', 'pageview');
-
Search
Search
Number of results: loading...
    
+
    Search
    Search
    Number of results: loading...
      
diff --git a/dev/search_index.js b/dev/search_index.js
index ee5df217..26e12875 100644
--- a/dev/search_index.js
+++ b/dev/search_index.js
@@ -1,3 +1,3 @@
 var documenterSearchIndex = {"docs":
-[{"location":"data/onehot/#One-Hot-Encoding-1","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"","category":"section"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"It's common to encode categorical variables (like true, false or cat, dog) in \"one-of-k\" or \"one-hot\" form. Flux provides the onehot function to make this easy.","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"julia> using Flux: onehot, onecold\n\njulia> onehot(:b, [:a, :b, :c])\n3-element Flux.OneHotVector:\n false\n  true\n false\n\njulia> onehot(:c, [:a, :b, :c])\n3-element Flux.OneHotVector:\n false\n false\n  true","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"The inverse is onecold (which can take a general probability distribution, as well as just booleans).","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"julia> onecold(ans, [:a, :b, :c])\n:c\n\njulia> onecold([true, false, false], [:a, :b, :c])\n:a\n\njulia> onecold([0.3, 0.2, 0.5], [:a, :b, :c])\n:c","category":"page"},{"location":"data/onehot/#Batches-1","page":"One-Hot Encoding","title":"Batches","text":"","category":"section"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"onehotbatch creates a batch (matrix) of one-hot vectors, and onecold treats matrices as batches.","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"julia> using Flux: onehotbatch\n\njulia> onehotbatch([:b, :a, :b], [:a, :b, :c])\n3×3 Flux.OneHotMatrix:\n false   true  false\n  true  false   true\n false  false  false\n\njulia> onecold(ans, [:a, :b, :c])\n3-element Array{Symbol,1}:\n  :b\n  :a\n  :b","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"Note that these operations returned OneHotVector and OneHotMatrix rather than Arrays. OneHotVectors behave like normal vectors but avoid any unnecessary cost compared to using an integer index directly. For example, multiplying a matrix with a one-hot vector simply slices out the relevant row of the matrix under the hood.","category":"page"},{"location":"models/regularisation/#Regularisation-1","page":"Regularisation","title":"Regularisation","text":"","category":"section"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"Applying regularisation to model parameters is straightforward. We just need to apply an appropriate regulariser, such as norm, to each model parameter and add the result to the overall loss.","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"For example, say we have a simple regression.","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"using Flux: crossentropy\nm = Dense(10, 5)\nloss(x, y) = crossentropy(softmax(m(x)), y)","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"We can regularise this by taking the (L2) norm of the parameters, m.W and m.b.","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"using LinearAlgebra\n\npenalty() = norm(m.W) + norm(m.b)\nloss(x, y) = crossentropy(softmax(m(x)), y) + penalty()","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"When working with layers, Flux provides the params function to grab all parameters at once. We can easily penalise everything with sum(norm, params).","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"julia> params(m)\n2-element Array{Any,1}:\n param([0.355408 0.533092; … 0.430459 0.171498])\n param([0.0, 0.0, 0.0, 0.0, 0.0])\n\njulia> sum(norm, params(m))\n26.01749952921026 (tracked)","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"Here's a larger example with a multi-layer perceptron.","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"m = Chain(\n  Dense(28^2, 128, relu),\n  Dense(128, 32, relu),\n  Dense(32, 10), softmax)\n\nloss(x, y) = crossentropy(m(x), y) + sum(norm, params(m))\n\nloss(rand(28^2), rand(10))","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"One can also easily add per-layer regularisation via the activations function:","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"julia> using Flux: activations\n\njulia> c = Chain(Dense(10,5,σ),Dense(5,2),softmax)\nChain(Dense(10, 5, σ), Dense(5, 2), softmax)\n\njulia> activations(c, rand(10))\n3-element Array{Any,1}:\n Float32[0.84682214, 0.6704139, 0.42177814, 0.257832, 0.36255655]\n Float32[0.1501253, 0.073269576]                                 \n Float32[0.5192045, 0.48079553]                                  \n\njulia> sum(norm, ans)\n2.1166067f0","category":"page"},{"location":"performance/#Performance-Tips-1","page":"Performance Tips","title":"Performance Tips","text":"","category":"section"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"All the usual Julia performance tips apply. As always profiling your code is generally a useful way of finding bottlenecks. Below follow some Flux specific tips/reminders.","category":"page"},{"location":"performance/#Don't-use-more-precision-than-you-need.-1","page":"Performance Tips","title":"Don't use more precision than you need.","text":"","category":"section"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"Flux works great with all kinds of number types. But often you do not need to be working with say Float64 (let alone BigFloat). Switching to Float32 can give you a significant speed up, not because the operations are faster, but because the memory usage is halved. Which means allocations occur much faster. And you use less memory.","category":"page"},{"location":"performance/#Make-sure-your-activation-and-loss-functions-preserve-the-type-of-their-inputs-1","page":"Performance Tips","title":"Make sure your activation and loss functions preserve the type of their inputs","text":"","category":"section"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"Not only should your activation and loss functions be type-stable, they should also preserve the type of their inputs.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"A very artificial example using an activation function like","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"    my_tanh(x) = Float64(tanh(x))","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"will result in performance on Float32 input orders of magnitude slower than the normal tanh would, because it results in having to use slow mixed type multiplication in the dense layers. Similar situations can occur in the loss function during backpropagation.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"Which means if you change your data say from Float64 to Float32 (which should give a speedup: see above), you will see a large slow-down","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"This can occur sneakily, because you can cause type-promotion by interacting with a numeric literals. E.g. the following will have run into the same problem as above:","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"    leaky_tanh(x) = 0.01x + tanh(x)","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"While one could change your activation function (e.g. to use 0.01f0x) to avoid this when ever your inputs change, the idiomatic (and safe way) is to use oftype.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"    leaky_tanh(x) = oftype(x/1, 0.01)x + tanh(x)","category":"page"},{"location":"performance/#Evaluate-batches-as-Matrices-of-features,-rather-than-sequences-of-Vector-features-1","page":"Performance Tips","title":"Evaluate batches as Matrices of features, rather than sequences of Vector features","text":"","category":"section"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"While it can sometimes be tempting to process your observations (feature vectors) one at a time e.g.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"function loss_total(xs::AbstractVector{<:Vector}, ys::AbstractVector{<:Vector})\n    sum(zip(xs, ys)) do (x, y_target)\n        y_pred = model(x) #  evaluate the model\n        return loss(y_pred, y_target)\n    end\nend","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"It is much faster to concatenate them into a matrix, as this will hit BLAS matrix-matrix multiplication, which is much faster than the equivalent sequence of matrix-vector multiplications. The improvement is enough that it is worthwhile allocating new memory to store them contiguously.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"x_batch = reduce(hcat, xs)\ny_batch = reduce(hcat, ys)\n...\nfunction loss_total(x_batch::Matrix, y_batch::Matrix)\n    y_preds = model(x_batch)\n    sum(loss.(y_preds, y_batch))\nend","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"When doing this kind of concatenation use reduce(hcat, xs) rather than hcat(xs...). This will avoid the splatting penalty, and will hit the optimised reduce method.","category":"page"},{"location":"saving/#Saving-and-Loading-Models-1","page":"Saving & Loading","title":"Saving and Loading Models","text":"","category":"section"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"You may wish to save models so that they can be loaded and run in a later session. The easiest way to do this is via BSON.jl.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"Save a model:","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"julia> using Flux\n\njulia> model = Chain(Dense(10,5,relu),Dense(5,2),softmax)\nChain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)\n\njulia> using BSON: @save\n\njulia> @save \"mymodel.bson\" model","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"Load it again:","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"julia> using Flux\n\njulia> using BSON: @load\n\njulia> @load \"mymodel.bson\" model\n\njulia> model\nChain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"Models are just normal Julia structs, so it's fine to use any Julia storage format for this purpose. BSON.jl is particularly well supported and most likely to be forwards compatible (that is, models saved now will load in future versions of Flux).","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"note: Note\nIf a saved model's weights are stored on the GPU, the model will not load later on if there is no GPU support available. It's best to move your model to the CPU with cpu(model) before saving it.","category":"page"},{"location":"saving/#Saving-Model-Weights-1","page":"Saving & Loading","title":"Saving Model Weights","text":"","category":"section"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"In some cases it may be useful to save only the model parameters themselves, and rebuild the model architecture in your code. You can use params(model) to get model parameters. You can also use data.(params) to remove tracking.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"julia> using Flux\n\njulia> model = Chain(Dense(10,5,relu),Dense(5,2),softmax)\nChain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)\n\njulia> weights = params(model);\n\njulia> using BSON: @save\n\njulia> @save \"mymodel.bson\" weights","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"You can easily load parameters back into a model with Flux.loadparams!.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"julia> using Flux\n\njulia> model = Chain(Dense(10,5,relu),Dense(5,2),softmax)\nChain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)\n\njulia> using BSON: @load\n\njulia> @load \"mymodel.bson\" weights\n\njulia> Flux.loadparams!(model, weights)","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"The new model we created will now be identical to the one we saved parameters for.","category":"page"},{"location":"saving/#Checkpointing-1","page":"Saving & Loading","title":"Checkpointing","text":"","category":"section"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"In longer training runs it's a good idea to periodically save your model, so that you can resume if training is interrupted (for example, if there's a power cut). You can do this by saving the model in the callback provided to train!.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"using Flux: throttle\nusing BSON: @save\n\nm = Chain(Dense(10,5,relu),Dense(5,2),softmax)\n\nevalcb = throttle(30) do\n  # Show loss\n  @save \"model-checkpoint.bson\" model\nend","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"This will update the \"model-checkpoint.bson\" file every thirty seconds.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"You can get more advanced by saving a series of models throughout training, for example","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"@save \"model-$(now()).bson\" model","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"will produce a series of models like \"model-2018-03-06T02:57:10.41.bson\". You could also store the current test set loss, so that it's easy to (for example) revert to an older copy of the model if it starts to overfit.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"@save \"model-$(now()).bson\" model loss = testloss()","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"You can even store optimiser state alongside the model, to resume training exactly where you left off.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"opt = ADAM()\n@save \"model-$(now()).bson\" model opt","category":"page"},{"location":"models/layers/#Basic-Layers-1","page":"Model Reference","title":"Basic Layers","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"These core layers form the foundation of almost all neural networks.","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Chain\nDense","category":"page"},{"location":"models/layers/#Flux.Chain","page":"Model Reference","title":"Flux.Chain","text":"Chain(layers...)\n\nChain multiple layers / functions together, so that they are called in sequence on a given input.\n\nm = Chain(x -> x^2, x -> x+1)\nm(5) == 26\n\nm = Chain(Dense(10, 5), Dense(5, 2))\nx = rand(10)\nm(x) == m[2](m[1](x))\n\nChain also supports indexing and slicing, e.g. m[2] or m[1:end-1]. m[1:3](x) will calculate the output of the first three layers.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.Dense","page":"Model Reference","title":"Flux.Dense","text":"Dense(in::Integer, out::Integer, σ = identity)\n\nCreates a traditional Dense layer with parameters W and b.\n\ny = σ.(W * x .+ b)\n\nThe input x must be a vector of length in, or a batch of vectors represented as an in × N matrix. The out y will be a vector or batch of length out.\n\njulia> d = Dense(5, 2)\nDense(5, 2)\n\njulia> d(rand(5))\nTracked 2-element Array{Float64,1}:\n  0.00257447\n  -0.00449443\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Convolution-and-Pooling-Layers-1","page":"Model Reference","title":"Convolution and Pooling Layers","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"These layers are used to build convolutional neural networks (CNNs).","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Conv\nMaxPool\nMeanPool\nDepthwiseConv\nConvTranspose\nCrossCor","category":"page"},{"location":"models/layers/#Flux.Conv","page":"Model Reference","title":"Flux.Conv","text":"Conv(size, in=>out)\nConv(size, in=>out, relu)\n\nStandard convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.\n\nExample: Applying Conv layer to a 1-channel input using a 2x2 window size,          giving us a 16-channel output. Output is activated with ReLU.\n\nsize = (2,2)\nin = 1\nout = 16\nConv((2, 2), 1=>16, relu)\n\nData should be stored in WHCN order (width, height, # channels, # batches). In other words, a 100×100 RGB image would be a 100×100×3×1 array, and a batch of 50 would be a 100×100×3×50 array.\n\nTakes the keyword arguments pad, stride and dilation.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.MaxPool","page":"Model Reference","title":"Flux.MaxPool","text":"MaxPool(k)\n\nMax pooling layer. k stands for the size of the window for each dimension of the input.\n\nTakes the keyword arguments pad and stride.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.MeanPool","page":"Model Reference","title":"Flux.MeanPool","text":"MeanPool(k)\n\nMean pooling layer. k stands for the size of the window for each dimension of the input.\n\nTakes the keyword arguments pad and stride.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.DepthwiseConv","page":"Model Reference","title":"Flux.DepthwiseConv","text":"DepthwiseConv(size, in=>out)\nDepthwiseConv(size, in=>out, relu)\n\nDepthwise convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively. Note that out must be an integer multiple of in.\n\nData should be stored in WHCN order. In other words, a 100×100 RGB image would be a 100×100×3 array, and a batch of 50 would be a 100×100×3×50 array.\n\nTakes the keyword arguments pad, stride and dilation.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.ConvTranspose","page":"Model Reference","title":"Flux.ConvTranspose","text":"ConvTranspose(size, in=>out)\nConvTranspose(size, in=>out, relu)\n\nStandard convolutional transpose layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.\n\nData should be stored in WHCN order. In other words, a 100×100 RGB image would be a 100×100×3 array, and a batch of 50 would be a 100×100×3×50 array.\n\nTakes the keyword arguments pad, stride and dilation.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.CrossCor","page":"Model Reference","title":"Flux.CrossCor","text":"CrossCor(size, in=>out)\nCrossCor(size, in=>out, relu)\n\nStandard cross convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.\n\nExample: Applying CrossCor layer to a 1-channel input using a 2x2 window size,          giving us a 16-channel output. Output is activated with ReLU.\n\nsize = (2,2)\nin = 1\nout = 16\nCrossCor((2, 2), 1=>16, relu)\n\nData should be stored in WHCN order (width, height, # channels, # batches). In other words, a 100×100 RGB image would be a 100×100×3×1 array, and a batch of 50 would be a 100×100×3×50 array.\n\nTakes the keyword arguments pad, stride and dilation.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Recurrent-Layers-1","page":"Model Reference","title":"Recurrent Layers","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Much like the core layers above, but can be used to process sequence data (as well as other kinds of structured data).","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"RNN\nLSTM\nGRU\nFlux.Recur","category":"page"},{"location":"models/layers/#Flux.RNN","page":"Model Reference","title":"Flux.RNN","text":"RNN(in::Integer, out::Integer, σ = tanh)\n\nThe most basic recurrent layer; essentially acts as a Dense layer, but with the output fed back into the input each time step.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.LSTM","page":"Model Reference","title":"Flux.LSTM","text":"LSTM(in::Integer, out::Integer)\n\nLong Short Term Memory recurrent layer. Behaves like an RNN but generally exhibits a longer memory span over sequences.\n\nSee this article for a good overview of the internals.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.GRU","page":"Model Reference","title":"Flux.GRU","text":"GRU(in::Integer, out::Integer)\n\nGated Recurrent Unit layer. Behaves like an RNN but generally exhibits a longer memory span over sequences.\n\nSee this article for a good overview of the internals.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.Recur","page":"Model Reference","title":"Flux.Recur","text":"Recur(cell)\n\nRecur takes a recurrent cell and makes it stateful, managing the hidden state in the background. cell should be a model of the form:\n\nh, y = cell(h, x...)\n\nFor example, here's a recurrent network that keeps a running total of its inputs.\n\naccum(h, x) = (h+x, x)\nrnn = Flux.Recur(accum, 0)\nrnn(2) # 2\nrnn(3) # 3\nrnn.state # 5\nrnn.(1:10) # apply to a sequence\nrnn.state # 60\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Other-General-Purpose-Layers-1","page":"Model Reference","title":"Other General Purpose Layers","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"These are marginally more obscure than the Basic Layers. But in contrast to the layers described in the other sections are not readily grouped around a particular purpose (e.g. CNNs or RNNs).","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Maxout\nSkipConnection","category":"page"},{"location":"models/layers/#Flux.Maxout","page":"Model Reference","title":"Flux.Maxout","text":"Maxout(over)\n\nMaxout is a neural network layer, which has a number of internal layers, which all have the same input, and the maxout returns the elementwise maximium of the internal layers' outputs.\n\nMaxout over linear dense layers satisfies the univeral approximation theorem.\n\nReference: Ian J. Goodfellow, David Warde-Farley, Mehdi Mirza, Aaron Courville, and Yoshua Bengio.\n\nMaxout networks.\n\nIn Proceedings of the 30th International Conference on International Conference on Machine Learning - Volume 28 (ICML'13), Sanjoy Dasgupta and David McAllester (Eds.), Vol. 28. JMLR.org III-1319-III-1327. https://arxiv.org/pdf/1302.4389.pdf\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.SkipConnection","page":"Model Reference","title":"Flux.SkipConnection","text":"SkipConnection(layers, connection)\n\nCreates a Skip Connection, of a layer or Chain of consecutive layers plus a shortcut connection. The connection function will combine the result of the layers with the original input, to give the final output.\n\nThe simplest 'ResNet'-type connection is just SkipConnection(layer, +), and requires the output of the layers to be the same shape as the input. Here is a more complicated example:\n\nm = Conv((3,3), 4=>7, pad=(1,1))\nx = ones(5,5,4,10);\nsize(m(x)) == (5, 5, 7, 10)\n\nsm = SkipConnection(m, (mx, x) -> cat(mx, x, dims=3))\nsize(sm(x)) == (5, 5, 11, 10)\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Activation-Functions-1","page":"Model Reference","title":"Activation Functions","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Non-linearities that go between layers of your model. Most of these functions are defined in NNlib but are available by default in Flux.","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Note that, unless otherwise stated, activation functions operate on scalars. To apply them to an array you can call σ.(xs), relu.(xs) and so on.","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"σ\nrelu\nleakyrelu\nelu\nswish","category":"page"},{"location":"models/layers/#NNlib.σ","page":"Model Reference","title":"NNlib.σ","text":"σ(x) = 1 / (1 + exp(-x))\n\nClassic sigmoid activation function.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#NNlib.relu","page":"Model Reference","title":"NNlib.relu","text":"relu(x) = max(0, x)\n\nRectified Linear Unit activation function.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#NNlib.leakyrelu","page":"Model Reference","title":"NNlib.leakyrelu","text":"leakyrelu(x) = max(0.01x, x)\n\nLeaky Rectified Linear Unit activation function. You can also specify the coefficient explicitly, e.g. leakyrelu(x, 0.01).\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#NNlib.elu","page":"Model Reference","title":"NNlib.elu","text":"elu(x, α = 1) =\n  x > 0 ? x : α * (exp(x) - 1)\n\nExponential Linear Unit activation function. See Fast and Accurate Deep Network Learning by Exponential Linear Units. You can also specify the coefficient explicitly, e.g. elu(x, 1).\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#NNlib.swish","page":"Model Reference","title":"NNlib.swish","text":"swish(x) = x * σ(x)\n\nSelf-gated activation function. See Swish: a Self-Gated Activation Function.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Normalisation-and-Regularisation-1","page":"Model Reference","title":"Normalisation & Regularisation","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"These layers don't affect the structure of the network but may improve training times or reduce overfitting.","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"BatchNorm\nDropout\nAlphaDropout\nLayerNorm\nGroupNorm","category":"page"},{"location":"models/layers/#Flux.BatchNorm","page":"Model Reference","title":"Flux.BatchNorm","text":"BatchNorm(channels::Integer, σ = identity;\n          initβ = zeros, initγ = ones,\n          ϵ = 1e-8, momentum = .1)\n\nBatch Normalization layer. The channels input should be the size of the channel dimension in your data (see below).\n\nGiven an array with N dimensions, call the N-1th the channel dimension. (For a batch of feature vectors this is just the data dimension, for WHCN images it's the usual channel dimension.)\n\nBatchNorm computes the mean and variance for each each W×H×1×N slice and shifts them to have a new mean and variance (corresponding to the learnable, per-channel bias and scale parameters).\n\nSee Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift.\n\nExample:\n\nm = Chain(\n  Dense(28^2, 64),\n  BatchNorm(64, relu),\n  Dense(64, 10),\n  BatchNorm(10),\n  softmax)\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.Dropout","page":"Model Reference","title":"Flux.Dropout","text":"Dropout(p, dims = :)\n\nA Dropout layer. For each input, either sets that input to 0 (with probability p) or scales it by 1/(1-p). The dims argument is to specified the unbroadcasted  dimensions, i.e. dims=1 does dropout along columns and dims=2 along rows. This is  used as a regularisation, i.e. it reduces overfitting during training. see also dropout.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.AlphaDropout","page":"Model Reference","title":"Flux.AlphaDropout","text":"AlphaDropout(p)\n\nA dropout layer. It is used in Self-Normalizing Neural Networks. (https://papers.nips.cc/paper/6698-self-normalizing-neural-networks.pdf) The AlphaDropout layer ensures that mean and variance of activations remains the same as before.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.LayerNorm","page":"Model Reference","title":"Flux.LayerNorm","text":"LayerNorm(h::Integer)\n\nA normalisation layer designed to be used with recurrent hidden states of size h. Normalises the mean/stddev of each input before applying a per-neuron gain/bias.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.GroupNorm","page":"Model Reference","title":"Flux.GroupNorm","text":"Group Normalization. This layer can outperform Batch-Normalization and Instance-Normalization.\n\nGroupNorm(chs::Integer, G::Integer, λ = identity;\n          initβ = (i) -> zeros(Float32, i), initγ = (i) -> ones(Float32, i),\n          ϵ = 1f-5, momentum = 0.1f0)\n\nchs is the number of channels, the channel dimension of your input. For an array of N dimensions, the (N-1)th index is the channel dimension.\n\nG is the number of groups along which the statistics would be computed. The number of channels must be an integer multiple of the number of groups.\n\nExample:\n\nm = Chain(Conv((3,3), 1=>32, leakyrelu;pad = 1),\n          GroupNorm(32,16)) # 32 channels, 16 groups (G = 16), thus 2 channels per group used\n\nLink : https://arxiv.org/pdf/1803.08494.pdf\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Cost-Functions-1","page":"Model Reference","title":"Cost Functions","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"mse\ncrossentropy\nlogitcrossentropy\nbinarycrossentropy\nlogitbinarycrossentropy\nkldivergence\npoisson\nhinge","category":"page"},{"location":"community/#Community-1","page":"Community","title":"Community","text":"","category":"section"},{"location":"community/#","page":"Community","title":"Community","text":"All Flux users are welcome to join our community on the Julia forum, or the slack (channel #machine-learning). If you have questions or issues we'll try to help you out.","category":"page"},{"location":"community/#","page":"Community","title":"Community","text":"If you're interested in hacking on Flux, the source code is open and easy to understand – it's all just the same Julia code you work with normally. You might be interested in our intro issues to get started.","category":"page"},{"location":"models/recurrence/#Recurrent-Models-1","page":"Recurrence","title":"Recurrent Models","text":"","category":"section"},{"location":"models/recurrence/#Recurrent-Cells-1","page":"Recurrence","title":"Recurrent Cells","text":"","category":"section"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"In the simple feedforward case, our model m is a simple function from various inputs xᵢ to predictions yᵢ. (For example, each x might be an MNIST digit and each y a digit label.) Each prediction is completely independent of any others, and using the same x will always produce the same y.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"y₁ = f(x₁)\ny₂ = f(x₂)\ny₃ = f(x₃)\n# ...","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Recurrent networks introduce a hidden state that gets carried over each time we run the model. The model now takes the old h as an input, and produces a new h as output, each time we run it.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"h = # ... initial state ...\nh, y₁ = f(h, x₁)\nh, y₂ = f(h, x₂)\nh, y₃ = f(h, x₃)\n# ...","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Information stored in h is preserved for the next prediction, allowing it to function as a kind of memory. This also means that the prediction made for a given x depends on all the inputs previously fed into the model.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"(This might be important if, for example, each x represents one word of a sentence; the model's interpretation of the word \"bank\" should change if the previous input was \"river\" rather than \"investment\".)","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Flux's RNN support closely follows this mathematical perspective. The most basic RNN is as close as possible to a standard Dense layer, and the output is also the hidden state.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Wxh = randn(5, 10)\nWhh = randn(5, 5)\nb   = randn(5)\n\nfunction rnn(h, x)\n  h = tanh.(Wxh * x .+ Whh * h .+ b)\n  return h, h\nend\n\nx = rand(10) # dummy data\nh = rand(5)  # initial hidden state\n\nh, y = rnn(h, x)","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"If you run the last line a few times, you'll notice the output y changing slightly even though the input x is the same.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"We sometimes refer to functions like rnn above, which explicitly manage state, as recurrent cells. There are various recurrent cells available, which are documented in the layer reference. The hand-written example above can be replaced with:","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"using Flux\n\nrnn2 = Flux.RNNCell(10, 5)\n\nx = rand(10) # dummy data\nh = rand(5)  # initial hidden state\n\nh, y = rnn2(h, x)","category":"page"},{"location":"models/recurrence/#Stateful-Models-1","page":"Recurrence","title":"Stateful Models","text":"","category":"section"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"For the most part, we don't want to manage hidden states ourselves, but to treat our models as being stateful. Flux provides the Recur wrapper to do this.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"x = rand(10)\nh = rand(5)\n\nm = Flux.Recur(rnn, h)\n\ny = m(x)","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"The Recur wrapper stores the state between runs in the m.state field.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"If you use the RNN(10, 5) constructor – as opposed to RNNCell – you'll see that it's simply a wrapped cell.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"julia> RNN(10, 5)\nRecur(RNNCell(10, 5, tanh))","category":"page"},{"location":"models/recurrence/#Sequences-1","page":"Recurrence","title":"Sequences","text":"","category":"section"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Often we want to work with sequences of inputs, rather than individual xs.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"seq = [rand(10) for i = 1:10]","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"With Recur, applying our model to each element of a sequence is trivial:","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"m.(seq) # returns a list of 5-element vectors","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"This works even when we've chain recurrent layers into a larger model.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"m = Chain(LSTM(10, 15), Dense(15, 5))\nm.(seq)","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Finally, we can reset the hidden state of the cell back to its initial value using reset!(m).","category":"page"},{"location":"training/training/#Training-1","page":"Training","title":"Training","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"To actually train a model we need four things:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"A objective function, that evaluates how well a model is doing given some input data.\nThe trainable parameters of the model.\nA collection of data points that will be provided to the objective function.\nAn optimiser that will update the model parameters appropriately.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"With these we can call Flux.train!:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Flux.train!(objective, params, data, opt)","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"There are plenty of examples in the model zoo.","category":"page"},{"location":"training/training/#Loss-Functions-1","page":"Training","title":"Loss Functions","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"The objective function must return a number representing how far the model is from its target – the loss of the model. The loss function that we defined in basics will work as an objective. We can also define an objective in terms of some model:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"m = Chain(\n  Dense(784, 32, σ),\n  Dense(32, 10), softmax)\n\nloss(x, y) = Flux.mse(m(x), y)\nps = Flux.params(m)\n\n# later\nFlux.train!(loss, ps, data, opt)","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"The objective will almost always be defined in terms of some cost function that measures the distance of the prediction m(x) from the target y. Flux has several of these built in, like mse for mean squared error or crossentropy for cross entropy loss, but you can calculate it however you want.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"At first glance it may seem strange that the model that we want to train is not part of the input arguments of Flux.train! too. However the target of the optimizer is not the model itself, but the objective function that represents the departure between modelled and observed data. In other words, the model is implicitly defined in the objective function, and there is no need to give it explicitly. Passing the objective function instead of the model and a cost function separately provides more flexibility, and the possibility of optimizing the calculations.","category":"page"},{"location":"training/training/#Model-parameters-1","page":"Training","title":"Model parameters","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"The model to be trained must have a set of tracked parameters that are used to calculate the gradients of the objective function. In the basics section it is explained how to create models with such parameters. The second argument of the function Flux.train! must be an object containing those parameters, which can be obtained from a model m as params(m).","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Such an object contains a reference to the model's parameters, not a copy, such that after their training, the model behaves according to their updated values.","category":"page"},{"location":"training/training/#Datasets-1","page":"Training","title":"Datasets","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"The data argument provides a collection of data to train with (usually a set of inputs x and target outputs y). For example, here's a dummy data set with only one data point:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"x = rand(784)\ny = rand(10)\ndata = [(x, y)]","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Flux.train! will call loss(x, y), calculate gradients, update the weights and then move on to the next data point if there is one. We can train the model on the same data three times:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"data = [(x, y), (x, y), (x, y)]\n# Or equivalently\ndata = Iterators.repeated((x, y), 3)","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"It's common to load the xs and ys separately. In this case you can use zip:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"xs = [rand(784), rand(784), rand(784)]\nys = [rand( 10), rand( 10), rand( 10)]\ndata = zip(xs, ys)","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Note that, by default, train! only loops over the data once (a single \"epoch\"). A convenient way to run multiple epochs from the REPL is provided by @epochs.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"julia> using Flux: @epochs\n\njulia> @epochs 2 println(\"hello\")\nINFO: Epoch 1\nhello\nINFO: Epoch 2\nhello\n\njulia> @epochs 2 Flux.train!(...)\n# Train for two epochs","category":"page"},{"location":"training/training/#Callbacks-1","page":"Training","title":"Callbacks","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"train! takes an additional argument, cb, that's used for callbacks so that you can observe the training process. For example:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"train!(objective, ps, data, opt, cb = () -> println(\"training\"))","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Callbacks are called for every batch of training data. You can slow this down using Flux.throttle(f, timeout) which prevents f from being called more than once every timeout seconds.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"A more typical callback might look like this:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"test_x, test_y = # ... create single batch of test data ...\nevalcb() = @show(loss(test_x, test_y))\n\nFlux.train!(objective, ps, data, opt,\n            cb = throttle(evalcb, 5))","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Calling Flux.stop() in a callback will exit the training loop early.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"cb = function ()\n  accuracy() > 0.9 && Flux.stop()\nend","category":"page"},{"location":"training/training/#Custom-Training-loops-1","page":"Training","title":"Custom Training loops","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"The Flux.train! function can be very convenient, especially for simple problems. Its also very flexible with the use of callbacks. But for some problems its much cleaner to write your own custom training loop. An example follows that works similar to the default Flux.train but with no callbacks. You don't need callbacks if you just code the calls to your functions directly into the loop. E.g. in the places marked with comments.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"function my_custom_train!(loss, ps, data, opt)\n  ps = Params(ps)\n  for d in data\n    gs = gradient(ps) do\n      training_loss = loss(d...)\n      # Insert what ever code you want here that needs Training loss, e.g. logging\n      return training_loss\n    end\n    # insert what ever code you want here that needs gradient\n    # E.g. logging with TensorBoardLogger.jl as histogram so you can see if it is becoming huge\n    update!(opt, ps, gs)\n    # Here you might like to check validation set accuracy, and break out to do early stopping\n  end\nend","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"You could simplify this further, for example by hard-coding in the loss function.","category":"page"},{"location":"gpu/#GPU-Support-1","page":"GPU Support","title":"GPU Support","text":"","category":"section"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"NVIDIA GPU support should work out of the box on systems with CUDA and CUDNN installed. For more details see the CuArrays readme.","category":"page"},{"location":"gpu/#GPU-Usage-1","page":"GPU Support","title":"GPU Usage","text":"","category":"section"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"Support for array operations on other hardware backends, like GPUs, is provided by external packages like CuArrays. Flux is agnostic to array types, so we simply need to move model weights and data to the GPU and Flux will handle it.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"For example, we can use CuArrays (with the cu converter) to run our basic example on an NVIDIA GPU.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"(Note that you need to have CUDA available to use CuArrays – please see the CuArrays.jl instructions for more details.)","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"using CuArrays\n\nW = cu(rand(2, 5)) # a 2×5 CuArray\nb = cu(rand(2))\n\npredict(x) = W*x .+ b\nloss(x, y) = sum((predict(x) .- y).^2)\n\nx, y = cu(rand(5)), cu(rand(2)) # Dummy data\nloss(x, y) # ~ 3","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"Note that we convert both the parameters (W, b) and the data set (x, y) to cuda arrays. Taking derivatives and training works exactly as before.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"If you define a structured model, like a Dense layer or Chain, you just need to convert the internal parameters. Flux provides fmap, which allows you to alter all parameters of a model at once.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"d = Dense(10, 5, σ)\nd = fmap(cu, d)\nd.W # Tracked CuArray\nd(cu(rand(10))) # CuArray output\n\nm = Chain(Dense(10, 5, σ), Dense(5, 2), softmax)\nm = fmap(cu, m)\nd(cu(rand(10)))","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"As a convenience, Flux provides the gpu function to convert models and data to the GPU if one is available. By default, it'll do nothing, but loading CuArrays will cause it to move data to the GPU instead.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"julia> using Flux, CuArrays\n\njulia> m = Dense(10,5) |> gpu\nDense(10, 5)\n\njulia> x = rand(10) |> gpu\n10-element CuArray{Float32,1}:\n 0.800225\n ⋮\n 0.511655\n\njulia> m(x)\nTracked 5-element CuArray{Float32,1}:\n -0.30535\n ⋮\n -0.618002","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"The analogue cpu is also available for moving models and data back off of the GPU.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"julia> x = rand(10) |> gpu\n10-element CuArray{Float32,1}:\n 0.235164\n ⋮\n 0.192538\n\njulia> x |> cpu\n10-element Array{Float32,1}:\n 0.235164\n ⋮\n 0.192538","category":"page"},{"location":"training/optimisers/#Optimisers-1","page":"Optimisers","title":"Optimisers","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Consider a simple linear regression. We create some dummy data, calculate a loss, and backpropagate to calculate gradients for the parameters W and b.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"using Flux\n\nW = rand(2, 5)\nb = rand(2)\n\npredict(x) = (W * x) .+ b\nloss(x, y) = sum((predict(x) .- y).^2)\n\nx, y = rand(5), rand(2) # Dummy data\nl = loss(x, y) # ~ 3\n\nθ = Params([W, b])\ngrads = gradient(() -> loss(x, y), θ)","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"We want to update each parameter, using the gradient, in order to improve (reduce) the loss. Here's one way to do that:","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"using Flux: update!\n\nη = 0.1 # Learning Rate\nfor p in (W, b)\n  update!(p, -η * grads[p])\nend","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Running this will alter the parameters W and b and our loss should go down. Flux provides a more general way to do optimiser updates like this.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"opt = Descent(0.1) # Gradient descent with learning rate 0.1\n\nfor p in (W, b)\n  update!(opt, p, grads[p])\nend","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"An optimiser update! accepts a parameter and a gradient, and updates the parameter according to the chosen rule. We can also pass opt to our training loop, which will update all parameters of the model in a loop. However, we can now easily replace Descent with a more advanced optimiser such as ADAM.","category":"page"},{"location":"training/optimisers/#Optimiser-Reference-1","page":"Optimisers","title":"Optimiser Reference","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"All optimisers return an object that, when passed to train!, will update the parameters passed to it.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Descent\nMomentum\nNesterov\nRMSProp\nADAM\nAdaMax\nADAGrad\nADADelta\nAMSGrad\nNADAM\nADAMW","category":"page"},{"location":"training/optimisers/#Flux.Optimise.Descent","page":"Optimisers","title":"Flux.Optimise.Descent","text":"Descent(η)\n\nClassic gradient descent optimiser with learning rate η. For each parameter p and its gradient δp, this runs p -= η*δp\n\nParameters\n\nLearning Rate (η): The amount by which the gradients are discounted before updating the weights. Defaults to 0.1.\n\nExample\n\nopt = Descent() # uses default η (0.1)\n\nopt = Descent(0.3) # use provided η\n\nps = params(model)\n\ngs = gradient(ps) do\n  loss(x, y)\nend\n\nFlux.Optimise.update!(opt, ps, gs)\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.Momentum","page":"Optimisers","title":"Flux.Optimise.Momentum","text":"Momentum(η, ρ)\n\nGradient descent with learning rate η and momentum ρ.\n\nParameters\n\nLearning Rate (η): Amount by which gradients are discounted before updating the weights. Defaults to 0.01.\nMomentum (ρ): Parameter that accelerates descent in the relevant direction and dampens oscillations. Defaults to 0.9.\n\nExamples\n\nopt = Momentum() # uses defaults of η = 0.01 and ρ = 0.9\n\nopt = Momentum(0.01, 0.99)\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.Nesterov","page":"Optimisers","title":"Flux.Optimise.Nesterov","text":"Nesterov(η, ρ)\n\nGradient descent with learning rate  η and Nesterov momentum ρ.\n\nParameters\n\nLearning Rate (η): Amount by which the gradients are dicsounted berfore updating the weights. Defaults to 0.001.\nNesterov Momentum (ρ): Paramters controlling the amount of nesterov momentum to be applied. Defaults to 0.9.\n\nExamples\n\nopt = Nesterov() # uses defaults η = 0.001 and ρ = 0.9\n\nopt = Nesterov(0.003, 0.95)\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.RMSProp","page":"Optimisers","title":"Flux.Optimise.RMSProp","text":"RMSProp(η, ρ)\n\nImplements the RMSProp algortihm. Often a good choice for recurrent networks. Paramters other than learning rate generally don't need tuning.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001.\nRho (ρ): Defaults to 0.9.\n\nExamples\n\nopt = RMSProp() # uses default η = 0.001 and ρ = 0.9\n\nopt = RMSProp(0.002, 0.95)\n\nReferences\n\nRMSProp\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.ADAM","page":"Optimisers","title":"Flux.Optimise.ADAM","text":"ADAM(η, β::Tuple)\n\nImplements the ADAM optimiser.\n\nParamters\n\nLearning Rate (η): Defaults to 0.001.\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\n\nExamples\n\nopt = ADAM() # uses the default η = 0.001 and β = (0.9, 0.999)\n\nopt = ADAM(0.001, (0.9, 0.8))\n\nReferences\n\nADAM optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.AdaMax","page":"Optimisers","title":"Flux.Optimise.AdaMax","text":"AdaMax(η, β::Tuple)\n\nVariant of ADAM based on ∞-norm.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\n\nExamples\n\nopt = AdaMax() # uses default η and β\n\nopt = AdaMax(0.001, (0.9, 0.995))\n\nReferences\n\nAdaMax optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.ADAGrad","page":"Optimisers","title":"Flux.Optimise.ADAGrad","text":"ADAGrad(η)\n\nImplements AdaGrad. It has parameter specific learning rates based on how frequently it is updated.\n\nParameters\n\nLearning Rate (η): Defaults to 0.1\n\nExamples\n\nopt = ADAGrad() # uses default η = 0.1\n\nopt = ADAGrad(0.001)\n\nReferences\n\nADAGrad optimiser. Parameters don't need tuning.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.ADADelta","page":"Optimisers","title":"Flux.Optimise.ADADelta","text":"ADADelta(ρ)\n\nVersion of ADAGrad that adapts learning rate based on a window of past gradient updates. Parameters don't need tuning.\n\nParameters\n\nRho (ρ): Factor by which gradient is decayed at each time step. Defaults to 0.9.\n\nExamples\n\nopt = ADADelta() # uses default ρ = 0.9\nopt = ADADelta(0.89)\n\nReferences\n\nADADelta optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.AMSGrad","page":"Optimisers","title":"Flux.Optimise.AMSGrad","text":"AMSGrad(η, β::Tuple)\n\nImplements AMSGrad version of the ADAM optimiser. Parameters don't need tuning.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001.\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\n\nExamples\n\nopt = AMSGrad() # uses default η and β\nopt = AMSGrad(0.001, (0.89, 0.995))\n\nReferences\n\nAMSGrad optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.NADAM","page":"Optimisers","title":"Flux.Optimise.NADAM","text":"NADAM(η, β::Tuple)\n\nNesterov variant of ADAM. Parameters don't need tuning.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001.\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\n\nExamples\n\nopt = NADAM() # uses default η and β\nopt = NADAM(0.002, (0.89, 0.995))\n\nReferences\n\nNADAM optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.ADAMW","page":"Optimisers","title":"Flux.Optimise.ADAMW","text":"ADAMW(η, β::Tuple, decay)\n\nVariant of ADAM defined by fixing weight decay regularization.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001.\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\ndecay: Decay applied to weights during optimisation. Defaults to 0.\n\nExamples\n\nopt = ADAMW() # uses default η, β and decay\nopt = ADAMW(0.001, (0.89, 0.995), 0.1)\n\nReferences\n\nADAMW\n\n\n\n\n\n","category":"function"},{"location":"training/optimisers/#Optimiser-Interface-1","page":"Optimisers","title":"Optimiser Interface","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Flux's optimsers are built around a struct that holds all the optimiser parameters along with a definition of how to apply the update rule associated with it. We do this via the apply! function which takes the optimiser as the first argument followed by the parameter and its corresponding gradient.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"In this manner Flux also allows one to create custom optimisers to be used seamlessly. Let's work this with a simple example.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"mutable struct Momentum\n  eta\n  rho\n  velocity\nend\n\nMomentum(eta::Real, rho::Real) = Momentum(eta, rho, IdDict())","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"The Momentum type will act as our optimiser in this case. Notice that we have added all the parameters as fields, along with the velocity which we will use as our state dictionary. Each parameter in our models will get an entry in there. We can now define the rule applied when this optimiser is invoked.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"function apply!(o::Momentum, x, Δ)\n  η, ρ = o.eta, o.rho\n  v = get!(o.velocity, x, zero(x))::typeof(x)\n  @. v = ρ * v - η * Δ\n  @. Δ = -v\nend","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"This is the basic definition of a Momentum update rule given by:","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"v = ρ * v - η * Δ\nw = w - v","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"The apply! defines the update rules for an optimiser opt, given the parameters and gradients. It returns the updated gradients. Here, every parameter x is retrieved from the running state v and subsequently updates the state of the optimiser.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Flux internally calls on this function via the update! function. It shares the API with apply! but ensures that multiple parameters are handled gracefully.","category":"page"},{"location":"training/optimisers/#Composing-Optimisers-1","page":"Optimisers","title":"Composing Optimisers","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Flux defines a special kind of optimiser called simply as Optimiser which takes in a arbitrary optimisers as input. Its behaviour is similar to the usual optimisers, but differs in that it acts by calling the optimisers listed in it sequentially. Each optimiser produces a modified gradient that will be fed into the next, and the resultant update will be applied to the parameter as usual. A classic use case is where adding decays is desirable. Flux defines some basic decays including ExpDecay, InvDecay etc.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"opt = Optimiser(ExpDecay(0.001, 0.1, 1000, 1e-4), Descent())","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Here we apply exponential decay to the Descent optimser. The defaults of ExpDecay say that its learning rate will be decayed every 1000 steps. It is then applied like any optimser.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"w = randn(10, 10)\nw1 = randn(10,10)\nps = Params([w, w1])\n\nloss(x) = Flux.mse(w * x, w1 * x)\n\nloss(rand(10)) # around 9\n\nfor t = 1:10^5\n  θ = Params([w, w1])\n  θ̄ = gradient(() -> loss(rand(10)), θ)\n  Flux.Optimise.update!(opt, θ, θ̄)\nend\n\nloss(rand(10)) # around 0.9","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"In this manner it is possible to compose optimisers for some added flexibility.","category":"page"},{"location":"training/optimisers/#Decays-1","page":"Optimisers","title":"Decays","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Similar to optimisers, Flux also defines some simple decays that can be used in conjunction with other optimisers, or standalone.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"ExpDecay\nInvDecay\nWeightDecay","category":"page"},{"location":"training/optimisers/#Flux.Optimise.ExpDecay","page":"Optimisers","title":"Flux.Optimise.ExpDecay","text":"ExpDecay(eta, decay, decay_step, clip)\n\nDiscount the learning rate eta by a multiplicative factor decay every decay_step till a minimum of clip.\n\nParameters\n\nLearning Rate (eta): Defaults to 0.001.\ndecay: Factor by which the learning rate is discounted. Defaults to 0.1.\ndecay_step: Schedules decay operations by setting number of steps between two decay operations. Defaults to 1000.\nclip: Minimum value of learning rate. Defaults to 1e-4.\n\nExample\n\nTo apply exponential decay to an optimiser:\n\n  Optimiser(ExpDecay(..), Opt(..))\n\n  opt = Optimiser(ExpDecay(), ADAM())\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.InvDecay","page":"Optimisers","title":"Flux.Optimise.InvDecay","text":"InvDecay(γ)\n\nApplies inverse time decay to an optimiser, i.e., the effective step size at iteration n is eta / (1 + γ * n) where eta is the initial step size. The wrapped optimiser's step size is not modified.\n\n\n## Parameters\n  - gamma (γ): Defaults to `0.001`\n\n## Example\n\njulia   Optimiser(InvDecay(..), Opt(..)) ```\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.WeightDecay","page":"Optimisers","title":"Flux.Optimise.WeightDecay","text":"WeightDecay(wd)\n\nDecays the weight by wd\n\nParameters\n\nweight decay (wd): 0\n\n\n\n\n\n","category":"type"},{"location":"#Flux:-The-Julia-Machine-Learning-Library-1","page":"Home","title":"Flux: The Julia Machine Learning Library","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Flux is a library for machine learning. It comes \"batteries-included\" with many useful tools built in, but also lets you use the full power of the Julia language where you need it. We follow a few key principles:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"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.\nYou could have written Flux. All of it, from LSTMs to GPU kernels, is straightforward Julia code. When in doubt, it’s well worth looking at the source. If you need something different, you can easily roll your own.\nPlay nicely with others. Flux works well with Julia libraries from data frames and images to differential equation solvers, so you can easily build complex data processing pipelines that integrate Flux models.","category":"page"},{"location":"#Installation-1","page":"Home","title":"Installation","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Download Julia 1.0 or later, if you haven't already. You can add Flux from using Julia's package manager, by typing ] add Flux in the Julia prompt.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"If you have CUDA you can also run ] add CuArrays to get GPU support; see here for more details.","category":"page"},{"location":"#Learning-Flux-1","page":"Home","title":"Learning Flux","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"There are several different ways to learn Flux. If you just want to get started writing models, the model zoo gives good starting points for many common ones. This documentation provides a reference to all of Flux's APIs, as well as a from-scratch introduction to Flux's take on models and how they work. Once you understand these docs, congratulations, you also understand Flux's source code, which is intended to be concise, legible and a good reference for more advanced concepts.","category":"page"},{"location":"models/basics/#Model-Building-Basics-1","page":"Basics","title":"Model-Building Basics","text":"","category":"section"},{"location":"models/basics/#Taking-Gradients-1","page":"Basics","title":"Taking Gradients","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Flux's core feature is taking gradients of Julia code. The gradient function takes another Julia function f and a set of arguments, and returns the gradient with respect to each argument. (It's a good idea to try pasting these examples in the Julia terminal.)","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"julia> using Flux\n\njulia> f(x) = 3x^2 + 2x + 1;\n\njulia> df(x) = gradient(f, x)[1]; # df/dx = 6x + 2\n\njulia> df(2)\n14\n\njulia> d2f(x) = gradient(df, x)[1]; # d²f/dx² = 6\n\njulia> d2f(2)\n6","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"When a function has many parameters, we can get gradients of each one at the same time:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"julia> f(x, y) = sum((x .- y).^2);\n\njulia> gradient(f, [2, 1], [2, 0])\n([0, 2], [0, -2])","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"But machine learning models can have hundreds of parameters! To handle this, Flux lets you work with collections of parameters, via params. You can get the gradient of all parameters used in a program without explicitly passing them in.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"julia> using Flux\n\njulia> x = [2, 1];\n\njulia> y = [2, 0];\n\njulia> gs = gradient(params(x, y)) do\n         f(x, y)\n       end\nGrads(...)\n\njulia> gs[x]\n2-element Array{Int64,1}:\n 0\n 2\n\njulia> gs[y]\n2-element Array{Int64,1}:\n  0\n -2","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Here, gradient takes a zero-argument function; no arguments are necessary because the params tell it what to differentiate.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"This will come in really handy when dealing with big, complicated models. For now, though, let's start with something simple.","category":"page"},{"location":"models/basics/#Simple-Models-1","page":"Basics","title":"Simple Models","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Consider a simple linear regression, which tries to predict an output array y from an input x.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"W = rand(2, 5)\nb = rand(2)\n\npredict(x) = W*x .+ b\n\nfunction loss(x, y)\n  ŷ = predict(x)\n  sum((y .- ŷ).^2)\nend\n\nx, y = rand(5), rand(2) # Dummy data\nloss(x, y) # ~ 3","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"To improve the prediction we can take the gradients of W and b with respect to the loss and perform gradient descent.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"using Flux\n\ngs = gradient(() -> loss(x, y), params(W, b))","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Now that we have gradients, we can pull them out and update W to train the model.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"W̄ = gs[W]\n\nW .-= 0.1 .* W̄\n\nloss(x, y) # ~ 2.5","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"The loss has decreased a little, meaning that our prediction x is closer to the target y. If we have some data we can already try training the model.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"All deep learning in Flux, however complex, is a simple generalisation of this example. Of course, models can look very different – they might have millions of parameters or complex control flow. Let's see how Flux handles more complex models.","category":"page"},{"location":"models/basics/#Building-Layers-1","page":"Basics","title":"Building Layers","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"It's common to create more complex models than the linear regression above. For example, we might want to have two linear layers with a nonlinearity like sigmoid (σ) in between them. In the above style we could write this as:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"using Flux\n\nW1 = rand(3, 5)\nb1 = rand(3)\nlayer1(x) = W1 * x .+ b1\n\nW2 = rand(2, 3)\nb2 = rand(2)\nlayer2(x) = W2 * x .+ b2\n\nmodel(x) = layer2(σ.(layer1(x)))\n\nmodel(rand(5)) # => 2-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"This works but is fairly unwieldy, with a lot of repetition – especially as we add more layers. One way to factor this out is to create a function that returns linear layers.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"function linear(in, out)\n  W = randn(out, in)\n  b = randn(out)\n  x -> W * x .+ b\nend\n\nlinear1 = linear(5, 3) # we can access linear1.W etc\nlinear2 = linear(3, 2)\n\nmodel(x) = linear2(σ.(linear1(x)))\n\nmodel(rand(5)) # => 2-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Another (equivalent) way is to create a struct that explicitly represents the affine layer.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"struct Affine\n  W\n  b\nend\n\nAffine(in::Integer, out::Integer) =\n  Affine(randn(out, in), randn(out))\n\n# Overload call, so the object can be used as a function\n(m::Affine)(x) = m.W * x .+ m.b\n\na = Affine(10, 5)\n\na(rand(10)) # => 5-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Congratulations! You just built the Dense layer that comes with Flux. Flux has many interesting layers available, but they're all things you could have built yourself very easily.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"(There is one small difference with Dense – for convenience it also takes an activation function, like Dense(10, 5, σ).)","category":"page"},{"location":"models/basics/#Stacking-It-Up-1","page":"Basics","title":"Stacking It Up","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"It's pretty common to write models that look something like:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"layer1 = Dense(10, 5, σ)\n# ...\nmodel(x) = layer3(layer2(layer1(x)))","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"For long chains, it might be a bit more intuitive to have a list of layers, like this:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"using Flux\n\nlayers = [Dense(10, 5, σ), Dense(5, 2), softmax]\n\nmodel(x) = foldl((x, m) -> m(x), layers, init = x)\n\nmodel(rand(10)) # => 2-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Handily, this is also provided for in Flux:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"model2 = Chain(\n  Dense(10, 5, σ),\n  Dense(5, 2),\n  softmax)\n\nmodel2(rand(10)) # => 2-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"This quickly starts to look like a high-level deep learning library; yet you can see how it falls out of simple abstractions, and we lose none of the power of Julia code.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"A nice property of this approach is that because \"models\" are just functions (possibly with trainable parameters), you can also see this as simple function composition.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"m = Dense(5, 2) ∘ Dense(10, 5, σ)\n\nm(rand(10))","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Likewise, Chain will happily work with any Julia function.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"m = Chain(x -> x^2, x -> x+1)\n\nm(5) # => 26","category":"page"},{"location":"models/basics/#Layer-helpers-1","page":"Basics","title":"Layer helpers","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Flux provides a set of helpers for custom layers, which you can enable by calling","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Flux.@functor Affine","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"This enables a useful extra set of functionality for our Affine layer, such as collecting its parameters or moving it to the GPU.","category":"page"}]
+[{"location":"training/optimisers/#Optimisers-1","page":"Optimisers","title":"Optimisers","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Consider a simple linear regression. We create some dummy data, calculate a loss, and backpropagate to calculate gradients for the parameters W and b.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"using Flux\n\nW = rand(2, 5)\nb = rand(2)\n\npredict(x) = (W * x) .+ b\nloss(x, y) = sum((predict(x) .- y).^2)\n\nx, y = rand(5), rand(2) # Dummy data\nl = loss(x, y) # ~ 3\n\nθ = Params([W, b])\ngrads = gradient(() -> loss(x, y), θ)","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"We want to update each parameter, using the gradient, in order to improve (reduce) the loss. Here's one way to do that:","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"using Flux.Optimise: update!\n\nη = 0.1 # Learning Rate\nfor p in (W, b)\n  update!(p, -η * grads[p])\nend","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Running this will alter the parameters W and b and our loss should go down. Flux provides a more general way to do optimiser updates like this.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"opt = Descent(0.1) # Gradient descent with learning rate 0.1\n\nfor p in (W, b)\n  update!(opt, p, grads[p])\nend","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"An optimiser update! accepts a parameter and a gradient, and updates the parameter according to the chosen rule. We can also pass opt to our training loop, which will update all parameters of the model in a loop. However, we can now easily replace Descent with a more advanced optimiser such as ADAM.","category":"page"},{"location":"training/optimisers/#Optimiser-Reference-1","page":"Optimisers","title":"Optimiser Reference","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"All optimisers return an object that, when passed to train!, will update the parameters passed to it.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Flux.Optimise.update!\nDescent\nMomentum\nNesterov\nRMSProp\nADAM\nAdaMax\nADAGrad\nADADelta\nAMSGrad\nNADAM\nADAMW","category":"page"},{"location":"training/optimisers/#Flux.Optimise.update!","page":"Optimisers","title":"Flux.Optimise.update!","text":"update!(opt, p, g)\nupdate!(opt, ps::Params, gs)\n\nPerform an update step of the parameters ps (or the single parameter p)  according to optimizer opt  and the gradients gs (the gradient g).\n\nAs a result, the parameters are mutated and the optimizer's internal state may change. \n\nupdate!(x, x̄)\n\nUpdate the array x according to x .-= x̄.\n\n\n\n\n\n","category":"function"},{"location":"training/optimisers/#Flux.Optimise.Descent","page":"Optimisers","title":"Flux.Optimise.Descent","text":"Descent(η)\n\nClassic gradient descent optimiser with learning rate η. For each parameter p and its gradient δp, this runs p -= η*δp\n\nParameters\n\nLearning Rate (η): The amount by which the gradients are discounted before updating the weights. Defaults to 0.1.\n\nExample\n\nopt = Descent() # uses default η (0.1)\n\nopt = Descent(0.3) # use provided η\n\nps = params(model)\n\ngs = gradient(ps) do\n  loss(x, y)\nend\n\nFlux.Optimise.update!(opt, ps, gs)\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.Momentum","page":"Optimisers","title":"Flux.Optimise.Momentum","text":"Momentum(η, ρ)\n\nGradient descent with learning rate η and momentum ρ.\n\nParameters\n\nLearning Rate (η): Amount by which gradients are discounted before updating the weights. Defaults to 0.01.\nMomentum (ρ): Parameter that accelerates descent in the relevant direction and dampens oscillations. Defaults to 0.9.\n\nExamples\n\nopt = Momentum() # uses defaults of η = 0.01 and ρ = 0.9\n\nopt = Momentum(0.01, 0.99)\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.Nesterov","page":"Optimisers","title":"Flux.Optimise.Nesterov","text":"Nesterov(η, ρ)\n\nGradient descent with learning rate  η and Nesterov momentum ρ.\n\nParameters\n\nLearning Rate (η): Amount by which the gradients are dicsounted berfore updating the weights. Defaults to 0.001.\nNesterov Momentum (ρ): Parameters controlling the amount of nesterov momentum to be applied. Defaults to 0.9.\n\nExamples\n\nopt = Nesterov() # uses defaults η = 0.001 and ρ = 0.9\n\nopt = Nesterov(0.003, 0.95)\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.RMSProp","page":"Optimisers","title":"Flux.Optimise.RMSProp","text":"RMSProp(η, ρ)\n\nImplements the RMSProp algortihm. Often a good choice for recurrent networks. Parameters other than learning rate generally don't need tuning.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001.\nRho (ρ): Defaults to 0.9.\n\nExamples\n\nopt = RMSProp() # uses default η = 0.001 and ρ = 0.9\n\nopt = RMSProp(0.002, 0.95)\n\nReferences\n\nRMSProp\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.ADAM","page":"Optimisers","title":"Flux.Optimise.ADAM","text":"ADAM(η, β::Tuple)\n\nImplements the ADAM optimiser.\n\nParamters\n\nLearning Rate (η): Defaults to 0.001.\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\n\nExamples\n\nopt = ADAM() # uses the default η = 0.001 and β = (0.9, 0.999)\n\nopt = ADAM(0.001, (0.9, 0.8))\n\nReferences\n\nADAM optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.AdaMax","page":"Optimisers","title":"Flux.Optimise.AdaMax","text":"AdaMax(η, β::Tuple)\n\nVariant of ADAM based on ∞-norm.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\n\nExamples\n\nopt = AdaMax() # uses default η and β\n\nopt = AdaMax(0.001, (0.9, 0.995))\n\nReferences\n\nAdaMax optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.ADAGrad","page":"Optimisers","title":"Flux.Optimise.ADAGrad","text":"ADAGrad(η)\n\nImplements AdaGrad. It has parameter specific learning rates based on how frequently it is updated.\n\nParameters\n\nLearning Rate (η): Defaults to 0.1\n\nExamples\n\nopt = ADAGrad() # uses default η = 0.1\n\nopt = ADAGrad(0.001)\n\nReferences\n\nADAGrad optimiser. Parameters don't need tuning.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.ADADelta","page":"Optimisers","title":"Flux.Optimise.ADADelta","text":"ADADelta(ρ)\n\nVersion of ADAGrad that adapts learning rate based on a window of past gradient updates. Parameters don't need tuning.\n\nParameters\n\nRho (ρ): Factor by which gradient is decayed at each time step. Defaults to 0.9.\n\nExamples\n\nopt = ADADelta() # uses default ρ = 0.9\nopt = ADADelta(0.89)\n\nReferences\n\nADADelta optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.AMSGrad","page":"Optimisers","title":"Flux.Optimise.AMSGrad","text":"AMSGrad(η, β::Tuple)\n\nImplements AMSGrad version of the ADAM optimiser. Parameters don't need tuning.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001.\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\n\nExamples\n\nopt = AMSGrad() # uses default η and β\nopt = AMSGrad(0.001, (0.89, 0.995))\n\nReferences\n\nAMSGrad optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.NADAM","page":"Optimisers","title":"Flux.Optimise.NADAM","text":"NADAM(η, β::Tuple)\n\nNesterov variant of ADAM. Parameters don't need tuning.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001.\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\n\nExamples\n\nopt = NADAM() # uses default η and β\nopt = NADAM(0.002, (0.89, 0.995))\n\nReferences\n\nNADAM optimiser.\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.ADAMW","page":"Optimisers","title":"Flux.Optimise.ADAMW","text":"ADAMW(η, β::Tuple, decay)\n\nVariant of ADAM defined by fixing weight decay regularization.\n\nParameters\n\nLearning Rate (η): Defaults to 0.001.\nBeta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).\ndecay: Decay applied to weights during optimisation. Defaults to 0.\n\nExamples\n\nopt = ADAMW() # uses default η, β and decay\nopt = ADAMW(0.001, (0.89, 0.995), 0.1)\n\nReferences\n\nADAMW\n\n\n\n\n\n","category":"function"},{"location":"training/optimisers/#Optimiser-Interface-1","page":"Optimisers","title":"Optimiser Interface","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Flux's optimisers are built around a struct that holds all the optimiser parameters along with a definition of how to apply the update rule associated with it. We do this via the apply! function which takes the optimiser as the first argument followed by the parameter and its corresponding gradient.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"In this manner Flux also allows one to create custom optimisers to be used seamlessly. Let's work this with a simple example.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"mutable struct Momentum\n  eta\n  rho\n  velocity\nend\n\nMomentum(eta::Real, rho::Real) = Momentum(eta, rho, IdDict())","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"The Momentum type will act as our optimiser in this case. Notice that we have added all the parameters as fields, along with the velocity which we will use as our state dictionary. Each parameter in our models will get an entry in there. We can now define the rule applied when this optimiser is invoked.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"function apply!(o::Momentum, x, Δ)\n  η, ρ = o.eta, o.rho\n  v = get!(o.velocity, x, zero(x))::typeof(x)\n  @. v = ρ * v - η * Δ\n  @. Δ = -v\nend","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"This is the basic definition of a Momentum update rule given by:","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"v = ρ * v - η * Δ\nw = w - v","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"The apply! defines the update rules for an optimiser opt, given the parameters and gradients. It returns the updated gradients. Here, every parameter x is retrieved from the running state v and subsequently updates the state of the optimiser.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Flux internally calls on this function via the update! function. It shares the API with apply! but ensures that multiple parameters are handled gracefully.","category":"page"},{"location":"training/optimisers/#Composing-Optimisers-1","page":"Optimisers","title":"Composing Optimisers","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Flux defines a special kind of optimiser simply called Optimiser which takes in arbitrary optimisers as input. Its behaviour is similar to the usual optimisers, but differs in that it acts by calling the optimisers listed in it sequentially. Each optimiser produces a modified gradient that will be fed into the next, and the resultant update will be applied to the parameter as usual. A classic use case is where adding decays is desirable. Flux defines some basic decays including ExpDecay, InvDecay etc.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"opt = Optimiser(ExpDecay(0.001, 0.1, 1000, 1e-4), Descent())","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Here we apply exponential decay to the Descent optimiser. The defaults of ExpDecay say that its learning rate will be decayed every 1000 steps. It is then applied like any optimiser.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"w = randn(10, 10)\nw1 = randn(10,10)\nps = Params([w, w1])\n\nloss(x) = Flux.mse(w * x, w1 * x)\n\nloss(rand(10)) # around 9\n\nfor t = 1:10^5\n  θ = Params([w, w1])\n  θ̄ = gradient(() -> loss(rand(10)), θ)\n  Flux.Optimise.update!(opt, θ, θ̄)\nend\n\nloss(rand(10)) # around 0.9","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"In this manner it is possible to compose optimisers for some added flexibility.","category":"page"},{"location":"training/optimisers/#Decays-1","page":"Optimisers","title":"Decays","text":"","category":"section"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"Similar to optimisers, Flux also defines some simple decays that can be used in conjunction with other optimisers, or standalone.","category":"page"},{"location":"training/optimisers/#","page":"Optimisers","title":"Optimisers","text":"ExpDecay\nInvDecay\nWeightDecay","category":"page"},{"location":"training/optimisers/#Flux.Optimise.ExpDecay","page":"Optimisers","title":"Flux.Optimise.ExpDecay","text":"ExpDecay(eta, decay, decay_step, clip)\n\nDiscount the learning rate eta by a multiplicative factor decay every decay_step till a minimum of clip.\n\nParameters\n\nLearning Rate (eta): Defaults to 0.001.\ndecay: Factor by which the learning rate is discounted. Defaults to 0.1.\ndecay_step: Schedules decay operations by setting number of steps between two decay operations. Defaults to 1000.\nclip: Minimum value of learning rate. Defaults to 1e-4.\n\nExample\n\nTo apply exponential decay to an optimiser:\n\nOptimiser(ExpDecay(..), Opt(..))\nopt = Optimiser(ExpDecay(), ADAM())\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.InvDecay","page":"Optimisers","title":"Flux.Optimise.InvDecay","text":"InvDecay(γ)\n\nApplies inverse time decay to an optimiser, i.e., the effective step size at iteration n is eta / (1 + γ * n) where eta is the initial step size. The wrapped optimiser's step size is not modified.\n\nParameters\n\ngamma (γ): Defaults to 0.001\n\nExample\n\nOptimiser(InvDecay(..), Opt(..))\n\n\n\n\n\n","category":"type"},{"location":"training/optimisers/#Flux.Optimise.WeightDecay","page":"Optimisers","title":"Flux.Optimise.WeightDecay","text":"WeightDecay(wd)\n\nDecays the weight by wd\n\nParameters\n\nweight decay (wd): 0\n\n\n\n\n\n","category":"type"},{"location":"models/regularisation/#Regularisation-1","page":"Regularisation","title":"Regularisation","text":"","category":"section"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"Applying regularisation to model parameters is straightforward. We just need to apply an appropriate regulariser, such as norm, to each model parameter and add the result to the overall loss.","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"For example, say we have a simple regression.","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"using Flux: crossentropy\nm = Dense(10, 5)\nloss(x, y) = crossentropy(softmax(m(x)), y)","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"We can regularise this by taking the (L2) norm of the parameters, m.W and m.b.","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"using LinearAlgebra\n\npenalty() = norm(m.W) + norm(m.b)\nloss(x, y) = crossentropy(softmax(m(x)), y) + penalty()","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"When working with layers, Flux provides the params function to grab all parameters at once. We can easily penalise everything with sum(norm, params).","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"julia> params(m)\n2-element Array{Any,1}:\n param([0.355408 0.533092; … 0.430459 0.171498])\n param([0.0, 0.0, 0.0, 0.0, 0.0])\n\njulia> sum(norm, params(m))\n26.01749952921026","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"Here's a larger example with a multi-layer perceptron.","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"m = Chain(\n  Dense(28^2, 128, relu),\n  Dense(128, 32, relu),\n  Dense(32, 10), softmax)\n\nloss(x, y) = crossentropy(m(x), y) + sum(norm, params(m))\n\nloss(rand(28^2), rand(10))","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"One can also easily add per-layer regularisation via the activations function:","category":"page"},{"location":"models/regularisation/#","page":"Regularisation","title":"Regularisation","text":"julia> using Flux: activations\n\njulia> c = Chain(Dense(10, 5, σ), Dense(5, 2), softmax)\nChain(Dense(10, 5, σ), Dense(5, 2), softmax)\n\njulia> activations(c, rand(10))\n3-element Array{Any,1}:\n Float32[0.84682214, 0.6704139, 0.42177814, 0.257832, 0.36255655]\n Float32[0.1501253, 0.073269576]                                 \n Float32[0.5192045, 0.48079553]                                  \n\njulia> sum(norm, ans)\n2.1166067f0","category":"page"},{"location":"data/dataloader/#DataLoader-1","page":"DataLoader","title":"DataLoader","text":"","category":"section"},{"location":"data/dataloader/#","page":"DataLoader","title":"DataLoader","text":"Flux provides the DataLoader type in the Flux.Data module to handle iteration over mini-batches of data. ","category":"page"},{"location":"data/dataloader/#","page":"DataLoader","title":"DataLoader","text":"Flux.Data.DataLoader","category":"page"},{"location":"data/dataloader/#Flux.Data.DataLoader","page":"DataLoader","title":"Flux.Data.DataLoader","text":"DataLoader(data...; batchsize=1, shuffle=false, partial=true)\n\nAn object that iterates over mini-batches of data, each mini-batch containing batchsize observations (except possibly the last one). \n\nTakes as input one or more data tensors, e.g. X in unsupervised learning, X and Y in  supervised learning. The last dimension in each tensor is considered to be the observation dimension. \n\nIf shuffle=true, shuffles the observations each time iterations are re-started. If partial=false, drops the last mini-batch if it is smaller than the batchsize.\n\nExample usage:\n\nXtrain = rand(10, 100)\ndtrain = DataLoader(Xtrain, batchsize=2) \n# iterate over 50 mini-batches\nfor x in dtrain: \n    @assert size(x) == (10, 2)\n    ...\nend\n\nXtrain = rand(10, 100)\nYtrain = rand(100)\ndtrain = DataLoader(Xtrain, Ytrain, batchsize=2, shuffle=true) \nfor epoch in 1:100\n    for (x, y) in dtrain: \n        @assert size(x) == (10, 2)\n        @assert size(y) == (2,)\n        ...\n    end\nend\n\n# train for 10 epochs\nusing IterTools: ncycle \nFlux.train!(loss, ps, ncycle(dtrain, 10), opt)\n\n\n\n\n\n","category":"type"},{"location":"performance/#Performance-Tips-1","page":"Performance Tips","title":"Performance Tips","text":"","category":"section"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"All the usual Julia performance tips apply. As always profiling your code is generally a useful way of finding bottlenecks. Below follow some Flux specific tips/reminders.","category":"page"},{"location":"performance/#Don't-use-more-precision-than-you-need.-1","page":"Performance Tips","title":"Don't use more precision than you need.","text":"","category":"section"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"Flux works great with all kinds of number types. But often you do not need to be working with say Float64 (let alone BigFloat). Switching to Float32 can give you a significant speed up, not because the operations are faster, but because the memory usage is halved. Which means allocations occur much faster. And you use less memory.","category":"page"},{"location":"performance/#Make-sure-your-activation-and-loss-functions-preserve-the-type-of-their-inputs-1","page":"Performance Tips","title":"Make sure your activation and loss functions preserve the type of their inputs","text":"","category":"section"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"Not only should your activation and loss functions be type-stable, they should also preserve the type of their inputs.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"A very artificial example using an activation function like","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"    my_tanh(x) = Float64(tanh(x))","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"will result in performance on Float32 input orders of magnitude slower than the normal tanh would, because it results in having to use slow mixed type multiplication in the dense layers. Similar situations can occur in the loss function during backpropagation.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"Which means if you change your data say from Float64 to Float32 (which should give a speedup: see above), you will see a large slow-down","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"This can occur sneakily, because you can cause type-promotion by interacting with a numeric literals. E.g. the following will have run into the same problem as above:","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"    leaky_tanh(x) = 0.01x + tanh(x)","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"While one could change your activation function (e.g. to use 0.01f0x) to avoid this when ever your inputs change, the idiomatic (and safe way) is to use oftype.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"    leaky_tanh(x) = oftype(x/1, 0.01)x + tanh(x)","category":"page"},{"location":"performance/#Evaluate-batches-as-Matrices-of-features,-rather-than-sequences-of-Vector-features-1","page":"Performance Tips","title":"Evaluate batches as Matrices of features, rather than sequences of Vector features","text":"","category":"section"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"While it can sometimes be tempting to process your observations (feature vectors) one at a time e.g.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"function loss_total(xs::AbstractVector{<:Vector}, ys::AbstractVector{<:Vector})\n    sum(zip(xs, ys)) do (x, y_target)\n        y_pred = model(x) #  evaluate the model\n        return loss(y_pred, y_target)\n    end\nend","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"It is much faster to concatenate them into a matrix, as this will hit BLAS matrix-matrix multiplication, which is much faster than the equivalent sequence of matrix-vector multiplications. The improvement is enough that it is worthwhile allocating new memory to store them contiguously.","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"x_batch = reduce(hcat, xs)\ny_batch = reduce(hcat, ys)\n...\nfunction loss_total(x_batch::Matrix, y_batch::Matrix)\n    y_preds = model(x_batch)\n    sum(loss.(y_preds, y_batch))\nend","category":"page"},{"location":"performance/#","page":"Performance Tips","title":"Performance Tips","text":"When doing this kind of concatenation use reduce(hcat, xs) rather than hcat(xs...). This will avoid the splatting penalty, and will hit the optimised reduce method.","category":"page"},{"location":"ecosystem/#The-Julia-Ecosystem-1","page":"The Julia Ecosystem","title":"The Julia Ecosystem","text":"","category":"section"},{"location":"ecosystem/#","page":"The Julia Ecosystem","title":"The Julia Ecosystem","text":"One of the main strengths of Julia lies in an ecosystem of packages  globally providing a rich and consistent user experience.","category":"page"},{"location":"ecosystem/#","page":"The Julia Ecosystem","title":"The Julia Ecosystem","text":"This is a non-exhaustive list of Julia packages, nicely complementing Flux in typical machine learning and deep learning workflows:","category":"page"},{"location":"ecosystem/#","page":"The Julia Ecosystem","title":"The Julia Ecosystem","text":"ArgParse.jl: package for parsing command-line arguments to Julia programs.\nAugmentor.jl: a fast image augmentation library in Julia for machine learning.\nBSON.jl: package for working with the Binary JSON serialisation format\nDataFrames.jl: in-memory tabular data in Julia\nDrWatson.jl:  a scientific project assistant software\nMLDatasets.jl: utility package for accessing common machine learning datasets\nOnlineStats.jl: single-pass algorithms for statistics\nParameters.jl: types with default field values, keyword constructors and (un-)pack macros\nProgressMeters.jl: progress meters for long-running computations\nTensorBoardLogger.jl: easy peasy logging to tensorboard in Julia","category":"page"},{"location":"ecosystem/#","page":"The Julia Ecosystem","title":"The Julia Ecosystem","text":"This tight integration among Julia pakages is shown in some of the examples in the model-zoo repository.","category":"page"},{"location":"models/nnlib/#NNlib-1","page":"NNlib","title":"NNlib","text":"","category":"section"},{"location":"models/nnlib/#","page":"NNlib","title":"NNlib","text":"Flux re-exports all of the functions exported by the NNlib package.","category":"page"},{"location":"models/nnlib/#Activation-Functions-1","page":"NNlib","title":"Activation Functions","text":"","category":"section"},{"location":"models/nnlib/#","page":"NNlib","title":"NNlib","text":"Non-linearities that go between layers of your model. Note that, unless otherwise stated, activation functions operate on scalars. To apply them to an array you can call σ.(xs), relu.(xs) and so on.","category":"page"},{"location":"models/nnlib/#","page":"NNlib","title":"NNlib","text":"NNlib.elu\nNNlib.gelu\nNNlib.leakyrelu\nNNlib.logcosh\nNNlib.logsigmoid\nNNlib.sigmoid\nNNlib.relu\nNNlib.selu\nNNlib.softplus\nNNlib.softsign\nNNlib.swish","category":"page"},{"location":"models/nnlib/#NNlib.elu","page":"NNlib","title":"NNlib.elu","text":"elu(x, α = 1) =\n  x > 0 ? x : α * (exp(x) - 1)\n\nExponential Linear Unit activation function. See Fast and Accurate Deep Network Learning by Exponential Linear Units. You can also specify the coefficient explicitly, e.g. elu(x, 1).\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.gelu","page":"NNlib","title":"NNlib.gelu","text":"gelu(x) = 0.5x*(1 + tanh(√(2/π)*(x + 0.044715x^3)))\n\nGaussian Error Linear Unit activation function.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.leakyrelu","page":"NNlib","title":"NNlib.leakyrelu","text":"leakyrelu(x) = max(0.01x, x)\n\nLeaky Rectified Linear Unit activation function. You can also specify the coefficient explicitly, e.g. leakyrelu(x, 0.01).\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.logcosh","page":"NNlib","title":"NNlib.logcosh","text":"logcosh(x)\n\nReturn log(cosh(x)) which is computed in a numerically stable way.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.logsigmoid","page":"NNlib","title":"NNlib.logsigmoid","text":"logσ(x)\n\nReturn log(σ(x)) which is computed in a numerically stable way.\n\njulia> logσ(0)\n-0.6931471805599453\njulia> logσ.([-100, -10, 100])\n3-element Array{Float64,1}:\n -100.0\n  -10.000045398899218\n   -3.720075976020836e-44\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.sigmoid","page":"NNlib","title":"NNlib.sigmoid","text":"σ(x) = 1 / (1 + exp(-x))\n\nClassic sigmoid activation function.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.relu","page":"NNlib","title":"NNlib.relu","text":"relu(x) = max(0, x)\n\nRectified Linear Unit activation function.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.selu","page":"NNlib","title":"NNlib.selu","text":"selu(x) = λ * (x ≥ 0 ? x : α * (exp(x) - 1))\n\nλ ≈ 1.0507\nα ≈ 1.6733\n\nScaled exponential linear units. See Self-Normalizing Neural Networks.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.softplus","page":"NNlib","title":"NNlib.softplus","text":"softplus(x) = log(exp(x) + 1)\n\nSee Deep Sparse Rectifier Neural Networks.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.softsign","page":"NNlib","title":"NNlib.softsign","text":"softsign(x) = x / (1 + |x|)\n\nSee Quadratic Polynomials Learn Better Image Features.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.swish","page":"NNlib","title":"NNlib.swish","text":"swish(x) = x * σ(x)\n\nSelf-gated activation function. See Swish: a Self-Gated Activation Function.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#Softmax-1","page":"NNlib","title":"Softmax","text":"","category":"section"},{"location":"models/nnlib/#","page":"NNlib","title":"NNlib","text":"NNlib.softmax\nNNlib.logsoftmax","category":"page"},{"location":"models/nnlib/#NNlib.softmax","page":"NNlib","title":"NNlib.softmax","text":"softmax(xs) = exp.(xs) ./ sum(exp.(xs))\n\nSoftmax takes log-probabilities (any real vector) and returns a probability distribution that sums to 1.\n\nIf given a matrix it will by default (dims=1) treat it as a batch of vectors, with each column independent. Keyword dims=2 will instead treat rows independently, etc.\n\njulia> softmax([1,2,3.])\n3-element Array{Float64,1}:\n  0.0900306\n  0.244728\n  0.665241\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#NNlib.logsoftmax","page":"NNlib","title":"NNlib.logsoftmax","text":"logsoftmax(xs) = log.(exp.(xs) ./ sum(exp.(xs)))\n\nComputes the log of softmax in a more numerically stable way than directly taking log.(softmax(xs)). Commonly used in computing cross entropy loss.\n\n\n\n\n\n","category":"function"},{"location":"models/nnlib/#Pooling-1","page":"NNlib","title":"Pooling","text":"","category":"section"},{"location":"models/nnlib/#","page":"NNlib","title":"NNlib","text":"NNlib.maxpool\nNNlib.meanpool","category":"page"},{"location":"models/nnlib/#Convolution-1","page":"NNlib","title":"Convolution","text":"","category":"section"},{"location":"models/nnlib/#","page":"NNlib","title":"NNlib","text":"NNlib.conv\nNNlib.depthwiseconv","category":"page"},{"location":"saving/#Saving-and-Loading-Models-1","page":"Saving & Loading","title":"Saving and Loading Models","text":"","category":"section"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"You may wish to save models so that they can be loaded and run in a later session. The easiest way to do this is via BSON.jl.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"Save a model:","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"julia> using Flux\n\njulia> model = Chain(Dense(10,5,relu),Dense(5,2),softmax)\nChain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)\n\njulia> using BSON: @save\n\njulia> @save \"mymodel.bson\" model","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"Load it again:","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"julia> using Flux\n\njulia> using BSON: @load\n\njulia> @load \"mymodel.bson\" model\n\njulia> model\nChain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"Models are just normal Julia structs, so it's fine to use any Julia storage format for this purpose. BSON.jl is particularly well supported and most likely to be forwards compatible (that is, models saved now will load in future versions of Flux).","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"note: Note\nIf a saved model's weights are stored on the GPU, the model will not load later on if there is no GPU support available. It's best to move your model to the CPU with cpu(model) before saving it.","category":"page"},{"location":"saving/#Saving-Model-Weights-1","page":"Saving & Loading","title":"Saving Model Weights","text":"","category":"section"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"In some cases it may be useful to save only the model parameters themselves, and rebuild the model architecture in your code. You can use params(model) to get model parameters. You can also use data.(params) to remove tracking.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"julia> using Flux\n\njulia> model = Chain(Dense(10,5,relu),Dense(5,2),softmax)\nChain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)\n\njulia> weights = params(model);\n\njulia> using BSON: @save\n\njulia> @save \"mymodel.bson\" weights","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"You can easily load parameters back into a model with Flux.loadparams!.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"julia> using Flux\n\njulia> model = Chain(Dense(10,5,relu),Dense(5,2),softmax)\nChain(Dense(10, 5, NNlib.relu), Dense(5, 2), NNlib.softmax)\n\njulia> using BSON: @load\n\njulia> @load \"mymodel.bson\" weights\n\njulia> Flux.loadparams!(model, weights)","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"The new model we created will now be identical to the one we saved parameters for.","category":"page"},{"location":"saving/#Checkpointing-1","page":"Saving & Loading","title":"Checkpointing","text":"","category":"section"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"In longer training runs it's a good idea to periodically save your model, so that you can resume if training is interrupted (for example, if there's a power cut). You can do this by saving the model in the callback provided to train!.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"using Flux: throttle\nusing BSON: @save\n\nm = Chain(Dense(10,5,relu),Dense(5,2),softmax)\n\nevalcb = throttle(30) do\n  # Show loss\n  @save \"model-checkpoint.bson\" model\nend","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"This will update the \"model-checkpoint.bson\" file every thirty seconds.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"You can get more advanced by saving a series of models throughout training, for example","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"@save \"model-$(now()).bson\" model","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"will produce a series of models like \"model-2018-03-06T02:57:10.41.bson\". You could also store the current test set loss, so that it's easy to (for example) revert to an older copy of the model if it starts to overfit.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"@save \"model-$(now()).bson\" model loss = testloss()","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"You can even store optimiser state alongside the model, to resume training exactly where you left off.","category":"page"},{"location":"saving/#","page":"Saving & Loading","title":"Saving & Loading","text":"opt = ADAM()\n@save \"model-$(now()).bson\" model opt","category":"page"},{"location":"models/layers/#Basic-Layers-1","page":"Model Reference","title":"Basic Layers","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"These core layers form the foundation of almost all neural networks.","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Chain\nDense","category":"page"},{"location":"models/layers/#Flux.Chain","page":"Model Reference","title":"Flux.Chain","text":"Chain(layers...)\n\nChain multiple layers / functions together, so that they are called in sequence on a given input.\n\nm = Chain(x -> x^2, x -> x+1)\nm(5) == 26\n\nm = Chain(Dense(10, 5), Dense(5, 2))\nx = rand(10)\nm(x) == m[2](m[1](x))\n\nChain also supports indexing and slicing, e.g. m[2] or m[1:end-1]. m[1:3](x) will calculate the output of the first three layers.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.Dense","page":"Model Reference","title":"Flux.Dense","text":"Dense(in::Integer, out::Integer, σ = identity)\n\nCreates a traditional Dense layer with parameters W and b.\n\ny = σ.(W * x .+ b)\n\nThe input x must be a vector of length in, or a batch of vectors represented as an in × N matrix. The out y will be a vector or batch of length out.\n\njulia> d = Dense(5, 2)\nDense(5, 2)\n\njulia> d(rand(5))\nTracked 2-element Array{Float64,1}:\n  0.00257447\n  -0.00449443\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Convolution-and-Pooling-Layers-1","page":"Model Reference","title":"Convolution and Pooling Layers","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"These layers are used to build convolutional neural networks (CNNs).","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Conv\nMaxPool\nMeanPool\nDepthwiseConv\nConvTranspose\nCrossCor","category":"page"},{"location":"models/layers/#Flux.Conv","page":"Model Reference","title":"Flux.Conv","text":"Conv(size, in=>out)\nConv(size, in=>out, relu)\n\nStandard convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.\n\nExample: Applying Conv layer to a 1-channel input using a 2x2 window size,          giving us a 16-channel output. Output is activated with ReLU.\n\nsize = (2,2)\nin = 1\nout = 16\nConv((2, 2), 1=>16, relu)\n\nData should be stored in WHCN order (width, height, # channels, batch size). In other words, a 100×100 RGB image would be a 100×100×3×1 array, and a batch of 50 would be a 100×100×3×50 array.\n\nTakes the keyword arguments pad, stride and dilation.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.MaxPool","page":"Model Reference","title":"Flux.MaxPool","text":"MaxPool(k)\n\nMax pooling layer. k stands for the size of the window for each dimension of the input.\n\nTakes the keyword arguments pad and stride.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.MeanPool","page":"Model Reference","title":"Flux.MeanPool","text":"MeanPool(k)\n\nMean pooling layer. k stands for the size of the window for each dimension of the input.\n\nTakes the keyword arguments pad and stride.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.DepthwiseConv","page":"Model Reference","title":"Flux.DepthwiseConv","text":"DepthwiseConv(size, in=>out)\nDepthwiseConv(size, in=>out, relu)\n\nDepthwise convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively. Note that out must be an integer multiple of in.\n\nData should be stored in WHCN order. In other words, a 100×100 RGB image would be a 100×100×3 array, and a batch of 50 would be a 100×100×3×50 array.\n\nTakes the keyword arguments pad, stride and dilation.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.ConvTranspose","page":"Model Reference","title":"Flux.ConvTranspose","text":"ConvTranspose(size, in=>out)\nConvTranspose(size, in=>out, relu)\n\nStandard convolutional transpose layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.\n\nData should be stored in WHCN order. In other words, a 100×100 RGB image would be a 100×100×3 array, and a batch of 50 would be a 100×100×3×50 array.\n\nTakes the keyword arguments pad, stride and dilation.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.CrossCor","page":"Model Reference","title":"Flux.CrossCor","text":"CrossCor(size, in=>out)\nCrossCor(size, in=>out, relu)\n\nStandard cross convolutional layer. size should be a tuple like (2, 2). in and out specify the number of input and output channels respectively.\n\nExample: Applying CrossCor layer to a 1-channel input using a 2x2 window size,          giving us a 16-channel output. Output is activated with ReLU.\n\nsize = (2,2)\nin = 1\nout = 16\nCrossCor((2, 2), 1=>16, relu)\n\nData should be stored in WHCN order (width, height, # channels, # batches). In other words, a 100×100 RGB image would be a 100×100×3×1 array, and a batch of 50 would be a 100×100×3×50 array.\n\nTakes the keyword arguments pad, stride and dilation.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Recurrent-Layers-1","page":"Model Reference","title":"Recurrent Layers","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Much like the core layers above, but can be used to process sequence data (as well as other kinds of structured data).","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"RNN\nLSTM\nGRU\nFlux.Recur","category":"page"},{"location":"models/layers/#Flux.RNN","page":"Model Reference","title":"Flux.RNN","text":"RNN(in::Integer, out::Integer, σ = tanh)\n\nThe most basic recurrent layer; essentially acts as a Dense layer, but with the output fed back into the input each time step.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.LSTM","page":"Model Reference","title":"Flux.LSTM","text":"LSTM(in::Integer, out::Integer)\n\nLong Short Term Memory recurrent layer. Behaves like an RNN but generally exhibits a longer memory span over sequences.\n\nSee this article for a good overview of the internals.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.GRU","page":"Model Reference","title":"Flux.GRU","text":"GRU(in::Integer, out::Integer)\n\nGated Recurrent Unit layer. Behaves like an RNN but generally exhibits a longer memory span over sequences.\n\nSee this article for a good overview of the internals.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.Recur","page":"Model Reference","title":"Flux.Recur","text":"Recur(cell)\n\nRecur takes a recurrent cell and makes it stateful, managing the hidden state in the background. cell should be a model of the form:\n\nh, y = cell(h, x...)\n\nFor example, here's a recurrent network that keeps a running total of its inputs.\n\naccum(h, x) = (h+x, x)\nrnn = Flux.Recur(accum, 0)\nrnn(2) # 2\nrnn(3) # 3\nrnn.state # 5\nrnn.(1:10) # apply to a sequence\nrnn.state # 60\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Other-General-Purpose-Layers-1","page":"Model Reference","title":"Other General Purpose Layers","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"These are marginally more obscure than the Basic Layers. But in contrast to the layers described in the other sections are not readily grouped around a particular purpose (e.g. CNNs or RNNs).","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Maxout\nSkipConnection","category":"page"},{"location":"models/layers/#Flux.Maxout","page":"Model Reference","title":"Flux.Maxout","text":"Maxout(over)\n\nMaxout is a neural network layer, which has a number of internal layers, which all have the same input, and the maxout returns the elementwise maximium of the internal layers' outputs.\n\nMaxout over linear dense layers satisfies the univeral approximation theorem.\n\nReference: Ian J. Goodfellow, David Warde-Farley, Mehdi Mirza, Aaron Courville, and Yoshua Bengio.\n\nMaxout networks.\n\nIn Proceedings of the 30th International Conference on International Conference on Machine Learning - Volume 28 (ICML'13), Sanjoy Dasgupta and David McAllester (Eds.), Vol. 28. JMLR.org III-1319-III-1327. https://arxiv.org/pdf/1302.4389.pdf\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.SkipConnection","page":"Model Reference","title":"Flux.SkipConnection","text":"SkipConnection(layers, connection)\n\nCreates a Skip Connection, of a layer or Chain of consecutive layers plus a shortcut connection. The connection function will combine the result of the layers with the original input, to give the final output.\n\nThe simplest 'ResNet'-type connection is just SkipConnection(layer, +), and requires the output of the layers to be the same shape as the input. Here is a more complicated example:\n\nm = Conv((3,3), 4=>7, pad=(1,1))\nx = ones(5,5,4,10);\nsize(m(x)) == (5, 5, 7, 10)\n\nsm = SkipConnection(m, (mx, x) -> cat(mx, x, dims=3))\nsize(sm(x)) == (5, 5, 11, 10)\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Normalisation-and-Regularisation-1","page":"Model Reference","title":"Normalisation & Regularisation","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"These layers don't affect the structure of the network but may improve training times or reduce overfitting.","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"BatchNorm\nDropout\nFlux.dropout\nAlphaDropout\nLayerNorm\nGroupNorm","category":"page"},{"location":"models/layers/#Flux.BatchNorm","page":"Model Reference","title":"Flux.BatchNorm","text":"BatchNorm(channels::Integer, σ = identity;\n          initβ = zeros, initγ = ones,\n          ϵ = 1e-8, momentum = .1)\n\nBatch Normalization layer. The channels input should be the size of the channel dimension in your data (see below).\n\nGiven an array with N dimensions, call the N-1th the channel dimension. (For a batch of feature vectors this is just the data dimension, for WHCN images it's the usual channel dimension.)\n\nBatchNorm computes the mean and variance for each each W×H×1×N slice and shifts them to have a new mean and variance (corresponding to the learnable, per-channel bias and scale parameters).\n\nUse testmode! during inference.\n\nSee Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift.\n\nExample:\n\nm = Chain(\n  Dense(28^2, 64),\n  BatchNorm(64, relu),\n  Dense(64, 10),\n  BatchNorm(10),\n  softmax)\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.Dropout","page":"Model Reference","title":"Flux.Dropout","text":"Dropout(p, dims = :)\n\nA Dropout layer. In the forward pass, applies the dropout function on the input.\n\nDoes nothing to the input once testmode! is false.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.dropout","page":"Model Reference","title":"Flux.dropout","text":"dropout(p, dims = :)\n\nDropout function. For each input, either sets that input to 0 (with probability p) or scales it by 1/(1-p). The dims argument is to specify the unbroadcasted dimensions, i.e. dims=1 does dropout along columns and dims=2 along rows. This is used as a regularisation, i.e. it reduces overfitting during training. \n\nSee also Dropout.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.AlphaDropout","page":"Model Reference","title":"Flux.AlphaDropout","text":"AlphaDropout(p)\n\nA dropout layer. It is used in Self-Normalizing Neural Networks. (https://papers.nips.cc/paper/6698-self-normalizing-neural-networks.pdf) The AlphaDropout layer ensures that mean and variance of activations remains the same as before.\n\nDoes nothing to the input once testmode! is false.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.LayerNorm","page":"Model Reference","title":"Flux.LayerNorm","text":"LayerNorm(h::Integer)\n\nA normalisation layer designed to be used with recurrent hidden states of size h. Normalises the mean/stddev of each input before applying a per-neuron gain/bias.\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Flux.GroupNorm","page":"Model Reference","title":"Flux.GroupNorm","text":"Group Normalization. This layer can outperform Batch-Normalization and Instance-Normalization.\n\nGroupNorm(chs::Integer, G::Integer, λ = identity;\n          initβ = (i) -> zeros(Float32, i), initγ = (i) -> ones(Float32, i),\n          ϵ = 1f-5, momentum = 0.1f0)\n\nchs is the number of channels, the channel dimension of your input. For an array of N dimensions, the (N-1)th index is the channel dimension.\n\nG is the number of groups along which the statistics would be computed. The number of channels must be an integer multiple of the number of groups.\n\nUse testmode! during inference.\n\nExample:\n\nm = Chain(Conv((3,3), 1=>32, leakyrelu;pad = 1),\n          GroupNorm(32,16)) # 32 channels, 16 groups (G = 16), thus 2 channels per group used\n\nLink : https://arxiv.org/pdf/1803.08494.pdf\n\n\n\n\n\n","category":"type"},{"location":"models/layers/#Testmode-1","page":"Model Reference","title":"Testmode","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Many normalisation layers behave differently under training and inference (testing). By default, Flux will automatically determine when a layer evaluation is part of training or inference. Still, depending on your use case, it may be helpful to manually specify when these layers should be treated as being trained or not. For this, Flux provides testmode!. When called on a model (e.g. a layer or chain of layers), this function will place the model into the mode specified.","category":"page"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"testmode!\ntrainmode!","category":"page"},{"location":"models/layers/#Flux.testmode!","page":"Model Reference","title":"Flux.testmode!","text":"testmode!(m, mode = true)\n\nSet a layer or model's test mode (see below). Using :auto mode will treat any gradient computation as training.\n\nNote: if you manually set a model into test mode, you need to manually place it back into train mode during training phase.\n\nPossible values include:\n\nfalse for training\ntrue for testing\n:auto or nothing for Flux to detect the mode automatically\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.trainmode!","page":"Model Reference","title":"Flux.trainmode!","text":"trainmode!(m, mode = true)\n\nSet a layer of model's train mode (see below). Symmetric to testmode! (i.e. `trainmode!(m, mode) == testmode!(m, !mode)).\n\nNote: if you manually set a model into train mode, you need to manually place it into test mode during testing phase.\n\nPossible values include:\n\ntrue for training\nfalse for testing\n:auto or nothing for Flux to detect the mode automatically\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Cost-Functions-1","page":"Model Reference","title":"Cost Functions","text":"","category":"section"},{"location":"models/layers/#","page":"Model Reference","title":"Model Reference","text":"Flux.mse\nFlux.crossentropy\nFlux.logitcrossentropy\nFlux.binarycrossentropy\nFlux.logitbinarycrossentropy\nFlux.kldivergence\nFlux.poisson\nFlux.hinge","category":"page"},{"location":"models/layers/#Flux.mse","page":"Model Reference","title":"Flux.mse","text":"mse(ŷ, y)\n\nReturn the mean squared error sum((ŷ .- y).^2) / length(y). \n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.crossentropy","page":"Model Reference","title":"Flux.crossentropy","text":"crossentropy(ŷ, y; weight=1)\n\nReturn the crossentropy computed as -sum(y .* log.(ŷ) .* weight) / size(y, 2). \n\nSee also logitcrossentropy, binarycrossentropy.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.logitcrossentropy","page":"Model Reference","title":"Flux.logitcrossentropy","text":"logitcrossentropy(ŷ, y; weight=1)\n\nReturn the crossentropy computed after a softmax operation: \n\n-sum(y .* logsoftmax(ŷ) .* weight) / size(y, 2)\n\nSee also crossentropy, binarycrossentropy.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.binarycrossentropy","page":"Model Reference","title":"Flux.binarycrossentropy","text":"binarycrossentropy(ŷ, y; ϵ=eps(ŷ))\n\nReturn -y*log(ŷ + ϵ) - (1-y)*log(1-ŷ + ϵ). The ϵ term provides numerical stability.\n\nTypically, the prediction ŷ is given by the output of a sigmoid activation.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.logitbinarycrossentropy","page":"Model Reference","title":"Flux.logitbinarycrossentropy","text":"logitbinarycrossentropy(ŷ, y)\n\nlogitbinarycrossentropy(ŷ, y) is mathematically equivalent to binarycrossentropy(σ(ŷ), y) but it is more numerically stable.\n\nSee also binarycrossentropy, sigmoid, logsigmoid.  \n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.kldivergence","page":"Model Reference","title":"Flux.kldivergence","text":"kldivergence(ŷ, y)\n\nKLDivergence is a measure of how much one probability distribution is different from the other. It is always non-negative and zero only when both the distributions are equal everywhere. KL Divergence.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.poisson","page":"Model Reference","title":"Flux.poisson","text":"poisson(ŷ, y)\n\nPoisson loss function is a measure of how the predicted distribution diverges from the expected distribution. Poisson Loss.\n\n\n\n\n\n","category":"function"},{"location":"models/layers/#Flux.hinge","page":"Model Reference","title":"Flux.hinge","text":"hinge(ŷ, y)\n\nMeasures the loss given the prediction ŷ and true labels y (containing 1 or -1).  Hinge Loss.\n\n\n\n\n\n","category":"function"},{"location":"community/#Community-1","page":"Community","title":"Community","text":"","category":"section"},{"location":"community/#","page":"Community","title":"Community","text":"All Flux users are welcome to join our community on the Julia forum, or the slack (channel #machine-learning). If you have questions or issues we'll try to help you out.","category":"page"},{"location":"community/#","page":"Community","title":"Community","text":"If you're interested in hacking on Flux, the source code is open and easy to understand – it's all just the same Julia code you work with normally. You might be interested in our intro issues to get started.","category":"page"},{"location":"models/recurrence/#Recurrent-Models-1","page":"Recurrence","title":"Recurrent Models","text":"","category":"section"},{"location":"models/recurrence/#Recurrent-Cells-1","page":"Recurrence","title":"Recurrent Cells","text":"","category":"section"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"In the simple feedforward case, our model m is a simple function from various inputs xᵢ to predictions yᵢ. (For example, each x might be an MNIST digit and each y a digit label.) Each prediction is completely independent of any others, and using the same x will always produce the same y.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"y₁ = f(x₁)\ny₂ = f(x₂)\ny₃ = f(x₃)\n# ...","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Recurrent networks introduce a hidden state that gets carried over each time we run the model. The model now takes the old h as an input, and produces a new h as output, each time we run it.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"h = # ... initial state ...\nh, y₁ = f(h, x₁)\nh, y₂ = f(h, x₂)\nh, y₃ = f(h, x₃)\n# ...","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Information stored in h is preserved for the next prediction, allowing it to function as a kind of memory. This also means that the prediction made for a given x depends on all the inputs previously fed into the model.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"(This might be important if, for example, each x represents one word of a sentence; the model's interpretation of the word \"bank\" should change if the previous input was \"river\" rather than \"investment\".)","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Flux's RNN support closely follows this mathematical perspective. The most basic RNN is as close as possible to a standard Dense layer, and the output is also the hidden state.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Wxh = randn(5, 10)\nWhh = randn(5, 5)\nb   = randn(5)\n\nfunction rnn(h, x)\n  h = tanh.(Wxh * x .+ Whh * h .+ b)\n  return h, h\nend\n\nx = rand(10) # dummy data\nh = rand(5)  # initial hidden state\n\nh, y = rnn(h, x)","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"If you run the last line a few times, you'll notice the output y changing slightly even though the input x is the same.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"We sometimes refer to functions like rnn above, which explicitly manage state, as recurrent cells. There are various recurrent cells available, which are documented in the layer reference. The hand-written example above can be replaced with:","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"using Flux\n\nrnn2 = Flux.RNNCell(10, 5)\n\nx = rand(10) # dummy data\nh = rand(5)  # initial hidden state\n\nh, y = rnn2(h, x)","category":"page"},{"location":"models/recurrence/#Stateful-Models-1","page":"Recurrence","title":"Stateful Models","text":"","category":"section"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"For the most part, we don't want to manage hidden states ourselves, but to treat our models as being stateful. Flux provides the Recur wrapper to do this.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"x = rand(10)\nh = rand(5)\n\nm = Flux.Recur(rnn, h)\n\ny = m(x)","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"The Recur wrapper stores the state between runs in the m.state field.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"If you use the RNN(10, 5) constructor – as opposed to RNNCell – you'll see that it's simply a wrapped cell.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"julia> RNN(10, 5)\nRecur(RNNCell(10, 5, tanh))","category":"page"},{"location":"models/recurrence/#Sequences-1","page":"Recurrence","title":"Sequences","text":"","category":"section"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Often we want to work with sequences of inputs, rather than individual xs.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"seq = [rand(10) for i = 1:10]","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"With Recur, applying our model to each element of a sequence is trivial:","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"m.(seq) # returns a list of 5-element vectors","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"This works even when we've chain recurrent layers into a larger model.","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"m = Chain(LSTM(10, 15), Dense(15, 5))\nm.(seq)","category":"page"},{"location":"models/recurrence/#","page":"Recurrence","title":"Recurrence","text":"Finally, we can reset the hidden state of the cell back to its initial value using reset!(m).","category":"page"},{"location":"training/training/#Training-1","page":"Training","title":"Training","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"To actually train a model we need four things:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"A objective function, that evaluates how well a model is doing given some input data.\nThe trainable parameters of the model.\nA collection of data points that will be provided to the objective function.\nAn optimiser that will update the model parameters appropriately.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"With these we can call train!:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Flux.Optimise.train!","category":"page"},{"location":"training/training/#Flux.Optimise.train!","page":"Training","title":"Flux.Optimise.train!","text":"train!(loss, params, data, opt; cb)\n\nFor each datapoint d in data computes the gradient of loss(d...) through backpropagation and calls the optimizer opt.\n\nIn case datapoints d are of numeric array type, assumes no splatting is needed  and computes the gradient of loss(d).\n\nTakes a callback as keyword argument cb. For example, this will print \"training\" every 10 seconds:\n\ntrain!(loss, params, data, opt,          cb = throttle(() -> println(\"training\"), 10))\n\nThe callback can call Flux.stop() to interrupt the training loop.\n\nMultiple optimisers and callbacks can be passed to opt and cb as arrays.\n\n\n\n\n\n","category":"function"},{"location":"training/training/#","page":"Training","title":"Training","text":"There are plenty of examples in the model zoo.","category":"page"},{"location":"training/training/#Loss-Functions-1","page":"Training","title":"Loss Functions","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"The objective function must return a number representing how far the model is from its target – the loss of the model. The loss function that we defined in basics will work as an objective. We can also define an objective in terms of some model:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"m = Chain(\n  Dense(784, 32, σ),\n  Dense(32, 10), softmax)\n\nloss(x, y) = Flux.mse(m(x), y)\nps = Flux.params(m)\n\n# later\nFlux.train!(loss, ps, data, opt)","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"The objective will almost always be defined in terms of some cost function that measures the distance of the prediction m(x) from the target y. Flux has several of these built in, like mse for mean squared error or crossentropy for cross entropy loss, but you can calculate it however you want.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"At first glance it may seem strange that the model that we want to train is not part of the input arguments of Flux.train! too. However the target of the optimizer is not the model itself, but the objective function that represents the departure between modelled and observed data. In other words, the model is implicitly defined in the objective function, and there is no need to give it explicitly. Passing the objective function instead of the model and a cost function separately provides more flexibility, and the possibility of optimizing the calculations.","category":"page"},{"location":"training/training/#Model-parameters-1","page":"Training","title":"Model parameters","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"The model to be trained must have a set of tracked parameters that are used to calculate the gradients of the objective function. In the basics section it is explained how to create models with such parameters. The second argument of the function Flux.train! must be an object containing those parameters, which can be obtained from a model m as params(m).","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Such an object contains a reference to the model's parameters, not a copy, such that after their training, the model behaves according to their updated values.","category":"page"},{"location":"training/training/#Datasets-1","page":"Training","title":"Datasets","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"The data argument provides a collection of data to train with (usually a set of inputs x and target outputs y). For example, here's a dummy data set with only one data point:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"x = rand(784)\ny = rand(10)\ndata = [(x, y)]","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Flux.train! will call loss(x, y), calculate gradients, update the weights and then move on to the next data point if there is one. We can train the model on the same data three times:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"data = [(x, y), (x, y), (x, y)]\n# Or equivalently\nusing IterTools: ncycle\ndata = ncycle([(x, y)], 3)","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"It's common to load the xs and ys separately. In this case you can use zip:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"xs = [rand(784), rand(784), rand(784)]\nys = [rand( 10), rand( 10), rand( 10)]\ndata = zip(xs, ys)","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Training data can be conveniently  partitioned for mini-batch training using the Flux.Data.DataLoader type:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"X = rand(28, 28, 60000)\nY = rand(0:9, 60000)\ndata = DataLoader(X, Y, batchsize=128) ","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Note that, by default, train! only loops over the data once (a single \"epoch\"). A convenient way to run multiple epochs from the REPL is provided by @epochs.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"julia> using Flux: @epochs\n\njulia> @epochs 2 println(\"hello\")\nINFO: Epoch 1\nhello\nINFO: Epoch 2\nhello\n\njulia> @epochs 2 Flux.train!(...)\n# Train for two epochs","category":"page"},{"location":"training/training/#Callbacks-1","page":"Training","title":"Callbacks","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"train! takes an additional argument, cb, that's used for callbacks so that you can observe the training process. For example:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"train!(objective, ps, data, opt, cb = () -> println(\"training\"))","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Callbacks are called for every batch of training data. You can slow this down using Flux.throttle(f, timeout) which prevents f from being called more than once every timeout seconds.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"A more typical callback might look like this:","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"test_x, test_y = # ... create single batch of test data ...\nevalcb() = @show(loss(test_x, test_y))\n\nFlux.train!(objective, ps, data, opt,\n            cb = throttle(evalcb, 5))","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"Calling Flux.stop() in a callback will exit the training loop early.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"cb = function ()\n  accuracy() > 0.9 && Flux.stop()\nend","category":"page"},{"location":"training/training/#Custom-Training-loops-1","page":"Training","title":"Custom Training loops","text":"","category":"section"},{"location":"training/training/#","page":"Training","title":"Training","text":"The Flux.train! function can be very convenient, especially for simple problems. Its also very flexible with the use of callbacks. But for some problems its much cleaner to write your own custom training loop. An example follows that works similar to the default Flux.train but with no callbacks. You don't need callbacks if you just code the calls to your functions directly into the loop. E.g. in the places marked with comments.","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"function my_custom_train!(loss, ps, data, opt)\n  ps = Params(ps)\n  for d in data\n    gs = gradient(ps) do\n      training_loss = loss(d...)\n      # Insert what ever code you want here that needs Training loss, e.g. logging\n      return training_loss\n    end\n    # insert what ever code you want here that needs gradient\n    # E.g. logging with TensorBoardLogger.jl as histogram so you can see if it is becoming huge\n    update!(opt, ps, gs)\n    # Here you might like to check validation set accuracy, and break out to do early stopping\n  end\nend","category":"page"},{"location":"training/training/#","page":"Training","title":"Training","text":"You could simplify this further, for example by hard-coding in the loss function.","category":"page"},{"location":"gpu/#GPU-Support-1","page":"GPU Support","title":"GPU Support","text":"","category":"section"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"NVIDIA GPU support should work out of the box on systems with CUDA and CUDNN installed. For more details see the CuArrays readme.","category":"page"},{"location":"gpu/#GPU-Usage-1","page":"GPU Support","title":"GPU Usage","text":"","category":"section"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"Support for array operations on other hardware backends, like GPUs, is provided by external packages like CuArrays. Flux is agnostic to array types, so we simply need to move model weights and data to the GPU and Flux will handle it.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"For example, we can use CuArrays (with the cu converter) to run our basic example on an NVIDIA GPU.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"(Note that you need to have CUDA available to use CuArrays – please see the CuArrays.jl instructions for more details.)","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"using CuArrays\n\nW = cu(rand(2, 5)) # a 2×5 CuArray\nb = cu(rand(2))\n\npredict(x) = W*x .+ b\nloss(x, y) = sum((predict(x) .- y).^2)\n\nx, y = cu(rand(5)), cu(rand(2)) # Dummy data\nloss(x, y) # ~ 3","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"Note that we convert both the parameters (W, b) and the data set (x, y) to cuda arrays. Taking derivatives and training works exactly as before.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"If you define a structured model, like a Dense layer or Chain, you just need to convert the internal parameters. Flux provides fmap, which allows you to alter all parameters of a model at once.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"d = Dense(10, 5, σ)\nd = fmap(cu, d)\nd.W # CuArray\nd(cu(rand(10))) # CuArray output\n\nm = Chain(Dense(10, 5, σ), Dense(5, 2), softmax)\nm = fmap(cu, m)\nd(cu(rand(10)))","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"As a convenience, Flux provides the gpu function to convert models and data to the GPU if one is available. By default, it'll do nothing, but loading CuArrays will cause it to move data to the GPU instead.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"julia> using Flux, CuArrays\n\njulia> m = Dense(10,5) |> gpu\nDense(10, 5)\n\njulia> x = rand(10) |> gpu\n10-element CuArray{Float32,1}:\n 0.800225\n ⋮\n 0.511655\n\njulia> m(x)\n5-element CuArray{Float32,1}:\n -0.30535\n ⋮\n -0.618002","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"The analogue cpu is also available for moving models and data back off of the GPU.","category":"page"},{"location":"gpu/#","page":"GPU Support","title":"GPU Support","text":"julia> x = rand(10) |> gpu\n10-element CuArray{Float32,1}:\n 0.235164\n ⋮\n 0.192538\n\njulia> x |> cpu\n10-element Array{Float32,1}:\n 0.235164\n ⋮\n 0.192538","category":"page"},{"location":"#Flux:-The-Julia-Machine-Learning-Library-1","page":"Home","title":"Flux: The Julia Machine Learning Library","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Flux is a library for machine learning. It comes \"batteries-included\" with many useful tools built in, but also lets you use the full power of the Julia language where you need it. We follow a few key principles:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"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.\nYou could have written Flux. All of it, from LSTMs to GPU kernels, is straightforward Julia code. When in doubt, it’s well worth looking at the source. If you need something different, you can easily roll your own.\nPlay nicely with others. Flux works well with Julia libraries from data frames and images to differential equation solvers, so you can easily build complex data processing pipelines that integrate Flux models.","category":"page"},{"location":"#Installation-1","page":"Home","title":"Installation","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Download Julia 1.0 or later, if you haven't already. You can add Flux from using Julia's package manager, by typing ] add Flux in the Julia prompt.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"If you have CUDA you can also run ] add CuArrays to get GPU support; see here for more details.","category":"page"},{"location":"#Learning-Flux-1","page":"Home","title":"Learning Flux","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"There are several different ways to learn Flux. If you just want to get started writing models, the model zoo gives good starting points for many common ones. This documentation provides a reference to all of Flux's APIs, as well as a from-scratch introduction to Flux's take on models and how they work. Once you understand these docs, congratulations, you also understand Flux's source code, which is intended to be concise, legible and a good reference for more advanced concepts.","category":"page"},{"location":"models/basics/#Model-Building-Basics-1","page":"Basics","title":"Model-Building Basics","text":"","category":"section"},{"location":"models/basics/#Taking-Gradients-1","page":"Basics","title":"Taking Gradients","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Flux's core feature is taking gradients of Julia code. The gradient function takes another Julia function f and a set of arguments, and returns the gradient with respect to each argument. (It's a good idea to try pasting these examples in the Julia terminal.)","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"julia> using Flux\n\njulia> f(x) = 3x^2 + 2x + 1;\n\njulia> df(x) = gradient(f, x)[1]; # df/dx = 6x + 2\n\njulia> df(2)\n14\n\njulia> d2f(x) = gradient(df, x)[1]; # d²f/dx² = 6\n\njulia> d2f(2)\n6","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"When a function has many parameters, we can get gradients of each one at the same time:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"julia> f(x, y) = sum((x .- y).^2);\n\njulia> gradient(f, [2, 1], [2, 0])\n([0, 2], [0, -2])","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"But machine learning models can have hundreds of parameters! To handle this, Flux lets you work with collections of parameters, via params. You can get the gradient of all parameters used in a program without explicitly passing them in.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"julia> using Flux\n\njulia> x = [2, 1];\n\njulia> y = [2, 0];\n\njulia> gs = gradient(params(x, y)) do\n         f(x, y)\n       end\nGrads(...)\n\njulia> gs[x]\n2-element Array{Int64,1}:\n 0\n 2\n\njulia> gs[y]\n2-element Array{Int64,1}:\n  0\n -2","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Here, gradient takes a zero-argument function; no arguments are necessary because the params tell it what to differentiate.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"This will come in really handy when dealing with big, complicated models. For now, though, let's start with something simple.","category":"page"},{"location":"models/basics/#Simple-Models-1","page":"Basics","title":"Simple Models","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Consider a simple linear regression, which tries to predict an output array y from an input x.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"W = rand(2, 5)\nb = rand(2)\n\npredict(x) = W*x .+ b\n\nfunction loss(x, y)\n  ŷ = predict(x)\n  sum((y .- ŷ).^2)\nend\n\nx, y = rand(5), rand(2) # Dummy data\nloss(x, y) # ~ 3","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"To improve the prediction we can take the gradients of W and b with respect to the loss and perform gradient descent.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"using Flux\n\ngs = gradient(() -> loss(x, y), params(W, b))","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Now that we have gradients, we can pull them out and update W to train the model.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"W̄ = gs[W]\n\nW .-= 0.1 .* W̄\n\nloss(x, y) # ~ 2.5","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"The loss has decreased a little, meaning that our prediction x is closer to the target y. If we have some data we can already try training the model.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"All deep learning in Flux, however complex, is a simple generalisation of this example. Of course, models can look very different – they might have millions of parameters or complex control flow. Let's see how Flux handles more complex models.","category":"page"},{"location":"models/basics/#Building-Layers-1","page":"Basics","title":"Building Layers","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"It's common to create more complex models than the linear regression above. For example, we might want to have two linear layers with a nonlinearity like sigmoid (σ) in between them. In the above style we could write this as:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"using Flux\n\nW1 = rand(3, 5)\nb1 = rand(3)\nlayer1(x) = W1 * x .+ b1\n\nW2 = rand(2, 3)\nb2 = rand(2)\nlayer2(x) = W2 * x .+ b2\n\nmodel(x) = layer2(σ.(layer1(x)))\n\nmodel(rand(5)) # => 2-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"This works but is fairly unwieldy, with a lot of repetition – especially as we add more layers. One way to factor this out is to create a function that returns linear layers.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"function linear(in, out)\n  W = randn(out, in)\n  b = randn(out)\n  x -> W * x .+ b\nend\n\nlinear1 = linear(5, 3) # we can access linear1.W etc\nlinear2 = linear(3, 2)\n\nmodel(x) = linear2(σ.(linear1(x)))\n\nmodel(rand(5)) # => 2-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Another (equivalent) way is to create a struct that explicitly represents the affine layer.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"struct Affine\n  W\n  b\nend\n\nAffine(in::Integer, out::Integer) =\n  Affine(randn(out, in), randn(out))\n\n# Overload call, so the object can be used as a function\n(m::Affine)(x) = m.W * x .+ m.b\n\na = Affine(10, 5)\n\na(rand(10)) # => 5-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Congratulations! You just built the Dense layer that comes with Flux. Flux has many interesting layers available, but they're all things you could have built yourself very easily.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"(There is one small difference with Dense – for convenience it also takes an activation function, like Dense(10, 5, σ).)","category":"page"},{"location":"models/basics/#Stacking-It-Up-1","page":"Basics","title":"Stacking It Up","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"It's pretty common to write models that look something like:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"layer1 = Dense(10, 5, σ)\n# ...\nmodel(x) = layer3(layer2(layer1(x)))","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"For long chains, it might be a bit more intuitive to have a list of layers, like this:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"using Flux\n\nlayers = [Dense(10, 5, σ), Dense(5, 2), softmax]\n\nmodel(x) = foldl((x, m) -> m(x), layers, init = x)\n\nmodel(rand(10)) # => 2-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Handily, this is also provided for in Flux:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"model2 = Chain(\n  Dense(10, 5, σ),\n  Dense(5, 2),\n  softmax)\n\nmodel2(rand(10)) # => 2-element vector","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"This quickly starts to look like a high-level deep learning library; yet you can see how it falls out of simple abstractions, and we lose none of the power of Julia code.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"A nice property of this approach is that because \"models\" are just functions (possibly with trainable parameters), you can also see this as simple function composition.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"m = Dense(5, 2) ∘ Dense(10, 5, σ)\n\nm(rand(10))","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Likewise, Chain will happily work with any Julia function.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"m = Chain(x -> x^2, x -> x+1)\n\nm(5) # => 26","category":"page"},{"location":"models/basics/#Layer-helpers-1","page":"Basics","title":"Layer helpers","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Flux provides a set of helpers for custom layers, which you can enable by calling","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Flux.@functor Affine","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"This enables a useful extra set of functionality for our Affine layer, such as collecting its parameters or moving it to the GPU.","category":"page"},{"location":"models/basics/#Utility-functions-1","page":"Basics","title":"Utility functions","text":"","category":"section"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Flux provides some utility functions to help you generate models in an automated fashion.","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"outdims enables you to calculate the spatial output dimensions of layers like Conv when applied to input images of a given size. Currently limited to the following layers:","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"Chain\nDense\nConv\nDiagonal\nMaxout\nConvTranspose\nDepthwiseConv\nCrossCor\nMaxPool\nMeanPool","category":"page"},{"location":"models/basics/#","page":"Basics","title":"Basics","text":"outdims","category":"page"},{"location":"data/onehot/#One-Hot-Encoding-1","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"","category":"section"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"It's common to encode categorical variables (like true, false or cat, dog) in \"one-of-k\" or \"one-hot\" form. Flux provides the onehot function to make this easy.","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"julia> using Flux: onehot, onecold\n\njulia> onehot(:b, [:a, :b, :c])\n3-element Flux.OneHotVector:\n false\n  true\n false\n\njulia> onehot(:c, [:a, :b, :c])\n3-element Flux.OneHotVector:\n false\n false\n  true","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"The inverse is onecold (which can take a general probability distribution, as well as just booleans).","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"julia> onecold(ans, [:a, :b, :c])\n:c\n\njulia> onecold([true, false, false], [:a, :b, :c])\n:a\n\njulia> onecold([0.3, 0.2, 0.5], [:a, :b, :c])\n:c","category":"page"},{"location":"data/onehot/#Batches-1","page":"One-Hot Encoding","title":"Batches","text":"","category":"section"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"onehotbatch creates a batch (matrix) of one-hot vectors, and onecold treats matrices as batches.","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"julia> using Flux: onehotbatch\n\njulia> onehotbatch([:b, :a, :b], [:a, :b, :c])\n3×3 Flux.OneHotMatrix:\n false   true  false\n  true  false   true\n false  false  false\n\njulia> onecold(ans, [:a, :b, :c])\n3-element Array{Symbol,1}:\n  :b\n  :a\n  :b","category":"page"},{"location":"data/onehot/#","page":"One-Hot Encoding","title":"One-Hot Encoding","text":"Note that these operations returned OneHotVector and OneHotMatrix rather than Arrays. OneHotVectors behave like normal vectors but avoid any unnecessary cost compared to using an integer index directly. For example, multiplying a matrix with a one-hot vector simply slices out the relevant row of the matrix under the hood.","category":"page"}]
 }
diff --git a/dev/training/optimisers/index.html b/dev/training/optimisers/index.html
index d0869be0..9affe30a 100644
--- a/dev/training/optimisers/index.html
+++ b/dev/training/optimisers/index.html
@@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 
 ga('create', 'UA-36890222-9', 'auto');
 ga('send', 'pageview');
-
      Optimisers
      Optimisers
      Consider a simple linear regression. We create some dummy data, calculate a loss, and backpropagate to calculate gradients for the parameters W and b.
      using Flux
+
      Optimisers
      Optimisers
      Consider a simple linear regression. We create some dummy data, calculate a loss, and backpropagate to calculate gradients for the parameters W and b.
      using Flux
 
 W = rand(2, 5)
 b = rand(2)
@@ -18,7 +18,7 @@ x, y = rand(5), rand(2) # Dummy data
 l = loss(x, y) # ~ 3
 
 θ = Params([W, b])
-grads = gradient(() -> loss(x, y), θ)
      We want to update each parameter, using the gradient, in order to improve (reduce) the loss. Here's one way to do that:
      using Flux: update!
+grads = gradient(() -> loss(x, y), θ)
      We want to update each parameter, using the gradient, in order to improve (reduce) the loss. Here's one way to do that:
      using Flux.Optimise: update!
 
 η = 0.1 # Learning Rate
 for p in (W, b)
@@ -27,7 +27,8 @@ end
      Running this will alter the parameters W and 
      An optimiser update! accepts a parameter and a gradient, and updates the parameter according to the chosen rule. We can also pass opt to our training loop, which will update all parameters of the model in a loop. However, we can now easily replace Descent with a more advanced optimiser such as ADAM.
      Optimiser Reference
      All optimisers return an object that, when passed to train!, will update the parameters passed to it.
      Flux.Optimise.Descent — Type.
      Descent(η)
      Classic gradient descent optimiser with learning rate η. For each parameter p and its gradient δp, this runs p -= η*δp
      Parameters
      • Learning Rate (η): The amount by which the gradients are discounted before updating the weights. Defaults to 0.1.
      Example
      opt = Descent() # uses default η (0.1)
+end
      An optimiser update! accepts a parameter and a gradient, and updates the parameter according to the chosen rule. We can also pass opt to our training loop, which will update all parameters of the model in a loop. However, we can now easily replace Descent with a more advanced optimiser such as ADAM.
      Optimiser Reference
      All optimisers return an object that, when passed to train!, will update the parameters passed to it.
      Flux.Optimise.update! — Function.
      update!(opt, p, g)
+update!(opt, ps::Params, gs)
      Perform an update step of the parameters ps (or the single parameter p)  according to optimizer opt  and the gradients gs (the gradient g).
      As a result, the parameters are mutated and the optimizer's internal state may change. 
      update!(x, x̄)
      Update the array x according to x .-= x̄.
      source
      Flux.Optimise.Descent — Type.
      Descent(η)
      Classic gradient descent optimiser with learning rate η. For each parameter p and its gradient δp, this runs p -= η*δp
      Parameters
      • Learning Rate (η): The amount by which the gradients are discounted before updating the weights. Defaults to 0.1.
      Example
      opt = Descent() # uses default η (0.1)
 
 opt = Descent(0.3) # use provided η
 
@@ -37,23 +38,23 @@ gs = gradient(ps) do
   loss(x, y)
 end
 
-Flux.Optimise.update!(opt, ps, gs)
      source
      Flux.Optimise.Momentum — Type.
      Momentum(η, ρ)
      Gradient descent with learning rate η and momentum ρ.
      Parameters
      • Learning Rate (η): Amount by which gradients are discounted before updating the weights. Defaults to 0.01.
      • Momentum (ρ): Parameter that accelerates descent in the relevant direction and dampens oscillations. Defaults to 0.9.
      Examples
      opt = Momentum() # uses defaults of η = 0.01 and ρ = 0.9
+Flux.Optimise.update!(opt, ps, gs)
      source
      Flux.Optimise.Momentum — Type.
      Momentum(η, ρ)
      Gradient descent with learning rate η and momentum ρ.
      Parameters
      • Learning Rate (η): Amount by which gradients are discounted before updating the weights. Defaults to 0.01.
      • Momentum (ρ): Parameter that accelerates descent in the relevant direction and dampens oscillations. Defaults to 0.9.
      Examples
      opt = Momentum() # uses defaults of η = 0.01 and ρ = 0.9
 
-opt = Momentum(0.01, 0.99)
      source
      Flux.Optimise.Nesterov — Type.
      Nesterov(η, ρ)
      Gradient descent with learning rate  η and Nesterov momentum ρ.
      Parameters
      • Learning Rate (η): Amount by which the gradients are dicsounted berfore updating the weights. Defaults to 0.001.
      • Nesterov Momentum (ρ): Paramters controlling the amount of nesterov momentum to be applied. Defaults to 0.9.
      Examples
      opt = Nesterov() # uses defaults η = 0.001 and ρ = 0.9
+opt = Momentum(0.01, 0.99)
      source
      Flux.Optimise.Nesterov — Type.
      Nesterov(η, ρ)
      Gradient descent with learning rate  η and Nesterov momentum ρ.
      Parameters
      • Learning Rate (η): Amount by which the gradients are dicsounted berfore updating the weights. Defaults to 0.001.
      • Nesterov Momentum (ρ): Parameters controlling the amount of nesterov momentum to be applied. Defaults to 0.9.
      Examples
      opt = Nesterov() # uses defaults η = 0.001 and ρ = 0.9
 
-opt = Nesterov(0.003, 0.95)
      source
      Flux.Optimise.RMSProp — Type.
      RMSProp(η, ρ)
      Implements the RMSProp algortihm. Often a good choice for recurrent networks. Paramters other than learning rate generally don't need tuning.
      Parameters
      • Learning Rate (η): Defaults to 0.001.
      • Rho (ρ): Defaults to 0.9.
      Examples
      opt = RMSProp() # uses default η = 0.001 and ρ = 0.9
+opt = Nesterov(0.003, 0.95)
      source
      Flux.Optimise.RMSProp — Type.
      RMSProp(η, ρ)
      Implements the RMSProp algortihm. Often a good choice for recurrent networks. Parameters other than learning rate generally don't need tuning.
      Parameters
      • Learning Rate (η): Defaults to 0.001.
      • Rho (ρ): Defaults to 0.9.
      Examples
      opt = RMSProp() # uses default η = 0.001 and ρ = 0.9
 
-opt = RMSProp(0.002, 0.95)
      References
      RMSProp
      source
      Flux.Optimise.ADAM — Type.
      ADAM(η, β::Tuple)
      Implements the ADAM optimiser.
      Paramters
      • Learning Rate (η): Defaults to 0.001.
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      Examples
      opt = ADAM() # uses the default η = 0.001 and β = (0.9, 0.999)
+opt = RMSProp(0.002, 0.95)
      References
      RMSProp
      source
      Flux.Optimise.ADAM — Type.
      ADAM(η, β::Tuple)
      Implements the ADAM optimiser.
      Paramters
      • Learning Rate (η): Defaults to 0.001.
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      Examples
      opt = ADAM() # uses the default η = 0.001 and β = (0.9, 0.999)
 
-opt = ADAM(0.001, (0.9, 0.8))
      References
      ADAM optimiser.
      source
      Flux.Optimise.AdaMax — Type.
      AdaMax(η, β::Tuple)
      Variant of ADAM based on ∞-norm.
      Parameters
      • Learning Rate (η): Defaults to 0.001
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      Examples
      opt = AdaMax() # uses default η and β
+opt = ADAM(0.001, (0.9, 0.8))
      References
      ADAM optimiser.
      source
      Flux.Optimise.AdaMax — Type.
      AdaMax(η, β::Tuple)
      Variant of ADAM based on ∞-norm.
      Parameters
      • Learning Rate (η): Defaults to 0.001
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      Examples
      opt = AdaMax() # uses default η and β
 
-opt = AdaMax(0.001, (0.9, 0.995))
      References
      AdaMax optimiser.
      source
      Flux.Optimise.ADAGrad — Type.
      ADAGrad(η)
      Implements AdaGrad. It has parameter specific learning rates based on how frequently it is updated.
      Parameters
      • Learning Rate (η): Defaults to 0.1
      Examples
      opt = ADAGrad() # uses default η = 0.1
+opt = AdaMax(0.001, (0.9, 0.995))
      References
      AdaMax optimiser.
      source
      Flux.Optimise.ADAGrad — Type.
      ADAGrad(η)
      Implements AdaGrad. It has parameter specific learning rates based on how frequently it is updated.
      Parameters
      • Learning Rate (η): Defaults to 0.1
      Examples
      opt = ADAGrad() # uses default η = 0.1
 
-opt = ADAGrad(0.001)
      References
      ADAGrad optimiser. Parameters don't need tuning.
      source
      Flux.Optimise.ADADelta — Type.
      ADADelta(ρ)
      Version of ADAGrad that adapts learning rate based on a window of past gradient updates. Parameters don't need tuning.
      Parameters
      • Rho (ρ): Factor by which gradient is decayed at each time step. Defaults to 0.9.
      Examples
      opt = ADADelta() # uses default ρ = 0.9
-opt = ADADelta(0.89)
      References
      ADADelta optimiser.
      source
      Flux.Optimise.AMSGrad — Type.
      AMSGrad(η, β::Tuple)
      Implements AMSGrad version of the ADAM optimiser. Parameters don't need tuning.
      Parameters
      • Learning Rate (η): Defaults to 0.001.
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      Examples
      opt = AMSGrad() # uses default η and β
-opt = AMSGrad(0.001, (0.89, 0.995))
      References
      AMSGrad optimiser.
      source
      Flux.Optimise.NADAM — Type.
      NADAM(η, β::Tuple)
      Nesterov variant of ADAM. Parameters don't need tuning.
      Parameters
      • Learning Rate (η): Defaults to 0.001.
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      Examples
      opt = NADAM() # uses default η and β
-opt = NADAM(0.002, (0.89, 0.995))
      References
      NADAM optimiser.
      source
      Flux.Optimise.ADAMW — Function.
      ADAMW(η, β::Tuple, decay)
      Variant of ADAM defined by fixing weight decay regularization.
      Parameters
      • Learning Rate (η): Defaults to 0.001.
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      • decay: Decay applied to weights during optimisation. Defaults to 0.
      Examples
      opt = ADAMW() # uses default η, β and decay
-opt = ADAMW(0.001, (0.89, 0.995), 0.1)
      References
      ADAMW
      source
      Optimiser Interface
      Flux's optimsers are built around a struct that holds all the optimiser parameters along with a definition of how to apply the update rule associated with it. We do this via the apply! function which takes the optimiser as the first argument followed by the parameter and its corresponding gradient.
      In this manner Flux also allows one to create custom optimisers to be used seamlessly. Let's work this with a simple example.
      mutable struct Momentum
+opt = ADAGrad(0.001)
      References
      ADAGrad optimiser. Parameters don't need tuning.
      source
      Flux.Optimise.ADADelta — Type.
      ADADelta(ρ)
      Version of ADAGrad that adapts learning rate based on a window of past gradient updates. Parameters don't need tuning.
      Parameters
      • Rho (ρ): Factor by which gradient is decayed at each time step. Defaults to 0.9.
      Examples
      opt = ADADelta() # uses default ρ = 0.9
+opt = ADADelta(0.89)
      References
      ADADelta optimiser.
      source
      Flux.Optimise.AMSGrad — Type.
      AMSGrad(η, β::Tuple)
      Implements AMSGrad version of the ADAM optimiser. Parameters don't need tuning.
      Parameters
      • Learning Rate (η): Defaults to 0.001.
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      Examples
      opt = AMSGrad() # uses default η and β
+opt = AMSGrad(0.001, (0.89, 0.995))
      References
      AMSGrad optimiser.
      source
      Flux.Optimise.NADAM — Type.
      NADAM(η, β::Tuple)
      Nesterov variant of ADAM. Parameters don't need tuning.
      Parameters
      • Learning Rate (η): Defaults to 0.001.
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      Examples
      opt = NADAM() # uses default η and β
+opt = NADAM(0.002, (0.89, 0.995))
      References
      NADAM optimiser.
      source
      Flux.Optimise.ADAMW — Function.
      ADAMW(η, β::Tuple, decay)
      Variant of ADAM defined by fixing weight decay regularization.
      Parameters
      • Learning Rate (η): Defaults to 0.001.
      • Beta (β::Tuple): The first element refers to β1 and the second to β2. Defaults to (0.9, 0.999).
      • decay: Decay applied to weights during optimisation. Defaults to 0.
      Examples
      opt = ADAMW() # uses default η, β and decay
+opt = ADAMW(0.001, (0.89, 0.995), 0.1)
      References
      ADAMW
      source
      Optimiser Interface
      Flux's optimisers are built around a struct that holds all the optimiser parameters along with a definition of how to apply the update rule associated with it. We do this via the apply! function which takes the optimiser as the first argument followed by the parameter and its corresponding gradient.
      In this manner Flux also allows one to create custom optimisers to be used seamlessly. Let's work this with a simple example.
      mutable struct Momentum
   eta
   rho
   velocity
@@ -65,7 +66,7 @@ Momentum(eta::Real, rho::Real) = Momentum(eta, rho, IdDict())
      The
   @. v = ρ * v - η * Δ
   @. Δ = -v
 end
      This is the basic definition of a Momentum update rule given by:
      \[v = ρ * v - η * Δ
-w = w - v\]
      The apply! defines the update rules for an optimiser opt, given the parameters and gradients. It returns the updated gradients. Here, every parameter x is retrieved from the running state v and subsequently updates the state of the optimiser.
      Flux internally calls on this function via the update! function. It shares the API with apply! but ensures that multiple parameters are handled gracefully.
      Composing Optimisers
      Flux defines a special kind of optimiser called simply as Optimiser which takes in a arbitrary optimisers as input. Its behaviour is similar to the usual optimisers, but differs in that it acts by calling the optimisers listed in it sequentially. Each optimiser produces a modified gradient that will be fed into the next, and the resultant update will be applied to the parameter as usual. A classic use case is where adding decays is desirable. Flux defines some basic decays including ExpDecay, InvDecay etc.
      opt = Optimiser(ExpDecay(0.001, 0.1, 1000, 1e-4), Descent())
      Here we apply exponential decay to the Descent optimser. The defaults of ExpDecay say that its learning rate will be decayed every 1000 steps. It is then applied like any optimser.
      w = randn(10, 10)
+w = w - v\]
      The apply! defines the update rules for an optimiser opt, given the parameters and gradients. It returns the updated gradients. Here, every parameter x is retrieved from the running state v and subsequently updates the state of the optimiser.
      Flux internally calls on this function via the update! function. It shares the API with apply! but ensures that multiple parameters are handled gracefully.
      Composing Optimisers
      Flux defines a special kind of optimiser simply called Optimiser which takes in arbitrary optimisers as input. Its behaviour is similar to the usual optimisers, but differs in that it acts by calling the optimisers listed in it sequentially. Each optimiser produces a modified gradient that will be fed into the next, and the resultant update will be applied to the parameter as usual. A classic use case is where adding decays is desirable. Flux defines some basic decays including ExpDecay, InvDecay etc.
      opt = Optimiser(ExpDecay(0.001, 0.1, 1000, 1e-4), Descent())
      Here we apply exponential decay to the Descent optimiser. The defaults of ExpDecay say that its learning rate will be decayed every 1000 steps. It is then applied like any optimiser.
      w = randn(10, 10)
 w1 = randn(10,10)
 ps = Params([w, w1])
 
@@ -79,10 +80,5 @@ for t = 1:10^5
   Flux.Optimise.update!(opt, θ, θ̄)
 end
 
-loss(rand(10)) # around 0.9
      In this manner it is possible to compose optimisers for some added flexibility.
      Decays
      Similar to optimisers, Flux also defines some simple decays that can be used in conjunction with other optimisers, or standalone.
      Flux.Optimise.ExpDecay — Type.
      ExpDecay(eta, decay, decay_step, clip)
      Discount the learning rate eta by a multiplicative factor decay every decay_step till a minimum of clip.
      Parameters
      • Learning Rate (eta): Defaults to 0.001.
      • decay: Factor by which the learning rate is discounted. Defaults to 0.1.
      • decay_step: Schedules decay operations by setting number of steps between two decay operations. Defaults to 1000.
      • clip: Minimum value of learning rate. Defaults to 1e-4.
      Example
      To apply exponential decay to an optimiser:
        Optimiser(ExpDecay(..), Opt(..))
-
-  opt = Optimiser(ExpDecay(), ADAM())
      source
      Flux.Optimise.InvDecay — Type.
      InvDecay(γ)
      Applies inverse time decay to an optimiser, i.e., the effective step size at iteration n is eta / (1 + γ * n) where eta is the initial step size. The wrapped optimiser's step size is not modified.
      
-## Parameters
-  - gamma (γ): Defaults to `0.001`
-
-## Example
      julia   Optimiser(InvDecay(..), Opt(..)) ```
      source
      Flux.Optimise.WeightDecay — Type.
      WeightDecay(wd)
      Decays the weight by wd
      Parameters
      • weight decay (wd): 0
      source
      
+loss(rand(10)) # around 0.9
      In this manner it is possible to compose optimisers for some added flexibility.
      Decays
      Similar to optimisers, Flux also defines some simple decays that can be used in conjunction with other optimisers, or standalone.
      Flux.Optimise.ExpDecay — Type.
      ExpDecay(eta, decay, decay_step, clip)
      Discount the learning rate eta by a multiplicative factor decay every decay_step till a minimum of clip.
      Parameters
      • Learning Rate (eta): Defaults to 0.001.
      • decay: Factor by which the learning rate is discounted. Defaults to 0.1.
      • decay_step: Schedules decay operations by setting number of steps between two decay operations. Defaults to 1000.
      • clip: Minimum value of learning rate. Defaults to 1e-4.
      Example
      To apply exponential decay to an optimiser:
      Optimiser(ExpDecay(..), Opt(..))
+opt = Optimiser(ExpDecay(), ADAM())
      source
      Flux.Optimise.InvDecay — Type.
      InvDecay(γ)
      Applies inverse time decay to an optimiser, i.e., the effective step size at iteration n is eta / (1 + γ * n) where eta is the initial step size. The wrapped optimiser's step size is not modified.
      Parameters
      • gamma (γ): Defaults to 0.001
      Example
      Optimiser(InvDecay(..), Opt(..))
      source
      Flux.Optimise.WeightDecay — Type.
      WeightDecay(wd)
      Decays the weight by wd
      Parameters
      • weight decay (wd): 0
      source
      
diff --git a/dev/training/training/index.html b/dev/training/training/index.html
index 84bcc412..cfff4b2d 100644
--- a/dev/training/training/index.html
+++ b/dev/training/training/index.html
@@ -6,7 +6,7 @@ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 
 ga('create', 'UA-36890222-9', 'auto');
 ga('send', 'pageview');
-
      Training
      Training
      To actually train a model we need four things:
      • A objective function, that evaluates how well a model is doing given some input data.
      • The trainable parameters of the model.
      • A collection of data points that will be provided to the objective function.
      • An optimiser that will update the model parameters appropriately.
      With these we can call Flux.train!:
      Flux.train!(objective, params, data, opt)
      There are plenty of examples in the model zoo.
      Loss Functions
      The objective function must return a number representing how far the model is from its target – the loss of the model. The loss function that we defined in basics will work as an objective. We can also define an objective in terms of some model:
      m = Chain(
+
      Training
      Training
      To actually train a model we need four things:
      • A objective function, that evaluates how well a model is doing given some input data.
      • The trainable parameters of the model.
      • A collection of data points that will be provided to the objective function.
      • An optimiser that will update the model parameters appropriately.
      With these we can call train!:
      Flux.Optimise.train! — Function.
      train!(loss, params, data, opt; cb)
      For each datapoint d in data computes the gradient of loss(d...) through backpropagation and calls the optimizer opt.
      In case datapoints d are of numeric array type, assumes no splatting is needed  and computes the gradient of loss(d).
      Takes a callback as keyword argument cb. For example, this will print "training" every 10 seconds:
      train!(loss, params, data, opt,          cb = throttle(() -> println("training"), 10))
      The callback can call Flux.stop() to interrupt the training loop.
      Multiple optimisers and callbacks can be passed to opt and cb as arrays.
      source
      There are plenty of examples in the model zoo.
      Loss Functions
      The objective function must return a number representing how far the model is from its target – the loss of the model. The loss function that we defined in basics will work as an objective. We can also define an objective in terms of some model:
      m = Chain(
   Dense(784, 32, σ),
   Dense(32, 10), softmax)
 
@@ -18,9 +18,12 @@ Flux.train!(loss, ps, data, opt)
      The objective will almost always
 y = rand(10)
 data = [(x, y)]
      Flux.train! will call loss(x, y), calculate gradients, update the weights and then move on to the next data point if there is one. We can train the model on the same data three times:
      data = [(x, y), (x, y), (x, y)]
 # Or equivalently
-data = Iterators.repeated((x, y), 3)
      It's common to load the xs and ys separately. In this case you can use zip:
      xs = [rand(784), rand(784), rand(784)]
+using IterTools: ncycle
+data = ncycle([(x, y)], 3)
      It's common to load the xs and ys separately. In this case you can use zip:
      xs = [rand(784), rand(784), rand(784)]
 ys = [rand( 10), rand( 10), rand( 10)]
-data = zip(xs, ys)
      Note that, by default, train! only loops over the data once (a single "epoch"). A convenient way to run multiple epochs from the REPL is provided by @epochs.
      julia> using Flux: @epochs
+data = zip(xs, ys)
      Training data can be conveniently  partitioned for mini-batch training using the Flux.Data.DataLoader type:
      X = rand(28, 28, 60000)
+Y = rand(0:9, 60000)
+data = DataLoader(X, Y, batchsize=128) 
      Note that, by default, train! only loops over the data once (a single "epoch"). A convenient way to run multiple epochs from the REPL is provided by @epochs.
      julia> using Flux: @epochs
 
 julia> @epochs 2 println("hello")
 INFO: Epoch 1
@@ -35,7 +38,7 @@ evalcb() = @show(loss(test_x, test_y))
 Flux.train!(objective, ps, data, opt,
             cb = throttle(evalcb, 5))
      Calling Flux.stop() in a callback will exit the training loop early.
      cb = function ()
   accuracy() > 0.9 && Flux.stop()
-end
      Custom Training loops
      The Flux.train! function can be very convenient, especially for simple problems. Its also very flexible with the use of callbacks. But for some problems its much cleaner to write your own custom training loop. An example follows that works similar to the default Flux.train but with no callbacks. You don't need callbacks if you just code the calls to your functions directly into the loop. E.g. in the places marked with comments.
      function my_custom_train!(loss, ps, data, opt)
+end
      Custom Training loops
      The Flux.train! function can be very convenient, especially for simple problems. Its also very flexible with the use of callbacks. But for some problems its much cleaner to write your own custom training loop. An example follows that works similar to the default Flux.train but with no callbacks. You don't need callbacks if you just code the calls to your functions directly into the loop. E.g. in the places marked with comments.
      function my_custom_train!(loss, ps, data, opt)
   ps = Params(ps)
   for d in data
     gs = gradient(ps) do
@@ -48,4 +51,4 @@ end
      PreviousOptimisers
      
+end

      You could simplify this further, for example by hard-coding in the loss function.