Add Oriented Matroids Package

.vscode/settings.json

@@ -32,5 +32,8 @@
         "Cython"
     ],
     "editor.formatOnType": true,
-    "esbonio.sphinx.confDir": ""
+    "esbonio.sphinx.confDir": "",
+    "flake8.args": [
+        "--select=E111,E21,E221,E222,E225,E227,E228,E25,E271,E303,E305,E306,E401,E502,E701,E702,E703,E71,E72,W291,W293,W391,W605"
+    ]
 }

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

@@ -65,4 +65,32 @@ Internals
    sage/matroids/set_system
    sage/matroids/unpickling
 
+Oriented Matroids
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/matroids/oriented_matroids/oriented_matroid
+
+Representations
+---------------
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/matroids/oriented_matroids/circuit_oriented_matroid
+   sage/matroids/oriented_matroids/covector_oriented_matroid
+   sage/matroids/oriented_matroids/real_hyperplane_arrangement_oriented_matroid
+   sage/matroids/oriented_matroids/vector_oriented_matroid
+
+Elements
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/matroids/oriented_matroids/signed_subset_element
+
 .. include:: ../footer.txt
+

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

@@ -963,6 +963,10 @@ REFERENCES:
             Anal. Appl. 15 (1994) 804-823.
             :doi:`10.1137/S0895479892230031`
 
+.. [BLSWZ1999] Anders Björner, Michel Las Vergnas, Bernd Sturmfels, Neil White
+               and Günter Ziegler, *Oriented Matroids*; Cambridge University
+               press, (1999).
+
 .. [BHMPW20a] Tom Braden, June Huh, Jacob P. Matherne, Nicholas Proudfoot,
              and Botong Wang, *A semi-small decomposition of the Chow
              ring of a matroid*, :arxiv:`2002.03341` (2020).

src/sage/matroids/all.py

@@ -8,5 +8,9 @@
 from sage.misc.lazy_import import lazy_import
 lazy_import('sage.matroids.constructor', 'Matroid')
 lazy_import('sage.matroids', 'matroids_catalog', 'matroids')
+
+# Add Oriented Matroids
+from sage.matroids.oriented_matroids.all import *
+
 del lazy_import
 del install_doc

src/sage/matroids/oriented_matroids/all.py

@@ -0,0 +1,8 @@
+"""
+Oriented Matroids
+"""
+from sage.misc.namespace_package import install_doc
+install_doc(__package__, __doc__)
+
+from sage.misc.lazy_import import lazy_import
+lazy_import('sage.matroids.oriented_matroids.oriented_matroid', 'OrientedMatroid')

src/sage/matroids/oriented_matroids/circuit_oriented_matroid.py

