Codac2 polytope

CMakeLists.txt

@@ -210,4 +210,4 @@
   set(CPACK_DEBIAN_PACKAGE_HOMEPAGE ${CODAC_URL})
   # todo: finish deb package
 
-  include(CPack)
+  include(CPack)

doc/manual/manual/contractors/index.rst

@@ -1,3 +1,4 @@
+.. _sec-ctc:
 Contractors, separators
 =======================
 

doc/manual/manual/geometry/facets.rst

@@ -0,0 +1,33 @@
+.. _sec-polytope:
+
+Facet classes
+=============
+
+  Main author: `Damien Massé <https://labsticc.fr/fr/annuaire/masse-damien>`_
+
+Facets
+------
+
+.. doxygentypedef:: codac2::Facet
+  :project: codac
+
+.. doxygennamespace:: codac2::Facet_
+  :project: codac
+  :members:
+
+.. doxygenclass:: codac2::FacetBase
+  :project: codac
+  :members:
+
+.. doxygenclass:: codac2::FacetRhs
+  :project: codac
+  :members:
+
+
+Collection of facets
+--------------------
+
+.. doxygenclass:: codac2::CollectFacets
+  :project: codac
+  :members:
+

doc/manual/manual/geometry/index.rst

@@ -3,7 +3,7 @@
 Geometry
 ========
 
-Codac provides a set of utility functions for basic 2d geometric calculations.
+Codac provides a set of utility functions for basic geometric calculations.
 
 Several basic geometric types are available under the form of classes representing enclosures of these types. For instance, a 2d point if represented by an ``IntervalVector`` enclosing it, a segment between two 2d points is implemented by the ``Segment`` class, the endpoints of which are ``IntervalVector`` objects. Furthermore, ``Polygon`` and ``ConvexPolygon`` are also available. Operations between these structure will reliably meet the uncertainties associated with the enclosure of points (vertices), as well as floating-point calculations.
 
@@ -16,6 +16,7 @@ Because computations are based on interval arithmetic, all these functions provi
   segment.rst
   polygon.rst
   zonotope.rst
+  polytope.rst
 
 Related interval enumerations
 -----------------------------

doc/manual/manual/geometry/polytope.rst

@@ -0,0 +1,60 @@
+.. _sec-polytope:
+
+Polytope
+========
+
+  Main author: `Damien Massé <https://labsticc.fr/fr/annuaire/masse-damien>`_
+
+The Polytope class represent convex polytopes (or, more generally, 
+convex polyhedra).
+Polytopes are internally represented as intersections of linear constraints
+(and a bounding box), in a class name CollectFacets.
+A double-description algorithm is used to compute generators for operations
+requiring them (union, projections...). Due to the imprecise nature of
+floating-point computations, the algorithm is designed such that the
+convex hull of the "generators" encloses the polytope. However, no guarantee
+is given that each vertice of the polytope is associated to a generator.
+As a result,
+going back to the hyperplane representation may return a larger polytope.
+
+.. toctree::
+  :maxdepth: 1
+
+  facets.rst
+  polytope_class.rst
+
+
+Building a polytope
+-------------------
+Polytopes can be defined from a set of facets (linear inequalities 
+or equalities), or a set of vertices. 
+
+.. tabs::
+
+  .. group-tab:: C++
+
+    .. literalinclude:: src_polytope.cpp
+      :language: c++
+      :start-after: [polytope-1-beg]
+      :end-before: [polytope-1-end]
+      :dedent: 2
+
+Output of a polytope
+--------------------
+Polytopes are displayed as a set of linear constraints and a bounding box.
+To display the set of vertices, one can use the 
+vertices() method.
+
+.. tabs::
+
+  .. group-tab:: C++
+
+    .. literalinclude:: src_polytope.cpp
+      :language: c++
+      :start-after: [polytope-2-beg]
+      :end-before: [polytope-2-end]
+      :dedent: 2
+
+Operations on polytopes
+-----------------------
+

