Update docstrings to reflect documentation changes
[linpy.git] / 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.