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 Z-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(0 <= x, x <= 2, 0 <= y, y <= 2)
  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(1 <= x, x <= 3, 1 <= y, y <= 3)
  35
  36 The usual polyhedral operations are available, including intersection:
  37
  38 >>> inter = square1.intersection(square2) # or square1 & square2
  39 >>> inter
  40 And(1 <= x, x <= 2, 1 <= y, y <= 2)
  41
  42 convex union:
  43
  44 >>> hull = square1.convex_union(square2)
  45 >>> hull
  46 And(0 <= x, 0 <= y, x <= y + 2, y <= x + 2, x <= 3, y <= 3)
  47
  48 and projection:
  49
  50 >>> proj = square1.project([y])
  51 >>> proj
  52 And(0 <= x, x <= 2)
  53
  54 Equality and inclusion tests are also provided.
  55 Special values :data:`Empty` and :data:`Universe` represent the empty and universe polyhedra.
  56
  57 >>> inter <= square1
  58 True
  59 >>> inter == Empty
  60 False
  61
  62
  63 .. _tutorial_domains:
  64
  65 Domains
  66 -------
  67
  68 LinPy is also able to manipulate polyhedral *domains*, that is, unions of polyhedra.
  69 An example of domain is the set union (as opposed to convex union) of polyhedra ``square1`` and ``square2``.
  70 The result is a :class:`Domain` object.
  71
  72 >>> union = square1.union(square2) # or square1 | square2
  73 >>> union
  74 Or(And(x <= 2, 0 <= x, y <= 2, 0 <= y), And(x <= 3, 1 <= x, y <= 3, 1 <= y))
  75 >>> union <= hull
  76 True
  77
  78 Unlike polyhedra, domains allow exact computation of union, subtraction and complementary operations.
  79
  80 >>> diff = square1.difference(square2) # or square1 - square2
  81 >>> diff
  82 Or(And(x == 0, 0 <= y, y <= 2), And(y == 0, 1 <= x, x <= 2))
  83 >>> ~square1
  84 Or(x + 1 <= 0, 3 <= x, And(0 <= x, x <= 2, y + 1 <= 0), And(0 <= x, x <= 2, 3 <= y))
  85
  86
  87 .. _tutorial_plot:
  88
  89 Plotting
  90 --------
  91
  92 LinPy can use the :mod:`matplotlib` plotting library, if available, to plot bounded polyhedra and domains.
  93
  94 >>> import matplotlib.pyplot as plt
  95 >>> from matplotlib import pylab
  96 >>> fig = plt.figure()
  97 >>> plot = fig.add_subplot(1, 1, 1, aspect='equal')
  98 >>> square1.plot(plot, facecolor='red', alpha=0.3)
  99 >>> square2.plot(plot, facecolor='blue', alpha=0.3)
 100 >>> hull.plot(plot, facecolor='blue', alpha=0.3)
 101 >>> pylab.show()
 102
 103 Note that you can pass a plot object to the :meth:`Domain.plot` method, which provides great flexibility.
 104 Also, keyword arguments can be passed such as color and the degree of transparency of a polygon.
 105
 106 .. figure:: images/union.jpg
 107     :align:  center
 108
 109 3D plots are also supported:
 110
 111 >>> import matplotlib.pyplot as plt
 112 >>> from matplotlib import pylab
 113 >>> from mpl_toolkits.mplot3d import Axes3D
 114 >>> from linpy import *
 115 >>> x, y, z = symbols('x y z')
 116 >>> fig = plt.figure()
 117 >>> plot = fig.add_subplot(1, 1, 1, projection='3d', aspect='equal')
 118 >>> plot.set_title('Chamfered cube')
 119 >>> poly = Le(0, x, 3) & Le(0, y, 3) & Le(0, z, 3) & \
 120            Le(z - 2, x) & Le(x, z + 2) & Le(1 - z, x) & Le(x, 5 - z) & \
 121            Le(z - 2, y) & Le(y, z + 2) & Le(1 - z, y) & Le(y, 5 - z) & \
 122            Le(y - 2, x) & Le(x, y + 2) & Le(1 - y, x) & Le(x, 5 - y)
 123 >>> poly.plot(plot, facecolor='red', alpha=0.75)
 124 >>> pylab.show()
 125
 126 .. figure:: images/cham_cube.jpg
 127     :align:  center