From 0ea17d8ff46323e2413c7c291102a3336add0e36 Mon Sep 17 00:00:00 2001 From: Kush <54781152+SpartaKushK@users.noreply.github.com> Date: Wed, 12 Jul 2023 15:49:37 +0200 Subject: [PATCH] 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 Co-authored-by: Dario Coscia <93731561+dario-coscia@users.noreply.github.com> --- pina/geometry/difference_domain.py | 13 +++++++++++-- pina/geometry/exclusion_domain.py | 11 ++++++++++- pina/geometry/intersection_domain.py | 11 ++++++++++- pina/geometry/operation_interface.py | 11 +++++++++-- pina/geometry/union_domain.py | 14 ++++++++++++-- 5 files changed, 52 insertions(+), 8 deletions(-) diff --git a/pina/geometry/difference_domain.py b/pina/geometry/difference_domain.py index 4ede524..9a571cb 100644 --- a/pina/geometry/difference_domain.py +++ b/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. diff --git a/pina/geometry/exclusion_domain.py b/pina/geometry/exclusion_domain.py index 2931b3f..ebfbb8f 100644 --- a/pina/geometry/exclusion_domain.py +++ b/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'. diff --git a/pina/geometry/intersection_domain.py b/pina/geometry/intersection_domain.py index ce53e8e..be78885 100644 --- a/pina/geometry/intersection_domain.py +++ b/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 diff --git a/pina/geometry/operation_interface.py b/pina/geometry/operation_interface.py index 53cc885..ae6fc79 100644 --- a/pina/geometry/operation_interface.py +++ b/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 diff --git a/pina/geometry/union_domain.py b/pina/geometry/union_domain.py index 415b8b6..6f10c8a 100644 --- a/pina/geometry/union_domain.py +++ b/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