[SymForce] Add symforce.set_epsilon_to_symbol

It is moderately inconvenient to set epsilon to a symbol
as is. This is because if one wants to set epsilont to a
symbol, one might run

``` python
import symforce.symbolic as sf
import symforce
symforce.set_epsilon(sf.Symbol("epsilon"))
```

The trouble with this, however, is that the file defining `Symbol` also
defined `atan2`, `asin_safe`, and `acos_safe`, which themselves
use the default epsilon. But since `symforce.set_epsilon` can only
be called before the value of epsilon is used (a restriction we impose
because default function arguments are bound at function definition
time, not late bound), the above snippet produces an error.

Now, we only import `symforce.symbolic` to have access to `Symbol`, and
don't actually need those default epsilon using functions.

A user could instead just import `sympy` or `symengine` directly, but
that would be inconvenient and confusing (especially for such a common
use case).

So instead, I'm adding the function `symforce.set_epsilon_to_symbol`
(along with `symforce.set_epsilon_to_number` and
`symforce.set_epsilon_to_zero`). This function will handle the import of
`Symbol` for the user, saving the user the trouble.

The other `symforce.set_epsilon_to_XXX` functions aren't strictly
necessary for anything, but in discussion with Aaron and Hayk, we
thought this api seemed nicest.

The default value for `symforce.set_epsilon_to_number` is supposed to be
`sf.numeric_epsilon`, which posed a small problem (the same exact
problem as `sf.Symbol`). To address this, I moved the definition of
`numeric_epsilon` to `symforce/__init__.py`, then reexport it in
`symforce.symbolic`.

An alternative was to simply redefine `atan2`, `asin_safe`, and
`acos_safe` whenever a new value of epsilon is set, allowing a user to
set epsilon after importing `symforce.symbolic`, but in conversation it
was deciding this was not something we wanted to allow.

Topic: set_epsilon_to_symbol
GitOrigin-RevId: 24d1a2389427316d21bd85322e43032ec7f7ae2e

Author: bradley-solliday-skydio

symforce/__init__.py

@@ -11,6 +11,7 @@
 from types import ModuleType
 import typing as T
 import os
+import sys
 import warnings
 
 # -------------------------------------------------------------------------------------------------
@@ -50,8 +51,6 @@ def set_log_level(log_level: str) -> None:
     logger.setLevel(getattr(logging, log_level.upper()))
 
     # Only do this if already imported, in case users don't want to use any C++ binaries
-    import sys
-
     if "cc_sym" in sys.modules:
         import cc_sym
 
@@ -80,8 +79,6 @@ def _find_symengine() -> ModuleType:
 
     Returns the imported symengine module
     """
-    import sys
-
     if "symengine" in sys.modules:
         return sys.modules["symengine"]
 
@@ -235,6 +232,9 @@ def set_backend(name: str) -> None:
 # Default epsilon
 # --------------------------------------------------------------------------------
 
+# Should match C++ default epsilon in epsilon.h
+numeric_epsilon = 10 * sys.float_info.epsilon
+
 
 class AlreadyUsedEpsilon(Exception):
     """
@@ -248,7 +248,7 @@ class AlreadyUsedEpsilon(Exception):
 _have_used_epsilon = False
 
 