doc/manual/manual/geometry/polytope_class.rst

@@ -0,0 +1,14 @@
+.. _sec-polytope:
+
+The Polytope class
+==================
+
+  Main author: `Damien Massé <https://labsticc.fr/fr/annuaire/masse-damien>`_
+
+Polytope
+--------
+
+.. doxygenclass:: codac2::Polytope
+  :project: codac
+  :members:
+

doc/manual/manual/geometry/src_polytope.cpp

@@ -0,0 +1,83 @@
+// Author : Damien Massé
+// Graphical illustration of the polytope test
+
+#include <codac>
+#include <vector>
+#include <memory>
+
+using namespace std;
+using namespace codac2;
+
+void draw_polytope(Figure3D &fig, const Polytope &P, const StyleProperties &st) {
+   std::vector<std::vector<Vector>> facets3D=P.vertices_3Dfacets();
+   Vector center = Vector::zero(3);
+   Matrix transfo = Matrix::Identity(3,3);
+   for (const std::vector<Vector> &vec : facets3D) {
+      fig.draw_polygon(center,transfo,vec,st);
+   }
+}
+
+int main(int argc, char *argv[])
+{
+//   std::cout << std::scientific << std::setprecision(20);
+
+   Figure3D fig("manual_polytope");
+
+   fig.draw_axes();
+
+   // [polytope-1-beg]
+   // definition using vertices
+   std::vector<Vector> vertices 
+       { {0,0,0}, {2,1,0}, {-1,1,0}, {0,1.5,2}, {-1.5,0,-1.5}, {0,3,0} };
+   Polytope p1(vertices); // vertices {0,0,0}, {2,1,0}, etc.
+   // definition using facets
+   std::vector<std::pair<Row,double>> facets 
+       { { {1,1,0.75}, 3 },        // x+y+0.75z <= 3
+         { {-1,-0.4,0.6} ,0.6 },   // -x-0.4y+0.6z <= 0.6
+         { {-1,0.5,0.375} ,1.5 },  // ...
+         { {-1,0.5,0} ,1.5 },
+         { {0.5,-1,0.75} ,0 },
+         { {-0.75,-1,0.75} ,0 },
+         { {0.5,-1,-0.5} ,0 },
+         { {1.0/3.0,1.0/3.0,-1} ,1 } };
+   // the first argument is a bounding box, here the whole space
+   Polytope p2(IntervalVector(3), facets);
+   // p1 and p2 are almost the same polytope
+   // [polytope-1-end]
+
+
+   // [polytope-2-beg]
+   std::cout << p1 << std::endl;
+   /* output, each facet is a row (sequences of double) and a right-hand-side
+    Polytope(bbox [ [-1.5, 2] ; [0, 3] ; [-1.5, 2] ]) : 
+    Collectfacets : 8 facets
+    1 :    1    1 0.75<=3
+    2 :        -1 -0.399999       0.6<=0.600001
+    3 :    -1   0.5 0.375<=1.5
+    4 :          -1         0.5 1.77636e-16<=1.5
+    5 :  0.5   -1 0.75<=0
+    6 :    -0.75       -1 0.750001<=5.92119e-16
+    7 :  0.5   -1 -0.5<=0
+    8 : 0.333334 0.333334       -1<=1
+     end Collectfacets
+    EndPolytope
+   */
+   std::vector<IntervalVector> vp2 = p2.vertices(); /* hull of p2 */
+   for (auto &v : vp2) std::cout << v << std::endl;
+   /* output : "vertices" are boxes which enclose the polytope, but each
+      box may not enclose a "real vertice". E.g. the vertice (0,0,0) is
+      not inside the second box displayed.
+    [ [1.99999, 2.00001] ; [0.999999, 1.00001] ; [-2.4743e-14, -1.70641e-15] ]
+    [ [-7.76463e-15, 1.69539e-14] ; [-3.15401e-14, -2.88916e-15] ; [-2.52802e-14, -2.40763e-15] ]
+    [ [-1.50001, -1.5] ; [-1.16016e-14, -9.33785e-15] ; [-1.50001, -1.5] ]
+    [ [-7.11673e-15, 1.609e-14] ; [1.49999, 1.50001] ; [1.99999, 2.00001] ]
+    [ [-2.47539e-15, 9.90153e-16] ; [2.99999, 3.00001] ; [-2.31036e-15, 3.30051e-15] ]
+    [ [-1.00001, -0.999999] ; [1, 1.00001] ; [1.83361e-15, 3.20883e-15] ]
+   */
+   // [polytope-2-end]
+
+   fig.draw_polytope(p1,StyleProperties(Color::dark_red(0.8),"p1"));
+   fig.draw_polytope(p2,StyleProperties(Color::dark_blue(0.8),"p2"));
+
+   return 0;
+}

