New contact module, Surface base class and tests

elastica/__init__.py

@@ -42,6 +42,9 @@
     HingeJoint,
     SelfContact,
 )
+from elastica.contact_forces import (
+    NoContact,
+)
 from elastica.callback_functions import CallBackBaseClass, ExportCallBack, MyCallBack
 from elastica.dissipation import (
     DamperBase,
@@ -54,6 +57,8 @@
 from elastica.modules.constraints import Constraints
 from elastica.modules.forcing import Forcing
 from elastica.modules.damping import Damping
+from elastica.modules.contact import Contact
+
 from elastica.transformations import inv_skew_symmetrize
 from elastica.transformations import rotate
 from elastica._calculus import (
@@ -66,7 +71,7 @@
 )
 from elastica._linalg import levi_civita_tensor
 from elastica.utils import isqrt
-from elastica.typing import RodType, SystemType
+from elastica.typing import RodType, SystemType, AllowedContactType
 from elastica.timestepper import (
     integrate,
     PositionVerlet,

elastica/contact_forces.py

@@ -0,0 +1,74 @@
+__doc__ = """ Numba implementation module containing contact between rods and rigid bodies and other rods rigid bodies or surfaces."""
+
+from elastica.typing import SystemType, AllowedContactType
+from elastica.rod import RodBase
+
+
+class NoContact:
+    """
+    This is the base class for contact applied between rod-like objects and allowed contact objects.
+
+    Notes
+    -----
+    Every new contact class must be derived
+    from NoContact class.
+
+    """
+
+    def __init__(self):
+        """
+        NoContact class does not need any input parameters.
+        """
+
+    def _order_check(
+        self,
+        system_one: SystemType,
+        system_two: AllowedContactType,
+    ):
+        """
+        This checks the contact order between a SystemType object and an AllowedContactType object, the order should follow: Rod, Rigid body, Surface.
+        In NoContact class, this just checks if system_two is a rod then system_one must be a rod.
+
+
+        Parameters
+        ----------
+        system_one
+            SystemType
+        system_two
+            AllowedContactType
+        Returns
+        -------
+
+        """
+        if issubclass(system_two.__class__, RodBase):
+            if not issubclass(system_one.__class__, RodBase):
+                raise TypeError(
+                    "Systems provided to the contact class have incorrect order. \n"
+                    " First system is {0} and second system is {1} . \n"
+                    " If the first system is a rod, the second system can be a rod, rigid body or surface. \n"
+                    " If the first system is a rigid body, the second system can be a rigid body or surface.".format(
+                        system_one.__class__, system_two.__class__
+                    )
+                )
+
+    def apply_contact(
+        self,
+        system_one: SystemType,
+        system_two: AllowedContactType,
+    ):
+        """
+        Apply contact forces and torques between SystemType object and AllowedContactType object.
+
+        In NoContact class, this routine simply passes.
+
+        Parameters
+        ----------
+        system_one : SystemType
+            Rod or rigid-body object
+        system_two : AllowedContactType
+            Rod, rigid-body, or surface object
+        Returns
+        -------
+
+        """
+        pass

elastica/modules/__init__.py

@@ -10,3 +10,4 @@
 from .forcing import Forcing
 from .callbacks import CallBacks
 from .damping import Damping
+from .contact import Contact

elastica/modules/contact.py

@@ -0,0 +1,171 @@
+__doc__ = """
+Contact
+-------
+
+Provides the contact interface to apply contact forces between objects
+(rods, rigid bodies, surfaces).
+"""
+
+
+class Contact:
+    """
+    The Contact class is a module for applying contact between rod-like objects . To apply contact between rod-like objects,
+    the simulator class must be derived from the Contact class.
+
+        Attributes
+        ----------
+        _contacts: list
+            List of contact classes defined for rod-like objects.
+    """
+
+    def __init__(self):
+        self._contacts = []
+        super(Contact, self).__init__()
+        self._feature_group_synchronize.append(self._call_contacts)
+        self._feature_group_finalize.append(self._finalize_contact)
+
+    def detect_contact_between(self, first_system, second_system):
+        """
+        This method adds contact detection between two objects using the selected contact class.
+        You need to input the two objects that are to be connected.
+
+        Parameters
+        ----------
+        first_system : object
+            Rod or rigid body object
+        second_system : object
+            Rod, rigid body or surface object
+
+        Returns
+        -------
+
+        """
+        sys_idx = [None] * 2
+        for i_sys, sys in enumerate((first_system, second_system)):
+            sys_idx[i_sys] = self._get_sys_idx_if_valid(sys)
+
+        # Create _Contact object, cache it and return to user
+        _contact = _Contact(*sys_idx)
+        self._contacts.append(_contact)
+
+        return _contact
+
+    def _finalize_contact(self):
+
+        # dev : the first indices stores the
+        # (first_rod_idx, second_rod_idx)
+        # to apply the contacts to
+        # Technically we can use another array but it its one more book-keeping
+        # step. Being lazy, I put them both in the same array
+        self._contacts[:] = [(*contact.id(), contact()) for contact in self._contacts]
+
+        # check contact order
+        for (
+            first_sys_idx,
+            second_sys_idx,
+            contact,
+        ) in self._contacts:
+            contact._order_check(
+                self._systems[first_sys_idx],
+                self._systems[second_sys_idx],
+            )
+
+    def _call_contacts(self, time, *args, **kwargs):
+        for (
+            first_sys_idx,
+            second_sys_idx,
+            contact,
+        ) in self._contacts:
+            contact.apply_contact(
+                self._systems[first_sys_idx],
+                self._systems[second_sys_idx],
+                *args,
+                **kwargs,
+            )
+
+
+class _Contact:
+    """
+    Contact module private class
+
+    Attributes
+    ----------
+    _first_sys_idx: int
+    _second_sys_idx: int
+    _contact_cls: list
+    *args
+        Variable length argument list.
+    **kwargs
+        Arbitrary keyword arguments.
+    """
+
+    def __init__(
+        self,
+        first_sys_idx: int,
+        second_sys_idx: int,
+    ):
+        """
+
+        Parameters
+        ----------
+        first_sys_idx
+        second_sys_idx
+        """
+        self.first_sys_idx = first_sys_idx
+        self.second_sys_idx = second_sys_idx
+        self._contact_cls = None
+        self._args = ()
+        self._kwargs = {}
+
+    def using(self, contact_cls, *args, **kwargs):
+        """
+        This method is a module to set which contact class is used to apply contact
+        between user defined rod-like objects.
+
+        Parameters
+        ----------
+        contact_cls: object
+            User defined callback class.
+        *args
+            Variable length argument list
+        **kwargs
+            Arbitrary keyword arguments.
+
+        Returns
+        -------
+
+        """
+        from elastica.contact_forces import NoContact
+
+        assert issubclass(
+            contact_cls, NoContact
+        ), "{} is not a valid contact class. Did you forget to derive from NoContact?".format(
+            contact_cls
+        )
+        self._contact_cls = contact_cls
+        self._args = args
+        self._kwargs = kwargs
+        return self
+
+    def id(self):
+        return (
+            self.first_sys_idx,
+            self.second_sys_idx,
+        )
+
+    def __call__(self, *args, **kwargs):
+        if not self._contact_cls:
+            raise RuntimeError(
+                "No contacts provided to to establish contact between rod-like object id {0}"
+                " and {1}, but a Contact"
+                "was intended as per code. Did you forget to"
+                "call the `using` method?".format(*self.id())
+            )
+
+        try:
+            return self._contact_cls(*self._args, **self._kwargs)
+        except (TypeError, IndexError):
+            raise TypeError(
+                r"Unable to construct contact class.\n"
+                r"Did you provide all necessary contact properties?"
+            )

elastica/surface/__init__.py

@@ -0,0 +1,2 @@
+__doc__ = """Surface classes"""
+from elastica.surface.surface_base import SurfaceBase

elastica/surface/surface_base.py

@@ -0,0 +1,18 @@
+__doc__ = """Base class for surfaces"""
+
+
+class SurfaceBase:
+    """
+    Base class for all surfaces.
+
+    Notes
+    -----
+    All new surface classes must be derived from this SurfaceBase class.
+
+    """
+
+    def __init__(self):
+        """
+        SurfaceBase does not take any arguments.
+        """
+        pass

elastica/typing.py

@@ -1,7 +1,9 @@
 from elastica.rod import RodBase
 from elastica.rigidbody import RigidBodyBase
+from elastica.surface import SurfaceBase
 
 from typing import Type, Union
 
 RodType = Type[RodBase]
 SystemType = Union[RodType, Type[RigidBodyBase]]
+AllowedContactType = Union[SystemType, Type[SurfaceBase]]