|
| 1 | +# Defining Your Own Flow Layer |
| 2 | + |
| 3 | +In practice, user might want to define their own normalizing flow. |
| 4 | +As briefly noted in [What are normalizing flows?](@ref), the key is to define a |
| 5 | +customized normalizing flow layer, including its transformation and inverse, |
| 6 | +as well as the log-determinant of the Jacobian of the transformation. |
| 7 | +`Bijectors.jl` offers a convenient interface to define a customized bijection. |
| 8 | +We refer users to [the documentation of |
| 9 | +`Bijectors.jl`](https://turinglang.org/Bijectors.jl/dev/transforms/#Implementing-a-transformation) |
| 10 | +for more details. |
| 11 | +`Flux.jl` is also a useful package, offering a convenient interface to define neural networks. |
| 12 | + |
| 13 | + |
| 14 | +In this tutorial, we demonstrate how to define a customized normalizing flow |
| 15 | +layer -- an `Affine Coupling Layer` (Dinh *et al.*, 2016) -- using `Bijectors.jl` and `Flux.jl`. |
| 16 | + |
| 17 | +## Affine Coupling Flow |
| 18 | + |
| 19 | +Given an input vector $\boldsymbol{x}$, the general *coupling transformation* splits it into two |
| 20 | +parts: $\boldsymbol{x}_{I_1}$ and $\boldsymbol{x}_{I\setminus I_1}$. Only one |
| 21 | +part (e.g., $\boldsymbol{x}_{I_1}$) undergoes a bijective transformation $f$, noted as the *coupling law*, |
| 22 | +based on the values of the other part (e.g., $\boldsymbol{x}_{I\setminus I_1}$), which remains unchanged. |
| 23 | +```math |
| 24 | +\begin{array}{llll} |
| 25 | +c_{I_1}(\cdot ; f, \theta): & \mathbb{R}^d \rightarrow \mathbb{R}^d & c_{I_1}^{-1}(\cdot ; f, \theta): & \mathbb{R}^d \rightarrow \mathbb{R}^d \\ |
| 26 | +& \boldsymbol{x}_{I \backslash I_1} \mapsto \boldsymbol{x}_{I \backslash I_1} & & \boldsymbol{y}_{I \backslash I_1} \mapsto \boldsymbol{y}_{I \backslash I_1} \\ |
| 27 | +& \boldsymbol{x}_{I_1} \mapsto f\left(\boldsymbol{x}_{I_1} ; \theta\left(\boldsymbol{x}_{I\setminus I_1}\right)\right) & & \boldsymbol{y}_{I_1} \mapsto f^{-1}\left(\boldsymbol{y}_{I_1} ; \theta\left(\boldsymbol{y}_{I\setminus I_1}\right)\right) |
| 28 | +\end{array} |
| 29 | +``` |
| 30 | +Here $\theta$ can be an arbitrary function, e.g., a neural network. |
| 31 | +As long as $f(\cdot; \theta(\boldsymbol{x}_{I\setminus I_1}))$ is invertible, $c_{I_1}$ is invertible, and the |
| 32 | +Jacobian determinant of $c_{I_1}$ is easy to compute: |
| 33 | +```math |
| 34 | +\left|\text{det} \nabla_x c_{I_1}(x)\right| = \left|\text{det} \nabla_{x_{I_1}} f(x_{I_1}; \theta(x_{I\setminus I_1}))\right| |
| 35 | +``` |
| 36 | + |
| 37 | +The affine coupling layer is a special case of the coupling transformation, where the coupling law $f$ is an affine function: |
| 38 | +```math |
| 39 | +\begin{aligned} |
| 40 | +\boldsymbol{x}_{I_1} &\mapsto \boldsymbol{x}_{I_1} \odot s\left(\boldsymbol{x}_{I\setminus I_1}\right) + t\left(\boldsymbol{x}_{I \setminus I_1}\right) \\ |
| 41 | +\boldsymbol{x}_{I \backslash I_1} &\mapsto \boldsymbol{x}_{I \backslash I_1} |
| 42 | +\end{aligned} |
| 43 | +``` |
| 44 | +Here, $s$ and $t$ are arbitrary functions (often neural networks) called the "scaling" and "translation" functions, respectively. |
| 45 | +They produce vectors of the |
| 46 | +same dimension as $\boldsymbol{x}_{I_1}$. |
| 47 | + |
| 48 | + |
| 49 | +## Implementing Affine Coupling Layer |
| 50 | + |
| 51 | +We start by defining a simple 3-layer multi-layer perceptron (MLP) using `Flux.jl`, |
| 52 | +which will be used to define the scaling $s$ and translation functions $t$ in the affine coupling layer. |
| 53 | +```@example afc |
| 54 | +using Flux |
| 55 | +
|
| 56 | +function MLP_3layer(input_dim::Int, hdims::Int, output_dim::Int; activation=Flux.leakyrelu) |
| 57 | + return Chain( |
| 58 | + Flux.Dense(input_dim, hdims, activation), |
| 59 | + Flux.Dense(hdims, hdims, activation), |
| 60 | + Flux.Dense(hdims, output_dim), |
| 61 | + ) |
| 62 | +end |
| 63 | +``` |
| 64 | + |
| 65 | +#### Construct the Object |
| 66 | + |
| 67 | +Following the user interface of `Bijectors.jl`, we define a struct `AffineCoupling` as a subtype of `Bijectors.Bijector`. |
| 68 | +The functions `parition` , `combine` are used to partition and recombine a vector into 3 disjoint subvectors. |
| 69 | +And `PartitionMask` is used to store this partition rule. |
| 70 | +These three functions are |
| 71 | +all defined in `Bijectors.jl`; see the [documentaion](https://github.com/TuringLang/Bijectors.jl/blob/49c138fddd3561c893592a75b211ff6ad949e859/src/bijectors/coupling.jl#L3) for more details. |
| 72 | + |
| 73 | +```@example afc |
| 74 | +using Functors |
| 75 | +using Bijectors |
| 76 | +using Bijectors: partition, combine, PartitionMask |
| 77 | +
|
| 78 | +struct AffineCoupling <: Bijectors.Bijector |
| 79 | + dim::Int |
| 80 | + mask::Bijectors.PartitionMask |
| 81 | + s::Flux.Chain |
| 82 | + t::Flux.Chain |
| 83 | +end |
| 84 | +
|
| 85 | +# to apply functions to the parameters that are contained in AffineCoupling.s and AffineCoupling.t, |
| 86 | +# and to re-build the struct from the parameters, we use the functor interface of `Functors.jl` |
| 87 | +# see https://fluxml.ai/Flux.jl/stable/models/functors/#Functors.functor |
| 88 | +@functor AffineCoupling (s, t) |
| 89 | +
|
| 90 | +function AffineCoupling( |
| 91 | + dim::Int, # dimension of input |
| 92 | + hdims::Int, # dimension of hidden units for s and t |
| 93 | + mask_idx::AbstractVector, # index of dimension that one wants to apply transformations on |
| 94 | +) |
| 95 | + cdims = length(mask_idx) # dimension of parts used to construct coupling law |
| 96 | + s = MLP_3layer(cdims, hdims, cdims) |
| 97 | + t = MLP_3layer(cdims, hdims, cdims) |
| 98 | + mask = PartitionMask(dim, mask_idx) |
| 99 | + return AffineCoupling(dim, mask, s, t) |
| 100 | +end |
| 101 | +``` |
| 102 | +By default, we define $s$ and $t$ using the `MLP_3layer` function, which is a |
| 103 | +3-layer MLP with leaky ReLU activation function. |
| 104 | + |
| 105 | +#### Implement the Forward and Inverse Transformations |
| 106 | + |
| 107 | + |
| 108 | +```@example afc |
| 109 | +function Bijectors.transform(af::AffineCoupling, x::AbstractVector) |
| 110 | + # partition vector using 'af.mask::PartitionMask` |
| 111 | + x₁, x₂, x₃ = partition(af.mask, x) |
| 112 | + y₁ = x₁ .* af.s(x₂) .+ af.t(x₂) |
| 113 | + return combine(af.mask, y₁, x₂, x₃) |
| 114 | +end |
| 115 | +
|
| 116 | +function Bijectors.transform(iaf::Inverse{<:AffineCoupling}, y::AbstractVector) |
| 117 | + af = iaf.orig |
| 118 | + # partition vector using `af.mask::PartitionMask` |
| 119 | + y_1, y_2, y_3 = partition(af.mask, y) |
| 120 | + # inverse transformation |
| 121 | + x_1 = (y_1 .- af.t(y_2)) ./ af.s(y_2) |
| 122 | + return combine(af.mask, x_1, y_2, y_3) |
| 123 | +end |
| 124 | +``` |
| 125 | + |
| 126 | +#### Implement the Log-determinant of the Jacobian |
| 127 | +Notice that here we wrap the transformation and the log-determinant of the Jacobian into a single function, `with_logabsdet_jacobian`. |
| 128 | + |
| 129 | +```@example afc |
| 130 | +function Bijectors.with_logabsdet_jacobian(af::AffineCoupling, x::AbstractVector) |
| 131 | + x_1, x_2, x_3 = Bijectors.partition(af.mask, x) |
| 132 | + y_1 = af.s(x_2) .* x_1 .+ af.t(x_2) |
| 133 | + logjac = sum(log ∘ abs, af.s(x_2)) |
| 134 | + return combine(af.mask, y_1, x_2, x_3), logjac |
| 135 | +end |
| 136 | +
|
| 137 | +function Bijectors.with_logabsdet_jacobian( |
| 138 | + iaf::Inverse{<:AffineCoupling}, y::AbstractVector |
| 139 | +) |
| 140 | + af = iaf.orig |
| 141 | + # partition vector using `af.mask::PartitionMask` |
| 142 | + y_1, y_2, y_3 = partition(af.mask, y) |
| 143 | + # inverse transformation |
| 144 | + x_1 = (y_1 .- af.t(y_2)) ./ af.s(y_2) |
| 145 | + logjac = -sum(log ∘ abs, af.s(y_2)) |
| 146 | + return combine(af.mask, x_1, y_2, y_3), logjac |
| 147 | +end |
| 148 | +``` |
| 149 | +#### Construct Normalizing Flow |
| 150 | + |
| 151 | +Now with all the above implementations, we are ready to use the `AffineCoupling` layer for normalizing flow |
| 152 | +by applying it to a base distribution $q_0$. |
| 153 | + |
| 154 | +```@example afc |
| 155 | +using Random, Distributions, LinearAlgebra |
| 156 | +dim = 4 |
| 157 | +hdims = 10 |
| 158 | +Ls = [ |
| 159 | + AffineCoupling(dim, hdims, 1:2), |
| 160 | + AffineCoupling(dim, hdims, 3:4), |
| 161 | + AffineCoupling(dim, hdims, 1:2), |
| 162 | + AffineCoupling(dim, hdims, 3:4), |
| 163 | + ] |
| 164 | +ts = reduce(∘, Ls) |
| 165 | +q₀ = MvNormal(zeros(Float32, dim), I) |
| 166 | +flow = Bijectors.transformed(q₀, ts) |
| 167 | +``` |
| 168 | +We can now sample from the flow: |
| 169 | +```@example afc |
| 170 | +x = rand(flow, 10) |
| 171 | +``` |
| 172 | +And evaluate the density of the flow: |
| 173 | +```@example afc |
| 174 | +logpdf(flow, x[:,1]) |
| 175 | +``` |
| 176 | + |
| 177 | + |
| 178 | +## Reference |
| 179 | +Dinh, L., Sohl-Dickstein, J. and Bengio, S., 2016. *Density estimation using real nvp.* |
| 180 | +arXiv:1605.08803. |
0 commit comments