doc/manual/manual/geometry/zonotope.rst

@@ -12,15 +12,69 @@ The following classes represent zonotopes.
 Zonotope
 --------
 
-.. doxygenclass:: codac2::Zonotope
-  :project: codac
-  :members:
+A zonotope is a convex and symmetric polytope. 
+It can be represented as the Minkowski sum of a finite number of line segments, which are called its generators.
+
+In Codac, zonotopes are represented by the class :class:`Zonotope`. A zonotope is defined by its center and its generators.
+The center is a :class:`Vector`, noted :math:`z`, and the generators are stored in a :class:`Matrix`, noted :math:`A`. 
+Each column of the matrix corresponds to a generator.
+
+The resulting zonotope is:
+
+.. math::
+  Z = z + A \cdot [-1,1]^m
+
+Where :math:`m` is the number of generators (i.e., the number of columns of the matrix :math:`A`).
+
+For example, let us consider the following zonotope in :math:`\mathbb{R}^2`:
+
+.. math::
+  Z = \left(\begin{array}{c} 1\\ 2\\ \end{array}\right) + \left(\begin{array}{ccc} 1 & 0 & 2 \\ 0 & 1 & 1 \end{array}\right) \cdot [-1,1]^3
+
+It can be constructed in Codac as follows:
+
+.. tabs::
+
+  .. code-tab:: py
+
+    z = Vector([1,2])
+    A = Matrix([[1,0,2],[0,1,1]])
+
+    Z = Zonotope(z, A)
+
+  .. code-tab:: c++
+
+    Vector z({1,2});
+    Matrix A({{1,0,2},{0,1,1}});
+
+    Zonotope Z(z, A);
+
+  .. code-tab:: matlab
+
+    z = Vector({1,2});
+    A = Matrix({{1,0,2},{0,1,1}});
+
+    Z = Zonotope(z,A);
+
+The resulting zonotope is represented in the figure below:
+
+.. figure:: zonotope.png
+    :width: 400px
+
+Additional methods are provided to handle zonotopes.
+
+- `box()`: gives the bounding box of the zonotope. Returns an :class:`IntervalVector`.
+- `proj(v)`: Projects the zonotope on a given subspace, defined by the vector of indices `v` (:class:`std::vector\<Index\>`). Returns a :class:`Zonotope`.
 
 .. _subsec-zonotope-parallelepiped:
 
 Parallelepiped
 --------------
 
-.. doxygenclass:: codac2::Parallelepiped
-  :project: codac
-  :members:
+A parallelepiped is a special case of zonotope, where the number of generators is equal or less than the dimension of the space.
+
+It inherits from the `Zonotope` class, and thus has the same properties and methods. In addition, it defines the following methods:
+
+- `vertices()`: gives the vertices of the parallelepiped. Returns a :class:`std::vector\<Vector\>`.
+- `contains(v)`: checks if the point `v` is contained in the parallelepiped. Returns a :class:`BoolInterval`. **The matrix A must be invertible**
+- `is_superset(x)`: checks if the parallelepiped is a superset of the :class:`IntervalVector` `x`. Returns a :class:`BoolInterval`. **The matrix A must be invertible**