Random template directions

[mforets]

Some concrete subtypes of AbstractDirections are UnitVector, BoxDirections, OctDirections and BoxDiagDirections. Their constructor receives the dimension parameter n.

Sometimes we want to generate many directions in 2D, typically to be passed as an argument to overapproximate.

This proposes to add RandomDirection that receive both n and the number of directions to be generated at random. In 2D it is easier than in nD (to make the sample uniform, which is not strictly necessary but a nice property -- uniform sample from the unit ball), so i would start in 2D.

[schillic]

I want to note that "random" and "template" does not fit together :wink:

More seriously, we currently assume that template directions are fixed directions in every iteration. This is important for the lazy inputs implementation. However, we can just adapt the function has_constant_directions that I will add in https://github.com/JuliaReach/Reachability.jl/pull/505.

[mforets]

Related: http://extremelearning.com.au/how-to-generate-uniformly-random-points-on-n-spheres-and-n-balls/

[mforets]

Muller's method for uniform sampling a d-dimensional sphere is neat, i'll give it a try.

[mforets]

Muller's method for uniform sampling a d-dimensional sphere is neat, i'll give it a try.

This was implemented in #1503 and it can be now be combined with CustomDirections. We should add some docs before considering this issue resolved. The following is an example on using custom directions with a randomly generated template:

julia> D = Vector{Vector{Float64}}(undef, 100);

julia> using LazySets, Distributions

julia> LazySets._sample_unit_nsphere_muller!(D, 3, 100); # dimension 3

julia> dirs = CustomDirections(D);

julia> typeof(dirs)
CustomDirections{Float64,Array{Float64,1}}

[mforets]

what would be a good interface for this feature? having to call the internal function LazySets._sample_unit_nsphere_muller! is not great.

[schillic]

You should never have to call unexported functions. _sample_unit_nsphere_muller! is actually nowhere used so far, so maybe that is the problem. We can add a function to return a CustomDirections object that was randomly generated. Not sure about the name.

function xxx(n, m, N=Float64)
    dirs = Vector{Vector{N}}(undef, m)
    _sample_unit_nsphere_muller!(dirs, n, m)
    return CustomDirections(dirs)
end

[mforets]

would rand(CustomDirections, n, m; N=Float64) work?

[schillic]

Yes, but maybe we should give m a more informative name (I know that I used that myself).

[mforets]

rand(CustomDirections; dim=2, num_dirs=10, N=Float64) ? note that in my first attempt, neither n nor m where kwargs, but the existing rand(::LazySet, ..) mostly use kwargs