@@ -0,0 +1,263 @@
+r"""
+Oriented matroid with circuit axioms
+
+This implements an oriented matroid using the circuit axioms.
+
+AUTHORS:
+
+- Aram Dermenjian (2019-07-12): Initial version
+"""
+
+# ****************************************************************************
+#      Copyright (C) 2019   Aram Dermenjian <aram.dermenjian.math at gmail.com>
+#
+# 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.matroids.oriented_matroids.oriented_matroid import OrientedMatroid
+
+
+class CircuitOrientedMatroid(OrientedMatroid):
+    r"""
+    An oriented matroid implemented using circuit axioms.
+
+    This implements an oriented matroid using the circuit axioms. For this
+    let `\mathcal{C}` be a set of signed subsets and `E` a groundset. Then
+    a pair `M = (E, \mathcal{C})` is an oriented matroid using the circuit
+    axioms if (see Definition 3.2.1 in [BLSWZ1999]_):
+
+    - `\emptyset \notin \mathcal{C}`
+    - `\mathcal{C} = -\mathcal{C}`
+    - For all `X, Y \in \mathcal{C}`, if the support of `X` is contained
+      in the support of `Y` then `X = Y` or `X = -Y`
+    - For all `X, Y \in \mathcal{C}`, `X \neq -Y`, and
+      `e \in X^+ \cap Y^-` there exists a `Z \in \mathcal{C}` such that
+      `Z^+ \subseteq (X^+ \cup Y^+) \backslash \left\{e\right\}` and
+      `Z^- \subseteq (X^- \cup Y^-) \backslash \left\{e\right\}`.
+
+    INPUT:
+
+    - ``data`` -- a tuple containing :class:`SignedSubsetElement` elements or
+      data that can be used to construct :class:`SignedSubsetElement` elements
+    - ``groundset`` -- (default: ``None``) the groundset for the data; if not
+      provided, we grab the data from the signed subsets
+
+    EXAMPLES::
+
+        sage: from sage.matroids.oriented_matroids.oriented_matroid import OrientedMatroid
+        sage: M = OrientedMatroid([[1], [-1]], key='circuit'); M
+        Circuit oriented matroid of rank 0
+        sage: M.groundset()
+        (0,)
+
+        sage: C = [((1,4),(2,3)), ((2,3),(1,4))]
+        sage: M = OrientedMatroid(C, key='circuit'); M
+        Circuit oriented matroid of rank 3
+        sage: M.groundset()
+        (1, 2, 3, 4)
+        sage: M.an_element() in M.elements()
+        True
+        sage: M.elements() == M.circuits()
+        True
+
+        sage: C5 = [((1,),(3,),(2,)), ((1,2),(3,),(4,)),
+        ....:       ((3,),(1,),(2,)), ((3,),(1,2),(4,))]
+        sage: OrientedMatroid(C5, key='circuit')
+        Traceback (most recent call last):
+        ...
+        ValueError: groundsets must be the same
+
+    .. SEEALSO::
+
+        - :class:`~sage.oriented_matroids.oriented_matroid.OrientedMatroid`
+        - :class:`~sage.oriented_matroids.oriented_matroids_category.OrientedMatroids`
+    """
+    def __init__(self, data, groundset=None, category=None):
+        """
+        Return a ``CircuitOrientedMatroid`` object.
+
+        EXAMPLES::
+
+            sage: from sage.matroids.oriented_matroids.oriented_matroid import OrientedMatroid
+            sage: M = OrientedMatroid([[1], [-1]], key='circuit'); M
+            Circuit oriented matroid of rank 0
+            sage: TestSuite(M).run()
+        """
+        OrientedMatroid.__init__(self, category=category)
+
+        # Set up our circuits
+        circuits = []
+        if data:
+            for d in data:
+                # Convert to the appropriate element class
+                circuits.append(self.element_class(self, data=d, groundset=groundset))
+
+        # If our groundset is none, make sure the groundsets are the same for
+        # all elements
+        if groundset is None and len(circuits) > 0:
+            if len(data[0]) < 3:
+                groundset = []
+                for X in circuits:
+                    groundset = list(set(groundset + X.groundset()))
+            else:
+                groundset = circuits[0].groundset()
+                for X in circuits:
+                    if X.groundset() != groundset:
+                        raise ValueError("groundsets must be the same")
+
+        self._circuits = circuits
+        self._elements = circuits
+
+        if groundset is None:
+            self._groundset = None
+        else:
+            self._groundset = tuple(groundset)
+
+    def is_valid(self, certificate=False) -> bool | tuple[bool, dict]:
+        """
+        Return whether our circuits satisfy the circuit axioms.
+
+        EXAMPLES::
+
+            sage: from sage.matroids.oriented_matroids.oriented_matroid import OrientedMatroid
+            sage: C = [((1,4),(2,3)), ((2,3),(1,4))]
+            sage: M = OrientedMatroid(C, key='circuit')
+            sage: M.is_valid(certificate=True)
+            (True, {})
+            sage: M.is_valid()
+            True
+
+            sage: C2 = [((1,4),(2,3)), ((1,3),(2,4)), ((2,3),(1,4))]
+            sage: M2 = OrientedMatroid(C2, key='circuit')
+            sage: M2.is_valid(certificate=True)
+            (False,
+             {'elt': (+: 1,4
+               -: 2,3
+               0: ,
+               +: 1,3
+               -: 2,4
+               0: ),
+              'msg': 'only same/opposites can have same support'})
+            sage: M2.is_valid()
+            False
+
+            sage: C3 = [((),()), ((1,4),(2,3)), ((2,3),(1,4))]
+            sage: M3 = OrientedMatroid(C3, key='circuit', groundset=[1,2,3,4])
+            sage: M3.is_valid(certificate=True)
+            (False,
+             {'elt': +: 
+               -: 
+               0: 1,2,3,4,
+              'msg': 'empty set not allowed'})
+
+            sage: C4= [((1,),()), ((1,4),(2,3)), ((2,3),(1,4))]
+            sage: M4 = OrientedMatroid(C4, key='circuit', groundset=[1,2,3,4])
+            sage: M4.is_valid(certificate=True)
+            (False,
+             {'elt': +: 1
+               -: 
+               0: 2,3,4,
+              'msg': 'every element needs an opposite'})
+        """
+        circuits = self.circuits()
+
+        for X in circuits:
+            # Axiom 1: Make sure empty is not present
+            if X.is_zero():
+                if certificate:
+                    error_info = {
+                        'msg': "empty set not allowed",
+                        'elt': X
+                        }
+                    return (False, error_info)
+                return False
+            # Axiom 2: (symmetry) Make sure negative exists
+            if -X not in circuits:
+                if certificate:
+                    error_info = {
+                        'msg': "every element needs an opposite",
+                        'elt': X
+                        }
+                    return (False, error_info)
+                return False
+            for Y in circuits:
+                # Axiom 3: (incomparability) supports must not be contained
+                if X.support().issubset(Y.support()):
+                    if X != Y and X != -Y:
+                        if certificate:
+                            error_info = {
+                                'msg': "only same/opposites can have same support",
+                                'elt': (X, Y)
+                                }
+                            return (
+                                False,
+                                error_info
+                            )
+                        return False
+                # Axiom 4: Weak elimination
+                if X != -Y:
+                    E = X.positives().intersection(Y.negatives())
+                    for e in E:
+                        p = X.positives().union(Y.positives())
+                        p.discard(e)
+                        n = X.negatives().union(Y.negatives())
+                        n.discard(e)
+                        found = False
+                        for Z in circuits:
+                            if found:
+                                break
+                            if Z.positives().issubset(p) and Z.negatives().issubset(n):
+                                found = True
+                        if not found:
+                            if certificate:
+                                error_info = {
+                                    'msg': "weak elimination failed",
+                                    'elt': (X, Y)
+                                    }
+                                return (False, error_info)
+                            return False
+        if certificate:
+            return (True, {})
+        return True
+
+    def _repr_(self) -> str:
+        """
+        Return a string representation of ``self``.
+
+        EXAMPLES::
+
+            sage: from sage.matroids.oriented_matroids.oriented_matroid import OrientedMatroid
+            sage: C = [((1,),(2,)), ((2,),(1,)), ((3,),(4,)), ((4,),(3,))]
+            sage: OrientedMatroid(C, key='circuit', groundset=[1,2,3,4])
+            Circuit oriented matroid of rank 2
+        """
+        try:
+            rep = f"Circuit oriented matroid of rank {self.rank()}"
+        except ValueError:
+            rep = "Circuit oriented matroid"
+        return rep
+
+    def matroid(self):
+        r"""
+        Return the underlying matroid.
+
+        Given an oriented matroid defined using circuits, the *underlying
+        matroid* is the (circuit) matroid whose groundset is the groundset of
+        the oriented matroid and the circuits are the set of supports of all
+        the signed subsets.
+
+        EXAMPLES::
+
+            sage: from sage.matroids.oriented_matroids.oriented_matroid import OrientedMatroid
+            sage: C = [((1,),(2,)), ((2,),(1,)), ((3,),(4,)), ((4,),(3,))]
+            sage: M = OrientedMatroid(C, key='circuit', groundset=[1,2,3,4])
+            sage: M.matroid()
+            Matroid of rank 2 on 4 elements with 2 circuits
+        """
+        from sage.matroids.constructor import Matroid
+        circs = list(set([frozenset(X.support()) for X in self.elements()]))
+        return Matroid(groundset=self.groundset(), circuits=circs)