doc/tutorial.rst

   1
   2 .. _tutorial:
   3
   4 Tutorial
   5 ========
   6
   7 This section a short introduction to some of LinPy's features.
   8 For a comprehensive description of its functionalities, please consult the :ref:`reference`.
   9
  10
  11 .. _tutorial_polyhedra:
  12
  13 Polyhedra
  14 ---------
  15
  16 The following example shows how we can manipulate polyhedra using LinPy.
  17 Let us define two square polyhedra, corresponding to the sets ``square1 = {(x, y) | 0 <= x <= 2, 0 <= y <= 2}`` and ``square2 = {(x, y) | 2 <= x <= 4, 2 <= y <= 4}``.
  18 First, we need define the symbols used, for instance with the :func:`symbols` function.
  19
  20 >>> from linpy import *
  21 >>> x, y = symbols('x y')
  22
  23 Then, we can build the :class:`Polyhedron` object ``square1`` from its constraints:
  24
  25 >>> square1 = Le(0, x, 2) & Le(0, y, 2)
  26 >>> square1
  27 And(Ge(x, 0), Ge(-x + 2, 0), Ge(y, 0), Ge(-y + 2, 0))
  28
  29 LinPy provides comparison functions :func:`Lt`, :func:`Le`, :func:`Eq`, :func:`Ne`, :func:`Ge` and :func:`Gt` to build constraints, and logical operators :func:`And`, :func:`Or`, :func:`Not` to combine them.
  30 Alternatively, a polyhedron can be built from a string:
  31
  32 >>> square2 = Polyhedron('1 <= x <= 3, 1 <= y <= 3')
  33 >>> square2
  34 And(Ge(x - 1, 0), Ge(-x + 3, 0), Ge(y - 1, 0), Ge(-y + 3, 0))
  35
  36 The usual polyhedral operations are available, including intersection:
  37
  38 >>> inter = square1.intersection(square2)
  39 >>> inter
  40 And(Ge(x - 1, 0), Ge(-x + 2, 0), Ge(y - 1, 0), Ge(-y + 2, 0))
  41
  42 convex union:
  43
  44 >>> hull = square1.convex_union(square2)
  45 >>> hull
  46 And(Ge(x, 0), Ge(y, 0), Ge(-x + y + 2, 0), Ge(x - y + 2, 0), Ge(-x + 3, 0), Ge(-y + 3, 0))
  47
  48 and projection:
  49
  50 >>> square1.project([y])
  51 And(Ge(x, 0), Ge(-x + 2, 0))
  52
  53 Equality and inclusion tests are also provided.
  54 Special values :data:`Empty` and :data:`Universe` represent the empty and universe polyhedra.
  55
  56 >>> inter <= square1
  57 True
  58 >>> inter == Empty
  59 False
  60
  61
  62 .. _tutorial_domains:
  63
  64 Domains
  65 -------
  66
  67 LinPy is also able to manipulate polyhedral *domains*, that is, unions of polyhedra.
  68 An example of domain is the set union (as opposed to convex union) of polyhedra ``square1`` and ``square2``.
  69 The result is a :class:`Domain` object.
  70
  71 >>> union = square1 | square2
  72 >>> union
  73 Or(And(Ge(-x + 2, 0), Ge(x, 0), Ge(-y + 2, 0), Ge(y, 0)), And(Ge(-x + 3, 0), Ge(x - 1, 0), Ge(-y + 3, 0), Ge(y - 1, 0)))
  74 >>> union <= hull
  75 True
  76
  77 Unlike polyhedra, domains allow exact computation of union, subtraction and complementary operations.
  78
  79 >>> diff = square1 - square2
  80 >>> diff
  81 Or(And(Eq(x, 0), Ge(y, 0), Ge(-y + 2, 0)), And(Eq(y, 0), Ge(x - 1, 0), Ge(-x + 2, 0)))
  82 >>> ~square1
  83 Or(Ge(-x - 1, 0), Ge(x - 3, 0), And(Ge(x, 0), Ge(-x + 2, 0), Ge(-y - 1, 0)), And(Ge(x, 0), Ge(-x + 2, 0), Ge(y - 3, 0)))
  84
  85
  86 .. _tutorial_plot:
  87
  88 Plotting
  89 --------
  90
  91 LinPy can use the :mod:`matplotlib` plotting library, if available, to plot bounded polyhedra and domains.
  92
  93 >>> import matplotlib.pyplot as plt
  94 >>> from matplotlib import pylab
  95 >>> fig = plt.figure()
  96 >>> plot = fig.add_subplot(1, 1, 1, aspect='equal')
  97 >>> square1.plot(plot, facecolor='red', alpha=0.3)
  98 >>> square2.plot(plot, facecolor='blue', alpha=0.3)
  99 >>> hull.plot(plot, facecolor='blue', alpha=0.3)
 100 >>> pylab.show()
 101
 102 Note that you can pass a plot object to the :meth:`Domain.plot` method, which provides great flexibility.
 103 Also, keyword arguments can be passed such as color and the degree of transparency of a polygon.
 104
 105 .. figure:: images/union.jpg
 106     :align:  center
 107
 108 3D plots are also supported:
 109
 110 >>> import matplotlib.pyplot as plt
 111 >>> from matplotlib import pylab
 112 >>> from mpl_toolkits.mplot3d import Axes3D
 113 >>> from linpy import *
 114 >>> x, y, z = symbols('x y z')
 115 >>> fig = plt.figure()
 116 >>> plot = fig.add_subplot(1, 1, 1, projection='3d', aspect='equal')
 117 >>> plot.set_title('Chamfered cube')
 118 >>> poly = Le(0, x, 3) & Le(0, y, 3) & Le(0, z, 3) & \
 119            Le(z - 2, x) & Le(x, z + 2) & Le(1 - z, x) & Le(x, 5 - z) & \
 120            Le(z - 2, y) & Le(y, z + 2) & Le(1 - z, y) & Le(y, 5 - z) & \
 121            Le(y - 2, x) & Le(x, y + 2) & Le(1 - y, x) & Le(x, 5 - y)
 122 >>> poly.plot(plot, facecolor='red', alpha=0.75)
 123 >>> pylab.show()
 124
 125 .. figure:: images/cham_cube.jpg
 126     :align:  center