document and doctest constructing polyhedra over number fields

[dimpase]

Currently, the only example given in Polyhedron docstring is

    When the input contains elements of a Number Field, they require an
    embedding::

        sage: K = NumberField(x^2-2,'s')
        sage: s = K.0
        sage: L = NumberField(x^3-2,'t')
        sage: t = L.0
        sage: P = Polyhedron(vertices = [[0,s],[t,0]])
        Traceback (most recent call last):
        ...
        ValueError: invalid base ring

This is clearly insufficient from online documentation point of view. One has to look either at the html/pdf docs ot at the header of the file sage/geometry/polyhedron/constructor.py for more examples with embeddings specified.

CC: @jplab @mkoeppe @mo271

Component: geometry

Author: Dima Pasechnik

Branch/Commit: a962a00

Reviewer: Jean-Philippe Labbé

Issue created by migration from https://trac.sagemath.org/ticket/26077

[dimpase]

comment:1

Could please someone provide a working example? I'll do the rest...

[dimpase]

comment:2

here is a small working example

R0.<r0>=QQ[]
R1.<r1>=NumberField(r0^2-2, embedding=1.414213562373095)
s = Polyhedron(vertices = [[0,1, 1], [1,r1, -1], [2,-1, 1], [7,-1, -1]], base_ring=R1)

I'd also have something more interesting, e.g. a regular icosahedron.

[dimpase]

Author: Dima Pasechnik

[jplab]

comment:4

Have a look at #17197 (which this present ticket might qualify as a duplicate).

Yes, this is true that polyhedron over number field is now well-documented. You can have a look at

#22420: Meta-ticket: Polyhedron: new features and known bugs

and

https://wiki.sagemath.org/OptiPolyGeom

for a roadmap about things on polyhedra. This issue is on the list for a long time. My priority was to offer a wide breath tutorial on polyhedra and use it to then complete the docstring. Perhaps not the right way around, but the tutorial is now available:

http://doc.sagemath.org/html/en/thematic_tutorials/geometry/polyhedra_tutorial.html

thanks to

#22572: Add a thematic tutorial on the polyhedron class

from which you can pick many examples that work under Sage 8.3.

I am sorry if the documentation string still has not been adapted yet.

[dimpase]

Commit: 1a0c188

[dimpase]

Branch: u/dimpase/geometry/poly_NF_doc

[dimpase]

comment:5

Here is a short fix for this. I deliberately constructed an example from scratch,
rather than picking one from polytopes.*.

I wonder how one can make pointers to the tutorial in the reference manual without
mentioning the full URL.

---

New commits:

1a0c188

add doc for #26077

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

d9d1220

add doc for #26077

[sagetrac-git]

Changed commit from 1a0c188 to d9d1220

[dimpase]

comment:7

some typos fixed; now the links look proper.

[jplab]

Changed branch from u/dimpase/geometry/poly_NF_doc to public/26077

[jplab]

Changed commit from d9d1220 to a962a00

[jplab]

Reviewer: Jean-Philippe Labbé

[jplab]

comment:8

Hi,

This looks good to me. I added the spacing convention to the example.

You can put it as positive review on my behalf if you accept the changes.

---

New commits:

a962a00

Added spacing convention

[dimpase]

comment:9

Thanks.

[vbraun]

Changed branch from public/26077 to a962a00