Coverage for local/lib/python2.7/site-packages/sage/categories/with_realizations.py : 30%

""" 

With Realizations Covariant Functorial Construction 

.. SEEALSO:: 

- :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>` 

for an introduction to *realizations* and *with realizations*. 

- :mod:`sage.categories.covariant_functorial_construction` 

for an introduction to covariant functorial constructions. 

""" 

#***************************************************************************** 

# Copyright (C) 2010-2012 Nicolas M. Thiery <nthiery at users.sf.net> 

# 

# Distributed under the terms of the GNU General Public License (GPL) 

# http://www.gnu.org/licenses/ 

#***************************************************************************** 

from sage.categories.category import Category 

from sage.categories.covariant_functorial_construction import RegressiveCovariantConstructionCategory 

def WithRealizations(self): 

""" 

Return the category of parents in ``self`` endowed with multiple realizations. 

INPUT: 

- ``self`` -- a category 

.. SEEALSO:: 

- The documentation and code 

(:mod:`sage.categories.examples.with_realizations`) of 

``Sets().WithRealizations().example()`` for more on how to use and 

implement a parent with several realizations. 

- Various use cases: 

- :class:`SymmetricFunctions` 

- :class:`QuasiSymmetricFunctions` 

- :class:`NonCommutativeSymmetricFunctions` 

- :class:`SymmetricFunctionsNonCommutingVariables` 

- :class:`DescentAlgebra` 

- :class:`algebras.Moebius` 

- :class:`IwahoriHeckeAlgebra` 

- :class:`ExtendedAffineWeylGroup` 

- The `Implementing Algebraic Structures 

<../../../../../thematic_tutorials/tutorial-implementing-algebraic-structures>`_ 

thematic tutorial. 

- :mod:`sage.categories.realizations` 

.. NOTE:: this *function* is actually inserted as a *method* in the class 

:class:`~sage.categories.category.Category` (see 

:meth:`~sage.categories.category.Category.WithRealizations`). It is defined 

here for code locality reasons. 

EXAMPLES:: 

sage: Sets().WithRealizations() 

Category of sets with realizations 

.. RUBRIC:: Parent with realizations 

Let us now explain the concept of realizations. A *parent with 

realizations* is a facade parent (see :class:`Sets.Facade`) 

admitting multiple concrete realizations where its elements are 

represented. Consider for example an algebra `A` which admits 

several natural bases:: 

sage: A = Sets().WithRealizations().example(); A 

The subset algebra of {1, 2, 3} over Rational Field 

For each such basis `B` one implements a parent `P_B` which 

realizes `A` with its elements represented by expanding them on 

the basis `B`:: 

sage: A.F() 

The subset algebra of {1, 2, 3} over Rational Field in the Fundamental basis 

sage: A.Out() 

The subset algebra of {1, 2, 3} over Rational Field in the Out basis 

sage: A.In() 

The subset algebra of {1, 2, 3} over Rational Field in the In basis 

sage: A.an_element() 

F[{}] + 2*F[{1}] + 3*F[{2}] + F[{1, 2}] 

If `B` and `B'` are two bases, then the change of basis from `B` 

to `B'` is implemented by a canonical coercion between `P_B` and 

`P_{B'}`:: 

sage: F = A.F(); In = A.In(); Out = A.Out() 

sage: i = In.an_element(); i 

In[{}] + 2*In[{1}] + 3*In[{2}] + In[{1, 2}] 

sage: F(i) 

7*F[{}] + 3*F[{1}] + 4*F[{2}] + F[{1, 2}] 

sage: F.coerce_map_from(Out) 

Generic morphism: 

From: The subset algebra of {1, 2, 3} over Rational Field in the Out basis 

To: The subset algebra of {1, 2, 3} over Rational Field in the Fundamental basis 

allowing for mixed arithmetic:: 

sage: (1 + Out.from_set(1)) * In.from_set(2,3) 

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}] 

In our example, there are three realizations:: 

sage: A.realizations() 

[The subset algebra of {1, 2, 3} over Rational Field in the Fundamental basis, 

The subset algebra of {1, 2, 3} over Rational Field in the In basis, 

The subset algebra of {1, 2, 3} over Rational Field in the Out basis] 

Instead of manually defining the shorthands ``F``, ``In``, and 

``Out``, as above one can just do:: 

sage: A.inject_shorthands() 

Defining F as shorthand for The subset algebra of {1, 2, 3} over Rational Field in the Fundamental basis 

Defining In as shorthand for The subset algebra of {1, 2, 3} over Rational Field in the In basis 

Defining Out as shorthand for The subset algebra of {1, 2, 3} over Rational Field in the Out basis 

.. RUBRIC:: Rationale 

Besides some goodies described below, the role of `A` is threefold: 

- To provide, as illustrated above, a single entry point for the 

algebra as a whole: documentation, access to its properties and 

different realizations, etc. 

- To provide a natural location for the initialization of the 

bases and the coercions between, and other methods that are 

common to all bases. 

- To let other objects refer to `A` while allowing elements to be 

represented in any of the realizations. 

We now illustrate this second point by defining the polynomial 

ring with coefficients in `A`:: 

sage: P = A['x']; P 

Univariate Polynomial Ring in x over The subset algebra of {1, 2, 3} over Rational Field 

sage: x = P.gen() 

In the following examples, the coefficients turn out to be all 

represented in the `F` basis:: 

sage: P.one() 

F[{}] 

sage: (P.an_element() + 1)^2 

F[{}]*x^2 + 2*F[{}]*x + F[{}] 

However we can create a polynomial with mixed coefficients, and 

compute with it:: 

sage: p = P([1, In[{1}], Out[{2}] ]); p 

Out[{2}]*x^2 + In[{1}]*x + F[{}] 

sage: p^2 

Out[{2}]*x^4 

+ (-8*In[{}] + 4*In[{1}] + 8*In[{2}] + 4*In[{3}] - 4*In[{1, 2}] - 2*In[{1, 3}] - 4*In[{2, 3}] + 2*In[{1, 2, 3}])*x^3 

+ (F[{}] + 3*F[{1}] + 2*F[{2}] - 2*F[{1, 2}] - 2*F[{2, 3}] + 2*F[{1, 2, 3}])*x^2 

+ (2*F[{}] + 2*F[{1}])*x 

+ F[{}] 

Note how each coefficient involves a single basis which need not 

be that of the other coefficients. Which basis is used depends on 

how coercion happened during mixed arithmetic and needs not be 

deterministic. 

One can easily coerce all coefficient to a given basis with:: 

sage: p.map_coefficients(In) 

(-4*In[{}] + 2*In[{1}] + 4*In[{2}] + 2*In[{3}] - 2*In[{1, 2}] - In[{1, 3}] - 2*In[{2, 3}] + In[{1, 2, 3}])*x^2 + In[{1}]*x + In[{}] 

Alas, the natural notation for constructing such polynomials does 

not yet work:: 

sage: In[{1}] * x 

Traceback (most recent call last): 

... 

TypeError: unsupported operand parent(s) for *: 'The subset algebra of {1, 2, 3} over Rational Field in the In basis' and 'Univariate Polynomial Ring in x over The subset algebra of {1, 2, 3} over Rational Field' 

.. RUBRIC:: The category of realizations of `A` 

The set of all realizations of `A`, together with the coercion morphisms 

is a category (whose class inherits from 

:class:`~sage.categories.realizations.Category_realization_of_parent`):: 

sage: A.Realizations() 

Category of realizations of The subset algebra of {1, 2, 3} over Rational Field 

The various parent realizing `A` belong to this category:: 

sage: A.F() in A.Realizations() 

True 

`A` itself is in the category of algebras with realizations:: 

sage: A in Algebras(QQ).WithRealizations() 

True 

The (mostly technical) ``WithRealizations`` categories are the 

analogs of the ``*WithSeveralBases`` categories in 

MuPAD-Combinat. They provide support tools for handling the 

different realizations and the morphisms between them. 

Typically, ``VectorSpaces(QQ).FiniteDimensional().WithRealizations()`` 

will eventually be in charge, whenever a coercion `\phi: A\mapsto B` is 

registered, to register `\phi^{-1}` as coercion `B \mapsto A` 

if there is none defined yet. To achieve this, 

``FiniteDimensionalVectorSpaces`` would provide a nested class 

``WithRealizations`` implementing the appropriate logic. 

``WithRealizations`` is a :mod:`regressive covariant functorial 

construction <sage.categories.covariant_functorial_construction>`. 

On our example, this simply means that `A` is automatically in the 

category of rings with realizations (covariance):: 

sage: A in Rings().WithRealizations() 

True 

and in the category of algebras (regressiveness):: 

sage: A in Algebras(QQ) 

True 

.. NOTE:: 

For ``C`` a category, ``C.WithRealizations()`` in fact calls 

``sage.categories.with_realizations.WithRealizations(C)``. The 

later is responsible for building the hierarchy of the 

categories with realizations in parallel to that of their base 

categories, optimizing away those categories that do not 

provide a ``WithRealizations`` nested class. See 

:mod:`sage.categories.covariant_functorial_construction` for 

the technical details. 

.. NOTE:: 

Design question: currently ``WithRealizations`` is a 

regressive construction. That is ``self.WithRealizations()`` 

is a subcategory of ``self`` by default:: 

sage: Algebras(QQ).WithRealizations().super_categories() 

[Category of algebras over Rational Field, 

Category of monoids with realizations, 

Category of additive unital additive magmas with realizations] 

Is this always desirable? For example, 

``AlgebrasWithBasis(QQ).WithRealizations()`` should certainly 

be a subcategory of ``Algebras(QQ)``, but not of 

``AlgebrasWithBasis(QQ)``. This is because 

``AlgebrasWithBasis(QQ)`` is specifying something about the 

concrete realization. 

TESTS:: 

sage: Semigroups().WithRealizations() 

Join of Category of semigroups and Category of sets with realizations 

sage: C = GradedHopfAlgebrasWithBasis(QQ).WithRealizations(); C 

Category of graded hopf algebras with basis over Rational Field with realizations 

sage: C.super_categories() 

[Join of Category of hopf algebras over Rational Field 

and Category of graded algebras over Rational Field] 

sage: TestSuite(Semigroups().WithRealizations()).run() 

""" 

return WithRealizationsCategory.category_of(self) 

Category.WithRealizations = WithRealizations 

class WithRealizationsCategory(RegressiveCovariantConstructionCategory): 

""" 

An abstract base class for all categories of parents with multiple 

realizations. 

.. SEEALSO:: :func:`Sets().WithRealizations <sage.categories.with_realizations.WithRealizations>` 

The role of this base class is to implement some technical goodies, such 

as the name for that category. 

""" 

_functor_category = "WithRealizations" 

def _repr_(self): 

""" 

String representation. 

EXAMPLES:: 

sage: C = GradedHopfAlgebrasWithBasis(QQ).WithRealizations(); C #indirect doctest 

Category of graded hopf algebras with basis over Rational Field with realizations 

""" 

s = repr(self.base_category()) 

return s+" with realizations"