Update documentation to match __repr__() changes

[linpy.git] / doc / reference.rst

diff --git a/doc/reference.rst b/doc/reference.rst
index e0efdde..e6f291d 100644 (file)
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -1,7 +1,12 @@
 
 

+.. _reference:
+

 Module Reference
 ================
 
 Module Reference
 ================
 

+
+.. _reference_symbols:
+

 Symbols
 -------
 
 Symbols
 -------
 


@@ -67,6 +72,8 @@ This is achieved using ``Dummy('x')``.
     True
 
 
     True
 
 

+.. _reference_linexprs:
+

 Linear Expressions
 ------------------
 
 Linear Expressions
 ------------------
 


@@ -77,12 +84,12 @@ Linear expressions are generally built using overloaded operators.
 For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :class:`LinExpr`.
 
 .. class:: LinExpr(coefficients=None, constant=0)
 For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :class:`LinExpr`.
 
 .. class:: LinExpr(coefficients=None, constant=0)

-              LinExpr(string)
+           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 term 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:
+    For example, the linear expression ``x + 2*y + 1`` can be constructed using one of the following instructions:

 
     >>> x, y = symbols('x y')
     >>> LinExpr({x: 1, y: 2}, 1)
 
     >>> x, y = symbols('x y')
     >>> LinExpr({x: 1, y: 2}, 1)


@@ -95,7 +102,7 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
 
     Alternatively, linear expressions can be constructed from a string:
 
 
     Alternatively, linear expressions can be constructed from a string:
 

-    >>> LinExpr('x + 2*y + 1')
+    >>> LinExpr('x + 2y + 1')

 
     :class:`LinExpr` instances are hashable, and should be treated as immutable.
 
 
     :class:`LinExpr` instances are hashable, and should be treated as immutable.
 


@@ -170,8 +177,7 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
 
         >>> x, y = symbols('x y')
         >>> x < y
 
         >>> x, y = symbols('x y')
         >>> x < y

-        Le(x - y + 1, 0)
-
+        x + 1 <= y

 
     .. method:: scaleint()
 
 
     .. method:: scaleint()
 


@@ -203,7 +209,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.
     .. 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()
 
 
     .. method:: tosympy()
 


@@ -214,7 +220,7 @@ Apart from :mod:`Symbol`, a particular case of linear expressions are rational v
 They are implemented by the :class:`Rational` class, that inherits from both :class:`LinExpr` and :class:`fractions.Fraction` classes.
 
 .. class:: Rational(numerator, denominator=1)
 They are implemented by the :class:`Rational` class, that inherits from both :class:`LinExpr` and :class:`fractions.Fraction` classes.
 
 .. class:: Rational(numerator, denominator=1)

