Document reset[h|v]rep! and set[h|v]rep! (JuliaPolyhedra#300)

* Document reset[h|v]rep! and set[h|v]rep!

* Add preview

* Document redundancy

* Export

* Fix

* warning -> info for reset

* Fixes for linearity doc

* Escape

* align -> align*

* Fix

docs/make.jl

@@ -47,4 +47,5 @@ makedocs(
 
 deploydocs(
  repo = "github.com/JuliaPolyhedra/Polyhedra.jl.git",
+ push_preview = true,
 )

docs/src/redundancy.md

@@ -26,6 +26,9 @@ removeduplicates
 
 ## Redundancy
 ```@docs
+Redundancy
+hredundancy
+vredundancy
 isredundant
 removehredundancy
 removehredundancy!

docs/src/representation.md

@@ -75,11 +75,20 @@ For instance, the simplex defined above can be obtained as follows:
 HalfSpace([-1, 0], 0) ∩ HyperPlane([1, 1], 1) ∩ HalfSpace([0, -1], 0)
 ```
 
-In addition to being created incrementally with intersections, an H-representation can also be created using the `hrep` function
+In addition to being created incrementally with intersections, an H-representation can also be created using the [`hrep`](@ref) function.
+The [`hrep`](@ref) function is also used to query the H-representation of a given polyhedron.
 ```@docs
 hrep
 ```
 
+The H-representation of a given polyhedron can be altered with the [`Polyhedra.resethrep!`](@ref)
+and [`Polyhedra.sethrep!`](@ref). Use [`Polyhedra.sethrep!`](@ref) with caution as it does not invalidate
+the V-representation! Use [`Polyhedra.resethrep!`](@ref) in case you are unsure on which one to use.
+```@docs
+Polyhedra.resethrep!
+Polyhedra.sethrep!
+```
+
 ### Interface
 
 An H-representation is represented as an intersection halfspaces and hyperplanes. The halfspaces can be obtained with [`halfspaces`](@ref) and the hyperplanes with [`hyperplanes`](@ref).
@@ -134,11 +143,20 @@ conichull(Line([1, 0]), Line([0, 1]))
 ```
 represents the full space.
 
-In addition to being created incrementally with convex hull and minkowsky addition, a V-representation can also be created using the `vrep` function
+In addition to being created incrementally with convex hull and minkowsky addition, a V-representation can also be created using the [`vrep`](@ref) function.
+The [`vrep`](@ref) function is also used to query the V-representation of a given polyhedron.
 ```@docs
 vrep
 ```
 
+The H-representation of a given polyhedron can be altered with the [`Polyhedra.resetvrep!`](@ref)
+and [`Polyhedra.setvrep!`](@ref). Use [`Polyhedra.setvrep!`](@ref) with caution as it does not invalidate
+the V-representation! Use [`Polyhedra.resetvrep!`](@ref) in case you are unsure on which one to use.
+```@docs
+Polyhedra.resetvrep!
+Polyhedra.setvrep!
+```
+
 ### Interface
 
 A P-representation is represented as a convex hull points.

src/defaultlibrary.jl

@@ -117,23 +117,23 @@ setvrep!(p, v, red) = setvrep!(p, v)
 resethrep!(p, h, red) = resethrep!(p, h)
 resetvrep!(p, v, red) = resetvrep!(p, v)
 
-function sethrep!(p::DefaultPolyhedron, h::HRepresentation, redundancy = UNKNOWN_REDUNDANCY)
+function sethrep!(p::DefaultPolyhedron, h::HRepresentation, redundancy::Redundancy = UNKNOWN_REDUNDANCY)
  p.hrep = h
  p.hred = redundancy
  return
 end
-function setvrep!(p::DefaultPolyhedron, v::VRepresentation, redundancy = UNKNOWN_REDUNDANCY)
+function setvrep!(p::DefaultPolyhedron, v::VRepresentation, redundancy::Redundancy = UNKNOWN_REDUNDANCY)
  p.vrep = v
  p.vred = redundancy
  return
 end
-function resethrep!(p::DefaultPolyhedron, h::HRepresentation, redundancy = UNKNOWN_REDUNDANCY)
+function resethrep!(p::DefaultPolyhedron, h::HRepresentation, redundancy::Redundancy = UNKNOWN_REDUNDANCY)
  p.hrep = h
  p.hred = redundancy
  p.vrep = nothing
  return
 end
-function resetvrep!(p::DefaultPolyhedron, v::VRepresentation, redundancy = UNKNOWN_REDUNDANCY)
+function resetvrep!(p::DefaultPolyhedron, v::VRepresentation, redundancy::Redundancy = UNKNOWN_REDUNDANCY)
  p.vrep = v
  p.vred = redundancy
  p.hrep = nothing

src/linearity.jl

@@ -122,11 +122,13 @@ with nonzero value, we can transform it to a line as well.
 In summary, we have a line `r_i` for each `i` such that `λ_i != 0`.
 
 The dual program is:
+```
 max z
- r_i'x >= z
+s.t. r_i'x ≥ z
+```
 When the primal is feasible, the dual program may still be feasible.
 We know that `z = 0` by strong duality as the objective value needs to be equal to the objective of the primal which is zero.
-So the constraints are `r_i'x >= 0`. If we have `r_i'x > 0` for some `i`, it means that `-r_i` does not belong to the cone
+So the constraints are `r_i'x ≥ 0`. If we have `r_i'x > 0` for some `i`, it means that `-r_i` does not belong to the cone
 hence `r_i` can be dropped for the purpose of searching for lines.
 
 ## Note
@@ -135,7 +137,7 @@ In CDDLib, the dual program is solved, if the objective value is zero then linea
 by, for each `i` such that `r_i'x = 0`, solve an LP to find whether `-r_i` belongs to the cone.
 CDDLib ignores the primal results provided in `λ` which directly gives linearity without the need
 to solve an LP for each ray.
-This method is therefore significantly more efficient as it's complexity is `O(dimension of linespace)` which is upper
+The method implemented in Polyhedra is therefore significantly more efficient as its complexity is `O(dimension of linespace)` which is upper
 bounded by `O(fulldim)` while the method of CDDLib is `O(number of rays)`.
 """
 function detect_new_linearities(rep::Representation, solver; verbose=0, kws...)

src/polyhedron.jl

@@ -24,6 +24,32 @@ Returns an H-representation for the polyhedron `p`.
 """
 hrep(p::Polyhedron) = error("`hrep` not implemented for `$(eltype(p))`")
 
+"""
+ Polyhedra.resethrep!(p::Polyhedron, h::HRepresentation, redundancy::Redundancy = UNKNOWN_REDUNDANCY)
+
+Reset the H-representation of `p` to `h`.
+The redundancy of `p` is assumed to be `redundancy`; see [`Polyhedra.Redundancy`](@ref).
+
+!!! info
+ The representation is not assumed to be a valid representation for `p`
+ so it invalidates the V-representation of `p`.
+ Use [`Polyhedra.sethrep!`](@ref) if `h` is known to be a valid representation for `p`.
+"""
+function resethrep! end
+
+"""
+ Polyhedra.sethrep!(p::Polyhedron, h::HRepresentation, redundancy::Redundancy = UNKNOWN_REDUNDANCY)
+
+Reset the H-representation of `p` to `h`.
+The redundancy of `p` is assumed to be `redundancy`; see [`Polyhedra.Redundancy`](@ref).
+
+!!! warning
+ The representation is assumed to be a valid representation for `p`
+ so it does not invalidate the V-representation of `p` if it was already computed previously.
+ Use [`Polyhedra.resethrep!`](@ref) if `h` is not known to be a valid representation for `p`.
+"""
+function sethrep! end
+
 """
  vrepiscomputed(p::Polyhedron)
 
@@ -38,6 +64,32 @@ Returns a V-representation for the polyhedron `p`.
 """
 vrep(p::Polyhedron) = error("`vrep` not implemented for `$(eltype(p))`")
 
+"""
+ Polyhedra.resetvrep!(p::Polyhedron, v::VRepresentation, redundancy::Redundancy = UNKNOWN_REDUNDANCY)
+
+Reset the V-representation of `p` to `v`.
+The redundancy of `p` is assumed to be `redundancy`; see [`Polyhedra.Redundancy`](@ref).
+
+!!! info
+ The representation is not assumed to be a valid representation for `p`
+ so it invalidates the H-representation of `p`.
+ Use [`Polyhedra.setvrep!`](@ref) if `v` is known to be a valid representation for `p`.
+"""
+function resetvrep! end
+
+"""
+ Polyhedra.setvrep!(p::Polyhedron, v::HRepresentation, redundancy::Redundancy = UNKNOWN_REDUNDANCY)
+
+Reset the H-representation of `p` to `v`.
+The redundancy of `p` is assumed to be `redundancy`; see [`Polyhedra.Redundancy`](@ref).
+
+!!! warning
+ The representation is assumed to be a valid representation for `p`
+ so it does not invalidate the H-representation of `p` if it was already computed previously.
+ Use [`Polyhedra.resetvrep!`](@ref) if `v` is not known to be a valid representation for `p`.
+"""
+function setvrep! end
+
 """
  volume(p::Polyhedron{T}) where {T}
 

src/redundancy.jl

@@ -3,10 +3,43 @@
 ######################
 
 # Redundancy
-export isredundant, removevredundancy!, removevredundancy, removehredundancy!, removehredundancy
+export isredundant, removevredundancy!, removevredundancy, removehredundancy!, removehredundancy, Redundancy, vredundancy, hredundancy
 
+"""
+ @enum Redundancy UNKNOWN_REDUNDANCY LINEARITY_DETECTED NO_REDUNDANCY
+
+Redundancy of a H-representation or V-representation.
+
+* `UNKNOWN_REDUNDANCY`: It is unknown whether there are any undetected linearity or redundancy.
+* `LINEARITY_DETECTED`: There are no undetected linearity.
+* `NO_REDUNDANCY`: There are no undetected linearity not redundancy.
+
+An *undetected linearity* for a V-representation is a [`Line`](@ref) that is implicit in a conic hull of [`Ray`](@ref)s.
+For instance, `conichull([1, 1], [-1, -1])` has undetected linearity because it contains
+the [`Line`](@ref) `Line([1, 1])`.
+Some undetected linearity is less obvious, e.g., `conichull([1, 0, -1], [0, 1, 1], [-1, -1, 0])`
+contains the [`Line`](@ref) `Line([1, 1, 0])` as the sum of the first two [`Ray`](@ref)s is `Ray([1, 1, 0])`.
+
+An *undetected linearity* for a H-representation is a [`HyperPlane`](@ref) that is implicit in an intersection of [`HalfSpace`](@ref)s.
+For instance, `HalfSpace([1, 1], 1) ∩ HalfSpace([-1, -1], 1)` has undetected linearity because it contains
+the [`HyperPlane`](@ref) `HyperPlane([1, 1], 1)`.
+Some undetected linearity is less obvious, e.g., `HalfSpace([1, 0], -1) ∩ HalfSpace([0, 1], 1) ∩ HalfSpace([-1, -1], 0)`
+contains the [`HyperPlane`](@ref) `HyperPlane([1, 1], 0)` as the sum of the first two [`HalfSpace`](@ref)s is `HalfSpace([1, 1], 0)`.
+"""
 @enum Redundancy UNKNOWN_REDUNDANCY LINEARITY_DETECTED NO_REDUNDANCY
+
+"""
+ hredundancy(p::Polyhedron)
+
+Return the [`Redundancy`](@ref) of [`hrep(p)`](@ref hrep).
+"""
 hredundancy(::Polyhedron) = UNKNOWN_REDUNDANCY
+
+"""
+ vredundancy(p::Polyhedron)
+
+Return the [`Redundancy`](@ref) of [`vrep(p)`](@ref vrep).
+"""
 vredundancy(::Polyhedron) = UNKNOWN_REDUNDANCY
 
 """