add method "is_cayley" to lattice polytopes

[fchapoton]

as this could be useful

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

[cxzhong]

you may need to consider all directions given by vertex differences

[fchapoton]

The algorithm should be fine as currently written.

@orlitzky : would you please have a look if you can ?

[orlitzky]

Is this the algorithm from Macaulay2? If so it would be polite to add an ALGORITHM:: block that says so, even though the implementation is pretty obvious. The way I think it works is that we may suppose the two parallel hyperplanes are v1 + H and v2 + H. We should have H as a facet, so some facet normal n is orthogonal to it, meaning that (if the polytope is Cayley) we should get only <v1 + H, n> = <v1,n> and <v2 + H, n> = <v2,n> in the set of inner products.

I am not sure this works in corner cases though. Should the trivial polytope be Cayley? How about (say) a 3d polytope in a 4d space, where all of the vertices are contained in the same 3d subspace?

I would also add at least one example that is not Cayley for good measure. You should just need to append another vertex to the cube.

[github-actions]

Documentation preview for this PR (built with commit 69a6069; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[fchapoton]

I have made some changes, as suggested.

[orlitzky]

Yes, sorry, I got busy. I don't know the origin of this definition (Cayley polytope), but if there is no important reason to require them to be full dimensional, I guess it would be easy to handle both cases with

if not self.is_full_dimensional():
    # all vertices are contained in a strict subspace; trivially true
    return True

at the beginning? Otherwise I think we should raise an error to avoid confidently returning False in cases like

sage: P = LatticePolytope([(0,0,0),(1,0,0),(0,1,0),(2,2,0)])
sage: P.is_full_dimensional()
False
sage: [ len(set(n.dot_product(v) for v in P.vertices()))
....:   for n in P.facet_normals() ]
[3, 3, 3, 3]

[fchapoton]

merci, voilà !

[orlitzky]

LGTM, thanks!