Documentation on `vertices_and_rays()` (tropical geometry)

[MarieKaltoft]

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

Is your feature request related to a problem? Please describe. I worked on a problem, where I was trying to get information about, what a tropical hypersurface looks like without having to use visualize(), as I was writing a program, which could use this information. We have the command vertices_and_rays(), which does exactly that! However, the command simply outputs the rays and vertices in some seemingly random order, where it is definitely not clear, which are which, and which rays belong to which vertices. I have included an example (in this case, the first vector listed is actually a ray for both of the two vertices). As far as I can tell, it is not consistent that the rays are always listed before the vertices -- sometimes they might be mixed.

A simple example first:

T = tropical_semiring()
Tx,(x1,x2) = polynomial_ring(T, 2)
g = 1 + 2*x1^2 + 2*x2^2 + 1*x1*x2
THg = tropical_hypersurface(g)
vertices_and_rays(THg)

which outputs

5-element SubObjectIterator{Union{PointVector{QQFieldElem}, RayVector{QQFieldElem}}}:
 [-1, -1]
 [1, 0]
 [0, 1]
 [-1//2, 1//2]
 [1//2, -1//2]

A more complex example:

f = 3 + 1*x1 + 1*x2 + 2*x1^2 + 0*x1*x2 + 6*x2^2 + 4*x1^2 + 0*x1^2*x2 + 2*x1*x2^2 + 12*x2^3 + 8*x1^4 + 3*x1^3*x2 + 0*x1^2*x2^2 + 9*x1*x2^3 + 10*x2^4
THf = tropical_hypersurface(f)
vertices_and_rays(THf)

which outputs

12-element SubObjectIterator{Union{PointVector{QQFieldElem}, RayVector{QQFieldElem}}}:
 [0, 1]
 [1, 0]
 [1, -1]
 [-3, 2]
 [2, -3]
 [0, 0]
 [-1, -1]
 [-3, 0]
 [0, 1]
 [-1, 2]
 [1, 1]
 [2, 2]

Running typeof.(vertices_and_rays(THf)) gives

12-element Vector{DataType}:
 RayVector{QQFieldElem}
 RayVector{QQFieldElem}
 PointVector{QQFieldElem}
 PointVector{QQFieldElem}
 PointVector{QQFieldElem}
 PointVector{QQFieldElem}
 RayVector{QQFieldElem}
 PointVector{QQFieldElem}
 PointVector{QQFieldElem}
 PointVector{QQFieldElem}
 PointVector{QQFieldElem}
 PointVector{QQFieldElem}

which illustrates the mixed order of the rays and vertices.

Describe the solution you'd like I would very much like some clearer and more in depth documentation describing how to read the output of this command. In general it would be great, if there was more documentation on how to get information on what a tropical hypersurface looks like.

[joschmitt]

I assume that this is fixed by #3923 and #3918. If not, please reopen.