## Basic Layers

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

Flux.ChainType
Chain(layers...)

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

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.

Examples

julia> m = Chain(x -> x^2, x -> x+1);

julia> m(5) == 26
true

julia> m = Chain(Dense(10, 5), Dense(5, 2));

julia> x = rand(10);

julia> m(x) == m[2](m[1](x))
true
source
Flux.DenseType
Dense(in::Integer, out::Integer, σ = identity)

Create 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.

Examples

jldoctest; setup = :(using Random; Random.seed!(0)) julia> d = Dense(5, 2) Dense(5, 2)

julia> d(rand(5)) 2-element Array{Float32,1}: -0.16210233 0.12311903

source

## Convolution and Pooling Layers

These layers are used to build convolutional neural networks (CNNs).

Flux.ConvType
Conv(size, in => out, σ = identity; init = glorot_uniform,
stride = 1, pad = 0, dilation = 1)

Standard convolutional 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 (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.

Examples

Apply a Conv layer to a 1-channel input using a 2×2 window size, giving us a 16-channel output. Output is activated with ReLU.

size = (2,2)
in = 1
out = 16
Conv(size, in => out, relu)
source
Flux.MaxPoolType
MaxPool(k; pad = 0, stride = k)

Max pooling layer. k is the size of the window for each dimension of the input.

source
Flux.GlobalMaxPoolType
GlobalMaxPool()

Global max pooling layer.

Transforms (w,h,c,b)-shaped input into (1,1,c,b)-shaped output, by performing max pooling on the complete (w,h)-shaped feature maps.

source
Flux.MeanPoolType
MeanPool(k; pad = 0, stride = k)

Mean pooling layer. k is the size of the window for each dimension of the input.

source
Flux.GlobalMeanPoolType
GlobalMeanPool()

Global mean pooling layer.

Transforms (w,h,c,b)-shaped input into (1,1,c,b)-shaped output, by performing mean pooling on the complete (w,h)-shaped feature maps.

source
Flux.DepthwiseConvType
DepthwiseConv(size, in => out, σ = identity; init = glorot_uniform,
stride = 1, pad = 0, dilation = 1)

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 (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.

source
Flux.ConvTransposeType
ConvTranspose(size, in => out, σ = identity; init = glorot_uniform,
stride = 1, pad = 0, dilation = 1)

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 (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.

source
Flux.CrossCorType
CrossCor(size, in => out, σ = identity; init = glorot_uniform,
stride = 1, pad = 0, dilation = 1)

Standard cross convolutional 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 (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.

Examples

Apply a CrossCor layer to a 1-channel input using a 2×2 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)
source
Flux.flattenFunction
flatten(x::AbstractArray)

Transform (w, h, c, b)-shaped input into (w × h × c, b)-shaped output by linearizing all values for each element in the batch.

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.RNNFunction
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.RecurType
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
Flux.reset!Function
reset!(rnn)

Reset the hidden state of a recurrent layer back to its original value.

Assuming you have a Recur layer rnn, this is roughly equivalent to:

rnn.state = hidden(rnn.cell)
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.MaxoutType
Maxout(over)

The Maxout layer has a number of internal layers which all receive the same input. It returns the elementwise maximum of the internal layers' outputs.

Maxout over linear dense layers satisfies the univeral approximation theorem.

source
Flux.SkipConnectionType
SkipConnection(layer, connection)

Create a skip connection which consists of a layer or Chain of consecutive layers and a shortcut connection linking the block's input to the output through a user-supplied 2-argument callable. The first argument to the callable will be propagated through the given layer while the second is the unchanged, "skipped" input.

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

## Normalisation & Regularisation

These layers don't affect the structure of the network but may improve training times or reduce overfitting.

Flux.normaliseFunction
normalise(x; dims=1)

Normalise x to mean 0 and standard deviation 1 across the dimensions given by dims. Defaults to normalising over columns.

julia> a = reshape(collect(1:9), 3, 3)
3×3 Array{Int64,2}:
1  4  7
2  5  8
3  6  9

julia> Flux.normalise(a)
3×3 Array{Float64,2}:
-1.22474  -1.22474  -1.22474
0.0       0.0       0.0
1.22474   1.22474   1.22474

julia> Flux.normalise(a, dims=2)
3×3 Array{Float64,2}:
-1.22474  0.0  1.22474
-1.22474  0.0  1.22474
-1.22474  0.0  1.22474
source
Flux.BatchNormType
BatchNorm(channels::Integer, σ = identity;
initβ = zeros, initγ = ones,
ϵ = 1e-8, momentum = .1)

Batch Normalization layer. channels 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.

Examples

m = Chain(
Dense(28^2, 64),
BatchNorm(64, relu),
Dense(64, 10),
BatchNorm(10),
softmax)
source
Flux.dropoutFunction
dropout(x, p; dims = :)

The dropout function. For each input, either sets that input to 0 (with probability p) or scales it by 1 / (1 - p). dims specifies the unbroadcasted dimensions, e.g. dims=1 applies dropout along columns and dims=2 along rows. This is used as a regularisation, i.e. it reduces overfitting during training.

See also the Dropout layer.

source
Flux.LayerNormType
LayerNorm(h::Integer)

A normalisation layer designed to be used with recurrent hidden states of size h. Normalises the mean and standard deviation of each input before applying a per-neuron gain/bias.

source
Flux.InstanceNormType
InstanceNorm(channels::Integer, σ = identity;
initβ = zeros, initγ = ones,
ϵ = 1e-8, momentum = .1)

Instance Normalization layer. channels 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.)

InstanceNorm computes the mean and variance for each each W×H×1×1 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.

Examples

m = Chain(
Dense(28^2, 64),
InstanceNorm(64, relu),
Dense(64, 10),
InstanceNorm(10),
softmax)
source
Flux.GroupNormType
GroupNorm(chs::Integer, G::Integer, λ = identity;
initβ = (i) -> zeros(Float32, i), initγ = (i) -> ones(Float32, i),
ϵ = 1f-5, momentum = 0.1f0)

Group Normalization layer. This layer can outperform Batch Normalization and Instance Normalization.

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

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

Use testmode! during inference.

Examples

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
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 Flux.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.maeFunction
mae(ŷ, y)

Return the mean of absolute error; calculated as sum(abs.(ŷ .- y)) / length(y).

source
Flux.mseFunction
mse(ŷ, y)

Return the mean squared error between ŷ and y; calculated as sum((ŷ .- y).^2) / length(y).

Examples

julia> Flux.mse([0, 2], [1, 1])
1//1
source
Flux.msleFunction
msle(ŷ, y; ϵ=eps(eltype(ŷ)))

Return the mean of the squared logarithmic errors; calculated as sum((log.(ŷ .+ ϵ) .- log.(y .+ ϵ)).^2) / length(y). The ϵ term provides numerical stability.

Penalizes an under-predicted estimate greater than an over-predicted estimate.

source
Flux.huber_lossFunction
huber_loss(ŷ, y; δ=1.0)

Return the mean of the Huber loss given the prediction ŷ and true values y.

             | 0.5 * |ŷ - y|,            for |ŷ - y| <= δ
Huber loss = |
|  δ * (|ŷ - y| - 0.5 * δ), otherwise
source
Flux.crossentropyFunction
crossentropy(ŷ, y; weight = nothing)

Return the cross entropy between the given probability distributions; calculated as -sum(y .* log.(ŷ) .* weight) / size(y, 2).

weight can be Nothing, a Number or an AbstractVector. weight=nothing acts like weight=1 but is faster.

Examples

julia> Flux.crossentropy(softmax([-1.1491, 0.8619, 0.3127]), [1, 1, 0])
3.085467254747739
source
Flux.logitcrossentropyFunction
logitcrossentropy(ŷ, y; weight = 1)

Return the crossentropy computed after a Flux.logsoftmax operation; calculated as -sum(y .* logsoftmax(ŷ) .* weight) / size(y, 2).

logitcrossentropy(ŷ, y) is mathematically equivalent to Flux.crossentropy(softmax(log(ŷ)), y) but it is more numerically stable.

Examples

julia> Flux.logitcrossentropy([-1.1491, 0.8619, 0.3127], [1, 1, 0])
3.085467254747738
source
Flux.binarycrossentropyFunction
binarycrossentropy(ŷ, y; ϵ=eps(ŷ))

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

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

Examples

julia> Flux.binarycrossentropy.(σ.([-1.1491, 0.8619, 0.3127]), [1, 1, 0])
3-element Array{Float64,1}:
1.424397097347566
0.35231664672364077
0.8616703662235441
source
Flux.kldivergenceFunction
kldivergence(ŷ, y)

Return the Kullback-Leibler divergence between the given probability distributions.

KL divergence 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.

source
Flux.poissonFunction
poisson(ŷ, y)

Return how much the predicted distribution ŷ diverges from the expected Poisson distribution y; calculated as sum(ŷ .- y .* log.(ŷ)) / size(y, 2).

source
Flux.squared_hingeFunction
squared_hinge(ŷ, y)

Return the squared hinge loss given the prediction ŷ and true labels y (containing 1 or -1); calculated as sum((max.(0, 1 .- ŷ .* y)).^2) / size(y, 2).

See also: hinge

source
Flux.dice_coeff_lossFunction
dice_coeff_loss(ŷ, y; smooth=1)

Return a loss based on the dice coefficient. Used in the V-Net image segmentation architecture. Similar to the F1_score. Calculated as: 1 - 2sum(|ŷ . y| + smooth) / (sum(ŷ.^2) + sum(y.^2) + smooth)

source
Flux.tversky_lossFunction
tversky_loss(ŷ, y; β=0.7)

Return the Tversky loss. Used with imbalanced data to give more weight to false negatives. Larger β weigh recall higher than precision (by placing more emphasis on false negatives) Calculated as: 1 - sum(|y .* ŷ| + 1) / (sum(y .* ŷ + β(1 .- y) . ŷ + (1 - β)y . (1 .- ŷ)) + 1)

source