Merge branch 'u/dkrenn/symbolic-subring' of trac.sagemath.org:sage in…

…to coerce/inverse-action

* 'u/dkrenn/symbolic-subring' of trac.sagemath.org:sage: (36 commits)
  correct parent of result of an_element
  rename only_constants --> no_variables
  module description of subring
  docstring of SR.subring
  typo in docstring
  change ValueError to TypeError to make everything work with SR as it should
  simplify a doctest
  subring in index.rst
  minor docstring rewriting of factory
  write doctests for coercions, common_parent, pushout
  extend _coerce_map_from_ in rejecting-subring
  write workaround for #19231
  SR: coercion from subrings
  write code for SR.subring
  remove unnecessary import
  write _apply_functor
  write coerce_map_from
  write an_element
  fix element constructor
  rejecting functor
  ...

src/doc/en/reference/calculus/index.rst

@@ -11,6 +11,7 @@ Symbolic Calculus
    sage/calculus/calculus
    sage/symbolic/units
    sage/symbolic/ring
+   sage/symbolic/subring
    sage/symbolic/function
    sage/symbolic/function_factory
    sage/calculus/functional

src/sage/symbolic/ring.pyx

@@ -131,6 +131,15 @@ cdef class SymbolicRing(CommutativeRing):
             6
             sage: SR(5)-True
             4
+
+        TESTS::
+
+            sage: SR.has_coerce_map_from(SR.subring(accepting_variables=('a',)))
+            True
+            sage: SR.has_coerce_map_from(SR.subring(rejecting_variables=('r',)))
+            True
+            sage: SR.has_coerce_map_from(SR.subring(no_variables=True))
+            True
         """
         if isinstance(R, type):
             if R in [int, float, long, complex, bool]:
@@ -167,6 +176,8 @@ cdef class SymbolicRing(CommutativeRing):
 
             from sage.interfaces.maxima import Maxima
 
+            from subring import GenericSymbolicSubring
+
             if ComplexField(mpfr_prec_min()).has_coerce_map_from(R):
                 # Anything with a coercion into any precision of CC
 
@@ -185,6 +196,8 @@ cdef class SymbolicRing(CommutativeRing):
                 return True
             elif isinstance(R, (Maxima, PariInstance)):
                 return False
+            elif isinstance(R, GenericSymbolicSubring):
+                return True
 
     def _element_constructor_(self, x):
         """
@@ -281,7 +294,6 @@ cdef class SymbolicRing(CommutativeRing):
             (<function mul_vararg at 0x...>, [x^5, log(y), 3])
         """
         cdef GEx exp
-
         if is_Expression(x):
             if (<Expression>x)._parent is self:
                 return x
@@ -829,6 +841,100 @@ cdef class SymbolicRing(CommutativeRing):
 
         return _the_element.subs(d, **kwds)
 
+    def subring(self, *args, **kwds):
+        r"""
+        Create a subring of this symbolic ring.
+
+        INPUT:
+
+        Choose one of the following keywords to create a subring.
+
+        - ``accepting_variables`` (default: ``None``) -- a tuple or other
+          iterable of variables. If specified, then a symbolic subring of
+          expressions in only these variables is created.
+
+        - ``rejecting_variables`` (default: ``None``) -- a tuple or other
+          iterable of variables. If specified, then a symbolic subring of
+          expressions in variables distinct to these variables is
+          created.
+
+        - ``no_variables`` (default: ``False``) -- a boolean. If set,
+          then a symbolic subring of constant expressions (i.e.,
+          expressions without a variable) is created.
+
+        OUTPUT:
+
+        A ring.
+
+        EXAMPLES:
+
+        Let us create a couple of symbolic variables first::
+
+            sage: V = var('a, b, r, s, x, y')
+
+        Now we create a symbolic subring only accepting expressions in
+        the variables `a` and `b`::
+
+            sage: A = SR.subring(accepting_variables=(a, b)); A
+            Symbolic Subring accepting the variables a, b
+
+        An element is
+        ::
+
+            sage: A.an_element()
+            a
+
+        From our variables in `V` the following are valid in `A`::
+
+            sage: tuple(v for v in V if v in A)
+            (a, b)
+
+        Next, we create a symbolic subring rejecting expressions with
+        given variables::
+
+            sage: R = SR.subring(rejecting_variables=(r, s)); R
+            Symbolic Subring rejecting the variables r, s
+
+        An element is
+        ::
+
+            sage: R.an_element()
+            some_variable
+
+        From our variables in `V` the following are valid in `R`::
+
+            sage: tuple(v for v in V if v in R)
+            (a, b, x, y)
+
+        We have a third kind of subring, namely the subring of
+        symbolic constants::
+
+            sage: C = SR.subring(no_variables=True); C
+            Symbolic Constants Subring
+
+        Note that this subring can be considered as a special accepting
+        subring; one without any variables.
+
+        An element is
+        ::
+
+            sage: C.an_element()
+            I*pi*e
+
+        None of our variables in `V` is valid in `C`::
+
+            sage: tuple(v for v in V if v in C)
+            ()
+
+        .. SEEALSO::
+
+            :doc:`subring`
+        """
+        if self is not SR:
+            raise NotImplementedError('Cannot create subring of %s.' % (self,))
+        from subring import SymbolicSubring
+        return SymbolicSubring(*args, **kwds)
+
 SR = SymbolicRing()
 
 cdef unsigned sage_domain_to_ginac_domain(object domain) except -1: