Merge pull request #468 from oscar-system/docs/Polytopes

Polytopes: Initial documentation

docs/make_work.jl

@@ -16,10 +16,10 @@ import Documenter.Documents: Document, Page
 #=
  copied from Documenter (0.26.1)
 
- Adds the loop to collect the AA/Nemo/Hecke doc files into the 
+ Adds the loop to collect the AA/Nemo/Hecke doc files into the
  build tree of Oscar.
 
-=# 
+=#
 function Selectors.runner(::Type{SetupBuildDirectory}, doc::Documents.Document)
     @info "SetupBuildDirectory: setting up build directory."
 
@@ -219,7 +219,7 @@ makedocs(bib,
                               "$(nemo)/series.md",
                               "$(nemo)/puiseux.md"],
                          ],
-             "Fields" => [            
+             "Fields" => [
                           "$(aa)/fields.md",
 			  "Rings/rational.md",
                           "Number Fields" => [
@@ -234,7 +234,7 @@ makedocs(bib,
                           "Local Fields" => [
                               "$(nemo)/padic.md",
                               "$(nemo)/qadic.md"],
-                          "$(nemo)/finitefield.md",    
+                          "$(nemo)/finitefield.md",
                          ],
              "Groups" => [ "Groups/groups.md",
                            "Groups/basics.md",
@@ -274,6 +274,9 @@ makedocs(bib,
 				       "CommutativeAlgebra/ca_affine_algebras.md",
 				       "CommutativeAlgebra/ca_binomial_ideals.md",
 				       "CommutativeAlgebra/ca_invariant_theory.md"],
+             "Polyhedral Geometry" => ["PolyhedralGeometry/pg.md",
+                       "PolyhedralGeometry/pg_polyhedra.md",
+                       "PolyhedralGeometry/pg_linear_programs.md"],
              "References" => "references.md",
              "Index" => "manualindex.md",
          ]

docs/oscar_references.bib

@@ -284,6 +284,27 @@ @article{EM19
        URL = {https://doi.org/10.1112/jlms.12232},
 }
 
+@Book{JT13,
+  author = 	 {Joswig, Michael and Theobald, Thorsten},
+  title = 	 {Polyhedral and Algebraic Methods in Computational Geometry},
+  publisher = 	 {Springer},
+  year = 	 {2013}
+}
+
+@BOOK{Zie95,
+  title = {Lectures on polytopes},
+  publisher = {Springer-Verlag},
+  year = {1995},
+  author = {Ziegler, Günter M.},
+  volume = {152},
+  pages = {x+370},
+  series = {Graduate Texts in Mathematics},
+  address = {New York},
+  isbn = {0-387-94365-X},
+  mrclass = {52Bxx},
+  mrnumber = {MR1311028 (96a:52011)},
+  mrreviewer = {Margaret M. Bayer}
+}
 
 @inproceedings{BDLP19,
   TITLE = {{Computing integral bases via localization and Hensel lifting}},

docs/src/PolyhedralGeometry/pg.md

@@ -0,0 +1,21 @@
+```@meta
+CurrentModule = Oscar
+```
+
+```@setup oscar
+using Oscar
+```
+
+```@contents
+Pages = ["pg.md"]
+```
+
+# Introduction
+
+The polyhedral geometry part of OSCAR provides functionality for handling
+- convex polytopes, unbounded polyhedra and cones
+- linear programs
+
+General textbooks offering details on theory and algorithms include: 
+- [JT13](@cite)
+- [Zie95](@cite)

docs/src/PolyhedralGeometry/pg_cones.md

@@ -0,0 +1,17 @@
+```@meta
+CurrentModule = Oscar
+```
+
+```@setup oscar
+using Oscar
+```
+
+```@contents
+Pages = ["pg_cones.md"]
+```
+
+# Cones
+
+## Introduction
+
+## Constructions

docs/src/PolyhedralGeometry/pg_linear_programs.md

@@ -0,0 +1,20 @@
+```@meta
+CurrentModule = Oscar
+```
+
+```@setup oscar
+using Oscar
+```
+
+```@contents
+Pages = ["pg_linear_programs.md"]
+```
+
+# Linear programs
+
+## Introduction
+
+## Constructions
+
+
+

docs/src/PolyhedralGeometry/pg_polyhedra.md

@@ -0,0 +1,71 @@
+```@meta
+CurrentModule = Oscar
+```
+
+```@setup oscar
+using Oscar
+```
+
+```@contents
+Pages = ["pg_polyhedra.md"]
+```
+
+# Polyhedra
+
+## Introduction
+
+A set $P \subseteq \mathbb{R}^n$ is called a (convex) polyhedron if it can be written as the intersection of finitely many closed affine halfspaces in $\mathbb{R}^n$.
+That is, there exists a matrix $A$ and a vector $b$ such that
+$$P = P(A,b) = \{ x \in \mathbb{R}^n \mid Ax \leq b\}.$$
+Writing $P$ as above is called an $H$-representation of $P$.
+
+When a polyhedron $P \subset \mathbb{R}^n$ is bounded, it is called a polytope and the fundamental theorem of polytopes states that it may be written as the convex hull of finitely many points.
+That is $$P = \textrm{conv}(p_1,\ldots,p_N), p_i \in \mathbb{R}^n.$$
+Writing $P$ in this way is called a $V$-representation.
+Polytopes are necessarily compact, i.e., they form convex bodies.
+
+Each polytope has a unique $V$-representation which is minimal with respect to inclusion (or cardinality).
+Conversely, a polyhedron which is full-dimensional, has a unique minimal $H$-representation.
+If the polyhedron is not full-dimensional, then there is no canonical choice of an $H$-representation.
+
+
+## Construction
+
+Based on the definition of an $H$-representation, the constructor of `Polyhedron` can be used:
+
+```@docs
+Polyhedron(A::Union{Oscar.MatElem,AbstractMatrix}, b)
+```
+
+The following defines a polytope, as a `Polyhedron`, via a $V$-representation by calling the following function:
+
+```@docs
+convex_hull(::AnyVecOrMat)
+```
+
+### Computing convex hulls
+
+This is a standard triangle, defined via a (redundant) $V$-representation  and its unique minimal $H$-representation:
+
+```@repl oscar
+T = convex_hull([ 0 0 ; 1 0 ; 0 1; 0 1/2 ])
+facets_as_halfspace_matrix_pair(T)
+```
+
+## `Polyhedron` and `polymake`'s `Polytope`
+
+Many polyhedral computations are done through `polymake`.
+This is visible in the structure `Polyhedron` via a pointer  `pm_polytope` to the corresponding `polymake` object.
+This allows to apply all functionality of `polymake` by calling a suitable `Polymake.jl` function on this pointer.
+
+To allow both `Oscar`'s and `polymake`'s functionality to be applicable to a polyhedron object, it can be converted back and forth:
+
+```@docs
+Polyhedron(::Polymake.BigObject)
+pm_polytope(::Polyhedron)
+```
+
+There are several design differences between `polymake` and `Oscar`.
+
+!!! warning
+    Polyhedra in `polymake` and `Polymake.jl` use homogeneous coordinates. The polyhedra in `Oscar` use affine coordinates.

docs/src/index.md

@@ -1,3 +1,6 @@
 # Welcome to Oscar
 
-Oscar is a new computer algebra system under development.
+Oscar is a new computer algebra system.
+While it is still under development it can already be used.
+
+Oscar features functions for groups, rings, and fields as well as linear and commutative algebra, number theory, algebraic and polyhedral geometry, and more.

src/Polytopes/Cone/constructors.jl

@@ -5,10 +5,33 @@
 ###############################################################################
 
 @doc Markdown.doc"""
-    Cone(Rays)
+    Cone(R [, L])
 
-     A polyhedral cone, not necessarily pointed, defined by the positive hull
-     of the rays, Rays.
+# Arguments
+- `R::Matrix`: Rays generating the cone; encoded row-wise as representative vectors.
+- `L::Matrix`: Generators of the Lineality space; encoded as row vectors.
+
+A polyhedral cone, not necessarily pointed, defined by the positive hull
+of the rays, Rays.
+
+# Examples
+To construct the positive orthant as a `Cone`, you can write:
+```julia-repl
+julia> R = [1 0; 0 1];
+
+julia> PO = Cone(R)
+A polyhedral cone in ambient dimension 2
+```
+
+To obtain the upper half-space of the plane:
+```julia-repl
+julia> R = [0 1];
+
+julia> L = [1 0];
+
+julia> HS = Cone(R, L)
+A polyhedral cone in ambient dimension 2
+```
 """
 struct Cone #a real polymake polyhedron
     pm_cone::Polymake.BigObject
@@ -36,10 +59,21 @@ end
 
 
 """
-    positive_hull(generators::Union{Oscar.MatElem,AbstractMatrix})
+    positive_hull(generators)
 
 A polyhedral cone, not necessarily pointed, defined by the positive hull
 of the `generators`. Redundant rays are allowed in the generators.
+
+# Arguments
+- `generators::Matrix`: Rays generating the cone; encoded row-wise as representative vectors.
+
+# Examples
+```julia-repl
+julia> R = [1 0; 0 1];
+
+julia> PO = positive_hull(R)
+A polyhedral cone in ambient dimension 2
+```
 """
 function positive_hull(generators::Union{Oscar.MatElem,AbstractMatrix})
     # TODO: Filter out zero rows
@@ -68,4 +102,3 @@ function Base.show(io::IO, C::Cone)
 end
 
 Polymake.visual(C::Cone; opts...) = Polymake.visual(pm_cone(C); opts...)
-