Documented functions

average_tensor(x)

Average the tensor x along its third axis.

convert_image_for_plot(image::Array{Float32,3})::Array{RGB{N0f8},2}

Convert image to the proper data format to enable plots in Julia.

create_dataset(decompressed_path::String, nb_samples::Int=10000)

Create the dataset corresponding to the data located at decompressed_path, possibly sub-sampling nb_samples points. The dataset is made of images of Warcraft terrains, cell cost labels and shortest path labels. It is a Vector of tuples, each Tuple being a dataset point.

create_warcraft_embedding()

Create and return a Flux.Chain embedding for the Warcraft terrains, inspired by differentiation of blackbox combinatorial solvers.

The embedding is made as follows: 1) The first 5 layers of ResNet18 (convolution, batch normalization, relu, maxpooling and first resnet block). 2) An adaptive maxpooling layer to get a (12x12x64) tensor per input image. 3) An average over the third axis (of size 64) to get a (12x12x1) tensor per input image. 4) The element-wize neg_exponential_tensor function to get cell weights of proper sign to apply shortest path algorithms. 4) A squeeze function to forget the two last dimensions.

decompress_dataset(compressed_path::String, decompressed_path::String)

Decompress the dataset located at compressed_path and save it at decompressed_path.

grid_bellman_ford_warcraft(g, s, d, length_max)

Apply the Bellman-Ford algorithm on an GridGraph g, and return a ShortestPathTree with source s and destination d, among the paths having length smaller than length_max.

neg_exponential_tensor(x)

Compute minus exponential element-wise on tensor x.

plot_image_and_path(im::Array{RGB{N0f8}, 2}, zero_one_path::Matrix{UInt8})

Plot the image im and the path zero_one_path on the same Figure.

plot_image_label_path(im::Array{RGB{N0f8}, 2}, zero_one_path::Matrix{UInt8}, label::Matrix{UInt8})

Plot the image im, the path zero_one_path and the labelled path label on the same Figure.

plot_loss_and_gap(losses::Matrix{Float64}, gaps::Matrix{Float64},  options::NamedTuple; filepath=nothing)

Plot the train and test losses, as well as the train and test gaps computed over epochs.

plot_terrain_weights(weights_label::Matrix{Float16}, computed_labels::Matrix{Float32})

Plot both the cell costs labelled and computed on the same colormap Figure.

read_dataset(decompressed_path::String, dtype::String="train")

Read the dataset of type dtype at the decompressed_path location. The dataset is made of images of Warcraft terrains, cell cost labels and shortest path labels. They are returned separately, with proper axis permutation and image scaling to be consistent with Flux embeddings.

save_metrics(;path::String,
                losses::Matrix{Float64},
                gaps::Matrix{Float64},

)

Save train and test losses and gaps tracked during training.

shortest_path_cost_ratio(model, x, y, kwargs)

Compute the ratio between the cost of the solution given by the model cell costs and the cost of the true solution. We evaluate both the shortest path with respect to the weights given by model(x) and the labelled shortest path y using the true cell costs stored in kwargs.wg.weights. This ratio is by definition greater than one. The closer it is to one, the better is the solution given by the current weights of model. We thus track this metric during training.

shortest_path_cost_ratio(model, batch)

Compute the average cost ratio between computed and true shorest paths over batch.

shortest_path_cost_ratio(;model, dataset)

Compute the average cost ratio between computed and true shorest paths over dataset.

squeeze_last_dims(x)

Squeeze two last dimensions on tensor x.

train_function!(;encoder, flux_loss, train_dataset, test_dataset, options::NamedTuple)

Train encoder model over train_dataset and test on test_dataset by minimizing flux_loss loss. This training involves differentiation through argmax with perturbed maximizers, using InferOpt package. The task is to learn the best parameters for the encoder, so that when solving the shortest path problem with its output cell costs, the given solution is close to the labelled shortest path corresponding to the input Warcraft terrain image. Hyperparameters are passed with options. During training, the average train and test losses are stored, as well as the average cost ratio computed with shortest_path_cost_ratio both on the train and test datasets.

train_test_split(X::AbstractVector, train_percentage::Real=0.5)

Split a dataset contained in X into train and test datasets. The proportion of the initial dataset kept in the train set is train_percentage.

true_maximizer(θ::AbstractMatrix{R}; kwargs...) where {R<:Real}

Compute the shortest path from top-left corner to down-right corner on a gridgraph of the size of θ as an argmax. The weights of the arcs are given by the opposite of the values of θ related to their destination nodes. We use GridGraphs, implemented in GridGraphs.jl.