sagemathgh-39988: Adding an implementation of the Abreu-Nigro symmetric functions
    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes sagemath#12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes sagemath#12345". -->

Following the definition given in (2.2) of
https://arxiv.org/abs/2504.09123, we implement the Abreu-Nigro symmetric
functions $g_{H,k}(x; q)$, where $H$ is a Hessenberg function. To do so,
we also implement their $\rho$ basis.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - sagemath#12345: short description why this is a dependency -->
<!-- - sagemath#34567: ... -->
    
URL: sagemath#39988
Reported by: Travis Scrimshaw
Reviewer(s): Darij Grinberg, Frédéric Chapoton

Author: Release Manager

src/doc/en/reference/combinat/module_list.rst

@@ -309,6 +309,7 @@ Comprehensive Module List
     sage/combinat/set_partition
     sage/combinat/set_partition_iterator
     sage/combinat/set_partition_ordered
+    sage/combinat/sf/abreu_nigro
     sage/combinat/sf/all
     sage/combinat/sf/character
     sage/combinat/sf/classical

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

@@ -265,6 +265,18 @@ REFERENCES:
               Symposium, Volume 51, page 20.
               Australian Computer Society, Inc. 2006.
 
+.. [AN2021] Alex Abreu and Antonio Nigro. *Chromatic symmetric functions from
+            the modular law*. J. Combin. Theory Ser. A, **180** (2021), paper
+            no. 105407. :arxiv:`2006.00657`.
+
+.. [AN2021II] Alex Abreu and Antonio Nigro. *A symmetric function of increasing
+              forests*. Forum Math. Sigma, **9** No. 21 (2021), Id/No e35.
+              :arxiv:`2006.08418`.
+
+.. [AN2023] Alex Abreu and Antonio Nigro. *Splitting the cohomology of Hessenberg
+            varieties and e-positivity of chromatic symmetric functions*.
+            Preprint (2023). :arxiv:`2304.10644`.
+
 .. [Ang1997] B. Anglès. 1997. *On some characteristic polynomials attached to
              finite Drinfeld modules.* manuscripta mathematica 93, 1 (01 Aug 1997),
              369–379. https://doi.org/10.1007/BF02677478

src/sage/combinat/posets/poset_examples.py

@@ -37,7 +37,7 @@
     :meth:`~Posets.DoubleTailedDiamond` | Return the double tailed diamond poset on `2n + 2` elements.
     :meth:`~Posets.IntegerCompositions` | Return the poset of integer compositions of `n`.
     :meth:`~Posets.IntegerPartitions` | Return the poset of integer partitions of ``n``.
-    :meth:`~Posets.IntegerPartitionsDominanceOrder` | Return the lattice of integer partitions on the integer `n` ordered by dominance.
+    :meth:`~Posets.IntegerPartitionsDominanceOrder` | Return the lattice of integer partitions of the integer `n` ordered by dominance.
     :meth:`~Posets.MobilePoset` | Return the mobile poset formed by the `ribbon` with `hangers` below and an `anchor` above.
     :meth:`~Posets.NoncrossingPartitions` | Return the poset of noncrossing partitions of a finite Coxeter group ``W``.
     :meth:`~Posets.PentagonPoset` | Return the Pentagon poset.
@@ -467,8 +467,8 @@ def DivisorLattice(n, facade=None):
         """
         Return the divisor lattice of an integer.
 
-        Elements of the lattice are divisors of `n` and `x < y` in the
-        lattice if `x` divides `y`.
+        Elements of the lattice are divisors of `n`, and we have
+        `x \leq y` in the lattice if `x` divides `y`.
 
         INPUT:
 
@@ -500,16 +500,53 @@ def DivisorLattice(n, facade=None):
         return FiniteLatticePoset(hasse, elements=Div_n, facade=facade,
                                   category=FiniteLatticePosets())
 
+    @staticmethod
+    def HessenbergPoset(H):
+        r"""
+        Return the poset associated to a Hessenberg function ``H``.
+
+        A *Hessenberg function* (of length `n`) is a function `H: \{1,\ldots,n\}
+        \to \{1,\ldots,n\}` such that `\max(i, H(i-1)) \leq H(i) \leq n` for all
+        `i` (where `H(0) = 0` by convention). The corresponding poset is given
+        by `i < j` (in the poset) if and only if `H(i) < j` (as integers).
+        These posets correspond to the natural unit interval order posets.
+
+        INPUT:
+
+        - ``H`` -- list of the Hessenberg function values
+          (without `H(0)`)
+
+        EXAMPLES::
+
+            sage: P = posets.HessenbergPoset([2, 3, 5, 5, 5]); P
+            Finite poset containing 5 elements
+            sage: P.cover_relations()
+            [[2, 4], [2, 5], [1, 3], [1, 4], [1, 5]]
+
+        TESTS::
+
+            sage: P = posets.HessenbergPoset([2, 2, 6, 4, 5, 6])
+            Traceback (most recent call last):
+            ...
+            ValueError: [2, 2, 6, 4, 5, 6] is not a Hessenberg function
+            sage: P = posets.HessenbergPoset([]); P
+            Finite poset containing 0 elements
+        """
+        n = len(H)
+        if not all(max(i+1, H[i-1]) <= H[i] for i in range(1, n)) or 0 < n < H[-1]:
+            raise ValueError(f"{H} is not a Hessenberg function")
+        return Poset((tuple(range(1, n+1)), lambda i, j: H[i-1] < j))
+
     @staticmethod
     def IntegerCompositions(n):
         """
         Return the poset of integer compositions of the integer ``n``.
 
         A composition of a positive integer `n` is a list of positive
         integers that sum to `n`. The order is reverse refinement:
-        `[p_1,p_2,...,p_l] < [q_1,q_2,...,q_m]` if `q` consists
-        of an integer composition of `p_1`, followed by an integer
-        composition of `p_2`, and so on.
+        `p = [p_1,p_2,...,p_l] \leq q = [q_1,q_2,...,q_m]` if `q`
+        consists of an integer composition of `p_1`, followed by an
+        integer composition of `p_2`, and so on.
 
         EXAMPLES::
 
@@ -526,7 +563,7 @@ def IntegerCompositions(n):
     @staticmethod
     def IntegerPartitions(n):
         """
-        Return the poset of integer partitions on the integer ``n``.
+        Return the poset of integer partitions of the integer ``n``.
 
         A partition of a positive integer `n` is a non-increasing list
         of positive integers that sum to `n`. If `p` and `q` are
@@ -565,7 +602,7 @@ def lower_covers(partition):
     @staticmethod
     def RestrictedIntegerPartitions(n):
         """
-        Return the poset of integer partitions on the integer `n`
+        Return the poset of integer partitions of the integer `n`
         ordered by restricted refinement.
 
         That is, if `p` and `q` are integer partitions of `n`, then
@@ -604,12 +641,12 @@ def lower_covers(partition):
     @staticmethod
     def IntegerPartitionsDominanceOrder(n):
         r"""
-        Return the lattice of integer partitions on the integer `n`
+        Return the lattice of integer partitions of the integer `n`
         ordered by dominance.
 
         That is, if `p=(p_1,\ldots,p_i)` and `q=(q_1,\ldots,q_j)` are
-        integer partitions of `n`, then `p` is greater than `q` if and
-        only if `p_1+\cdots+p_k > q_1+\cdots+q_k` for all `k`.
+        integer partitions of `n`, then `p \geq q` if and
+        only if `p_1+\cdots+p_k \geq q_1+\cdots+q_k` for all `k`.
 
         INPUT: