Method v/s manifold

[asinghvi17]

It's agreed that we should have

arclength(geom; manifold = discover_manifold(geom), method = nothing) = arclength(method, manifold, geom)

and then

arclength(manifold, geom) = arclength(nothing, manifold, geom)
arclength(::Nothing, manifold, geom) = arclength(BEST_METHOD_FOR_MANIFOLD, manifold, geom)

then we, or users, define methods for the API

[asinghvi17]

This way, we have the ability to disambiguate methods from manifolds.

[rafaqz]

I'm not sure this was what we specifically agreed! :

arclength(method, manifold, geom)

Two traits is a bit confusing and ambiguous for users, another option is that keyword arguments could be preffered and dispatch to traits could be on _arclength, or just one trait would be allowed as the first argument.

There is a point where combinatorial positional traits becomes confusing to read. I'm not sure if two is too many but three definately would be!

[asinghvi17]

Hmm, we could do

arclength(geom; manifold, method)
arclength(manifold, geom; method)

and then dispatch is done internally? I'm still not sure I like the underscore architecture though, it seems a bit fishy for extendability...

Definitely agree on combinatorial position traits being bad. But dispatching off keyword arguments is probably bad form.

I had also considered making algorithms an optional part of this informal "operation interface". But the problem is that you can't shoehorn e.g GEOS() into that framework, so there has to be some form of space for algorithms.

[rafaqz]

Ok right underscore methods are not so good in an interface. It would have to be something else. So I guess its preferable to have those positional methods as long as we have the keyword methods as the main things in the docs.

[asinghvi17]

Talking with @TheCedarPrince we came up with what I consider a decent interface:

struct SomeManifold{T} <: Manifold
    val::T
end

struct SomeAlgorithm{T} <: Algorithm
    val::T
    # or maybe
    # kw1
    # kw2
    # ...
end

# user space
arclength(geom; kwargs...) = arclength(best_manifold(geom), geom)
# some specification / preference
arclength(m::Manifold, geom; kwargs...) = arclength(m, best_algorithm(m, geom; kwargs...), geom)
arclength(a::Algorithm, geom #= NO KWARGS ALLOWED =#) = arclength(applicable_manifold(a, geom), a, geom)

# user/algorithm developer space
arclength(m::Manifold, alg::Algorithm, geom #= NO KWARGS ALLOWED =#) # main dispatch point

and then, in user space,

# the maximum the user can do
arclength(Planar(), GEOS(; maybe_kwargs...), geom)
# but also
arclength(Geodesic(), PROJ(; maybe_kwargs...), geom) == arclength(PROJ(), geom) == arclength(Geodesic(), geom)

# generally the user will see
arclength(geom; maybe_kwargs...) # auto choose, collapse kwargs into algorithm
# or
arclength(Planar(), geom; maybe_kwargs...) # auto choose - usually native Julia in this instance, collapse kwargs into algorithm
# and if calling out to a library, we know which manifold it should be in
arclength(GEOS(), geom)

[asinghvi17]

@evetion @rafaqz you were both there at the initial discussion, what do you guys think?

[rafaqz]

I don't love having two arguments for traits. I would use one argument for both - then users and other packages can pass around one bundle rather than two.

So arclength(GEOS(Geodesic(; kw...); kw...), x) would be the full specification syntax.

But either arclength(GEOS(), x) or arclength(Geodesic(), x) would work as well, but needing clarification with applicable_manifold or best_algorithm to end up with the arclength(Algorithm(Manifold()), x) call.

applicable_manifold could then accept the function for clarifying dispach applicable_manifold(::typeof(arclength), ::Geos) = Geodesic()

Top level functions func(trait, x) could just call _func(resolve_alg_and_manifold(func, trait), x) or something.

[asinghvi17]

After some chats we arrived at the idea that we should have each "operation" be a callable struct, similar to the approach in fix. Then operations can be:

abstract type Operation{Alg <: Algorithm} end

# subtype operations based on what they do
# bikeshed name participle - maybe ApplierOperation or ApplyReducerOperation, or something
abstract type ApplyOperation{Alg} <: Operation{Alg} end
abstract type ApplyReduceOperation{Alg} <: Operation{Alg} end


(op::Operation)(data; kw...) = run(op, data; kw...)

function run(op::ApplyOperation, data; kw...)
    apply(op, trait_target(op), data; kw...)
end


function run(op::ApplyReduceOperation, data; kw...)
    applyreduce(mapper(op),  reducer(op), trait_target(op), data; kw...)
end
# or something like this - so the user only has to define

(::SomeOperation)(::GI.SomeTrait, geom) = ...
# or something like that.

struct SomeOperation{Alg <: Algorithm} <: Operation{Alg} 
    alg::Algorithm
end

# alternatively the user can take over at a higher level, like this, if there's something they need to do
function run(operation::SomeOperation{SomeAlg}, data; runner_keywords_like_threaded_and_init)
end