-def set_epsilon(new_epsilon: T.Any) -> None:
+def _set_epsilon(new_epsilon: T.Any) -> None:
     """
     Set the default epsilon for SymForce
 
@@ -266,3 +266,46 @@ def set_epsilon(new_epsilon: T.Any) -> None:
 
     global _epsilon  # pylint: disable=global-statement
     _epsilon = new_epsilon
+
+
+def set_epsilon_to_symbol(name: str = "epsilon") -> None:
+    """
+    Set the default epsilon for Symforce to a Symbol.
+
+    This must be called before `symforce.symbolic` or other symbolic libraries have been imported.
+    See `symforce.symbolic.epsilon` for more information.
+
+    Args:
+        name: The name of the symbol for the new default epsilon to use
+    """
+    if get_symbolic_api() == "sympy":
+        import sympy
+    elif get_symbolic_api() == "symengine":
+        sympy = _find_symengine()
+    else:
+        raise InvalidSymbolicApiError(get_symbolic_api())
+
+    _set_epsilon(sympy.Symbol(name))
+
+
+def set_epsilon_to_number(value: T.Any = numeric_epsilon) -> None:
+    """
+    Set the default epsilon for Symforce to a number.
+
+    This must be called before `symforce.symbolic` or other symbolic libraries have been imported.
+    See `symforce.symbolic.epsilon` for more information.
+
+    Args:
+        value: The new default epsilon to use
+    """
+    _set_epsilon(value)
+
+
+def set_epsilon_to_zero() -> None:
+    """
+    Set the default epsilon for Symforce to zero.
+
+    This must be called before `symforce.symbolic` or other symbolic libraries have been imported.
+    See `symforce.symbolic.epsilon` for more information.
+    """
+    _set_epsilon(0.0)

symforce/internal/symbolic.py

@@ -28,8 +28,6 @@
 # pylint: disable=ungrouped-imports
 
 import contextlib
-import sys
-
 import symforce
 from symforce import typing as T
 from symforce import logger
@@ -255,8 +253,7 @@
 # --------------------------------------------------------------------------------
 
 
-# Should match C++ default epsilon in epsilon.h
-numeric_epsilon = 10 * sys.float_info.epsilon
+from symforce import numeric_epsilon
 
 
 def epsilon() -> T.Any:

test/symforce_set_epsilon_test.py

@@ -0,0 +1,149 @@
+# ----------------------------------------------------------------------------
+# SymForce - Copyright 2022, Skydio, Inc.
+# This source code is under the Apache 2.0 license found in the LICENSE file.
+# ----------------------------------------------------------------------------
+
+import sys
+
+from symforce.test_util import TestCase
+from symforce import typing as T
+
+
+def clear_symforce() -> None:
+    """
+    Removes symforce modules from sys.modules. Ensures that all symforce
+    code will be (re-)executed upon import.
+    """
+    module_names = list(sys.modules.keys())
+    for module in module_names:
+        if module.startswith("symforce"):
+            del sys.modules[module]
+
+
+class SymforceSetEpsilonTest(TestCase):
+    """
+    Test symforce.set_epsilon functions.
+    """
+
+    saved_modules: T.List[T.Tuple[str, T.Any]] = []
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        # NOTE(brad): This is necessary because while the test classes are run sequentially, it
+        # seems they are all created before any are run. That means they can save references to
+        # modules which might get deleted and reloaded by clear_symforce.
+        #
+        # Since some code relies on the original module still being available in sys.modules, we
+        # need to save and restore the original modules to keep from breaking other tests.
+        cls.saved_modules = []
+        for module in sys.modules:
+            if module.startswith("symforce"):
+                cls.saved_modules.append((module, sys.modules[module]))
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        clear_symforce()
+
+        for key, module in cls.saved_modules:
+            sys.modules[key] = module
+
+    def test_set_epsilon_to_zero(self) -> None:
+        """
+        Assumes symforce.set_epsilon_to_number works.
+
+        Tests:
+            symforce.set_epsilon_to_zero
+        """
+        clear_symforce()
+        with self.subTest(msg="Test set_epsilon_to_zero()"):
+            import symforce
+
+            symforce.set_epsilon_to_number(4.4)
+            symforce.set_epsilon_to_zero()
+            import symforce.symbolic as sf
+
+            self.assertEqual(0.0, sf.epsilon())
+
+        clear_symforce()
+        with self.subTest(msg="Test function properly raises AlreadyUsedEpsilon exception"):
+            import symforce
+
+            with self.assertRaises(symforce.AlreadyUsedEpsilon):
+                import symforce.symbolic as sf
+
+                sf.epsilon()
+                symforce.set_epsilon_to_zero()
+
+    def test_set_epsilon_to_symbol(self) -> None:
+        """
+        Assumes symforce.set_epsilon_to_number works.
+
+        Tests:
+            symforce.set_epsilon_to_symbol
+        """
+        clear_symforce()
+        with self.subTest(msg="Test set_epsilon_to_symbol()"):
+            import symforce
+
+            symforce.set_epsilon_to_number(4.4)
+            symforce.set_epsilon_to_symbol()
+            import symforce.symbolic as sf
+
+            self.assertEqual(sf.Symbol("epsilon"), sf.epsilon())
+
+        clear_symforce()
+        with self.subTest(msg="Test set_epsilon_to_symbol(name)"):
+            import symforce
+
+            symforce.set_epsilon_to_number(4.4)
+            symforce.set_epsilon_to_symbol(name="alpha")
+            import symforce.symbolic as sf
+
+            self.assertEqual(sf.Symbol("alpha"), sf.epsilon())
+
+        clear_symforce()
+        with self.subTest(msg="Test function properly raises AlreadyUsedEpsilon exception"):
+            import symforce
+
+            with self.assertRaises(symforce.AlreadyUsedEpsilon):
+                import symforce.symbolic as sf
+
+                sf.epsilon()
+                symforce.set_epsilon_to_number()
+
+    def test_set_epsilon_to_number(self) -> None:
+        """
+        Tests:
+            symforce.set_epsilon_to_number
+        """
+        clear_symforce()
+        with self.subTest(msg="Test set_epsilon_to_number()"):
+            import symforce
+
+            symforce.set_epsilon_to_number()
+            import symforce.symbolic as sf
+
+            self.assertEqual(sf.numeric_epsilon, sf.epsilon())
+
+        clear_symforce()
+        with self.subTest(msg="Test set_epsilon_to_number(value)"):
+            import symforce
+
+            symforce.set_epsilon_to_number(value=4.4)
+            import symforce.symbolic as sf
+
+            self.assertEqual(4.4, sf.epsilon())
+
+        clear_symforce()
+        with self.subTest(msg="Test function properly raises AlreadyUsedEpsilon exception"):
+            import symforce
+
+            with self.assertRaises(symforce.AlreadyUsedEpsilon):
+                import symforce.symbolic as sf
+
+                sf.epsilon()
+                symforce.set_epsilon_to_symbol()
+
+
+if __name__ == "__main__":
+    TestCase.main()