### Navigation

- index
- modules |
- next |
- previous |
- Category Theory »

# Sets

exception `sage.categories.sets_cat.``EmptySetError`

  Bases: `exceptions.ValueError`

  Exception raised when some operation can’t be performed on the empty set.

  EXAMPLES:

      sage: def first_element(st):
      ...    if not st: raise EmptySetError, "no elements"
      ...    else: return st[0]
      sage: first_element(Set((1,2,3)))
      1
      sage: first_element(Set([]))
      Traceback (most recent call last):
      ...
      EmptySetError: no elements

class `sage.categories.sets_cat.``Sets`(s=None)

  Bases: `sage.categories.category_singleton.Category_singleton`

  The category of sets.

  The base category for collections of elements with = (equality).

  This is also the category whose objects are all parents.

  EXAMPLES:

      sage: Sets()
      Category of sets
      sage: Sets().super_categories()
      [Category of sets with partial maps]
      sage: Sets().all_super_categories()
      [Category of sets, Category of sets with partial maps, Category of objects]

  Let us consider an example of set:

      sage: P = Sets().example("inherits")
      sage: P
      Set of prime numbers

  See `P??` for the code.

  P is in the category of sets:

      sage: P.category()
      Category of sets

  and therefore gets its methods from the following classes:

      sage: for cl in P.__class__.mro(): print(cl)
      <class 'sage.categories.examples.sets_cat.PrimeNumbers_Inherits_with_category'>
      <class 'sage.categories.examples.sets_cat.PrimeNumbers_Inherits'>
      <class 'sage.categories.examples.sets_cat.PrimeNumbers_Abstract'>
      <class 'sage.structure.unique_representation.UniqueRepresentation'>
      <class 'sage.structure.unique_representation.CachedRepresentation'>
      <type 'sage.misc.fast_methods.WithEqualityById'>
      <type 'sage.structure.parent.Parent'>
      <type 'sage.structure.category_object.CategoryObject'>
      <type 'sage.structure.sage_object.SageObject'>
      <class 'sage.categories.sets_cat.Sets.parent_class'>
      <class 'sage.categories.sets_with_partial_maps.SetsWithPartialMaps.parent_class'>
      <class 'sage.categories.objects.Objects.parent_class'>
      <type 'object'>

  We run some generic checks on P:

      sage: TestSuite(P).run(verbose=True)
      running ._test_an_element() . . . pass
      running ._test_category() . . . pass
      running ._test_elements() . . .
        Running the test suite of self.an_element()
        running ._test_category() . . . pass
        running ._test_eq() . . . pass
        running ._test_not_implemented_methods() . . . pass
        running ._test_pickling() . . . pass
        pass
      running ._test_elements_eq_reflexive() . . . pass
      running ._test_elements_eq_symmetric() . . . pass
      running ._test_elements_eq_transitive() . . . pass
      running ._test_elements_neq() . . . pass
      running ._test_eq() . . . pass
      running ._test_not_implemented_methods() . . . pass
      running ._test_pickling() . . . pass
      running ._test_some_elements() . . . pass

  Now, we manipulate some elements of P:

      sage: P.an_element()
      47
      sage: x = P(3)
      sage: x.parent()
      Set of prime numbers
      sage: x in P, 4 in P
      (True, False)
      sage: x.is_prime()
      True

  They get their methods from the following classes:

      sage: for cl in x.__class__.mro(): print(cl)
      <class 'sage.categories.examples.sets_cat.PrimeNumbers_Inherits_with_category.element_class'>
      <class 'sage.categories.examples.sets_cat.PrimeNumbers_Inherits.Element'>
      <type 'sage.rings.integer.IntegerWrapper'>
      <type 'sage.rings.integer.Integer'>
      <type 'sage.structure.element.EuclideanDomainElement'>
      <type 'sage.structure.element.PrincipalIdealDomainElement'>
      <type 'sage.structure.element.DedekindDomainElement'>
      <type 'sage.structure.element.IntegralDomainElement'>
      <type 'sage.structure.element.CommutativeRingElement'>
      <type 'sage.structure.element.RingElement'>
      <type 'sage.structure.element.ModuleElement'>
      <class 'sage.categories.examples.sets_cat.PrimeNumbers_Abstract.Element'>
      <type 'sage.structure.element.Element'>
      <type 'sage.structure.sage_object.SageObject'>
      <class 'sage.categories.sets_cat.Sets.element_class'>
      <class 'sage.categories.sets_with_partial_maps.SetsWithPartialMaps.element_class'>
      <class 'sage.categories.objects.Objects.element_class'>
      <type 'object'>

  FIXME: Objects.element_class is not very meaningful ...

  TESTS:

      sage: TestSuite(Sets()).run()

  class `Algebras`(category, *args)

    Bases: `sage.categories.algebra_functor.AlgebrasCategory`

    TESTS:

        sage: from sage.categories.covariant_functorial_construction import CovariantConstructionCategory
        sage: class FooBars(CovariantConstructionCategory):
        ...       _functor_category = "FooBars"
        sage: Category.FooBars = lambda self: FooBars.category_of(self)
        sage: C = FooBars(ModulesWithBasis(ZZ))
        sage: C
        Category of foo bars of modules with basis over Integer Ring
        sage: C.base_category()
        Category of modules with basis over Integer Ring
        sage: latex(C)
        \mathbf{FooBars}(\mathbf{ModulesWithBasis}_{\Bold{Z}})
        sage: import __main__; __main__.FooBars = FooBars # Fake FooBars being defined in a python module
        sage: TestSuite(C).run()

    `extra_super_categories`()

      EXAMPLES:

          sage: Sets().Algebras(ZZ).super_categories()
          [Category of modules with basis over Integer Ring]

          sage: Sets().Algebras(QQ).extra_super_categories()
          [Category of vector spaces with basis over Rational Field]

          sage: Sets().example().algebra(ZZ).categories()
          [Category of set algebras over Integer Ring,
           Category of modules with basis over Integer Ring,
           ...
           Category of objects]

  class `Sets.``CartesianProducts`(category, *args)

    Bases: `sage.categories.cartesian_product.CartesianProductsCategory`

    EXAMPLES:

        sage: C = Sets().CartesianProducts().example()
        sage: C
        The cartesian product of (Set of prime numbers (basic implementation),
         An example of an infinite enumerated set: the non negative integers,
         An example of a finite enumerated set: {1,2,3})
        sage: C.category()
        Category of Cartesian products of sets
        sage: C.categories()
        [Category of Cartesian products of sets, Category of sets,
         Category of sets with partial maps,
         Category of objects]
        sage: TestSuite(C).run()

    class `ElementMethods`
      `cartesian_factors`()

        Return the cartesian factors of `self`.

        EXAMPLES:

            sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.__custom_name = "F"
            sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.__custom_name = "G"
            sage: H = CombinatorialFreeModule(ZZ, [4,7]); H.__custom_name = "H"
            sage: S = cartesian_product([F, G, H])
            sage: x = S.monomial((0,4)) + 2 * S.monomial((0,5)) + 3 * S.monomial((1,6)) + 4 * S.monomial((2,4)) + 5 * S.monomial((2,7))
            sage: x.cartesian_factors()
            (B[4] + 2*B[5], 3*B[6], 4*B[4] + 5*B[7])
            sage: [s.parent() for s in x.cartesian_factors()]
            [F, G, H]
            sage: S.zero().cartesian_factors()
            (0, 0, 0)
            sage: [s.parent() for s in S.zero().cartesian_factors()]
            [F, G, H]

      `cartesian_projection`(i)

        Return the projection of `self` onto the \(i\)-th factor of the cartesian product.

        INPUTS:

        - `i` – the index of a factor of the cartesian product

        EXAMPLES:

            sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.__custom_name = "F"
            sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.__custom_name = "G"
            sage: S = cartesian_product([F, G])
            sage: x = S.monomial((0,4)) + 2 * S.monomial((0,5)) + 3 * S.monomial((1,6))
            sage: x.cartesian_projection(0)
            B[4] + 2*B[5]
            sage: x.cartesian_projection(1)
            3*B[6]

      `summand_projection`(*args, **kwds)

        Deprecated: Use `cartesian_projection()` instead. See trac ticket #10963 for details.

      `summand_split`(*args, **kwds)

        Deprecated: Use `cartesian_factors()` instead. See trac ticket #10963 for details.

    class `Sets.CartesianProducts.``ParentMethods`
      `an_element`()

        EXAMPLES:

            sage: C = Sets().CartesianProducts().example(); C
            The cartesian product of (Set of prime numbers (basic implementation),
             An example of an infinite enumerated set: the non negative integers,
             An example of a finite enumerated set: {1,2,3})
            sage: C.an_element()
            (47, 42, 1)

      `cardinality`()

        Return the cardinality of `self`

        EXAMPLES:

            sage: C = cartesian_product([GF(3), FiniteEnumeratedSet(['a','b']), GF(5)])
            sage: C.cardinality()
            30

      `cartesian_factors`()

        Return the cartesian factors of `self`.

        EXAMPLES:

            sage: cartesian_product([QQ, ZZ, ZZ]).cartesian_factors()
            (Rational Field, Integer Ring, Integer Ring)

      `cartesian_projection`(i)

        Return the natural projection onto the \(i\)-th cartesian factor of `self`.

        INPUT:

        - `i` – the index of a cartesian factor of `self`

        EXAMPLES:

            sage: C = Sets().CartesianProducts().example(); C
            The cartesian product of (Set of prime numbers (basic implementation),
             An example of an infinite enumerated set: the non negative integers,
             An example of a finite enumerated set: {1,2,3})
            sage: x = C.an_element(); x
            (47, 42, 1)
            sage: pi = C.cartesian_projection(1)
            sage: pi(x)
            42

    `Sets.CartesianProducts.``example`()

      EXAMPLES:

          sage: Sets().CartesianProducts().example()
          The cartesian product of (Set of prime numbers (basic implementation),
           An example of an infinite enumerated set: the non negative integers,
           An example of a finite enumerated set: {1,2,3})

    `Sets.CartesianProducts.``extra_super_categories`()

      A cartesian product of sets is a set.

      EXAMPLES:

          sage: Sets().CartesianProducts().extra_super_categories()
          [Category of sets]
          sage: Sets().CartesianProducts().super_categories()
          [Category of sets]

  class `Sets.``ElementMethods`
    `cartesian_product`(*elements)

      Return the cartesian product of its arguments, as an element of the cartesian product of the parents of those elements.

      EXAMPLES:

          sage: C = AlgebrasWithBasis(QQ)
          sage: A = C.example()
          sage: (a,b,c) = A.algebra_generators()
          sage: a.cartesian_product(b, c)
          B[(0, word: a)] + B[(1, word: b)] + B[(2, word: c)]

      FIXME: is this a policy that we want to enforce on all parents?

  `Sets.``Facade`

    alias of `FacadeSets`

  `Sets.``Finite`

    alias of `FiniteSets`

  class `Sets.``Infinite`(base_category)

    Bases: `sage.categories.category_with_axiom.CategoryWithAxiom_singleton`

    TESTS:

        sage: C = Sets.Finite(); C
        Category of finite sets
        sage: type(C)
        <class 'sage.categories.finite_sets.FiniteSets_with_category'>
        sage: type(C).__base__.__base__
        <class 'sage.categories.category_with_axiom.CategoryWithAxiom_singleton'>

        sage: TestSuite(C).run()

    class `ParentMethods`
      `cardinality`()

        Count the elements of the enumerated set.

        EXAMPLES:

            sage: NN = InfiniteEnumeratedSets().example()
            sage: NN.cardinality()
            +Infinity

      `is_finite`()

        Return `False` since `self` is not finite.

        EXAMPLES:

            sage: C = InfiniteEnumeratedSets().example()
            sage: C.is_finite()
            False

        TESTS:

            sage: C.is_finite.im_func is sage.categories.sets_cat.Sets.Infinite.ParentMethods.is_finite.im_func
            True

  class `Sets.``IsomorphicObjects`(category, *args)

    Bases: `sage.categories.isomorphic_objects.IsomorphicObjectsCategory`

    A category for isomorphic objects of sets.

    EXAMPLES:

        sage: Sets().IsomorphicObjects()
        Category of isomorphic objects of sets
        sage: Sets().IsomorphicObjects().all_super_categories()
        [Category of isomorphic objects of sets,
         Category of subobjects of sets, Category of quotients of sets,
         Category of subquotients of sets,
         Category of sets,
         Category of sets with partial maps,
         Category of objects]

    class `ParentMethods`
  class `Sets.``ParentMethods`
    `CartesianProduct`

      alias of `CartesianProduct`

    `algebra`(base_ring, category=None)

      Return the algebra of `self` over `base_ring`.

      INPUT:

      - `self` – a parent \(S\)
      - `base_ring` – a ring \(K\)
      - `category` – a super category of the category of \(S\), or `None`

      This returns the \(K\)-free module with basis indexed by \(S\), endowed with whatever structure can be induced from that of \(S\). Note that the `category` keyword needs to be fed with the structure on \(S\) to be used, not the structure that one wants to obtain on the result; see the examples below.

      EXAMPLES:

      If \(S\) is a monoid, the result is the monoid algebra \(KS\):

          sage: S = Monoids().example(); S
          An example of a monoid: the free monoid generated by ('a', 'b', 'c', 'd')
          sage: A = S.algebra(QQ); A
          Free module generated by An example of a monoid: the free monoid generated by ('a', 'b', 'c', 'd') over Rational Field
          sage: A.category()
          Category of monoid algebras over Rational Field

      If \(S\) is a group, the result is the group algebra \(KS\):

          sage: S = Groups().example(); S
          General Linear Group of degree 4 over Rational Field
          sage: A = S.algebra(QQ); A
          Group algebra of General Linear Group of degree 4 over Rational Field over Rational Field
          sage: A.category()
          Category of group algebras over Rational Field

      which is actually a Hopf algebra:

          sage: A in HopfAlgebras(QQ)
          True

      One may specify for which category one takes the algebra:

          sage: A = S.algebra(QQ, category = Sets()); A
          Free module generated by General Linear Group of degree 4 over Rational Field over Rational Field
          sage: A.category()
          Category of set algebras over Rational Field

      One may construct as well algebras of additive magmas, semigroups, monoids, or groups:

          sage: S = CommutativeAdditiveMonoids().example(); S
          An example of a commutative monoid: the free commutative monoid generated by ('a', 'b', 'c', 'd')
          sage: U = S.algebra(QQ); U
          Free module generated by An example of a commutative monoid: the free commutative monoid generated by ('a', 'b', 'c', 'd') over Rational Field

      Despite saying “free module”, this is really an algebra and its elements can be multiplied:

          sage: U in Algebras(QQ)
          True
          sage: (a,b,c,d) = S.additive_semigroup_generators()
          sage: U(a) * U(b)
          B[a + b]

      Constructing the algebra of a set endowed with both an additive and a multiplicative structure is ambiguous:

          sage: Z3 = IntegerModRing(3)
          sage: A = Z3.algebra(QQ)
          Traceback (most recent call last):
          ...
          TypeError:  `S = Ring of integers modulo 3` is both an additive and a multiplicative semigroup.
          Constructing its algebra is ambiguous.
          Please use, e.g., S.algebra(QQ, category = Semigroups())

      The ambiguity can be resolved using the `category` argument:

          sage: A = Z3.algebra(QQ, category = Monoids()); A
          Free module generated by Ring of integers modulo 3 over Rational Field
          sage: A.category()
          Category of monoid algebras over Rational Field

          sage: A = Z3.algebra(QQ, category = CommutativeAdditiveGroups()); A
          Free module generated by Ring of integers modulo 3 over Rational Field
          sage: A.category()
          Category of commutative additive group algebras over Rational Field

      Similarly, on , we obtain for additive magmas, monoids, groups.

      Warning

      As we have seen, in most practical use cases, the result is actually an algebra, hence the name of this method. In the other cases this name is misleading:

          sage: A = Sets().example().algebra(QQ); A
          Free module generated by Set of prime numbers (basic implementation) over Rational Field
          sage: A.category()
          Category of set algebras over Rational Field
          sage: A in Algebras(QQ)
          False

      Suggestions for a uniform, meaningful, and non misleading name are welcome!

    `an_element`()

      Return a (preferably typical) element of this parent.

      This is used both for illustration and testing purposes. If the set `self` is empty, `an_element()` should raise the exception `EmptySetError`.

      This default implementation calls `_an_element_()` and caches the result. Any parent should implement either `an_element()` or `_an_element_()`.

      EXAMPLES:

          sage: CDF.an_element()
          1.0*I
          sage: ZZ[['t']].an_element()
          t

    `cardinality`()

      The cardinality of `self`.

      `self.cardinality()` should return the cardinality of the set `self` as a sage `Integer` or as `infinity`.

      This if the default implementation from the category `Sets()`; it raises a `NotImplementedError` since one does not know whether the set is finite or not.

      EXAMPLES:

          sage: class broken(UniqueRepresentation, Parent):
          ....:     def __init__(self):
          ....:         Parent.__init__(self, category = Sets())
          sage: broken().cardinality()
          Traceback (most recent call last):
          ...
          NotImplementedError: unknown cardinality

    `cartesian_product`(*parents)

      Return the cartesian product of the parents.

      EXAMPLES:

          sage: C = AlgebrasWithBasis(QQ)
          sage: A = C.example(); A.rename("A")
          sage: A.cartesian_product(A,A)
          A (+) A (+) A
          sage: ZZ.cartesian_product(GF(2), FiniteEnumeratedSet([1,2,3]))
          The cartesian product of (Integer Ring, Finite Field of size 2, {1, 2, 3})

          sage: C = ZZ.cartesian_product(A); C
          The cartesian product of (Integer Ring, A)

      TESTS:

          sage: type(C)
          <class 'sage.sets.cartesian_product.CartesianProduct_with_category'>
          sage: C.category()
          Join of Category of rings and ...
              and Category of Cartesian products of commutative additive groups

    `is_parent_of`(element)

      Return whether `self` is the parent of `element`.

      INPUT:

      - `element` – any object

      EXAMPLES:

          sage: S = ZZ
          sage: S.is_parent_of(1)
          True
          sage: S.is_parent_of(2/1)
          False

      This method differs from `__contains__()` because it does not attempt any coercion:

          sage: 2/1 in S, S.is_parent_of(2/1)
          (True, False)
          sage: int(1) in S, S.is_parent_of(int(1))
          (True, False)

    `some_elements`()

      Return a list (or iterable) of elements of `self`.

      This is typically used for running generic tests (see `TestSuite`).

      This default implementation calls `an_element()`.

      EXAMPLES:

          sage: S = Sets().example(); S
          Set of prime numbers (basic implementation)
          sage: S.an_element()
          47
          sage: S.some_elements()
          [47]
          sage: S = Set([])
          sage: S.some_elements()
          []

      This method should return an iterable, not an iterator.

  class `Sets.``Quotients`(category, *args)

    Bases: `sage.categories.quotients.QuotientsCategory`

    A category for quotients of sets.

    See also

    `Sets().Quotients()`

    EXAMPLES:

        sage: Sets().Quotients()
        Category of quotients of sets
        sage: Sets().Quotients().all_super_categories()
        [Category of quotients of sets,
         Category of subquotients of sets,
         Category of sets,
         Category of sets with partial maps,
         Category of objects]

    class `ParentMethods`
  class `Sets.``Realizations`(category, *args)

    Bases: `sage.categories.realizations.RealizationsCategory`

    TESTS:

        sage: from sage.categories.covariant_functorial_construction import CovariantConstructionCategory
        sage: class FooBars(CovariantConstructionCategory):
        ...       _functor_category = "FooBars"
        sage: Category.FooBars = lambda self: FooBars.category_of(self)
        sage: C = FooBars(ModulesWithBasis(ZZ))
        sage: C
        Category of foo bars of modules with basis over Integer Ring
        sage: C.base_category()
        Category of modules with basis over Integer Ring
        sage: latex(C)
        \mathbf{FooBars}(\mathbf{ModulesWithBasis}_{\Bold{Z}})
        sage: import __main__; __main__.FooBars = FooBars # Fake FooBars being defined in a python module
        sage: TestSuite(C).run()

    class `ParentMethods`
      `realization_of`()

        Return the parent this is a realization of.

        EXAMPLES:

            sage: A = Sets().WithRealizations().example(); A
            The subset algebra of {1, 2, 3} over Rational Field
            sage: In = A.In(); In
            The subset algebra of {1, 2, 3} over Rational Field in the In basis
            sage: In.realization_of()
            The subset algebra of {1, 2, 3} over Rational Field

  class `Sets.``SubcategoryMethods`
    `Algebras`(base_ring)

      Return the category of objects constructed as algebras of objects of `self` over `base_ring`.

      INPUT:

      - `base_ring` – a ring

      See `Sets.ParentMethods.algebra()` for the precise meaning in Sage of the algebra of an object.

      EXAMPLES:

          sage: Monoids().Algebras(QQ)
          Category of monoid algebras over Rational Field

          sage: Groups().Algebras(QQ)
          Category of group algebras over Rational Field

          sage: AdditiveMagmas().AdditiveAssociative().Algebras(QQ)
          Category of additive semigroup algebras over Rational Field

          sage: Monoids().Algebras(Rings())
          Category of monoid algebras over Category of rings

      See also

      - `algebra_functor.AlgebrasCategory`
      - `CovariantFunctorialConstruction`

      TESTS:

          sage: TestSuite(Groups().Finite().Algebras(QQ)).run()

    `CartesianProducts`()

      Return the full subcategory of the objects of `self` constructed as cartesian products.

      See also

      - `cartesian_product.CartesianProductFunctor`
      - `RegressiveCovariantFunctorialConstruction`

      EXAMPLES:

          sage: Sets().CartesianProducts()
          Category of Cartesian products of sets
          sage: Semigroups().CartesianProducts()
          Category of Cartesian products of semigroups
          sage: EuclideanDomains().CartesianProducts()
          Join of Category of rings and Category of Cartesian products of ...

    `Facade`()

      Return the full subcategory of the facade objects of `self`.

      What is a facade set?

      Recall that, in Sage, sets are modelled by *parents*, and their elements know which distinguished set they belong to. For example, the ring of integers \(\ZZ\) is modelled by the parent `ZZ`, and integers know that they belong to this set:

          sage: ZZ
          Integer Ring
          sage: 42.parent()
          Integer Ring

      Sometimes, it is convenient to represent the elements of a parent `P` by elements of some other parent. For example, the elements of the set of prime numbers are represented by plain integers:

          sage: Primes()
          Set of all prime numbers: 2, 3, 5, 7, ...
          sage: p = Primes().an_element(); p
          43
          sage: p.parent()
          Integer Ring

      In this case, `P` is called a facade set.

      This feature is advertised through the category of \(P\):

          sage: Primes().category()
          Category of facade infinite enumerated sets
          sage: Sets().Facade()
          Category of facade sets

      Typical use cases include modeling a subset of an existing parent:

          sage: Set([4,6,9])                    # random
          {4, 6, 9}
          sage: Sets().Facade().example()
          An example of facade set: the monoid of positive integers

      or the union of several parents:

          sage: Sets().Facade().example("union")
          An example of a facade set: the integers completed by +-infinity

      or endowing an existing parent with more (or less!) structure:

          sage: Posets().example("facade")
          An example of a facade poset: the positive integers ordered by divisibility

      Let us investigate in detail a close variant of this last example: let \(P\) be set of divisors of \(12\) partially ordered by divisibility. There are two options for representing its elements:

      1. as plain integers:

             sage: P = Poset((divisors(12), attrcall("divides")), facade=True)

      2. as integers, modified to be aware that their parent is \(P\):

             sage: Q = Poset((divisors(12), attrcall("divides")), facade=False)

      The advantage of option 1. is that one needs not do conversions back and forth between \(P\) and \(\ZZ\). The disadvantage is that this introduces an ambiguity when writing \(2 < 3\): does this compare \(2\) and \(3\) w.r.t. the natural order on integers or w.r.t. divisibility?:

          sage: 2 < 3
          True

      To raise this ambiguity, one needs to explicitly specify the underlying poset as in \(2 <_P 3\):

          sage: P = Posets().example("facade")
          sage: P.lt(2,3)
          False

      On the other hand, with option 2. and once constructed, the elements know unambiguously how to compare themselves:

          sage: Q(2) < Q(3)
          False
          sage: Q(2) < Q(6)
          True

      Beware that `P(2)` is still the integer \(2\). Therefore `P(2) < P(3)` still compares \(2\) and \(3\) as integers!:

          sage: P(2) < P(3)
          True

      In short \(P\) being a facade parent is one of the programmatic counterparts (with e.g. coercions) of the usual mathematical idiom: “for ease of notation, we identify an element of \(P\) with the corresponding integer”. Too many identifications lead to confusion; the lack thereof leads to heavy, if not obfuscated, notations. Finding the right balance is an art, and even though there are common guidelines, it is ultimately up to the writer to choose which identifications to do. This is no different in code.

      See also

      The following examples illustrate various ways to implement subsets like the set of prime numbers; look at their code for details:

          sage: Sets().example("facade")
          Set of prime numbers (facade implementation)
          sage: Sets().example("inherits")
          Set of prime numbers
          sage: Sets().example("wrapper")
          Set of prime numbers (wrapper implementation)

      Specifications

      A parent which is a facade must either:

      - call `Parent.__init__()` using the `facade` parameter to specify a parent, or tuple thereof.
      - overload the method `facade_for()`.

      Note

      The concept of facade parents was originally introduced in the computer algebra system MuPAD.

      TESTS:

      Check that multiple categories initialisation works (trac ticket #13801):

          sage: class A(Parent):
          ....:   def __init__(self):
          ....:       Parent.__init__(self, category=(FiniteEnumeratedSets(),Monoids()), facade=True)
          sage: a = A()

      TESTS:

          sage: Posets().Facade()
          Category of facade posets
          sage: Posets().Facade().Finite() is  Posets().Finite().Facade()
          True

    `Facades`(*args, **kwds)

      Deprecated: Use `Facade()` instead. See trac ticket #17073 for details.

    `Finite`()

      Return the full subcategory of the finite objects of `self`.

      EXAMPLES:

          sage: Sets().Finite()
          Category of finite sets
          sage: Rings().Finite()
          Category of finite rings

      TESTS:

          sage: TestSuite(Sets().Finite()).run()
          sage: Rings().Finite.__module__
          'sage.categories.sets_cat'

    `Infinite`()

      Return the full subcategory of the infinite objects of `self`.

      EXAMPLES:

          sage: Sets().Infinite()
          Category of infinite sets
          sage: Rings().Infinite()
          Category of infinite rings

      TESTS:

          sage: TestSuite(Sets().Infinite()).run()
          sage: Rings().Infinite.__module__
          'sage.categories.sets_cat'

    `IsomorphicObjects`()

      Return the full subcategory of the objects of `self` constructed by isomorphism.

      Given a concrete category `As()` (i.e. a subcategory of `Sets()`), `As().IsomorphicObjects()` returns the category of objects of `As()` endowed with a distinguished description as the image of some other object of `As()` by an isomorphism in this category.

      See `Subquotients()` for background.

      EXAMPLES:

      In the following example, \(A\) is defined as the image by \(x\mapsto x^2\) of the finite set \(B = \{1,2,3\}\):

          sage: A = FiniteEnumeratedSets().IsomorphicObjects().example(); A
          The image by some isomorphism of An example of a finite enumerated set: {1,2,3}

      Since \(B\) is a finite enumerated set, so is \(A\):

          sage: A in FiniteEnumeratedSets()
          True
          sage: A.cardinality()
          3
          sage: A.list()
          [1, 4, 9]

      The isomorphism from \(B\) to \(A\) is available as:

          sage: A.retract(3)
          9

      and its inverse as:

          sage: A.lift(9)
          3

      It often is natural to declare those morphisms as coercions so that one can do `A(b)` and `B(a)` to go back and forth between \(A\) and \(B\) (TODO: refer to a category example where the maps are declared as a coercion). This is not done by default. Indeed, in many cases one only wants to transport part of the structure of \(B\) to \(A\). Assume for example, that one wants to construct the set of integers \(B=ZZ\), endowed with `max` as addition, and `+` as multiplication instead of the usual `+` and `*`. One can construct \(A\) as isomorphic to \(B\) as an infinite enumerated set. However \(A\) is not isomorphic to \(B\) as a ring; for example, for \(a\in A\) and \(a\in B\), the expressions \(a+A(b)\) and \(B(a)+b\) give completely different results; hence we would not want the expression \(a+b\) to be implicitly resolved to any one of above two, as the coercion mechanism would do.

      Coercions also cannot be used with facade parents (see `Sets.Facade`) like in the example above.

      We now look at a category of isomorphic objects:

          sage: C = Sets().IsomorphicObjects(); C
          Category of isomorphic objects of sets

          sage: C.super_categories()
          [Category of subobjects of sets, Category of quotients of sets]

          sage: C.all_super_categories()
          [Category of isomorphic objects of sets,
           Category of subobjects of sets,
           Category of quotients of sets,
           Category of subquotients of sets,
           Category of sets,
           Category of sets with partial maps,
           Category of objects]

      Unless something specific about isomorphic objects is implemented for this category, one actually get an optimized super category:

          sage: C = Semigroups().IsomorphicObjects(); C
          Join of Category of quotients of semigroups
              and Category of isomorphic objects of sets

      See also

      - `Subquotients()` for background
      - `isomorphic_objects.IsomorphicObjectsCategory`
      - `RegressiveCovariantFunctorialConstruction`

      TESTS:

          sage: TestSuite(Sets().IsomorphicObjects()).run()

    `Quotients`()

      Return the full subcategory of the objects of `self` constructed as quotients.

      Given a concrete category `As()` (i.e. a subcategory of `Sets()`), `As().Quotients()` returns the category of objects of `As()` endowed with a distinguished description as quotient (in fact homomorphic image) of some other object of `As()`.

      Implementing an object of `As().Quotients()` is done in the same way as for `As().Subquotients()`; namely by providing an ambient space and a lift and a retract map. See `Subquotients()` for detailed instructions.

      See also

      - `Subquotients()` for background
      - `quotients.QuotientsCategory`
      - `RegressiveCovariantFunctorialConstruction`

      EXAMPLES:

          sage: C = Semigroups().Quotients(); C
          Category of quotients of semigroups
          sage: C.super_categories()
          [Category of subquotients of semigroups, Category of quotients of sets]
          sage: C.all_super_categories()
          [Category of quotients of semigroups,
           Category of subquotients of semigroups,
           Category of semigroups,
           Category of subquotients of magmas,
           Category of magmas,
           Category of quotients of sets,
           Category of subquotients of sets,
           Category of sets,
           Category of sets with partial maps,
           Category of objects]

      The caller is responsible for checking that the given category admits a well defined category of quotients:

          sage: EuclideanDomains().Quotients()
          Join of Category of euclidean domains
              and Category of subquotients of monoids
              and Category of quotients of semigroups

      TESTS:

          sage: TestSuite(C).run()

    `Subobjects`()

      Return the full subcategory of the objects of `self` constructed as subobjects.

      Given a concrete category `As()` (i.e. a subcategory of `Sets()`), `As().Subobjects()` returns the category of objects of `As()` endowed with a distinguished embedding into some other object of `As()`.

      Implementing an object of `As().Subobjects()` is done in the same way as for `As().Subquotients()`; namely by providing an ambient space and a lift and a retract map. In the case of a trivial embedding, the two maps will typically be identity maps that just change the parent of their argument. See `Subquotients()` for detailed instructions.

      See also

      - `Subquotients()` for background
      - `subobjects.SubobjectsCategory`
      - `RegressiveCovariantFunctorialConstruction`

      EXAMPLES:

          sage: C = Sets().Subobjects(); C
          Category of subobjects of sets

          sage: C.super_categories()
          [Category of subquotients of sets]

          sage: C.all_super_categories()
          [Category of subobjects of sets,
           Category of subquotients of sets,
           Category of sets,
           Category of sets with partial maps,
           Category of objects]

      Unless something specific about subobjects is implemented for this category, one actually gets an optimized super category:

          sage: C = Semigroups().Subobjects(); C
          Join of Category of subquotients of semigroups
              and Category of subobjects of sets

      The caller is responsible for checking that the given category admits a well defined category of subobjects.

      TESTS:

          sage: Semigroups().Subobjects().is_subcategory(Semigroups().Subquotients())
          True
          sage: TestSuite(C).run()

    `Subquotients`()

      Return the full subcategory of the objects of `self` constructed as subquotients.

      Given a concrete category `self == As()` (i.e. a subcategory of `Sets()`), `As().Subquotients()` returns the category of objects of `As()` endowed with a distinguished description as subquotient of some other object of `As()`.

      EXAMPLES:

          sage: Monoids().Subquotients()
          Category of subquotients of monoids

      A parent \(A\) in `As()` is further in `As().Subquotients()` if there is a distinguished parent \(B\) in `As()`, called the ambient set, a subobject \(B'\) of \(B\), and a pair of maps:

      \[l: A \to B' \text{ and } r: B' \to A\]

      called respectively the lifting map and retract map such that \(r \circ l\) is the identity of \(A\) and \(r\) is a morphism in `As()`.

      Todo

      Draw the typical commutative diagram.

      It follows that, for each operation \(op\) of the category, we have some property like:

      \[op_A(e) = r(op_B(l(e))), \text{ for all } e\in A\]

      This allows for implementing the operations on \(A\) from those on \(B\).

      The two most common use cases are:

      > - homomorphic images (or quotients), when \(B'=B\), \(r\) is an homomorphism from \(B\) to \(A\) (typically a canonical quotient map), and \(l\) a section of it (not necessarily a homomorphism); see `Quotients()`;
      > - subobjects (up to an isomorphism), when \(l\) is an embedding from \(A\) into \(B\); in this case, \(B'\) is typically isomorphic to \(A\) through the inverse isomorphisms \(r\) and \(l\); see `Subobjects()`;

      Note

      - The usual definition of “subquotient” (Wikipedia article Subquotient) does not involve the lifting map \(l\). This map is required in Sage’s context to make the definition constructive. It is only used in computations and does not affect their results. This is relatively harmless since the category is a concrete category (i.e., its objects are sets and its morphisms are set maps).
      - In mathematics, especially in the context of quotients, the retract map \(r\) is often referred to as a projection map instead.
      - Since \(B'\) is not specified explicitly, it is possible to abuse the framework with situations where \(B'\) is not quite a subobject and \(r\) not quite a morphism, as long as the lifting and retract maps can be used as above to compute all the operations in \(A\). Use at your own risk!

      Assumptions:

      - For any category `As()`, `As().Subquotients()` is a subcategory of `As()`.

        Example: a subquotient of a group is a group (e.g., a left or right quotient of a group by a non-normal subgroup is not in this category).

      - This construction is covariant: if `As()` is a subcategory of `Bs()`, then `As().Subquotients()` is a subcategory of `Bs().Subquotients()`.

        Example: if \(A\) is a subquotient of \(B\) in the category of groups, then it is also a subquotient of \(B\) in the category of monoids.

      - If the user (or a program) calls `As().Subquotients()`, then it is assumed that subquotients are well defined in this category. This is not checked, and probably never will be. Note that, if a category `As()` does not specify anything about its subquotients, then its subquotient category looks like this:

            sage: EuclideanDomains().Subquotients()
            Join of Category of euclidean domains
                and Category of subquotients of monoids

      Interface: the ambient set \(B\) of \(A\) is given by `A.ambient()`. The subset \(B'\) needs not be specified, so the retract map is handled as a partial map from \(B\) to \(A\).

      The lifting and retract map are implemented respectively as methods `A.lift(a)` and `A.retract(b)`. As a shorthand for the former, one can use alternatively `a.lift()`:

          sage: S = Semigroups().Subquotients().example(); S
          An example of a (sub)quotient semigroup: a quotient of the left zero semigroup
          sage: S.ambient()
          An example of a semigroup: the left zero semigroup
          sage: S(3).lift().parent()
          An example of a semigroup: the left zero semigroup
          sage: S(3) * S(1) == S.retract( S(3).lift() * S(1).lift() )
          True

      See `S?` for more.

      Todo

      use a more interesting example, like \(\ZZ/n\ZZ\).

      See also

      - `Quotients()`, `Subobjects()`, `IsomorphicObjects()`
      - `subquotients.SubquotientsCategory`
      - `RegressiveCovariantFunctorialConstruction`

      TESTS:

          sage: TestSuite(Sets().Subquotients()).run()

  class `Sets.``Subobjects`(category, *args)

    Bases: `sage.categories.subobjects.SubobjectsCategory`

    A category for subobjects of sets.

    See also

    `Sets().Subobjects()`

    EXAMPLES:

        sage: Sets().Subobjects()
        Category of subobjects of sets
        sage: Sets().Subobjects().all_super_categories()
        [Category of subobjects of sets,
         Category of subquotients of sets,
         Category of sets,
         Category of sets with partial maps,
         Category of objects]

    class `ParentMethods`
  class `Sets.``Subquotients`(category, *args)

    Bases: `sage.categories.subquotients.SubquotientsCategory`

    A category for subquotients of sets.

    See also

    `Sets().Subquotients()`

    EXAMPLES:

        sage: Sets().Subquotients()
        Category of subquotients of sets
        sage: Sets().Subquotients().all_super_categories()
        [Category of subquotients of sets, Category of sets,
         Category of sets with partial maps,
         Category of objects]

    class `ElementMethods`
      `lift`()

        Lift `self` to the ambient space for its parent.

        EXAMPLES:

            sage: S = Semigroups().Subquotients().example()
            sage: s = S.an_element()
            sage: s, s.parent()
            (42, An example of a (sub)quotient semigroup: a quotient of the left zero semigroup)
            sage: S.lift(s), S.lift(s).parent()
            (42, An example of a semigroup: the left zero semigroup)
            sage: s.lift(), s.lift().parent()
            (42, An example of a semigroup: the left zero semigroup)

    class `Sets.Subquotients.``ParentMethods`
      `ambient`()

        Return the ambient space for `self`.

        EXAMPLES:

            sage: Semigroups().Subquotients().example().ambient()
            An example of a semigroup: the left zero semigroup

        See also

        `Sets.SubcategoryMethods.Subquotients()` for the specifications and `lift()` and `retract()`.

      `lift`(x)

        Lift \(x\) to the ambient space for `self`.

        INPUT:

        - `x` – an element of `self`

        EXAMPLES:

            sage: S = Semigroups().Subquotients().example()
            sage: s = S.an_element()
            sage: s, s.parent()
            (42, An example of a (sub)quotient semigroup: a quotient of the left zero semigroup)
            sage: S.lift(s), S.lift(s).parent()
            (42, An example of a semigroup: the left zero semigroup)
            sage: s.lift(), s.lift().parent()
            (42, An example of a semigroup: the left zero semigroup)

        See also

        `Sets.SubcategoryMethods.Subquotients` for the specifications, `ambient()`, `retract()`, and also `Sets.Subquotients.ElementMethods.lift()`.

      `retract`(x)

        Retract `x` to `self`.

        INPUT:

        - `x` – an element of the ambient space for `self`

        See also

        `Sets.SubcategoryMethods.Subquotients` for the specifications, `ambient()`, `retract()`, and also `Sets.Subquotients.ElementMethods.retract()`.

        EXAMPLES:

            sage: S = Semigroups().Subquotients().example()
            sage: s = S.ambient().an_element()
            sage: s, s.parent()
            (42, An example of a semigroup: the left zero semigroup)
            sage: S.retract(s), S.retract(s).parent()
            (42, An example of a (sub)quotient semigroup: a quotient of the left zero semigroup)

  class `Sets.``WithRealizations`(category, *args)

    Bases: `sage.categories.with_realizations.WithRealizationsCategory`

    TESTS:

        sage: from sage.categories.covariant_functorial_construction import CovariantConstructionCategory
        sage: class FooBars(CovariantConstructionCategory):
        ...       _functor_category = "FooBars"
        sage: Category.FooBars = lambda self: FooBars.category_of(self)
        sage: C = FooBars(ModulesWithBasis(ZZ))
        sage: C
        Category of foo bars of modules with basis over Integer Ring
        sage: C.base_category()
        Category of modules with basis over Integer Ring
        sage: latex(C)
        \mathbf{FooBars}(\mathbf{ModulesWithBasis}_{\Bold{Z}})
        sage: import __main__; __main__.FooBars = FooBars # Fake FooBars being defined in a python module
        sage: TestSuite(C).run()

    class `ParentMethods`
      class `Realizations`(parent_with_realization)

        Bases: `sage.categories.realizations.Category_realization_of_parent`

        TESTS:

            sage: from sage.categories.realizations import Category_realization_of_parent
            sage: A = Sets().WithRealizations().example(); A
            The subset algebra of {1, 2, 3} over Rational Field
            sage: C = A.Realizations(); C
            Category of realizations of The subset algebra of {1, 2, 3} over Rational Field
            sage: isinstance(C, Category_realization_of_parent)
            True
            sage: C.parent_with_realization
            The subset algebra of {1, 2, 3} over Rational Field
            sage: TestSuite(C).run(skip=["_test_category_over_bases"])

        Todo

        Fix the failing test by making `C` a singleton category. This will require some fiddling with the assertion in `Category_singleton.__classcall__()`

        `super_categories`()

          EXAMPLES:

              sage: A = Sets().WithRealizations().example(); A
              The subset algebra of {1, 2, 3} over Rational Field
              sage: A.Realizations().super_categories()
              [Category of realizations of sets]

      `Sets.WithRealizations.ParentMethods.``a_realization`()

        Return a realization of `self`.

        EXAMPLES:

            sage: A = Sets().WithRealizations().example(); A
            The subset algebra of {1, 2, 3} over Rational Field
            sage: A.a_realization()
            The subset algebra of {1, 2, 3} over Rational Field in the Fundamental basis

      `Sets.WithRealizations.ParentMethods.``facade_for`()

        Return the parents `self` is a facade for, that is the realizations of `self`

        EXAMPLES:

            sage: A = Sets().WithRealizations().example(); A
            The subset algebra of {1, 2, 3} over Rational Field
            sage: A.facade_for()
            [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]

            sage: A = Sets().WithRealizations().example(); A
            The subset algebra of {1, 2, 3} over Rational Field
            sage: f = A.F().an_element(); f
            F[{}] + 2*F[{1}] + 3*F[{2}] + F[{1, 2}]
            sage: i = A.In().an_element(); i
            In[{}] + 2*In[{1}] + 3*In[{2}] + In[{1, 2}]
            sage: o = A.Out().an_element(); o
            Out[{}] + 2*Out[{1}] + 3*Out[{2}] + Out[{1, 2}]
            sage: f in A, i in A, o in A
            (True, True, True)

      `Sets.WithRealizations.ParentMethods.``inject_shorthands`(verbose=True)

        EXAMPLES:

            sage: A = Sets().WithRealizations().example(QQ); A
            The subset algebra of {1, 2, 3} over Rational Field
            sage: A.inject_shorthands()
            Injecting F as shorthand for The subset algebra of {1, 2, 3} over Rational Field in the Fundamental basis
            Injecting In as shorthand for The subset algebra of {1, 2, 3} over Rational Field in the In basis
            ...

      `Sets.WithRealizations.ParentMethods.``realizations`()

        Return all the realizations of `self` that `self` is aware of.

        EXAMPLES:

            sage: A = Sets().WithRealizations().example(); A
            The subset algebra of {1, 2, 3} over Rational Field
            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]

        Note

        Constructing a parent `P` in the category `A.Realizations()` automatically adds `P` to this list by calling `A._register_realization(A)`

    `Sets.WithRealizations.``example`(base_ring=None, set=None)

      Return an example of set with multiple realizations, as per `Category.example()`.

      EXAMPLES:

          sage: Sets().WithRealizations().example()
          The subset algebra of {1, 2, 3} over Rational Field

          sage: Sets().WithRealizations().example(ZZ, Set([1,2]))
          The subset algebra of {1, 2} over Integer Ring

    `Sets.WithRealizations.``extra_super_categories`()

      A set with multiple realizations is a facade parent.

      EXAMPLES:

          sage: Sets().WithRealizations().extra_super_categories()
          [Category of facade sets]
          sage: Sets().WithRealizations().super_categories()
          [Category of facade sets]

  `Sets.``example`(choice=None)

    Returns examples of objects of `Sets()`, as per `Category.example()`.

    EXAMPLES:

        sage: Sets().example()
        Set of prime numbers (basic implementation)

        sage: Sets().example("inherits")
        Set of prime numbers

        sage: Sets().example("facade")
        Set of prime numbers (facade implementation)

        sage: Sets().example("wrapper")
        Set of prime numbers (wrapper implementation)

  `Sets.``super_categories`()

    We include SetsWithPartialMaps between Sets and Objects so that we can define morphisms between sets that are only partially defined. This is also to have the Homset constructor not complain that SetsWithPartialMaps is not a supercategory of Fields, for example.

    EXAMPLES:

        sage: Sets().super_categories()
        [Category of sets with partial maps]

`sage.categories.sets_cat.``print_compare`(x, y)

  Helper method used in `Sets.ParentMethods._test_elements_eq_symmetric()`, `Sets.ParentMethods._test_elements_eq_tranisitive()`.

  INPUT:

  - `x` – an element
  - `y` – an element

  EXAMPLES:

      sage: from sage.categories.sets_cat import print_compare
      sage: print_compare(1,2)
      1 != 2
      sage: print_compare(1,1)
      1 == 1

### Navigation

- index
- modules |
- next |
- previous |
- Category Theory »