Trac #31246: some details in posets

adding a few words about conversion to GAP and Macaulay2 posets

just a few typing annotations

and a few typos

URL: https://trac.sagemath.org/31246
Reported by: chapoton
Ticket author(s): Frédéric Chapoton
Reviewer(s): Travis Scrimshaw

src/sage/combinat/posets/posets.py

@@ -861,6 +861,19 @@ class FinitePoset(UniqueRepresentation, Parent):
         sage: parent(QP[0]) is QP
         True
 
+    Conversion to some other software is possible::
+
+        sage: P = posets.TamariLattice(3)
+        sage: libgap(P)  # optional - gap_packages
+        <A poset on 5 points>
+
+        sage: P = Poset({1:[2],2:[]})
+        sage: macaulay2('needsPackage "Posets"')   # optional - macaulay2
+        Posets
+        sage: macaulay2(P)   # optional - macaulay2
+        Relation Matrix: | 1 1 |
+                         | 0 1 |
+
     .. NOTE::
 
        A class that inherits from this class needs to define
@@ -1191,7 +1204,7 @@ def unwrap(self, element):
             sage: P.unwrap(x) is x
             True
 
-        This method is useful in code where we don't know if ``P`` is
+        This method is useful in code where we do not know if ``P`` is
         a facade poset or not.
         """
         if self._is_facade:
@@ -1507,7 +1520,7 @@ def linear_extension(self, linear_extension=None, check=True):
 
         - ``linear_extension`` -- (default: ``None``) a list of the
           elements of ``self``
-        - ``check`` -- a boolean (default: True);
+        - ``check`` -- a boolean (default: ``True``);
           whether to check that ``linear_extension`` is indeed a
           linear extension of ``self``.
 
@@ -1776,7 +1789,7 @@ def atkinson(self, a):
                 new_a_spec[-1] += k_val * a_spec[i - 1] * n_lin_exts
         return new_a_spec
 
-    def is_linear_extension(self, l):
+    def is_linear_extension(self, l) -> bool:
         """
         Return whether ``l`` is a linear extension of ``self``.
 
@@ -2245,7 +2258,7 @@ def diamonds(self):
                     w
 
         Thus each edge represents a cover relation in the Hasse diagram.
-        We represent his as the tuple `(w, x, y, z)`.
+        We represent this as the tuple `(w, x, y, z)`.
 
         OUTPUT:
 
@@ -2281,7 +2294,7 @@ def common_upper_covers(self, elmts):
         vertices = list(map(self._element_to_vertex, elmts))
         return list(map(self._vertex_to_element, self._hasse_diagram.common_upper_covers(vertices)))
 
-    def is_d_complete(self):
+    def is_d_complete(self) -> bool:
         r"""
         Return ``True`` if a poset is d-complete and ``False`` otherwise.
 
@@ -2549,7 +2562,7 @@ def relations_number(self):
     # Maybe this should also be deprecated.
     intervals_number = relations_number
 
-    def is_incomparable_chain_free(self, m, n=None):
+    def is_incomparable_chain_free(self, m, n=None) -> bool:
         r"""
         Return ``True`` if the poset is `(m+n)`-free, and ``False`` otherwise.
 
@@ -2666,7 +2679,7 @@ def is_incomparable_chain_free(self, m, n=None):
                 return False
         return True
 
-    def is_lequal(self, x, y):
+    def is_lequal(self, x, y) -> bool:
         """
         Return ``True`` if `x` is less than or equal to `y` in the poset, and
         ``False`` otherwise.
@@ -2691,7 +2704,7 @@ def is_lequal(self, x, y):
 
     le = is_lequal
 
-    def is_less_than(self, x, y):
+    def is_less_than(self, x, y) -> bool:
         """
         Return ``True`` if `x` is less than but not equal to `y` in the poset,
         and ``False`` otherwise.
@@ -2720,7 +2733,7 @@ def is_less_than(self, x, y):
 
     lt = is_less_than
 
-    def is_gequal(self, x, y):
+    def is_gequal(self, x, y) -> bool:
         """
         Return ``True`` if `x` is greater than or equal to `y` in the poset,
         and ``False`` otherwise.
@@ -2743,7 +2756,7 @@ def is_gequal(self, x, y):
 
     ge = is_gequal
 
-    def is_greater_than(self, x, y):
+    def is_greater_than(self, x, y) -> bool:
         """
         Return ``True`` if `x` is greater than but not equal to `y` in the
         poset, and ``False`` otherwise.
@@ -3024,7 +3037,7 @@ def has_isomorphic_subposet(self, other):
             return False
         return True
 
-    def is_bounded(self):
+    def is_bounded(self) -> bool:
         """
         Return ``True`` if the poset is bounded, and ``False`` otherwise.
 
@@ -3057,7 +3070,7 @@ def is_bounded(self):
         """
         return self._hasse_diagram.is_bounded()
 
