harmonise the interfaces of orientation() and acyclic_orientation()

[dimpase]

Steps To Reproduce

for a graph g, outputs of g.orientation() and g.acyclic_orientation() are rather different, type-wise.
As reported by Gordon Royle on sage-devel

My suggestion is to redefine orientations of a graph $\Gamma=(V,E)$ to be a function $E\to V\times V$,
and return these, eventually making this the default.

Expected Behavior

should be consistent

Actual Behavior

is not

Additional Information

see also https://ask.sagemath.org/question/79427/the-acyclic-orientations-function-behaves-unexpectedly/

Environment

• OS: all
• Sage Version: 10.*

Checklist

• I have searched the existing issues for a bug report that matches the one I want to file, without success.
• I have read the documentation and troubleshoot guide

[dimpase]

@dcoudert - do you think it's a good idea?

[maxale]

Then there also should be an easy way to apply an orientation function to the graph and obtain the corresponding directed graph. Something like D = G.orient(f).

[maxale]

Please also include .random_orientation() into the proposed harmonization.

[dcoudert]

The current proposal is to make acyclic_orientations return a digraph with properly directed edges #38757

What should be done in .random_orientation() ?
We could also consider strong_orientations_iterator (which could be renamed strong_orientations).

Do we really need a method like D = G.orient(f) ? Roughly, it should be D = DiGraph([G, [f(e) for e G.edges()]]).

[maxale]

What should be done in .random_orientation() ?
We could also consider strong_orientations_iterator (which could be renamed strong_orientations).

I do not know if anything needs to be done. My point is that a harmonization/uniformization of the interfaces should be applied to all functions that produce graph orientations. The strong_orientations should be included into that class as well.

Do we really need a method like D = G.orient(f) ? Roughly, it should be D = DiGraph([G, [f(e) for e G.edges()]]).

Yes, assuming that f understands labeled edges and preserves the labels. Here my point is that if there is a function, then there should be a way to apply this function without thinking about underlying technicalities.

[dcoudert]

In #38809, we move all remaining orientation methods to file orientations.py. This should ease the maintenance and harmonisation of these methods.

[maxale]

Please include yet another orientation method - eulerian_orientation().