Documentation: vertices_and_rays and maximal_polyhedra (tropical …

…variety) (oscar-system#3918)

docs/src/TropicalGeometry/hypersurface.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = Oscar
+DocTestSetup = Oscar.doctestsetup()
+```
 # Tropical hypersurfaces
 
 ## Introduction
@@ -26,3 +30,76 @@ algebraic_polynomial(TropH::TropicalHypersurface)
 tropical_polynomial(TropH::TropicalHypersurface)
 dual_subdivision(TropH::TropicalHypersurface)
 ```
+
+## Example
+The following code sets up an example and prints the vertices and rays of the tropical hypersurface (in no particular order).
+```jldoctest exampleHypersurface
+julia> T = tropical_semiring();
+
+julia> Tx,(x1,x2) = polynomial_ring(T, 2);
+
+julia> g = 1 + 2*x1^2 + 2*x2^2 + 1*x1*x2;
+
+julia> TropH = tropical_hypersurface(g);
+
+julia> vertRays = vertices_and_rays(TropH)
+5-element SubObjectIterator{Union{PointVector{QQFieldElem}, RayVector{QQFieldElem}}}:
+ [-1, -1]
+ [1, 0]
+ [0, 1]
+ [-1//2, 1//2]
+ [1//2, -1//2]
+```
+By broadcasting the `typeof()` command, we can see, which are vertices, and which are rays.
+```jldoctest exampleHypersurface
+julia> typeof.(vertRays)
+5-element Vector{DataType}:
+ RayVector{QQFieldElem}
+ RayVector{QQFieldElem}
+ RayVector{QQFieldElem}
+ PointVector{QQFieldElem}
+ PointVector{QQFieldElem}
+```
+The maximal polyhedra of our tropical hypersurface is simply the edges (both bounded and unbounded). The command `maximal_polyhedra()` gives us a list of these edges (in no particular order).
+```jldoctest exampleHypersurface
+julia> maxPol = maximal_polyhedra(TropH)
+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
+```
+The polyhedrons are the unbounded edges, and the polytopes are the bounded edges.
+
+The incidence matrix of the maximal polyhedra is a list of the relations between the elements of `vertices_and_rays(TropH)`. 
+From these relations, we can draw the hypersurface. However, one should be careful, as there is no distinction between vertices and rays in the incidence matrix.
+```jldoctest exampleHypersurface
+julia> IncidenceMatrix(maxPol)
+5×5 IncidenceMatrix
+[1, 4]
+[1, 5]
+[3, 4]
+[4, 5]
+[2, 5]
+```
+This is made clearer if we ask for the vertices of each of the maximal polyhedra (the bounded edges have a vertex at each end, while the unbounded only have one vertex).
+```jldoctest exampleHypersurface
+julia> vertices.(maxPol)
+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]]
+```
+Instead of being between two vertices, the unbounded edges are defined by a vertex and a ray. These rays can be seen in the following way.
+```jldoctest exampleHypersurface
+julia> rays.(maxPol)
+5-element Vector{SubObjectIterator{RayVector{QQFieldElem}}}:
+ [[-1, -1]]
+ [[-1, -1]]
+ [[0, 1]]
+ 0-element SubObjectIterator{RayVector{QQFieldElem}}
+ [[1, 0]]
+```