Update documentation to match __repr__() changes

[linpy.git] / linpy / geometry.py

diff --git a/linpy/geometry.py b/linpy/geometry.py
index 335a826..cc19a72 100644 (file)
--- a/linpy/geometry.py
+++ b/linpy/geometry.py
@@ -33,65 +33,113 @@ __all__ = [
 
 
 class GeometricObject(ABC):
 
 
 class GeometricObject(ABC):

+    """
+    GeometricObject is an abstract class to represent objects with a
+    geometric representation in space. Subclasses of GeometricObject are
+    Polyhedron, Domain and Point.
+    """

 
     @abstractproperty
     def symbols(self):
 
     @abstractproperty
     def symbols(self):

+        """
+        The tuple of symbols present in the object expression, sorted according
+        to Symbol.sortkey().
+        """

         pass
 
     @property
     def dimension(self):
         pass
 
     @property
     def dimension(self):

+        """
+        The dimension of the object, i.e. the number of symbols present in it.
+        """

         return len(self.symbols)
 
     @abstractmethod
     def aspolyhedron(self):
         return len(self.symbols)
 
     @abstractmethod
     def aspolyhedron(self):

+        """
+        Return a Polyhedron object that approximates the geometric object.
+        """

         pass
 
     def asdomain(self):
         pass
 
     def asdomain(self):

+        """
+        Return a Domain object that approximates the geometric object.
+        """

         return self.aspolyhedron()
 
 
 class Coordinates:
         return self.aspolyhedron()
 
 
 class Coordinates:

+    """
+    This class represents coordinate systems.
+    """

 
     __slots__ = (
         '_coordinates',
     )
 
     def __new__(cls, coordinates):
 
     __slots__ = (
         '_coordinates',
     )
 
     def __new__(cls, coordinates):

+        """
+        Create a coordinate system from a dictionary or a sequence that maps the
+        symbols to their coordinates. Coordinates must be rational numbers.
+        """

         if isinstance(coordinates, Mapping):
             coordinates = coordinates.items()
         self = object().__new__(cls)
         if isinstance(coordinates, Mapping):
             coordinates = coordinates.items()
         self = object().__new__(cls)

-        self._coordinates = OrderedDict()
-        for symbol, coordinate in sorted(coordinates,
-                key=lambda item: item[0].sortkey()):
+        self._coordinates = []
+        for symbol, coordinate in coordinates:

             if not isinstance(symbol, Symbol):
                 raise TypeError('symbols must be Symbol instances')
             if not isinstance(coordinate, numbers.Real):
                 raise TypeError('coordinates must be real numbers')
             if not isinstance(symbol, Symbol):
                 raise TypeError('symbols must be Symbol instances')
             if not isinstance(coordinate, numbers.Real):
                 raise TypeError('coordinates must be real numbers')

-            self._coordinates[symbol] = coordinate
+            self._coordinates.append((symbol, coordinate))
+        self._coordinates.sort(key=lambda item: item[0].sortkey())
+        self._coordinates = OrderedDict(self._coordinates)

         return self
 
     @property
     def symbols(self):
         return self
 
     @property
     def symbols(self):

+        """
+        The tuple of symbols present in the coordinate system, sorted according
+        to Symbol.sortkey().
+        """

         return tuple(self._coordinates)
 
     @property
     def dimension(self):
         return tuple(self._coordinates)
 
     @property
     def dimension(self):

+        """
+        The dimension of the coordinate system, i.e. the number of symbols
+        present in it.
+        """

         return len(self.symbols)
 
         return len(self.symbols)
 

-    def coordinates(self):
-        yield from self._coordinates.items()
-

     def coordinate(self, symbol):
     def coordinate(self, symbol):

+        """
+        Return the coordinate value of the given symbol. Raise KeyError if the
+        symbol is not involved in the coordinate system.
+        """

         if not isinstance(symbol, Symbol):
             raise TypeError('symbol must be a Symbol instance')
         return self._coordinates[symbol]
 
     __getitem__ = coordinate
 
         if not isinstance(symbol, Symbol):
             raise TypeError('symbol must be a Symbol instance')
         return self._coordinates[symbol]
 
     __getitem__ = coordinate
 

+    def coordinates(self):
+        """
+        Iterate over the pairs (symbol, value) of coordinates in the coordinate
+        system.
+        """
+        yield from self._coordinates.items()
+

     def values(self):
     def values(self):

+        """
+        Iterate over the coordinate values in the coordinate system.
+        """

         yield from self._coordinates.values()
 
     def __bool__(self):
         yield from self._coordinates.values()
 
     def __bool__(self):

+        """
+        Return True if not all coordinates are 0.
+        """

         return any(self._coordinates.values())
 
     def __hash__(self):
         return any(self._coordinates.values())
 
     def __hash__(self):


@@ -121,11 +169,13 @@ class Coordinates:
 class Point(Coordinates, GeometricObject):
     """
     This class represents points in space.
 class Point(Coordinates, GeometricObject):
     """
     This class represents points in space.

+
+    Point instances are hashable and should be treated as immutable.

     """
 
     def isorigin(self):
         """
     """
 
     def isorigin(self):
         """

-        Return True if a Point is the origin.
+        Return True if all coordinates are 0.

         """
         return not bool(self)
 
         """
         return not bool(self)
 


@@ -134,16 +184,18 @@ class Point(Coordinates, GeometricObject):
 
     def __add__(self, other):
         """
 
     def __add__(self, other):
         """

-        Adds a Point to a Vector and returns the result as a Point.
+        Translate the point by a Vector object and return the resulting point.

         """
         """

-        if not isinstance(other, Vector):
-            return NotImplemented
-        coordinates = self._map2(other, operator.add)
-        return Point(coordinates)
+        if isinstance(other, Vector):
+            coordinates = self._map2(other, operator.add)
+            return Point(coordinates)
+        return NotImplemented

 
     def __sub__(self, other):
         """
 
     def __sub__(self, other):
         """

-        Returns the difference between two Points as a Vector.
+        If other is a point, substract it from self and return the resulting
+        vector. If other is a vector, translate the point by the opposite vector
+        and returns the resulting point.

         """
         coordinates = []
         if isinstance(other, Point):
         """
         coordinates = []
         if isinstance(other, Point):


@@ -152,20 +204,17 @@ class Point(Coordinates, GeometricObject):
         elif isinstance(other, Vector):
             coordinates = self._map2(other, operator.sub)
             return Point(coordinates)
         elif isinstance(other, Vector):
             coordinates = self._map2(other, operator.sub)
             return Point(coordinates)

-        else:
-            return NotImplemented
+        return NotImplemented

 
     def __eq__(self, other):
         """
 
     def __eq__(self, other):
         """

-        Compares two Points for equality.
+        Test whether two points are equal.

         """
         """

-        return isinstance(other, Point) and \
-            self._coordinates == other._coordinates
+        if isinstance(other, Point):
+            return self._coordinates == other._coordinates
+        return NotImplemented

 
     def aspolyhedron(self):
 
     def aspolyhedron(self):

-        """
-        Return a Point as a polyhedron.
-        """

         from .polyhedra import Polyhedron
         equalities = []
         for symbol, coordinate in self.coordinates():
         from .polyhedra import Polyhedron
         equalities = []
         for symbol, coordinate in self.coordinates():


@@ -175,10 +224,16 @@ class Point(Coordinates, GeometricObject):
 
 class Vector(Coordinates):
     """
 
 class Vector(Coordinates):
     """

-    This class represents displacements in space.
+    This class represents vectors in space.
+
+    Vector instances are hashable and should be treated as immutable.

     """
 
     def __new__(cls, initial, terminal=None):
     """
 
     def __new__(cls, initial, terminal=None):

+        """
+        Create a vector from a dictionary or a sequence that maps the symbols to
+        their coordinates, or as the displacement between two points.
+        """

         if not isinstance(initial, Point):
             initial = Point(initial)
         if terminal is None:
         if not isinstance(initial, Point):
             initial = Point(initial)
         if terminal is None:


@@ -191,7 +246,7 @@ class Vector(Coordinates):
 
     def isnull(self):
         """
 
     def isnull(self):
         """

-        Returns true if a Vector is null.
+        Return True if all coordinates are 0.

         """
         return not bool(self)
 
         """
         return not bool(self)
 


@@ -200,13 +255,60 @@ class Vector(Coordinates):
 
     def __add__(self, other):
         """
 
     def __add__(self, other):
         """

-        Adds either a Point or Vector to a Vector.
+        If other is a point, translate it with the vector self and return the
+        resulting point. If other is a vector, return the vector self + other.

         """
         if isinstance(other, (Point, Vector)):
             coordinates = self._map2(other, operator.add)
             return other.__class__(coordinates)
         return NotImplemented
 
         """
         if isinstance(other, (Point, Vector)):
             coordinates = self._map2(other, operator.add)
             return other.__class__(coordinates)
         return NotImplemented
 

+    def __sub__(self, other):
+        """
+        If other is a point, substract it from the vector self and return the
+        resulting point. If other is a vector, return the vector self - other.
+        """
+        if isinstance(other, (Point, Vector)):
+            coordinates = self._map2(other, operator.sub)
+            return other.__class__(coordinates)
+        return NotImplemented
+
+    def __neg__(self):
+        """
+        Return the vector -self.
+        """
+        coordinates = self._map(operator.neg)
+        return Vector(coordinates)
+
+    def __mul__(self, other):
+        """
+        Multiplies a Vector by a scalar value.
+        """
+        if isinstance(other, numbers.Real):
+            coordinates = self._map(lambda coordinate: other * coordinate)
+            return Vector(coordinates)
+        return NotImplemented
+
+    __rmul__ = __mul__
+
+    def __truediv__(self, other):
+        """
+        Divide the vector by the specified scalar and returns the result as a
+        vector.
+        """
+        if isinstance(other, numbers.Real):
+            coordinates = self._map(lambda coordinate: coordinate / other)
+            return Vector(coordinates)
+        return NotImplemented
+
+    def __eq__(self, other):
+        """
+        Test whether two vectors are equal.
+        """
+        if isinstance(other, Vector):
+            return self._coordinates == other._coordinates
+        return NotImplemented
+

     def angle(self, other):
         """
         Retrieve the angle required to rotate the vector into the vector passed
     def angle(self, other):
         """
         Retrieve the angle required to rotate the vector into the vector passed


@@ -220,7 +322,8 @@ class Vector(Coordinates):
 
     def cross(self, other):
         """
 
     def cross(self, other):
         """

-        Calculate the cross product of two Vector3D structures.
+        Compute the cross product of two 3D vectors. If either one of the
+        vectors is not three-dimensional, a ValueError exception is raised.

         """
         if not isinstance(other, Vector):
             raise TypeError('other must be a Vector instance')
         """
         if not isinstance(other, Vector):
             raise TypeError('other must be a Vector instance')


@@ -235,19 +338,9 @@ class Vector(Coordinates):
         coordinates.append((z, self[x]*other[y] - self[y]*other[x]))
         return Vector(coordinates)
 
         coordinates.append((z, self[x]*other[y] - self[y]*other[x]))
         return Vector(coordinates)
 

-    def __truediv__(self, other):
-        """
-        Divide the vector by the specified scalar and returns the result as a
-        vector.
-        """
-        if not isinstance(other, numbers.Real):
-            return NotImplemented
-        coordinates = self._map(lambda coordinate: coordinate / other)
-        return Vector(coordinates)
-

     def dot(self, other):
         """
     def dot(self, other):
         """

-        Calculate the dot product of two vectors.
+        Compute the dot product of two vectors.

         """
         if not isinstance(other, Vector):
             raise TypeError('argument must be a Vector instance')
         """
         if not isinstance(other, Vector):
             raise TypeError('argument must be a Vector instance')


@@ -256,54 +349,27 @@ class Vector(Coordinates):
             result += coordinate1 * coordinate2
         return result
 
             result += coordinate1 * coordinate2
         return result
 

-    def __eq__(self, other):
-        """
-        Compares two Vectors for equality.
-        """
-        return isinstance(other, Vector) and \
-            self._coordinates == other._coordinates
-

     def __hash__(self):
     def __hash__(self):

-        return hash(tuple(self.coordinates()))
-
-    def __mul__(self, other):
-        """
-        Multiplies a Vector by a scalar value.
-        """
-        if not isinstance(other, numbers.Real):
-            return NotImplemented
-        coordinates = self._map(lambda coordinate: other * coordinate)
-        return Vector(coordinates)
-
-    __rmul__ = __mul__
-
-    def __neg__(self):
-        """
-        Returns the negated form of a Vector.
-        """
-        coordinates = self._map(operator.neg)
-        return Vector(coordinates)
+        return super().__hash__()

 
     def norm(self):
         """
 
     def norm(self):
         """

-        Normalizes a Vector.
+        Return the norm of the vector.

         """
         return math.sqrt(self.norm2())
 
     def norm2(self):
         """
         return math.sqrt(self.norm2())
 
     def norm2(self):

+        """
+        Return the squared norm of the vector.
+        """

         result = 0
         for coordinate in self._coordinates.values():
             result += coordinate ** 2
         return result
 
     def asunit(self):
         result = 0
         for coordinate in self._coordinates.values():
             result += coordinate ** 2
         return result
 
     def asunit(self):

-        return self / self.norm()
-
-    def __sub__(self, other):

         """
         """

-        Subtract a Point or Vector from a Vector.
+        Return the normalized vector, i.e. the vector of same direction but with
+        norm 1.

         """
         """

-        if isinstance(other, (Point, Vector)):
-            coordinates = self._map2(other, operator.sub)
-            return other.__class__(coordinates)
-        return NotImplemented
+        return self / self.norm()