Merge branch 'u/saraedum/ticket/15898' of git://trac.sagemath.org/sage into ticket/15898-DirichletGroup_unique

Conflicts:
	src/sage/modular/dirichlet.py

Author: pjbruin

src/sage/modular/dirichlet.py

@@ -47,10 +47,14 @@
 
 -  Craig Citro (2008-02-16): speed up __call__ method for
    Dirichlet characters, miscellaneous fixes
+
+-  Julian Rueth (2014-03-06): use UniqueFactory to cache DirichletGroups
+
 """
 
 ########################################################################
 #       Copyright (C) 2004,2005,2006 William Stein <[email protected]>
+#                     2014 Julian Rueth <[email protected]>
 #
 #  Distributed under the terms of the GNU General Public License (GPL)
 #
@@ -78,6 +82,7 @@
 from sage.rings.arith                       import binomial, bernoulli
 from sage.structure.element                 import MultiplicativeGroupElement
 from sage.structure.sequence                import Sequence
+from sage.structure.factory                 import UniqueFactory
 
 def trivial_character(N, base_ring=rings.RationalField()):
     r"""
@@ -1580,55 +1585,41 @@ def element(self):
             return v
 
 
-_cache = {}
-def DirichletGroup(modulus, base_ring=None, zeta=None, zeta_order=None,
-                   names=None, integral=False):
+class DirichletGroupFactory(UniqueFactory):
     r"""
-    The group of Dirichlet characters modulo `N` with values in
-    the subgroup `\langle \zeta_n\rangle` of the
-    multiplicative group of the ``base_ring``. If the
-    base_ring is omitted then we use `\QQ(\zeta_n)`,
-    where `n` is the exponent of
-    `(\ZZ/N\ZZ)^*`. If `\zeta` is omitted
-    then we compute and use a maximal-order zeta in base_ring, if
-    possible.
+    The group of Dirichlet characters modulo `N` with values in the subgroup
+    `\langle \zeta_n\rangle` of the multiplicative group of the ``base_ring``.
+    If ``base_ring`` is omitted then we use `\QQ(\zeta_n)`, where `n` is the
+    exponent of `(\ZZ/N\ZZ)^*`. If `\zeta` is omitted then we compute and use a
+    maximal-order zeta in ``base_ring``, if possible.
 
     INPUT:
 
+    - ``N`` - an integer
 
-    -  ``modulus`` - int
-
-    -  ``base_ring`` - Ring (optional), where characters
-       take their values (should be an integral domain).
+    - ``base_ring`` - a ring (optional), where characters take their values
+      (should be an integral domain)
 
-    -  ``zeta`` - Element (optional), element of
-       base_ring; zeta is a root of unity
+    - ``zeta`` - an element (optional), a root of unity in ``base_ring``
 
-    -  ``zeta_order`` - int (optional), the order of zeta
+    - ``zeta_order`` - an integer (optional), the order of zeta
 
-    -  ``names`` - ignored (needed so G.... =
-       DirichletGroup(...) notation works)
-
-    -  ``integral`` - boolean (default:
-       ``False``). If ``True``, return the group
-       with base_ring the ring of integers in the smallest choice of
-       CyclotomicField. Ignored if base_ring is not
-       ``None``.
+    - ``names`` - ignored (needed so ``G.... = DirichletGroup(...)`` notation
+      works)
 
+    - ``integral`` - a boolean (default: ``False``). If ``True``, return the
+      group with ``base_ring`` the ring of integers in the smallest choice of
+      :meth:`sage.rings.number_field.number_field.CyclotomicField`. Ignored if
+      ``base_ring`` is not ``None``.
 
     OUTPUT:
 
-
-    -  ``DirichletGroup`` - a group of Dirichlet
-       characters.
-
+    a group of Dirichlet characters
 
     EXAMPLES:
 
     The default base ring is a cyclotomic field of order the exponent
-    of `(\ZZ/N\ZZ)^*`.
-
-    ::
+    of `(\ZZ/N\ZZ)^*`::
 
         sage: DirichletGroup(20)
         Group of Dirichlet characters of modulus 20 over Cyclotomic Field of order 4 and degree 2
@@ -1650,13 +1641,13 @@ def DirichletGroup(modulus, base_ring=None, zeta=None, zeta_order=None,
         [Dirichlet character modulo 20 of conductor 1 mapping 11 |--> 1, 17 |--> 1, Dirichlet character modulo 20 of conductor 4 mapping 11 |--> -1, 17 |--> 1, Dirichlet character modulo 20 of conductor 5 mapping 11 |--> 1, 17 |--> -1, Dirichlet character modulo 20 of conductor 20 mapping 11 |--> -1, 17 |--> -1]
 
     Next we construct the group of Dirichlet character mod 20, but with
-    values in Q(zeta_n)::
+    values in `\QQ(\zeta_n)`::
 
         sage: G = DirichletGroup(20)
         sage: G.1
         Dirichlet character modulo 20 of conductor 5 mapping 11 |--> 1, 17 |--> zeta4
 
-    We next compute several invariants of G::
+    We next compute several invariants of ``G``::
 
         sage: G.gens()
         (Dirichlet character modulo 20 of conductor 4 mapping 11 |--> -1, 17 |--> 1, Dirichlet character modulo 20 of conductor 5 mapping 11 |--> 1, 17 |--> zeta4)
@@ -1668,9 +1659,7 @@ def DirichletGroup(modulus, base_ring=None, zeta=None, zeta_order=None,
         4
 
     In this example we create a Dirichlet character with values in a
-    number field. We have to give zeta, but not its order.
-
-    ::
+    number field. We have to give ``zeta``, but not its order::
 
         sage: R.<x> = PolynomialRing(QQ)
         sage: K.<a> = NumberField(x^4 + 1)
@@ -1691,18 +1680,14 @@ def DirichletGroup(modulus, base_ring=None, zeta=None, zeta_order=None,
         sage: loads(G.dumps()) == G
         True
 
-    We compute a Dirichlet group over a large prime field.
-
-    ::
+    We compute a Dirichlet group over a large prime field::
 
         sage: p = next_prime(10^40)
         sage: g = DirichletGroup(19, GF(p)); g
         Group of Dirichlet characters of modulus 19 over Finite Field of size 10000000000000000000000000000000000000121
 
     Note that the root of unity has small order, i.e., it is not the
-    largest order root of unity in the field.
-
-    ::
+    largest order root of unity in the field::
 
         sage: g.zeta_order()
         2
@@ -1732,42 +1717,98 @@ def DirichletGroup(modulus, base_ring=None, zeta=None, zeta_order=None,
         Group of Dirichlet characters of modulus 60 over Maximal Order in Cyclotomic Field of order 4 and degree 2
         sage: parent(DirichletGroup(60, integral=True).gens()[2].values_on_gens()[2])
         Maximal Order in Cyclotomic Field of order 4 and degree 2
+
+    TESTS:
+
+    Dirichlet groups are cached, creating two groups with the same parameters
+    yields the same object::
+
+        sage: DirichletGroup(60) is DirichletGroup(60)
+        True
+
     """
