ParametrisedConvexApproximators

ParametrisedConvexApproximators.jl is a Julia package providing predefined parametrised convex approximators and related functionalities. An official package of ¹.

To install ParametrisedConvexApproximator, please open Julia's interactive session (a.k.a REPL) and press ] key in the REPL to use the package mode, then type the following command

pkg> add ParametrisedConvexApproximator

• For PLSE(plus), the differentiation of the minimiser is now available via implicit differentiation.
• The benchmark result was reported in ParametrisedConvexApproximator.jl v0.1.1 ¹.

ParametrisedConvexApproximators.jl focuses on providing predefined approximators including parameterized convex approximators. Note that when approximators receive two arguments, the first and second arguments correspond to parameter and optimization variable, usually denoted by x and u, respectively.

Note that the terms of parameter x and optimization variable u are often referred to as condition and decision from the decision-making point of view ¹.

Applications include amortized optimization (learning-based parametric optimization) ².

using ParametrisedConvexApproximators
using Flux
using Random  # to reproduce the following result

# construction
seed = 2023
Random.seed!(seed)
n, m = 3, 2
i_max = 20
T = 1.0
h_array = [64, 64]
act = Flux.leakyrelu
network = PLSE(n, m, i_max, T, h_array, act)  # parametrised log-sum-exp (PLSE) network
x, u = rand(n), rand(m)
f̂ = network(x, u)
@show f̂

f̂ = [3.029994811790289]

min_condition = -ones(n)
max_condition = +ones(n)
min_decision = -ones(m)
max_decision = +ones(m)
target_function_name = :quadratic
target_function = example_target_function(target_function_name)  # f(x, u) = x'*x + u'*u
N = 5_000

dataset = DecisionMakingDataset(
    target_function;
    target_function_name=:quadratic,  # just for metadata
    N=N, n=n, m=m, seed=seed,
    min_condition=min_condition,
    max_condition=max_condition,
    min_decision=min_decision,
    max_decision=max_decision,
)

trainer = SupervisedLearningTrainer(dataset, network; optimiser=Adam(1e-4))

@show get_loss(trainer.network, trainer.dataset[:train], trainer.loss)
@show get_loss(trainer.network, trainer.dataset[:validate], trainer.loss)
best_network = Flux.train!(trainer; epochs=200)
@show get_loss(best_network, trainer.dataset[:test], trainer.loss)

...

epoch: 199/200
loss_train = 0.0001664964550015733
loss_validate = 0.0003002414225961646
Best network found!
minimum_loss_validate = 0.0003002414225961646
epoch: 200/200
loss_train = 0.0001647995673689787
loss_validate = 0.00029825480495257375
Best network found!
minimum_loss_validate = 0.00029825480495257375

# optimization
Random.seed!(seed)
x = rand(n)  # any value
minimiser = minimise(network, x; u_min=min_decision, u_max=max_decision)  # box-constrained minimization; you can define your own optimization problem manually.
@show minimiser
@show network(x, minimiser)
@show dataset[:train].metadata.target_function(x, minimiser)

minimiser = [-0.003060366520019827, 0.007150205329478883]
network(x, minimiser) = [0.9629849722035002]
(dataset[:train]).metadata.target_function(x, minimiser) = 0.9666740244969058

• AbstractApproximator is an abstract type of approximator.
• ParametrisedConvexApproximator <: AbstractApproximator is an abstract type of parametrised convex approximator.
• ConvexApproximator <: ParametrisedConvexApproximator is an abstract type of convex approximator.
• DifferenceOfConvexApproximator <: AbstractApproximator is an abstract type of difference of convex approximator.

• All approximators in ParametrisedConvexApproximators.jl receive two arguments, namely, x and u. When x and u are vectors whose lengths are n and m, respectively, the output of an approximator is one-length vector.

  • Note that x and u can be matrices, whose sizes are (n, d) and (m, d), for evaluations of d pairs of x's and u's. In this case, the output's size is (1, d).

• The list of predefined approximators:

  • FNN::AbstractApproximator: feedforward neural network
  • MA::ConvexApproximator: max-affine (MA) network ³
  • LSE::ConvexApproximator: log-sum-exp (LSE) network ³
  • PICNN::ParametrisedConvexApproximator: partially input-convex neural network (PICNN) ⁴
  • PMA::ParametrisedConvexApproximator: parametrised MA (PMA) network ¹
  • PLSE::ParametrisedConvexApproximator: parametrised LSE (PLSE) network ¹
    • The default setting is strict = false.
    • PLSEPlus = PLSE with strict=true
  • DLSE::DifferenceOfConvexApproximator: difference of LSE (DLSE) network ⁵

• (nn::approximator)(x, u) provides the approximate function value.
• minimiser = minimise(approximator, x; u_min=nothing, u_max=nothing) provides the minimiser for given parameter x considering box constraints of u >= u_min and u <= u_max (element-wise).
  • The parameter x can be a vector, i.e., size(x) = (n,), or a matrix for multiple parameters via multi-threading, i.e., size(x) = (n, d).

• DecisionMakingDataset

• SupervisedLearningTrainer

See ./examples/visualization.jl.

• The following illustration shows the construction of MA network for given convex function.
• See ³.
• NOTICE: the following illustration does not show the training progress.

• The following illustration shows the construction of PMA network for given parameterized convex function.
• See ¹, Theorem 3.
• NOTICE: the following illustration does not show the training progress.

• The following illustration shows the PLSE network with different temperature for the corresponding PMA network constructed above.
• See ¹, Corollary 1.

• To construct an MA network³, any subgradient can arbitrarily be selected.

• To construct an PMA network³, the subgradient function, a function of parameter x, should carefully be considered so that it can be continuous and represent (approximate) the subgradient function well.
  • As shown in the following, the subgradient function may be multivalued.

The subgradient function can be approximated by a continuous approximate selection.

• Given multivalued function $f:X \to Y$, a single-valued function $g: X \to Y$ is said to be a continuous approximate selection if $\textup{Graph}(g) \subset \textup{Graph}(B(f, \epsilon))$.
  • The following figure adopts $L_{1}$-norm for illustration.