Doc updates (not complete)

[linpy.git] / doc / domain.rst

diff --git a/doc/domain.rst b/doc/domain.rst
index 4cd79d9..06eec6e 100644 (file)
--- a/doc/domain.rst
+++ b/doc/domain.rst
@@ -1,31 +1,36 @@
 Domains Module
 ==============
 
 Domains Module
 ==============
 

+This module provides classes and functions to deal with polyhedral
+domains, i.e. unions of polyhedra.
+

 .. py:class :: Domain
 
 .. py:class :: Domain
 

-    The properties of a domain can be are found using the following
+    This class represents polyhedral domains, i.e. unions of polyhedra.
+
+    .. py:method:: __new__(cls, *polyhedra)
+    
+       Create and return a new domain from a string or a list of polyhedra. 

 
 

-    .. py:method:: symbols
+    .. attribute:: polyhedra
+    
+       The tuple of polyhedra which constitute the domain. 
+    
+    .. attribute:: symbols

 
         Returns a tuple of the symbols that exsist in a domain.
 
 
         Returns a tuple of the symbols that exsist in a domain.
 

-    .. py:method:: dimension
+    .. attribute:: dimension

 
         Returns the number of variables that exist in a domain.
 
 
         Returns the number of variables that exist in a domain.
 

-    .. py:method:: disjoint
-
-        Returns a domain as disjoint.
-
-    .. py:method:: involves_vars(self, dims)
-
-       Returns ``True`` if a domain depends on the given dimensions.
-
-    The unary properties of a domain can be inspected using the following methods.
-

     .. py:method:: isempty(self)
 
         Return ``True`` is a domain is empty.
     .. py:method:: isempty(self)
 
         Return ``True`` is a domain is empty.

+        
+    .. py:method:: __bool__(self)
+    
+        Return ``True`` if the domain is non-empty.

 
     .. py:method:: isuniverse(self)
 
 
     .. py:method:: isuniverse(self)
 


@@ -35,11 +40,9 @@ Domains Module
 
         Return ``True`` if a domain is bounded.
 
 
         Return ``True`` if a domain is bounded.
 

-    .. py:method:: disjoint(self)
-
-        It is not guarenteed that a domain is disjoint. If it is necessary, this method will return a domain as disjoint.
+    .. py:method:: make_disjoint(self)

 
 

-    The following methods compare two domains to find the binary properties.
+        It is not guarenteed that a domain is disjoint. If it is necessary, this method will return an equivalent domain, whose polyhedra are disjoint.

 
     .. py:method:: isdisjoint(self, other)
 
 
     .. py:method:: isdisjoint(self, other)
 


@@ -74,21 +77,29 @@ Domains Module
 
        Test whether every element in *other* is in a domain.
 
 
        Test whether every element in *other* is in a domain.
 

-
-    The following methods implement unary operations on a domain.
-

     .. py:method:: complement(self)
     .. py:method:: complement(self)

-                   ¬self
-
-        Return the complement of a domain.
+                   ~self
+
+        Return the complementary domain of a domain.
+        
+    .. py:method:: coalesce(self)
+    
+       Simplify the representation of the domain by trying to combine pairs of
+        polyhedra into a single polyhedron. 
+        
+        
+    .. py:method:: detect_equalities(self)
+    
+        Simplify the representation of the domain by detecting implicit
+        equalities.

 
     .. py:method:: simplify(self)
 
         Return a new domain without any redundant constraints.
 
 
     .. py:method:: simplify(self)
 
         Return a new domain without any redundant constraints.
 

-    .. py:method:: project(self, dims)
+    .. py:method:: project(self, variables)

 
 

-        Return a new domain with the given dimensions removed.
+        Return a new domain with the given variables removed.

 
     .. py:method:: aspolyhedron(self)
 
 
     .. py:method:: aspolyhedron(self)
 


@@ -98,19 +109,20 @@ Domains Module
 
         Return a single sample subset of a domain.
 
 
         Return a single sample subset of a domain.
 

-    The following methods implement binary operations on two domains.
-

     .. py:method:: intersection(self, other)
     .. py:method:: intersection(self, other)

+                  __or__

                    self | other
 
         Return a new domain with the elements that are common between *self* and *other*.
 
     .. py:method:: union(self, other)
                    self | other
 
         Return a new domain with the elements that are common between *self* and *other*.
 
     .. py:method:: union(self, other)

+                  __and__

                    self & other
 
         Return a new domain with all the elements from *self* and *other*.
 
     .. py:method:: difference(self, other)
                    self & other
 
         Return a new domain with all the elements from *self* and *other*.
 
     .. py:method:: difference(self, other)

+                  __sub__

                    self - other
 
         Return a new domain with the elements in a domain that are not in *other* .
                    self - other
 
         Return a new domain with the elements in a domain that are not in *other* .


@@ -120,22 +132,40 @@ Domains Module
 
         Return the sum of two domains.
 
 
         Return the sum of two domains.
 

-    The following methods use lexicographical ordering to find the maximum or minimum element in a domain.
-

     .. py:method:: lexmin(self)
 
     .. py:method:: lexmin(self)
 

-        Return a new set containing the lexicographic minimum of the elements in the set.
+        Return a new domain containing the lexicographic minimum of the elements in the domain.

 
     .. py:method:: lexmax(self)
 
 
     .. py:method:: lexmax(self)
 

-        Return a new set containing the lexicographic maximum of the elements in the set.
+        Return a new domain containing the lexicographic maximum of the elements in the domain.
+
+    .. py:method:: subs(self, symbol, expression=None):
+
+        Subsitute symbol by expression in equations and return the resulting
+        domain.

 
 

+    .. py:method:: fromstring(cls, string)
+        
+        Convert a string into a domain.
+        
+    .. py:method:: fromsympy(cls, expr)
+    
+        Convert a SymPy expression into a domain.
+        
+    .. py:method:: tosympy(self)
+    
+        Convert a domain into a SymPy expression.

 
 

-    A 2D or 3D domain can be plotted using the :meth:`plot` function. The points, verticies, and faces of a domain can be inspected using the following functions.
+A 2D or 3D domain can be plotted using the :meth:`plot` method. The points, vertices, and faces of a domain can be inspected using the following functions.

 
     .. py:method:: points(self)
 
 
     .. py:method:: points(self)
 

-        Return a list of the points contained in a domain as :class:`Points` objects.
+        Return a list of the points with integer coordinates contained in a domain as :class:`Points` objects.
+        
+    .. py:method:: __contains__(self, point)
+    
+       Return ``True`` if point if contained within the domain. 

 
     .. py:method:: vertices(self)
 
 
     .. py:method:: vertices(self)
 


@@ -147,4 +177,4 @@ Domains Module
 
     .. py:method:: plot(self, plot=None, **kwargs)
 
 
     .. py:method:: plot(self, plot=None, **kwargs)
 

-        Return a plot of the given domain.
+        Return a plot of the given domain or add a plot to a plot instance, using matplotlib.