Categories for Family

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

@@ -74,8 +74,10 @@ Individual Categories
    sage/categories/distributive_magmas_and_additive_magmas
    sage/categories/division_rings
    sage/categories/domains
+   sage/categories/enumerated_families
    sage/categories/enumerated_sets
    sage/categories/euclidean_domains
+   sage/categories/families
    sage/categories/fields
    sage/categories/filtered_algebras
    sage/categories/filtered_algebras_with_basis

src/sage/algebras/jordan_algebra.py

@@ -21,6 +21,7 @@
 from sage.structure.element import AlgebraElement
 from sage.structure.richcmp import richcmp
 from sage.categories.magmatic_algebras import MagmaticAlgebras
+from sage.categories.sets_cat import Sets
 from sage.misc.cachefunc import cached_method
 from sage.structure.element import is_Matrix
 from sage.modules.free_module import FreeModule
@@ -347,7 +348,10 @@ def gens(self):
             ...
             NotImplementedError: infinite set
         """
-        return tuple(self.algebra_generators())
+        if self.algebra_generators() in Sets().Finite():
+            return tuple(self.algebra_generators())
+        else:
+            raise NotImplementedError('infinite set')
 
     @cached_method
     def zero(self):

src/sage/categories/enumerated_families.py

@@ -0,0 +1,63 @@
+r"""
+Enumerated families
+"""
+
+#*****************************************************************************
+#       Copyright (C) 2022 Matthias Koeppe
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+#*****************************************************************************
+
+from sage.misc.abstract_method import abstract_method
+from sage.misc.cachefunc import cached_method
+from sage.categories.category_singleton import Category_singleton
+from sage.categories.enumerated_sets import EnumeratedSets
+from sage.categories.families import Families
+
+
+class EnumeratedFamilies(Category_singleton):
+    r"""
+    The category of enumerated families
+
+    An *enumerated family* is a family whose keys are an enumerated set
+    that induces an enumeration of the family.
+
+    - ``F[key]``: the value (element) indexed by ``key``.
+
+    The standard methods for a family ``F`` are:
+
+    - ``F.keys()``, ``F.values()``, ``F.items()``: methods similar to those of
+      :class:`dict` (or :class:`collections.abc.Mapping`).
+
+    The map is not necessarily injective.
+
+    - ``iter(F)``: returns an iterator for the elements (values) of ``F`` as a set
+      in the same order as ``iter(F.values())``, but with duplicates removed.
+
+    EXAMPLES::
+
+        sage: from sage.categories.enumerated_families import EnumeratedFamilies
+        sage: from sage.categories.families import Families
+        sage: EnumeratedFamilies()
+        Category of enumerated families
+
+        sage: EnumeratedFamilies() == Families() & EnumeratedSets()
+        False
+
+        sage: Families() & EnumeratedSets()  # BUG
+        Category of enumerated families
+    """
+
+    def super_categories(self):
+        r"""
+        EXAMPLES::
+
+            sage: from sage.categories.enumerated_families import EnumeratedFamilies
+            sage: EnumeratedFamilies().super_categories()
+            [Category of families, Category of enumerated sets]
+        """
+        return [Families(), EnumeratedSets()]

src/sage/categories/families.py

@@ -0,0 +1,142 @@
+r"""
+Families
+"""
+
+#*****************************************************************************
+#       Copyright (C) 2022 Matthias Koeppe
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+#*****************************************************************************
+
+from sage.misc.abstract_method import abstract_method
+from sage.misc.cachefunc import cached_method
+from sage.misc.lazy_import import LazyImport
+from sage.categories.category_with_axiom import CategoryWithAxiom
+from sage.categories.category_singleton import Category_singleton
+from sage.categories.sets_cat import Sets
+
+
+class Families(Category_singleton):
+    r"""
+    The category of families
+
+    A *family* is a set together with a map from a set of "keys" onto it.
+
+    Morphisms of :class:`Families` preserve this map. This is the additional
+    structure compared to :class:`Sets`. Hence, equality of families takes
+    this map into account.
+
+    The standard methods for a family ``F`` are:
+
+    - ``F.keys()``, ``F.values()``, ``F.items()``: methods similar to those of
+      :class:`dict` (or :class:`collections.abc.Mapping`).
+
+    - ``F[key]``: the value (element) indexed by ``key``.
+
+    A family is not necessarily enumerated, and the map is not necessarily injective.
+    However, if it is iterable, then:
+
+    - ``iter(F)``: returns an iterator for the elements (values) of ``F`` as a set,
+      i.e., no value appears twice.
+
+    Stronger guarantees are given by the category :class:`EnumeratedFamilies`.
+
+    EXAMPLES::
+
+        sage: from sage.categories.families import Families
+        sage: Families().is_full_subcategory(Sets())
+        False
+
+    TESTS::
+
+        sage: C = Families()
+        sage: TestSuite(C).run()
+    """
+
+    def super_categories(self):
+        r"""
+        EXAMPLES::
+
+            sage: from sage.categories.families import Families
+            sage: Families().super_categories()
+            [Category of facade sets]
+        """
+        return [Sets().Facade()]
+
+    class ParentMethods:
+
+        #def __getitem__(self, i):
+
+        @abstract_method
+        def keys(self):
+            """
+            Return the keys of the family.
+
+            This may or may not be an iterable.
+
+            EXAMPLES::
+
+                sage: f = Family({3: 'a', 4: 'b', 7: 'd'})
+                sage: sorted(f.keys())
+                [3, 4, 7]
+            """
+
+        @abstract_method(optional=True)
+        def values(self):
+            """
+            Return the elements (values) of the family.
+
+            If :meth:`keys` returns an iterable, then :meth:`values` will
+            return an iterable parallel to that. When the family is not injective,
+            values will appear multiple times in the iteration.
+
+            EXAMPLES::
+
+                sage: f = Family(["c", "a", "b"], lambda x: x + x)
+                sage: sorted(f.values())
+                ['aa', 'bb', 'cc']
+            """
+
+        def items(self):
+            """
+            Return the key-value pairs of the family.
+
+            This may or may not be an iterable.
+
+            A key can only appear once, but if the function is not injective, values will
+            appear multiple times.
+
+            EXAMPLES::
+
+                sage: f = Family(["a", "ab", "bc", "def"], len)
+                sage: sorted(f.items())
+                [('a', 1), ('ab', 2), ('bc', 2), ('def', 3)]
+            """
+            return zip(self.keys(), self.values())
+
+        @cached_method
+        def as_set(self):
+            """
+            Return the elements (values) of this family as a set.
+
+            EXAMPLES::
+
+                sage: f = Family({1: 'a', 2: 'b', 3: 'c'})
+                sage: g = Family({1: 'b', 2: 'c', 3: 'a'})
+                sage: f == g
+                False
+                sage: f.as_set() == g.as_set()
+                True
+
+            This is the same as calling :func:`~sage.sets.set.Set` on ``self``::
+
+                sage: f.as_set()
+                {...}
+                sage: Set(f)
+                {...}
+            """
+            return Set(self.values())

src/sage/categories/finitely_enumerated_families.py

@@ -0,0 +1,53 @@
+r"""
+Finitely enumerated families
+"""
+
+#*****************************************************************************
+#       Copyright (C) 2022 Matthias Koeppe
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+#*****************************************************************************
+
+from sage.misc.abstract_method import abstract_method
+from sage.misc.cachefunc import cached_method
+from sage.categories.category_singleton import Category_singleton
+from sage.categories.finite_enumerated_sets import FiniteEnumeratedSets
+from sage.categories.enumerated_families import EnumeratedFamilies
+
+
+class FinitelyEnumeratedFamilies(Category_singleton):
+    r"""
+    The category of finitely enumerated families
+
+    An *finitely enumerated family* is an enumerated family whose keys
+    form a finite enumerated set; this implies that the family is a finite set.
+
+    EXAMPLES::
+
+        sage: from sage.categories.enumerated_families import EnumeratedFamilies
+        sage: from sage.categories.finitely_enumerated_families import FinitelyEnumeratedFamilies
+        sage: FinitelyEnumeratedFamilies()
+        Category of finitely enumerated families
+
+        sage: FinitelyEnumeratedFamilies() == EnumeratedFamilies() & FiniteSets()
+        False
+        sage: F = Family(ZZ, lambda x: x % 7, is_injective=False, category=FiniteSets())
+        sage: F in EnumeratedFamilies() & FiniteSets()
+        True
+        sage: F in FinitelyEnumeratedFamilies()
+        False
+    """
+
+    def super_categories(self):
+        r"""
+        EXAMPLES::
+
+            sage: from sage.categories.finitely_enumerated_families import FinitelyEnumeratedFamilies
+            sage: FinitelyEnumeratedFamilies().super_categories()
+            [Category of enumerated families, Category of finite enumerated sets]
+        """
+        return [EnumeratedFamilies(), FiniteEnumeratedSets()]

src/sage/quivers/path_semigroup.py

@@ -541,7 +541,7 @@ def cardinality(self):
             sage: list(A.basis())
             Traceback (most recent call last):
             ...
-            ValueError: the underlying quiver has cycles, thus, there may be an infinity of directed paths
+            NotImplementedError: infinite set
         """
         from sage.rings.integer_ring import ZZ
         if self._quiver.is_directed_acyclic() and not self._quiver.has_loops():