Documentation on maximal_polyhedra() and vertices_and_rays() (tropical geometry)

[MarieKaltoft]

I am a Master's student learning about tropical geometry. Some things in the documentation of the tropical geometry section of Oscar have been confusing, so I am making a couple of posts on here.

I made a feature request concerning documentation on the command vertices_and_rays() in the tropical geometry part of Oscar. This is an idea, which expands on this request.

In addition to more documentation for the above command, I found the relation between the commands maximal_polyhedra() and vertices_and_rays() rather confusing, and I had to guess this relation from trial and error.

Something that could have helped me would have been to have an example. I have included a possible example below. However, I am unsure of how one could determine what is an edge and what is a ray, if writing a general function, which uses these objects, when given a tropical polynomial/hypersurface.
Does anyone have insights on these things? What is the process to possibly including an example like this (and maybe more) in the documentation?

julia> TRing = tropical_semiring();

julia> Tx,(x1,x2) = polynomial_ring(TRing, 2);

julia> g = 1 + 2*x1^2 + 2*x2^2 + 1*x1*x2;

julia> THg = tropical_hypersurface(g);

julia> vertices_and_rays(THg)
5-element SubObjectIterator{Union{PointVector{QQFieldElem}, RayVector{QQFieldElem}}}:
 [-1, -1]
 [1, 0]
 [0, 1]
 [-1//2, 1//2]
 [1//2, -1//2]

julia> maxPolTg = maximal_polyhedra(THg)
5-element SubObjectIterator{Polyhedron{QQFieldElem}}:
 Polyhedron in ambient dimension 2
 Polyhedron in ambient dimension 2
 Polyhedron in ambient dimension 2
 Polytope in ambient dimension 2
 Polyhedron in ambient dimension 2

julia> vertices.(maxPolTg)
5-element Vector{SubObjectIterator{PointVector{QQFieldElem}}}:
 [[-1//2, 1//2]]
 [[1//2, -1//2]]
 [[-1//2, 1//2]]
 [[-1//2, 1//2], [1//2, -1//2]]
 [[1//2, -1//2]]

julia> rays.(maxPolTg)
5-element Vector{SubObjectIterator{RayVector{QQFieldElem}}}:
 [[-1, -1]]
 [[-1, -1]]
 [[0, 1]]
 0-element SubObjectIterator{RayVector{QQFieldElem}}
 [[1, 0]]

[joschmitt]

What is the process to possibly including an example like this (and maybe more) in the documentation?

The functions vertices_and_rays and maximal_polyhedra both have doc strings

Oscar.jl/src/TropicalGeometry/variety_supertype.jl

Line 231 in 953f8bf

Return the vertices and rays of `TropV`.

and

Oscar.jl/src/TropicalGeometry/variety_supertype.jl

Line 114 in 953f8bf

Return the maximal polyhedra of `TropV`.

and one could add examples there. One could also add more explanation on how these functions relate to each other in the online documentation, so in this case it should probably go here: https://github.com/oscar-system/Oscar.jl/blob/master/docs/src/TropicalGeometry/variety.md . If you want to do this, you would have to open a pull request with the changes. (If you need help with that, please ask!)

Does anyone have insights on these things?

Maybe @YueRen does?

[MarieKaltoft]

Thanks for your reply!

The doc strings honestly do not add much more information than the function name itself, which might be purposeful -- if not, this could probably do with some expansion.

What exactly is the difference between this and the doc strings? I have tried reading the Developer Documentation, but it is not totally clear to me.

I will try to create a branch and make a draft PR.

[joschmitt]

The doc strings are what you get when you type ? vertices_and_rays in Julia. They are attached to one function and should just be about that particular function, but one can link to other parts of the documentation as mentioned below.
The doc strings get included in the online documentation at docs.oscar-system.org via these ```@docs ...``` blocks in the markdown files in docs/src/. So the file https://github.com/oscar-system/Oscar.jl/blob/master/docs/src/TropicalGeometry/variety.md gets rendered as https://docs.oscar-system.org/stable/TropicalGeometry/variety/ for example. Here one can add more general information and explanation, for example about conventions used throughout. You can preview your changes as described here https://docs.oscar-system.org/stable/DeveloperDocumentation/documentation/#Building-the-OSCAR-documentation-with-Oscar.build_doc .

I don't think we have any precise guidelines of "what belongs where" for the documentation. If you open a pull request, we can still figure out where exactly the added documentation should go :)

[MarieKaltoft]

@joschmitt I have started a draft PR, thanks for the help!

I was wondering, if it is best to include it in variety.md (as you suggested) or maybe in hypersurface.md, as the examples I have are specifically about hypersurfaces?

[joschmitt]

I honestly don't know much about tropical geometry. I think it's best if you just add it wherever you think it fits best and then @YueRen can have a look (and possibly move it).

[MarieKaltoft]

Thanks! That all clarifies a lot! I will try to put it somewhere sensible and work from there!

[YueRen]

Hi @MarieKaltoft. Thanks for documenting your journey using tropical geometry in OSCAR, that effort is much appreciated!

Regarding your issue with vertices_and_rays, the problem here is lacking documentation of vertices_and_rays for polyhedral complexes:

julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]])
2×4 IncidenceMatrix
[1, 2, 3]
[1, 3, 4]


julia> vr = [0 0; 1 0; 1 1; 0 1]
4×2 Matrix{Int64}:
 0  0
 1  0
 1  1
 0  1

julia> PC = polyhedral_complex(IM, vr)
Polyhedral complex in ambient dimension 2

julia> vertices_and_rays(PC)
4-element SubObjectIterator{Union{PointVector{QQFieldElem}, RayVector{QQFieldElem}}}:
 [0, 0]
 [1, 0]
 [1, 1]
 [0, 1]

As a general rule of thumb: All polyhedral features in the tropical part of OSCAR are inherited from the polyhedral part, and I decided against adding in-depth documentation for them to avoid ballooning the documentation of OSCAR unnecessarily.

But maybe I could add links to the respective functions in the polyhedral module to the documentation of the tropical module. I'll take care of the missing documentation for vertices_and_rays and ask around how that can be best done regarding linking docus.

[MarieKaltoft]

It would be very helpful to have such links! From the documentation in the tropical section, it is not clear that it is simply inherited from the polyhedral module. Thanks for helping!

I will try to do as joschmitt said above and add an example to the documentation page to make the relation between the two functions clearer.

[benlorenz]

Docs for vertices_and_rays in polyhedral geometry were added very recently (#3854) and are only available in the dev-docs.

The main point of this function is to return these vectors in the same order that maximal_polyhedra(IncidenceMatrix, object) uses. Otherwise I would recommend using vertices and rays separately.

[MarieKaltoft]

Thanks for the clarification on documentation! Then it makes sense that I couldn't find it!

I gathered that the ordering was the same as the one used in maximal_polyhedra (I am guessing it works in the same way as in Polymake.jl).