-              Rational(string)
+           Rational(string)

 
     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 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`.


@@ -227,6 +233,9 @@ They are implemented by the :class:`Rational` class, that inherits from both :cl
 
     See the documentation of :class:`fractions.Fraction` for more information and examples.
 
 
     See the documentation of :class:`fractions.Fraction` for more information and examples.
 

+
+.. _reference_polyhedra:
+

 Polyhedra
 ---------
 
 Polyhedra
 ---------
 


@@ -234,14 +243,16 @@ A *convex polyhedron* (or simply "polyhedron") is the space defined by a system
 This space can be unbounded.
 
 .. class:: Polyhedron(equalities, inequalities)
 This space can be unbounded.
 
 .. class:: Polyhedron(equalities, inequalities)

-              Polyhedron(string)
-              Polyhedron(geometric object)
+           Polyhedron(string)
+           Polyhedron(geometric object)

 
     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``.
     For example, the polyhedron ``0 <= x <= 2, 0 <= y <= 2`` can be constructed with:
 
     >>> x, y = symbols('x y')
     >>> square = Polyhedron([], [x, 2 - x, y, 2 - y])
 
     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``.
     For example, the polyhedron ``0 <= x <= 2, 0 <= y <= 2`` can be constructed with:
 
     >>> x, y = symbols('x y')
     >>> square = Polyhedron([], [x, 2 - x, y, 2 - y])

+    >>> square
+    And(0 <= x, x <= 2, 0 <= y, y <= 2)

 
     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:
 
 
     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:
 


@@ -259,6 +270,7 @@ This space can be unbounded.
     >>> square = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
     >>> square2 = Polyhedron('2 <= x <= 4, 2 <= y <= 4')
     >>> Polyhedron(square | square2)
     >>> square = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
     >>> square2 = Polyhedron('2 <= x <= 4, 2 <= y <= 4')
     >>> Polyhedron(square | square2)

+    And(x <= 4, 0 <= x, y <= 4, 0 <= y, x <= y + 2, y <= x + 2)

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


@@ -278,10 +290,20 @@ This space can be unbounded.
         The tuple of constraints, i.e., equalities and inequalities.
         This is semantically equivalent to: ``equalities + inequalities``.
 
         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.
 
     .. method:: widen(polyhedron)
 
         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
 
 
 .. data:: Empty
 


@@ -291,21 +313,26 @@ This space can be unbounded.
 
     The universe polyhedron, whose set of constraints is always satisfiable, i.e. is empty.
 
 
     The universe polyhedron, whose set of constraints is always satisfiable, i.e. is empty.
 

+
+.. _reference_domains:
+

 Domains
 -------
 
 A *domain* is a union of polyhedra.
 Domains
 -------
 
 A *domain* is a union of polyhedra.

-Unlike polyhedra, domains allow exact computation of union and complementary operations.
+Unlike polyhedra, domains allow exact computation of union, subtraction and complementary operations.

 
 .. class:: Domain(*polyhedra)
 
 .. class:: Domain(*polyhedra)

-              Domain(string)
-              Domain(geometric object)
+           Domain(string)
+           Domain(geometric object)

 
     Return a domain from a sequence of polyhedra.
 
     >>> square = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
     >>> square2 = Polyhedron('2 <= x <= 4, 2 <= y <= 4')
 
     Return a domain from a sequence of polyhedra.
 
     >>> square = Polyhedron('0 <= x <= 2, 0 <= y <= 2')
     >>> square2 = Polyhedron('2 <= x <= 4, 2 <= y <= 4')

-    >>> dom = Domain([square, square2])
+    >>> dom = Domain(square, square2)
+    >>> dom
+    Or(And(x <= 2, 0 <= x, y <= 2, 0 <= y), And(x <= 4, 2 <= x, y <= 4, 2 <= y))

 
     It is also possible to build domains from polyhedra using arithmetic operators :meth:`Domain.__and__`, :meth:`Domain.__or__` or functions :func:`And` and :func:`Or`, using one of the following instructions:
 
 
     It is also possible to build domains from polyhedra using arithmetic operators :meth:`Domain.__and__`, :meth:`Domain.__or__` or functions :func:`And` and :func:`Or`, using one of the following instructions:
 


@@ -473,6 +500,8 @@ Unlike polyhedra, domains allow exact computation of union and complementary ope
         Convert the domain to a sympy expression.
 
 
         Convert the domain to a sympy expression.
 
 

+.. _reference_operators:
+

 Comparison and Logic Operators
 ------------------------------
 
 Comparison and Logic Operators
 ------------------------------
 


@@ -493,7 +522,7 @@ The following functions create :class:`Polyhedron` or :class:`Domain` instances
 .. function:: Ne(expr1, expr2[, expr3, ...])
 
     Create the domain such that ``expr1 != expr2 != expr3 ...``.
 .. 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, ...])
 
 
 .. function:: Ge(expr1, expr2[, expr3, ...])
 


@@ -505,19 +534,21 @@ The following functions create :class:`Polyhedron` or :class:`Domain` instances
 
 The following functions 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[, ...])
-
-    Create the union domain of the domains given in arguments.
-

 .. function:: And(domain1, domain2[, ...])
 
     Create the intersection domain of the domains given in arguments.
 
 .. function:: And(domain1, domain2[, ...])
 
     Create the intersection domain of the domains given in arguments.
 

+.. function:: Or(domain1, domain2[, ...])
+
+    Create the union domain of the domains given in arguments.
+

 .. function:: Not(domain)
 
     Create the complementary domain of the domain given in argument.
 
 
 .. function:: Not(domain)
 
     Create the complementary domain of the domain given in argument.
 
 

+.. _reference_geometry:
+

 Geometric Objects
 -----------------
 
 Geometric Objects
 -----------------
 


@@ -677,7 +708,7 @@ Geometric Objects
     .. method:: cross(vector)
 
         Compute the cross product of two 3D vectors.
     .. 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)
 
 
     .. method:: dot(vector)