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
 168     As explained below, it is possible to create polyhedra from linear expressions using comparison methods.
 169
 170     .. method:: __lt__(expr)
 171                 __le__(expr)
 172                 __ge__(expr)
 173                 __gt__(expr)
 174
 175         Create a new :class:`Polyhedron` instance whose unique constraint is the comparison between two linear expressions.
 176         As an alternative, functions :func:`Lt`, :func:`Le`, :func:`Ge` and :func:`Gt` can be used.
 177
 178         >>> x, y = symbols('x y')
 179         >>> x < y
 180         x + 1 <= y
 181
 182     .. method:: scaleint()
 183
 184         Return the expression multiplied by its lowest common denominator to make all values integer.
 185
 186     .. method:: subs(symbol, expression)
 187                 subs(pairs)
 188
 189         Substitute the given symbol by an expression and return the resulting expression.
 190         Raise :exc:`TypeError` if the resulting expression is not linear.
 191
 192         >>> x, y = symbols('x y')
 193         >>> e = x + 2*y + 1
 194         >>> e.subs(y, x - 1)
 195         3*x - 1
 196
 197         To perform multiple substitutions at once, pass a sequence or a dictionary of ``(old, new)`` pairs to ``subs``.
 198
 199         >>> e.subs({x: y, y: x})
 200         2*x + y + 1
 201
 202     .. classmethod:: fromstring(string)
 203
 204         Create an expression from a string.
 205         Raise :exc:`SyntaxError` if the string is not properly formatted.
 206
 207     There are also methods to convert linear expressions to and from `SymPy <http://sympy.org>`_ expressions:
 208
 209     .. classmethod:: fromsympy(expr)
 210
 211         Create a linear expression from a :mod:`sympy` expression.
 212         Raise :exc:`TypeError` is the :mod:`sympy` expression is not linear.
 213
 214     .. method:: tosympy()
 215
 216         Convert the linear expression to a sympy expression.
 217
 218
 219 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.
 220 They are implemented by the :class:`Rational` class, that inherits from both :class:`LinExpr` and :class:`fractions.Fraction` classes.
 221
 222 .. class:: Rational(numerator, denominator=1)
 223            Rational(string)
 224
 225     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``.
 226     If the denominator is ``0``, it raises a :exc:`ZeroDivisionError`.
 227     The other version of the constructor expects a string.
 228     The usual form for this instance is::
 229
 230         [sign] numerator ['/' denominator]
 231
 232     where the optional ``sign`` may be either '+' or '-' and the ``numerator`` and ``denominator`` (if present) are strings of decimal digits.
 233
 234     See the documentation of :class:`fractions.Fraction` for more information and examples.
 235
 236
 237 .. _reference_polyhedra:
 238
 239 Polyhedra
 240 ---------
 241
 242 A *convex polyhedron* (or simply "polyhedron") is the space defined by a system of linear equalities and inequalities.
 243 This space can be unbounded.
 244
 245 .. class:: Polyhedron(equalities, inequalities)
 246            Polyhedron(string)
 247            Polyhedron(geometric object)
 248
 249     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``.
 250     For example, the polyhedron ``0 <= x <= 2, 0 <= y <= 2`` can be constructed with:
 251
 252     >>> x, y = symbols('x y')
 253     >>> square1 = Polyhedron([], [x, 2 - x, y, 2 - y])
 254     >>> square1
 255     And(0 <= x, x <= 2, 0 <= y, y <= 2)
 256
 257     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:
 258
 259     >>> x, y = symbols('x y')
 260     >>> square1 = (0 <= x) & (x <= 2) & (0 <= y) & (y <= 2)
 261     >>> square1 = Le(0, x, 2) & Le(0, y, 2)
 262
 263     It is also possible to build a polyhedron from a string.
 264
 265     >>> square1 = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
 266
 267     Finally, a polyhedron can be constructed from a :class:`GeometricObject` instance, calling the :meth:`GeometricObject.aspolyedron` method.
 268     This way, it is possible to compute the polyhedral hull of a :class:`Domain` instance, i.e., the convex hull of two polyhedra:
 269
 270     >>> square1 = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
 271     >>> square2 = Polyhedron('1 <= x <= 3, 1 <= y <= 3')
 272     >>> Polyhedron(square1 | square2)
 273     And(0 <= x, 0 <= y, x <= y + 2, y <= x + 2, x <= 3, y <= 3)
 274
 275     A polyhedron is a :class:`Domain` instance, and, therefore, inherits the functionalities of this class.
 276     It is also a :class:`GeometricObject` instance.
 277
 278     .. attribute:: equalities
 279
 280         The tuple of equalities.
 281         This is a list of :class:`LinExpr` instances that are equal to ``0`` in the polyhedron.
 282
 283     .. attribute:: inequalities
 284
 285         The tuple of inequalities.
 286         This is a list of :class:`LinExpr` instances that are greater or equal to ``0`` in the polyhedron.
 287
 288     .. attribute:: constraints
 289
 290         The tuple of constraints, i.e., equalities and inequalities.
 291         This is semantically equivalent to: ``equalities + inequalities``.
 292
 293     .. method:: convex_union(polyhedron[, ...])
 294
 295         Return the convex union of two or more polyhedra.
 296
 297     .. method:: asinequalities()
 298
 299         Express the polyhedron using inequalities, given as a list of expressions greater or equal to 0.
 300
 301     .. method:: widen(polyhedron)
 302
 303         Compute the *standard widening* of two polyhedra, à la Halbwachs.
 304
 305         In its current implementation, this method is slow and should not be used on large polyhedra.
 306
 307
 308 .. data:: Empty
 309
 310     The empty polyhedron, whose set of constraints is not satisfiable.
 311
 312 .. data:: Universe
 313
 314     The universe polyhedron, whose set of constraints is always satisfiable, i.e. is empty.
 315
 316
 317 .. _reference_domains:
 318
 319 Domains
 320 -------
 321
 322 A *domain* is a union of polyhedra.
 323 Unlike polyhedra, domains allow exact computation of union, subtraction and complementary operations.
 324
 325 .. class:: Domain(*polyhedra)
 326            Domain(string)
 327            Domain(geometric object)
 328
 329     Return a domain from a sequence of polyhedra.
 330
 331     >>> square1 = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
 332     >>> square2 = Polyhedron('1 <= x <= 3, 1 <= y <= 3')
 333     >>> dom = Domain(square1, square2)
 334     >>> dom
 335     Or(And(x <= 2, 0 <= x, y <= 2, 0 <= y), And(x <= 3, 1 <= x, y <= 3, 1 <= y))
 336
 337     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:
 338
 339     >>> dom = square1 | square2
 340     >>> dom = Or(square1, square2)
 341
 342     Alternatively, a domain can be built from a string:
 343
 344     >>> dom = Domain('0 <= x <= 2, 0 <= y <= 2; 1 <= x <= 3, 1 <= y <= 3')
 345
 346     Finally, a domain can be built from a :class:`GeometricObject` instance, calling the :meth:`GeometricObject.asdomain` method.
 347
 348     A domain is also a :class:`GeometricObject` instance.
 349     A domain with a unique polyhedron is automatically subclassed as a :class:`Polyhedron` instance.
 350
 351     .. attribute:: polyhedra
 352
 353         The tuple of polyhedra present in the domain.
 354
 355     .. attribute:: symbols
 356
 357         The tuple of symbols present in the domain equations, sorted according to :meth:`Symbol.sortkey`.
 358
 359     .. attribute:: dimension
 360
 361         The dimension of the domain, i.e. the number of symbols present in it.
 362
 363     .. method:: isempty()
 364
 365         Return ``True`` if the domain is empty, that is, equal to :data:`Empty`.
 366
 367     .. method:: __bool__()
 368
 369         Return ``True`` if the domain is non-empty.
 370
 371     .. method:: isuniverse()
 372
 373         Return ``True`` if the domain is universal, that is, equal to :data:`Universe`.
 374
 375     .. method:: isbounded()
 376
 377         Return ``True`` is the domain is bounded.
 378
 379     .. method:: __eq__(domain)
 380
 381         Return ``True`` if two domains are equal.
 382
 383     .. method:: isdisjoint(domain)
 384
 385         Return ``True`` if two domains have a null intersection.
 386
 387     .. method:: issubset(domain)
 388                 __le__(domain)
 389
 390         Report whether another domain contains the domain.
 391
 392     .. method:: __lt__(domain)
 393
 394         Report whether another domain is contained within the domain.
 395
 396     .. method:: complement()
 397                 __invert__()
 398
 399         Return the complementary domain of the domain.
 400
 401     .. method:: make_disjoint()
 402
 403         Return an equivalent domain, whose polyhedra are disjoint.
 404
 405     .. method:: coalesce()
 406
 407         Simplify the representation of the domain by trying to combine pairs of polyhedra into a single polyhedron, and return the resulting domain.
 408
 409     .. method:: detect_equalities()
 410
 411         Simplify the representation of the domain by detecting implicit equalities, and return the resulting domain.
 412
 413     .. method:: remove_redundancies()
 414
 415         Remove redundant constraints in the domain, and return the resulting domain.
 416
 417     .. method:: project(symbols)
 418
 419         Project out the sequence of symbols given in arguments, and return the resulting domain.
 420
 421     .. method:: sample()
 422
 423         Return a sample of the domain, as an integer instance of :class:`Point`.
 424         If the domain is empty, a :exc:`ValueError` exception is raised.
 425
 426     .. method:: intersection(domain[, ...])
 427                 __and__(domain)
 428
 429         Return the intersection of two or more domains as a new domain.
 430         As an alternative, function :func:`And` can be used.
 431
 432     .. method:: union(domain[, ...])
 433                 __or__(domain)
 434                 __add__(domain)
 435
 436         Return the union of two or more domains as a new domain.
 437         As an alternative, function :func:`Or` can be used.
 438
 439     .. method:: difference(domain)
 440                 __sub__(domain)
 441
 442         Return the difference between two domains as a new domain.
 443
 444     .. method:: lexmin()
 445
 446         Return the lexicographic minimum of the elements in the domain.
 447
 448     .. method:: lexmax()
 449
 450         Return the lexicographic maximum of the elements in the domain.
 451
 452     .. method:: vertices()
 453
 454         Return the vertices of the domain, as a list of rational instances of :class:`Point`.
 455
 456     .. method:: points()
 457
 458         Return the integer points of a bounded domain, as a list of integer instances of :class:`Point`.
 459         If the domain is not bounded, a :exc:`ValueError` exception is raised.
 460
 461     .. method:: __contains__(point)
 462
 463         Return ``True`` if the point is contained within the domain.
 464
 465     .. method:: faces()
 466
 467         Return the list of faces of a bounded domain.
 468         Each face is represented by a list of vertices, in the form of rational instances of :class:`Point`.
 469         If the domain is not bounded, a :exc:`ValueError` exception is raised.
 470
 471     .. method:: plot(plot=None, **options)
 472
 473         Plot a 2D or 3D domain using `matplotlib <http://matplotlib.org/>`_.
 474         Draw it to the current *plot* object if present, otherwise create a new one.
 475         *options* are keyword arguments passed to the matplotlib drawing functions, they can be used to set the drawing color for example.
 476         Raise :exc:`ValueError` is the domain is not 2D or 3D.
 477
 478     .. method:: subs(symbol, expression)
 479                 subs(pairs)
 480
 481         Substitute the given symbol by an expression in the domain constraints.
 482         To perform multiple substitutions at once, pass a sequence or a dictionary of ``(old, new)`` pairs to ``subs``.
 483         The syntax of this function is similar to :func:`LinExpr.subs`.
 484
 485     .. classmethod:: fromstring(string)
 486
 487         Create a domain from a string.
 488         Raise :exc:`SyntaxError` if the string is not properly formatted.
 489
 490     There are also methods to convert a domain to and from `SymPy <http://sympy.org>`_ expressions:
 491
 492     .. classmethod:: fromsympy(expr)
 493
 494         Create a domain from a sympy expression.
 495
 496     .. method:: tosympy()
 497
 498         Convert the domain to a sympy expression.
 499
 500
 501 .. _reference_operators:
 502
 503 Comparison and Logic Operators
 504 ------------------------------
 505
 506 The following functions create :class:`Polyhedron` or :class:`Domain` instances using the comparisons of two or more :class:`LinExpr` instances:
 507
 508 .. function:: Lt(expr1, expr2[, expr3, ...])
 509
 510     Create the polyhedron with constraints ``expr1 < expr2 < expr3 ...``.
 511
 512 .. function:: Le(expr1, expr2[, expr3, ...])
 513
 514     Create the polyhedron with constraints ``expr1 <= expr2 <= expr3 ...``.
 515
 516 .. function:: Eq(expr1, expr2[, expr3, ...])
 517
 518     Create the polyhedron with constraints ``expr1 == expr2 == expr3 ...``.
 519
 520 .. function:: Ne(expr1, expr2[, expr3, ...])
 521
 522     Create the domain such that ``expr1 != expr2 != expr3 ...``.
 523     The result is a :class:`Domain` object, not a :class:`Polyhedron`.
 524
 525 .. function:: Ge(expr1, expr2[, expr3, ...])
 526
 527     Create the polyhedron with constraints ``expr1 >= expr2 >= expr3 ...``.
 528
 529 .. function:: Gt(expr1, expr2[, expr3, ...])
 530
 531     Create the polyhedron with constraints ``expr1 > expr2 > expr3 ...``.
 532
 533 The following functions combine :class:`Polyhedron` or :class:`Domain` instances using logic operators:
 534
 535 .. function:: And(domain1, domain2[, ...])
 536
 537     Create the intersection domain of the domains given in arguments.
 538
 539 .. function:: Or(domain1, domain2[, ...])
 540
 541     Create the union domain of the domains given in arguments.
 542
 543 .. function:: Not(domain)
 544
 545     Create the complementary domain of the domain given in argument.
 546
 547
 548 .. _reference_geometry:
 549
 550 Geometric Objects
 551 -----------------
 552
 553 .. class:: GeometricObject
 554
 555     :class:`GeometricObject` is an abstract class to represent objects with a geometric representation in space.
 556     Subclasses of :class:`GeometricObject` are :class:`Polyhedron`, :class:`Domain` and :class:`Point`.
 557     The following elements must be provided:
 558
 559     .. attribute:: symbols
 560
 561         The tuple of symbols present in the object expression, sorted according to :class:`Symbol.sortkey()`.
 562
 563     .. attribute:: dimension
 564
 565         The dimension of the object, i.e. the number of symbols present in it.
 566
 567     .. method:: aspolyedron()
 568
 569         Return a :class:`Polyhedron` object that approximates the geometric object.
 570
 571     .. method:: asdomain()
 572
 573         Return a :class:`Domain` object that approximates the geometric object.
 574
 575 .. class:: Point(coordinates)
 576
 577     Create a point from a dictionary or a sequence that maps the symbols to their coordinates.
 578     Coordinates must be rational numbers.
 579
 580     For example, the point ``(x: 1, y: 2)`` can be constructed using one of the following instructions:
 581
 582     >>> x, y = symbols('x y')
 583     >>> p = Point({x: 1, y: 2})
 584     >>> p = Point([(x, 1), (y, 2)])
 585
 586     :class:`Point` instances are hashable and should be treated as immutable.
 587
 588     A point is a :class:`GeometricObject` instance.
 589
 590     .. attribute:: symbols
 591
 592         The tuple of symbols present in the point, sorted according to :class:`Symbol.sortkey()`.
 593
 594     .. attribute:: dimension
 595
 596         The dimension of the point, i.e. the number of symbols present in it.
 597
 598     .. method:: coordinate(symbol)
 599                 __getitem__(symbol)
 600
 601         Return the coordinate value of the given symbol.
 602         Raise :exc:`KeyError` if the symbol is not involved in the point.
 603
 604     .. method:: coordinates()
 605
 606         Iterate over the pairs ``(symbol, value)`` of coordinates in the point.
 607
 608     .. method:: values()
 609
 610         Iterate over the coordinate values in the point.
 611
 612     .. method:: isorigin()
 613
 614         Return ``True`` if all coordinates are ``0``.
 615
 616     .. method:: __bool__()
 617
 618         Return ``True`` if not all coordinates are ``0``.
 619
 620     .. method:: __add__(vector)
 621
 622         Translate the point by a :class:`Vector` object and return the resulting point.
 623
 624     .. method:: __sub__(point)
 625                 __sub__(vector)
 626
 627         The first version substracts a point from another and returns the resulting vector.
 628         The second version translates the point by the opposite vector of *vector* and returns the resulting point.
 629
 630     .. method:: __eq__(point)
 631
 632         Test whether two points are equal.
 633
 634
 635 .. class:: Vector(coordinates)
 636            Vector(point1, point2)
 637
 638     The first version creates a vector from a dictionary or a sequence that maps the symbols to their coordinates, similarly to :meth:`Point`.
 639     The second version creates a vector between two points.
 640
 641     :class:`Vector` instances are hashable and should be treated as immutable.
 642
 643     .. attribute:: symbols
 644
 645         The tuple of symbols present in the point, sorted according to :class:`Symbol.sortkey()`.
 646
 647     .. attribute:: dimension
 648
 649         The dimension of the point, i.e. the number of symbols present in it.
 650
 651     .. method:: coordinate(symbol)
 652                 __getitem__(symbol)
 653
 654         Return the coordinate value of the given symbol.
 655         Raise :exc:`KeyError` if the symbol is not involved in the point.
 656
 657     .. method:: coordinates()
 658
 659         Iterate over the pairs ``(symbol, value)`` of coordinates in the point.
 660
 661     .. method:: values()
 662
 663         Iterate over the coordinate values in the point.
 664
 665     .. method:: isnull()
 666
 667         Return ``True`` if all coordinates are ``0``.
 668
 669     .. method:: __bool__()
 670
 671         Return ``True`` if not all coordinates are ``0``.
 672
 673     .. method:: __add__(point)
 674                 __add__(vector)
 675
 676         The first version translates the point *point* to the vector and returns the resulting point.
 677         The second version adds vector *vector* to the vector and returns the resulting vector.
 678
 679     .. method:: __sub__(point)
 680                 __sub__(vector)
 681
 682         The first version substracts a point from a vector and returns the resulting point.
 683         The second version returns the difference vector between two vectors.
 684
 685     .. method:: __neg__()
 686
 687         Return the opposite vector.
 688
 689     .. method:: __mul__(value)
 690
 691         Multiply the vector by a scalar value and return the resulting vector.
 692
 693     .. method:: __truediv__(value)
 694
 695         Divide the vector by a scalar value and return the resulting vector.
 696
 697     .. method:: __eq__(vector)
 698
 699         Test whether two vectors are equal.
 700
 701     .. method:: angle(vector)
 702
 703         Retrieve the angle required to rotate the vector into the vector passed in argument.
 704         The result is an angle in radians, ranging between ``-pi`` and ``pi``.
 705
 706     .. method:: cross(vector)
 707
 708         Compute the cross product of two 3D vectors.
 709         If either one of the vectors is not three-dimensional, a :exc:`ValueError` exception is raised.
 710
 711     .. method:: dot(vector)
 712
 713         Compute the dot product of two vectors.
 714
 715     .. method:: norm()
 716
 717         Return the norm of the vector.
 718
 719     .. method:: norm2()
 720
 721         Return the squared norm of the vector.
 722
 723     .. method:: asunit()
 724
 725         Return the normalized vector, i.e. the vector of same direction but with norm 1.