Add a thematic tutorial on the polyhedron class

[jipilab]

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: #22574, #22575
• #17215: Implement the normal_cone of a face
• #24837: Improve the output of repr_pretty

[jipilab]

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?

[jipilab]

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

[mforets]

Replying to jipilab:

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 :/

[jipilab]

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!

[jipilab]

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.(!)

[vdelecroix]

you have to remove trailing whitespaces

[vdelecroix]

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...

[vdelecroix]

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.

[vdelecroix]

New commits:

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

[vdelecroix]

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...

[jipilab]

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

[jipilab]

New commits:

​e1904c6	22572: first draft of polyhedra tutorial
​5a09b69	22572: revamp polyhedra tutorials

[git]

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

​db5e413

Updated to 8.2.b5, fixed many errors

[git]

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

​a7b78dd

Added a ref to the handbook

[git]

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

​31edde6

Completed a comment

[vdelecroix]

You should not use a generic name for your file like geometry/lectures.rst. Your tutorial is specific on polytopes. Note that there is moreover a polytutorial.rst. Perhaps polytope_quick_tutorial.rst for the latter and polytope_tutorial.rst (that way all of them starts with polytope that helps)?

[vdelecroix]

Some sided comment:

• :math:`\mathbb{R}^d` could be simplified to `\mathbb{R}^d` (the default sphinx directive for backstick is math)
• `\mathbb{R}^d` could be simplifed in `\RR^d` (sage comes with some predefined macro)

[sdrewitz]

in lectures.rst at the beginning of the first lecture right after the second displayed equation, do you need to ask for the \lambda_i to be \geq 0 ?

[git]

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

​231cd56	deleted trailing whitespace
​f685c64	fixed some typos in lectures.rst
​7f5e125	fixed typos in polyhedra_quickref.rst
​bd6c356	LateX -> LaTeX in polytope_tikz.rst

[jipilab]

Replying to sdrewitz:

in lectures.rst at the beginning of the first lecture right after the second displayed equation, do you need to ask for the \lambda_i to be \geq 0 ?

Yes! Thanks for spotting this!

[git]

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

​b1ce45b	Several other corrections
​d526f70	renamed tutorial files

[jipilab]

I just pushed the suggested changes.

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

[vdelecroix]

Replying to jipilab:

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.

[git]

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

​d7896f8

Merge branch 'develop' into 22572

[git]

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

​597b802

Merge branch sage8.2.rc1 into 22572

[moritz]

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.

[git]

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

​eee533a	Corrections from review
​b74ae85	Made tests pass

[jipilab]

Salut Moritz,

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

Hopefully, the bot likes it.