index 8184c43..8e36056 100644 (file)
@@ -2,6 +2,7 @@
Module Reference
================

+
Symbols
-------

@@ -12,7 +13,7 @@ They correspond to mathematical variables.

Return a symbol with the name string given in argument.
Alternatively, the function :func:`symbols` allows to create several symbols at once.
-    Symbols are instances of class :class:`LinExpr` and, as such, inherit its functionalities.
+    Symbols are instances of class :class:`LinExpr` and inherit its functionalities.

>>> x = Symbol('x')
>>> x
@@ -46,12 +47,12 @@ They correspond to mathematical variables.
>>> x, y = symbols(['x', 'y'])

-Sometimes, you need to have a unique symbol, for example as a temporary one in some calculation, which is going to be substituted for something else at the end anyway.
+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.
This is achieved using ``Dummy('x')``.

.. class:: Dummy(name=None)

-    A variation of :class:`Symbol` which are all unique, identified by an internal count index.
+    A variation of :class:`Symbol` in which all symbols are unique and identified by an internal count index.
If a name is not supplied then a string value of the count index will be used.
This is useful when a unique, temporary variable is needed and the name of the variable used in the expression is not important.

@@ -79,8 +80,8 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
.. class:: LinExpr(coefficients=None, constant=0)
LinExpr(string)

-    Return a linear expression from a dictionary or a sequence that maps symbols to their coefficients, and a constant term.
-    The coefficients and the constant must be rational numbers.
+    Return a linear expression from a dictionary or a sequence, that maps symbols to their coefficients, and a constant term.
+    The coefficients and the constant term must be rational numbers.

For example, the linear expression ``x + 2y + 1`` can be constructed using one of the following instructions:

@@ -88,7 +89,7 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
>>> LinExpr({x: 1, y: 2}, 1)
>>> LinExpr([(x, 1), (y, 2)], 1)

-    although it may be easier to use overloaded operators:
+    However, it may be easier to use overloaded operators:

>>> x, y = symbols('x y')
>>> x + 2*y + 1
@@ -103,7 +104,7 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
A linear expression with no symbol, only a constant term, is automatically subclassed as a :class:`Rational` instance.

.. method:: coefficient(symbol)
-                   __getitem__(symbol)
+                __getitem__(symbol)

Return the coefficient value of the given symbol, or ``0`` if the symbol does not appear in the expression.

@@ -161,9 +162,9 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
As explained below, it is possible to create polyhedra from linear expressions using comparison methods.

.. method:: __lt__(expr)
-                   __le__(expr)
-                   __ge__(expr)
-                   __gt__(expr)
+                __le__(expr)
+                __ge__(expr)
+                __gt__(expr)

Create a new :class:`Polyhedron` instance whose unique constraint is the comparison between two linear expressions.
As an alternative, functions :func:`Lt`, :func:`Le`, :func:`Ge` and :func:`Gt` can be used.
@@ -172,16 +173,15 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
>>> x < y
Le(x - y + 1, 0)

-
.. method:: scaleint()

Return the expression multiplied by its lowest common denominator to make all values integer.

.. method:: subs(symbol, expression)
-                   subs(pairs)
+                subs(pairs)

Substitute the given symbol by an expression and return the resulting expression.
-        Raise :exc:`TypeError` is the resulting expression is not linear.
+        Raise :exc:`TypeError` if the resulting expression is not linear.

>>> x, y = symbols('x y')
>>> e = x + 2*y + 1
@@ -203,7 +203,7 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
.. classmethod:: fromsympy(expr)

Create a linear expression from a :mod:`sympy` expression.
-        Raise :exc:`ValueError` is the :mod:`sympy` expression is not linear.
+        Raise :exc:`TypeError` is the :mod:`sympy` expression is not linear.

.. method:: tosympy()

@@ -216,21 +216,22 @@ They are implemented by the :class:`Rational` class, that inherits from both :cl
.. class:: Rational(numerator, denominator=1)
Rational(string)

-    The first version requires that *numerator* and *denominator* are instances of :class:`numbers.Rational` and returns a new :class:`Rational` instance with value ``numerator/denominator``.
-    If denominator is ``0``, it raises a :exc:`ZeroDivisionError`.
+    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``.
+    If the denominator is ``0``, it raises a :exc:`ZeroDivisionError`.
The other version of the constructor expects a string.
The usual form for this instance is::

