gh-37015: Implement the Aomoto complex of the Orlik-Solomon algebra and Hilbert series for filtered modules
    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->

We implement the Aomoto complex of the Orlik-Solomon algebra $A$, which
is defined as the chain complex on $A$ with the differential defined by
$\omega \wedge$ for any $\omega \in A_1$.

We also provide an implemented of Hilbert series for any filtered
module, where those for finite rank modules return honest polynomials.
(This was originally going to be just for the Orlik-Solomon algebra, but
the implementation trivially generalizes.)

<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #37015
Reported by: Travis Scrimshaw
Reviewer(s): Frédéric Chapoton, Travis Scrimshaw

Author: Release Manager

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

@@ -1362,6 +1362,10 @@ REFERENCES:
             complexes and posets. I*. Trans. of
             Amer. Math. Soc. **348** No. 4. (1996)
 
+.. [BY2016] Pauline Bailet and Masahiko Yoshinaga. *Vanishing results for the
+            Aomoto complex of real hyperplane arrangements via minimality*.
+            J. Singularities. **14** (2016), 74-90.
+
 .. [BZ01] \A. Berenstein, A. Zelevinsky
           *Tensor product multiplicities, canonical bases
           and totally positive varieties*

src/sage/algebras/orlik_solomon.py

@@ -492,7 +492,6 @@ def as_gca(self):
             20*x^3 + 29*x^2 + 10*x + 1
             sage: [len(A.basis(i)) for i in range(5)]
             [1, 10, 29, 20, 0]
-
         """
         from sage.algebras.commutative_dga import GradedCommutativeAlgebra
         gens = self.algebra_generators()
@@ -519,8 +518,8 @@ def as_gca(self):
 
     def as_cdga(self):
         r"""
-        Return the commutative differential graded algebra corresponding to ``self``
-        with the trivial differential.
+        Return the commutative differential graded algebra corresponding
+        to ``self`` with the trivial differential.
 
         EXAMPLES::
 
@@ -537,6 +536,76 @@ def as_cdga(self):
         """
         return self.as_gca().cdg_algebra({})
 
+    def aomoto_complex(self, omega):
+        r"""
+        Return the Aomoto complex of ``self`` defined by ``omega``.
+
+        Let `A(M)` be an Orlik-Solomon algebra of a matroid `M`. Let
+        `\omega \in A(M)_1` be an element of (homogeneous) degree 1.
+        The Aomoto complete is the chain complex defined on `A(M)`
+        with the differential defined by `\omega \wedge`.
+
+        EXAMPLES::
+
+            sage: OS = hyperplane_arrangements.braid(3).orlik_solomon_algebra(QQ)
+            sage: gens = OS.algebra_generators()
+            sage: AC = OS.aomoto_complex(gens[0])
+            sage: ascii_art(AC)
+                                      [0]
+                        [1 0 0]       [0]
+                        [0 1 0]       [1]
+             0 <-- C_2 <-------- C_1 <---- C_0 <-- 0
+            sage: AC.homology()
+            {0: Vector space of dimension 0 over Rational Field,
+             1: Vector space of dimension 0 over Rational Field,
+             2: Vector space of dimension 0 over Rational Field}
+
+            sage: AC = OS.aomoto_complex(-2*gens[0] + gens[1] + gens[2]); ascii_art(AC)
+                                         [ 1]
+                        [-1 -1 -1]       [ 1]
+                        [-1 -1 -1]       [-2]
+             0 <-- C_2 <----------- C_1 <----- C_0 <-- 0
+            sage: AC.homology()
+            {0: Vector space of dimension 0 over Rational Field,
+             1: Vector space of dimension 1 over Rational Field,
+             2: Vector space of dimension 1 over Rational Field}
+
+        TESTS::
+
+            sage: OS = hyperplane_arrangements.braid(4).orlik_solomon_algebra(QQ)
+            sage: gens = OS.algebra_generators()
+            sage: OS.aomoto_complex(gens[0] * gens[1] * gens[3])
+            Traceback (most recent call last):
+            ...
+            ValueError: omega must be a homogeneous element of degree 1
+
+        REFERENCES:
+
+        - [BY2016]_
+        """
+        if not omega.is_homogeneous() or omega.degree() != 1:
+            raise ValueError("omega must be a homogeneous element of degree 1")
+        from sage.homology.chain_complex import ChainComplex
+        R = self.base_ring()
+        from collections import defaultdict
+        from sage.matrix.constructor import matrix
+        graded_basis = defaultdict(list)
+        B = self.basis()
+        for k in B.keys():
+            graded_basis[len(k)].append(k)
+        degrees = list(graded_basis)
+        data = {i: matrix.zero(R, len(graded_basis[i+1]), len(graded_basis[i]))
+                for i in degrees}
+        for i in degrees:
+            mat = data[i]
+            for j, key in enumerate(graded_basis[i]):
+                ret = (omega * B[key]).monomial_coefficients(copy=False)
+                for k, imkey in enumerate(graded_basis[i+1]):
+                    if imkey in ret:
+                        mat[k,j] = ret[imkey]
+            mat.set_immutable()
+        return ChainComplex(data, R)
+
 
 class OrlikSolomonInvariantAlgebra(FiniteDimensionalInvariantModule):
     r"""

