Operation docs update (#154)

* Operation Interface Enhancement + Clarification
- added set notation to all the geometry operations
- added a warning to say sample_surface=True doesn't work

* minor fix docs

* fix operation_interface.py doc

---------

Co-authored-by: Dario Coscia <dariocoscia@Dario-Coscia.local>
Co-authored-by: Dario Coscia <93731561+dario-coscia@users.noreply.github.com>

pina/geometry/difference_domain.py

@@ -9,7 +9,16 @@ class Difference(OperationInterface):
     """ PINA implementation of Difference of Domains."""
 
     def __init__(self, geometries):
-        """ PINA implementation of Difference of Domains.
+        """
+        PINA implementation of Difference of Domains.
+        Given two sets :math:`A` and :math:`B` then the
+        domain difference is defined as:
+
+        ..:math:
+        A \setminus B = \{x \mid x \in A \text{ and } x \not\in B\},
+
+        with :math:`x` a point in :math:`\mathbb{R}^N` and :math:`N`
+        the dimension of the geometry space.
 
         :param list geometries: A list of geometries from 'pina.geometry' 
             such as 'EllipsoidDomain' or 'CartesianDomain'. The first 
@@ -32,7 +41,7 @@ class Difference(OperationInterface):
             if geometry.is_inside(point):
                 return False
         return self.geometries[0].is_inside(point, check_border)
-    
+
     def sample(self, n, mode='random', variables='all'):
         """Sample routine for difference domain.
 

pina/geometry/exclusion_domain.py

@@ -11,7 +11,16 @@ class Exclusion(OperationInterface):
     """ PINA implementation of Exclusion of Domains."""
 
     def __init__(self, geometries):
-        """ PINA implementation of Exclusion of Domains.
+        """
+        PINA implementation of Exclusion of Domains.
+        Given two sets :math:`A` and :math:`B` then the
+        domain difference is defined as:
+
+        ..:math:
+        A \setminus B = \{x \mid x \in A \text{ and } x \in B\ \text{ and } x \not\in (A \text{ or } B)},
+
+        with :math:`x` a point in :math:`\mathbb{R}^N` and :math:`N`
+        the dimension of the geometry space.
 
         :param list geometries: A list of geometries from 'pina.geometry' 
             such as 'EllipsoidDomain' or 'CartesianDomain'.

pina/geometry/intersection_domain.py

@@ -10,7 +10,16 @@ class Intersection(OperationInterface):
     """ PINA implementation of Intersection of Domains."""
 
     def __init__(self, geometries):
-        """ PINA implementation of Intersection of Domains.
+        """
+        PINA implementation of Intersection of Domains.
+        Given two sets :math:`A` and :math:`B` then the
+        domain difference is defined as:
+
+        ..:math:
+        A \cap B = \{x \mid x \in A \text{ and } x \in B\},
+
+        with :math:`x` a point in :math:`\mathbb{R}^N` and :math:`N`
+        the dimension of the geometry space.
 
         :param list geometries: A list of geometries from 'pina.geometry' 
             such as 'EllipsoidDomain' or 'CartesianDomain'. The intersection

pina/geometry/operation_interface.py

@@ -7,21 +7,28 @@ import random
 
 
 class OperationInterface(Location, metaclass=ABCMeta):
+    """PINA Operation Interface"""
+
     def __init__(self, geometries):
         """
         Abstract Operation class.
         Any geometry operation entity must inherit from this class.
 
+        .. warning::
+            The ``sample_surface=True`` option is not implemented yet
+            for Difference, Intersection, and Exclusion. The usage will
+            result in unwanted behaviour.
+
         :param list geometries: A list of geometries from 'pina.geometry' 
             such as 'EllipsoidDomain' or 'CartesianDomain'.
         """
         # check consistency geometries
         check_consistency(geometries, Location)
 
-        # check we are passing always different 
+        # check we are passing always different
         # geometries with the same labels.
         self._check_dimensions(geometries)
-        
+
         # assign geometries
         self._geometries = geometries
 

pina/geometry/union_domain.py

@@ -10,7 +10,16 @@ class Union(OperationInterface):
     """ PINA implementation of Unions of Domains."""
 
     def __init__(self, geometries):
-        """ PINA implementation of Unions of Domains.
+        """
+        PINA implementation of Unions of Domains.
+        Given two sets :math:`A` and :math:`B` then the
+        domain difference is defined as:
+
+        ..:math:
+        A \cup B = \{x \mid x \in A \text{ or } x \in B\},
+
+        with :math:`x` a point in :math:`\mathbb{R}^N` and :math:`N`
+        the dimension of the geometry space.
 
         :param list geometries: A list of geometries from 'pina.geometry' 
             such as 'EllipsoidDomain' or 'CartesianDomain'.
@@ -86,7 +95,8 @@ class Union(OperationInterface):
             # int(i < remainder) is one only if we have a remainder
             # different than zero. Notice that len(geometries) is
             # always smaller than remaider.
-            sampled_points.append(geometry.sample(num_points + int(i < remainder), mode, variables))
+            sampled_points.append(geometry.sample(
+                num_points + int(i < remainder), mode, variables))
             # in case number of sampled points is smaller than the number of geometries
             if len(sampled_points) >= n:
                 break