[sign] numerator ['/' denominator]

-    where the optional ``sign`` may be either '+' or '-' and ``numerator`` and ``denominator`` (if present) are strings of decimal digits.
+    where the optional ``sign`` may be either '+' or '-' and the ``numerator`` and ``denominator`` (if present) are strings of decimal digits.

See the documentation of :class:`fractions.Fraction` for more information and examples.

+
Polyhedra
---------

-A *convex polyhedron* (or simply polyhedron) is the space defined by a system of linear equalities and inequalities.
+A *convex polyhedron* (or simply "polyhedron") is the space defined by a system of linear equalities and inequalities.
This space can be unbounded.

.. class:: Polyhedron(equalities, inequalities)
@@ -260,7 +261,7 @@ This space can be unbounded.
>>> square2 = Polyhedron('2 <= x <= 4, 2 <= y <= 4')
>>> Polyhedron(square | square2)

-    A polyhedron is a :class:`Domain` instance, and, as such, inherits the functionalities of this class.
+    A polyhedron is a :class:`Domain` instance, and, therefore, inherits the functionalities of this class.
It is also a :class:`GeometricObject` instance.

.. attribute:: equalities
@@ -278,9 +279,19 @@ This space can be unbounded.
The tuple of constraints, i.e., equalities and inequalities.
This is semantically equivalent to: ``equalities + inequalities``.

+    .. method:: convex_union(polyhedron[, ...])
+
+        Return the convex union of two or more polyhedra.
+
+    .. method:: asinequalities()
+
+        Express the polyhedron using inequalities, given as a list of expressions greater or equal to 0.
+
.. method:: widen(polyhedron)

-        Compute the standard widening of two polyhedra, à la Halbwachs.
+        Compute the *standard widening* of two polyhedra, à la Halbwachs.
+
+        In its current implementation, this method is slow and should not be used on large polyhedra.

.. data:: Empty
@@ -291,6 +302,7 @@ This space can be unbounded.

The universe polyhedron, whose set of constraints is always satisfiable, i.e. is empty.

+
Domains
-------

@@ -329,7 +341,7 @@ Unlike polyhedra, domains allow exact computation of union and complementary ope

.. attribute:: symbols

-        The tuple of symbols present in the domain expression, sorted according to :meth:`Symbol.sortkey`.
+        The tuple of symbols present in the domain equations, sorted according to :meth:`Symbol.sortkey`.

.. attribute:: dimension

@@ -435,7 +447,7 @@ Unlike polyhedra, domains allow exact computation of union and complementary ope

.. method:: __contains__(point)

-        Return ``True`` if the :class:`Point` is contained within the domain.
+        Return ``True`` if the point is contained within the domain.

.. method:: faces()

@@ -476,7 +488,7 @@ Unlike polyhedra, domains allow exact computation of union and complementary ope
Comparison and Logic Operators
------------------------------

-The following functions allow to create :class:`Polyhedron` or :class:`Domain` instances by comparison of :class:`LinExpr` instances:
+The following functions create :class:`Polyhedron` or :class:`Domain` instances using the comparisons of two or more :class:`LinExpr` instances:

.. function:: Lt(expr1, expr2[, expr3, ...])

@@ -493,7 +505,7 @@ The following functions allow to create :class:`Polyhedron` or :class:`Domain` i
.. function:: Ne(expr1, expr2[, expr3, ...])

Create the domain such that ``expr1 != expr2 != expr3 ...``.
-    The result is a :class:`Domain`, not a :class:`Polyhedron`.
+    The result is a :class:`Domain` object, not a :class:`Polyhedron`.

.. function:: Ge(expr1, expr2[, expr3, ...])

@@ -503,15 +515,15 @@ The following functions allow to create :class:`Polyhedron` or :class:`Domain` i

Create the polyhedron with constraints ``expr1 > expr2 > expr3 ...``.

-The following functions allow to combine :class:`Polyhedron` or :class:`Domain` instances using logic operators:
+The following functions combine :class:`Polyhedron` or :class:`Domain` instances using logic operators:

-.. function:: Or(domain1, domain2[, ...])
+.. function:: And(domain1, domain2[, ...])

-    Create the union domain of domains given in arguments.
+    Create the intersection domain of the domains given in arguments.

-.. function:: And(domain1, domain2[, ...])
+.. function:: Or(domain1, domain2[, ...])

