Ticket #7980: trac_7980-multiple-realizations-nt.patch

File trac_7980-multiple-realizations-nt.patch, 62.0 KB (added by nthiery, 8 years ago)
  • doc/en/reference/categories.rst

    # HG changeset patch
    # User Nicolas M. Thiery <nthiery@users.sf.net>
    # Date 1331915772 -3600
    # Node ID ce7273e0b8b822267857e5eb8f219fd4c25b8687
    # Parent  4f81b7090dfec820b2a9e8576aceb1ade05492cb
    #7980: Implement generic support for parents with (multiple) realizations
    * * *
    TODO:
    
     - Use bindable classes
     - seealso w.r.t. SEEALSO
     - Bases ou Realizations dans l'exemple?
    
    diff --git a/doc/en/reference/categories.rst b/doc/en/reference/categories.rst
    a b Functorial constructions 
    3333   sage/categories/subobjects
    3434   sage/categories/isomorphic_objects
    3535
     36   sage/categories/realizations
     37   sage/categories/with_realizations
     38
     39
    3640Categories
    3741==========
    3842
    Examples of parents using categories 
    157161   sage/categories/examples/semigroups
    158162   sage/categories/examples/semigroups_cython
    159163   sage/categories/examples/sets_cat
     164   sage/categories/examples/with_realizations
    160165
    161166Miscellaneous
    162167=============
  • sage/categories/all.py

    diff --git a/sage/categories/all.py b/sage/categories/all.py
    a b  
    1 from category import    is_Category, Category, HomCategory, AbstractCategory
     1from category import    is_Category, Category, HomCategory
    22
    33from category_types import(
    44                        Elements,
    from morphism import Morphism, is_Morphi 
    2222
    2323from basic import *
    2424
     25from realizations import Realizations
     26
    2527from g_sets import GSets
    2628from pointed_sets import PointedSets
    2729
  • sage/categories/category.py

    diff --git a/sage/categories/category.py b/sage/categories/category.py
    a b A parent ``P`` is in a category ``C`` if 
    9595#                  http://www.gnu.org/licenses/
    9696#*****************************************************************************
    9797
    98 from sage.misc.abstract_method import abstract_methods_of_class
     98from sage.misc.abstract_method import abstract_method, abstract_methods_of_class
    9999from sage.misc.lazy_attribute import lazy_attribute
    100100from sage.misc.cachefunc import cached_method, cached_function
    101101#from sage.misc.misc import attrcall
    class Category(UniqueRepresentation, Sag 
    718718         """
    719719         return category_graph([self])
    720720
     721    @abstract_method
     722    def super_categories(self):
     723        """
     724        Returns the immediate super categories of ``self``
     725
     726        EXAMPLES::
     727
     728            sage: Groups().super_categories()
     729            [Category of monoids]
     730            sage: Objects().super_categories()
     731            []
     732        """
     733
    721734    @cached_method
    722735    def _all_super_categories_raw(self):
    723736        """
    class Category(UniqueRepresentation, Sag 
    763776
    764777        EXAMPLES::
    765778
    766             sage: C = GradedHopfAlgebrasWithBasis(QQ).abstract_category(); C
    767             Category of abstract graded hopf algebras with basis over Rational Field
     779            sage: C = Rings(); C
     780            Category of rings
    768781            sage: C.all_super_categories()
    769             [Category of abstract graded hopf algebras with basis over Rational Field,
    770              Category of graded hopf algebras over Rational Field,
    771              Category of graded bialgebras over Rational Field,
    772              Category of graded algebras over Rational Field,
    773              Category of graded coalgebras over Rational Field,
    774              Category of graded modules over Rational Field,
    775              Category of hopf algebras over Rational Field,
    776              Category of bialgebras over Rational Field,
    777              Category of algebras over Rational Field,
    778              ...]
     782            [Category of rings,
     783             Category of rngs,
     784             Category of commutative additive groups,
     785             Category of semirings,
     786             Category of commutative additive monoids,
     787             Category of commutative additive semigroups,
     788             Category of additive magmas,
     789             Category of monoids,
     790             Category of semigroups,
     791             Category of magmas,
     792             Category of sets,
     793             Category of sets with partial maps,
     794             Category of objects]
     795
     796            sage: C.all_super_categories(proper = True)
     797            [Category of rngs,
     798             Category of commutative additive groups,
     799             Category of semirings,
     800             Category of commutative additive monoids,
     801             Category of commutative additive semigroups,
     802             Category of additive magmas,
     803             Category of monoids,
     804             Category of semigroups,
     805             Category of magmas,
     806             Category of sets,
     807             Category of sets with partial maps,
     808             Category of objects]
    779809        """
    780810        done = set()
    781811        linear_extension = []
    class Category(UniqueRepresentation, Sag 
    12061236        except AttributeError:
    12071237            return Category.join((category.hom_category() for category in self.super_categories()))
    12081238
    1209     def abstract_category(self):
    1210         r"""
    1211         An abstract parent is a parent which models an abstract
    1212         algebraic structure which has several concrete representations.
    1213 
    1214         This returns a mostly technical category which provides
    1215         support tools for handling the different representation, and
    1216         in particular the coercions between them.
    1217 
    1218         It can be manually specified by defining a class
    1219         AbstractCategory as a member of this category.
    1220 
    1221         Typically, ``FiniteDimensionalModulesWithBasis(QQ).abstract_category()``
    1222         will be in charge, whenever a coercion `\phi: A\mapsto B` is
    1223         registered, to register `\phi^{-1}` as coercion `B \mapsto A`
    1224         if there is none defined yet.
    1225 
    1226         This is the analog of the `*WithSeveralBases` categories in MuPAD-Combinat.
    1227 
    1228         TODO: find a better name!
    1229 
    1230         The hierarchy of all abstract categories is built in parallel
    1231         to that of their base categories, optimizing away those
    1232         categories which do not have an AbstractCategory.
    1233 
    1234         Design question: currently ``self.abstract_category()`` is a
    1235         subcategory of self by default. Is this desirable? For example,
    1236         ``Algebras(QQ).abstract_category()`` should definitely be a
    1237         subcategory of ``Algebras(QQ)``. On the other hand,
    1238         ``AlgebrasWithBasis(QQ).abstract_category()`` should be a
    1239         subcategory of ``Algebras(QQ)``, but not of
    1240         ``AlgebrasWithBasis(QQ)``. This is because
    1241         ``AlgebrasWithBasis(QQ)`` is specifying something about the
    1242         concrete representation.
    1243 
    1244         EXAMPLES::
    1245 
    1246             sage: Semigroups().abstract_category()
    1247             Category of semigroups
    1248             sage: C = GradedHopfAlgebrasWithBasis(QQ).abstract_category(); C
    1249             Category of abstract graded hopf algebras with basis over Rational Field
    1250             sage: C.all_super_categories()
    1251             [Category of abstract graded hopf algebras with basis over Rational Field,
    1252              Category of graded hopf algebras over Rational Field,
    1253              Category of graded bialgebras over Rational Field,
    1254              Category of graded algebras over Rational Field,
    1255              Category of graded coalgebras over Rational Field,
    1256              Category of graded modules over Rational Field,
    1257              Category of hopf algebras over Rational Field,
    1258              Category of bialgebras over Rational Field,
    1259              Category of algebras over Rational Field,
    1260              ...]
    1261 
    1262         """
    1263         if hasattr(self, "AbstractCategory"):
    1264             return self.AbstractCategory(self)
    1265         else:
    1266             return Category.join(([self]+[category.abstract_category() for category in self.super_categories()]))
    1267 
    12681239    def example(self, *args, **keywords):
    12691240        """
    12701241        Returns an object in this category. Most of the time, this is a parent.
    def category_graph(categories = None): 
    13691340    import sage.categories.all
    13701341    if categories is None:
    13711342        import all
    1372         abstract_classes_for_categories = [Category, HomCategory, AbstractCategory]
     1343        abstract_classes_for_categories = [Category, HomCategory]
    13731344        categories = [ cat.an_instance() for cat in sage.categories.all.__dict__.values() if isinstance(cat, type) and issubclass(cat, Category) and cat not in abstract_classes_for_categories ]
    13741345    cats = set()
    13751346    for category in categories:
    class HomCategory(Category): 
    14711442
    14721443
    14731444#############################################################
    1474 # Categories of abstract parents
    1475 #############################################################
    1476 
    1477 class AbstractCategory(Category):
    1478     """
    1479     An abstract base class for all categories of abstract parents
    1480 
    1481     See Category.abstract_category.
    1482 
    1483     Caveat: specifications subject to change shortly.
    1484     """
    1485     def __init__(self, category, name=None):
    1486         """
    1487         Initializes this AbstractCategory
    1488 
    1489         INPUT:
    1490 
    1491         - ``category`` -- the category of which this category forms the abstract category.
    1492         - ``name`` -- An optional name for this category.
    1493 
    1494         TESTS::
    1495 
    1496             sage: C = sage.categories.category.AbstractCategory(Sets())
    1497             sage: C
    1498             Category of abstract sets
    1499             sage: TestSuite(C).run()
    1500         """
    1501         Category.__init__(self, name)
    1502         self.base_category = category
    1503 
    1504     def _repr_(self):
    1505         """
    1506         String representation.
    1507 
    1508         EXAMPLES::
    1509 
    1510             sage: C = GradedHopfAlgebrasWithBasis(QQ).abstract_category(); C #indirect doctest
    1511             Category of abstract graded hopf algebras with basis over Rational Field
    1512         """
    1513         s = repr(self.base_category)
    1514         return s[:11]+" abstract"+s[11:]
    1515 
    1516 #    def construction(self):
    1517 #        return (attrcall("abstract_category"), self.base_category)
    1518 
    1519     @cached_method
    1520     def super_categories(self):
    1521         """
    1522         Returns the immediate super categories, as per :meth:`Category.super_categories`.
    1523 
    1524         EXAMPLES::
    1525 
    1526             sage: C = GradedHopfAlgebrasWithBasis(QQ).abstract_category()
    1527             sage: C.super_categories()
    1528             [Category of graded hopf algebras over Rational Field]
    1529         """
    1530         return Category.join(self.extra_super_categories() +
    1531                              [category.abstract_category()
    1532                               for category in self.base_category.super_categories()],
    1533                              as_list=True)
    1534     @cached_method
    1535     def extra_super_categories(self):
    1536         """
    1537         The super categories of self that are not derived from the
    1538         inheritance diagram of the base category, as a list.
    1539 
    1540         EXAMPLES::
    1541 
    1542             sage: C = GradedHopfAlgebrasWithBasis(QQ).abstract_category()
    1543             sage: C.extra_super_categories()
    1544             [Category of graded hopf algebras with basis over Rational Field]
    1545         """
    1546         return [self.base_category]
    1547 
    1548 
    1549 
    1550 #############################################################
    15511445# Join of several categories
    15521446#############################################################
    15531447
  • new file sage/categories/examples/with_realizations.py

    diff --git a/sage/categories/examples/with_realizations.py b/sage/categories/examples/with_realizations.py
    new file mode 100644
    - +  
     1r"""
     2Examples of parents endowed with multiple realizations
     3"""
     4#*****************************************************************************
     5#  Copyright (C) 2008-2009 Nicolas M. Thiery <nthiery at users.sf.net>
     6#
     7#  Distributed under the terms of the GNU General Public License (GPL)
     8#                  http://www.gnu.org/licenses/
     9#*****************************************************************************
     10
     11from sage.misc.cachefunc import cached_method
     12from sage.categories.all import Rings, Algebras, AlgebrasWithBasis
     13from sage.categories.realizations import Category_realization_of_parent
     14from sage.structure.unique_representation import UniqueRepresentation
     15from sage.structure.parent import Parent
     16from sage.sets.set import Set
     17from sage.combinat.free_module import CombinatorialFreeModule
     18from sage.combinat.subset import Subsets
     19
     20class SubsetAlgebra(UniqueRepresentation, Parent):
     21    r"""
     22    An example of parent endowed with several realizations
     23
     24    We consider an algebra `A(S)` whose bases are indexed by the
     25    subsets `s` of a given set `S`. We consider three natural basis of
     26    this algebra: ``F``, ``In``, and ``Out``. In the first basis, the
     27    product is given by the union of the indexing sets. That is, for any
     28    `s, t\subset S`
     29
     30    .. MATH::
     31
     32        F_s F_t  = F_{s\cup t}
     33
     34    The ``In`` basis and ``Out`` basis are defined respectively by:
     35
     36    .. MATH::
     37
     38        In_s  = \sum_{t\subset s} F_t
     39        \qquad\text{and}\qquad
     40        F_s   = \sum_{t\supset s} Out_t
     41
     42    Each such basis gives a realization of `A`, where the elements are
     43    represented by their expansion in this basis.
     44
     45    This parent, and its code, demonstrate how to implement this
     46    algebra and its three realizations, with coercions and mixed
     47    arithmetic between them.
     48
     49    .. SEEALSO::
     50
     51       - :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>`
     52
     53    EXAMPLES::
     54
     55        sage: A = Sets().WithRealizations().example(); A
     56        The subset algebra of {1, 2, 3} over Rational Field
     57
     58    The three bases of ``A``::
     59
     60        sage: F   = A.F()  ; F
     61        The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     62        sage: In  = A.In() ; In
     63        The subset algebra of {1, 2, 3} over Rational Field on the in basis
     64        sage: Out = A.Out(); Out
     65        The subset algebra of {1, 2, 3} over Rational Field on the out basis
     66
     67        sage: F.basis().list()
     68        [F[{}], F[{1}], F[{2}], F[{3}], F[{1, 2}], F[{1, 3}], F[{2, 3}], F[{1, 2, 3}]]
     69
     70    Some conversions::
     71
     72        sage: F(In.from_set(2,3))
     73        F[{}] + F[{2}] + F[{3}] + F[{2, 3}]
     74        sage: In(F.from_set(2,3))
     75        In[{}] - In[{2}] - In[{3}] + In[{2, 3}]
     76
     77        sage: Out(F.from_set(3))
     78        Out[{3}] + Out[{1, 3}] + Out[{2, 3}] + Out[{1, 2, 3}]
     79        sage: F(Out.from_set(3))
     80        F[{3}] - F[{1, 3}] - F[{2, 3}] + F[{1, 2, 3}]
     81
     82        sage: Out(In.from_set(2,3))
     83        Out[{}] + Out[{1}] + 2*Out[{2}] + 2*Out[{3}] + 2*Out[{1, 2}] + 2*Out[{1, 3}] + 4*Out[{2, 3}] + 4*Out[{1, 2, 3}]
     84
     85    We can now mix expressions::
     86
     87        sage: (1 + Out.from_set(1)) * In.from_set(2,3)
     88        Out[{}] + 2*Out[{1}] + 2*Out[{2}] + 2*Out[{3}] + 2*Out[{1, 2}] + 2*Out[{1, 3}] + 4*Out[{2, 3}] + 4*Out[{1, 2, 3}]
     89    """
     90
     91    def __init__(self, R, S):
     92        r"""
     93        EXAMPLES::
     94
     95            sage: from sage.categories.examples.with_realizations import SubsetAlgebra
     96            sage: A = SubsetAlgebra(QQ, Set((1,2,3))); A
     97            The subset algebra of {1, 2, 3} over Rational Field
     98            sage: Sets().WithRealizations().example() is A
     99            True
     100            sage: TestSuite(A).run()
     101        """
     102        assert(R in Rings())
     103        self._base = R # Won't be needed when CategoryObject won't override anymore base_ring
     104        self._S = S
     105        Parent.__init__(self, category = Algebras(R).WithRealizations())
     106
     107    # Could possibly go in Monoids.WithRealizations.ParentMethods
     108    def one(self):
     109        r"""
     110        EXAMPLES::
     111
     112            sage: A = Sets().WithRealizations().example(); A
     113            The subset algebra of {1, 2, 3} over Rational Field
     114            sage: A.one()
     115            F[{}]
     116            sage: A.one() is A.F().one()
     117            True
     118        """
     119        return self.F().one()
     120
     121    # Could possibly go in CommutativeAdditiveMonoids.WithRealizations.ParentMethods
     122    def zero(self):
     123        r"""
     124        EXAMPLES::
     125
     126            sage: A = Sets().WithRealizations().example(); A
     127            The subset algebra of {1, 2, 3} over Rational Field
     128            sage: A.zero()
     129            0
     130            sage: A.zero() is A.F().zero()
     131            True
     132        """
     133        return self.F().zero()
     134
     135    # Could be inherited from ParentWithBase?
     136    def base_ring(self):
     137        r"""
     138        EXAMPLES::
     139
     140            sage: A = Sets().WithRealizations().example(); A
     141            The subset algebra of {1, 2, 3} over Rational Field
     142            sage: A.base_ring()
     143            Rational Field
     144        """
     145        return self._base
     146
     147    def base_set(self):
     148        r"""
     149        EXAMPLES::
     150
     151            sage: A = Sets().WithRealizations().example(); A
     152            The subset algebra of {1, 2, 3} over Rational Field
     153            sage: A.base_set()
     154            {1, 2, 3}
     155        """
     156        return self._S
     157
     158    def indices(self):
     159        r"""
     160        EXAMPLES::
     161
     162            sage: A = Sets().WithRealizations().example(); A
     163            The subset algebra of {1, 2, 3} over Rational Field
     164            sage: A.indices()
     165            Subsets of {1, 2, 3}
     166        """
     167        return Subsets(self._S)
     168
     169    def indices_cmp(self, x, y):
     170        r"""
     171        A comparison function on sets which gives a linear extension
     172        of the inclusion order.
     173
     174        INPUT:
     175
     176        - ``x``, ``y`` -- sets
     177
     178        EXAMPLES::
     179
     180            sage: A = Sets().WithRealizations().example(); A
     181            The subset algebra of {1, 2, 3} over Rational Field
     182            sage: sorted(A.indices(), A.indices_cmp)
     183            [{}, {1}, {2}, {3}, {1, 2}, {1, 3}, {2, 3}, {1, 2, 3}]
     184        """
     185        s = cmp(len(x), len(y))
     186        if s != 0:
     187            return s
     188        return cmp(list(x), list(y))
     189
     190    def supsets(self, set):
     191        r"""
     192        INPUT:
     193
     194        - ``set`` -- a subset of the base set `S` of ``self``
     195
     196        Returns all the subsets of `S` containing ``set``
     197
     198        EXAMPLES::
     199
     200            sage: A = Sets().WithRealizations().example(); A
     201            The subset algebra of {1, 2, 3} over Rational Field
     202            sage: A.supsets(Set((2,)))
     203            [{1, 2, 3}, {2, 3}, {1, 2}, {2}]
     204        """
     205        S = self.base_set()
     206        return list(S.difference(s) for s in Subsets(S.difference(set)))
     207
     208    def _repr_(self):
     209        r"""
     210        EXAMPLES::
     211
     212            sage: Sets().WithRealizations().example()   # indirect doctest
     213            The subset algebra of {1, 2, 3} over Rational Field
     214        """
     215        return "The subset algebra of %s over %s"%(self.base_set(), self.base_ring())
     216
     217    # Eventually it will be possible to put the class directly here if desired
     218    def F(self):
     219        """
     220        Returns the fundamental basis of ``self``
     221
     222        EXAMPLES::
     223
     224            sage: Sets().WithRealizations().example().F()
     225            The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     226        """
     227        return Fundamental(self)
     228
     229    def In(self):
     230        """
     231        Returns the in basis of ``self``
     232
     233        EXAMPLES::
     234
     235            sage: Sets().WithRealizations().example().In()
     236            The subset algebra of {1, 2, 3} over Rational Field on the in basis
     237        """
     238        return In(self)
     239
     240    def Out(self):
     241        """
     242        Returns the out basis of ``self``
     243
     244        EXAMPLES::
     245
     246            sage: Sets().WithRealizations().example().Out()
     247            The subset algebra of {1, 2, 3} over Rational Field on the out basis
     248        """
     249        return Out(self)
     250
     251    def __init_extra__(self):
     252        r"""
     253        Initializes the bases and change of bases of ``self``
     254
     255        TESTS::
     256
     257            sage: A = Sets().WithRealizations().example(); A
     258            The subset algebra of {1, 2, 3} over Rational Field
     259            sage: F, In, Out = A.realizations()
     260            sage: type(F.coerce_map_from(In))
     261            <class 'sage.categories.modules_with_basis.TriangularModuleMorphism'>
     262            sage: type(In.coerce_map_from(F))
     263            <class 'sage.categories.modules_with_basis.TriangularModuleMorphism'>
     264            sage: type(F.coerce_map_from(Out))
     265            <class 'sage.categories.modules_with_basis.TriangularModuleMorphism'>
     266            sage: type(Out.coerce_map_from(F))
     267            <class 'sage.categories.modules_with_basis.TriangularModuleMorphism'>
     268            sage: In.coerce_map_from(Out)
     269            Composite map:
     270              From: The subset algebra of {1, 2, 3} over Rational Field on the out basis
     271              To:   The subset algebra of {1, 2, 3} over Rational Field on the in basis
     272              Defn:   Generic morphism:
     273                      From: The subset algebra of {1, 2, 3} over Rational Field on the out basis
     274                      To:   The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     275                    then
     276                      Generic morphism:
     277                      From: The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     278                      To:   The subset algebra of {1, 2, 3} over Rational Field on the in basis
     279            sage: Out.coerce_map_from(In)
     280            Composite map:
     281              From: The subset algebra of {1, 2, 3} over Rational Field on the in basis
     282              To:   The subset algebra of {1, 2, 3} over Rational Field on the out basis
     283              Defn:   Generic morphism:
     284                      From: The subset algebra of {1, 2, 3} over Rational Field on the in basis
     285                      To:   The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     286                    then
     287                      Generic morphism:
     288                      From: The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     289                      To:   The subset algebra of {1, 2, 3} over Rational Field on the out basis
     290        """
     291        category   = self.Realizations()
     292        F   = self.F()
     293        In  = self.In()
     294        Out = self.Out()
     295
     296        In_to_F = In.module_morphism(F.sum_of_monomials * Subsets,
     297                                     codomain = F, category = category,
     298                                     triangular = 'upper', unitriangular = True,
     299                                     cmp = self.indices_cmp)
     300        In_to_F   .register_as_coercion()
     301        (~In_to_F).register_as_coercion()
     302
     303        F_to_Out = F.module_morphism(Out.sum_of_monomials * self.supsets,
     304                                     codomain = Out, category = category,
     305                                     triangular = 'lower', unitriangular = True,
     306                                     cmp = self.indices_cmp)
     307        F_to_Out   .register_as_coercion()
     308        (~F_to_Out).register_as_coercion()
     309
     310    # Alternatively, this category can be defined elsewhere, with just a link
     311    class Realizations(Category_realization_of_parent):
     312        r"""
     313        The category of the realizations of the subset algebra
     314        """
     315
     316        def super_categories(self):
     317            r"""
     318            EXAMPLES::
     319
     320                sage: A = Sets().WithRealizations().example(); A
     321                The subset algebra of {1, 2, 3} over Rational Field
     322                sage: C = A.Realizations(); C
     323                The category of realizations of The subset algebra of {1, 2, 3} over Rational Field
     324                sage: C.super_categories()
     325                [Join of Category of algebras over Rational Field and Category of realizations of sets, Category of algebras with basis over Rational Field]
     326            """
     327            R = self.base().base_ring()
     328            return [Algebras(R).Realizations(), AlgebrasWithBasis(R)]
     329
     330        class ParentMethods:
     331
     332            def from_set(self, *args):
     333                r"""
     334                Construct the monomial indexed by the set containing the
     335                elements passed as arguments.
     336
     337                EXAMPLES::
     338
     339                    sage: In = Sets().WithRealizations().example().In(); In
     340                    The subset algebra of {1, 2, 3} over Rational Field on the in basis
     341                    sage: In.from_set(2,3)
     342                    In[{2, 3}]
     343
     344                .. TODO:: rename to __getitem__ once ``Parent.__getitem__``
     345                   won't be anymore in the way::
     346
     347                        sage: In[2,3]     # todo: not implemented
     348                        In[{2, 3}]
     349                """
     350                return self.monomial(Set(args))
     351
     352            # This could go in some super category VectorSpaces().Realizations()
     353            def _repr_(self):
     354                r"""
     355                EXAMPLES::
     356
     357                    sage: Sets().WithRealizations().example().In()  # indirect doctest
     358                    The subset algebra of {1, 2, 3} over Rational Field on the in basis
     359                """
     360                return "%s %s"%(self.realization_of(), "on the %s basis"%(self._realization_name()))
     361
     362            @cached_method
     363            def one(self):
     364                r"""
     365                Returns the unit of this algebra.
     366
     367                This default implementation takes the unit in the
     368                fundamental basis, and coerces it in ``self``.
     369
     370                EXAMPLES::
     371
     372                    sage: A = Sets().WithRealizations().example(); A
     373                    The subset algebra of {1, 2, 3} over Rational Field
     374                    sage: In = A.In(); Out = A.Out()
     375                    sage: In.one()
     376                    In[{}]
     377                    sage: Out.one()
     378                    Out[{}] + Out[{1}] + Out[{2}] + Out[{3}] + Out[{1, 2}] + Out[{1, 3}] + Out[{2, 3}] + Out[{1, 2, 3}]
     379                """
     380                return self(self.realization_of().F().one())
     381
     382class Fundamental(CombinatorialFreeModule):
     383    r"""
     384    The class for the parent modeling the fundamental basis of the
     385    Subset Algebra
     386
     387    INPUT:
     388
     389    - ``A`` -- a parent with realization in :class:`SubsetAlgebra`
     390    """
     391
     392    def __init__(self, A):
     393        r"""
     394        EXAMPLES::
     395
     396            sage: A = Sets().WithRealizations().example(); A
     397            The subset algebra of {1, 2, 3} over Rational Field
     398            sage: F = A.F(); F
     399            The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     400            sage: TestSuite(F).run()
     401        """
     402        CombinatorialFreeModule.__init__(self,
     403            A.base_ring(), A.indices(),
     404            category=A.Realizations(), prefix='F', monomial_cmp=A.indices_cmp)
     405
     406    def product_on_basis(self, left, right):
     407        r"""
     408        Product of basis elements, as per :meth:`AlgebrasWithBasis.ParentMethods.product_on_basis`.
     409
     410        INPUT:
     411
     412        - ``left``, ``right`` -- sets indexing basis elements
     413
     414        EXAMPLES::
     415
     416            sage: F = Sets().WithRealizations().example().F(); F
     417            The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     418            sage: S = F.basis().keys(); S
     419            Subsets of {1, 2, 3}
     420            sage: F.product_on_basis(S([]), S([]))
     421            F[{}]
     422            sage: F.product_on_basis(S({1}), S({3}))
     423            F[{1, 3}]
     424            sage: F.product_on_basis(S({1,2}), S({2,3}))
     425            F[{1, 2, 3}]
     426        """
     427        return self.monomial( left.union(right)  )
     428
     429    def one_basis(self):
     430        r"""
     431        Returns the index of the basis element which is equal to '1'.
     432
     433        EXAMPLES::
     434
     435            sage: F = Sets().WithRealizations().example().F(); F
     436            The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     437            sage: F.one_basis()
     438            {}
     439            sage: F.one()
     440            F[{}]
     441        """
     442        return Set([])
     443
     444    one = AlgebrasWithBasis.ParentMethods.one
     445
     446class In(CombinatorialFreeModule):
     447    r"""
     448    The class for the parent modeling the ``In`` basis of the Subset
     449    Algebra
     450
     451    INPUT:
     452
     453    - ``A`` -- a parent with realization in :class:`SubsetAlgebra`
     454    """
     455
     456    def __init__(self, A):
     457        r"""
     458        EXAMPLES::
     459
     460            sage: In = Sets().WithRealizations().example().In(); In
     461            The subset algebra of {1, 2, 3} over Rational Field on the in basis
     462            sage: TestSuite(In).run()
     463        """
     464        CombinatorialFreeModule.__init__(self,
     465            A.base_ring(), A.indices(),
     466            category=A.Realizations(), prefix='In', monomial_cmp=A.indices_cmp)
     467
     468    # This won't be needed any more once #8878 will be closed
     469    def product(self, x, y):
     470        r"""
     471        Returns the product of ``x`` by ``y``
     472
     473        .. SEEALSO:: :meth:`Magmas.ParentMethods.product`
     474
     475        EXAMPLES::
     476
     477            sage: In = Sets().WithRealizations().example().In(); In
     478            The subset algebra of {1, 2, 3} over Rational Field on the in basis
     479            sage: x = In.an_element()
     480            sage: y = In.an_element()
     481            sage: In.product(x, y)
     482            -21*In[{}] - 2*In[{1}] + 19*In[{2}] + 53*In[{1, 2}]
     483
     484        .. TODO:: this method won't be needed once :trac:`8878` will be closed
     485        """
     486        F = self.realization_of().F()
     487        return self(F(x) * F(y))
     488
     489class Out(CombinatorialFreeModule):
     490    r"""
     491    The class for the parent modeling the `Out` basis of the Subset
     492    Algebra
     493
     494    INPUT:
     495
     496    - ``A`` -- a parent with realization in :class:`SubsetAlgebra`
     497    """
     498
     499    def __init__(self, A):
     500        r"""
     501        EXAMPLES::
     502
     503            sage: Out = Sets().WithRealizations().example().Out(); Out
     504            The subset algebra of {1, 2, 3} over Rational Field on the out basis
     505            sage: TestSuite(Out).run()
     506        """
     507        CombinatorialFreeModule.__init__(self,
     508            A.base_ring(), A.indices(),
     509            category=A.Realizations(), prefix='Out', monomial_cmp=A.indices_cmp)
     510
     511    def product(self, x, y):
     512        r"""
     513        Returns the product of ``x`` by ``y``
     514
     515        .. SEEALSO:: :meth:`Magmas.ParentMethods.product`
     516
     517        EXAMPLES::
     518
     519            sage: Out = Sets().WithRealizations().example().Out(); Out
     520            The subset algebra of {1, 2, 3} over Rational Field on the out basis
     521            sage: x = Out.an_element()
     522            sage: y = Out.an_element()
     523            sage: Out.product(x, y)
     524            Out[{}] + 4*Out[{1}] + 9*Out[{2}] + Out[{1, 2}]
     525
     526        .. TODO:: this method won't be needed once :trac:`8878` will be closed
     527        """
     528        F = self.realization_of().F()
     529        return self(F(x) * F(y))
  • sage/categories/graded_hopf_algebras_with_basis.py

    diff --git a/sage/categories/graded_hopf_algebras_with_basis.py b/sage/categories/graded_hopf_algebras_with_basis.py
    a b Graded Hopf algebras with basis 
    1010#******************************************************************************
    1111
    1212from category_types import Category_over_base_ring
    13 from sage.categories.all import AbstractCategory, GradedHopfAlgebras, HopfAlgebrasWithBasis, GradedBialgebrasWithBasis
     13from sage.categories.all import GradedHopfAlgebras, HopfAlgebrasWithBasis, GradedBialgebrasWithBasis
     14from sage.categories.with_realizations import WithRealizationsCategory
    1415from sage.misc.cachefunc import cached_method
    1516
    1617class GradedHopfAlgebrasWithBasis(Category_over_base_ring):
    class GradedHopfAlgebrasWithBasis(Catego 
    4647    class ElementMethods:
    4748        pass
    4849
    49     class AbstractCategory(AbstractCategory):
     50    class WithRealizations(WithRealizationsCategory):
     51
    5052        @cached_method
    5153        def super_categories(self):
    5254            """
    5355            EXAMPLES::
    5456
    55                 sage: GradedHopfAlgebrasWithBasis(QQ).abstract_category().super_categories()
     57                sage: GradedHopfAlgebrasWithBasis(QQ).WithRealizations().super_categories()
    5658                [Category of graded hopf algebras over Rational Field]
    5759
    5860            TESTS::
    5961
    60                 sage: TestSuite(GradedHopfAlgebrasWithBasis(QQ).abstract_category()).run()
     62                sage: TestSuite(GradedHopfAlgebrasWithBasis(QQ).WithRealizations()).run()
    6163            """
    6264            from sage.categories.graded_hopf_algebras import GradedHopfAlgebras
    63             R = self.base_category.base_ring()
     65            R = self.base_category().base_ring()
    6466            return [GradedHopfAlgebras(R)]
  • new file sage/categories/realizations.py

    diff --git a/sage/categories/realizations.py b/sage/categories/realizations.py
    new file mode 100644
    - +  
     1"""
     2Realizations Covariant Functorial Construction
     3
     4.. SEEALSO::
     5
     6    - :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>`
     7      for an introduction to *realizations* and *with realizations*.
     8    - :mod:`sage.categories.covariant_functorial_construction`
     9      for an introduction to covariant functorial constructions.
     10    - :mod:`sage.categories.examples.with_realizations` for an example.
     11"""
     12#*****************************************************************************
     13#  Copyright (C) 2010-2012 Nicolas M. Thiery <nthiery at users.sf.net>
     14#
     15#  Distributed under the terms of the GNU General Public License (GPL)
     16#                  http://www.gnu.org/licenses/
     17#*****************************************************************************
     18
     19from sage.categories.category import Category
     20from sage.categories.category_types import Category_over_base
     21from sage.categories.covariant_functorial_construction import RegressiveCovariantConstructionCategory
     22
     23class RealizationsCategory(RegressiveCovariantConstructionCategory):
     24    """
     25    An abstract base class for all categories of realizations category
     26
     27    Relization are implemented as
     28    :class:`~sage.categories.covariant_functorial_construction.RegressiveCovariantConstructionCategory`.
     29    See there for the documentation of how the various bindings such
     30    as ``Sets().Realizations()`` and ``P.Realizations()``, where ``P``
     31    is a parent, work.
     32
     33    .. SEEALSO:: :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>`
     34
     35    TESTS::
     36
     37        sage: Sets().Realizations
     38        <bound method Sets.Realizations of Category of sets>
     39        sage: Sets().Realizations()
     40        Category of realizations of sets
     41        sage: Sets().Realizations().super_categories()
     42        [Category of sets]
     43        sage: Groups().Realizations().super_categories()
     44        [Category of groups, Category of realizations of sets]
     45    """
     46
     47    _functor_category = "Realizations"
     48
     49def Realizations(self):
     50    """
     51    Return the category of realizations of the parent ``self`` or of objects
     52    of the category ``self``
     53
     54    INPUT:
     55
     56    - ``self`` -- a parent or a concrete category
     57
     58    .. NOTE:: this *function* is actually inserted as a *method* in the class
     59       :class:`~sage.categories.category.Category` (see
     60       :meth:`~sage.categories.category.Category.Realizations`). It is defined
     61       here for code locality reasons.
     62
     63    EXAMPLES:
     64
     65    The category of realizations of some algebra::
     66
     67        sage: Algebras(QQ).Realizations()
     68        Join of Category of algebras over Rational Field and Category of realizations of sets
     69
     70    The category of realizations of a given algebra::
     71
     72        sage: A = Sets().WithRealizations().example(); A
     73        The subset algebra of {1, 2, 3} over Rational Field
     74        sage: A.Realizations()
     75        The category of realizations of The subset algebra of {1, 2, 3} over Rational Field
     76
     77        sage: C = GradedHopfAlgebrasWithBasis(QQ).Realizations(); C
     78        Join of Category of graded hopf algebras with basis over Rational Field and Category of realizations of sets
     79        sage: C.super_categories()
     80        [Category of graded hopf algebras with basis over Rational Field, Category of realizations of sets]
     81
     82        sage: TestSuite(C).run()
     83
     84    .. SEEALSO::
     85
     86        - :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>`
     87        - :class:`ClasscallMetaclass`
     88
     89    .. TODO::
     90
     91        Add an optional argument to allow for::
     92
     93            sage: Realizations(A, category = Blahs()) # todo: not implemented
     94    """
     95    if isinstance(self, Category):
     96        return RealizationsCategory.category_of(self)
     97    else:
     98        return getattr(self.__class__, "Realizations")(self)
     99
     100Category.Realizations = Realizations
     101
     102class Category_realization_of_parent(Category_over_base):
     103    """
     104    An abstract base class for categories of all realizations of a given parent
     105
     106    INPUT:
     107
     108    - ``parent_with_realization`` -- a parent
     109
     110    .. SEEALSO:: :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>`
     111
     112    EXAMPLES::
     113
     114        sage: A = Sets().WithRealizations().example(); A
     115        The subset algebra of {1, 2, 3} over Rational Field
     116
     117    The role of this base class is to implement some technical goodies, like
     118    the binding ``A.Realizations()`` when a subclass ``Realizations`` is
     119    implemented as a nested class in ``A``
     120    (see the :mod:`code of the example <sage.categories.examples.with_realizations.SubsetAlgebra>`)::
     121
     122        sage: C = A.Realizations(); C
     123        The category of realizations of The subset algebra of {1, 2, 3} over Rational Field
     124
     125    as well as the name for that category.
     126
     127    TESTS::
     128
     129        sage: TestSuite(C).run()
     130    """
     131    @staticmethod
     132    def __classget__(cls, parent, owner):
     133        r"""
     134        Implements class binding
     135
     136        EXAMPLES:
     137
     138        Let `A` be an algebra with several realizations::
     139
     140            sage: A = Sets().WithRealizations().example(); A
     141            The subset algebra of {1, 2, 3} over Rational Field
     142
     143        This implements a hack allowing ``A.Realizations()`` to call
     144        ``A.__class__.Realizations(A)`` to construct the category of
     145        realizations of `A`::
     146
     147            sage: A.Realizations()
     148            The category of realizations of The subset algebra of {1, 2, 3} over Rational Field
     149
     150            sage: A.__class__.Realizations(A)
     151            The category of realizations of The subset algebra of {1, 2, 3} over Rational Field
     152
     153        As an intermediate step, this binds the method
     154        :func:`sage.categories.realizations.Realizations` to `A` so
     155        that introspection plays nicely::
     156
     157            sage: A.Realizations
     158            <bound method sage.categories.realizations.Realizations of The subset algebra of {1, 2, 3} over Rational Field>
     159
     160        .. SEEALSO::
     161            - :class:`ClasscallMetaclass`
     162            - :class:`Sets.WithRealizations`
     163        """
     164        if parent is None:
     165            return cls
     166        # From within a module, is there a shortcut to oneself?
     167        import sage.categories.realizations
     168        return Realizations.__get__(parent, sage.categories.realizations)
     169
     170    def __init__(self, parent_with_realization):
     171        """
     172        TESTS::
     173
     174            sage: from sage.categories.realizations import Category_realization_of_parent
     175            sage: A = Sets().WithRealizations().example(); A
     176            The subset algebra of {1, 2, 3} over Rational Field
     177            sage: C = A.Realizations(); C
     178            The category of realizations of The subset algebra of {1, 2, 3} over Rational Field
     179            sage: isinstance(C, Category_realization_of_parent)
     180            True
     181            sage: C.parent_with_realization
     182            The subset algebra of {1, 2, 3} over Rational Field
     183            sage: TestSuite(C).run()
     184        """
     185        Category_over_base.__init__(self, parent_with_realization)
     186        self.parent_with_realization = parent_with_realization
     187
     188    def _get_name(self):
     189        """
     190        Return a human readable string specifying which kind of bases this category is for
     191
     192        It is obtained by splitting and lower casing the last part of
     193        the class name.
     194
     195        EXAMPLES::
     196
     197            sage: from sage.categories.realizations import Category_realization_of_parent
     198            sage: class MultiplicativeBasesOnPrimitiveElements(Category_realization_of_parent):
     199            ...       pass
     200            sage: Sym = SymmetricFunctions(QQ); Sym.rename("Sym")
     201            sage: MultiplicativeBasesOnPrimitiveElements(Sym)._get_name()
     202            'multiplicative bases on primitive elements'
     203        """
     204        import re
     205        return re.sub(".[A-Z]", lambda s: s.group()[0]+" "+s.group()[1], self.__class__.__name__.split(".")[-1]).lower()
     206
     207    def _repr_(self):
     208        """
     209        EXAMPLES::
     210
     211            sage: from sage.categories.realizations import Category_realization_of_parent
     212            sage: class MultiplicativeBasesOnPrimitiveElements(Category_realization_of_parent):
     213            ...       pass
     214            ...
     215            sage: Sym = SymmetricFunctions(QQ); Sym.rename("Sym")
     216            sage: MultiplicativeBasesOnPrimitiveElements(Sym)     # indirect doctest
     217            The category of multiplicative bases on primitive elements of Sym
     218        """
     219        return "The category of %s of %s"%(self._get_name(), self.base())
  • sage/categories/sets_cat.py

    diff --git a/sage/categories/sets_cat.py b/sage/categories/sets_cat.py
    a b from sage.categories.subobjects import 
    2727from sage.categories.isomorphic_objects   import IsomorphicObjectsCategory
    2828from sage.categories.algebra_functor import AlgebrasCategory
    2929from sage.categories.cartesian_product import cartesian_product, CartesianProductsCategory
     30from sage.categories.realizations import RealizationsCategory, Category_realization_of_parent
     31from sage.categories.with_realizations import WithRealizationsCategory
    3032
    3133lazy_import('sage.sets.cartesian_product', 'CartesianProduct')
    3234
    class Sets(Category_singleton): 
    11111113            """
    11121114            from sage.categories.modules_with_basis import ModulesWithBasis
    11131115            return [ModulesWithBasis(self.base_ring())]
     1116
     1117    class WithRealizations(WithRealizationsCategory):
     1118
     1119        def extra_super_categories(self):
     1120            """
     1121            A set with multiple realizations is a facade parent
     1122
     1123            EXAMPLES::
     1124
     1125                sage: Sets().WithRealizations().extra_super_categories()
     1126                [Category of facade sets]
     1127                sage: Sets().WithRealizations().super_categories()
     1128                [Category of facade sets]
     1129            """
     1130            return [Sets().Facades()]
     1131
     1132        def example(self, base_ring = None, set = None):
     1133            r"""
     1134            Returns an example of set with multiple realizations, as
     1135            per :meth:`Category.example`.
     1136
     1137            EXAMPLES::
     1138
     1139                sage: Sets().WithRealizations().example()
     1140                The subset algebra of {1, 2, 3} over Rational Field
     1141
     1142                sage: Sets().WithRealizations().example(ZZ, Set([1,2]))
     1143                The subset algebra of {1, 2} over Integer Ring
     1144            """
     1145            from sage.rings.rational_field import QQ
     1146            from sage.sets.set import Set
     1147            if base_ring is None:
     1148                base_ring = QQ
     1149            if set is None:
     1150                set = Set([1,2,3])
     1151            from sage.categories.examples.with_realizations import SubsetAlgebra
     1152            return SubsetAlgebra(base_ring, set)
     1153
     1154
     1155        class ParentMethods:
     1156
     1157            def _test_with_realizations(self, **options):
     1158                r"""
     1159                Test that this parent with realizations is properly implemented
     1160
     1161                INPUT::
     1162
     1163                 - ``options`` -- any keyword arguments accepted by :meth:`_tester`.
     1164
     1165                EXAMPLES::
     1166
     1167                    sage: A = Sets().WithRealizations().example()
     1168                    sage: A._test_with_realizations()
     1169
     1170                See the documentation for :class:`TestSuite` for more information.
     1171                """
     1172                tester = self._tester(**options)
     1173                for R in self.realizations():
     1174                    tester.assert_(R in self.Realizations())
     1175                # Could check that there are coerce maps between any two realizations
     1176
     1177            @lazy_attribute
     1178            def _realizations(self):
     1179                """
     1180                This lazily initializes the attribute
     1181                ``_realizations`` the first time it is needed.
     1182
     1183                TESTS::
     1184
     1185                    sage: class MyParent(Parent):
     1186                    ...      pass
     1187                    sage: P = MyParent(category = Sets().WithRealizations())
     1188                    sage: P._realizations
     1189                    []
     1190                """
     1191                return []
     1192
     1193            def _register_realization(self, realization):
     1194                """
     1195                EXAMPLES::
     1196
     1197                    sage: A = Sets().WithRealizations().example(QQ[x]); A
     1198                    The subset algebra of {1, 2, 3} over Univariate Polynomial Ring in x over Rational Field
     1199                    sage: class ANewRealizationOfA(CombinatorialFreeModule):
     1200                    ...       pass
     1201                    sage: R = ANewRealizationOfA(A.base_ring(), A.F().basis().keys(), category = A.Realizations())
     1202                    sage: R in A.realizations()  # indirect doctest
     1203                    True
     1204
     1205                Note: the test above uses ``QQ[x]`` to not interfer with other tests
     1206                """
     1207                assert realization.realization_of() is self
     1208                self._realizations.append(realization)
     1209
     1210            def realizations(self):
     1211                """
     1212                Returns all the realizations of ``self`` that ``self`` is aware of.
     1213
     1214                EXAMPLES::
     1215
     1216                    sage: A = Sets().WithRealizations().example(); A
     1217                    The subset algebra of {1, 2, 3} over Rational Field
     1218                    sage: A.realizations()
     1219                    [The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis, The subset algebra of {1, 2, 3} over Rational Field on the in basis, The subset algebra of {1, 2, 3} over Rational Field on the out basis]
     1220
     1221                .. note::
     1222
     1223                    Constructing a parent ``P`` in the category
     1224                    ``A.Realizations()`` automatically adds ``P`` to
     1225                    this list by calling ``A._register_realization(A)``
     1226                """
     1227                return self._realizations
     1228
     1229            facade_for = realizations
     1230            """
     1231            Returns the parents ``self`` is a facade for, that is
     1232            the realizations of ``self``
     1233
     1234            EXAMPLES::
     1235
     1236                sage: A = Sets().WithRealizations().example(); A
     1237                The subset algebra of {1, 2, 3} over Rational Field
     1238                sage: A.facade_for()
     1239                [The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis, The subset algebra of {1, 2, 3} over Rational Field on the in basis, The subset algebra of {1, 2, 3} over Rational Field on the out basis]
     1240
     1241                sage: A = Sets().WithRealizations().example(); A
     1242                The subset algebra of {1, 2, 3} over Rational Field
     1243                sage: f = A.F().an_element(); f
     1244                F[{}] + 2*F[{1}] + 3*F[{2}] + F[{1, 2}]
     1245                sage: i = A.In().an_element(); i
     1246                In[{}] + 2*In[{1}] + 3*In[{2}] + In[{1, 2}]
     1247                sage: o = A.Out().an_element(); o
     1248                Out[{}] + 2*Out[{1}] + 3*Out[{2}] + Out[{1, 2}]
     1249                sage: f in A, i in A, o in A
     1250                (True, True, True)
     1251            """
     1252
     1253            # Do we really want this feature?
     1254            class Realizations(Category_realization_of_parent):
     1255
     1256                def super_categories(self):
     1257                    """
     1258                    EXAMPLES::
     1259
     1260                        sage: A = Sets().WithRealizations().example(); A
     1261                        The subset algebra of {1, 2, 3} over Rational Field
     1262                        sage: A.Realizations().super_categories()
     1263                        [Join of Category of algebras over Rational Field and Category of realizations of sets, Category of algebras with basis over Rational Field]
     1264                    """
     1265                    return [Sets().Realizations()]
     1266
     1267            def _an_element_(self):
     1268                """
     1269                Returns an element of some realization of ``self``
     1270
     1271                EXAMPLES::
     1272
     1273                    sage: A = Sets().WithRealizations().example(); A
     1274                    The subset algebra of {1, 2, 3} over Rational Field
     1275                    sage: A.an_element()        # indirect doctest
     1276                    F[{}] + 2*F[{1}] + 3*F[{2}] + F[{1, 2}]
     1277                """
     1278                return self.realizations()[0].an_element()
     1279
     1280            # TODO: maybe this could be taken care of by Sets.Facades()?
     1281            def __contains__(self, x):
     1282                r"""
     1283                Test whether ``x`` is in ``self``, that is if it is an
     1284                element of some realization of ``self``.
     1285
     1286                EXAMPLES::
     1287
     1288                    sage: A = Sets().WithRealizations().example(); A
     1289                    The subset algebra of {1, 2, 3} over Rational Field
     1290                    sage: A.an_element() in A
     1291                    True
     1292                    sage: A.In().an_element() in A
     1293                    True
     1294                    sage: A.F().an_element() in A
     1295                    True
     1296                    sage: A.Out().an_element() in A
     1297                    True
     1298                    sage: 1 in A
     1299                    True
     1300                    sage: QQ['x'].an_element() in A
     1301                    False
     1302                """
     1303                return any(x in realization for realization in self.realizations())
     1304
     1305    class Realizations(RealizationsCategory):
     1306
     1307        class ParentMethods:
     1308
     1309            def __init_extra__(self):
     1310                """
     1311                Registers ``self`` as a realization of ``self.realization_of``
     1312
     1313                TESTS::
     1314
     1315                    sage: A = Sets().WithRealizations().example()
     1316                    sage: A.realizations()    # indirect doctest
     1317                    [The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis,
     1318                     The subset algebra of {1, 2, 3} over Rational Field on the in basis,
     1319                     The subset algebra of {1, 2, 3} over Rational Field on the out basis]
     1320                """
     1321                self.realization_of()._register_realization(self)
     1322
     1323            @cached_method
     1324            def realization_of(self):
     1325                """
     1326                Returns the parent this is a realization of
     1327
     1328                EXAMPLES::
     1329
     1330                    sage: A = Sets().WithRealizations().example(); A
     1331                    The subset algebra of {1, 2, 3} over Rational Field
     1332                    sage: In = A.In(); In
     1333                    The subset algebra of {1, 2, 3} over Rational Field on the in basis
     1334                    sage: In.realization_of()
     1335                    The subset algebra of {1, 2, 3} over Rational Field
     1336                """
     1337                for category in self.categories():
     1338                    if isinstance(category, Category_realization_of_parent):
     1339                        return category.base()
     1340
     1341            def _realization_name(self):
     1342                """
     1343                Returns the name of this realization
     1344
     1345                In this default implementation, this is guessed from
     1346                the name of its class.
     1347
     1348                EXAMPLES::
     1349
     1350                    sage: A = Sets().WithRealizations().example(); A
     1351                    The subset algebra of {1, 2, 3} over Rational Field
     1352                    sage: In = A.In(); In
     1353                    The subset algebra of {1, 2, 3} over Rational Field on the in basis
     1354                    sage: In._realization_name()
     1355                    'in'
     1356
     1357                FIXME: Do we want ``In`` instead?
     1358                """
     1359                # The __base__ gets rid of the with_category
     1360                return self.__class__.__base__.__name__.lower()
     1361
     1362            def _repr_(self):
     1363                """
     1364                EXAMPLES::
     1365
     1366                    sage: A = Sets().WithRealizations().example(); A
     1367                    The subset algebra of {1, 2, 3} over Rational Field
     1368                    sage: In = A.In(); In
     1369                    The subset algebra of {1, 2, 3} over Rational Field on the in basis
     1370
     1371                In the example above, :meth:`repr` was overriden by
     1372                the category ``A.Realizations()``. We now add a new
     1373                (fake) realization which is not in
     1374                ``A.Realizations()`` to actually exercise this
     1375                method::
     1376
     1377                    sage: from sage.categories.realizations import Realizations
     1378                    sage: class Blah(Parent):
     1379                    ...       pass
     1380                    sage: P = Blah(category = Sets.WithRealizations.ParentMethods.Realizations(A))
     1381                    sage: P     # indirect doctest
     1382                    The subset algebra of {1, 2, 3} over Rational Field in the realization blah
     1383                """
     1384                return "%s in the realization %s"%(self.realization_of(), self._realization_name())
  • new file sage/categories/with_realizations.py

    diff --git a/sage/categories/with_realizations.py b/sage/categories/with_realizations.py
    new file mode 100644
    - +  
     1"""
     2With Realizations Covariant Functorial Construction
     3
     4.. SEEALSO::
     5
     6    - :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>`
     7      for an introduction to *realizations* and *with realizations*.
     8    - :mod:`sage.categories.covariant_functorial_construction`
     9      for an introduction to covariant functorial constructions.
     10"""
     11#*****************************************************************************
     12#  Copyright (C) 2010-2012 Nicolas M. Thiery <nthiery at users.sf.net>
     13#
     14#  Distributed under the terms of the GNU General Public License (GPL)
     15#                  http://www.gnu.org/licenses/
     16#*****************************************************************************
     17
     18from sage.categories.category import Category
     19from sage.categories.covariant_functorial_construction import RegressiveCovariantConstructionCategory
     20
     21def WithRealizations(self):
     22    """
     23    Returns the category of parents in ``self`` endowed with multiple realizations
     24
     25    INPUT:
     26
     27    - ``self`` -- a category
     28
     29    .. SEEALSO::
     30
     31        - the documentation and code
     32          (:mod:`sage.categories.examples.with_realizations`) of
     33          ``Sets().WithRealizations().example()`` for more on how to use and
     34          implement a parent with several realizations.
     35
     36        - :mod:`sage.categories.realizations`
     37
     38
     39    .. NOTE:: this *function* is actually inserted as a *method* in the class
     40       :class:`~sage.categories.category.Category` (see
     41       :meth:`~sage.categories.category.Category.WithRealizations`). It is defined
     42       here for code locality reasons.
     43
     44    EXAMPLES::
     45
     46        sage: Sets().WithRealizations()
     47        Category of sets with realizations
     48
     49    .. RUBRIC:: Parent with realizations
     50
     51    Let us now explain the concept of realizations. A *parent with
     52    realizations* is a facade parent (see :class:`Sets.Facades`)
     53    admitting multiple concrete realizations where its elements are
     54    represented. Consider for example an algebra `A` which admits
     55    several natural bases::
     56
     57        sage: A = Sets().WithRealizations().example(); A
     58        The subset algebra of {1, 2, 3} over Rational Field
     59
     60    For each such basis `B` one implements a parent `P_B` which
     61    realizes `A` with its elements represented by expanding them on
     62    the basis `B`::
     63
     64        sage: A.F()
     65        The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     66        sage: A.Out()
     67        The subset algebra of {1, 2, 3} over Rational Field on the out basis
     68        sage: A.In()
     69        The subset algebra of {1, 2, 3} over Rational Field on the in basis
     70
     71        sage: A.an_element()
     72        F[{}] + 2*F[{1}] + 3*F[{2}] + F[{1, 2}]
     73
     74    If `B` and `B'` are two bases, then the change of basis from `B`
     75    to `B'` is implemented by a canonical coercion between `P_B` and
     76    `P_{B'}`::
     77
     78        sage: F = A.F(); In = A.In(); Out = A.Out()
     79        sage: i = In.an_element(); i
     80        In[{}] + 2*In[{1}] + 3*In[{2}] + In[{1, 2}]
     81        sage: F(i)
     82        7*F[{}] + 3*F[{1}] + 4*F[{2}] + F[{1, 2}]
     83        sage: F.coerce_map_from(Out)
     84        Generic morphism:
     85          From: The subset algebra of {1, 2, 3} over Rational Field on the out basis
     86          To:   The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis
     87
     88    allowing for mixed arithmetic::
     89
     90        sage: (1 + Out.from_set(1)) * In.from_set(2,3)
     91        Out[{}] + 2*Out[{1}] + 2*Out[{2}] + 2*Out[{3}] + 2*Out[{1, 2}] + 2*Out[{1, 3}] + 4*Out[{2, 3}] + 4*Out[{1, 2, 3}]
     92
     93    In our example, there are three realizations::
     94
     95        sage: A.realizations()
     96        [The subset algebra of {1, 2, 3} over Rational Field on the fundamental basis,
     97         The subset algebra of {1, 2, 3} over Rational Field on the in basis,
     98         The subset algebra of {1, 2, 3} over Rational Field on the out basis]
     99
     100    The set of all realizations of `A`, together with the coercion morphisms
     101    is a category (whose class inherits from
     102    :class:`~sage.categories.realizations.Category_realization_of_parent`)::
     103
     104        sage: A.Realizations()
     105        The category of realizations of The subset algebra of {1, 2, 3} over Rational Field
     106
     107    The various parent realizing `A` belong to this category::
     108
     109        sage: A.F() in A.Realizations()
     110        True
     111
     112    `A` itself is in the category of algebras with realizations::
     113
     114        sage: A in Algebras(QQ).WithRealizations()
     115        True
     116
     117    The (mostly technical) ``WithRealizations`` categories are the
     118    analogs of the ``*WithSeveralBases`` categories in
     119    MuPAD-Combinat. They provide support tools for handling the
     120    different realizations and the morphisms between them.
     121
     122    Typically, ``FiniteDimensionalVectorSpaces(QQ).WithRealizations()``
     123    will eventually be in charge, whenever a coercion `\phi: A\mapsto B` is
     124    registered, to register `\phi^{-1}` as coercion `B \mapsto A`
     125    if there is none defined yet. To achieve this,
     126    ``FiniteDimensionalVectorSpaces`` would provide a nested class
     127    ``WithRealizations`` implementing the appropriate logic.
     128
     129    ``WithRealizations`` is a :mod:`regressive covariant functorial
     130    construction <sage.categories.covariant_functorial_construction>`.
     131    On our example, this simply means that `A` is automatically in the
     132    category of rings with realizations (covariance)::
     133
     134        sage: A in Rings().WithRealizations()
     135        True
     136
     137    and in the category of algebras (regressiveness)::
     138
     139        sage: A in Algebras(QQ)
     140        True
     141
     142    .. NOTE::
     143
     144        For ``C`` a category, ``C.WithRealizations()`` in fact calls
     145        ``sage.categories.with_realizations.Realizations(C)``. The
     146        later is responsible for building the hierarchy of the
     147        categories with realizations in parallel to that of their base
     148        categories, optimizing away those categories that do not
     149        provide a ``WithRealizations`` nested class. See
     150        :mod:`sage.categories.covariant_functorial_construction` for
     151        the technical details.
     152
     153    .. NOTE::
     154
     155        Design question: currently ``WithRealizations`` is a
     156        regressive construction. That is ``self.WithRealizations()``
     157        is a subcategory of ``self`` by default::
     158
     159            sage: Algebras(QQ).WithRealizations().super_categories()
     160            [Category of algebras over Rational Field, Category of sets with realizations]
     161
     162        Is this always desirable? For example,
     163        ``AlgebrasWithBasis(QQ).WithRealizations()`` should certainly
     164        be a subcategory of ``Algebras(QQ)``, but not of
     165        ``AlgebrasWithBasis(QQ)``. This is because
     166        ``AlgebrasWithBasis(QQ)`` is specifying something about the
     167        concrete realization.
     168
     169    TESTS::
     170
     171        sage: Semigroups().WithRealizations()
     172        Join of Category of semigroups and Category of sets with realizations
     173        sage: C = GradedHopfAlgebrasWithBasis(QQ).WithRealizations(); C
     174        Category of graded hopf algebras with basis over Rational Field with realizations
     175        sage: C.super_categories()
     176        [Category of graded hopf algebras over Rational Field]
     177        sage: C.all_super_categories()
     178        [Category of graded hopf algebras with basis over Rational Field with realizations,
     179         Category of graded hopf algebras over Rational Field,
     180         Category of graded bialgebras over Rational Field,
     181         Category of graded algebras over Rational Field,
     182         Category of graded coalgebras over Rational Field,
     183         Category of graded modules over Rational Field,
     184         Category of hopf algebras over Rational Field,
     185         Category of bialgebras over Rational Field,
     186         Category of algebras over Rational Field,
     187         ...]
     188
     189        sage: TestSuite(Semigroups().WithRealizations()).run()
     190
     191    """
     192    return WithRealizationsCategory.category_of(self)
     193
     194Category.WithRealizations = WithRealizations
     195
     196class WithRealizationsCategory(RegressiveCovariantConstructionCategory):
     197    """
     198    An abstract base class for all categories of parents with multiple
     199    realizations.
     200
     201    .. SEEALSO:: :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>`
     202
     203    The role of this base class is to implement some technical goodies, such
     204    as the name for that category.
     205    """
     206
     207    _functor_category = "WithRealizations"
     208
     209    def _repr_(self):
     210        """
     211        String representation.
     212
     213        EXAMPLES::
     214
     215            sage: C = GradedHopfAlgebrasWithBasis(QQ).WithRealizations(); C #indirect doctest
     216            Category of graded hopf algebras with basis over Rational Field with realizations
     217        """
     218        s = repr(self.base_category())
     219        return s+" with realizations"
     220
     221
  • sage/combinat/sf/sf.py

    diff --git a/sage/combinat/sf/sf.py b/sage/combinat/sf/sf.py
    a b class SymmetricFunctions(UniqueRepresent 
    3838
    3939    Sym is the unique free commutative graded connected
    4040    algebra, with one generator in each degree::
    41    
     41
    4242        sage: Sym.category()
    43         Category of abstract graded hopf algebras with basis over Rational Field
     43        Category of graded hopf algebras with basis over Rational Field with realizations
    4444
    4545    We use the Sage standard renaming idiom to get shorter outputs::
    4646
    class SymmetricFunctions(UniqueRepresent 
    236236        """
    237237        assert(R in Rings())
    238238        self._base = R # Won't be needed when CategoryObject won't override anymore base_ring
    239         Parent.__init__(self, category = GradedHopfAlgebrasWithBasis(R).abstract_category())
     239        Parent.__init__(self, category = GradedHopfAlgebrasWithBasis(R).WithRealizations())
    240240
    241241    def _repr_(self): # could be taken care of by the category
    242242        """