ParameterHandling.jl

bounded(val::Array{<:Real}, lower_bound::Real, upper_bound::Real)

Roughly equivalent to bounded.(val, lower_bound, upper_bound), but implemented such that unflattening can be efficiently differentiated through using algorithmic differentiation (Zygote in particular).

bounded(val::Real, lower_bound::Real, upper_bound::Real)

Constructs a Bounded. The value of a Bounded is a Real number that is constrained to be within the interval (lower_bound, upper_bound), and is equal to val. This is represented internally in terms of an unconstrained_value and a transform that maps any Real to this interval.

deferred(f, args...)

The value of a deferred is f(value(args)...). This makes it possible to make the value of the args e.g. AbstractParameters and, therefore, enforce constraints on them even if f knows nothing about AbstractParameters.

It can be helpful to use deferred recursively when constructing complicated objects.

fixed(val)

Represents a parameter whose value is required to stay constant. The value of a Fixed is simply val. Constantness of the parameter is enforced by returning an empty vector from flatten.

flatten([eltype=Float64], x)

Returns a "flattened" representation of x as a vector of real numbers, and a function unflatten that takes a vector of reals of the same length and returns an object of the same type as x.

unflatten is the inverse of flatten, so

julia> x = (randn(5), 5.0, (a=5.0, b=randn(2, 3)));

julia> v, unflatten = flatten(x);

julia> x == unflatten(v)
true

nearest_orthogonal_matrix(X::AbstractMatrix{<:Union{Real,Complex}})

Project X onto the closest orthogonal matrix in Frobenius norm.

Originally used in varz: https://github.com/wesselb/varz/blob/master/varz/vars.py#L446

orthogonal(X::AbstractMatrix{<:Real})

Produce a parameter whose value is constrained to be an orthogonal matrix. The argument X need not be orthogonal.

This functionality projects X onto the nearest element subspace of orthogonal matrices (in Frobenius norm) and is overparametrised as a consequence.

Originally used in varz: https://github.com/wesselb/varz/blob/master/varz/vars.py#L446

positive(val::Real, transform=exp, ε=sqrt(eps(typeof(val))))

Return a Positive. The value of a Positive is a Real number that is constrained to be positive. This is represented in terms of a transform that maps an unconstrained_value to the positive reals. Satisfies val ≈ transform(unconstrained_value).

positive(x::Array{<:Real})

Roughly equivalent to map(positive, x), but implemented such that unflattening can be efficiently differentiated through using algorithmic differentiation (Zygote in particular).

positive_definite(X::AbstractMatrix{<:Real})

Produce a parameter whose value is constrained to be a positive-definite matrix. The argument X needs to be a positive-definite matrix (see https://en.wikipedia.org/wiki/Definite_matrix).

The unconstrained parameter is a LowerTriangular matrix, stored as a vector.

value(x)

Return the "value" of an object. For AbstractParameters this typically applies some transformation to some data contained in the parameter, and returns a plain data type. It might, for example, return a transformation of some internal data, the result of which is guaranteed to satisfy some constraint.

value_flatten([eltype=Float64], x)

Operates similarly to flatten, but the returned unflatten function returns an object like x, but with unwrapped values.

Doing

v, unflatten = value_flatten(x)

is the same as doing

v, _unflatten = flatten(x)
unflatten = ParameterHandling.value ∘ _unflatten