doc/reference.rst

   1
   2 .. _reference:
   3
   4 Module Reference
   5 ================
   6
   7
   8 .. _reference_symbols:
   9
  10 Symbols
  11 -------
  12
  13 *Symbols* are the basic components to build expressions and constraints.
  14 They correspond to mathematical variables.
  15
  16 .. class:: Symbol(name)
  17
  18     Return a symbol with the name string given in argument.
  19     Alternatively, the function :func:`symbols` allows to create several symbols at once.
  20     Symbols are instances of class :class:`LinExpr` and inherit its functionalities.
  21
  22     >>> x = Symbol('x')
  23     >>> x
  24     x
  25
  26     Two instances of :class:`Symbol` are equal if they have the same name.
  27
  28     .. attribute:: name
  29
  30         The name of the symbol.
  31
  32     .. method:: asdummy()
  33
  34         Return a new :class:`Dummy` symbol instance with the same name.
  35
  36     .. method:: sortkey()
  37
  38         Return a sorting key for the symbol.
  39         It is useful to sort a list of symbols in a consistent order, as comparison functions are overridden (see the documentation of class :class:`LinExpr`).
  40
  41         >>> sort(symbols, key=Symbol.sortkey)
  42
  43
  44 .. function:: symbols(names)
  45
  46     This function returns a tuple of symbols whose names are taken from a comma or whitespace delimited string, or a sequence of strings.
  47     It is useful to define several symbols at once.
  48
  49     >>> x, y = symbols('x y')
  50     >>> x, y = symbols('x, y')
  51     >>> x, y = symbols(['x', 'y'])
  52
  53
  54 Sometimes you need to have a unique symbol. For example, you might need a temporary one in some calculation, which is going to be substituted for something else at the end anyway.
  55 This is achieved using ``Dummy('x')``.
  56
  57 .. class:: Dummy(name=None)
  58
  59     A variation of :class:`Symbol` in which all symbols are unique and identified by an internal count index.
  60     If a name is not supplied then a string value of the count index will be used.
  61     This is useful when a unique, temporary variable is needed and the name of the variable used in the expression is not important.
  62
  63     Unlike :class:`Symbol`, :class:`Dummy` instances with the same name are not equal:
  64
  65     >>> x = Symbol('x')
  66     >>> x1, x2 = Dummy('x'), Dummy('x')
  67     >>> x == x1
  68     False
  69     >>> x1 == x2
  70     False
  71     >>> x1 == x1
  72     True
  73
  74
  75 .. _reference_linexprs:
  76
  77 Linear Expressions
  78 ------------------
  79
  80 A *linear expression* consists of a list of coefficient-variable pairs that capture the linear terms, plus a constant term.
  81 Linear expressions are used to build constraints. They are temporary objects that typically have short lifespans.
  82
  83 Linear expressions are generally built using overloaded operators.
  84 For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :class:`LinExpr`.
  85
  86 .. class:: LinExpr(coefficients=None, constant=0)
  87            LinExpr(string)
  88
  89     Return a linear expression from a dictionary or a sequence, that maps symbols to their coefficients, and a constant term.
  90     The coefficients and the constant term must be rational numbers.
  91
  92     For example, the linear expression ``x + 2*y + 1`` can be constructed using one of the following instructions:
  93
  94     >>> x, y = symbols('x y')
  95     >>> LinExpr({x: 1, y: 2}, 1)
  96     >>> LinExpr([(x, 1), (y, 2)], 1)
  97
  98     However, it may be easier to use overloaded operators:
  99
 100     >>> x, y = symbols('x y')
 101     >>> x + 2*y + 1
 102
 103     Alternatively, linear expressions can be constructed from a string:
 104
 105     >>> LinExpr('x + 2y + 1')
 106
 107     :class:`LinExpr` instances are hashable, and should be treated as immutable.
 108
 109     A linear expression with a single symbol of coefficient 1 and no constant term is automatically subclassed as a :class:`Symbol` instance.
 110     A linear expression with no symbol, only a constant term, is automatically subclassed as a :class:`Rational` instance.
 111
 112     .. method:: coefficient(symbol)
 113                 __getitem__(symbol)
 114
 115         Return the coefficient value of the given symbol, or ``0`` if the symbol does not appear in the expression.
 116
 117     .. method:: coefficients()
 118
 119         Iterate over the pairs ``(symbol, value)`` of linear terms in the expression.
 120         The constant term is ignored.
 121
 122     .. attribute:: constant
 123
 124         The constant term of the expression.
 125
 126     .. attribute:: symbols
 127
 128         The tuple of symbols present in the expression, sorted according to :meth:`Symbol.sortkey`.
 129
 130     .. attribute:: dimension
 131
 132         The dimension of the expression, i.e. the number of symbols present in it.
 133
 134     .. method:: isconstant()
 135
 136         Return ``True`` if the expression only consists of a constant term.
 137         In this case, it is a :class:`Rational` instance.
 138
 139     .. method:: issymbol()
 140
 141         Return ``True`` if an expression only consists of a symbol with coefficient ``1``.
 142         In this case, it is a :class:`Symbol` instance.
 143
 144     .. method:: values()
 145
 146         Iterate over the coefficient values in the expression, and the constant term.
 147
 148     .. method:: __add__(expr)
 149
 150         Return the sum of two linear expressions.
 151
 152     .. method:: __sub__(expr)
 153
 154         Return the difference between two linear expressions.
 155
 156     .. method:: __mul__(value)
 157
 158         Return the product of the linear expression by a rational.
 159
 160     .. method:: __truediv__(value)
 161
 162         Return the quotient of the linear expression by a rational.
 163
 164     .. method:: __eq__(expr)
 165
 166         Test whether two linear expressions are equal.
 167         Unlike methods :meth:`LinExpr.__lt__`, :meth:`LinExpr.__le__`, :meth:`LinExpr.__ge__`, :meth:`LinExpr.__gt__`, the result is a boolean value, not a polyhedron.
 168         To express that two linear expressions are equal or not equal, use functions :func:`Eq` and :func:`Ne` instead.
 169
 170     As explained below, it is possible to create polyhedra from linear expressions using comparison methods.
 171
 172     .. method:: __lt__(expr)
 173                 __le__(expr)
 174                 __ge__(expr)
 175                 __gt__(expr)
 176
 177         Create a new :class:`Polyhedron` instance whose unique constraint is the comparison between two linear expressions.
 178         As an alternative, functions :func:`Lt`, :func:`Le`, :func:`Ge` and :func:`Gt` can be used.
 179
 180         >>> x, y = symbols('x y')
 181         >>> x < y
 182         x + 1 <= y
 183
 184     .. method:: scaleint()
 185
 186         Return the expression multiplied by its lowest common denominator to make all values integer.
 187
 188     .. method:: subs(symbol, expression)
 189                 subs(pairs)
 190
 191         Substitute the given symbol by an expression and return the resulting expression.
 192         Raise :exc:`TypeError` if the resulting expression is not linear.
 193
 194         >>> x, y = symbols('x y')
 195         >>> e = x + 2*y + 1
 196         >>> e.subs(y, x - 1)
 197         3*x - 1
 198
 199         To perform multiple substitutions at once, pass a sequence or a dictionary of ``(old, new)`` pairs to ``subs``.
 200
 201         >>> e.subs({x: y, y: x})
 202         2*x + y + 1
 203
 204     .. classmethod:: fromstring(string)
 205
 206         Create an expression from a string.
 207         Raise :exc:`SyntaxError` if the string is not properly formatted.
 208
 209     There are also methods to convert linear expressions to and from `SymPy <http://sympy.org>`_ expressions:
 210
 211     .. classmethod:: fromsympy(expr)
 212
 213         Create a linear expression from a :mod:`sympy` expression.
 214         Raise :exc:`TypeError` is the :mod:`sympy` expression is not linear.
 215
 216     .. method:: tosympy()
 217
 218         Convert the linear expression to a sympy expression.
 219
 220
 221 Apart from :mod:`Symbol`, a particular case of linear expressions are rational values, i.e. linear expressions consisting only of a constant term, with no symbol.
 222 They are implemented by the :class:`Rational` class, that inherits from both :class:`LinExpr` and :class:`fractions.Fraction` classes.
 223
 224 .. class:: Rational(numerator, denominator=1)
 225            Rational(string)
 226
 227     The first version requires that the *numerator* and *denominator* are instances of :class:`numbers.Rational` and returns a new :class:`Rational` instance with the value ``numerator/denominator``.
 228     If the denominator is ``0``, it raises a :exc:`ZeroDivisionError`.
 229     The other version of the constructor expects a string.
 230     The usual form for this instance is::
 231
 232         [sign] numerator ['/' denominator]
 233
 234     where the optional ``sign`` may be either '+' or '-' and the ``numerator`` and ``denominator`` (if present) are strings of decimal digits.
 235
 236     See the documentation of :class:`fractions.Fraction` for more information and examples.
 237
 238
 239 .. _reference_polyhedra:
 240
 241 Polyhedra
 242 ---------
 243
 244 A *convex polyhedron* (or simply "polyhedron") is the space defined by a system of linear equalities and inequalities.
 245 This space can be unbounded.
 246
 247 .. class:: Polyhedron(equalities, inequalities)
 248            Polyhedron(string)
 249            Polyhedron(geometric object)
 250
 251     Return a polyhedron from two sequences of linear expressions: *equalities* is a list of expressions equal to ``0``, and *inequalities* is a list of expressions greater or equal to ``0``.
 252     For example, the polyhedron ``0 <= x <= 2, 0 <= y <= 2`` can be constructed with:
 253
 254     >>> x, y = symbols('x y')
 255     >>> square1 = Polyhedron([], [x, 2 - x, y, 2 - y])
 256     >>> square1
 257     And(0 <= x, x <= 2, 0 <= y, y <= 2)
 258
 259     It may be easier to use comparison operators :meth:`LinExpr.__lt__`, :meth:`LinExpr.__le__`, :meth:`LinExpr.__ge__`, :meth:`LinExpr.__gt__`, or functions :func:`Lt`, :func:`Le`, :func:`Eq`, :func:`Ge` and :func:`Gt`, using one of the following instructions:
 260
 261     >>> x, y = symbols('x y')
 262     >>> square1 = (0 <= x) & (x <= 2) & (0 <= y) & (y <= 2)
 263     >>> square1 = Le(0, x, 2) & Le(0, y, 2)
 264
 265     It is also possible to build a polyhedron from a string.
 266
 267     >>> square1 = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
 268
 269     Finally, a polyhedron can be constructed from a :class:`GeometricObject` instance, calling the :meth:`GeometricObject.aspolyedron` method.
 270     This way, it is possible to compute the polyhedral hull of a :class:`Domain` instance, i.e., the convex hull of two polyhedra:
 271
 272     >>> square1 = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
 273     >>> square2 = Polyhedron('1 <= x <= 3, 1 <= y <= 3')
 274     >>> Polyhedron(square1 | square2)
 275     And(0 <= x, 0 <= y, x <= y + 2, y <= x + 2, x <= 3, y <= 3)
 276
 277     A polyhedron is a :class:`Domain` instance, and, therefore, inherits the functionalities of this class.
 278     It is also a :class:`GeometricObject` instance.
 279
 280     .. attribute:: equalities
 281
 282         The tuple of equalities.
 283         This is a list of :class:`LinExpr` instances that are equal to ``0`` in the polyhedron.
 284
 285     .. attribute:: inequalities
 286
 287         The tuple of inequalities.
 288         This is a list of :class:`LinExpr` instances that are greater or equal to ``0`` in the polyhedron.
 289
 290     .. attribute:: constraints
 291
 292         The tuple of constraints, i.e., equalities and inequalities.
 293         This is semantically equivalent to: ``equalities + inequalities``.
 294
 295     .. method:: convex_union(polyhedron[, ...])
 296
 297         Return the convex union of two or more polyhedra.
 298
 299     .. method:: asinequalities()
 300
 301         Express the polyhedron using inequalities, given as a list of expressions greater or equal to 0.
 302
 303     .. method:: widen(polyhedron)
 304
 305         Compute the *standard widening* of two polyhedra, à la Halbwachs.
 306
 307         In its current implementation, this method is slow and should not be used on large polyhedra.
 308
 309
 310 .. data:: Empty
 311
 312     The empty polyhedron, whose set of constraints is not satisfiable.
 313
 314 .. data:: Universe
 315
 316     The universe polyhedron, whose set of constraints is always satisfiable, i.e. is empty.
 317
 318
 319 .. _reference_domains:
 320
 321 Domains
 322 -------
 323
 324 A *domain* is a union of polyhedra.
 325 Unlike polyhedra, domains allow exact computation of union, subtraction and complementary operations.
 326
 327 .. class:: Domain(*polyhedra)
 328            Domain(string)
 329            Domain(geometric object)
 330
 331     Return a domain from a sequence of polyhedra.
 332
 333     >>> square1 = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
 334     >>> square2 = Polyhedron('1 <= x <= 3, 1 <= y <= 3')
 335     >>> dom = Domain(square1, square2)
 336     >>> dom
 337     Or(And(x <= 2, 0 <= x, y <= 2, 0 <= y), And(x <= 3, 1 <= x, y <= 3, 1 <= y))
 338
 339     It is also possible to build domains from polyhedra using arithmetic operators :meth:`Domain.__or__`, :meth:`Domain.__invert__` or functions :func:`Or` and :func:`Not`, using one of the following instructions:
 340
 341     >>> dom = square1 | square2
 342     >>> dom = Or(square1, square2)
 343
 344     Alternatively, a domain can be built from a string:
 345
 346     >>> dom = Domain('0 <= x <= 2, 0 <= y <= 2; 1 <= x <= 3, 1 <= y <= 3')
 347
 348     Finally, a domain can be built from a :class:`GeometricObject` instance, calling the :meth:`GeometricObject.asdomain` method.
 349
 350     A domain is also a :class:`GeometricObject` instance.
 351     A domain with a unique polyhedron is automatically subclassed as a :class:`Polyhedron` instance.
 352
 353     .. attribute:: polyhedra
 354
 355         The tuple of polyhedra present in the domain.
 356
 357     .. attribute:: symbols
 358
 359         The tuple of symbols present in the domain equations, sorted according to :meth:`Symbol.sortkey`.
 360
 361     .. attribute:: dimension
 362
 363         The dimension of the domain, i.e. the number of symbols present in it.
 364
 365     .. method:: isempty()
 366
 367         Return ``True`` if the domain is empty, that is, equal to :data:`Empty`.
 368
 369     .. method:: __bool__()
 370
 371         Return ``True`` if the domain is non-empty.
 372
 373     .. method:: isuniverse()
 374
 375         Return ``True`` if the domain is universal, that is, equal to :data:`Universe`.
 376
 377     .. method:: isbounded()
 378
 379         Return ``True`` is the domain is bounded.
 380
 381     .. method:: __eq__(domain)
 382
 383         Return ``True`` if two domains are equal.
 384
 385     .. method:: isdisjoint(domain)
 386
 387         Return ``True`` if two domains have a null intersection.
 388
 389     .. method:: issubset(domain)
 390                 __le__(domain)
 391
 392         Report whether another domain contains the domain.
 393
 394     .. method:: __lt__(domain)
 395
 396         Report whether another domain is contained within the domain.
 397
 398     .. method:: complement()
 399                 __invert__()
 400
 401         Return the complementary domain of the domain.
 402
 403     .. method:: make_disjoint()
 404
 405         Return an equivalent domain, whose polyhedra are disjoint.
 406
 407     .. method:: coalesce()
 408
 409         Simplify the representation of the domain by trying to combine pairs of polyhedra into a single polyhedron, and return the resulting domain.
 410
 411     .. method:: detect_equalities()
 412
 413         Simplify the representation of the domain by detecting implicit equalities, and return the resulting domain.
 414
 415     .. method:: remove_redundancies()
 416
 417         Remove redundant constraints in the domain, and return the resulting domain.
 418
 419     .. method:: project(symbols)
 420
 421         Project out the sequence of symbols given in arguments, and return the resulting domain.
 422
 423     .. method:: sample()
 424
 425         Return a sample of the domain, as an integer instance of :class:`Point`.
 426         If the domain is empty, a :exc:`ValueError` exception is raised.
 427
 428     .. method:: intersection(domain[, ...])
 429                 __and__(domain)
 430
 431         Return the intersection of two or more domains as a new domain.
 432         As an alternative, function :func:`And` can be used.
 433
 434     .. method:: union(domain[, ...])
 435                 __or__(domain)
 436                 __add__(domain)
 437
 438         Return the union of two or more domains as a new domain.
 439         As an alternative, function :func:`Or` can be used.
 440
 441     .. method:: difference(domain)
 442                 __sub__(domain)
 443
 444         Return the difference between two domains as a new domain.
 445
 446     .. method:: lexmin()
 447
 448         Return the lexicographic minimum of the elements in the domain.
 449
 450     .. method:: lexmax()
 451
 452         Return the lexicographic maximum of the elements in the domain.
 453
 454     .. method:: vertices()
 455
 456         Return the vertices of the domain, as a list of rational instances of :class:`Point`.
 457
 458     .. method:: points()
 459
 460         Return the integer points of a bounded domain, as a list of integer instances of :class:`Point`.
 461         If the domain is not bounded, a :exc:`ValueError` exception is raised.
 462
 463     .. method:: __contains__(point)
 464
 465         Return ``True`` if the point is contained within the domain.
 466
 467     .. method:: faces()
 468
 469         Return the list of faces of a bounded domain.
 470         Each face is represented by a list of vertices, in the form of rational instances of :class:`Point`.
 471         If the domain is not bounded, a :exc:`ValueError` exception is raised.
 472
 473     .. method:: plot(plot=None, **options)
 474
 475         Plot a 2D or 3D domain using `matplotlib <http://matplotlib.org/>`_.
 476         Draw it to the current *plot* object if present, otherwise create a new one.
 477         *options* are keyword arguments passed to the matplotlib drawing functions, they can be used to set the drawing color for example.
 478         Raise :exc:`ValueError` is the domain is not 2D or 3D.
 479
 480     .. method:: subs(symbol, expression)
 481                 subs(pairs)
 482
 483         Substitute the given symbol by an expression in the domain constraints.
 484         To perform multiple substitutions at once, pass a sequence or a dictionary of ``(old, new)`` pairs to ``subs``.
 485         The syntax of this function is similar to :func:`LinExpr.subs`.
 486
 487     .. classmethod:: fromstring(string)
 488
 489         Create a domain from a string.
 490         Raise :exc:`SyntaxError` if the string is not properly formatted.
 491
 492     There are also methods to convert a domain to and from `SymPy <http://sympy.org>`_ expressions:
 493
 494     .. classmethod:: fromsympy(expr)
 495
 496         Create a domain from a sympy expression.
 497
 498     .. method:: tosympy()
 499
 500         Convert the domain to a sympy expression.
 501
 502
 503 .. _reference_operators:
 504
 505 Comparison and Logic Operators
 506 ------------------------------
 507
 508 The following functions create :class:`Polyhedron` or :class:`Domain` instances using the comparisons of two or more :class:`LinExpr` instances:
 509
 510 .. function:: Lt(expr1, expr2[, expr3, ...])
 511
 512     Create the polyhedron with constraints ``expr1 < expr2 < expr3 ...``.
 513
 514 .. function:: Le(expr1, expr2[, expr3, ...])
 515
 516     Create the polyhedron with constraints ``expr1 <= expr2 <= expr3 ...``.
 517
 518 .. function:: Eq(expr1, expr2[, expr3, ...])
 519
 520     Create the polyhedron with constraints ``expr1 == expr2 == expr3 ...``.
 521
 522 .. function:: Ne(expr1, expr2[, expr3, ...])
 523
 524     Create the domain such that ``expr1 != expr2 != expr3 ...``.
 525     The result is a :class:`Domain` object, not a :class:`Polyhedron`.
 526
 527 .. function:: Ge(expr1, expr2[, expr3, ...])
 528
 529     Create the polyhedron with constraints ``expr1 >= expr2 >= expr3 ...``.
 530
 531 .. function:: Gt(expr1, expr2[, expr3, ...])
 532
 533     Create the polyhedron with constraints ``expr1 > expr2 > expr3 ...``.
 534
 535 The following functions combine :class:`Polyhedron` or :class:`Domain` instances using logic operators:
 536
 537 .. function:: And(domain1, domain2[, ...])
 538
 539     Create the intersection domain of the domains given in arguments.
 540
 541 .. function:: Or(domain1, domain2[, ...])
 542
 543     Create the union domain of the domains given in arguments.
 544
 545 .. function:: Not(domain)
 546
 547     Create the complementary domain of the domain given in argument.
 548
 549
 550 .. _reference_geometry:
 551
 552 Geometric Objects
 553 -----------------
 554
 555 .. class:: GeometricObject
 556
 557     :class:`GeometricObject` is an abstract class to represent objects with a geometric representation in space.
 558     Subclasses of :class:`GeometricObject` are :class:`Polyhedron`, :class:`Domain` and :class:`Point`.
 559     The following elements must be provided:
 560
 561     .. attribute:: symbols
 562
 563         The tuple of symbols present in the object expression, sorted according to :class:`Symbol.sortkey()`.
 564
 565     .. attribute:: dimension
 566
 567         The dimension of the object, i.e. the number of symbols present in it.
 568
 569     .. method:: aspolyedron()
 570
 571         Return a :class:`Polyhedron` object that approximates the geometric object.
 572
 573     .. method:: asdomain()
 574
 575         Return a :class:`Domain` object that approximates the geometric object.
 576
 577 .. class:: Point(coordinates)
 578
 579     Create a point from a dictionary or a sequence that maps the symbols to their coordinates.
 580     Coordinates must be rational numbers.
 581
 582     For example, the point ``(x: 1, y: 2)`` can be constructed using one of the following instructions:
 583
 584     >>> x, y = symbols('x y')
 585     >>> p = Point({x: 1, y: 2})
 586     >>> p = Point([(x, 1), (y, 2)])
 587
 588     :class:`Point` instances are hashable and should be treated as immutable.
 589
 590     A point is a :class:`GeometricObject` instance.
 591
 592     .. attribute:: symbols
 593
 594         The tuple of symbols present in the point, sorted according to :class:`Symbol.sortkey()`.
 595
 596     .. attribute:: dimension
 597
 598         The dimension of the point, i.e. the number of symbols present in it.
 599
 600     .. method:: coordinate(symbol)
 601                 __getitem__(symbol)
 602
 603         Return the coordinate value of the given symbol.
 604         Raise :exc:`KeyError` if the symbol is not involved in the point.
 605
 606     .. method:: coordinates()
 607
 608         Iterate over the pairs ``(symbol, value)`` of coordinates in the point.
 609
 610     .. method:: values()
 611
 612         Iterate over the coordinate values in the point.
 613
 614     .. method:: isorigin()
 615
 616         Return ``True`` if all coordinates are ``0``.
 617
 618     .. method:: __bool__()
 619
 620         Return ``True`` if not all coordinates are ``0``.
 621
 622     .. method:: __add__(vector)
 623
 624         Translate the point by a :class:`Vector` object and return the resulting point.
 625
 626     .. method:: __sub__(point)
 627                 __sub__(vector)
 628
 629         The first version substracts a point from another and returns the resulting vector.
 630         The second version translates the point by the opposite vector of *vector* and returns the resulting point.
 631
 632     .. method:: __eq__(point)
 633
 634         Test whether two points are equal.
 635
 636
 637 .. class:: Vector(coordinates)
 638            Vector(point1, point2)
 639
 640     The first version creates a vector from a dictionary or a sequence that maps the symbols to their coordinates, similarly to :meth:`Point`.
 641     The second version creates a vector between two points.
 642
 643     :class:`Vector` instances are hashable and should be treated as immutable.
 644
 645     .. attribute:: symbols
 646
 647         The tuple of symbols present in the point, sorted according to :class:`Symbol.sortkey()`.
 648
 649     .. attribute:: dimension
 650
 651         The dimension of the point, i.e. the number of symbols present in it.
 652
 653     .. method:: coordinate(symbol)
 654                 __getitem__(symbol)
 655
 656         Return the coordinate value of the given symbol.
 657         Raise :exc:`KeyError` if the symbol is not involved in the point.
 658
 659     .. method:: coordinates()
 660
 661         Iterate over the pairs ``(symbol, value)`` of coordinates in the point.
 662
 663     .. method:: values()
 664
 665         Iterate over the coordinate values in the point.
 666
 667     .. method:: isnull()
 668
 669         Return ``True`` if all coordinates are ``0``.
 670
 671     .. method:: __bool__()
 672
 673         Return ``True`` if not all coordinates are ``0``.
 674
 675     .. method:: __add__(point)
 676                 __add__(vector)
 677
 678         The first version translates the point *point* to the vector and returns the resulting point.
 679         The second version adds vector *vector* to the vector and returns the resulting vector.
 680
 681     .. method:: __sub__(point)
 682                 __sub__(vector)
 683
 684         The first version substracts a point from a vector and returns the resulting point.
 685         The second version returns the difference vector between two vectors.
 686
 687     .. method:: __neg__()
 688
 689         Return the opposite vector.
 690
 691     .. method:: __mul__(value)
 692
 693         Multiply the vector by a scalar value and return the resulting vector.
 694
 695     .. method:: __truediv__(value)
 696
 697         Divide the vector by a scalar value and return the resulting vector.
 698
 699     .. method:: __eq__(vector)
 700
 701         Test whether two vectors are equal.
 702
 703     .. method:: angle(vector)
 704
 705         Retrieve the angle required to rotate the vector into the vector passed in argument.
 706         The result is an angle in radians, ranging between ``-pi`` and ``pi``.
 707
 708     .. method:: cross(vector)
 709
 710         Compute the cross product of two 3D vectors.
 711         If either one of the vectors is not three-dimensional, a :exc:`ValueError` exception is raised.
 712
 713     .. method:: dot(vector)
 714
 715         Compute the dot product of two vectors.
 716
 717     .. method:: norm()
 718
 719         Return the norm of the vector.
 720
 721     .. method:: norm2()
 722
 723         Return the squared norm of the vector.
 724
 725     .. method:: asunit()
 726
 727         Return the normalized vector, i.e. the vector of same direction but with norm 1.