-    def is_chain(self):
+    def is_chain(self) -> bool:
         """
         Return ``True`` if the poset is totally ordered ("chain"), and
         ``False`` otherwise.
@@ -3083,7 +3096,7 @@ def is_chain(self):
         """
         return self._hasse_diagram.is_chain()
 
-    def is_chain_of_poset(self, elms, ordered=False):
+    def is_chain_of_poset(self, elms, ordered=False) -> bool:
         """
         Return ``True`` if ``elms`` is a chain of the poset,
         and ``False`` otherwise.
@@ -3180,11 +3193,11 @@ def is_antichain_of_poset(self, elms):
         elms_H = [self._element_to_vertex(e) for e in elms]
         return self._hasse_diagram.is_antichain_of_poset(elms_H)
 
-    def is_connected(self):
+    def is_connected(self) -> bool:
         """
         Return ``True`` if the poset is connected, and ``False`` otherwise.
 
-        A poset is connected if it's Hasse diagram is connected.
+        A poset is connected if its Hasse diagram is connected.
 
         If a poset is not connected, then it can be divided to parts
         `S_1` and `S_2` so that every element of `S_1` is incomparable to
@@ -3209,7 +3222,7 @@ def is_connected(self):
         """
         return self._hasse_diagram.is_connected()
 
-    def is_series_parallel(self):
+    def is_series_parallel(self) -> bool:
         """
         Return ``True`` if the poset is series-parallel, and ``False``
         otherwise.
@@ -3737,7 +3750,7 @@ def rank(self, element=None):
         else:
             raise ValueError("the poset is not ranked")
 
-    def is_ranked(self):
+    def is_ranked(self) -> bool:
         r"""
         Return ``True`` if the poset is ranked, and ``False`` otherwise.
 
@@ -3766,7 +3779,7 @@ def is_ranked(self):
         """
         return bool(self.rank_function())
 
-    def is_graded(self):
+    def is_graded(self) -> bool:
         r"""
         Return ``True`` if the poset is graded, and ``False`` otherwise.
 
@@ -3808,7 +3821,7 @@ def is_graded(self):
         if len(self) <= 2:
             return True
         # Let's work with the Hasse diagram in order to avoid some
-        # indirection (the output doesn't depend on the vertex labels).
+        # indirection (the output does not depend on the vertex labels).
         hasse = self._hasse_diagram
         rf = hasse.rank_function()
         if rf is None:
@@ -6699,7 +6712,7 @@ def maximal_antichains(self):
 
         EXAMPLES::
 
-            sage: P=Poset({'a':['b', 'c'], 'b':['d','e']})
+            sage: P = Poset({'a':['b', 'c'], 'b':['d','e']})
             sage: [sorted(anti) for anti in P.maximal_antichains()]
             [['a'], ['b', 'c'], ['c', 'd', 'e']]
 
@@ -6761,7 +6774,7 @@ def order_complex(self, on_ints=False):
 
         INPUT:
 
-        - ``on_ints`` -- a boolean (default: False)
+        - ``on_ints`` -- a boolean (default: ``False``)
 
         OUTPUT:
 
@@ -7090,7 +7103,7 @@ def flag_f_polynomial(self):
         the maximum of `P`, where `\rho` is the rank function of `P`
         (normalized to satisfy `\rho(\min P) = 0`), and where
         `n` is the rank of `\max P`. (Note that the indeterminate
-        `x_0` doesn't actually appear in the polynomial.)
+        `x_0` does not actually appear in the polynomial.)
 
         For technical reasons, the polynomial is returned in the
         slightly larger ring `\ZZ[x_0, x_1, x_2, \cdots, x_{n+1}]` by
@@ -7538,7 +7551,7 @@ def evacuation(self):
         """
         return self.linear_extension().evacuation().to_poset()
 
-    def is_rank_symmetric(self):
+    def is_rank_symmetric(self) -> bool:
         r"""
         Return ``True`` if the poset is rank symmetric, and ``False``
         otherwise.
@@ -8670,7 +8683,7 @@ def _ford_fulkerson_chronicle(G, s, t, a):
     .. WARNING::
 
         This method is tailor-made for its use in the
-        :meth:`FinitePoset.greene_shape()` method of a finite poset. It's not
+        :meth:`FinitePoset.greene_shape()` method of a finite poset. It is not
         very useful in general. First of all, as said above, the iterator
         does not know when to halt. Second, `G` needs to be acyclic for it
         to correctly work. This must be amended if this method is ever to be
@@ -8726,7 +8739,7 @@ def _ford_fulkerson_chronicle(G, s, t, a):
 
     # f: flow function as a dictionary.
     f = { (u, v): 0 for (u, v, l) in G.edge_iterator() }
-    # val: value of the flow f. (Can't call it v due to Python's asinine
+    # val: value of the flow f. (Cannot call it v due to Python's asinine
     # handling of for loops.)
     val = 0