-    modulus = rings.Integer(modulus)
+    def create_key(self, N, base_ring=None, zeta=None, zeta_order=None, names=None, integral=False):
+        """
+        Create a key that uniquely determines a Dirichlet group.
 
-    if base_ring is None:
-        if not (zeta is None and zeta_order is None):
-            raise ValueError("zeta and zeta_order must be None if base_ring not specified.")
-        e = rings.IntegerModRing(modulus).unit_group_exponent()
-        base_ring = rings.CyclotomicField(e)
-        if integral:
-            base_ring = base_ring.ring_of_integers()
+        TESTS::
 
-    if not is_Ring(base_ring):
-        raise TypeError("base_ring (=%s) must be a ring"%base_ring)
+            sage: DirichletGroup.create_key(60)
+            (Cyclotomic Field of order 4 and degree 2, 60, zeta4, 4)
 
-    if zeta is None:
-        e = rings.IntegerModRing(modulus).unit_group_exponent()
-        try:
-            zeta = base_ring.zeta(e)
+        An example to illustrate that ``base_ring`` is a part of the key::
+
+            sage: k = DirichletGroup.create_key(2, base_ring=QQ); k
+            (Rational Field, 2, 1, 1)
+            sage: l = DirichletGroup.create_key(2, base_ring=CC); l
+            (Complex Field with 53 bits of precision, 2, 1.00000000000000, 1)
+            sage: k == l
+            False
+            sage: G = DirichletGroup.create_object(None, k); G
+            Group of Dirichlet characters of modulus 2 over Rational Field
+            sage: H = DirichletGroup.create_object(None, l); H
+            Group of Dirichlet characters of modulus 2 over Complex Field with 53 bits of precision
+            sage: G == H
+            False
+
+        If ``base_ring`` was not be a part of the key, the keys would compare
+        equal and the caching would be broken::
+
+            sage: k = k[1:]; k
+            (2, 1, 1)
+            sage: l = l[1:]; l
+            (2, 1.00000000000000, 1)
+            sage: k == l
+            True
+            sage: DirichletGroup(2, base_ring=QQ) is DirichletGroup(2, base_ring=CC)
+            False
+
+        """
+        modulus = rings.Integer(N)
+
+        if base_ring is None:
+            if not (zeta is None and zeta_order is None):
+                raise ValueError, "zeta and zeta_order must be None if base_ring not specified."
+            e = rings.IntegerModRing(modulus).unit_group_exponent()
+            base_ring = rings.CyclotomicField(e)
+            if integral:
+                base_ring = base_ring.ring_of_integers()
+
+        if not is_Ring(base_ring):
+            raise TypeError, "base_ring (=%s) must be a ring"%base_ring
+
+        if zeta is None:
+            e = rings.IntegerModRing(modulus).unit_group_exponent()
+            try:
+                zeta = base_ring.zeta(e)
+                zeta_order = zeta.multiplicative_order()
+            except (TypeError, ValueError, ArithmeticError):
+                zeta = base_ring.zeta(base_ring.zeta_order())
+                n = zeta.multiplicative_order()
+                zeta_order = arith.GCD(e,n)
+                zeta = zeta**(n//zeta_order)
+
+        elif zeta_order is None:
             zeta_order = zeta.multiplicative_order()
-        except (TypeError, ValueError, ArithmeticError):
-            zeta = base_ring.zeta(base_ring.zeta_order())
-            n = zeta.multiplicative_order()
-            zeta_order = arith.GCD(e,n)
-            zeta = zeta**(n//zeta_order)
-
-    elif zeta_order is None:
-        zeta_order = zeta.multiplicative_order()
-
-    key = (base_ring, modulus, zeta, zeta_order)
-    if key in _cache:
-        x = _cache[key]()
-        if not x is None: return x
-
-    R = DirichletGroup_class(modulus, zeta, zeta_order)
-    _cache[key] = weakref.ref(R)
-    return R
+
+        return (base_ring, modulus, zeta, zeta_order)
+
+    def create_object(self, version, key, **extra_args):
+        """
+        Create the object from the key (extra arguments are ignored). This is
+        only called if the object was not found in the cache.
+
+        TESTS::
+
+            sage: K = CyclotomicField(4)
+            sage: DirichletGroup.create_object(None, (K, 60, K.gen(), 4))
+            Group of Dirichlet characters of modulus 60 over Cyclotomic Field of order 4 and degree 2
+
+        """
+        base_ring, modulus, zeta, zeta_order = key
+        return DirichletGroup_class(modulus, zeta, zeta_order)
+
+DirichletGroup = DirichletGroupFactory("DirichletGroup")
 
 def is_DirichletGroup(x):
     """