src/sage/categories/filtered_modules_with_basis.py

@@ -32,6 +32,7 @@
 from sage.misc.abstract_method import abstract_method
 from sage.misc.cachefunc import cached_method
 from sage.categories.subobjects import SubobjectsCategory
+from sage.categories.category_with_axiom import CategoryWithAxiom_over_base_ring
 
 class FilteredModulesWithBasis(FilteredModulesCategory):
     r"""
@@ -246,6 +247,52 @@ def homogeneous_component(self, d):
             M.rename("Degree {} homogeneous component of {}".format(d, self))
             return M
 
+        def hilbert_series(self, prec=None):
+            r"""
+            Return the Hilbert series of ``self``.
+
+            Let `R` be a commutative ring (with unit). Let
+            `M = \bigcup_{n=0}^{\infty} M_n` be a filtered `R`-module.
+            The *Hilbert series* of `M` is the formal power series
+
+            .. MATH::
+
+                H(t) = \sum_{n=0}^{\infty} \ell(M_n / M_{n-1}) t^n,
+
+            where `\ell(N)` is the *length* of `N`, which is the
+            longest chain of submodules (over `R`), and by convention
+            `M_{-1} = \{0\}`. By the assumptions of the category,
+            `M_n / M_{n-1}` is a free `R`-module, and so `\ell(M_n / M_{n-1})`
+            is equal to the rank of `M_n / M_{n-1}`.
+
+            INPUT:
+
+            - ``prec`` -- (default: `\infty`) the precision
+
+            OUTPUT:
+
+            If the precision is finite, then this returns an element in the
+            :class:`PowerSeriesRing` over ``ZZ``. Otherwise it returns an
+            element in the :class:`LazyPowerSeriesRing` over ``ZZ``.
+
+            EXAMPLES::
+
+                sage: A = GradedModulesWithBasis(ZZ).example()
+                sage: A.hilbert_series()
+                1 + t + 2*t^2 + 3*t^3 + 5*t^4 + 7*t^5 + 11*t^6 + O(t^7)
+                sage: A.hilbert_series(10)
+                1 + t + 2*t^2 + 3*t^3 + 5*t^4 + 7*t^5 + 11*t^6 + 15*t^7 + 22*t^8 + 30*t^9 + O(t^10)
+            """
+            from sage.rings.integer_ring import ZZ
+            if prec is None:
+                from sage.rings.lazy_series_ring import LazyPowerSeriesRing
+                R = LazyPowerSeriesRing(ZZ, 't')
+                return R(lambda n: self.homogeneous_component_basis(n).cardinality())
+            from sage.rings.power_series_ring import PowerSeriesRing
+            R = PowerSeriesRing(ZZ, 't')
+            elt = R([self.homogeneous_component_basis(n).cardinality() for n in range(prec)])
+            return elt.O(prec)
+
         def graded_algebra(self):
             r"""
             Return the associated graded module to ``self``.
