Documentation: vertices_and_rays and maximal_polyhedra (tropical variety)

docs/src/TropicalGeometry/hypersurface.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = Oscar
+DocTestSetup = Oscar.doctestsetup()
+```
 # Tropical hypersurfaces
 
 ## Introduction
@@ -23,3 +27,63 @@ 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> 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> vertRays = 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]
+```
+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> 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
+```
+The polyhedrons are the unbounded edges, and the polytopes are the bounded edges. This is also made clear 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.(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]]
+```
+Instead of being between two vertices, the unbounded edges are defined by a vertex and a ray.
+```jldoctest exampleHypersurface
+julia> rays.(maxPolTg)
+5-element Vector{SubObjectIterator{RayVector{QQFieldElem}}}:
+ [[-1, -1]]
+ [[-1, -1]]
+ [[0, 1]]
+ 0-element SubObjectIterator{RayVector{QQFieldElem}}
+ [[1, 0]]
+```