Reformat examples

[linpy.git] / doc / reference.rst

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

+.. _reference:
+

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

+
+.. _reference_symbols:
+

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


@@ -12,7 +17,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.
 
     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
 
     >>> x = Symbol('x')
     >>> x


@@ -46,12 +51,12 @@ They correspond to mathematical variables.
     >>> x, y = symbols(['x', 'y'])
 
 
     >>> 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)
 
 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.
 
     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.
 


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

+.. _reference_linexprs:
+

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


@@ -79,8 +86,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)
 
 .. 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:
 
 
     For example, the linear expression ``x + 2y + 1`` can be constructed using one of the following instructions:
 


@@ -88,7 +95,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)
 
     >>> 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
 
     >>> x, y = symbols('x y')
     >>> x + 2*y + 1


@@ -103,7 +110,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)
     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.
 
 
         Return the coefficient value of the given symbol, or ``0`` if the symbol does not appear in the expression.
 


@@ -161,9 +168,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)
     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.
 
         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 +179,15 @@ For example, if ``x`` is a :class:`Symbol`, then ``x + 1`` is an instance of :cl
         >>> x < y
         Le(x - y + 1, 0)
 
         >>> 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)
     .. 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.
 
         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
 
         >>> x, y = symbols('x y')
         >>> e = x + 2*y + 1


@@ -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()
 


@@ -216,21 +222,24 @@ They are implemented by the :class:`Rational` class, that inherits from both :cl
 .. class:: Rational(numerator, denominator=1)
               Rational(string)
 
 .. 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]
 
     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.
 
 
     See the documentation of :class:`fractions.Fraction` for more information and examples.
 

+
+.. _reference_polyhedra:
+

 Polyhedra
 ---------
 
 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)
 This space can be unbounded.
 
 .. class:: Polyhedron(equalities, inequalities)


@@ -260,7 +269,7 @@ This space can be unbounded.
     >>> square2 = Polyhedron('2 <= x <= 4, 2 <= y <= 4')
     >>> Polyhedron(square | square2)
 
     >>> 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
     It is also a :class:`GeometricObject` instance.
 
     .. attribute:: equalities


@@ -278,9 +287,19 @@ 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)
 
     .. 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
 
 
 .. data:: Empty


@@ -291,11 +310,14 @@ 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)
               Domain(string)
 
 .. class:: Domain(*polyhedra)
               Domain(string)


@@ -329,7 +351,7 @@ Unlike polyhedra, domains allow exact computation of union and complementary ope
 
     .. attribute:: symbols
 
 
     .. 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
 
 
     .. attribute:: dimension
 


@@ -435,7 +457,7 @@ Unlike polyhedra, domains allow exact computation of union and complementary ope
 
     .. method:: __contains__(point)
 
 
     .. 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()
 
 
     .. method:: faces()
 


@@ -473,10 +495,12 @@ 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
 ------------------------------
 

-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, ...])
 
 
 .. function:: Lt(expr1, expr2[, expr3, ...])
 


@@ -493,7 +517,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 ...``.
 .. 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, ...])
 


@@ -503,21 +527,23 @@ The following functions allow to create :class:`Polyhedron` or :class:`Domain` i
 
     Create the polyhedron with constraints ``expr1 > expr2 > expr3 ...``.
 
 
     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)
 
     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
 -----------------
 


@@ -545,7 +571,7 @@ Geometric Objects
 
 .. class:: Point(coordinates)
 
 
 .. 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:
     Coordinates must be rational numbers.
 
     For example, the point ``(x: 1, y: 2)`` can be constructed using one of the following instructions:


@@ -554,7 +580,7 @@ Geometric Objects
     >>> p = Point({x: 1, y: 2})
     >>> p = Point([(x, 1), (y, 2)])
 
     >>> 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.
 
 
     A point is a :class:`GeometricObject` instance.
 


@@ -567,7 +593,7 @@ Geometric Objects
         The dimension of the point, i.e. the number of symbols present in it.
 
     .. method:: coordinate(symbol)
         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.
 
         Return the coordinate value of the given symbol.
         Raise :exc:`KeyError` if the symbol is not involved in the point.


@@ -590,12 +616,12 @@ Geometric Objects
 
     .. method:: __add__(vector)
 
 
     .. method:: __add__(vector)
 

-        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)
 
     .. 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)
         The second version translates the point by the opposite vector of *vector* and returns the resulting point.
 
     .. method:: __eq__(point)


@@ -604,11 +630,12 @@ Geometric Objects
 
 
 .. class:: Vector(coordinates)
 
 
 .. 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
 
 
     .. attribute:: symbols
 


@@ -619,7 +646,7 @@ Geometric Objects
         The dimension of the point, i.e. the number of symbols present in it.
 
     .. method:: coordinate(symbol)
         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.
 
         Return the coordinate value of the given symbol.
         Raise :exc:`KeyError` if the symbol is not involved in the point.


@@ -641,13 +668,13 @@ Geometric Objects
         Return ``True`` if not all coordinates are ``0``.
 
     .. method:: __add__(point)
         Return ``True`` if not all coordinates are ``0``.
 
     .. method:: __add__(point)

-                   __add__(vector)
+                __add__(vector)

 
         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)
 
         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.
 
         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 +683,18 @@ Geometric Objects
 
         Return the opposite vector.
 
 
         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.
     .. method:: angle(vector)
 
         Retrieve the angle required to rotate the vector into the vector passed in argument.


@@ -664,31 +703,19 @@ 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)
 
         Compute the dot product of two vectors.
 
 
     .. 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()
 
     .. 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()
 
 
     .. method:: asunit()