-    Create the intersection domain of domains given in arguments.
+    Create the union domain of the domains given in arguments.

.. function:: Not(domain)

@@ -545,7 +557,7 @@ Geometric Objects

.. class:: Point(coordinates)

-    Create a point from a dictionnary or a sequence that maps symbols to their coordinates.
+    Create a point from a dictionary or a sequence that maps the symbols to their coordinates.
Coordinates must be rational numbers.

For example, the point ``(x: 1, y: 2)`` can be constructed using one of the following instructions:
@@ -554,7 +566,7 @@ Geometric Objects
>>> p = Point({x: 1, y: 2})
>>> p = Point([(x, 1), (y, 2)])

-    :class:`Point` instances are hashable, and should be treated as immutable.
+    :class:`Point` instances are hashable and should be treated as immutable.

A point is a :class:`GeometricObject` instance.

@@ -567,7 +579,7 @@ Geometric Objects
The dimension of the point, i.e. the number of symbols present in it.

.. method:: coordinate(symbol)
-                   __getitem__(symbol)
+                __getitem__(symbol)

Return the coordinate value of the given symbol.
Raise :exc:`KeyError` if the symbol is not involved in the point.
@@ -590,12 +602,12 @@ Geometric Objects

-        Translate the point by a :class:`Vector` instance and return the resulting point.
+        Translate the point by a :class:`Vector` object and return the resulting point.

.. method:: __sub__(point)
-                   __sub__(vector)
+                __sub__(vector)

-        The first version substract a point from another and return the resulting vector.
+        The first version substracts a point from another and returns the resulting vector.
The second version translates the point by the opposite vector of *vector* and returns the resulting point.

.. method:: __eq__(point)
@@ -604,11 +616,12 @@ Geometric Objects

.. class:: Vector(coordinates)
+           Vector(point1, point2)

-    Create a point from a dictionnary or a sequence that maps symbols to their coordinates, similarly to :meth:`Point`.
-    Coordinates must be rational numbers.
+    The first version creates a vector from a dictionary or a sequence that maps the symbols to their coordinates, similarly to :meth:`Point`.
+    The second version creates a vector between two points.

-    :class:`Vector` instances are hashable, and should be treated as immutable.
+    :class:`Vector` instances are hashable and should be treated as immutable.

.. attribute:: symbols

@@ -619,7 +632,7 @@ Geometric Objects
The dimension of the point, i.e. the number of symbols present in it.

.. method:: coordinate(symbol)
-                   __getitem__(symbol)
+                __getitem__(symbol)

Return the coordinate value of the given symbol.
Raise :exc:`KeyError` if the symbol is not involved in the point.
@@ -641,13 +654,13 @@ Geometric Objects
Return ``True`` if not all coordinates are ``0``.

The first version translates the point *point* to the vector and returns the resulting point.
The second version adds vector *vector* to the vector and returns the resulting vector.

.. method:: __sub__(point)
-                   __sub__(vector)
+                __sub__(vector)

The first version substracts a point from a vector and returns the resulting point.
The second version returns the difference vector between two vectors.
@@ -656,6 +669,18 @@ Geometric Objects

Return the opposite vector.

+    .. method:: __mul__(value)
+
+        Multiply the vector by a scalar value and return the resulting vector.
+
+    .. method:: __truediv__(value)
+
+        Divide the vector by a scalar value and return the resulting vector.
+
+    .. method:: __eq__(vector)
+
+        Test whether two vectors are equal.
+
.. method:: angle(vector)

Retrieve the angle required to rotate the vector into the vector passed in argument.
@@ -664,31 +689,19 @@ Geometric Objects
.. method:: cross(vector)

Compute the cross product of two 3D vectors.
-        If either one of the vectors is not tridimensional, a :exc:`ValueError` exception is raised.
+        If either one of the vectors is not three-dimensional, a :exc:`ValueError` exception is raised.

.. method:: dot(vector)

Compute the dot product of two vectors.

-    .. method:: __eq__(vector)
-
-        Test whether two vectors are equal.
-
-    .. method:: __mul__(value)
-
-        Multiply the vector by a scalar value and return the resulting vector.
-
-    .. method:: __truediv__(value)
-
-        Divide the vector by a scalar value and return the resulting vector.
-
.. method:: norm()

Return the norm of the vector.

.. method:: norm2()

-        Return the square norm of the vector.
+        Return the squared norm of the vector.

.. method:: asunit()