Add documentation and test for ga.ReciprocalFrame

Also deprecates passing `mode="nonsense"`.

Author: eric-wieser

galgebra/ga.py

@@ -1951,6 +1951,17 @@ def connection(self, rbase, key_base, mode, left):
         return C
 
     def ReciprocalFrame(self, basis, mode='norm'):
+        """
+        Compute the reciprocal frame of a set of vectors
+
+        The `mode` argument must be either:
+
+        * ``"norm"``, indicating the reciprocal vectors should be normalized
+          such that their product with the input vectors is 1
+        * ``"append"``, indicating that instead of normalizing, the
+          normalization coefficient should be appended to the returned tuple.
+          One can divide by this coefficient to normalize the vectors.
+        """
         dim = len(basis)
 
         indexes = tuple(range(dim))
@@ -1983,11 +1994,17 @@ def ReciprocalFrame(self, basis, mode='norm'):
             rbasis.append(recpv)
             sgn = -sgn
 
-        if mode != 'norm':
-            rbasis.append(E_sq)
-        else:
+        if mode == 'norm':
             for i in range(dim):
                 rbasis[i] = rbasis[i] / E_sq
+        else:
+            if mode != 'append':
+                # galgebra 0.5.0
+                warnings.warn(
+                    "Mode {!r} not understood, falling back to {!r}  but this "
+                    "is deprecated".format(mode, 'append'),
+                    DeprecationWarning, stacklevel=2)
+            rbasis.append(E_sq)
 
         return tuple(rbasis)
 

test/test_test.py

@@ -363,6 +363,33 @@ def test_extracting_vectors_from_conformal_2_blade(self):
         aB = a|B
         assert str(aB) == '-(P2.a)*P1 + (P1.a)*P2'
 
+    def test_ReciprocalFrame(self):
+        ga, *basis = Ga.build('e*u|v|w')
+
+        r_basis = ga.ReciprocalFrame(basis)
+
+        for i, base in enumerate(basis):
+            for r_i, r_base in enumerate(r_basis):
+                if i == r_i:
+                    assert (base | r_base).simplify() == 1
+                else:
+                    assert (base | r_base).simplify() == 0
+
+    def test_ReciprocalFrame_append(self):
+        ga, *basis = Ga.build('e*u|v|w')
+        *r_basis, E_sq = ga.ReciprocalFrame(basis, mode='append')
+
+        for i, base in enumerate(basis):
+            for r_i, r_base in enumerate(r_basis):
+                if i == r_i:
+                    assert (base | r_base).simplify() == E_sq
+                else:
+                    assert (base | r_base).simplify() == 0
+
+        # anything that isn't 'norm' means 'append', but this is deprecated
+        with pytest.warns(DeprecationWarning):
+            assert ga.ReciprocalFrame(basis, mode='nonsense') = (*r_basis, E_sq)
+
     def test_reciprocal_frame_test(self):
 
         g = '1 # #,'+ \