X-Git-Url: https://scm.cri.ensmp.fr/git/linpy.git/blobdiff_plain/e50b2facb441d96febf17a6210370489bbcb9dbf..454a26a54cc7ff563ab278567f3bbad9c6ff42bb:/doc/domain.rst diff --git a/doc/domain.rst b/doc/domain.rst index 7098c32..06eec6e 100644 --- a/doc/domain.rst +++ b/doc/domain.rst @@ -1,157 +1,180 @@ Domains Module ============== +This module provides classes and functions to deal with polyhedral +domains, i.e. unions of polyhedra. + .. 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:: symbols + .. py:method:: __new__(cls, *polyhedra) - Returns a tuple of the symbols that exsist in a domain. + Create and return a new domain from a string or a list of polyhedra. - .. py:method:: dimension + .. attribute:: polyhedra + + The tuple of polyhedra which constitute the domain. + .. attribute:: symbols + + Returns a tuple of the symbols that exsist in a domain. + + .. attribute:: dimension + Returns the number of variables that exist in a domain. - .. py:method:: disjoint - - Returns a domain as disjoint. - - .. py:method:: num_parameters - - Returns the total number of parameters, input, output or dimensions in a domain. - - .. py:method:: involves_dims(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:: isuniverse(self) + .. py:method:: __bool__(self) + Return ``True`` if the domain is non-empty. + + .. py:method:: isuniverse(self) + Return ``True`` if a domain is the Universe set. - + .. py:method:: isbounded(self) - - 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. + Return ``True`` if a domain is bounded. + + .. 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) - + Return ``True`` if the intersection of *self* and *other* results in an empty set. - + .. py:method:: issubset(self, other) - + Test whether every element in a domain is in *other*. .. py:method:: __eq__(self, other) self == other - - Test whether a domain is equal to *other*. - + + Test whether a domain is equal to *other*. + .. py:method:: __lt__(self, other) self < other - - Test whether a domain is a strict subset of *other*. - + + Test whether a domain is a strict subset of *other*. + .. py:method:: __le__(self, other) self <= other - - Test whether every element in a domain is in *other*. - + + Test whether every element in a domain is in *other*. + .. py:method:: __gt__(self, other) self > other - - Test whether a domain is a strict superset of *other*. - + + Test whether a domain is a strict superset of *other*. + .. py:method:: __ge__(self, other) self >= other - - Test whether every element in *other* is in a domain. - - The following methods implement unary operations on a domain. + Test whether every element in *other* is in a domain. .. py:method:: complement(self) - ¬self + ~self + + Return the complementary domain of a domain. + + .. py:method:: coalesce(self) - Return the complement of a domain. + 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:: project(self, dims) - - Return a new domain with the given dimensions removed. + .. py:method:: project(self, variables) + + Return a new domain with the given variables removed. .. py:method:: aspolyhedron(self) - - Return polyhedral hull of a domain. - + + Return polyhedral hull of a domain. + .. py:method:: sample(self) - - Return a single sample subset of a domain. - The following methods implement binary operations on two domains. + Return a single sample subset of a domain. .. py:method:: intersection(self, other) + __or__ self | other - - Return a new domain with the elements that are common between *self* and *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*. - + + 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* . - + + Return a new domain with the elements in a domain that are not in *other* . + .. py:method:: __add__(self, other) self + other - - Return the sum of two domains. - - The following methods use lexicographical ordering to find the maximum or minimum element in a domain. + + Return the sum of two domains. .. 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) + + 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) - Return a new set containing the lexicographic maximum of the elements in the set. + 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) + + Return a list of the points with integer coordinates contained in a domain as :class:`Points` objects. + + .. py:method:: __contains__(self, point) - Return a list of the points contained in a domain as :class:`Points` objects. + Return ``True`` if point if contained within the domain. .. py:method:: vertices(self) - + Return a list of the verticies of a domain. - + .. py:method:: faces(self) - + Return a list of the vertices for each face of a domain. - + .. 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.