re-incorporated lti.timebaseEqual, with a pendingDeprecationWarning

sawyerbfuller · bnavigator · commit 24eeb75ac494 · 2020-12-31T01:16:13.000+01:00
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+    "restructuredtext.confPath": "${workspaceFolder}/doc"
+}
diff --git a/control/lti.py b/control/lti.py
@@ -14,9 +14,11 @@
 
 import numpy as np
 from numpy import absolute, real
+from warnings import warn
 
-__all__ = ['issiso', 'timebase', 'common_timebase', 'isdtime', 'isctime',
-           'pole', 'zero', 'damp', 'evalfr', 'freqresp', 'dcgain']
+__all__ = ['issiso', 'timebase', 'common_timebase', 'timebaseEqual', 
+           'isdtime', 'isctime', 'pole', 'zero', 'damp', 'evalfr', 
+           'freqresp', 'dcgain']
 
 class LTI:
     """LTI is a parent class to linear time-invariant (LTI) system objects.
@@ -158,12 +160,35 @@ def timebase(sys, strict=True):
     return sys.dt
 
 def common_timebase(dt1, dt2):
-    """Find the common timebase when interconnecting systems."""
-    # cases: 
+    """
+    Find the common timebase when interconnecting systems
+    
+    Parameters
+    ----------
+    dt1, dt2: number or system with a 'dt' attribute (e.g. TransferFunction 
+        or StateSpace system)
+
+    Returns
+    -------
+    dt: number
+        The common timebase of dt1 and dt2, as specified in 
+        :ref:`conventions-ref`. 
+        
+    Raises
+    ------
+    ValueError
+        when no compatible time base can be found
+    """
+    # explanation: 
     # if either dt is None, they are compatible with anything
     # if either dt is True (discrete with unspecified time base), 
     #   use the timebase of the other, if it is also discrete
-    # otherwise they must be equal (holds for both cont and discrete systems)
+    # otherwise both dts must be equal 
+    if hasattr(dt1, 'dt'):
+        dt1 = dt1.dt
+    if hasattr(dt2, 'dt'):
+        dt2 = dt2.dt
+
     if dt1 is None: 
         return dt2
     elif dt2 is None: 
@@ -183,6 +208,32 @@ def common_timebase(dt1, dt2):
     else: 
         raise ValueError("Systems have incompatible timebases")
 
+# Check to see if two timebases are equal
+def timebaseEqual(sys1, sys2):
+    """
+    Check to see if two systems have the same timebase
+
+    timebaseEqual(sys1, sys2)
+
+    returns True if the timebases for the two systems are compatible.  By
+    default, systems with timebase 'None' are compatible with either
+    discrete or continuous timebase systems.  If two systems have a discrete
+    timebase (dt > 0) then their timebases must be equal.
+    """
+    warn("timebaseEqual will be deprecated in a future release of "
+         "python-control; use :func:`common_timebase` instead", 
+         PendingDeprecationWarning)
+        
+    if (type(sys1.dt) == bool or type(sys2.dt) == bool):
+        # Make sure both are unspecified discrete timebases
+        return type(sys1.dt) == type(sys2.dt) and sys1.dt == sys2.dt
+    elif (sys1.dt is None or sys2.dt is None):
+        # One or the other is unspecified => the other can be anything
+        return True
+    else:
+        return sys1.dt == sys2.dt
+
+
 # Check to see if a system is a discrete time system
 def isdtime(sys, strict=False):
     """

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "restructuredtext.confPath": "${workspaceFolder}/doc"`
	`3`	`+}`