Improve and fix documentation of Combinatorial or Discrete Geometry

[jplab]

The reference manual for the currently called combinatorial geometry needs some logical reorganization.

http://doc.sagemath.org/html/en/reference/geometry/index.html

This ticket fixes the following:

• add the normaliz backend to the references and add a note on how to install it.
• fixes an indentation that caused the documentation not to build in the normaliz backend
• the section on combinatorial geometry is renamed by adding also Discrete
• the section on hyperbolic geometry gets moved in the table of content to Geometry and Topology and not inside Combinatorial and Discrete Geometry (which made no sense).
• the combinatorial and discrete geometry table of content is restructured logically.
• fixes a small bug in the documentation of the base class of polyhedron (missing backtick)
• added some links to other modules in the constructor of polyhedra to different classes and backends.

CC: @mo271 @mkoeppe @videlec @sagetrac-tmonteil @fchapoton

Component: geometry

Keywords: polyhedron, days84

Author: Jean-Philippe Labbé

Branch/Commit: f931571

Reviewer: Vincent Klein

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

[jplab]

Branch: u/jipilab/improve_doc_poly

[sagetrac-git]

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

e6beae2

Corrected a title

[sagetrac-git]

Commit: e6beae2

[fchapoton]

comment:5

Salut !

missing empty line here

+.. NOTE::
+    This backend requires `PyNormaliz <https://pypi.python.org/pypi/PyNormaliz/1.5>`_.

and in several other places....

[sagetrac-git]

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

38a89eb

Added missing linespacing

[sagetrac-git]

Changed commit from e6beae2 to 38a89eb

[sagetrac-git]

Changed commit from 38a89eb to 71b1f42

[sagetrac-git]

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

71b1f42

Several small corrections

[sagetrac-git]

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

1a1e7b1

Corrected the indentation of an input block

[sagetrac-git]

Changed commit from 71b1f42 to 1a1e7b1

[novoselt]

comment:10

I would not give cones and fan "Toric Varieties" title, there are classes for these which are based on fans and cones. Also lattice_polytope logically fits with them better.

[jplab]

comment:11

I would not give cones and fan "Toric Varieties" title, there are classes for these which are based on fans and cones.

I agree. I was sorting through the files and for the first version I put the 7 files whose documentation started with

This module was designed as a part of framework for toric varieties

together in a section called Toric Varieties.

Perhaps naming the section. Lattices, Cones, Fans, and related objects ? What do you think? Do you have any suggestions?

Also lattice_polytope logically fits with them better.

Okay. Are there other modules that would logically go with them as well?

[novoselt]

comment:12

"Toric Geometry" may be appropriate, just no "varieties" themselves, I think.

Everything under "Lattice polyhedra" may be clamped with it - while there are presumably other reasons to consider them, almost everything here was done with toric geometry and mirror symmetry applications in mind.

[jplab]

comment:13

Replying to @novoselt:

"Toric Geometry" may be appropriate, just no "varieties" themselves, I think.

Sounds good.

Everything under "Lattice polyhedra" may be clamped with it - while there are presumably other reasons to consider them, almost everything here was done with toric geometry and mirror symmetry applications in mind.

I could put it in the polyhedral computations section after the lattice polytopes, that would be good? One argument to keep "Toric geometry" in its own section is somehow to reflect a little bit the structure in the geometry component (although I admit it does not necessarily have to follow it...) since polyhedron is a module on its own and the toric geometry framework is located directly in geometry and not in polyhedron...

I'm fine with both.

[sagetrac-git]

Changed commit from 1a1e7b1 to 51a05cf

[sagetrac-git]

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

51a05cf

Renamed subsection and moved it

[jplab]

Dependencies: #22469

[sagetrac-tmonteil]

comment:16

A very related question (for another ticket, but it is good to have your opinion while you are at it) would be to move the isolated python files within src/sage/geometry/ into some appropriate directory, like riemannian_manifolds for riemannian manifolds, polyhedron for polyhedra, etc.

The files to classify are:

• cone.py
• fan_isomorphism.py
• fan_morphism.py
• fan.py
• hasse_diagram.py
• integral_points.pyx
• lattice_polytope.py
• linear_expression.py
• newton_polygon.py
• point_collection.pyx
• pseudolines.py
• ribbon_graph.py
• toric_lattice_element.pyx
• toric_lattice.py
• toric_plotter.py

[sagetrac-tmonteil]

Changed dependencies from #22469 to none

[novoselt]

comment:17

Would make sense to have src/sage/geometry/toric similar to src/sage/schemes/toric with files

• cone.py
• fan_isomorphism.py
• fan_morphism.py
• fan.py
• lattice_polytope.py
• point_collection.pyx
• toric_lattice_element.pyx
• toric_lattice.py
• toric_plotter.py

[sagetrac-tmonteil]

comment:18

Replying to @novoselt:

Would make sense to have src/sage/geometry/toric similar to src/sage/schemes/toric with files

• cone.py
• fan_isomorphism.py
• fan_morphism.py
• fan.py
• lattice_polytope.py
• point_collection.pyx
• toric_lattice_element.pyx
• toric_lattice.py
• toric_plotter.py

OK great, having such a src/sage/geometry/toric would be a good step toward cleaning up src/sage/geometry !

[sagetrac-git]

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

27f9f4d

Rebased on 7.6.beta6

[sagetrac-git]

Changed commit from 51a05cf to 27f9f4d

[jplab]

Dependencies: #13517

[jplab]

comment:20

Okay. I would say that it is ready to be reviewed again.

[jplab]

Changed dependencies from #13517 to none

[sagetrac-git]

Changed commit from 27f9f4d to f931571

[sagetrac-git]

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

f931571

Corrected indentation in doc

[vinklein]

Reviewer: Vincent Klein

[vinklein]

comment:24

doctest passed on :

• src/sage/geometry/polyhedron/backend_normaliz.py
• src/sage/geometry/polyhedron/base.py
• src/sage/geometry/polyhedron/constructor.py

build of the doc passed and page discrete_geometry/index.html looks conform.

[vbraun]

Changed branch from u/jipilab/improve_doc_poly to f931571