Add a thematic tutorial on the polyhedron class

[jplab]

This ticket adds a thorough tutorial surrounding the polyhedron class.

The tutorial was elaborated during the Sage Days 84 where all participants gave several significant inputs about the tutorial and its content.

FOLLOW UPS:

• Include the following methods in the tutorial in a follow-up ticket: Add .change_ring() method for polyhedra #22574, Fix Polyhedron.base_extend so it does not ignore the backend parameter #22575
• Normal cone of faces of polyhedra #17215: Implement the normal_cone of a face
• Improve the output of repr_pretty_Hrepresentation for Polyhedron #24837: Improve the output of repr_pretty

Depends on #22558
Depends on #22565

CC: @mo271 @mkoeppe @videlec @sagetrac-tmonteil @fchapoton @mmasdeu @tscrim @mforets @simon-king-jena @novoselt @vinklein

Component: geometry

Keywords: days84, tutorial, days88, days93, IMA-PolyGeom

Author: Jean-Philippe Labbé, Vincent Delecroix

Branch/Commit: b74ae85

Reviewer: Moritz Firsching

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

[jplab]

comment:1

What is the username of Vincent Klein?

I should try to push a version complete "draft version" very soon. Not much is left.

Meanwhile, a question: is it possible that a ref block in rst can not include math mode?

[jplab]

Dependencies: #22605, #22498, #22565

[jplab]

Branch: u/jipilab/22572

[jplab]

Commit: fdcb144

[jplab]

Last 10 new commits:

4b9192d	Added one more file
5d4faf5	duplicate label
7213306	Edits in titles
81d71bc	added some missing methods
a1ad1af	Added tips and some more methods
7fcfb04	Reorder alphabetically in visualization
46f48fa	Added description of is_ methods
79bb4ce	Corrected a link and added Ehrhart poly
e2aa8a8	Repaired references to objects
fdcb144	Added ref to Perles

[jplab]

Changed dependencies from #22605, #22498, #22565 to #22605, #22498, #22565, #22522, #22622, #22558, #22546, #22574, #22575

[mforets]

comment:6

Replying to @jplab:

What is the username of Vincent Klein?

It is vklein.

I should try to push a version complete "draft version" very soon. Not much is left.

Are you looking for a reviewer for this ticket?

Meanwhile, a question: is it possible that a ref block in rst can not include math mode?

Hmm, I didn't understand :/

[jplab]

comment:7

Thanks Marcelo!

My question refers to the fact that I make references to the base classes using :ref: and in this block, the math does not appear, like QQ and ZZ. I do not know why...

As for reviewers, you are welcome to review the ticket! I am not completely done yet though... That's why I left it as new. I still want to put some more work in there, but I thought that it is good if people can have a look at it already!

[jplab]

Changed dependencies from #22605, #22498, #22565, #22522, #22622, #22558, #22546, #22574, #22575 to #20887, #22605, #22498, #22565, #22522, #22622, #22558, #22546, #22574, #22575

[jplab]

Changed dependencies from #20887, #22605, #22498, #22565, #22522, #22622, #22558, #22546, #22574, #22575 to #20887, #22605, #22498, #22565, #22522, #22622, #22558, #22546,

[jplab]

comment:10

Since the tickets #22574, #22575 are not quite ready yet and I'd like this ticket done soon, I put them in a forthcoming ticket to do later.(!)

[jplab]

Changed keywords from days84, tutorial to days84, tutorial, days88

[videlec]

comment:12

you have to remove trailing whitespaces

[videlec]

comment:13

I would not order a tutorial by method. This is what the reference manual is about. You should find a "fil rouge". I think the best way to proceed is to have concrete big problems and show how to solve it in Sage step by step.

Furthermore, I think that it is very good to have exercices in thematic tutorials!

EDIT: there are actually a lot of different files:

• is_this_polyhedron.rst
• lectures.rst
• new_from_old.rst
• related_objects.rst
• tips.rst
• visualization.rst
  I think it is bad to put these rather generic names. Geometry is not just about polyhedra...

[videlec]

comment:14

1. Change the title Tutorials for the Geometry module of Sage into Polyhedra in the file geometry.rst

2. At the very top of the main thematic tutorial page there is a nice distinction between quickrefs, primer and tutorial. It would be good to tag the different files you wrote accordingly.

[videlec]

Changed dependencies from #20887, #22605, #22498, #22565, #22522, #22622, #22558, #22546, to #22558, #22565

[videlec]

Changed branch from u/jipilab/22572 to public/22572

[videlec]

Changed commit from fdcb144 to d2dd9f7

[videlec]

New commits:

01bc985	22572: first draft of polyhedra tutorial
d2dd9f7	22572: revamp polyhedra tutorials

[videlec]

comment:16

I rebased everything on 8.1.beta3 (folding all your commits in 1). The three documents is_this_polyhedron.rst, new_from_old.rst and related_objects.rst are now folded in a unique polyhedra_quickref.rst.

The organization of the quickref should be discussed...

[jplab]

comment:17

I added some todos that I observed while making the tutorial.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

b1ce45b	Several other corrections
d526f70	renamed tutorial files

[sagetrac-git]

Changed commit from bd6c356 to d526f70

[jplab]

comment:29

I just pushed the suggested changes.

One remark: I prefer how the \mathbf{R} appears compared to \RR.

[videlec]

comment:30

Replying to @jplab:

I just pushed the suggested changes.

Great :-)

One remark: I prefer how the \mathbf{R} appears compared to \RR.

Then propose to change it globally in Sage? This is just a macro. It is better to have it consistent accross documentation rather than good looking on your tutorial.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

d7896f8

Merge branch 'develop' into 22572

[sagetrac-git]

Changed commit from d526f70 to d7896f8

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

597b802

Merge branch sage8.2.rc1 into 22572

[sagetrac-git]

Changed commit from d7896f8 to 597b802

[mo271]

Reviewer: Moritz Firsching

[mo271]

comment:33

Thanks for the tutorial!

I only have a few remarks/corrections

• has the ambient space --> as the ambient space
• should the explanation for "is_compact" perhaps mention the word "bounded"?
• add a link for "composite_field" (and change the word to "composite_fields")
• the reason why we cant do computations in the symbolic ring is given as because it is "not exact". Perhaps we could simply state that it is not implemented. (Computations in RDF are also "not exact")
• access to vertices ... --> access vertices ...
• remove the part "clearly (!)" (or is this a joke I don't get?)
• in the sage_input example, I suggest to change whats there to

sage: Cube = polytopes.cube()
sage: TCube = Cube.truncation().dilation(1/2)
sage: sage_input(TCube)

That is add "dilation" to avoid "QQ(1)" many times, which doesn't look pretty.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

eee533a	Corrections from review
b74ae85	Made tests pass

[sagetrac-git]

Changed commit from 597b802 to b74ae85

[jplab]

comment:35

Salut Moritz,

Thanks a lot for the review. I made the corrections you suggested.

Hopefully, the bot likes it.

[jplab]

Changed keywords from days84, tutorial, days88, days93 to days84, tutorial, days88, days93, IMA-PolyGeom

[vbraun]

Changed branch from public/22572v8.2b5 to b74ae85