@@ -1112,3 +1159,47 @@ def maximal_degree(self):
                     2
                 """
                 return self.lift().maximal_degree()
+
+    class FiniteDimensional(CategoryWithAxiom_over_base_ring):
+        class ParentMethods:
+            def hilbert_series(self, prec=None):
+                r"""
+                Return the Hilbert series of ``self`` as a polynomial.
+
+                Let `R` be a commutative ring (with unit). Let
+                `M = \bigcup_{n=0}^{\infty} M_n` be a filtered `R`-module.
+                The *Hilbert series* of `M` is the formal power series
+
+                .. MATH::
+
+                    H(t) = \sum_{n=0}^{\infty} \ell(M_n / M_{n-1}) t^n,
+
+                where `\ell(N)` is the *length* of `N`, which is the
+                longest chain of submodules (over `R`), and by convention
+                `M_{-1} = \{0\}`. By the assumptions of the category,
+                `M_n / M_{n-1}` is a free `R`-module, and so
+                `\ell(M_n / M_{n-1})` is equal to the rank of `M_n / M_{n-1}`.
+
+                EXAMPLES::
+
+                    sage: OS = hyperplane_arrangements.braid(3).orlik_solomon_algebra(QQ)
+                    sage: OS.hilbert_series()
+                    2*t^2 + 3*t + 1
+
+                    sage: OS = matroids.Uniform(5, 3).orlik_solomon_algebra(ZZ)
+                    sage: OS.hilbert_series()
+                    t^3 + 3*t^2 + 3*t + 1
+
+                    sage: OS = matroids.PG(2, 3).orlik_solomon_algebra(ZZ['x','y'])
+                    sage: OS.hilbert_series()
+                    27*t^3 + 39*t^2 + 13*t + 1
+                """
+                from collections import defaultdict
+                from sage.rings.integer_ring import ZZ
+                from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing
+                R = self.base_ring()
+                PR = PolynomialRing(ZZ, 't')
+                dims = defaultdict(ZZ)
+                for b in self.basis():
+                    dims[b.homogeneous_degree()] += 1
+                return PR(dims)

src/sage/categories/finite_dimensional_graded_lie_algebras_with_basis.py

@@ -32,6 +32,7 @@ class FiniteDimensionalGradedLieAlgebrasWithBasis(CategoryWithAxiom_over_base_ri
         Category of finite dimensional graded Lie algebras with basis over Integer Ring
         sage: C.super_categories()
         [Category of graded Lie algebras with basis over Integer Ring,
+         Category of finite dimensional filtered modules with basis over Integer Ring,
          Category of finite dimensional Lie algebras with basis over Integer Ring]
 
         sage: C is LieAlgebras(ZZ).WithBasis().FiniteDimensional().Graded()

src/sage/categories/graded_modules_with_basis.py

@@ -122,7 +122,7 @@ def submodule(self, gens, check=True, already_echelonized=False,
                 Join of
                  Category of graded vector spaces with basis over Rational Field and
                  Category of subobjects of filtered modules with basis over Rational Field and
-                 Category of finite dimensional vector spaces with basis over Rational Field
+                 Category of finite dimensional filtered modules with basis over Rational Field
                 sage: S.basis()[0].degree()
                 1
                 sage: S.basis()[1].degree()
@@ -135,7 +135,7 @@ def submodule(self, gens, check=True, already_echelonized=False,
                 Join of
                  Category of graded vector spaces with basis over Rational Field and
                  Category of subobjects of filtered modules with basis over Rational Field and
-                 Category of finite dimensional vector spaces with basis over Rational Field
+                 Category of finite dimensional filtered modules with basis over Rational Field
 
             If it is generated by inhomogeneous elements, then it is
             filtered by default::
@@ -144,8 +144,8 @@ def submodule(self, gens, check=True, already_echelonized=False,
                 sage: F.category()                                                      # needs sage.combinat sage.modules
                 Join of
                  Category of subobjects of filtered modules with basis over Rational Field and
-                 Category of filtered vector spaces with basis over Rational Field and
-                 Category of finite dimensional vector spaces with basis over Rational Field
+                 Category of finite dimensional filtered modules with basis over Rational Field and
+                 Category of filtered vector spaces with basis over Rational Field
 
             If ``category`` is specified, then it does not give any extra
             structure to the submodule (we can think of this as applying
@@ -233,7 +233,7 @@ def quotient_module(self, submodule, check=True, already_echelonized=False, cate
                 Join of
                  Category of quotients of graded modules with basis over Rational Field and
                  Category of graded vector spaces with basis over Rational Field and
-                 Category of finite dimensional vector spaces with basis over Rational Field
+                 Category of finite dimensional filtered modules with basis over Rational Field
 
             .. SEEALSO::