This is Matroids.info, produced by Macaulay2, version 1.24.11

Matroids -- a package for computations with matroids
****************************************************

Description
===========

A matroid is a combinatorial structure abstracting the notion of (linear
algebraic, graph-theoretic) independence. This package provides methods to
perform computations with matroids in Macaulay2.

This package provides capabilities for converting between various
representations of matroids, creating linear and graphic matroids from a matrix
or graph, forming and detecting existence of minors, computing Tutte
polynomials, and additional functions for applications of matroids to areas
like optimization and convex geometry.

Matroids are stored as pairs (E, B) of a ground set E and a list B of bases,
which are maximal independent subsets of the ground set. Internally, a ground
set of size n is always identified with the set $\{0, ..., n-1\}$, and thus all
subsets of the ground set (e.g. bases, circuits, flats) are also treated as
subsets of $\{0, ..., n-1\}$ (for more, cf. groundSet).
However, the actual elements of the ground set are allowed to be arbitrary
(e.g. integers, symbols, vectors, edges in a graph), and can be accessed by
taking subscripts.

+-----------------------------------------------------------------------------+
|i1 : M = matroid({a, matrix{{-1.2},{3.78}}, x, set{4,6}, -9}, {{a, x}, {x,   |
|                                                                             |
|o1 = a "matroid" of rank 2 on 5 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
|-----------------------------------------------------------------------------|
|-9}})                                                                        |
+-----------------------------------------------------------------------------+
|i2 : peek M                                                                  |
|                                                                             |
|o2 = Matroid{bases => {set {0, 2}, set {4, 2}}}                              |
|             cache => CacheTable{...1...}                                    |
|             groundSet => set {0, 1, 2, 3, 4}                                |
|             rank => 2                                                       |
+-----------------------------------------------------------------------------+
|i3 : M_{0,1,4}                                                               |
|                                                                             |
|o3 = {a, | -1.2 |, -9}                                                       |
|         | 3.78 |                                                            |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : peek restriction(M, set{1,2,3})                                         |
|                                                                             |
|o4 = Matroid{bases => {set {1}}          }                                   |
|             cache => CacheTable{...1...}                                    |
|             groundSet => set {0, 1, 2}                                      |
|             rank => 1                                                       |
+-----------------------------------------------------------------------------+
|i5 : circuits M                                                              |
|                                                                             |
|o5 = {set {1}, set {3}, set {4, 0}}                                          |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : netList flats M                                                         |
|                                                                             |
|     +-------------------+                                                   |
|o6 = |set {1, 3}         |                                                   |
|     +-------------------+                                                   |
|     |set {0, 1, 3, 4}   |                                                   |
|     +-------------------+                                                   |
|     |set {1, 2, 3}      |                                                   |
|     +-------------------+                                                   |
|     |set {0, 1, 2, 3, 4}|                                                   |
|     +-------------------+                                                   |
+-----------------------------------------------------------------------------+
|i7 : tuttePolynomial M                                                       |
|                                                                             |
|      2 2      3                                                             |
|o7 = x y  + x*y                                                              |
|                                                                             |
|o7 : ZZ[x..y]                                                                |
+-----------------------------------------------------------------------------+

A matroid can be specified by its bases, nonbases, circuits, from a matrix,
graph, or ideal, or via a collection of predefined matroids. For more on how to
construct a matroid, see matroid.

Reference Oxley, Matroid Theory, second edition. Oxford University Press, 2011.

Contributors
============

The following people have generously contributed code, improved existing code,
or enhanced the documentation: Aaron Dall, Chris Eur, Matthew Mastroeni, Jason
McCullough, Tianyi Zhang.

Author
======

  * Justin Chen <jchen@math.berkeley.edu>

Certification a gold star
=========================

Version 0.9.7 of this package was accepted for publication in volume 9 (see
https://msp.org/jsag/2019/9-1/ ) of The Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 27 September 2018, in the article
Matroids: a Macaulay2 package (see https://msp.org/jsag/2019/9-1/p03.xhtml )
(DOI: 10.2140/jsag.2019.9.19 (see https://doi.org/10.2140/jsag.2019.9.19 )).
That version can be obtained from the journal (see
https://msp.org/jsag/2019/9-1/jsag-v9-n1-x03-Matroids.m2 ) or from the
Macaulay2 source code repository (see
https://github.com/Macaulay2/M2/blob/cf37f5a1eefc2fe7e6eef2868718256106805027/
M2/Macaulay2/packages/Matroids.m2 ).

Version
=======

This documentation describes version 1.7.0 of Matroids.

Source code
===========

The source code from which this documentation is derived is in the file
Matroids.m2 (see common/share/Macaulay2/Matroids.m2 ). The auxiliary files
accompanying it are in the directory Matroids/ (see
common/share/Macaulay2/Matroids/ ).

Exports
=======

  * Types
      * Matroid -- the class of all matroids
  * Functions and commands
      * affineGeometry -- affine geometry of rank n+1
        over F_p
      * allMatroids -- returns all n-element matroids of
        rank r
      * allMinors -- returns all minors of one matroid in
        another
      * bases -- bases of matroid
      * basisIndicatorMatrix -- matrix of basis
        polytope
      * chromaticPolynomial -- computes chromatic
        polynomial of a graph
      * circuits -- circuits of matroid
      * closure -- closure of a subset of a matroid
      * coextension -- the free coextension of a matroid
      * cogeneratorChowRing -- cogenerator of the
        Chow ring of a matroid
      * coloops -- coloops of matroid
      * contraction -- contraction of subset of matroid
      * deletion -- deletion of subset of matroid
      * elementaryQuotient -- associated to a
        modular cut or linear subclass
      * extension -- of a matroid relative to a flat or
        modular cut
      * flats -- flats of a matroid
      * fundamentalCircuit -- fundamental circuit of
        independent set
      * getCycles -- find cycles of graph
      * getIsos -- all isomorphisms between two matroids
      * getRepresentation -- retrieves stored
        representation
      * getSeparation -- finds a k-separation of a
        matroid
      * groundSet -- (internal) ground set
      * hasMinor -- whether a matroid has a given minor
      * idealChowRing -- the defining ideal of the Chow
        ring
      * idealOrlikSolomonAlgebra (missing documentation)
      * indicesOf -- indices of a sublist
      * is3Connected -- whether a matroid is 3-connected
      * isBinary -- whether a matroid is representable over
        F_2
      * isDependent -- whether a subset is dependent
      * isElementaryQuotient -- whether a matroid
        is an elementary quotient of another matroid
      * isLinearSubclass -- whether a list of
        hyperplanes of a matroid is a linear subclass
      * isModularCut -- whether a list of flats of a
        matroid is a modular cut
      * isNonCrossing -- whether 2 subsets are
        non-crossing
      * isoTypes -- distinct isomorphism classes
      * isPositivelyOrientable -- whether a
        matroid is positively orientable
      * isPositivelyOriented -- whether a matroid
        is positively oriented
      * isQuotient -- whether a matroid is a quotient of
        another matroid
      * latticeOfFlats -- lattice of flats of a matroid
      * linearSubclass -- associated to an elementary
        quotient or modular cut
      * loops -- loops of matroid
      * matroid -- constructs a matroid
      * maxWeightBasis -- maximum weight basis using
        greedy algorithm
      * minor -- minor of matroid
      * modularCut -- associated to an elementary quotient
        or linear subclass
      * nonbases -- nonbases of matroid
      * parallelConnection -- parallel connection of
        two matroids
      * positiveOrientation -- a positive
        orientation of a matroid
      * projectiveGeometry -- projective geometry of
        dimension n over F_p
      * quickIsomorphismTest -- quick checks for
        isomorphism between matroids
      * relabel -- relabel a matroid
      * relaxation -- relaxation of matroid
      * restriction -- restriction to subset of matroid
      * "readFromFile" -- see saveMatroid, -- save matroid
        to file
      * saveMatroid -- save matroid to file
      * searchRepresentation -- search for a
        representation of a matroid over a finite field
      * seriesConnection -- series connection of two
        matroids
      * setRepresentation -- stores user-defined
        representation
      * simpleMatroid -- simple matroid associated to a
        matroid
      * specificMatroid -- creates built-in matroid
      * "binarySpike" -- see spike, -- spike matroid
      * spike -- spike matroid
      * sum2 -- 2-sum of matroids
      * swirl -- swirl matroid
      * thetaMatroid -- theta matroid
      * "fromSageMatroid" -- see toSageMatroid, -- Sage
        format for matroid
      * toSageMatroid -- Sage format for matroid
      * tutteEvaluate -- evaluate Tutte polynomial
      * uniformMatroid -- uniform matroid
      * wheel -- wheels/whirls
      * "whirl" -- see wheel, -- wheels/whirls
  * Methods
      * "affineGeometry(ZZ,ZZ)" -- see affineGeometry, --
        affine geometry of rank n+1 over F_p
      * "allMatroids(ZZ)" -- see allMatroids, -- returns all
        n-element matroids of rank r
      * "allMatroids(ZZ,ZZ)" -- see allMatroids, -- returns
        all n-element matroids of rank r
      * "allMinors(Matroid,Matroid)" -- see allMinors, --
        returns all minors of one matroid in another
      * areIsomorphic(Matroid,Matroid)
        -- whether two matroids are
        isomorphic
      * "bases(Matroid)" -- see bases, -- bases of matroid
      * "basisIndicatorMatrix(Matroid)" -- see basisIndicatorMatrix,
        -- matrix of basis polytope
      * characteristicPolynomial(Matroid)
        -- computes characteristic
        polynomial of a matroid
      * "chromaticPolynomial(Graph)" -- see chromaticPolynomial,
        -- computes chromatic polynomial of a graph
      * "circuits(Matroid)" -- see circuits, -- circuits of
        matroid
      * "closure(Matroid,List)" -- see closure, -- closure of a
        subset of a matroid
      * "closure(Matroid,Set)" -- see closure, -- closure of a
        subset of a matroid
      * "coextension(Matroid)" -- see coextension, -- the
        free coextension of a matroid
      * "cogeneratorChowRing(Matroid)" -- see cogeneratorChowRing,
        -- cogenerator of the Chow ring of a matroid
      * "coloops(Matroid)" -- see coloops, -- coloops of matroid
      * components(Matroid) -- connected
        components of matroid
      * "contraction(Matroid,List)" -- see contraction, --
        contraction of subset of matroid
      * "contraction(Matroid,Set)" -- see contraction, --
        contraction of subset of matroid
      * "Matroid / List" -- see contraction, -- contraction
        of subset of matroid
      * "Matroid / Set" -- see contraction, -- contraction
        of subset of matroid
      * "deletion(Matroid,List)" -- see deletion, -- deletion
        of subset of matroid
      * "deletion(Matroid,Set)" -- see deletion, -- deletion of
        subset of matroid
      * /// Matroid \ List /// -- see deletion, -- deletion of
        subset of matroid
      * /// Matroid \ Set /// -- see deletion, -- deletion of
        subset of matroid
      * dual(Matroid) -- dual matroid
      * "elementaryQuotient(Matroid,List)" -- see elementaryQuotient,
        -- associated to a modular cut or linear subclass
      * "extension(Matroid)" -- see extension, -- of a matroid
        relative to a flat or modular cut
      * "extension(Matroid,List)" -- see extension, -- of a
        matroid relative to a flat or modular cut
      * "extension(Matroid,Set)" -- see extension, -- of a
        matroid relative to a flat or modular cut
      * "flats(Matroid)" -- see flats, -- flats of a matroid
      * "flats(Matroid,ZZ)" -- see flats, -- flats of a matroid
      * "flats(Matroid,ZZ,String)" -- see flats, -- flats of a
        matroid
      * "fundamentalCircuit(Matroid,List,Thing)" -- see
        fundamentalCircuit, -- fundamental circuit of
        independent set
      * "fundamentalCircuit(Matroid,Set,ZZ)" -- see fundamentalCircuit,
        -- fundamental circuit of independent set
      * fVector(Matroid) -- f-vector of a matroid
      * "getCycles(Graph)" -- see getCycles, -- find cycles of
        graph
      * "getIsos(Matroid,Matroid)" -- see getIsos, -- all
        isomorphisms between two matroids
      * "getRepresentation(Matroid)" -- see getRepresentation,
        -- retrieves stored representation
      * "getSeparation(Matroid,ZZ)" -- see getSeparation,
        -- finds a k-separation of a matroid
      * "groundSet(Matroid)" -- see groundSet, -- (internal)
        ground set
      * "hasMinor(Matroid,Matroid)" -- see hasMinor, -- whether
        a matroid has a given minor
      * "hyperplanes(Matroid)" -- see hyperplanes, --
        hyperplanes of a matroid
      * ideal(Matroid) -- Stanley-Reisner (circuit)
        ideal of matroid
      * "idealChowRing(Matroid)" -- see idealChowRing, --
        the defining ideal of the Chow ring
      * idealOrlikSolomonAlgebra(Matroid) (missing documentation)
      * independenceComplex(Matroid),
        -- independence complex of matroid
      * "independentSets(Matroid)" -- see independentSets(Matroid,ZZ),
        -- independent subsets of a matroid
      * "independentSets(Matroid,List)" -- see
        independentSets(Matroid,ZZ), --
        independent subsets of a matroid
      * "independentSets(Matroid,Set)" -- see
        independentSets(Matroid,ZZ), --
        independent subsets of a matroid
      * independentSets(Matroid,ZZ),
        -- independent subsets of a matroid
      * "indicesOf(List,List)" -- see indicesOf, -- indices of
        a sublist
      * "indicesOf(Matroid,List)" -- see indicesOf, -- indices
        of a sublist
      * "is3Connected(Matroid)" -- see is3Connected, --
        whether a matroid is 3-connected
      * "isBinary(Matroid)" -- see isBinary, -- whether a
        matroid is representable over F_2
      * isConnected(Matroid) -- whether a
        matroid is connected
      * "isDependent(Matroid,List)" -- see isDependent, --
        whether a subset is dependent
      * "isDependent(Matroid,Set)" -- see isDependent, --
        whether a subset is dependent
      * "isElementaryQuotient(Matroid,Matroid)" -- see
        isElementaryQuotient, -- whether a matroid is an
        elementary quotient of another matroid
      * "isLinearSubclass(Matroid,List)" -- see isLinearSubclass,
        -- whether a list of hyperplanes of a matroid is a
        linear subclass
      * "isModularCut(Matroid,List)" -- see isModularCut,
        -- whether a list of flats of a matroid is a modular cut
      * "isNonCrossing(List,List)" -- see isNonCrossing,
        -- whether 2 subsets are non-crossing
      * "isNonCrossing(Set,Set)" -- see isNonCrossing, --
        whether 2 subsets are non-crossing
      * isomorphism(Matroid,Matroid),
        -- computes an isomorphism between isomorphic matroids
      * "isoTypes(List)" -- see isoTypes, -- distinct
        isomorphism classes
      * "isPositivelyOrientable(Matroid)" -- see isPositivelyOrientable,
        -- whether a matroid is positively orientable
      * "isPositivelyOriented(Matroid)" -- see isPositivelyOriented,
        -- whether a matroid is positively oriented
      * "isQuotient(Matroid,Matroid)" -- see isQuotient, --
        whether a matroid is a quotient of another matroid
      * isSimple(Matroid) -- whether a matroid is
        simple
      * isWellDefined(Matroid) -- whether
        the input is a well-defined matroid
      * "latticeOfFlats(Matroid)" -- see latticeOfFlats,
        -- lattice of flats of a matroid
      * "linearSubclass(Matroid,List)" -- see linearSubclass,
        -- associated to an elementary quotient or modular cut
      * "linearSubclass(Matroid,Matroid)" -- see linearSubclass,
        -- associated to an elementary quotient or modular cut
      * "loops(Matroid)" -- see loops, -- loops of matroid
      * "matroid(Graph)" -- see matroid, -- constructs a matroid
      * "matroid(Ideal)" -- see matroid, -- constructs a matroid
      * "matroid(List)" -- see matroid, -- constructs a matroid
      * "matroid(List,List)" -- see matroid, -- constructs a
        matroid
      * "matroid(List,List,ZZ)" -- see matroid, -- constructs a
        matroid
      * "matroid(List,MonomialIdeal)" -- see matroid, --
        constructs a matroid
      * "matroid(Matrix)" -- see matroid, -- constructs a
        matroid
      * "matroid(ZZ,List)" -- see matroid, -- constructs a
        matroid
      * Matroid + Matroid -- union of matroids
      * Matroid ++ Matroid -- direct sum of matroids
      * Matroid == Matroid -- whether two matroids
        are equal
      * Matroid _ List -- elements of matroid
      * "Matroid _ Set" -- see Matroid _ List, --
        elements of matroid
      * "Matroid _ ZZ" -- see Matroid _ List, --
        elements of matroid
      * "Matroid _*" -- see Matroid _ List, -- elements
        of matroid
      * "maxWeightBasis(Matroid,List)" -- see maxWeightBasis,
        -- maximum weight basis using greedy algorithm
      * "minor(Matroid,List,List)" -- see minor, -- minor of
        matroid
      * "minor(Matroid,Set,Set)" -- see minor, -- minor of matroid
      * "modularCut(Matroid,List)" -- see modularCut, --
        associated to an elementary quotient or linear subclass
      * "modularCut(Matroid,Matroid)" -- see modularCut, --
        associated to an elementary quotient or linear subclass
      * "nonbases(Matroid)" -- see nonbases, -- nonbases of
        matroid
      * "parallelConnection(Matroid,Matroid)" -- see parallelConnection,
        -- parallel connection of two matroids
      * "positiveOrientation(Matroid)" -- see positiveOrientation,
        -- a positive orientation of a matroid
      * "projectiveGeometry(ZZ,ZZ)" -- see projectiveGeometry,
        -- projective geometry of dimension n over F_p
      * "quickIsomorphismTest(Matroid,Matroid)" -- see
        quickIsomorphismTest, -- quick checks for
        isomorphism between matroids
      * rank(Matroid) -- rank of a matroid
      * "rank(Matroid,List)" -- see rank(Matroid,Set),
        -- rank of a subset of a matroid
      * rank(Matroid,Set) -- rank of a subset
        of a matroid
      * "relabel(Matroid)" -- see relabel, -- relabel a matroid
      * "relabel(Matroid,HashTable)" -- see relabel, -- relabel
        a matroid
      * "relabel(Matroid,List)" -- see relabel, -- relabel a
        matroid
      * "relaxation(Matroid)" -- see relaxation, --
        relaxation of matroid
      * "relaxation(Matroid,List)" -- see relaxation, --
        relaxation of matroid
      * "relaxation(Matroid,Set)" -- see relaxation, --
        relaxation of matroid
      * "Matroid | List" -- see restriction, -- restriction
        to subset of matroid
      * "Matroid | Set" -- see restriction, -- restriction
        to subset of matroid
      * "restriction(Matroid,List)" -- see restriction, --
        restriction to subset of matroid
      * "restriction(Matroid,Set)" -- see restriction, --
        restriction to subset of matroid
      * "readFromFile(String)" -- see saveMatroid, -- save
        matroid to file
      * "saveMatroid(Matroid)" -- see saveMatroid, -- save
        matroid to file
      * "saveMatroid(Matroid,String)" -- see saveMatroid, --
        save matroid to file
      * "searchRepresentation(Matroid,GaloisField)" -- see
        searchRepresentation, -- search for a
        representation of a matroid over a finite field
      * "seriesConnection(Matroid,Matroid)" -- see seriesConnection,
        -- series connection of two matroids
      * "setRepresentation(Matroid,Matrix)" -- see setRepresentation,
        -- stores user-defined representation
      * "simpleMatroid(Matroid)" -- see simpleMatroid, --
        simple matroid associated to a matroid
      * "specificMatroid(String)" -- see specificMatroid,
        -- creates built-in matroid
      * "specificMatroid(Symbol)" -- see specificMatroid,
        -- creates built-in matroid
      * "binarySpike(ZZ)" -- see spike, -- spike matroid
      * "spike(ZZ)" -- see spike, -- spike matroid
      * "spike(ZZ,List)" -- see spike, -- spike matroid
      * "sum2(Matroid,Matroid)" -- see sum2, -- 2-sum of matroids
      * "swirl(ZZ)" -- see swirl, -- swirl matroid
      * "thetaMatroid(ZZ)" -- see thetaMatroid, -- theta
        matroid
      * "fromSageMatroid(String)" -- see toSageMatroid, --
        Sage format for matroid
      * "toSageMatroid(Matroid)" -- see toSageMatroid, --
        Sage format for matroid
      * "truncate(Matroid)" -- see truncate(Set,Matroid),
        -- the truncation of a matroid with
        respect to a flat
      * truncate(Set,Matroid) -- the
        truncation of a matroid with respect to a flat
      * truncate(ZZ,Matroid) -- the
        truncation of a matroid with respect to a flat
      * "tutteEvaluate(Matroid,Thing,Thing)" -- see tutteEvaluate,
        -- evaluate Tutte polynomial
      * tuttePolynomial(Matroid) -- Tutte
        polynomial of a matroid
      * "tuttePolynomial(Matroid,Ring)" -- see tuttePolynomial(Matroid),
        -- Tutte polynomial of a matroid
      * "uniformMatroid(ZZ,ZZ)" -- see uniformMatroid, --
        uniform matroid
      * "wheel(ZZ)" -- see wheel, -- wheels/whirls
      * "whirl(ZZ)" -- see wheel, -- wheels/whirls
  * Symbols
      * CheckWellDefined -- an optional argument
      * "ChowRingOptions" -- see idealChowRing, -- the
        defining ideal of the Chow ring
      * "FlatOrder" -- see idealChowRing, -- the defining
        ideal of the Chow ring
      * "Presentation" -- see idealChowRing, -- the
        defining ideal of the Chow ring
      * "Loops" -- see matroid, -- constructs a matroid
      * "ParallelEdges" -- see matroid, -- constructs a matroid
      * "Attempts" -- see searchRepresentation, --
        search for a representation of a matroid over a finite field
      * "storedRepresentation" -- see setRepresentation,
        -- stores user-defined representation

For the programmer
==================

The object Matroids, is a package (Macaulay2Doc).

affineGeometry -- affine geometry of rank n+1 over F_p
******************************************************

Synopsis
========

  * Usage:
        M = affineGeometry(n, p)
  * Inputs:
      * n, an integer (Macaulay2Doc), the dimension of the ambient
        vector space
      * p, an integer (Macaulay2Doc), a prime
  * Outputs:
      * a matroid, the affine geometry of rank n+1 over F_p

Description
===========

The affine geometry of rank n+1 over F_p is the matroid whose ground set
consists of all vectors in a vector space over F_p of dimension n, where
independence is given by affine independence, i.e. vectors are dependent iff
there is a linear combination equaling zero in which the coefficients sum to
zero (equivalently, the vectors are placed in the hyperplane x_0 = 1 in a
vector space of dimension n+1, with ordinary linear independence in the larger
space).

+-----------------------------------------------------------------------------+
|i1 : M = affineGeometry(3, 2)                                                |
|                                                                             |
|o1 = a "matroid" of rank 4 on 8 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : M === specificMatroid "AG32"                                            |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
|i3 : circuits M                                                              |
|                                                                             |
|o3 = {set {0, 1, 2, 3}, set {0, 1, 4, 5}, set {2, 3, 4, 5}, set {0, 2, 4, 6},|
|     ------------------------------------------------------------------------|
|     set {1, 3, 4, 6}, set {1, 2, 5, 6}, set {0, 3, 5, 6}, set {1, 2, 4, 7}, |
|     ------------------------------------------------------------------------|
|     set {0, 3, 4, 7}, set {0, 2, 5, 7}, set {1, 3, 5, 7}, set {0, 1, 6, 7}, |
|     ------------------------------------------------------------------------|
|     set {2, 3, 6, 7}, set {4, 5, 6, 7}}                                     |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : getRepresentation M                                                     |
|                                                                             |
|o4 = | 1 1 1 1 1 1 1 1 |                                                     |
|     | 0 0 0 0 1 1 1 1 |                                                     |
|     | 0 0 1 1 0 0 1 1 |                                                     |
|     | 0 1 0 1 0 1 0 1 |                                                     |
|                                                                             |
|             ZZ 4      ZZ 8                                                  |
|o4 : Matrix (--)  <-- (--)                                                   |
|              2         2                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * projectiveGeometry -- projective geometry of
    dimension n over F_p
  * specificMatroid -- creates built-in matroid

Ways to use affineGeometry:
===========================

  * "affineGeometry(ZZ,ZZ)"

For the programmer
==================

The object affineGeometry, is a method function (Macaulay2Doc).

allMatroids -- returns all n-element matroids of rank r
*******************************************************

Synopsis
========

  * Usage:
        allMatroids n
        allMatroids(n, r)
  * Inputs:
      * n, an integer (Macaulay2Doc), the size of the ground set
      * r, an integer (Macaulay2Doc), the target rank
  * Outputs:
      * a list (Macaulay2Doc), of matroids on n elements

Description
===========

This method returns a list of matroids on n elements of rank r, for small n
(currently, n <= 9). This list is complete for isomorphism types of rank r
matroids on n elements, i.e. every matroid on n elements of rank r is
isomorphic, to a unique matroid in this
list.

This function will silently switch inputs so that the rank r is the smaller of
the two inputs (i.e. allMatroids(3,6) and allMatroids(6,3) return the same
output). If no rank r is provided, then all matroids on n elements are
returned.

One can perform many verifications using this method:

+-----------------------------------------------------------------------------+
|i1 : L = allMatroids 5; #L                                                   |
|                                                                             |
|o2 = 38                                                                      |
+-----------------------------------------------------------------------------+
|i3 : all(L, isWellDefined)                                                   |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+
|i4 : all(subsets(L, 2), S -> quickIsomorphismTest(S#0, S#1) == "false")      |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+
|i5 : tally(L/fVector/values)                                                 |
|                                                                             |
|o5 = Tally{{1, 1} => 5              }                                        |
|        {1, 2, 1} => 6                                                       |
|        {1, 3, 1} => 4                                                       |
|        {1, 3, 3, 1} => 4                                                    |
|        {1, 4, 1} => 2                                                       |
|        {1, 4, 4, 1} => 3                                                    |
|        {1, 4, 6, 1} => 2                                                    |
|        {1, 4, 6, 4, 1} => 2                                                 |
|        {1, 5, 1} => 1                                                       |
|        {1, 5, 5, 1} => 1                                                    |
|        {1, 5, 6, 1} => 1                                                    |
|        {1, 5, 8, 1} => 1                                                    |
|        {1, 5, 8, 5, 1} => 1                                                 |
|        {1, 5, 10, 1} => 1                                                   |
|        {1, 5, 10, 7, 1} => 1                                                |
|        {1, 5, 10, 10, 1} => 1                                               |
|        {1, 5, 10, 10, 5, 1} => 1                                            |
|        {1} => 1                                                             |
|                                                                             |
|o5 : Tally                                                                   |
+-----------------------------------------------------------------------------+
|i6 : smallMatroids = flatten apply(6, i -> allMatroids i); -- all matroids on|
|-----------------------------------------------------------------------------|
|< 6 elements                                                                 |
+-----------------------------------------------------------------------------+
|i7 : #smallMatroids                                                          |
|                                                                             |
|o7 = 70                                                                      |
+-----------------------------------------------------------------------------+

Ways to use allMatroids:
========================

  * "allMatroids(ZZ)"
  * "allMatroids(ZZ,ZZ)"

For the programmer
==================

The object allMatroids, is a method function (Macaulay2Doc).

allMinors -- returns all minors of one matroid in another
*********************************************************

Synopsis
========

  * Usage:
        allMinors(M, N)
  * Inputs:
      * M, a matroid, the ambient matroid
      * N, a matroid, the candidate minor
  * Outputs:
      * a list (Macaulay2Doc), of pairs (S, T), such that M / S \ T
        is isomorphic to N

Description
===========

This method returns a list of all possible ways to realize N as a minor of M.
The output is a list of pairs (S, T) of subsets of the ground set of M such
that minor(M, S, T), is isomorphic to N.

In fact, S will be an independent subset of M, of size = rank M - rank N, and T
will be a coindependent subset of M, of size = #((M/S).groundSet) -
#N.groundSet, which is disjoint from S.

The output of this method should be the empty list iff the output of
hasMinor, is false (for the same input).

+-----------------------------------------------------------------+
|i1 : V = specificMatroid "vamos"                                 |
|                                                                 |
|o1 = a "matroid" of rank 4 on 8 elements                         |
|                                                                 |
|o1 : Matroid                                                     |
+-----------------------------------------------------------------+
|i2 : U25 = uniformMatroid(2,5)                                   |
|                                                                 |
|o2 = a "matroid" of rank 2 on 5 elements                         |
|                                                                 |
|o2 : Matroid                                                     |
+-----------------------------------------------------------------+
|i3 : elapsedTime L = allMinors(V, U25);                          |
| -- .0581936s elapsed                                            |
+-----------------------------------------------------------------+
|i4 : #L                                                          |
|                                                                 |
|o4 = 64                                                          |
+-----------------------------------------------------------------+
|i5 : netList L_{0..4}                                            |
|                                                                 |
|     +----------+-------+                                        |
|o5 = |set {5, 3}|set {2}|                                        |
|     +----------+-------+                                        |
|     |set {5, 3}|set {4}|                                        |
|     +----------+-------+                                        |
|     |set {6, 3}|set {2}|                                        |
|     +----------+-------+                                        |
|     |set {6, 3}|set {7}|                                        |
|     +----------+-------+                                        |
|     |set {5, 6}|set {0}|                                        |
|     +----------+-------+                                        |
+-----------------------------------------------------------------+
|i6 : all(L, pair -> areIsomorphic(U25, minor(V, pair#0, pair#1)))|
|                                                                 |
|o6 = true                                                        |
+-----------------------------------------------------------------+

See also
========

  * minor -- minor of matroid
  * hasMinor -- whether a matroid has a given minor

Ways to use allMinors:
======================

  * "allMinors(Matroid,Matroid)"

For the programmer
==================

The object allMinors, is a method function (Macaulay2Doc).

areIsomorphic(Matroid,Matroid) -- whether two matroids are isomorphic
*********************************************************************

Synopsis
========

  * Function: areIsomorphic (Posets),
  * Usage:
        areIsomorphic(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if the matroids are
        isomorphic, false otherwise

Description
===========

Two matroids are isomorphic if there is a bijection between their ground sets
which induces a bijection between bases, or equivalently, circuits (which is
what this package actually checks, since there are often fewer circuits than
bases).

This method first runs quickIsomorphismTest, then
isomorphism, if the tests are
inconclusive.

+---------------------------------------------+
|i1 : M = matroid({a,b,c},{{a,b},{a,c},{b,c}})|
|                                             |
|o1 = a "matroid" of rank 2 on 3 elements     |
|                                             |
|o1 : Matroid                                 |
+---------------------------------------------+
|i2 : areIsomorphic(M, uniformMatroid(2,3))   |
|                                             |
|o2 = true                                    |
+---------------------------------------------+
|i3 : M0 = matroid({a,b,c},{{a,b},{a,c}})     |
|                                             |
|o3 = a "matroid" of rank 2 on 3 elements     |
|                                             |
|o3 : Matroid                                 |
+---------------------------------------------+
|i4 : areIsomorphic(M, M0)                    |
|                                             |
|o4 = false                                   |
+---------------------------------------------+

Caveat
======

Isomorphism of matroids should not be confused with equality: cf. ==,
for more details.

See also
========

  * isomorphism(Matroid,Matroid), --
    computes an isomorphism between isomorphic matroids
  * getIsos -- all isomorphisms between two matroids
  * quickIsomorphismTest -- quick checks for
    isomorphism between matroids

Ways to use this method:
========================

  * areIsomorphic(Matroid,Matroid),
    -- whether two matroids are isomorphic

bases -- bases of matroid
*************************

Synopsis
========

  * Usage:
        bases M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a list (Macaulay2Doc), of bases

Description
===========

Returns a list of bases of the matroid. The basis elements are represented as
sets of nonnegative integers, which are the indices of the elements in the
ground set that make up a basis element. To get the subset of the ground set
corresponding to a set of indices, use subscripts.

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : bases M                             |
|                                         |
|o2 = {set {0, 1}, set {0, 2}}            |
|                                         |
|o2 : List                                |
+-----------------------------------------+
|i3 : M_((bases M)#0)                     |
|                                         |
|o3 = set {a, b}                          |
|                                         |
|o3 : Set                                 |
+-----------------------------------------+

In this package, bases are the only structure that is always computed upon
creation of a matroid. Additional invariants (such as the ideal,
or circuits) are not precomputed, but are
cached after being computed once. This allows for maximum speed in methods that
need to call the constructor function, many, many times: e.g.
see tuttePolynomial, and hasMinor.

See also
========

  * nonbases -- nonbases of matroid
  * independentSets(Matroid), --
    independent subsets of a matroid
  * Matroid _ List -- elements of matroid

Ways to use bases:
==================

  * "bases(Matroid)"

For the programmer
==================

The object bases, is a method function (Macaulay2Doc).

basisIndicatorMatrix -- matrix of basis polytope
************************************************

Synopsis
========

  * Usage:
        basisIndicatorMatrix M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a matrix (Macaulay2Doc),

Description
===========

The matroid (basis) polytope of a matroid on n elements lives in R^n, and is
the convex hull of the indicator vectors of the bases.

For uniform matroids, the basis polytope is precisely the hypersimplex:

+----------------------------------------+
|i1 : U24 = uniformMatroid(2, 4)         |
|                                        |
|o1 = a "matroid" of rank 2 on 4 elements|
|                                        |
|o1 : Matroid                            |
+----------------------------------------+
|i2 : A = basisIndicatorMatrix U24       |
|                                        |
|o2 = | 1 1 0 1 0 0 |                    |
|     | 1 0 1 0 1 0 |                    |
|     | 0 1 1 0 0 1 |                    |
|     | 0 0 0 1 1 1 |                    |
|                                        |
|              4       6                 |
|o2 : Matrix ZZ  <-- ZZ                  |
+----------------------------------------+

In order to obtain an actual polytope object in M2, one must take the convex
hull of the columns of the indicator matrix, which is provided by either the
Polyhedra or OldPolyhedra package:

+-----------------------------+
|i3 : needsPackage "Polyhedra"|
|                             |
|o3 = Polyhedra               |
|                             |
|o3 : Package                 |
+-----------------------------+
|i4 : P = convexHull A        |
|                             |
|o4 = P                       |
|                             |
|o4 : Polyhedron              |
+-----------------------------+
|i5 : vertices P              |
|                             |
|o5 = | 1 1 0 1 0 0 |         |
|     | 1 0 1 0 1 0 |         |
|     | 0 1 1 0 0 1 |         |
|     | 0 0 0 1 1 1 |         |
|                             |
|              4       6      |
|o5 : Matrix QQ  <-- QQ       |
+-----------------------------+

The Gelfand-Goresky-MacPherson-Serganova (GGMS) theorem characterizes which
polytopes are basis polytopes for a matroid: namely, each edge is of the form
$e_i - e_j$ for some $i, j$, where $e_i$ are the standard basis vectors.

See also
========

  * bases -- bases of matroid
  * independenceComplex(Matroid), --
    independence complex of matroid

Ways to use basisIndicatorMatrix:
=================================

  * "basisIndicatorMatrix(Matroid)"

For the programmer
==================

The object basisIndicatorMatrix, is a method function (Macaulay2Doc).

characteristicPolynomial(Matroid) -- computes characteristic polynomial of a matroid
************************************************************************************

Synopsis
========

  * Function: characteristicPolynomial (Posets),
  * Usage:
        characteristicPolynomial M
  * Inputs:
      * M, a matroid,
  * Optional inputs (Macaulay2Doc),:
      * VariableName (Posets), => ..., default
        value q,
  * Outputs:
      * a ring element (Macaulay2Doc), the characteristic
        polynomial of M

Description
===========

The characteristic polynomial is a particular specialization of the Tutte
polynomial. If M is a matroid of rank r with Tutte polynomial T(x, y), then the
characteristic polynomial of M is given by (-1)^r * T(1 - x, 0).

This function computes the characteristic polynomial as an evaluation of the
Tutte polynomial. If the Tutte polynomial of the matroid has already been
computed, then this function should return the characteristic polynomial
instantaneously.

+-----------------------------------------+
|i1 : M = matroid completeGraph 4         |
|                                         |
|o1 = a "matroid" of rank 3 on 6 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : T = tuttePolynomial M               |
|                                         |
|      3    3     2            2          |
|o2 = x  + y  + 3x  + 4x*y + 3y  + 2x + 2y|
|                                         |
|o2 : ZZ[x..y]                            |
+-----------------------------------------+
|i3 : factor characteristicPolynomial M   |
|                                         |
|o3 = (x - 3)(x - 2)(x - 1)               |
|                                         |
|o3 : Expression of class Product         |
+-----------------------------------------+

Caveat
======

If M = M(G) is a graphic matroid, then the characteristic polynomial of M and
the chromatic polynomial of G differ by a factor of x^k, where k is the number
of connected components of the graph G.

See also
========

  * tuttePolynomial(Matroid) -- Tutte
    polynomial of a matroid
  * chromaticPolynomial -- computes chromatic
    polynomial of a graph

Ways to use this method:
========================

  * characteristicPolynomial(Matroid)
    -- computes characteristic
    polynomial of a matroid

CheckWellDefined -- an optional argument
****************************************

Description
===========

A symbol used as the name of an optional argument provided by the package
Matroids.

Functions with optional argument named CheckWellDefined:
========================================================

  * "relaxation(...,CheckWellDefined=>...)"
  * elementaryQuotient(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut or linear subclass
  * extension(...,CheckWellDefined=>...)
    -- check whether
    the list is a modular cut or linear subclass
  * linearSubclass(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut
  * modularCut(...,CheckWellDefined=>...)
    -- check whether
    the list is a linear subclass

For the programmer
==================

The object CheckWellDefined, is a symbol (Macaulay2Doc).

chromaticPolynomial -- computes chromatic polynomial of a graph
***************************************************************

Synopsis
========

  * Usage:
        chromaticPolynomial G
  * Inputs:
      * G, a graph (Graphs),
  * Outputs:
      * a ring element (Macaulay2Doc), the chromatic
        polynomial of G

Description
===========

The chromatic polynomial is an invariant of a graph that counts the number of
vertex colorings. The value of this polynomial at a natural number n is the
number of ways to color the vertices of G using at most n colors, such that no
adjacent vertices have the same color.

This method computes the chromatic polynomial as a multiple of the
characteristic polynomial of the graphic matroid. Indeed, if M = M(G) is the
graphic matroid corresponding to a graph G, then the chromatic polynomial of G
equals the characteristic polynomial of M times x^k, where k is the number of
connected components of G (which is distinct from the number of
components, of M).

+---------------------------------------------------------+
|i1 : factor chromaticPolynomial cycleGraph 7             |
|                                                         |
|                        2            2                   |
|o1 = (x)(x - 2)(x - 1)(x  - 3x + 3)(x  - x + 1)          |
|                                                         |
|o1 : Expression of class Product                         |
+---------------------------------------------------------+
|i2 : factor characteristicPolynomial matroid cycleGraph 7|
|                                                         |
|                     2            2                      |
|o2 = (x - 2)(x - 1)(x  - 3x + 3)(x  - x + 1)             |
|                                                         |
|o2 : Expression of class Product                         |
+---------------------------------------------------------+

The Four Color Theorem states that if G is a planar graph, then its chromatic
polynomial has value > 0 at n = 4. In accordance with this, we see that K5 is
not planar (on the other hand, note that K_{3,3} is bipartite, hence
2-colorable):

+-----------------------------------------------+
|i3 : factor chromaticPolynomial completeGraph 5|
|                                               |
|o3 = (x)(x - 4)(x - 3)(x - 2)(x - 1)           |
|                                               |
|o3 : Expression of class Product               |
+-----------------------------------------------+

See also
========

  * tuttePolynomial(Matroid) -- Tutte
    polynomial of a matroid
  * characteristicPolynomial(Matroid)
    -- computes characteristic
    polynomial of a matroid

Ways to use chromaticPolynomial:
================================

  * "chromaticPolynomial(Graph)"

For the programmer
==================

The object chromaticPolynomial, is a method function (Macaulay2Doc).

circuits -- circuits of matroid
*******************************

Synopsis
========

  * Usage:
        circuits M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a list (Macaulay2Doc), of circuits

Description
===========

The circuits of a matroid are the minimal dependent subsets of the ground set.

Just as with bases, and nonbases, circuits are
stored via their indices (rather than the elements of the ground set
themselves).

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : circuits M                          |
|                                         |
|o2 = {set {1, 2}, set {3}}               |
|                                         |
|o2 : List                                |
+-----------------------------------------+

See also
========

  * ideal(Matroid) -- Stanley-Reisner (circuit)
    ideal of matroid
  * fundamentalCircuit -- fundamental circuit of
    independent set
  * loops -- loops of matroid

Ways to use circuits:
=====================

  * "circuits(Matroid)"

For the programmer
==================

The object circuits, is a method function (Macaulay2Doc).

closure -- closure of a subset of a matroid
*******************************************

Synopsis
========

  * Usage:
        closure(M, S)
  * Inputs:
      * M, a matroid,
      * S, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M
  * Outputs:
      * a list (Macaulay2Doc),

Description
===========

The closure of a subset S of a matroid (E, B) is the set cl(S) := {x $\in$ E :
rank(S) = rank(S $\cup \{x\}$) }. The closure operator 2^E -> 2^E, S $\mapsto$
cl(S), completely determines the matroid (indeed, the maximal proper closed
sets - i.e. see hyperplanes, - already determine the matroid).

+-----------------------------------------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})                                    |
|                                                                             |
|o1 = a "matroid" of rank 2 on 4 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : for s in subsets M_* do print(toString s | " has closure " | toString   |
|{} has closure {3}                                                           |
|{a} has closure {0, 3}                                                       |
|{b} has closure {1, 2, 3}                                                    |
|{a, b} has closure {0, 1, 2, 3}                                              |
|{c} has closure {1, 2, 3}                                                    |
|{a, c} has closure {0, 1, 2, 3}                                              |
|{b, c} has closure {1, 2, 3}                                                 |
|{a, b, c} has closure {0, 1, 2, 3}                                           |
|{d} has closure {3}                                                          |
|{a, d} has closure {0, 3}                                                    |
|{b, d} has closure {1, 2, 3}                                                 |
|{a, b, d} has closure {0, 1, 2, 3}                                           |
|{c, d} has closure {1, 2, 3}                                                 |
|{a, c, d} has closure {0, 1, 2, 3}                                           |
|{b, c, d} has closure {1, 2, 3}                                              |
|{a, b, c, d} has closure {0, 1, 2, 3}                                        |
|-----------------------------------------------------------------------------|
|closure_M s)                                                                 |
+-----------------------------------------------------------------------------+
|i3 : F = flats M                                                             |
|                                                                             |
|o3 = {set {3}, set {1, 2, 3}, set {0, 3}, set {0, 1, 2, 3}}                  |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : all(F, f -> closure_M f === f)                                          |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * flats -- flats of a matroid

Ways to use closure:
====================

  * "closure(Matroid,List)"
  * "closure(Matroid,Set)"

For the programmer
==================

The object closure, is a method function (Macaulay2Doc).

coextension -- the free coextension of a matroid
************************************************

Synopsis
========

  * Usage:
        coextension M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a matroid, the free coextension of the matroid

Description
===========

This function is provided by the package Matroids.

A matroid N is a coextension of the matroid M if the dual of M is an extension
of the dual of N.  The free coextension of M is the dual of the free extension
of the dual of M.  The free coextension of a uniform matroid U_{r,n} is
U_{r+1,n+1}.

+--------------------------------------------------+
|i1 : M = uniformMatroid(3, 4);                    |
+--------------------------------------------------+
|i2 : N = coextension M                            |
|                                                  |
|o2 = a "matroid" of rank 4 on 5 elements          |
|                                                  |
|o2 : Matroid                                      |
+--------------------------------------------------+
|i3 : quickIsomorphismTest(N, uniformMatroid(4, 5))|
|                                                  |
|o3 = true                                         |
+--------------------------------------------------+

The free coextension N is a matroid whose ground set is the ground set of M
plus one additional element e.  Flats of the free coextension come in one of
two types: They are either independent sets of M or sets containing e that
become flats of M after removing e.

+-----------------------------------------------------------------------------+
|i4 : M = matroid completeGraph 3;                                            |
+-----------------------------------------------------------------------------+
|i5 : partition(I -> #I, independentSets M)                                   |
|                                                                             |
|o5 = HashTable{0 => {set {}}                            }                    |
|               1 => {set {1}, set {2}, set {0}}                              |
|               2 => {set {1, 2}, set {0, 2}, set {0, 1}}                     |
|                                                                             |
|o5 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i6 : partition(F -> rank(M, F), flats M)                                     |
|                                                                             |
|o6 = HashTable{0 => {set {}}                   }                             |
|               1 => {set {2}, set {1}, set {0}}                              |
|               2 => {set {0, 1, 2}}                                          |
|                                                                             |
|o6 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i7 : N = coextension M                                                       |
|                                                                             |
|o7 = a "matroid" of rank 3 on 4 elements                                     |
|                                                                             |
|o7 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i8 : partition(F -> rank(N, F), flats N)                                     |
|                                                                             |
|o8 = HashTable{0 => {set {}}                                                 |
|               1 => {set {3}, set {2}, set {1}, set {0}}                     |
|               2 => {set {2, 3}, set {1, 3}, set {0, 3}, set {1, 2}, set {0, |
|               3 => {set {0, 1, 2, 3}}                                       |
|                                                                             |
|o8 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|               }                                                             |
|                                                                             |
|2}, set {0, 1}}                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * extension -- of a matroid relative to a flat or modular
    cut

Ways to use coextension:
========================

  * "coextension(Matroid)"

For the programmer
==================

The object coextension, is a method function (Macaulay2Doc).

cogeneratorChowRing -- cogenerator of the Chow ring of a matroid
****************************************************************

Synopsis
========

  * Usage:
        cogeneratorChowRing M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a ring element (Macaulay2Doc), the dual socle
        generator of the Chow ring of M

Description
===========

If R is an Artinian Gorenstein k-algebra, then the Macaulay inverse system of R
is generated by a single polynomial (in dual/differential variables), called
the cogenerator (or dual socle generator) of R. By a result of Adiprasito,
Katz, and Huh, the Chow ring of a matroid M is always Gorenstein. This function
computes the cogenerator of the Chow ring of M, which is also called the volume
polynomial of M. Note that this is a very fine invariant of M - indeed, this
single polynomial can recover the entire Chow ring of M, and thus most of the
lattice of flats of M.

+-----------------------------------------------------------------------------+
|i1 : M = matroid completeGraph 4                                             |
|                                                                             |
|o1 = a "matroid" of rank 3 on 6 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : I = idealChowRing M;                                                    |
|                                                                             |
|o2 : Ideal of QQ[x   , x   , x   , x   , x   , x   , x         , x         , |
|                  {5}   {4}   {3}   {2}   {1}   {0}   {3, 4, 5}   {1, 2, 5}  |
|-----------------------------------------------------------------------------|
|x      , x         , x      , x      , x         ]                           |
| {0, 5}   {0, 2, 4}   {1, 4}   {2, 3}   {0, 1, 3}                            |
+-----------------------------------------------------------------------------+
|i3 : betti I                                                                 |
|                                                                             |
|            0  1                                                             |
|o3 = total: 1 65                                                             |
|         0: 1  5                                                             |
|         1: . 60                                                             |
|                                                                             |
|o3 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i4 : F = cogeneratorChowRing M                                               |
|                                                                             |
|       2       2       2       2       2       2                             |
|o4 = 2t    + 2t    + 2t    + 2t    + 2t    + 2t    - 2t   t          -       |
|       {5}     {4}     {3}     {2}     {1}     {0}     {5} {3, 4, 5}         |
|     ------------------------------------------------------------------------|
|                                          2                                  |
|     2t   t          - 2t   t          + t          - 2t   t          -      |
|       {4} {3, 4, 5}     {3} {3, 4, 5}    {3, 4, 5}     {5} {1, 2, 5}        |
|     ------------------------------------------------------------------------|
|                                          2                                  |
|     2t   t          - 2t   t          + t          - 2t   t       -         |
|       {2} {1, 2, 5}     {1} {1, 2, 5}    {1, 2, 5}     {5} {0, 5}           |
|     ------------------------------------------------------------------------|
|                     2                                                       |
|     2t   t       + t       - 2t   t          - 2t   t          - 2t   t     |
|       {0} {0, 5}    {0, 5}     {4} {0, 2, 4}     {2} {0, 2, 4}     {0} {0,  |
|     ------------------------------------------------------------------------|
|              2                                          2                   |
|           + t          - 2t   t       - 2t   t       + t       - 2t   t     |
|     2, 4}    {0, 2, 4}     {4} {1, 4}     {1} {1, 4}    {1, 4}     {3} {2,  |
|     ------------------------------------------------------------------------|
|                          2                                                  |
|        - 2t   t       + t       - 2t   t          - 2t   t          -       |
|     3}     {2} {2, 3}    {2, 3}     {3} {0, 1, 3}     {1} {0, 1, 3}         |
|     ------------------------------------------------------------------------|
|                        2                                                    |
|     2t   t          + t                                                     |
|       {0} {0, 1, 3}    {0, 1, 3}                                            |
|                                                                             |
|o4 : QQ[t   , t   , t   , t   , t   , t   , t         , t         , t      , |
|         {5}   {4}   {3}   {2}   {1}   {0}   {3, 4, 5}   {1, 2, 5}   {0, 5}  |
|-----------------------------------------------------------------------------|
|t         , t      , t      , t         ]                                    |
| {0, 2, 4}   {1, 4}   {2, 3}   {0, 1, 3}                                     |
+-----------------------------------------------------------------------------+
|i5 : T = ring F                                                              |
|                                                                             |
|o5 = T                                                                       |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : diff(gens((map(T, ring I, gens T)) I), F)                               |
|                                                                             |
|o6 = 0                                                                       |
|                                                                             |
|             1      65                                                       |
|o6 : Matrix T  <-- T                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * latticeOfFlats -- lattice of flats of a matroid
  * idealChowRing -- the defining ideal of the Chow ring

Ways to use cogeneratorChowRing:
================================

  * "cogeneratorChowRing(Matroid)"

For the programmer
==================

The object cogeneratorChowRing, is a method function (Macaulay2Doc).

coloops -- coloops of matroid
*****************************

Synopsis
========

  * Usage:
        coloops M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a list (Macaulay2Doc),

Description
===========

The coloops of a matroid M are the loops of the dual,
matroid. The set of coloops of M equals both the intersection of the
bases, of M, and the complement of the union of the circuits,
of M.

+----------------------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})                 |
|                                                          |
|o1 = a "matroid" of rank 2 on 4 elements                  |
|                                                          |
|o1 : Matroid                                              |
+----------------------------------------------------------+
|i2 : circuits M                                           |
|                                                          |
|o2 = {set {1, 2}, set {3}}                                |
|                                                          |
|o2 : List                                                 |
+----------------------------------------------------------+
|i3 : C = set coloops M                                    |
|                                                          |
|o3 = set {0}                                              |
|                                                          |
|o3 : Set                                                  |
+----------------------------------------------------------+
|i4 : C === M.groundSet - fold(circuits M, (a, b) -> a + b)|
|                                                          |
|o4 = true                                                 |
+----------------------------------------------------------+
|i5 : C === fold(bases M, (a, b) -> a*b)                   |
|                                                          |
|o5 = true                                                 |
+----------------------------------------------------------+
|i6 : M_C                                                  |
|                                                          |
|o6 = set {a}                                              |
|                                                          |
|o6 : Set                                                  |
+----------------------------------------------------------+
|i7 : D = dual M; peek D                                   |
|                                                          |
|o8 = Matroid{bases => {set {2, 3}, set {1, 3}}}           |
|             cache => CacheTable{...2...}                 |
|             groundSet => set {0, 1, 2, 3}                |
|             rank => 2                                    |
+----------------------------------------------------------+
|i9 : coloops matroid completeGraph 4 == {}                |
|                                                          |
|o9 = true                                                 |
+----------------------------------------------------------+

See also
========

  * loops -- loops of matroid
  * dual(Matroid) -- dual matroid

Ways to use coloops:
====================

  * "coloops(Matroid)"

For the programmer
==================

The object coloops, is a method function (Macaulay2Doc).

components(Matroid) -- connected components of matroid
******************************************************

Synopsis
========

  * Function: components (Macaulay2Doc),
  * Usage:
        components M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a list (Macaulay2Doc), the connected components of M

Description
===========

Define an equivalence relation ~ on the ground set of M by e ~ f if e = f or
$\{e,f\}$ is contained in a circuit. The equivalence classes under ~ are the
connected components of M. A matroid is the direct sum of its connected
components.

+-----------------------------------------------------------------------------+
|i1 : M = matroid graph({{0,1},{0,2},{1,2},{3,4},{4,5}})                      |
|                                                                             |
|o1 = a "matroid" of rank 4 on 5 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : C = components M                                                        |
|                                                                             |
|o2 = {a "matroid" of rank 1 on 1 elements, a "matroid" of rank 1 on 1        |
|     ------------------------------------------------------------------------|
|     elements, a "matroid" of rank 2 on 3 elements}                          |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : areIsomorphic(M, fold(C, (a, b) -> a ++ b))                             |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+
|i4 : G = graph({{0,1},{0,2},{0,3},{0,4},{1,2},{3,4}})                        |
|                                                                             |
|o4 = Graph{0 => {1, 2, 3, 4}}                                                |
|           1 => {0, 2}                                                       |
|           2 => {0, 1}                                                       |
|           3 => {0, 4}                                                       |
|           4 => {0, 3}                                                       |
|                                                                             |
|o4 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i5 : isConnected G                                                           |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : components matroid G                                                    |
|                                                                             |
|o6 = {a "matroid" of rank 2 on 3 elements, a "matroid" of rank 2 on 3        |
|     ------------------------------------------------------------------------|
|     elements}                                                               |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

As the examples above show, the connected components of the graphic matroid
M(G) need not be the same as the connected components of the graph G (indeed,
for any graph G, there exists a connected graph H with M(G) isomorphic to
M(H)).

See also
========

  * circuits -- circuits of matroid
  * Matroid ++ Matroid -- direct sum of matroids

Ways to use this method:
========================

  * components(Matroid) -- connected components
    of matroid

contraction -- contraction of subset of matroid
***********************************************

Synopsis
========

  * Usage:
        contraction(M, S)
        M / S
  * Inputs:
      * M, a matroid,
      * S, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M
  * Outputs:
      * a matroid, the contraction M / S

Description
===========

The contraction of M by S is given by M/S := (M* \ S)*, where * stands for
dual, and \ is deletion.

+------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}}) |
|                                          |
|o1 = a "matroid" of rank 2 on 4 elements  |
|                                          |
|o1 : Matroid                              |
+------------------------------------------+
|i2 : N = M / {c}                          |
|                                          |
|o2 = a "matroid" of rank 1 on 3 elements  |
|                                          |
|o2 : Matroid                              |
+------------------------------------------+
|i3 : peek N                               |
|                                          |
|o3 = Matroid{bases => {set {0}}          }|
|             cache => CacheTable{...2...} |
|             groundSet => set {0, 1, 2}   |
|             rank => 1                    |
+------------------------------------------+
|i4 : N == M / set{2}                      |
|                                          |
|o4 = true                                 |
+------------------------------------------+

See also
========

  * deletion -- deletion of subset of matroid
  * dual(Matroid) -- dual matroid
  * minor -- minor of matroid

Ways to use contraction:
========================

  * "contraction(Matroid,List)"
  * "contraction(Matroid,Set)"

For the programmer
==================

The object contraction, is a method function (Macaulay2Doc).

deletion -- deletion of subset of matroid
*****************************************

Synopsis
========

  * Usage:
        deletion(M, S)
        M \ S
  * Inputs:
      * M, a matroid,
      * S, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M
  * Outputs:
      * a matroid, the deletion M \ S

Description
===========

The deletion M \ S is obtained by restricting to the complement of S.

+------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}}) |
|                                          |
|o1 = a "matroid" of rank 2 on 4 elements  |
|                                          |
|o1 : Matroid                              |
+------------------------------------------+
|i2 : N = M \ {a}                          |
|                                          |
|o2 = a "matroid" of rank 1 on 3 elements  |
|                                          |
|o2 : Matroid                              |
+------------------------------------------+
|i3 : peek N                               |
|                                          |
|o3 = Matroid{bases => {set {0}, set {1}} }|
|             cache => CacheTable{...1...} |
|             groundSet => set {0, 1, 2}   |
|             rank => 1                    |
+------------------------------------------+
|i4 : N == M \ set{0}                      |
|                                          |
|o4 = true                                 |
+------------------------------------------+

See also
========

  * restriction -- restriction to subset of matroid
  * contraction -- contraction of subset of matroid
  * minor -- minor of matroid

Ways to use deletion:
=====================

  * "deletion(Matroid,List)"
  * "deletion(Matroid,Set)"

For the programmer
==================

The object deletion, is a method function (Macaulay2Doc).

dual(Matroid) -- dual matroid
*****************************

Synopsis
========

  * Function: dual (Macaulay2Doc),
  * Usage:
        dual M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a matroid, the dual matroid of M

Description
===========

The dual matroid of a matroid M has the same ground set as M, and bases equal
to the complements of bases of M.

Duality is a fundamental operation in matroid theory: for nearly any
property/operation of matroids, there is a corresponding dual version, usually
denoted with the prefix "co-". For instance, coloops are loops of the dual, and
contraction is dual to deletion.

In this package, every dual matroid is created as a matroid-dual matroid pair,
and each is cached as the dual of the other. Often the ideal of the dual
matroid has a significantly different number of generators, so many algorithms
in this package will use an equivalent check for the ideal with fewer
generators.

+--------------------------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})                     |
|                                                              |
|o1 = a "matroid" of rank 2 on 4 elements                      |
|                                                              |
|o1 : Matroid                                                  |
+--------------------------------------------------------------+
|i2 : D = dual M                                               |
|                                                              |
|o2 = a "matroid" of rank 2 on 4 elements                      |
|                                                              |
|o2 : Matroid                                                  |
+--------------------------------------------------------------+
|i3 : peek D                                                   |
|                                                              |
|o3 = Matroid{bases => {set {2, 3}, set {1, 3}}}               |
|             cache => CacheTable{...2...}                     |
|             groundSet => set {0, 1, 2, 3}                    |
|             rank => 2                                        |
+--------------------------------------------------------------+
|i4 : M == dual D                                              |
|                                                              |
|o4 = true                                                     |
+--------------------------------------------------------------+
|i5 : loops D == coloops M                                     |
|                                                              |
|o5 = true                                                     |
+--------------------------------------------------------------+
|i6 : hyperplanes M === apply(circuits D, C -> D.groundSet - C)|
|                                                              |
|o6 = true                                                     |
+--------------------------------------------------------------+

A matroid that is isomorphic, to
its dual is called self-dual; and a matroid that is equal,
to its dual is called identically self-dual.

+-----------------------------------------+
|i7 : V8plus = specificMatroid "V8+"      |
|                                         |
|o7 = a "matroid" of rank 4 on 8 elements |
|                                         |
|o7 : Matroid                             |
+-----------------------------------------+
|i8 : V8plus == dual V8plus               |
|                                         |
|o8 = true                                |
+-----------------------------------------+
|i9 : V = relaxation(V8plus, set{4,5,6,7})|
|                                         |
|o9 = a "matroid" of rank 4 on 8 elements |
|                                         |
|o9 : Matroid                             |
+-----------------------------------------+
|i10 : V == dual V                        |
|                                         |
|o10 = false                              |
+-----------------------------------------+
|i11 : areIsomorphic(V, dual V)           |
|                                         |
|o11 = true                               |
+-----------------------------------------+

If a matroid has a representation, stored, then this
function will attempt to automatically compute a representation for the dual
(whether this works depends on whether reducedRowEchelonForm (Macaulay2Doc),
is implemented for the underlying ring of
the matrix).

+-----------------------------------------+
|i12 : F7 = specificMatroid fano          |
|                                         |
|o12 = a "matroid" of rank 3 on 7 elements|
|                                         |
|o12 : Matroid                            |
+-----------------------------------------+
|i13 : getRepresentation F7               |
|                                         |
|o13 = | 1 1 1 1 0 0 0 |                  |
|      | 0 0 1 1 1 1 0 |                  |
|      | 0 1 0 1 0 1 1 |                  |
|                                         |
|              ZZ 3      ZZ 7             |
|o13 : Matrix (--)  <-- (--)              |
|               2         2               |
+-----------------------------------------+
|i14 : M = dual F7                        |
|                                         |
|o14 = a "matroid" of rank 4 on 7 elements|
|                                         |
|o14 : Matroid                            |
+-----------------------------------------+
|i15 : getRepresentation M                |
|                                         |
|o15 = | 1 1 1 1 0 0 0 |                  |
|      | 1 0 1 0 1 0 0 |                  |
|      | 0 1 1 0 0 1 0 |                  |
|      | 1 1 0 0 0 0 1 |                  |
|                                         |
|              ZZ 4      ZZ 7             |
|o15 : Matrix (--)  <-- (--)              |
|               2         2               |
+-----------------------------------------+

Ways to use this method:
========================

  * dual(Matroid) -- dual matroid

elementaryQuotient -- associated to a modular cut or linear subclass
********************************************************************

Synopsis
========

  * Usage:
        elementaryQuotient(M, L)
  * Inputs:
      * M, a matroid,
      * L, a list (Macaulay2Doc), a list of flats or hyperplanes of
        the matroid forming a modular cut/linear subclass
  * Optional inputs (Macaulay2Doc),:
      * CheckWellDefined,
        =>
        ..., default value false, check whether the list is a modular cut or
        linear subclass
      * EntryMode,
        => ..., default value "modular cut", use a modular cut or linear
        subclass
  * Outputs:
      * a matroid, the elementary quotient of the matroid
        associated to modular cut/linear subclass

Description
===========

This function is provided by the package Matroids.

An elementary quotient a matroid M is a matroid on the same ground set that is
a quotient matroid of M having rank equal to the rank of M minus one.  Every
elementary quotient is completely determined by a modular cut of flats of M.
See isModularCut, for more details about modular cuts.  The
elementary quotient of M corresponding to a modular cut K is the extension of M
by a single element e associated to K followed by the contraction of the set
{e}.

+--------------------------------------------------------------------+
|i1 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}|
|                                                                    |
|o1 = | 1 0 0 1 1  |                                                 |
|     | 0 1 0 1 -1 |                                                 |
|     | 0 0 1 0 0  |                                                 |
|                                                                    |
|              3       5                                             |
|o1 : Matrix ZZ  <-- ZZ                                              |
+--------------------------------------------------------------------+
|i2 : M = matroid A                                                  |
|                                                                    |
|o2 = a "matroid" of rank 3 on 5 elements                            |
|                                                                    |
|o2 : Matroid                                                        |
+--------------------------------------------------------------------+
|i3 : K = {{2}, {2, 4}, {2, 3}, {1, 2}, {0, 2}, {0, 1, 2, 3, 4}};    |
+--------------------------------------------------------------------+
|i4 : isModularCut(M, K)                                             |
|                                                                    |
|o4 = true                                                           |
+--------------------------------------------------------------------+
|i5 : Q1 = elementaryQuotient(M, K)                                  |
|                                                                    |
|o5 = a "matroid" of rank 2 on 5 elements                            |
|                                                                    |
|o5 : Matroid                                                        |
+--------------------------------------------------------------------+

Equivalently since, a modular cut K of the matroid M is completely determined
by a collection of hyperplanes of M called a linear subclass, we can form an
elementary quotient by specifying a much shorter list of hyperplanes as
follows.  See isLinearSubclass, for more details about
linear subclasses.

+--------------------------------------------------------------+
|i6 : H = linearSubclass(M, K)                                 |
|                                                              |
|o6 = {set {0, 2}, set {4, 2}, set {1, 2}, set {2, 3}}         |
|                                                              |
|o6 : List                                                     |
+--------------------------------------------------------------+
|i7 : Q2 = elementaryQuotient(M, H, EntryMode => "hyperplanes")|
|                                                              |
|o7 = a "matroid" of rank 2 on 5 elements                      |
|                                                              |
|o7 : Matroid                                                  |
+--------------------------------------------------------------+
|i8 : Q1 == Q2                                                 |
|                                                              |
|o8 = true                                                     |
+--------------------------------------------------------------+

See also
========

  * isElementaryQuotient -- whether a matroid is
    an elementary quotient of another matroid
  * isLinearSubclass -- whether a list of hyperplanes
    of a matroid is a linear subclass
  * isModularCut -- whether a list of flats of a matroid
    is a modular cut
  * isQuotient -- whether a matroid is a quotient of another
    matroid
  * linearSubclass -- associated to an elementary
    quotient or modular cut
  * modularCut -- associated to an elementary quotient or
    linear subclass

Ways to use elementaryQuotient:
===============================

  * "elementaryQuotient(Matroid,List)"

For the programmer
==================

The object elementaryQuotient, is a method function with options (Macaulay2Doc).

elementaryQuotient(...,CheckWellDefined=>...) -- check whether the list is a modular cut or linear subclass
***********************************************************************************************************

Synopsis
========

  * Usage:
        elementaryQuotient(M, L, CheckWellDefined => true)
  * Inputs:
      * M, a matroid,
      * L, a list (Macaulay2Doc), a list of flats or hyperplanes of
        the matroid forming a modular cut/linear subclass
  * Outputs:
      * a matroid, the elementary quotient of the matroid
        associated to modular cut/linear subclass

Description
===========

This option is provided by the package Matroids.

When producing the elementary quotient of a matroid M corresponding to a list
of flats or hyperplanes L, setting this option to true calls
isModularCut, or isLinearSubclass, to
check that the list is a modular cut or linear subclass respectively.

+-----------------------------------------------------------------------------+
|i1 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}         |
|                                                                             |
|o1 = | 1 0 0 1 1  |                                                          |
|     | 0 1 0 1 -1 |                                                          |
|     | 0 0 1 0 0  |                                                          |
|                                                                             |
|              3       5                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i2 : M = matroid A                                                           |
|                                                                             |
|o2 = a "matroid" of rank 3 on 5 elements                                     |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : K = modularCut(M, drop(hyperplanes M, 1))                               |
|                                                                             |
|o3 = {set {2}, set {4, 2}, set {2, 3}, set {1, 2}, set {0, 2}, set {0, 1, 2, |
|     ------------------------------------------------------------------------|
|     3, 4}}                                                                  |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : elementaryQuotient(M, K, CheckWellDefined => true)                      |
|                                                                             |
|o4 = a "matroid" of rank 2 on 5 elements                                     |
|                                                                             |
|o4 : Matroid                                                                 |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: elementaryQuotient, -- associated to a
    modular cut or linear subclass
  * Option key: CheckWellDefined, -- an optional
    argument

See also
========

  * elementaryQuotient -- associated to a modular
    cut or linear subclass

Functions with optional argument named CheckWellDefined:
========================================================

  * "relaxation(...,CheckWellDefined=>...)" -- see CheckWellDefined,
    -- an optional argument
  * elementaryQuotient(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut or linear subclass
  * extension(...,CheckWellDefined=>...)
    -- check whether
    the list is a modular cut or linear subclass
  * linearSubclass(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut
  * modularCut(...,CheckWellDefined=>...)
    -- check whether
    the list is a linear subclass

elementaryQuotient(...,EntryMode=>...) -- use a modular cut or linear subclass
******************************************************************************

Synopsis
========

  * Usage:
        elementaryQuotient(M, L, Entry => "hyperplanes")
  * Inputs:
      * M, a matroid,
      * L, a list (Macaulay2Doc), a list of flats or hyperplanes of
        the matroid forming a modular cut/linear subclass
  * Outputs:
      * a matroid, the elementary quotient of the matroid
        associated to modular cut/linear subclass

Description
===========

This option is provided by the package Matroids.

An elementary quotient of a matroid M can be produced from a list of flats
forming a modular cut of M or a list of hyperplanes of M forming a linear
subclass.  By default, it is assumed the specified list is a modular cut, but
setting this option to "hyperplanes" allows passing a much shorter list of
hyperplanes forming a linear subclass instead.

+--------------------------------------------------------------------+
|i1 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}|
|                                                                    |
|o1 = | 1 0 0 1 1  |                                                 |
|     | 0 1 0 1 -1 |                                                 |
|     | 0 0 1 0 0  |                                                 |
|                                                                    |
|              3       5                                             |
|o1 : Matrix ZZ  <-- ZZ                                              |
+--------------------------------------------------------------------+
|i2 : M = matroid A                                                  |
|                                                                    |
|o2 = a "matroid" of rank 3 on 5 elements                            |
|                                                                    |
|o2 : Matroid                                                        |
+--------------------------------------------------------------------+
|i3 : H = drop(hyperplanes M, 1)                                     |
|                                                                    |
|o3 = {set {4, 2}, set {2, 3}, set {1, 2}, set {0, 2}}               |
|                                                                    |
|o3 : List                                                           |
+--------------------------------------------------------------------+
|i4 : elementaryQuotient(M, H, EntryMode => "hyperplanes")           |
|                                                                    |
|o4 = a "matroid" of rank 2 on 5 elements                            |
|                                                                    |
|o4 : Matroid                                                        |
+--------------------------------------------------------------------+

Further information
===================

  * Default value: modular cut
  * Function: elementaryQuotient, -- associated to a
    modular cut or linear subclass
  * Option key: EntryMode (Graphs), -- Constructs a simple graph

See also
========

  * elementaryQuotient -- associated to a modular
    cut or linear subclass

Functions with optional argument named EntryMode:
=================================================

  * digraph(...,EntryMode=>...) (missing documentation)
  * elementaryQuotient(...,EntryMode=>...)
    -- use a modular
    cut or linear subclass
  * extension(...,EntryMode=>...)
    -- use a modular cut or
    linear subclass
  * "graph(...,EntryMode=>...)" -- see graph (Graphs), --
    Constructs a simple graph
  * matroid(...,EntryMode=>...)
    -- select method of
    specifying matroid

extension -- of a matroid relative to a flat or modular cut
***********************************************************

Synopsis
========

  * Usage:
        extension(M, L),
        extension(M, F),
        extension M
  * Inputs:
      * M, a matroid,
      * L, a list (Macaulay2Doc), a list of flats or hyperplanes of
        the matroid forming a modular cut/linear subclass
      * F, a set (Macaulay2Doc), a flat of the matroid
  * Optional inputs (Macaulay2Doc),:
      * CheckWellDefined,
        => ..., default
        value false, check whether the list is a modular cut or linear subclass
      * EntryMode, =>
        ..., default value "modular cut", use a modular cut or linear subclass
  * Outputs:
      * a matroid, a single-element extension of the given
        matroid

Description
===========

This function is provided by the package Matroids.

A matroid N is a (single-element) extension of a matroid M if M can be obtained
from N by deleting a single element e.  Every extension N of M is uniquely
determined by a modular cut of flats of M whose closure in N contains e.

Given a modular cut K of M, we can construct the corresponding extension.

+--------------------------------------------------------+
|i1 : M = uniformMatroid(4, 5);                          |
+--------------------------------------------------------+
|i2 : K = modularCut(M, {{0,1,2}, {2,3,4}})              |
|                                                        |
|o2 = {set {4, 2, 3}, set {0, 1, 2}, set {0, 1, 2, 3, 4}}|
|                                                        |
|o2 : List                                               |
+--------------------------------------------------------+
|i3 : isModularCut(M, K)                                 |
|                                                        |
|o3 = true                                               |
+--------------------------------------------------------+
|i4 : N = extension(M, K)                                |
|                                                        |
|o4 = a "matroid" of rank 4 on 6 elements                |
|                                                        |
|o4 : Matroid                                            |
+--------------------------------------------------------+

Every flat F of the matroid M determines a principal modular cut consisting of
all flats containing F. The independent sets of the free extension N come in
two types: They are either independent sets of M or sets containing e that,
after deleting e, become independent sets of M whose closure in M does not
contain F.   We can construct the extension corresponding to this modular cut
as follows.

+-----------------------------------------------------------------------------+
|i5 : F = set{0, 1, 3}                                                        |
|                                                                             |
|o5 = set {0, 1, 3}                                                           |
|                                                                             |
|o5 : Set                                                                     |
+-----------------------------------------------------------------------------+
|i6 : N = extension(M, F)                                                     |
|                                                                             |
|o6 = a "matroid" of rank 4 on 6 elements                                     |
|                                                                             |
|o6 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i7 : bases N                                                                 |
|                                                                             |
|o7 = {set {0, 1, 2, 3}, set {0, 1, 2, 4}, set {0, 1, 3, 4}, set {0, 2, 3, 4},|
|     ------------------------------------------------------------------------|
|     set {1, 2, 3, 4}, set {2, 3, 4, 5}, set {1, 3, 4, 5}, set {0, 3, 4, 5}, |
|     ------------------------------------------------------------------------|
|     set {1, 2, 4, 5}, set {0, 2, 4, 5}, set {0, 1, 4, 5}, set {1, 2, 3, 5}, |
|     ------------------------------------------------------------------------|
|     set {0, 2, 3, 5}, set {0, 1, 2, 5}}                                     |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+

When no modular cut or flat is specified, the free extension of M is
constructed.  This is the extension corresponding to the modular cut that
contains the ground set of M as its only flat. For a uniform matroid U_{r,n},
the free extension is just U_{r,n+1}.

+--------------------------------------------------+
|i8 : N = extension M                              |
|                                                  |
|o8 = a "matroid" of rank 4 on 6 elements          |
|                                                  |
|o8 : Matroid                                      |
+--------------------------------------------------+
|i9 : quickIsomorphismTest(N, uniformMatroid(4, 6))|
|                                                  |
|o9 = true                                         |
+--------------------------------------------------+

See also
========

  * coextension -- the free coextension of a matroid
  * elementaryQuotient -- associated to a modular
    cut or linear subclass
  * modularCut -- associated to an elementary quotient or
    linear subclass

Ways to use extension:
======================

  * "extension(Matroid)"
  * "extension(Matroid,List)"
  * "extension(Matroid,Set)"

For the programmer
==================

The object extension, is a method function with options (Macaulay2Doc).

extension(...,CheckWellDefined=>...) -- check whether the list is a modular cut or linear subclass
**************************************************************************************************

Synopsis
========

  * Usage:
        extension(M, L, CheckWellDefined => true)
  * Inputs:
      * M, a matroid,
      * L, a list (Macaulay2Doc), a list of flats or hyperplanes of
        the matroid forming a modular cut/linear subclass
  * Outputs:
      * a matroid, the extension of the matroid associated to
        modular cut/linear subclass

Description
===========

This option is provided by the package Matroids.

When producing the single-element extension of a matroid M corresponding to a
list of flats or hyperplanes L, setting this option to true calls
isModularCut, or isLinearSubclass, to
check that the list is a modular cut or linear subclass respectively.

+-----------------------------------------------------------------------------+
|i1 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}         |
|                                                                             |
|o1 = | 1 0 0 1 1  |                                                          |
|     | 0 1 0 1 -1 |                                                          |
|     | 0 0 1 0 0  |                                                          |
|                                                                             |
|              3       5                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i2 : M = matroid A                                                           |
|                                                                             |
|o2 = a "matroid" of rank 3 on 5 elements                                     |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : K = modularCut(M, drop(hyperplanes M, 1))                               |
|                                                                             |
|o3 = {set {2}, set {4, 2}, set {2, 3}, set {1, 2}, set {0, 2}, set {0, 1, 2, |
|     ------------------------------------------------------------------------|
|     3, 4}}                                                                  |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : extension(M, K, CheckWellDefined => true)                               |
|                                                                             |
|o4 = a "matroid" of rank 3 on 6 elements                                     |
|                                                                             |
|o4 : Matroid                                                                 |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: extension, -- of a matroid relative to a flat or
    modular cut
  * Option key: CheckWellDefined, -- an optional
    argument

See also
========

  * extension -- of a matroid relative to a flat or modular
    cut

Functions with optional argument named CheckWellDefined:
========================================================

  * "relaxation(...,CheckWellDefined=>...)" -- see CheckWellDefined,
    -- an optional argument
  * elementaryQuotient(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut or linear subclass
  * extension(...,CheckWellDefined=>...)
    -- check whether
    the list is a modular cut or linear subclass
  * linearSubclass(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut
  * modularCut(...,CheckWellDefined=>...)
    -- check whether
    the list is a linear subclass

extension(...,EntryMode=>...) -- use a modular cut or linear subclass
*********************************************************************

Synopsis
========

  * Usage:
        extension(M, L, Entry => "hyperplanes")
  * Inputs:
      * M, a matroid,
      * L, a list (Macaulay2Doc), a list of flats or hyperplanes of
        the matroid forming a modular cut/linear subclass
  * Outputs:
      * a matroid, the extension of the matroid associated to
        modular cut/linear subclass

Description
===========

This option is provided by the package Matroids.

A single-element extension of a matroid M can be produced from a list of flats
forming a modular cut of M or a list of hyperplanes of M forming a linear
subclass.  By default, it is assumed the specified list is a modular cut, but
setting this option to "hyperplanes" allows passing a much shorter list of
hyperplanes forming a linear subclass instead.

+--------------------------------------------------------------------+
|i1 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}|
|                                                                    |
|o1 = | 1 0 0 1 1  |                                                 |
|     | 0 1 0 1 -1 |                                                 |
|     | 0 0 1 0 0  |                                                 |
|                                                                    |
|              3       5                                             |
|o1 : Matrix ZZ  <-- ZZ                                              |
+--------------------------------------------------------------------+
|i2 : M = matroid A                                                  |
|                                                                    |
|o2 = a "matroid" of rank 3 on 5 elements                            |
|                                                                    |
|o2 : Matroid                                                        |
+--------------------------------------------------------------------+
|i3 : H = drop(hyperplanes M, 1)                                     |
|                                                                    |
|o3 = {set {4, 2}, set {2, 3}, set {1, 2}, set {0, 2}}               |
|                                                                    |
|o3 : List                                                           |
+--------------------------------------------------------------------+
|i4 : extension(M, H, EntryMode => "hyperplanes")                    |
|                                                                    |
|o4 = a "matroid" of rank 3 on 6 elements                            |
|                                                                    |
|o4 : Matroid                                                        |
+--------------------------------------------------------------------+

Further information
===================

  * Default value: modular cut
  * Function: extension, -- of a matroid relative to a flat or
    modular cut
  * Option key: EntryMode (Graphs), -- Constructs a simple graph

See also
========

  * extension -- of a matroid relative to a flat or modular
    cut

Functions with optional argument named EntryMode:
=================================================

  * digraph(...,EntryMode=>...) (missing documentation)
  * elementaryQuotient(...,EntryMode=>...)
    -- use a modular
    cut or linear subclass
  * extension(...,EntryMode=>...)
    -- use a modular cut or
    linear subclass
  * "graph(...,EntryMode=>...)" -- see graph (Graphs), --
    Constructs a simple graph
  * matroid(...,EntryMode=>...)
    -- select method of
    specifying matroid

flats -- flats of a matroid
***************************

Synopsis
========

  * Usage:
        flats M
        flats(M, r)
        flats(M, r, s)
  * Inputs:
      * M, a matroid,
      * r, an integer (Macaulay2Doc), a target (co)rank (optional)
      * s, a string (Macaulay2Doc), either "rank" or "corank"
  * Outputs:
      * a list (Macaulay2Doc),

Description
===========

A flat, or closed subset, of a matroid is a subset A of the ground set which
equals its closure. The set of flats, partially ordered by
inclusion, forms a lattice, called the lattice of flats.
This is an important invariant of the matroid: one can recover the matroid from
the lattice of flats, and for simple matroids (i.e. matroids whose circuits all
have size >= 3), the isomorphism type of the lattice is already a complete
invariant.

If a target rank r is provided, then this method returns the list of all rank r
flats of M.

If a target corank r is provided along with the mode "corank", then this method
computes all intersections of r distinct hyperplanes. This is guaranteed to
contain all flats of rank = rank M - r (cf. Oxley, Prop. 1.7.8), and may be
useful if the lattice of flats is large, and only the upper portion is required
(such as in the Scum theorem).

+-----------------------------------------------------------------------------+
|i1 : M = uniformMatroid(4, 6)                                                |
|                                                                             |
|o1 = a "matroid" of rank 4 on 6 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : netList flats M                                                         |
|                                                                             |
|     +----------------------+                                                |
|o2 = |set {}                |                                                |
|     +----------------------+                                                |
|     |set {5}               |                                                |
|     +----------------------+                                                |
|     |set {4}               |                                                |
|     +----------------------+                                                |
|     |set {3}               |                                                |
|     +----------------------+                                                |
|     |set {2}               |                                                |
|     +----------------------+                                                |
|     |set {1}               |                                                |
|     +----------------------+                                                |
|     |set {0}               |                                                |
|     +----------------------+                                                |
|     |set {4, 5}            |                                                |
|     +----------------------+                                                |
|     |set {5, 3}            |                                                |
|     +----------------------+                                                |
|     |set {4, 3}            |                                                |
|     +----------------------+                                                |
|     |set {5, 2}            |                                                |
|     +----------------------+                                                |
|     |set {4, 2}            |                                                |
|     +----------------------+                                                |
|     |set {1, 5}            |                                                |
|     +----------------------+                                                |
|     |set {4, 1}            |                                                |
|     +----------------------+                                                |
|     |set {0, 5}            |                                                |
|     +----------------------+                                                |
|     |set {0, 4}            |                                                |
|     +----------------------+                                                |
|     |set {2, 3}            |                                                |
|     +----------------------+                                                |
|     |set {1, 3}            |                                                |
|     +----------------------+                                                |
|     |set {0, 3}            |                                                |
|     +----------------------+                                                |
|     |set {1, 2}            |                                                |
|     +----------------------+                                                |
|     |set {0, 2}            |                                                |
|     +----------------------+                                                |
|     |set {0, 1}            |                                                |
|     +----------------------+                                                |
|     |set {4, 5, 3}         |                                                |
|     +----------------------+                                                |
|     |set {4, 5, 2}         |                                                |
|     +----------------------+                                                |
|     |set {4, 5, 1}         |                                                |
|     +----------------------+                                                |
|     |set {4, 0, 5}         |                                                |
|     +----------------------+                                                |
|     |set {5, 2, 3}         |                                                |
|     +----------------------+                                                |
|     |set {5, 1, 3}         |                                                |
|     +----------------------+                                                |
|     |set {0, 5, 3}         |                                                |
|     +----------------------+                                                |
|     |set {5, 1, 2}         |                                                |
|     +----------------------+                                                |
|     |set {0, 5, 2}         |                                                |
|     +----------------------+                                                |
|     |set {0, 5, 1}         |                                                |
|     +----------------------+                                                |
|     |set {4, 2, 3}         |                                                |
|     +----------------------+                                                |
|     |set {4, 1, 3}         |                                                |
|     +----------------------+                                                |
|     |set {4, 0, 3}         |                                                |
|     +----------------------+                                                |
|     |set {4, 1, 2}         |                                                |
|     +----------------------+                                                |
|     |set {4, 0, 2}         |                                                |
|     +----------------------+                                                |
|     |set {4, 0, 1}         |                                                |
|     +----------------------+                                                |
|     |set {1, 2, 3}         |                                                |
|     +----------------------+                                                |
|     |set {0, 2, 3}         |                                                |
|     +----------------------+                                                |
|     |set {0, 1, 3}         |                                                |
|     +----------------------+                                                |
|     |set {0, 1, 2}         |                                                |
|     +----------------------+                                                |
|     |set {0, 1, 2, 3, 4, 5}|                                                |
|     +----------------------+                                                |
+-----------------------------------------------------------------------------+
|i3 : flats(M, 1)                                                             |
|                                                                             |
|o3 = {set {5}, set {4}, set {3}, set {2}, set {1}, set {0}}                  |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : flats(M, 2, "corank")                                                   |
|                                                                             |
|o4 = {set {4, 5, 3}, set {4, 5}, set {5, 3}, set {5}, set {4, 3}, set {4},   |
|     ------------------------------------------------------------------------|
|     set {3}, set {}, set {4, 5, 2}, set {5, 2}, set {4, 2}, set {2}, set {4,|
|     ------------------------------------------------------------------------|
|     1, 5}, set {1, 5}, set {4, 1}, set {1}, set {0, 4, 5}, set {0, 5}, set  |
|     ------------------------------------------------------------------------|
|     {0, 4}, set {0}, set {5, 2, 3}, set {2, 3}, set {1, 5, 3}, set {1, 3},  |
|     ------------------------------------------------------------------------|
|     set {0, 5, 3}, set {0, 3}, set {1, 5, 2}, set {1, 2}, set {0, 5, 2}, set|
|     ------------------------------------------------------------------------|
|     {0, 2}, set {0, 1, 5}, set {0, 1}, set {4, 2, 3}, set {4, 1, 3}, set {0,|
|     ------------------------------------------------------------------------|
|     4, 3}, set {4, 1, 2}, set {0, 4, 2}, set {0, 4, 1}, set {1, 2, 3}, set  |
|     ------------------------------------------------------------------------|
|     {0, 2, 3}, set {0, 1, 3}, set {0, 1, 2}}                                |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

In general, this method computes flats by iteratively intersecting
hyperplanes, of M. Thus if hyperplanes of M have been precomputed,
then this function is typically much faster.

+---------------------------------------+
|i4 : M = matroid completeGraph 7       |
|                                       |
|o4 = a matroid of rank 6 on 21 elements|
|                                       |
|o4 : Matroid                           |
+---------------------------------------+
|i5 : time #hyperplanes M               |
|     ‐‐ used 4.98437 seconds           |
|                                       |
|o5 = 63                                |
+---------------------------------------+
|i6 : time #flats M                     |
|     ‐‐ used 0.515625 seconds          |
|                                       |
|o6 = 877                               |
+---------------------------------------+

See also
========

  * closure -- closure of a subset of a matroid
  * hyperplanes(Matroid) -- hyperplanes of a matroid
  * fVector(Matroid) -- f-vector of a matroid
  * latticeOfFlats -- lattice of flats of a matroid

Ways to use flats:
==================

  * "flats(Matroid)"
  * "flats(Matroid,ZZ)"
  * "flats(Matroid,ZZ,String)"

For the programmer
==================

The object flats, is a method function (Macaulay2Doc).

fundamentalCircuit -- fundamental circuit of independent set
************************************************************

Synopsis
========

  * Usage:
        fundamentalCircuit(M, I, e)
  * Inputs:
      * M, a matroid,
      * I, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M, which is an independent set
      * e, an integer (Macaulay2Doc), an index, or an element in M,
        such that $I \cup \{e\}$ is dependent
  * Outputs:
      * a set (Macaulay2Doc), the fundamental circuit of e with
        respect to I

Description
===========

If I is an independent set I, and e is an element such that $I \cup \{e\}$ is
dependent (in particular e is not in I), then there is a unique circuit
contained in $I \cup \{e\}$, called the fundamental circuit of e with respect
to I, which moreover contains e. Every circuit is the fundamental circuit of
some element with respect to some basis.

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : circuits M                          |
|                                         |
|o2 = {set {1, 2}, set {3}}               |
|                                         |
|o2 : List                                |
+-----------------------------------------+
|i3 : fundamentalCircuit(M, {a,c}, b)     |
|                                         |
|o3 = set {1, 2}                          |
|                                         |
|o3 : Set                                 |
+-----------------------------------------+
|i4 : fundamentalCircuit(M, set{0,2}, 1)  |
|                                         |
|o4 = set {1, 2}                          |
|                                         |
|o4 : Set                                 |
+-----------------------------------------+
|i5 : fundamentalCircuit(M, set{0,2}, 3)  |
|                                         |
|o5 = set {3}                             |
|                                         |
|o5 : Set                                 |
+-----------------------------------------+

This method does not perform any checks (e.g. whether $I$ is independent, or if
$e$ is not in $I$). If $I \cup \{e\}$ is independent, then (if debugLevel is
greater than 0) a warning is printed, and null (Macaulay2Doc), is
returned. In the example below, the elements with indices 2 and 3 are parallel
(indeed, both are equal to the column vector (1, 1)). Thus in general it is
safer to refer to a subset by its indices, rather than its elements.

+---------------------------------------------------------+
|i6 : M = matroid matrix{{1,0,1,1},{0,1,1,1}}             |
|                                                         |
|o6 = a "matroid" of rank 2 on 4 elements                 |
|                                                         |
|o6 : Matroid                                             |
+---------------------------------------------------------+
|i7 : circuits M                                          |
|                                                         |
|o7 = {set {0, 1, 2}, set {0, 1, 3}, set {2, 3}}          |
|                                                         |
|o7 : List                                                |
+---------------------------------------------------------+
|i8 : M_2                                                 |
|                                                         |
|o8 = | 1 |                                               |
|     | 1 |                                               |
|                                                         |
|              2       1                                  |
|o8 : Matrix ZZ  <-- ZZ                                   |
+---------------------------------------------------------+
|i9 : M_2 == M_3                                          |
|                                                         |
|o9 = true                                                |
+---------------------------------------------------------+
|i10 : (try fundamentalCircuit (M, M_{1,2}, M_3)) === null|
|                                                         |
|o10 = true                                               |
+---------------------------------------------------------+
|i11 : fundamentalCircuit (M, set{1,2}, 3)                |
|                                                         |
|o11 = set {2, 3}                                         |
|                                                         |
|o11 : Set                                                |
+---------------------------------------------------------+

See also
========

  * circuits -- circuits of matroid
  * independentSets(Matroid), --
    independent subsets of a matroid
  * isDependent -- whether a subset is dependent

Ways to use fundamentalCircuit:
===============================

  * "fundamentalCircuit(Matroid,List,Thing)"
  * "fundamentalCircuit(Matroid,Set,ZZ)"

For the programmer
==================

The object fundamentalCircuit, is a method function (Macaulay2Doc).

fVector(Matroid) -- f-vector of a matroid
*****************************************

Synopsis
========

  * Function: fVector (Polyhedra),
  * Usage:
        fVector M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a hash table (Macaulay2Doc),

Description
===========

The f-vector of a matroid M is the invariant (f_0, f_1, ..., f_r), where f_i is
the number of rank, i flats, of M,
and r is the rank, of M. Note that f_0 = f_r = 1, as
the set of loops, is the unique flat of rank 0, and the ground set
is the unique flat of maximal rank.

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : fVector M                           |
|                                         |
|o2 = HashTable{0 => 1}                   |
|               1 => 2                    |
|               2 => 1                    |
|                                         |
|o2 : HashTable                           |
+-----------------------------------------+
|i3 : fVector matroid completeGraph 4     |
|                                         |
|o3 = HashTable{0 => 1}                   |
|               1 => 6                    |
|               2 => 7                    |
|               3 => 1                    |
|                                         |
|o3 : HashTable                           |
+-----------------------------------------+

Caveat
======

This is not the same as the f-vector of the independence complex,
of the matroid M, which counts the number of
independent sets of a given size. To do this instead, use "fVector
independenceComplex M".

See also
========

  * flats -- flats of a matroid
  * rank(Matroid) -- rank of a matroid
  * latticeOfFlats -- lattice of flats of a matroid

Ways to use this method:
========================

  * fVector(Matroid) -- f-vector of a matroid

getCycles -- find cycles of graph
*********************************

Synopsis
========

  * Usage:
        getCycles(G)
  * Inputs:
      * G, a graph (Graphs),
  * Outputs:
      * a list (Macaulay2Doc), a list of (simple) cycles of G

Description
===========

A cycle of G is a connected, 2-regular subgraph of G (i.e. every vertex has
degree 2). This method returns all cycles of length at least 3, as ordered
lists of vertices (for cycles of length 1 or 2, see the options Loops and
ParallelEdges at matroid). This method is used to create the
graphic matroid: the output is in bijection with the circuits of the graphic
matroid (excluding loops and parallel edges).

+-----------------------------------------------------------------------------+
|i1 : getCycles completeGraph 4                                               |
|                                                                             |
|o1 = {{0, 1, 2, 0}, {0, 1, 3, 0}, {0, 2, 3, 0}, {0, 1, 2, 3, 0}, {0, 1, 3, 2,|
|     ------------------------------------------------------------------------|
|     0}, {0, 2, 1, 3, 0}, {1, 2, 3, 1}}                                      |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use getCycles:
======================

  * "getCycles(Graph)"

For the programmer
==================

The object getCycles, is a method function (Macaulay2Doc).

getIsos -- all isomorphisms between two matroids
************************************************

Synopsis
========

  * Usage:
        getIsos(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a list (Macaulay2Doc), of all isomorphisms between M and N

Description
===========

This method computes all isomorphisms,
between M and N: in particular, this
method returns an empty list iff M and N are not isomorphic.

To compute only a single isomorphism, use isomorphism.
To test if two matroids are isomorphic,
use areIsomorphic.

To save space, the isomorphisms are given as lists (as opposed to hash tables).
One way to interpret the output of this method is: given two isomorphic
matroids, this method returns a permutation representation of the automorphism
group of that matroid, inside the symmetric group on the ground set.

+-----------------------------------------------------------------------+
|i1 : M = matroid({a,b,c},{{a,b},{a,c}})                                |
|                                                                       |
|o1 = a "matroid" of rank 2 on 3 elements                               |
|                                                                       |
|o1 : Matroid                                                           |
+-----------------------------------------------------------------------+
|i2 : U23 = uniformMatroid(2,3)                                         |
|                                                                       |
|o2 = a "matroid" of rank 2 on 3 elements                               |
|                                                                       |
|o2 : Matroid                                                           |
+-----------------------------------------------------------------------+
|i3 : getIsos(M, U23) -- not isomorphic                                 |
|                                                                       |
|o3 = {}                                                                |
|                                                                       |
|o3 : List                                                              |
+-----------------------------------------------------------------------+
|i4 : getIsos(M, M)                                                     |
|                                                                       |
|o4 = {{0, 1, 2}, {0, 2, 1}}                                            |
|                                                                       |
|o4 : List                                                              |
+-----------------------------------------------------------------------+
|i5 : getIsos(U23, U23) -- the full symmetric group S3                  |
|                                                                       |
|o5 = {{0, 1, 2}, {0, 2, 1}, {1, 0, 2}, {1, 2, 0}, {2, 0, 1}, {2, 1, 0}}|
|                                                                       |
|o5 : List                                                              |
+-----------------------------------------------------------------------+

We can verify that the Fano matroid (the projective plane over the field of two
elements) has automorphism group of order 168, and give a permutation
representation for this nonabelian simple group (= PGL(3, F_2)) inside the
symmetric group S_7:

+-------------------------------------------------------+
|i6 : F7 = specificMatroid "fano"                       |
|                                                       |
|o6 = a "matroid" of rank 3 on 7 elements               |
|                                                       |
|o6 : Matroid                                           |
+-------------------------------------------------------+
|i7 : time autF7 = getIsos(F7, F7);                     |
| -- used 0.0777451s (cpu); 0.0440258s (thread); 0s (gc)|
+-------------------------------------------------------+
|i8 : #autF7                                            |
|                                                       |
|o8 = 168                                               |
+-------------------------------------------------------+

See also
========

  * isomorphism(Matroid,Matroid), --
    computes an isomorphism between isomorphic matroids
  * quickIsomorphismTest -- quick checks for
    isomorphism between matroids
  * areIsomorphic(Matroid,Matroid),
    -- whether two matroids are isomorphic

Ways to use getIsos:
====================

  * "getIsos(Matroid,Matroid)"

For the programmer
==================

The object getIsos, is a method function (Macaulay2Doc).

getRepresentation -- retrieves stored representation
****************************************************

Synopsis
========

  * Usage:
        getRepresentation M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a thing (Macaulay2Doc), a representation of M (either a
        matrix or a graph)

Description
===========

For a matroid created from a matrix, this function provides a user-friendly way
to access the original matrix. Similarly, for a matroid created from a (simple)
graph, this function returns the graph used to create the matroid.

Note that some constructions applied to a matroid M (such as taking dual, or
minors) will automatically compute an induced representation (if a
representation of M exists), which can be viewed with this function.

+----------------------------------------+
|i1 : A = random(QQ^3,QQ^5)              |
|                                        |
|o1 = | 9/2 1/2 3/2 7/9  7/10 |          |
|     | 1/2 1   3/4 7/10 7/3  |          |
|     | 9/4 3/4 7/4 1/2  7    |          |
|                                        |
|              3       5                 |
|o1 : Matrix QQ  <-- QQ                  |
+----------------------------------------+
|i2 : M = matroid A                      |
|                                        |
|o2 = a "matroid" of rank 3 on 5 elements|
|                                        |
|o2 : Matroid                            |
+----------------------------------------+
|i3 : A == getRepresentation M           |
|                                        |
|o3 = true                               |
+----------------------------------------+
|i4 : K4 = completeGraph 4               |
|                                        |
|o4 = Graph{0 => {1, 2, 3}}              |
|           1 => {0, 2, 3}               |
|           2 => {0, 1, 3}               |
|           3 => {0, 1, 2}               |
|                                        |
|o4 : Graph                              |
+----------------------------------------+
|i5 : M4 = matroid K4                    |
|                                        |
|o5 = a "matroid" of rank 3 on 6 elements|
|                                        |
|o5 : Matroid                            |
+----------------------------------------+
|i6 : getRepresentation M4 === K4        |
|                                        |
|o6 = true                               |
+----------------------------------------+
|i7 : N = M / set{0}                     |
|                                        |
|o7 = a "matroid" of rank 2 on 4 elements|
|                                        |
|o7 : Matroid                            |
+----------------------------------------+
|i8 : getRepresentation N                |
|                                        |
|o8 = | 11925/8863 7515/17726 1 0 |      |
|     | 3270/62041 1270/8863  0 1 |      |
|                                        |
|              2       4                 |
|o8 : Matrix QQ  <-- QQ                  |
+----------------------------------------+

See also
========

  * setRepresentation -- stores user-defined
    representation
  * matroid -- constructs a matroid

Ways to use getRepresentation:
==============================

  * "getRepresentation(Matroid)"

For the programmer
==================

The object getRepresentation, is a method function (Macaulay2Doc).

getSeparation -- finds a k-separation of a matroid
**************************************************

Synopsis
========

  * Usage:
        getSeparation(M, k)
  * Inputs:
      * M, a matroid,
      * k, an integer (Macaulay2Doc),
  * Outputs:
      * a set (Macaulay2Doc), a k-separation of M, if one exists, or
        null (Macaulay2Doc), if none exists

Description
===========

For a matroid M on a ground set E, and k >= 1, a (2-)partition (X, E - X) of
E(M) is called a k-separation of M if |X| >= k, |E - X| >= k, and rank(X) +
rank(E - X) - rank(M) <= k-1. The separation is called minimal if either |X| =
k or |E - X| = k.

This method computes a k-separation of M, if one exists. If no k-separation of
M exists, then null (Macaulay2Doc), is returned.

Efficiency is achieved by using special structure of k-separations: if (X, E -
X) is a minimal k-separation (and no m-separation with m < k exists) with |X| =
k, then X is either an independent cocircuit or a coindependent circuit. On the
other hand, if (X, E - X) is a nonminimal separation with |E - X| minimal, then
X is both a flat and a coflat. In particular, if the ranks of all flats have
been previously computed (e.g. via fVector), then
this method should finish quickly.

For k = 1, it is generally more efficient to use components,
and isConnected, than
this method.

+-----------------------------------------------------------------------------+
|i1 : G = graph({{0,1},{1,2},{2,3},{3,4},{4,5},{5,6},{6,0},{0,2},{0,3},{0,4},{|
|                                                                             |
|o1 = Graph{0 => {1, 2, 3, 4, 6}   }                                          |
|           1 => {0, 2, 3}                                                    |
|           2 => {0, 1, 3}                                                    |
|           3 => {0, 1, 2, 4, 5, 6}                                           |
|           4 => {0, 3, 5}                                                    |
|           5 => {3, 4, 6}                                                    |
|           6 => {0, 3, 5}                                                    |
|                                                                             |
|o1 : Graph                                                                   |
|-----------------------------------------------------------------------------|
|1,3},{3,5},{3,6}})                                                           |
+-----------------------------------------------------------------------------+
|i2 : M = matroid G                                                           |
|                                                                             |
|o2 = a "matroid" of rank 6 on 13 elements                                    |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : getSeparation(M, 2)                                                     |
|                                                                             |
|o3 = set {2, 3, 4, 8, 9, 10, 11, 12}                                         |
|                                                                             |
|o3 : Set                                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * isConnected(Matroid) -- whether a matroid
    is connected
  * is3Connected -- whether a matroid is 3-connected

Ways to use getSeparation:
==========================

  * "getSeparation(Matroid,ZZ)"

For the programmer
==================

The object getSeparation, is a method function (Macaulay2Doc).

groundSet -- (internal) ground set
**********************************

Synopsis
========

  * Usage:
        groundSet M
        M.groundSet
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a set (Macaulay2Doc), of integers starting from 0

Description
===========

Returns the internal representation of the ground set.

Important: read the following if you encounter warnings/errors when specifying
subsets of a matroid (e.g. restriction/deletion/contraction, ranks of subset,
etc.)

For a matroid M, there are 2 main differences between M.groundSet and the
elements of M (given by M_*). First is data types:
M.groundSet is a Set (Macaulay2Doc), and M_* is a List (Macaulay2Doc).
Second, M.groundSet always consists of integers from 0 to
n-1, where n is the number of elements of M; on the other hand, the elements of
M themselves can be arbitrary (e.g. symbols, matrices, edges in a graph, etc.).

Thus, one can think of M.groundSet as the set of indices of the elements in the
list M_*: the first element of M has index 0, corresponding to the element 0 in
M.groundSet; the second element of M has index 1, etc.

The key point is that all sets associated to the structure of a matroid -
bases, circuits, flats, etc. - are subsets of M.groundSet (not M_*). In
particular, they are also of class Set (Macaulay2Doc), (although a
collection of them is usually a List (Macaulay2Doc)), and are also
indexed from 0 to n-1. (An exception here is loops and coloops, which are given
as a list of indices, rather than single-element sets).

A recommended way to circumvent this distinction between indices and elements
is to use $\{0, ..., n-1\}$ as the actual elements of M, in which case an
element is equal to its index in M.groundSet. Most methods in this package will
accept either a list of elements or a set of indices, and if the elements of M
are $\{0, ..., n-1\}$, then functionally there will be no difference between
inputting lists or sets.

In summary: lists (Macaulay2Doc), are used for elements in M, and
given as sublists of M_*, while sets (Macaulay2Doc), are used for
indices, and given as subsets of M.groundSet.

+-----------------------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})                  |
|                                                           |
|o1 = a "matroid" of rank 2 on 4 elements                   |
|                                                           |
|o1 : Matroid                                               |
+-----------------------------------------------------------+
|i2 : peek M                                                |
|                                                           |
|o2 = Matroid{bases => {set {0, 1}, set {0, 2}}}            |
|             cache => CacheTable{...1...}                  |
|             groundSet => set {0, 1, 2, 3}                 |
|             rank => 2                                     |
+-----------------------------------------------------------+
|i3 : M.groundSet                                           |
|                                                           |
|o3 = set {0, 1, 2, 3}                                      |
|                                                           |
|o3 : Set                                                   |
+-----------------------------------------------------------+
|i4 : M_*                                                   |
|                                                           |
|o4 = {a, b, c, d}                                          |
|                                                           |
|o4 : List                                                  |
+-----------------------------------------------------------+
|i5 : bases M                                               |
|                                                           |
|o5 = {set {0, 1}, set {0, 2}}                              |
|                                                           |
|o5 : List                                                  |
+-----------------------------------------------------------+
|i6 : (bases M)#0                                           |
|                                                           |
|o6 = set {0, 1}                                            |
|                                                           |
|o6 : Set                                                   |
+-----------------------------------------------------------+
|i7 : circuits M                                            |
|                                                           |
|o7 = {set {1, 2}, set {3}}                                 |
|                                                           |
|o7 : List                                                  |
+-----------------------------------------------------------+
|i8 : flats M                                               |
|                                                           |
|o8 = {set {3}, set {1, 2, 3}, set {0, 3}, set {0, 1, 2, 3}}|
|                                                           |
|o8 : List                                                  |
+-----------------------------------------------------------+
|i9 : loops M                                               |
|                                                           |
|o9 = {3}                                                   |
|                                                           |
|o9 : List                                                  |
+-----------------------------------------------------------+
|i10 : coloops M                                            |
|                                                           |
|o10 = {0}                                                  |
|                                                           |
|o10 : List                                                 |
+-----------------------------------------------------------+

Note in particular the types of the various outputs above.

The following illustrates how to perform operations with a specified subset of
M.groundSet. In the final example, a list of indices is given, which goes
against the conventions above, but the elements of the list are treated
(correctly) as indices, and if debugLevel is greater than 0, then a warning is
printed.

+-----------------------------------------------------------------------------+
|i11 : N1 = M | {a,c,d}                                                       |
|                                                                             |
|o11 = a "matroid" of rank 2 on 3 elements                                    |
|                                                                             |
|o11 : Matroid                                                                |
+-----------------------------------------------------------------------------+
|i12 : N2 = M | set{0,2,3}                                                    |
|                                                                             |
|o12 = a "matroid" of rank 2 on 3 elements                                    |
|                                                                             |
|o12 : Matroid                                                                |
+-----------------------------------------------------------------------------+
|i13 : N1 == N2                                                               |
|                                                                             |
|o13 = true                                                                   |
+-----------------------------------------------------------------------------+
|i14 : debugLevel = 1                                                         |
|                                                                             |
|o14 = 1                                                                      |
+-----------------------------------------------------------------------------+
|i15 : N3 = M | {0,2,3} -- gives a warning, but attempts to treat 0 as an     |
| -- indicesOf: 0 is not a member of {a, b, c, d}. Treating 0 as an index     |
|                                                                             |
|o15 = a "matroid" of rank 2 on 3 elements                                    |
|                                                                             |
|o15 : Matroid                                                                |
|-----------------------------------------------------------------------------|
|index                                                                        |
|(cf. 'help groundSet')...                                                    |
+-----------------------------------------------------------------------------+
|i16 : N3 == N2                                                               |
|                                                                             |
|o16 = true                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * Matroid _ List -- elements of matroid
  * indicesOf -- indices of a sublist
  * relabel -- relabel a matroid

Ways to use groundSet:
======================

  * "groundSet(Matroid)"

For the programmer
==================

The object groundSet, is a method function (Macaulay2Doc).

hasMinor -- whether a matroid has a given minor
***********************************************

Synopsis
========

  * Usage:
        hasMinor(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Optional inputs (Macaulay2Doc),:
      * Strategy => ..., default value "flats"
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether N is a minor of
        M

Description
===========

Determines if N is a minor of M, i.e. can be obtained from M by a contraction
followed by a deletion. Since deletion and contraction by disjoint subsets
commute, every sequence of deletion and contraction operations can be written
as a single contraction and a single deletion.

Many families of matroids can be defined by a list of forbidden minors: i.e. a
matroid M is in the family iff M does not have any of the forbidden minors as a
minor. For instance, a matroid is representable over F_2 iff it does not have
U_{2,4} as a minor, i.e. U_{2,4} is the (sole) forbidden minor for binary matroids.

There are 2 strategies for this method: the default (and generally fastest)
method is ``Strategy => "flats"'', which can be sped up by precomputing the
fVector, of M. Otherwise, all
independent/coindependent sets of a certain size/rank are iterated over.

+-----------------------------------------------------------------------------+
|i1 : (M4, M5, M6) = (4,5,6)/completeGraph/matroid                            |
|                                                                             |
|o1 = (a "matroid" of rank 3 on 6 elements, a "matroid" of rank 4 on 10       |
|     ------------------------------------------------------------------------|
|     elements, a "matroid" of rank 5 on 15 elements)                         |
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : hasMinor(M4, uniformMatroid(2,4))                                       |
|                                                                             |
|o2 = false                                                                   |
+-----------------------------------------------------------------------------+
|i3 : time hasMinor(M6, M5)                                                   |
| -- used 1.15278s (cpu); 0.839114s (thread); 0s (gc)                         |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * minor -- minor of matroid
  * isBinary -- whether a matroid is representable over F_2

Ways to use hasMinor:
=====================

  * "hasMinor(Matroid,Matroid)"

For the programmer
==================

The object hasMinor, is a method function with options (Macaulay2Doc).

hyperplanes -- hyperplanes of a matroid
***************************************

Synopsis
========

  * Usage:
        hyperplanes M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a list (Macaulay2Doc),

Description
===========

The hyperplanes of a matroid are the flats of rank equal to rank M - 1. The
complements of the hyperplanes are precisely the circuits, of
the dual, matroid (which is indeed how this method
computes hyperplanes), and thus a matroid is determined by its hyperplanes.

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : hyperplanes M                       |
|                                         |
|o2 = {set {1, 2, 3}, set {0, 3}}         |
|                                         |
|o2 : List                                |
+-----------------------------------------+

See also
========

  * flats -- flats of a matroid
  * rank(Matroid) -- rank of a matroid

Ways to use hyperplanes:
========================

  * "hyperplanes(Cone)" -- see hyperplanes (Polyhedra), --
    computes the defining hyperplanes of a Cone or a Polyhedron
  * "hyperplanes(Matroid)"
  * "hyperplanes(Polyhedron)" -- see hyperplanes (Polyhedra),
    -- computes the defining hyperplanes of a Cone or a Polyhedron

For the programmer
==================

The object hyperplanes (Polyhedra), is a method function (Macaulay2Doc).

ideal(Matroid) -- Stanley-Reisner (circuit) ideal of matroid
************************************************************

Synopsis
========

  * Function: ideal (Macaulay2Doc),
  * Usage:
        ideal M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a monomial ideal (Macaulay2Doc), the Stanley
        Reisner ideal of the independence complex, also called the circuit
        ideal

Description
===========

The independent sets, of a matroid M
form a simplicial complex (i.e., are downward closed), called the
independence complex, of M. Via the
Stanley-Reisner correspondence, the independence complex of M corresponds
uniquely to a squarefree monomial ideal, which is the output of this method.

The minimal generators of the ideal correspond to minimal non-faces of the
simplicial complex. As the faces of the independence complex are precisely the
independent sets, the minimal non-faces are exactly the minimal dependent sets,
i.e. the circuits, of M.

The facets of the simplicial complex correspond to bases, of M,
and thus also to irreducible components of the ideal of M; which are in
bijection with the minimal generators of the Alexander dual ideal via taking
complements.

Internally, the ideal of the matroid is an important complete invariant, and is
heavily used in many algorithms in this package. Accordingly, once the ideal of
a matroid is computed, it is cached in the CacheTable (Macaulay2Doc),
of the matroid, which speeds up any algorithm which
requires the ideal as part of the input.

+--------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})   |
|                                            |
|o1 = a "matroid" of rank 2 on 4 elements    |
|                                            |
|o1 : Matroid                                |
+--------------------------------------------+
|i2 : circuits M                             |
|                                            |
|o2 = {set {1, 2}, set {3}}                  |
|                                            |
|o2 : List                                   |
+--------------------------------------------+
|i3 : ideal M                                |
|                                            |
|o3 = monomialIdeal (x x , x )               |
|                     1 2   3                |
|                                            |
|o3 : MonomialIdeal of QQ[x ..x ]            |
|                          0   3             |
+--------------------------------------------+
|i4 : J = dual ideal M                       |
|                                            |
|o4 = monomialIdeal (x x , x x )             |
|                     1 3   2 3              |
|                                            |
|o4 : MonomialIdeal of QQ[x ..x ]            |
|                          0   3             |
+--------------------------------------------+
|i5 : J_*/indices                            |
|                                            |
|o5 = {{1, 3}, {2, 3}}                       |
|                                            |
|o5 : List                                   |
+--------------------------------------------+
|i6 : bases M                                |
|                                            |
|o6 = {set {0, 1}, set {0, 2}}               |
|                                            |
|o6 : List                                   |
+--------------------------------------------+
|i7 : betti res ideal matroid completeGraph 4|
|                                            |
|            0 1  2 3                        |
|o7 = total: 1 7 12 6                        |
|         0: 1 .  . .                        |
|         1: . .  . .                        |
|         2: . 4  . .                        |
|         3: . 3 12 6                        |
|                                            |
|o7 : BettiTally                             |
+--------------------------------------------+

See also
========

  * circuits -- circuits of matroid
  * bases -- bases of matroid
  * independenceComplex(Matroid), --
    independence complex of matroid

Ways to use this method:
========================

  * ideal(Matroid) -- Stanley-Reisner (circuit)
    ideal of matroid

idealChowRing -- the defining ideal of the Chow ring
****************************************************

Synopsis
========

  * Usage:
        idealChowRing M
  * Inputs:
      * M, a matroid,
  * Optional inputs (Macaulay2Doc),:
      * ChowRingOptions => ..., default value new OptionTable from
        {MonomialOrder => GLex}
      * CoefficientRing => ..., default value QQ
      * FlatOrder => ..., default value null
      * Presentation => ..., default value "standard"
      * Variable => ..., default value "x"
  * Outputs:
      * an ideal (Macaulay2Doc), the defining ideal of the Chow
        ring of M

Description
===========

The Chow ring of M is the ring R := QQ[x_F]/(I1 + I2), where $I1 =
(\sum_{i_1\in F} x_F - \sum_{i_2\in F} x_F : i_1, i_2 \in M)$ and $I2 =
(x_Fx_{F'} : F, F' incomparable)$, as $F$ runs over all proper nonempty flats
of $M$. This is the same as the Chow ring of the toric variety associated to
the Bergman fan of M. This ring is an Artinian standard graded Gorenstein ring,
by a result of Adiprasito, Katz, and Huh: cf. https://arxiv.org/abs/1511.02888,
Theorem 6.19.

This method returns the defining ideal of the Chow ring, which lives in a
polynomial ring with variable indices equal to the flats of M. To work with
these subscripts, use "last baseName v" to get the index of a variable v. For
more information, cf. Working with Chow rings of matroids.

+-----------------------------------------------------------------------------+
|i1 : M = matroid completeGraph 4                                             |
|                                                                             |
|o1 = a "matroid" of rank 3 on 6 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : I = idealChowRing M                                                     |
|                                                                             |
|o2 = ideal (x   x   , x   x   , x   x   , x   x   , x   x   , x   x   ,      |
|             {5} {4}   {5} {3}   {4} {3}   {5} {2}   {4} {2}   {3} {2}       |
|     ------------------------------------------------------------------------|
|     x   x   , x   x   , x   x   , x   x   , x   x   , x   x   , x   x   ,   |
|      {5} {1}   {4} {1}   {3} {1}   {2} {1}   {5} {0}   {4} {0}   {3} {0}    |
|     ------------------------------------------------------------------------|
|     x   x   , x   x   , x   x         , x   x         , x   x         ,     |
|      {2} {0}   {1} {0}   {2} {3, 4, 5}   {1} {3, 4, 5}   {0} {3, 4, 5}      |
|     ------------------------------------------------------------------------|
|     x   x         , x   x         , x   x         , x         x         ,   |
|      {4} {1, 2, 5}   {3} {1, 2, 5}   {0} {1, 2, 5}   {3, 4, 5} {1, 2, 5}    |
|     ------------------------------------------------------------------------|
|     x   x      , x   x      , x   x      , x   x      , x         x      ,  |
|      {4} {0, 5}   {3} {0, 5}   {2} {0, 5}   {1} {0, 5}   {3, 4, 5} {0, 5}   |
|     ------------------------------------------------------------------------|
|     x         x      , x   x         , x   x         , x   x         , x    |
|      {1, 2, 5} {0, 5}   {5} {0, 2, 4}   {3} {0, 2, 4}   {1} {0, 2, 4}   {3, |
|     ------------------------------------------------------------------------|
|          x         , x         x         , x      x         , x   x      ,  |
|     4, 5} {0, 2, 4}   {1, 2, 5} {0, 2, 4}   {0, 5} {0, 2, 4}   {5} {1, 4}   |
|     ------------------------------------------------------------------------|
|     x   x      , x   x      , x   x      , x         x      , x         x   |
|      {3} {1, 4}   {2} {1, 4}   {0} {1, 4}   {3, 4, 5} {1, 4}   {1, 2, 5} {1,|
|     ------------------------------------------------------------------------|
|       , x      x      , x         x      , x   x      , x   x      ,        |
|     4}   {0, 5} {1, 4}   {0, 2, 4} {1, 4}   {5} {2, 3}   {4} {2, 3}         |
|     ------------------------------------------------------------------------|
|     x   x      , x   x      , x         x      , x         x      , x       |
|      {1} {2, 3}   {0} {2, 3}   {3, 4, 5} {2, 3}   {1, 2, 5} {2, 3}   {0,    |
|     ------------------------------------------------------------------------|
|       x      , x         x      , x      x      , x   x         , x   x     |
|     5} {2, 3}   {0, 2, 4} {2, 3}   {1, 4} {2, 3}   {5} {0, 1, 3}   {4} {0,  |
|     ------------------------------------------------------------------------|
|          , x   x         , x         x         , x         x         , x    |
|     1, 3}   {2} {0, 1, 3}   {3, 4, 5} {0, 1, 3}   {1, 2, 5} {0, 1, 3}   {0, |
|     ------------------------------------------------------------------------|
|       x         , x         x         , x      x         , x      x         |
|     5} {0, 1, 3}   {0, 2, 4} {0, 1, 3}   {1, 4} {0, 1, 3}   {2, 3} {0, 1,   |
|     ------------------------------------------------------------------------|
|       , x    - x    + x          - x       - x          + x      , x    -   |
|     3}   {1}    {0}    {1, 2, 5}    {0, 5}    {0, 2, 4}    {1, 4}   {2}     |
|     ------------------------------------------------------------------------|
|     x    + x          - x       + x       - x         , x    - x    + x     |
|      {0}    {1, 2, 5}    {0, 5}    {2, 3}    {0, 1, 3}   {3}    {0}    {3,  |
|     ------------------------------------------------------------------------|
|           - x       - x          + x      , x    - x    + x          - x    |
|     4, 5}    {0, 5}    {0, 2, 4}    {2, 3}   {4}    {0}    {3, 4, 5}    {0, |
|     ------------------------------------------------------------------------|
|        + x       - x         , x    - x    + x          + x          - x    |
|     5}    {1, 4}    {0, 1, 3}   {5}    {0}    {3, 4, 5}    {1, 2, 5}    {0, |
|     ------------------------------------------------------------------------|
|           - x         )                                                     |
|     2, 4}    {0, 1, 3}                                                      |
|                                                                             |
|o2 : Ideal of QQ[x   , x   , x   , x   , x   , x   , x         , x         , |
|                  {5}   {4}   {3}   {2}   {1}   {0}   {3, 4, 5}   {1, 2, 5}  |
|-----------------------------------------------------------------------------|
|x      , x         , x      , x      , x         ]                           |
| {0, 5}   {0, 2, 4}   {1, 4}   {2, 3}   {0, 1, 3}                            |
+-----------------------------------------------------------------------------+
|i3 : basis comodule I                                                        |
|                                                                             |
|o3 = | 1 x_{0} x_{3, 4, 5} x_{1, 2, 5} x_{0, 5} x_{0, 2, 4} x_{1, 4} x_{2, 3}|
|     ------------------------------------------------------------------------|
|     x_{0, 1, 3} x_{0, 1, 3}^2 |                                             |
|                                                                             |
|o3 : Matrix                                                                  |
+-----------------------------------------------------------------------------+
|i4 : (0..<rank M)/(i -> hilbertFunction(i, I))                               |
|                                                                             |
|o4 = (1, 8, 1)                                                               |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i5 : betti res minimalPresentation I                                         |
|                                                                             |
|            0  1   2   3   4   5   6  7 8                                    |
|o5 = total: 1 35 160 350 448 350 160 35 1                                    |
|         0: 1  .   .   .   .   .   .  . .                                    |
|         1: . 35 160 350 448 350 160 35 .                                    |
|         2: .  .   .   .   .   .   .  . 1                                    |
|                                                                             |
|o5 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i6 : apply(gens ring I, v -> last baseName v)                                |
|                                                                             |
|o6 = {{5}, {4}, {3}, {2}, {1}, {0}, {3, 4, 5}, {1, 2, 5}, {0, 5}, {0, 2, 4}, |
|     ------------------------------------------------------------------------|
|     {1, 4}, {2, 3}, {0, 1, 3}}                                              |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * latticeOfFlats -- lattice of flats of a matroid
  * cogeneratorChowRing -- cogenerator of the Chow
    ring of a matroid
  * Working with Chow rings of matroids

Ways to use idealChowRing:
==========================

  * "idealChowRing(Matroid)"

For the programmer
==================

The object idealChowRing, is a method function with options (Macaulay2Doc).

idealOrlikSolomonAlgebra
************************

Ways to use idealOrlikSolomonAlgebra:
=====================================

  * idealOrlikSolomonAlgebra(Matroid) (missing documentation)

For the programmer
==================

The object idealOrlikSolomonAlgebra (missing documentation) is a method function with options (Macaulay2Doc).

independenceComplex(Matroid) -- independence complex of matroid
***************************************************************

Synopsis
========

  * Function: independenceComplex (Graphs),
  * Usage:
        independenceComplex M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * an abstract simplicial complex (SimplicialComplexes),

Description
===========

The independence complex of a matroid is the simplicial complex associated (via
the Stanley-Reisner correspondence) to the circuit ideal of the matroid (which
is a squarefree monomial ideal). This method uses the
SimplicialComplexes, package to return an object of
type SimplicialComplex (SimplicialComplexes).

+-------------------------------------------------------------+
|i1 : M = matroid({{0,1},{0,2},{0,3},{1,2},{2,3}})            |
|                                                             |
|o1 = a "matroid" of rank 2 on 4 elements                     |
|                                                             |
|o1 : Matroid                                                 |
+-------------------------------------------------------------+
|i2 : independenceComplex M                                   |
|                                                             |
|o2 = simplicialComplex | x_2x_3 x_0x_3 x_1x_2 x_0x_2 x_0x_1 ||
|                                                             |
|o2 : SimplicialComplex                                       |
+-------------------------------------------------------------+

See also
========

  * independentSets(Matroid), --
    independent subsets of a matroid
  * ideal(Matroid) -- Stanley-Reisner (circuit)
    ideal of matroid
  * basisIndicatorMatrix(Matroid) -- matrix of
    basis polytope

Ways to use this method:
========================

  * independenceComplex(Matroid), --
    independence complex of matroid

independentSets(Matroid,ZZ) -- independent subsets of a matroid
***************************************************************

Synopsis
========

  * Function: independentSets (Macaulay2Doc),
  * Usage:
        independentSets(M, s)
        independentSets M
  * Inputs:
      * M, a matroid,
      * s, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Limit (Macaulay2Doc), => ..., default value
        infinity,
  * Outputs:
      * a list (Macaulay2Doc), of independent sets in M

Description
===========

A subset of the ground set is called independent if it is contained in a
basis, or equivalently, does not contain a circuit.
This method returns certain independent subsets of the ground set, depending on
the input:

If an integer $s$ is provided, then all independent subsets of size $s$ in $M$
are returned.

If a subset $S$ of the ground set of $M$ is given, then all maximal independent
subsets of $S$ are returned.

If neither a size $s$ nor a subset $S$ is given, then all independent sets of M
is returned (which may be quite large).

+-----------------------------------------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})                                    |
|                                                                             |
|o1 = a "matroid" of rank 2 on 4 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : independentSets(M, 2)                                                   |
|                                                                             |
|o2 = {set {0, 1}, set {0, 2}}                                                |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : independentSets(M, set{1,2,3})                                          |
|                                                                             |
|o3 = {set {1}, set {2}}                                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : netList independentSets M                                               |
|                                                                             |
|     +----------+                                                            |
|o4 = |set {}    |                                                            |
|     +----------+                                                            |
|     |set {0}   |                                                            |
|     +----------+                                                            |
|     |set {1}   |                                                            |
|     +----------+                                                            |
|     |set {0, 1}|                                                            |
|     +----------+                                                            |
|     |set {2}   |                                                            |
|     +----------+                                                            |
|     |set {0, 2}|                                                            |
|     +----------+                                                            |
+-----------------------------------------------------------------------------+
|i5 : V = specificMatroid "vamos"                                             |
|                                                                             |
|o5 = a "matroid" of rank 4 on 8 elements                                     |
|                                                                             |
|o5 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i6 : I3 = independentSets(V, 3)                                              |
|                                                                             |
|o6 = {set {5, 6, 3}, set {5, 7, 3}, set {6, 7, 3}, set {5, 6, 7}, set {5, 6, |
|     ------------------------------------------------------------------------|
|     2}, set {5, 2, 7}, set {6, 2, 7}, set {5, 1, 6}, set {5, 1, 7}, set {1, |
|     ------------------------------------------------------------------------|
|     6, 7}, set {0, 5, 6}, set {0, 5, 7}, set {0, 6, 7}, set {4, 6, 3}, set  |
|     ------------------------------------------------------------------------|
|     {4, 7, 3}, set {4, 6, 7}, set {4, 6, 2}, set {4, 2, 7}, set {4, 1, 6},  |
|     ------------------------------------------------------------------------|
|     set {4, 1, 7}, set {4, 0, 6}, set {4, 0, 7}, set {1, 6, 3}, set {1, 7,  |
|     ------------------------------------------------------------------------|
|     3}, set {0, 6, 3}, set {0, 7, 3}, set {1, 6, 2}, set {1, 2, 7}, set {0, |
|     ------------------------------------------------------------------------|
|     6, 2}, set {0, 2, 7}, set {4, 5, 3}, set {4, 5, 7}, set {4, 5, 2}, set  |
|     ------------------------------------------------------------------------|
|     {4, 5, 1}, set {4, 0, 5}, set {5, 2, 3}, set {2, 7, 3}, set {5, 1, 3},  |
|     ------------------------------------------------------------------------|
|     set {0, 5, 3}, set {5, 1, 2}, set {0, 5, 2}, set {0, 5, 1}, set {0, 1,  |
|     ------------------------------------------------------------------------|
|     7}, set {4, 2, 3}, set {4, 1, 3}, set {4, 0, 3}, set {4, 1, 2}, set {4, |
|     ------------------------------------------------------------------------|
|     0, 2}, set {4, 0, 1}, set {1, 2, 3}, set {0, 2, 3}, set {0, 1, 3}, set  |
|     ------------------------------------------------------------------------|
|     {0, 1, 2}, set {4, 5, 6}, set {6, 2, 3}, set {0, 1, 6}}                 |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : #I3                                                                     |
|                                                                             |
|o7 = 56                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * bases -- bases of matroid
  * isDependent -- whether a subset is dependent
  * independenceComplex(Matroid), --
    independence complex of matroid

Ways to use this method:
========================

  * "independentSets(Matroid)"
  * "independentSets(Matroid,List)"
  * "independentSets(Matroid,Set)"
  * independentSets(Matroid,ZZ), --
    independent subsets of a matroid

indicesOf -- indices of a sublist
*********************************

Synopsis
========

  * Usage:
        indicesOf(E, L)
        indicesOf(M, L)
  * Inputs:
      * E, a list (Macaulay2Doc),
      * M, a matroid,
      * L, a list (Macaulay2Doc), a list of sublists of E, or a
        sublist of M_*
  * Outputs:
      * a list (Macaulay2Doc), of indices

Description
===========

This method has two typical-use cases. The first case is to convert sublists of
a list E to their corresponding indices. For technical reasons, the accepted
input is a list L of sublists of E, and the output is a list of sets of
indices, one set for each sublist in L. Note that the order of elements in the
sublist is lost, when viewed as a set.

+-----------------------------------------------------------------------------+
|i1 : indicesOf(toList(a..z) | toList(0..9), {{m,a,c,a,u,l,a,y,2},{i,s},{f,u,n|
|                                                                             |
|o1 = {set {0, 2, 20, 24, 11, 28, 12}, set {8, 18}, set {20, 13, 5}}          |
|                                                                             |
|o1 : List                                                                    |
|-----------------------------------------------------------------------------|
|}})                                                                          |
+-----------------------------------------------------------------------------+

The second case is with a matroid as input. Here the ambient list E is taken as
the ground set of the matroid (i.e. E = M_*), and L should be a list of
elements of M (not a list of lists); in this case the inverse of this method is
given by taking subscripts, with respect to M.

+-----------------------------------------+
|i2 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o2 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o2 : Matroid                             |
+-----------------------------------------+
|i3 : B = {a, c}                          |
|                                         |
|o3 = {a, c}                              |
|                                         |
|o3 : List                                |
+-----------------------------------------+
|i4 : S = indicesOf(M, B)                 |
|                                         |
|o4 = {0, 2}                              |
|                                         |
|o4 : List                                |
+-----------------------------------------+
|i5 : M_S == B                            |
|                                         |
|o5 = true                                |
+-----------------------------------------+

In this case, if L is not a sublist of M_*, then a warning is printed, and L
itself is returned. This is done so that if a user inputs a list of indices,
then it will be interpreted as a set of indices. For more on this, cf.
groundSet.

See also
========

  * groundSet -- (internal) ground set
  * Matroid _ List -- elements of matroid
  * relabel -- relabel a matroid

Ways to use indicesOf:
======================

  * "indicesOf(List,List)"
  * "indicesOf(Matroid,List)"

For the programmer
==================

The object indicesOf, is a method function (Macaulay2Doc).

is3Connected -- whether a matroid is 3-connected
************************************************

Synopsis
========

  * Usage:
        is3Connected M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether M is 3-connected

Description
===========

A matroid M is called m-connected if M has no k-separations for k < m (see
getSeparation, for the definition of a k-separation). Thus
a matroid is 3-connected if it has no 2-separations (or 1-separations).

+---------------------------------------------------------+
|i1 : U1 = uniformMatroid(1, 4)                           |
|                                                         |
|o1 = a "matroid" of rank 1 on 4 elements                 |
|                                                         |
|o1 : Matroid                                             |
+---------------------------------------------------------+
|i2 : isConnected U1                                      |
|                                                         |
|o2 = true                                                |
+---------------------------------------------------------+
|i3 : is3Connected U1                                     |
|                                                         |
|o3 = false                                               |
+---------------------------------------------------------+
|i4 : is3Connected matroid completeMultipartiteGraph {3,3}|
|                                                         |
|o4 = true                                                |
+---------------------------------------------------------+

See also
========

  * isConnected(Matroid) -- whether a matroid
    is connected
  * getSeparation -- finds a k-separation of a matroid
  * sum2 -- 2-sum of matroids

Ways to use is3Connected:
=========================

  * "is3Connected(Matroid)"

For the programmer
==================

The object is3Connected, is a method function (Macaulay2Doc).

isBinary -- whether a matroid is representable over F_2
*******************************************************

Synopsis
========

  * Usage:
        isBinary M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether M is binary

Description
===========

Determines if M is a binary matroid, i.e. is representable over the field $F_2$
of 2 elements.

A matroid is representable over F_2 iff it does not have U_{2,4} as a minor.
However, this method does not go through hasMinor, for
efficiency reasons: rather it checks whether the symmetric difference of any 2
distinct circuits is dependent.

Note: in general, determining representability is a difficult computational
problem. For instance, assuming access to an independence oracle, it is known
that the problem of determining whether a matroid is binary cannot be solved in
polynomial time.

+-----------------------------------------+
|i1 : M5 = matroid completeGraph 5        |
|                                         |
|o1 = a "matroid" of rank 4 on 10 elements|
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : isBinary M5                         |
|                                         |
|o2 = true                                |
+-----------------------------------------+
|i3 : U48 = uniformMatroid(4, 8)          |
|                                         |
|o3 = a "matroid" of rank 4 on 8 elements |
|                                         |
|o3 : Matroid                             |
+-----------------------------------------+
|i4 : isBinary U48                        |
|                                         |
|o4 = false                               |
+-----------------------------------------+

See also
========

  * hasMinor -- whether a matroid has a given minor
  * getRepresentation -- retrieves stored
    representation

Ways to use isBinary:
=====================

  * "isBinary(Matroid)"

For the programmer
==================

The object isBinary, is a method function (Macaulay2Doc).

isConnected(Matroid) -- whether a matroid is connected
******************************************************

Synopsis
========

  * Function: isConnected (Graphs),
  * Usage:
        isConnected M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether M is connected

Description
===========

A matroid M is called connected if for every pair of distinct elements f, g in
M, there is a circuit containing both of them. This turns out to be equivalent
to saying that there does not exist an element e in M with rank({e}) + rank(M -
{e}) = rank(M) (note that <= always holds by submodularity of the rank
function).

This method checks connectivity using the first definition above. The second
definition generalizes to higher connectivity - cf. is3Connected.
In the language of higher connectivity, a matroid is connected
(in the sense of the two definitions above) if and only if it is 2-connected,
i.e. has no 1-separation.

To obtain the connected components of a matroid, use components.

+-----------------------------------------------------------------------------+
|i1 : M = matroid graph({{0,1},{0,2},{1,2},{3,4},{4,5}})                      |
|                                                                             |
|o1 = a "matroid" of rank 4 on 5 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : isConnected M                                                           |
|                                                                             |
|o2 = false                                                                   |
+-----------------------------------------------------------------------------+
|i3 : C = components M                                                        |
|                                                                             |
|o3 = {a "matroid" of rank 1 on 1 elements, a "matroid" of rank 1 on 1        |
|     ------------------------------------------------------------------------|
|     elements, a "matroid" of rank 2 on 3 elements}                          |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : all(C, isConnected)                                                     |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * components(Matroid) -- connected components
    of matroid
  * is3Connected -- whether a matroid is 3-connected

Ways to use this method:
========================

  * isConnected(Matroid) -- whether a matroid
    is connected

isDependent -- whether a subset is dependent
********************************************

Synopsis
========

  * Usage:
        isDependent(M, S)
  * Inputs:
      * M, a matroid,
      * S, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether S is dependent
        in M

Description
===========

This method checks if the given subset of the ground set is dependent, i.e.
contains a circuit.

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : isDependent(M, {a,b})               |
|                                         |
|o2 = false                               |
+-----------------------------------------+
|i3 : isDependent(M, {d})                 |
|                                         |
|o3 = true                                |
+-----------------------------------------+

See also
========

  * independentSets(Matroid), --
    independent subsets of a matroid

Ways to use isDependent:
========================

  * "isDependent(Matroid,List)"
  * "isDependent(Matroid,Set)"

For the programmer
==================

The object isDependent, is a method function (Macaulay2Doc).

isElementaryQuotient -- whether a matroid is an elementary quotient of another matroid
**************************************************************************************

Synopsis
========

  * Usage:
        isElementaryQuotient(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the first
        matroid is an elementary quotient of the second

Description
===========

This function is provided by the package Matroids.

An elementary quotient of a matroid N is a quotient M whose rank is the rank of
N minus one.  Elementary quotients are completely determined by the modular cut
of flats in M (which are also flats of N) whose rank in M is one less than
their rank in N. Examples of elementary quotients of N are its principal
truncations with respect to a given flat F.

+-----------------------------------------+
|i1 : N = matroid completeGraph 5         |
|                                         |
|o1 = a "matroid" of rank 4 on 10 elements|
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : F = set {0,1,4};                    |
+-----------------------------------------+
|i3 : TFN = truncate(F, N)                |
|                                         |
|o3 = a "matroid" of rank 3 on 10 elements|
|                                         |
|o3 : Matroid                             |
+-----------------------------------------+
|i4 : isElementaryQuotient(TFN, N)        |
|                                         |
|o4 = true                                |
+-----------------------------------------+
|i5 : T2N = truncate(2, N)                |
|                                         |
|o5 = a "matroid" of rank 2 on 10 elements|
|                                         |
|o5 : Matroid                             |
+-----------------------------------------+
|i6 : isElementaryQuotient(T2N, N)        |
|                                         |
|o6 = false                               |
+-----------------------------------------+

See also
========

  * elementaryQuotient -- associated to a modular
    cut or linear subclass
  * isModularCut -- whether a list of flats of a matroid
    is a modular cut
  * isQuotient -- whether a matroid is a quotient of another
    matroid
  * modularCut -- associated to an elementary quotient or
    linear subclass
  * truncate(Set,Matroid) -- the truncation
    of a matroid with respect to a flat

Ways to use isElementaryQuotient:
=================================

  * "isElementaryQuotient(Matroid,Matroid)"

For the programmer
==================

The object isElementaryQuotient, is a method function (Macaulay2Doc).

isLinearSubclass -- whether a list of hyperplanes of a matroid is a linear subclass
***********************************************************************************

Synopsis
========

  * Usage:
        isLinearSubclass(M, H)
  * Inputs:
      * M, a matroid,
      * H, a list (Macaulay2Doc), a list of hyperplanes of the
        matroid
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the list of
        hyperplanes is a linear subclass

Description
===========

This function is provided by the package Matroids.

A linear subclass for a matroid M is a collection of hyperplanes H of M that
uniquely determines a given modular cut of M.  Specifically, H is a linear
subclass if for any hyperplanes h and h' in H whose intersection has rank equal
to the rank of M minus two, every hyperplane of M containing the intersection
of h and h' is also in H.

Each hyperplane in the linear subclass may be represented as either a set or a
list of elements of the ground set of M. The list of hyperplanes H below is a
linear subclass for the uniform matroid U_{4,6} since no two hyperplanes in H
have an intersection of rank 2.

+----------------------------------------------+
|i1 : M = uniformMatroid(4, 6);                |
+----------------------------------------------+
|i2 : H = {set{0,1,2}, set{2,3,4}, set{0,3,5}};|
+----------------------------------------------+
|i3 : isLinearSubclass(M, H)                   |
|                                              |
|o3 = true                                     |
+----------------------------------------------+

The list of hyperplanes H' below is not a linear subclass since the hyperplanes
{0,1,2} and {0,1,4} have an intersection of rank 2 which is contained in the
hyperplane {0,1,3} that does not belong to H'.

+-----------------------------------------------+
|i4 : H' = {{0,1,2}, {2,3,4}, {0,3,5}, {0,1,4}};|
+-----------------------------------------------+
|i5 : isLinearSubclass(M, H')                   |
|                                               |
|o5 = false                                     |
+-----------------------------------------------+

See also
========

  * modularCut -- associated to an elementary quotient or
    linear subclass
  * linearSubclass -- associated to an elementary
    quotient or modular cut

Ways to use isLinearSubclass:
=============================

  * "isLinearSubclass(Matroid,List)"

For the programmer
==================

The object isLinearSubclass, is a method function (Macaulay2Doc).

isModularCut -- whether a list of flats of a matroid is a modular cut
*********************************************************************

Synopsis
========

  * Usage:
        isModularCut(M, K)
  * Inputs:
      * M, a matroid,
      * K, a list (Macaulay2Doc), a list of flats of the matroid
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the list of
        flats is a modular cut

Description
===========

This function is provided by the package Matroids.

A modular cut for a matroid M is a collection K of flats of M with the
properties that for any flats F and G of M: (i) if F is in K and F is contained
in G, then G is also in K, and (ii) if the rank of union of F and G plus the
rank of the intersection of F and G equals the sum of the ranks of F and G,
then the intersection of F and G is also in K. Two flats F and G satisfying the
rank condition in (ii) above are called a modular pair.  If F is contained in
G, then F and G trivially form a modular pair.

Each flat in the modular cut may be represented as either a set or a list of
elements of the ground set of M. The list of flats K below is a modular cut for
the uniform matroid U_{4,5} since the only two incomparable flats are not a
modular pair; both flats have rank 3, but their intersection and union have
rank 1 and 4 respectively.

+--------------------------------------------------+
|i1 : M = uniformMatroid(4, 5);                    |
+--------------------------------------------------+
|i2 : K = {set{0,1,2}, set{2,3,4}, set{0,1,2,3,4}};|
+--------------------------------------------------+
|i3 : isModularCut(M, K)                           |
|                                                  |
|o3 = true                                         |
+--------------------------------------------------+

The list of flats K' below is not a modular cut since the flats {0,1,2} and
{0,1,3} are a modular pair but their intersection does not belong to K'.

+------------------------------------------+
|i4 : K' = {{0,1,2}, {0,1,3}, {0,1,2,3,4}};|
+------------------------------------------+
|i5 : isModularCut(M, K')                  |
|                                          |
|o5 = false                                |
+------------------------------------------+

See also
========

  * modularCut -- associated to an elementary quotient or
    linear subclass
  * linearSubclass -- associated to an elementary
    quotient or modular cut

Ways to use isModularCut:
=========================

  * "isModularCut(Matroid,List)"

For the programmer
==================

The object isModularCut, is a method function (Macaulay2Doc).

isNonCrossing -- whether 2 subsets are non-crossing
***************************************************

Synopsis
========

  * Usage:
        isNonCrossing(A, B)
  * Inputs:
      * A, a list (Macaulay2Doc),
      * B, a list (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether A and B are
        non-crossing subsets of [n]

Description
===========

This function determines whether two disjoint subsets of [n] are non-crossing.

+-----------------------------------+
|i1 : isNonCrossing({0,1,7},{2,4,5})|
|                                   |
|o1 = true                          |
+-----------------------------------+
|i2 : isNonCrossing({2,3,6},{1,4})  |
|                                   |
|o2 = false                         |
+-----------------------------------+

See also
========

  * isPositivelyOriented -- whether a matroid is
    positively oriented

Ways to use isNonCrossing:
==========================

  * "isNonCrossing(List,List)"
  * "isNonCrossing(Set,Set)"

For the programmer
==================

The object isNonCrossing, is a method function (Macaulay2Doc).

isomorphism(Matroid,Matroid) -- computes an isomorphism between isomorphic matroids
***********************************************************************************

Synopsis
========

  * Function: isomorphism (Posets),
  * Usage:
        isomorphism(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a hash table (Macaulay2Doc), an isomorphism between M
        and N

Description
===========

This method computes a single isomorphism,
between M and N, if one exists, and
returns null (Macaulay2Doc), if no such isomorphism exists.

The output is a HashTable (Macaulay2Doc), where the keys are
elements of the groundSet, of M, and their corresponding
values are elements of (the ground set of) N.

To obtain all isomorphisms between two matroids, use getIsos.

+-----------------------------------------------------------------------------+
|i1 : M = matroid({a,b,c},{{a,b},{a,c}})                                      |
|                                                                             |
|o1 = a "matroid" of rank 2 on 3 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : isomorphism(M, uniformMatroid(2,3)) -- not isomorphic                   |
+-----------------------------------------------------------------------------+
|i3 : (M5, M6) = (5,6)/completeGraph/matroid                                  |
|                                                                             |
|o3 = (a "matroid" of rank 4 on 10 elements, a "matroid" of rank 5 on 15      |
|     ------------------------------------------------------------------------|
|     elements)                                                               |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i4 : minorM6 = minor(M6, set{8}, set{4,5,6,7})                               |
|                                                                             |
|o4 = a "matroid" of rank 4 on 10 elements                                    |
|                                                                             |
|o4 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i5 : time isomorphism(M5, minorM6)                                           |
| -- used 0.0100003s (cpu); 0.00981761s (thread); 0s (gc)                     |
|                                                                             |
|o5 = HashTable{0 => 1}                                                       |
|               1 => 0                                                        |
|               2 => 3                                                        |
|               3 => 2                                                        |
|               4 => 6                                                        |
|               5 => 5                                                        |
|               6 => 4                                                        |
|               7 => 9                                                        |
|               8 => 8                                                        |
|               9 => 7                                                        |
|                                                                             |
|o5 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i6 : isomorphism(M5, M5)                                                     |
|                                                                             |
|o6 = HashTable{0 => 0}                                                       |
|               1 => 1                                                        |
|               2 => 2                                                        |
|               3 => 3                                                        |
|               4 => 4                                                        |
|               5 => 5                                                        |
|               6 => 6                                                        |
|               7 => 7                                                        |
|               8 => 8                                                        |
|               9 => 9                                                        |
|                                                                             |
|o6 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i7 : N = relabel M6                                                          |
|                                                                             |
|o7 = a "matroid" of rank 5 on 15 elements                                    |
|                                                                             |
|o7 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i8 : time phi = isomorphism(N,M6)                                            |
| -- used 8.01067s (cpu); 3.29692s (thread); 0s (gc)                          |
|                                                                             |
|o8 = HashTable{0 => 11 }                                                     |
|               1 => 0                                                        |
|               2 => 1                                                        |
|               3 => 6                                                        |
|               4 => 9                                                        |
|               5 => 8                                                        |
|               6 => 5                                                        |
|               7 => 12                                                       |
|               8 => 7                                                        |
|               9 => 3                                                        |
|               10 => 10                                                      |
|               11 => 4                                                       |
|               12 => 2                                                       |
|               13 => 13                                                      |
|               14 => 14                                                      |
|                                                                             |
|o8 : HashTable                                                               |
+-----------------------------------------------------------------------------+

See also
========

  * getIsos -- all isomorphisms between two matroids
  * quickIsomorphismTest -- quick checks for
    isomorphism between matroids
  * areIsomorphic(Matroid,Matroid),
    -- whether two matroids are isomorphic

Ways to use this method:
========================

  * isomorphism(Matroid,Matroid), --
    computes an isomorphism between isomorphic matroids

isoTypes -- distinct isomorphism classes
****************************************

Synopsis
========

  * Usage:
        isoTypes L
  * Inputs:
      * L, a list (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc), of distinct isomorphism classes
        among elements of L

Description
===========

Given a list of Macaulay2 objects for which areIsomorphic,
makes sense for any pair, this method
determines the distinct isomorphism classes appearing in the list, by
performing "upper-triangular" comparisons of pairs.

In particular, the output list (of representatives of each isomorphism class)
is always ordered consistently with the order of the original list.

If the list has size $n$, and all objects are pairwise non-isomorphic, then
($n$ choose $2$) comparisons are made, while if all objects are isomorphic,
then only $n-1$ comparisons are made.

+-----------------------------------------------------------------------------+
|i1 : M = uniformMatroid_3 5                                                  |
|                                                                             |
|o1 = a "matroid" of rank 3 on 5 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : L = {M / {0}, uniformMatroid_2 4, matroid random(QQ^2,QQ^4)}            |
|                                                                             |
|o2 = {a "matroid" of rank 2 on 4 elements, a "matroid" of rank 2 on 4        |
|     ------------------------------------------------------------------------|
|     elements, a "matroid" of rank 2 on 4 elements}                          |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : isoTypes L                                                              |
|                                                                             |
|o3 = {a "matroid" of rank 2 on 4 elements}                                   |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * areIsomorphic(Matroid,Matroid),
    -- whether two matroids are isomorphic
  * getIsos -- all isomorphisms between two matroids

Ways to use isoTypes:
=====================

  * "isoTypes(List)"

For the programmer
==================

The object isoTypes, is a method function (Macaulay2Doc).

isPositivelyOrientable -- whether a matroid is positively orientable
********************************************************************

Synopsis
========

  * Usage:
        isPositivelyOrientable M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether M is positively
        orientable

Description
===========

This function determines whether a matroid is positively orientable, i.e. has a
relabelling, for which it is positively oriented.

+--------------------------------------------------------------+
|i1 : M = matroid({{0,1},{2,3},{4,5}}, EntryMode => "circuits")|
|                                                              |
|o1 = a "matroid" of rank 3 on 6 elements                      |
|                                                              |
|o1 : Matroid                                                  |
+--------------------------------------------------------------+
|i2 : isPositivelyOrientable M                                 |
|                                                              |
|o2 = true                                                     |
+--------------------------------------------------------------+

See also
========

  * isPositivelyOriented -- whether a matroid is
    positively oriented
  * positiveOrientation -- a positive orientation
    of a matroid

Ways to use isPositivelyOrientable:
===================================

  * "isPositivelyOrientable(Matroid)"

For the programmer
==================

The object isPositivelyOrientable, is a
method function (Macaulay2Doc).

isPositivelyOriented -- whether a matroid is positively oriented
****************************************************************

Synopsis
========

  * Usage:
        isPositivelyOriented M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether M is positively
        oriented

Description
===========

This function determines whether a matroid is positively oriented, using a
theorem of da Silva (which checks whether any disjoint circuit,
-cocircuit pair is non-crossing).

+--------------------------------------------------------------+
|i1 : M = matroid({{0,1},{2,3},{4,5}}, EntryMode => "circuits")|
|                                                              |
|o1 = a "matroid" of rank 3 on 6 elements                      |
|                                                              |
|o1 : Matroid                                                  |
+--------------------------------------------------------------+
|i2 : isPositivelyOriented M                                   |
|                                                              |
|o2 = false                                                    |
+--------------------------------------------------------------+

See also
========

  * isPositivelyOrientable -- whether a matroid
    is positively orientable
  * positiveOrientation -- a positive orientation
    of a matroid

Ways to use isPositivelyOriented:
=================================

  * "isPositivelyOriented(Matroid)"

For the programmer
==================

The object isPositivelyOriented, is a method function (Macaulay2Doc).

isQuotient -- whether a matroid is a quotient of another matroid
****************************************************************

Synopsis
========

  * Usage:
        isQuotient(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the first
        matroid is a quotient of the second

Description
===========

This function is provided by the package Matroids.

A matroid M is a quotient of a matroid N if the matroids have the same ground
set and every flat of M is a flat of N.

+-----------------------------------------------------------------------------+
|i1 : N = matroid completeGraph 6;                                            |
+-----------------------------------------------------------------------------+
|i2 : T2N = truncate(2, N)                                                    |
|                                                                             |
|o2 = a "matroid" of rank 3 on 15 elements                                    |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : partition(F -> rank(T2N, F), flats T2N)                                 |
|                                                                             |
|o3 = HashTable{0 => {set {}}                                                 |
|               1 => {set {14}, set {13}, set {12}, set {11}, set {10}, set {9|
|               2 => {set {12, 13, 14}, set {14, 10, 11}, set {9, 14}, set {8,|
|               3 => {set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14}} |
|                                                                             |
|o3 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|}, set {8}, set {7}, set {6}, set {5}, set                                   |
| 14, 7}, set {14, 6}, set {5, 14}, set {4,                                   |
|-----------------------------------------------------------------------------|
|                                                                             |
|{4}, set {3}, set {2}, set {1}, set {0}}                                     |
|14, 3}, set {14, 2}, set {1, 14}, set {0, 14}, set {13, 9, 11}, set {13, 10},|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|set {8, 13, 6}, set {13, 7}, set {13, 5}, set {4, 13, 2}, set {13, 3}, set   |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|{13, 1}, set {0, 13}, set {12, 11}, set {12, 9, 10}, set {12, 8}, set {12, 6,|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|7}, set {12, 5}, set {12, 4}, set {12, 2, 3}, set {12, 1}, set {12, 0}, set  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|{8, 5, 11}, set {11, 7}, set {6, 11}, set {4, 1, 11}, set {11, 3}, set {2,   |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|11}, set {0, 11}, set {8, 10}, set {5, 10, 7}, set {10, 6}, set {4, 10}, set |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|{1, 10, 3}, set {10, 2}, set {0, 10}, set {8, 9}, set {9, 7}, set {9, 5, 6}, |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|set {4, 9}, set {9, 3}, set {9, 1, 2}, set {0, 9}, set {8, 4, 0}, set {8, 3},|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|set {8, 2}, set {8, 1}, set {4, 7}, set {0, 7, 3}, set {2, 7}, set {1, 7},   |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|set {4, 6}, set {6, 3}, set {0, 6, 2}, set {1, 6}, set {4, 5}, set {5, 3},   |
|-----------------------------------------------------------------------------|
|                          }                                                  |
|                                                                             |
|set {5, 2}, set {0, 5, 1}}                                                   |
+-----------------------------------------------------------------------------+
|i4 : isQuotient(T2N, N)                                                      |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * elementaryQuotient -- associated to a modular
    cut or linear subclass
  * isElementaryQuotient -- whether a matroid is
    an elementary quotient of another matroid
  * truncate(Set,Matroid) -- the truncation
    of a matroid with respect to a flat

Ways to use isQuotient:
=======================

  * "isQuotient(Matroid,Matroid)"

For the programmer
==================

The object isQuotient, is a method function (Macaulay2Doc).

isSimple(Matroid) -- whether a matroid is simple
************************************************

Synopsis
========

  * Function: isSimple (Graphs),
  * Usage:
        isSimple M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether M is a simple
        matroid

Description
===========

A matroid is simple if it has no loops, or parallel classes;
equivalently, it has no circuits, of size <= 2.

Among the class of simple matroids, the lattice of flats,
is a complete invariant. Every matroid has a unique simplification,
which has the same lattice of flats.

+-----------------------------------------------------------------------------+
|i1 : isSimple matroid completeGraph 3                                        |
|                                                                             |
|o1 = true                                                                    |
+-----------------------------------------------------------------------------+
|i2 : M = matroid(completeGraph 3, ParallelEdges =>                           |
|                                                                             |
|o2 = a "matroid" of rank 2 on 8 elements                                     |
|                                                                             |
|o2 : Matroid                                                                 |
|-----------------------------------------------------------------------------|
|{set{0,1},set{0,1},set{1,2}}, Loops => {0,2})                                |
+-----------------------------------------------------------------------------+
|i3 : isSimple M                                                              |
|                                                                             |
|o3 = false                                                                   |
+-----------------------------------------------------------------------------+
|i4 : S = simpleMatroid M                                                     |
|                                                                             |
|o4 = a "matroid" of rank 2 on 3 elements                                     |
|                                                                             |
|o4 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i5 : isSimple S                                                              |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : latticeOfFlats M == latticeOfFlats S                                    |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

Note that the dual, of a simple matroid may not be
simple:

+----------------------------------------+
|i7 : U = uniformMatroid(2, 2)           |
|                                        |
|o7 = a "matroid" of rank 2 on 2 elements|
|                                        |
|o7 : Matroid                            |
+----------------------------------------+
|i8 : isSimple U                         |
|                                        |
|o8 = true                               |
+----------------------------------------+
|i9 : isSimple dual U                    |
|                                        |
|o9 = false                              |
+----------------------------------------+

See also
========

  * simpleMatroid -- simple matroid associated to a
    matroid

Ways to use this method:
========================

  * isSimple(Matroid) -- whether a matroid is
    simple

isWellDefined(Matroid) -- whether the input is a well-defined matroid
*********************************************************************

Synopsis
========

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        isWellDefined M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether or not a set of
        subsets satisfies the circuit elimination axiom

Description
===========

If E is a set and C is a collection of subsets of E such that (i) no two
elements of C are comparable, and (ii): for C1, C2 in C and $e \in C1 \cap C2$,
there exists $C3 \in C$ with $C \subseteq (C1 \cup C2) - e$, then C is the set
of circuits of a matroid on E. Property (ii) is called the circuit elimination
axiom, and these characterize the collections of subsets of E which can be
circuits for a matroid on E. This method verifies if the circuit elimination
axiom holds for the given input, and additionally whether the input has the
correct keys and data types that an object of type Matroid has.

+-----------------------------------------------------------------------------+
|i1 : isWellDefined matroid({a,b,c,d},{{a,b},{c,d}})                          |
|                                                                             |
|o1 = false                                                                   |
+-----------------------------------------------------------------------------+
|i2 : isWellDefined matroid({a,b,c,d},{{a,b},{a,c}})                          |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
|i3 : isWellDefined matroid({{1,2,3},{1,4,5},{2,3,4,5},{2,3,6,7},{4,5,6,7}},  |
|                                                                             |
|o3 = false                                                                   |
|-----------------------------------------------------------------------------|
|EntryMode =>"circuits") -- the Escher "matroid"                              |
+-----------------------------------------------------------------------------+
|i4 : isWellDefined matroid({{1,2,3},{1,4,5},{1,6,7},{2,3,4,5},{2,3,6,7},{4,5,|
|                                                                             |
|o4 = true                                                                    |
|-----------------------------------------------------------------------------|
|6,7}}, EntryMode =>"circuits")                                               |
+-----------------------------------------------------------------------------+
|i5 : isWellDefined matroid random(ZZ^3, ZZ^5)                                |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : isWellDefined matroid completeGraph 4                                   |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : isWellDefined uniformMatroid(4, 5)                                      |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

A theorem of Terai and Trung states that a monomial ideal is the
Stanley-Reisner ideal for (the independence complex of) a matroid iff all
symbolic powers is Cohen-Macaulay (indeed, this happens iff the 3rd symbolic
power is Cohen-Macaulay). This can be verified as follows:

+-----------------------------------------------------------------------------+
|i8 : R = QQ[x_0..x_3]                                                        |
|                                                                             |
|o8 = R                                                                       |
|                                                                             |
|o8 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i9 : I = monomialIdeal(x_0*x_1, x_0*x_2, x_3)                                |
|                                                                             |
|o9 = monomialIdeal (x x , x x , x )                                          |
|                     0 1   0 2   3                                           |
|                                                                             |
|o9 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i10 : isWellDefined matroid I                                                |
|                                                                             |
|o10 = false                                                                  |
+-----------------------------------------------------------------------------+
|i11 : symbolicCube = intersect apply(irreducibleDecomposition I, P -> P^3)   |
|                                                                             |
|                      3 3   3 2     3   2   3 3   2 2     2         2 2      |
|o11 = monomialIdeal (x x , x x x , x x x , x x , x x x , x x x x , x x x ,   |
|                      0 1   0 1 2   0 1 2   0 2   0 1 3   0 1 2 3   0 2 3    |
|      -----------------------------------------------------------------------|
|           2       2   3                                                     |
|      x x x , x x x , x )                                                    |
|       0 1 3   0 2 3   3                                                     |
|                                                                             |
|o11 : MonomialIdeal of R                                                     |
+-----------------------------------------------------------------------------+
|i12 : (codim symbolicCube, pdim betti res symbolicCube)                      |
|                                                                             |
|o12 = (2, 3)                                                                 |
|                                                                             |
|o12 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * isWellDefined(Matroid) -- whether the
    input is a well-defined matroid

latticeOfFlats -- lattice of flats of a matroid
***********************************************

Synopsis
========

  * Usage:
        latticeOfFlats M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * an instance of the type Poset (Posets),

Description
===========

The lattice of flats of a matroid M is the set of flats of M, partially ordered
by containment; i.e. $F1 \le F2$ if F1 is contained in F2. The lattice of flats
of a matroid is a geometric lattice: i.e. it is atomic (every element is a join
of atoms = rank 1 elements) and semimodular ($h(x) + h(y) \ge h(x \vee y) + h(x
\wedge y)$ for any x, y, where h is the height function = maximum length of a
chain from 0, and all maximal chains have the same length). Conversely, every
geometric lattice is the lattice of flats of a matroid.

If M and N are simple matroids, (i.e. no loops or
parallel classes) with isomorphic lattice of flats, then M and N are
isomorphic.

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : latticeOfFlats M                    |
|                                         |
|o2 = Relation Matrix: | 1 1 1 1 |        |
|                      | 0 1 0 1 |        |
|                      | 0 0 1 1 |        |
|                      | 0 0 0 1 |        |
|                                         |
|o2 : Poset                               |
+-----------------------------------------+

One can also view the lattice of flats, using displayPoset (Posets),
provided by the Posets, package (the
option SuppressLabels (Posets), may be useful).

See also
========

  * flats -- flats of a matroid
  * rank(Matroid) -- rank of a matroid
  * fVector(Matroid) -- f-vector of a matroid

Ways to use latticeOfFlats:
===========================

  * "latticeOfFlats(Matroid)"

For the programmer
==================

The object latticeOfFlats, is a method function (Macaulay2Doc).

linearSubclass -- associated to an elementary quotient or modular cut
*********************************************************************

Synopsis
========

  * Usage:
        linearSubclass(M, N),
        linearSubclass(M, K)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
      * K, a list (Macaulay2Doc), a list of flats of the matroid
        forming a modular cut
  * Optional inputs (Macaulay2Doc),:
      * CheckWellDefined,
        => ...,
        default value false, check whether the list is a modular cut
  * Outputs:
      * a list (Macaulay2Doc), a list of hyperplanes of the matroid
        forming a linear subclass

Description
===========

This function is provided by the package Matroids.

A modular cut K of the matroid M is determined by the collection of hyperplanes
of M that belong to K, which is called the corresponding linear subclass.  See
isLinearSubclass, for more details about linear
subclasses. Given a list K of flats of M forming a modular cut, this function
produces the corresponding linear subclass.

+--------------------------------------------------------------------+
|i1 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}|
|                                                                    |
|o1 = | 1 0 0 1 1  |                                                 |
|     | 0 1 0 1 -1 |                                                 |
|     | 0 0 1 0 0  |                                                 |
|                                                                    |
|              3       5                                             |
|o1 : Matrix ZZ  <-- ZZ                                              |
+--------------------------------------------------------------------+
|i2 : M = matroid A                                                  |
|                                                                    |
|o2 = a "matroid" of rank 3 on 5 elements                            |
|                                                                    |
|o2 : Matroid                                                        |
+--------------------------------------------------------------------+
|i3 : K = {{2}, {2, 4}, {2, 3}, {1, 2}, {0, 2}, {0, 1, 2, 3, 4}};    |
+--------------------------------------------------------------------+
|i4 : isModularCut(M, K)                                             |
|                                                                    |
|o4 = true                                                           |
+--------------------------------------------------------------------+
|i5 : linearSubclass(M, K)                                           |
|                                                                    |
|o5 = {set {0, 2}, set {4, 2}, set {1, 2}, set {2, 3}}               |
|                                                                    |
|o5 : List                                                           |
+--------------------------------------------------------------------+

Since every elementary quotient M of a matroid N determines a modular cut of
flats of N, we can find the corresponding linear subclass as follows.

+------------------------------------------------------------------------+
|i6 : N = matroid completeGraph 5                                        |
|                                                                        |
|o6 = a "matroid" of rank 4 on 10 elements                               |
|                                                                        |
|o6 : Matroid                                                            |
+------------------------------------------------------------------------+
|i7 : F = set {0, 1, 4};                                                 |
+------------------------------------------------------------------------+
|i8 : TFN = truncate(F, N);                                              |
+------------------------------------------------------------------------+
|i9 : isElementaryQuotient(TFN, N)                                       |
|                                                                        |
|o9 = true                                                               |
+------------------------------------------------------------------------+
|i10 : linearSubclass(TFN, N)                                            |
|                                                                        |
|o10 = {set {0, 9, 1, 4}, set {0, 1, 2, 4, 5, 7}, set {8, 0, 1, 3, 4, 6}}|
|                                                                        |
|o10 : List                                                              |
+------------------------------------------------------------------------+

See also
========

  * elementaryQuotient -- associated to a modular
    cut or linear subclass
  * isElementaryQuotient -- whether a matroid is
    an elementary quotient of another matroid
  * isLinearSubclass -- whether a list of hyperplanes
    of a matroid is a linear subclass
  * isModularCut -- whether a list of flats of a matroid
    is a modular cut
  * modularCut -- associated to an elementary quotient or
    linear subclass

Ways to use linearSubclass:
===========================

  * "linearSubclass(Matroid,List)"
  * "linearSubclass(Matroid,Matroid)"

For the programmer
==================

The object linearSubclass, is a method function with options (Macaulay2Doc).

linearSubclass(...,CheckWellDefined=>...) -- check whether the list is a modular cut
************************************************************************************

Synopsis
========

  * Usage:
        linearSubclass(M, K, CheckWellDefined => true)
  * Inputs:
      * M, a matroid,
      * K, a list (Macaulay2Doc), a list of flats of the matroid
        forming a modular cut
  * Outputs:
      * a list (Macaulay2Doc), a list of hyperplanes of the matroid
        forming a linear subclass

Description
===========

This option is provided by the package Matroids.

When producing the linear subclass of a matroid M corresponding to a list of
flats K, setting this option to true calls isModularCut, to
check that the list K is in fact a modular cut.

+--------------------------------------------------------------------+
|i1 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}|
|                                                                    |
|o1 = | 1 0 0 1 1  |                                                 |
|     | 0 1 0 1 -1 |                                                 |
|     | 0 0 1 0 0  |                                                 |
|                                                                    |
|              3       5                                             |
|o1 : Matrix ZZ  <-- ZZ                                              |
+--------------------------------------------------------------------+
|i2 : M = matroid A                                                  |
|                                                                    |
|o2 = a "matroid" of rank 3 on 5 elements                            |
|                                                                    |
|o2 : Matroid                                                        |
+--------------------------------------------------------------------+
|i3 : K = {{2}, {2, 4}, {2, 3}, {1, 2}, {0, 2}, {0, 1, 2, 3, 4}};    |
+--------------------------------------------------------------------+
|i4 : linearSubclass(M, K, CheckWellDefined => true)                 |
|                                                                    |
|o4 = {set {0, 2}, set {4, 2}, set {1, 2}, set {2, 3}}               |
|                                                                    |
|o4 : List                                                           |
+--------------------------------------------------------------------+

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: linearSubclass, -- associated to an
    elementary quotient or modular cut
  * Option key: CheckWellDefined, -- an optional
    argument

See also
========

  * linearSubclass -- associated to an elementary
    quotient or modular cut

Functions with optional argument named CheckWellDefined:
========================================================

  * "relaxation(...,CheckWellDefined=>...)" -- see CheckWellDefined,
    -- an optional argument
  * elementaryQuotient(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut or linear subclass
  * extension(...,CheckWellDefined=>...)
    -- check whether
    the list is a modular cut or linear subclass
  * linearSubclass(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut
  * modularCut(...,CheckWellDefined=>...)
    -- check whether
    the list is a linear subclass

loops -- loops of matroid
*************************

Synopsis
========

  * Usage:
        loops M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a list (Macaulay2Doc), the loops of M

Description
===========

The loops of a matroid are the one-element circuits.

+--------------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})         |
|                                                  |
|o1 = a "matroid" of rank 2 on 4 elements          |
|                                                  |
|o1 : Matroid                                      |
+--------------------------------------------------+
|i2 : loops M                                      |
|                                                  |
|o2 = {3}                                          |
|                                                  |
|o2 : List                                         |
+--------------------------------------------------+
|i3 : all(loops M, l -> member(set{l}, circuits M))|
|                                                  |
|o3 = true                                         |
+--------------------------------------------------+
|i4 : loops(M/(set loops M)) == {}                 |
|                                                  |
|o4 = true                                         |
+--------------------------------------------------+

See also
========

  * coloops -- coloops of matroid
  * circuits -- circuits of matroid

Ways to use loops:
==================

  * "loops(Matroid)"

For the programmer
==================

The object loops, is a method function (Macaulay2Doc).

Matroid -- the class of all matroids
************************************

Description
===========

To see how to specify a matroid, see matroid.

In this package, the ground set of the matroid is always (internally) assumed
to be a set of the form $\{0, ..., n-1\}$. This means that although the actual
elements of the ground set can be arbitrary, all subsets of the ground set are
specified by their indices, i.e. as a subset of $\{0, ..., n-1\}$ (this
includes bases, circuits, flats, loops, etc.).

For convenience, the user can specify a subset of the ground set either by
indices (which are integers between 0 and n-1), or as actual elements. If
indices are used, they should be given as a Set (Macaulay2Doc), and
if elements are used, they should be given as a List (Macaulay2Doc).

One can use the function indicesOf, to convert elements of the
ground set to their indices. Conversely, use subscripts,
to obtain the elements from their indices.

A recommended way to circumvent this distinction between indices and elements
is to make the elements of M equal to integers from 0 to n-1, in which case an
element is equal to its index in M.groundSet.

For more on this package-wide convention, see groundSet.

+-----------------------------------------------------------------------------+
|i1 : U24 = uniformMatroid(2, 4)                                              |
|                                                                             |
|o1 = a "matroid" of rank 2 on 4 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : U24 == dual U24                                                         |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
|i3 : ideal U24                                                               |
|                                                                             |
|o3 = monomialIdeal (x x x , x x x , x x x , x x x )                          |
|                     0 1 2   0 1 3   0 2 3   1 2 3                           |
|                                                                             |
|o3 : MonomialIdeal of QQ[x ..x ]                                             |
|                          0   3                                              |
+-----------------------------------------------------------------------------+
|i4 : peek U24                                                                |
|                                                                             |
|o4 = Matroid{bases => {set {0, 1}, set {0, 2}, set {1, 2}, set {0, 3}, set   |
|             cache => CacheTable{...3...}                                    |
|             groundSet => set {0, 1, 2, 3}                                   |
|             rank => 2                                                       |
|-----------------------------------------------------------------------------|
|{1, 3}, set {2, 3}}}                                                         |
+-----------------------------------------------------------------------------+
|i5 : tuttePolynomial U24                                                     |
|                                                                             |
|      2    2                                                                 |
|o5 = x  + y  + 2x + 2y                                                       |
|                                                                             |
|o5 : ZZ[x..y]                                                                |
+-----------------------------------------------------------------------------+
|i6 : N = U24 / {0}                                                           |
|                                                                             |
|o6 = a "matroid" of rank 1 on 3 elements                                     |
|                                                                             |
|o6 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i7 : areIsomorphic(N, uniformMatroid(1, 3))                                  |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

Many computations performed in this package are cached in order to speed up
subsequent calculations (as well as avoiding redundancy). These include the
circuits, flats, ideal,
see rank function, and
Tutte polynomial, of a matroid, and are stored in
the CacheTable (Macaulay2Doc), of the matroid. Since the cache
is a MutableHashTable (Macaulay2Doc), the user can also
manually cache data (e.g. if it has been computed in a previous session), which
can greatly speed up computation.

+-----------------------------------------------------------------------------+
|i8 : R10 = specificMatroid "R10"                                             |
|                                                                             |
|o8 = a "matroid" of rank 5 on 10 elements                                    |
|                                                                             |
|o8 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i9 : keys R10.cache                                                          |
|                                                                             |
|o9 = {groundSet, rankFunction, storedRepresentation}                         |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : time isWellDefined R10                                                 |
| -- used 0.0905457s (cpu); 0.0551402s (thread); 0s (gc)                      |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+
|i11 : time fVector R10                                                       |
| -- used 0.0786207s (cpu); 0.0449226s (thread); 0s (gc)                      |
|                                                                             |
|o11 = HashTable{0 => 1 }                                                     |
|                1 => 10                                                      |
|                2 => 45                                                      |
|                3 => 75                                                      |
|                4 => 30                                                      |
|                5 => 1                                                       |
|                                                                             |
|o11 : HashTable                                                              |
+-----------------------------------------------------------------------------+
|i12 : keys R10.cache                                                         |
|                                                                             |
|o12 = {hyperplanes, flatsRelationsTable, rankFunction, ideal, ranks, flats,  |
|      -----------------------------------------------------------------------|
|      groundSet, dual, storedRepresentation}                                 |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+
|i13 : time fVector R10                                                       |
| -- used 0.000253267s (cpu); 0.000149759s (thread); 0s (gc)                  |
|                                                                             |
|o13 = HashTable{0 => 1 }                                                     |
|                1 => 10                                                      |
|                2 => 45                                                      |
|                3 => 75                                                      |
|                4 => 30                                                      |
|                5 => 1                                                       |
|                                                                             |
|o13 : HashTable                                                              |
+-----------------------------------------------------------------------------+

Functions and methods returning a matroid:
==========================================

  * "affineGeometry(ZZ,ZZ)" -- see affineGeometry, --
    affine geometry of rank n+1 over F_p
  * "coextension(Matroid)" -- see coextension, -- the free
    coextension of a matroid
  * "contraction(Matroid,List)" -- see contraction, --
    contraction of subset of matroid
  * "contraction(Matroid,Set)" -- see contraction, --
    contraction of subset of matroid
  * "deletion(Matroid,List)" -- see deletion, -- deletion of
    subset of matroid
  * "deletion(Matroid,Set)" -- see deletion, -- deletion of
    subset of matroid
  * dual(Matroid) -- dual matroid
  * "elementaryQuotient(Matroid,List)" -- see elementaryQuotient,
    -- associated to a modular cut or linear subclass
  * "extension(Matroid)" -- see extension, -- of a matroid
    relative to a flat or modular cut
  * "extension(Matroid,List)" -- see extension, -- of a
    matroid relative to a flat or modular cut
  * "extension(Matroid,Set)" -- see extension, -- of a matroid
    relative to a flat or modular cut
  * "matroid(Graph)" -- see matroid, -- constructs a matroid
  * "matroid(Ideal)" -- see matroid, -- constructs a matroid
  * "matroid(List)" -- see matroid, -- constructs a matroid
  * "matroid(List,List)" -- see matroid, -- constructs a matroid
  * "matroid(List,List,ZZ)" -- see matroid, -- constructs a
    matroid
  * "matroid(List,MonomialIdeal)" -- see matroid, -- constructs
    a matroid
  * "matroid(Matrix)" -- see matroid, -- constructs a matroid
  * "matroid(ZZ,List)" -- see matroid, -- constructs a matroid
  * "minor(Matroid,List,List)" -- see minor, -- minor of matroid
  * "minor(Matroid,Set,Set)" -- see minor, -- minor of matroid
  * "parallelConnection(Matroid,Matroid)" -- see parallelConnection,
    -- parallel connection of two matroids
  * "projectiveGeometry(ZZ,ZZ)" -- see projectiveGeometry,
    -- projective geometry of dimension n over F_p
  * "relabel(Matroid)" -- see relabel, -- relabel a matroid
  * "relabel(Matroid,HashTable)" -- see relabel, -- relabel a
    matroid
  * "relabel(Matroid,List)" -- see relabel, -- relabel a matroid
  * "relaxation(Matroid)" -- see relaxation, -- relaxation of
    matroid
  * "relaxation(Matroid,List)" -- see relaxation, --
    relaxation of matroid
  * "relaxation(Matroid,Set)" -- see relaxation, --
    relaxation of matroid
  * "restriction(Matroid,List)" -- see restriction, --
    restriction to subset of matroid
  * "restriction(Matroid,Set)" -- see restriction, --
    restriction to subset of matroid
  * "seriesConnection(Matroid,Matroid)" -- see seriesConnection,
    -- series connection of two matroids
  * "setRepresentation(Matroid,Matrix)" -- see setRepresentation,
    -- stores user-defined representation
  * "simpleMatroid(Matroid)" -- see simpleMatroid, --
    simple matroid associated to a matroid
  * "specificMatroid(String)" -- see specificMatroid, --
    creates built-in matroid
  * "specificMatroid(Symbol)" -- see specificMatroid, --
    creates built-in matroid
  * "binarySpike(ZZ)" -- see spike, -- spike matroid
  * "spike(ZZ)" -- see spike, -- spike matroid
  * "spike(ZZ,List)" -- see spike, -- spike matroid
  * "sum2(Matroid,Matroid)" -- see sum2, -- 2-sum of matroids
  * "swirl(ZZ)" -- see swirl, -- swirl matroid
  * "thetaMatroid(ZZ)" -- see thetaMatroid, -- theta
    matroid
  * "fromSageMatroid(String)" -- see toSageMatroid, --
    Sage format for matroid
  * "uniformMatroid(ZZ,ZZ)" -- see uniformMatroid, --
    uniform matroid
  * "wheel(ZZ)" -- see wheel, -- wheels/whirls
  * "whirl(ZZ)" -- see wheel, -- wheels/whirls

Methods that use a matroid:
===========================

  * "allMinors(Matroid,Matroid)" -- see allMinors, -- returns
    all minors of one matroid in another
  * areIsomorphic(Matroid,Matroid),
    -- whether two matroids are isomorphic
  * "bases(Matroid)" -- see bases, -- bases of matroid
  * "basisIndicatorMatrix(Matroid)" -- see basisIndicatorMatrix,
    -- matrix of basis polytope
  * characteristicPolynomial(Matroid)
    -- computes characteristic
    polynomial of a matroid
  * "circuits(Matroid)" -- see circuits, -- circuits of matroid
  * "closure(Matroid,List)" -- see closure, -- closure of a
    subset of a matroid
  * "closure(Matroid,Set)" -- see closure, -- closure of a
    subset of a matroid
  * "cogeneratorChowRing(Matroid)" -- see cogeneratorChowRing,
    -- cogenerator of the Chow ring of a matroid
  * "coloops(Matroid)" -- see coloops, -- coloops of matroid
  * components(Matroid) -- connected components
    of matroid
  * "Matroid / List" -- see contraction, -- contraction of
    subset of matroid
  * "Matroid / Set" -- see contraction, -- contraction of
    subset of matroid
  * /// Matroid \ List /// -- see deletion, -- deletion of
    subset of matroid
  * /// Matroid \ Set /// -- see deletion, -- deletion of
    subset of matroid
  * "flats(Matroid)" -- see flats, -- flats of a matroid
  * "flats(Matroid,ZZ)" -- see flats, -- flats of a matroid
  * "flats(Matroid,ZZ,String)" -- see flats, -- flats of a matroid
  * "fundamentalCircuit(Matroid,List,Thing)" -- see fundamentalCircuit,
    -- fundamental circuit of independent set
  * "fundamentalCircuit(Matroid,Set,ZZ)" -- see fundamentalCircuit,
    -- fundamental circuit of independent set
  * fVector(Matroid) -- f-vector of a matroid
  * "getIsos(Matroid,Matroid)" -- see getIsos, -- all
    isomorphisms between two matroids
  * "getRepresentation(Matroid)" -- see getRepresentation,
    -- retrieves stored representation
  * "getSeparation(Matroid,ZZ)" -- see getSeparation, --
    finds a k-separation of a matroid
  * "groundSet(Matroid)" -- see groundSet, -- (internal)
    ground set
  * "hasMinor(Matroid,Matroid)" -- see hasMinor, -- whether a
    matroid has a given minor
  * "hyperplanes(Matroid)" -- see hyperplanes, --
    hyperplanes of a matroid
  * ideal(Matroid) -- Stanley-Reisner (circuit)
    ideal of matroid
  * "idealChowRing(Matroid)" -- see idealChowRing, -- the
    defining ideal of the Chow ring
  * idealOrlikSolomonAlgebra(Matroid) (missing documentation)
  * independenceComplex(Matroid), --
    independence complex of matroid
  * "independentSets(Matroid)" -- see independentSets(Matroid,ZZ),
    -- independent subsets of a matroid
  * "independentSets(Matroid,List)" -- see independentSets(Matroid,ZZ),
    -- independent subsets of a matroid
  * "independentSets(Matroid,Set)" -- see independentSets(Matroid,ZZ),
    -- independent subsets of a matroid
  * independentSets(Matroid,ZZ), --
    independent subsets of a matroid
  * "indicesOf(Matroid,List)" -- see indicesOf, -- indices of
    a sublist
  * "is3Connected(Matroid)" -- see is3Connected, -- whether
    a matroid is 3-connected
  * "isBinary(Matroid)" -- see isBinary, -- whether a matroid
    is representable over F_2
  * isConnected(Matroid) -- whether a matroid
    is connected
  * "isDependent(Matroid,List)" -- see isDependent, --
    whether a subset is dependent
  * "isDependent(Matroid,Set)" -- see isDependent, --
    whether a subset is dependent
  * "isElementaryQuotient(Matroid,Matroid)" -- see isElementaryQuotient,
    -- whether a matroid is an elementary quotient of
    another matroid
  * "isLinearSubclass(Matroid,List)" -- see isLinearSubclass,
    -- whether a list of hyperplanes of a matroid is a linear
    subclass
  * "isModularCut(Matroid,List)" -- see isModularCut, --
    whether a list of flats of a matroid is a modular cut
  * isomorphism(Matroid,Matroid), --
    computes an isomorphism between isomorphic matroids
  * "isPositivelyOrientable(Matroid)" -- see isPositivelyOrientable,
    -- whether a matroid is positively orientable
  * "isPositivelyOriented(Matroid)" -- see isPositivelyOriented,
    -- whether a matroid is positively oriented
  * "isQuotient(Matroid,Matroid)" -- see isQuotient, --
    whether a matroid is a quotient of another matroid
  * isSimple(Matroid) -- whether a matroid is
    simple
  * isWellDefined(Matroid) -- whether the
    input is a well-defined matroid
  * "latticeOfFlats(Matroid)" -- see latticeOfFlats, --
    lattice of flats of a matroid
  * "linearSubclass(Matroid,List)" -- see linearSubclass,
    -- associated to an elementary quotient or modular cut
  * "linearSubclass(Matroid,Matroid)" -- see linearSubclass,
    -- associated to an elementary quotient or modular cut
  * "loops(Matroid)" -- see loops, -- loops of matroid
  * Matroid + Matroid -- union of matroids
  * Matroid ++ Matroid -- direct sum of matroids
  * Matroid == Matroid -- whether two matroids are
    equal
  * Matroid _ List -- elements of matroid
  * "Matroid _ Set" -- see Matroid _ List, -- elements
    of matroid
  * "Matroid _ ZZ" -- see Matroid _ List, -- elements
    of matroid
  * "Matroid _*" -- see Matroid _ List, -- elements of
    matroid
  * "maxWeightBasis(Matroid,List)" -- see maxWeightBasis,
    -- maximum weight basis using greedy algorithm
  * "modularCut(Matroid,List)" -- see modularCut, --
    associated to an elementary quotient or linear subclass
  * "modularCut(Matroid,Matroid)" -- see modularCut, --
    associated to an elementary quotient or linear subclass
  * "nonbases(Matroid)" -- see nonbases, -- nonbases of matroid
  * "positiveOrientation(Matroid)" -- see positiveOrientation,
    -- a positive orientation of a matroid
  * "quickIsomorphismTest(Matroid,Matroid)" -- see quickIsomorphismTest,
    -- quick checks for isomorphism between matroids
  * rank(Matroid) -- rank of a matroid
  * "rank(Matroid,List)" -- see rank(Matroid,Set),
    -- rank of a subset of a matroid
  * rank(Matroid,Set) -- rank of a subset of a
    matroid
  * "Matroid | List" -- see restriction, -- restriction to
    subset of matroid
  * "Matroid | Set" -- see restriction, -- restriction to
    subset of matroid
  * "saveMatroid(Matroid)" -- see saveMatroid, -- save
    matroid to file
  * "saveMatroid(Matroid,String)" -- see saveMatroid, --
    save matroid to file
  * "searchRepresentation(Matroid,GaloisField)" -- see
    searchRepresentation, -- search for a representation
    of a matroid over a finite field
  * "toSageMatroid(Matroid)" -- see toSageMatroid, -- Sage
    format for matroid
  * "truncate(Matroid)" -- see truncate(Set,Matroid),
    -- the truncation of a matroid with respect to
    a flat
  * truncate(Set,Matroid) -- the truncation
    of a matroid with respect to a flat
  * truncate(ZZ,Matroid) -- the truncation
    of a matroid with respect to a flat
  * "tutteEvaluate(Matroid,Thing,Thing)" -- see tutteEvaluate,
    -- evaluate Tutte polynomial
  * tuttePolynomial(Matroid) -- Tutte
    polynomial of a matroid
  * "tuttePolynomial(Matroid,Ring)" -- see tuttePolynomial(Matroid),
    -- Tutte polynomial of a matroid

For the programmer
==================

The object Matroid, is a type (Macaulay2Doc), with
ancestor classes HashTable (Macaulay2Doc), < Thing (Macaulay2Doc).

matroid -- constructs a matroid
*******************************

Synopsis
========

  * Usage:
        M = matroid(E, B)
        M = matroid(E, C, EntryMode => "circuits")
        M = matroid(E, N, r)
        M = matroid(B)
        M = matroid(A)
        M = matroid(G)
        M = matroid(I)
  * Inputs:
      * E, a list (Macaulay2Doc), a ground set
      * n, an integer (Macaulay2Doc), the size of the ground set
      * B, a list (Macaulay2Doc), a list of bases
      * C, a list (Macaulay2Doc), a list of circuits
      * N, a list (Macaulay2Doc), a list of non-spanning circuits
      * r, an integer (Macaulay2Doc), the target rank
      * A, a matrix (Macaulay2Doc), whose column vectors form the
        ground set
      * G, a graph (Graphs), whose edges form the ground set
      * I, an ideal (Macaulay2Doc), a squarefree monomial ideal
        defining the independence complex
  * Optional inputs (Macaulay2Doc),:
      * EntryMode, => ...,
        default value "bases", select method of specifying matroid
      * Loops => ..., default value {}
      * ParallelEdges => ..., default value {}
  * Outputs:
      * M, a matroid,

Description
===========

The default representation of a matroid in this package is by its ground set
and list of bases.

+-----------------------------------------------+
|i1 : M = matroid({a,b,c,d}, {{a,b},{a,c}})     |
|                                               |
|o1 = a "matroid" of rank 2 on 4 elements       |
|                                               |
|o1 : Matroid                                   |
+-----------------------------------------------+
|i2 : peek M                                    |
|                                               |
|o2 = Matroid{bases => {set {0, 1}, set {0, 2}}}|
|             cache => CacheTable{...1...}      |
|             groundSet => set {0, 1, 2, 3}     |
|             rank => 2                         |
+-----------------------------------------------+

One can create a matroid by specifying its circuits, or
nonbases, instead, using the option EntryMode.
Regardless of the value of
EntryMode, the bases are automatically computed in the process of creation.

+-----------------------------------------------------------------------------+
|i3 : M = matroid({a,b,c,d},{}, EntryMode => "nonbases") -- defaults to       |
|                                                                             |
|o3 = a "matroid" of rank 4 on 4 elements                                     |
|                                                                             |
|o3 : Matroid                                                                 |
|-----------------------------------------------------------------------------|
|uniform matroid of full rank                                                 |
+-----------------------------------------------------------------------------+
|i4 : peek M                                                                  |
|                                                                             |
|o4 = Matroid{bases => {set {0, 1, 2, 3}}  }                                  |
|             cache => CacheTable{...2...}                                    |
|             groundSet => set {0, 1, 2, 3}                                   |
|             rank => 4                                                       |
+-----------------------------------------------------------------------------+
|i5 : N = matroid({a,b,c,d}, {{b,c}}, EntryMode => "circuits")                |
|                                                                             |
|o5 = a "matroid" of rank 3 on 4 elements                                     |
|                                                                             |
|o5 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i6 : peek N                                                                  |
|                                                                             |
|o6 = Matroid{bases => {set {0, 2, 3}, set {0, 1, 3}}}                        |
|             cache => CacheTable{...3...}                                    |
|             groundSet => set {0, 1, 2, 3}                                   |
|             rank => 3                                                       |
+-----------------------------------------------------------------------------+

If no ground set is provided, the ground set is taken to be the (sorted) union
of the bases/nonbases/circuits.

+-----------------------------------------------+
|i7 : M = matroid {{a,b},{a,c}}                 |
|                                               |
|o7 = a "matroid" of rank 2 on 3 elements       |
|                                               |
|o7 : Matroid                                   |
+-----------------------------------------------+
|i8 : peek M                                    |
|                                               |
|o8 = Matroid{bases => {set {0, 1}, set {0, 2}}}|
|             cache => CacheTable{...1...}      |
|             groundSet => set {0, 1, 2}        |
|             rank => 2                         |
+-----------------------------------------------+

If an integer n is the first argument, the ground set is taken to be {0, ...,
n-1}.

The non-spanning circuits, together with the target rank, may also be
specified.

+-----------------------------------------------------------------------------+
|i9 : matroid(toList(0..<8), {{0,1,2,3},{2,3,4,5},{0,1,6,7},{4,5,6,7}}, 4) == |
|                                                                             |
|o9 = true                                                                    |
|-----------------------------------------------------------------------------|
|swirl 4                                                                      |
+-----------------------------------------------------------------------------+

If a matrix is provided, then the realizable matroid on the columns of the
matrix is returned. The ground set consists of columns of the matrix, and
independence is determined by the method rank (Macaulay2Doc), (which
allows flexibility over general rings understood by M2).

+-----------------------------------------------------------------------------+
|i10 : M = matroid random(ZZ^3, ZZ^5)                                         |
|                                                                             |
|o10 = a "matroid" of rank 3 on 5 elements                                    |
|                                                                             |
|o10 : Matroid                                                                |
+-----------------------------------------------------------------------------+
|i11 : peek M                                                                 |
|                                                                             |
|o11 = Matroid{bases => {set {0, 1, 2}, set {0, 1, 3}, set {0, 2, 3}, set {1, |
|              cache => CacheTable{...3...}                                   |
|              groundSet => set {0, 1, 2, 3, 4}                               |
|              rank => 3                                                      |
|-----------------------------------------------------------------------------|
|2, 3}, set {4, 0, 1}, set {4, 0, 2}, set {4, 1, 2}, set {4, 0, 3}, set {4, 1,|
|-----------------------------------------------------------------------------|
|3}, set {4, 2, 3}}}                                                          |
+-----------------------------------------------------------------------------+

If a graph is provided, then the graphic matroid is returned. The ground set
consists of edges in the graph, and circuits are precisely the (minimal) cycles
in the graph.

+------------------------------------------------------------+
|i12 : M = matroid completeGraph 3                           |
|                                                            |
|o12 = a "matroid" of rank 2 on 3 elements                   |
|                                                            |
|o12 : Matroid                                               |
+------------------------------------------------------------+
|i13 : peek M                                                |
|                                                            |
|o13 = Matroid{bases => {set {1, 2}, set {0, 2}, set {0, 1}}}|
|              cache => CacheTable{...6...}                  |
|              groundSet => set {0, 1, 2}                    |
|              rank => 2                                     |
+------------------------------------------------------------+

One can use the optional arguments Loops and ParallelEdges to specify loops and
parallel edges for the graph, respectively (as the Graphs,
package does not currently provide functionality for loops or parallel edges).
These options are intended only for use with graphic matroids. ParallelEdges
should be given as a list of edges (which are two-element sets of the form
set$\{i,j\}$ where i, j are vertices in G), and Loops should be given as a list
of vertices where the loops are based.

+-----------------------------------------------------------------------------+
|i14 : M = matroid(completeGraph 3, ParallelEdges =>                          |
|                                                                             |
|o14 = a "matroid" of rank 2 on 8 elements                                    |
|                                                                             |
|o14 : Matroid                                                                |
|-----------------------------------------------------------------------------|
|{set{0,1},set{0,1},set{1,2}}, Loops => {0,2})                                |
+-----------------------------------------------------------------------------+
|i15 : peek M                                                                 |
|                                                                             |
|o15 = Matroid{bases => {set {4, 5}, set {5, 3}, set {5, 1}, set {0, 5}, set  |
|              cache => CacheTable{...5...}                                   |
|              groundSet => set {0, 1, 2, 3, 4, 5, 6, 7}                      |
|              rank => 2                                                      |
|-----------------------------------------------------------------------------|
|{4, 2}, set {4, 1}, set {2, 3}, set {1, 3}, set {1, 2}, set {0, 2}, set {0,  |
|-----------------------------------------------------------------------------|
|1}}}                                                                         |
+-----------------------------------------------------------------------------+
|i16 : circuits M                                                             |
|                                                                             |
|o16 = {set {0, 1, 2}, set {1, 2, 3}, set {0, 3}, set {4, 1, 2}, set {4, 3},  |
|      -----------------------------------------------------------------------|
|      set {4, 0}, set {0, 5, 1}, set {5, 1, 3}, set {4, 5, 1}, set {5, 2},   |
|      -----------------------------------------------------------------------|
|      set {6}, set {7}}                                                      |
|                                                                             |
|o16 : List                                                                   |
+-----------------------------------------------------------------------------+

If a squarefree monomial ideal is provided, corresponding to a simplicial
complex $\Delta$ via the Stanley-Reisner correspondence, then the matroid with
independence complex, $\Delta$ is
returned. The ground set consists of the variables in the ring of the ideal.

+-----------------------------------------------------------------------------+
|i17 : R = QQ[x_0..x_4]                                                       |
|                                                                             |
|o17 = R                                                                      |
|                                                                             |
|o17 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i18 : I = monomialIdeal (x_0*x_1*x_3,x_1*x_2*x_4,x_0*x_2*x_3*x_4)            |
|                                                                             |
|o18 = monomialIdeal (x x x , x x x , x x x x )                               |
|                      0 1 3   1 2 4   0 2 3 4                                |
|                                                                             |
|o18 : MonomialIdeal of R                                                     |
+-----------------------------------------------------------------------------+
|i19 : M = matroid I                                                          |
|                                                                             |
|o19 = a "matroid" of rank 3 on 5 elements                                    |
|                                                                             |
|o19 : Matroid                                                                |
+-----------------------------------------------------------------------------+
|i20 : peek M                                                                 |
|                                                                             |
|o20 = Matroid{bases => {set {4, 2, 3}, set {4, 1, 3}, set {4, 0, 3}, set {4, |
|              cache => CacheTable{...2...}                                   |
|              groundSet => set {0, 1, 2, 3, 4}                               |
|              rank => 3                                                      |
|-----------------------------------------------------------------------------|
|0, 2}, set {4, 0, 1}, set {1, 2, 3}, set {0, 2, 3}, set {0, 1, 2}}}          |
+-----------------------------------------------------------------------------+

Caveat
======

This function does not check if (E,B) defines a matroid - see
isWellDefined.

The bases are not stored as sets of elements of M - rather, the indices (with
respect to the ground set) are stored instead. For more, see groundSet.

See also
========

  * isWellDefined(Matroid) -- whether the
    input is a well-defined matroid
  * bases -- bases of matroid
  * indicesOf -- indices of a sublist
  * specificMatroid -- creates built-in matroid

Ways to use matroid:
====================

  * "matroid(Graph)"
  * "matroid(Ideal)"
  * "matroid(List)"
  * "matroid(List,List)"
  * "matroid(List,List,ZZ)"
  * "matroid(List,MonomialIdeal)"
  * "matroid(Matrix)"
  * "matroid(ZZ,List)"

For the programmer
==================

The object matroid, is a method function with options (Macaulay2Doc).

Matroid + Matroid -- union of matroids
**************************************

Synopsis
========

  * Operator: + (Macaulay2Doc),
  * Usage:
        M + N
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a matroid, the sum, or union, of M and N

Description
===========

The union of M and N has ground set equal to the union of those of M and N, and
independent sets given by pairwise unions of independent sets of M and N.

+-----------------------------------------------------------------------------+
|i1 : M = uniformMatroid(2,4) + uniformMatroid(1,4)                           |
|                                                                             |
|o1 = a "matroid" of rank 3 on 4 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : peek M                                                                  |
|                                                                             |
|o2 = Matroid{bases => {set {0, 1, 2}, set {0, 1, 3}, set {0, 2, 3}, set {1,  |
|             cache => CacheTable{...1...}                                    |
|             groundSet => set {0, 1, 2, 3}                                   |
|             rank => 3                                                       |
|-----------------------------------------------------------------------------|
|2, 3}}}                                                                      |
+-----------------------------------------------------------------------------+
|i3 : M == uniformMatroid(3, 4)                                               |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+

When the ground sets of M and N are disjoint, this is the direct sum,
of M and N. Beware of order when using ==,
though:

+----------------------------------------------------------+
|i4 : M0 = uniformMatroid(2, 4) + matroid completeGraph 4  |
|                                                          |
|o4 = a "matroid" of rank 5 on 10 elements                 |
|                                                          |
|o4 : Matroid                                              |
+----------------------------------------------------------+
|i5 : M0 == uniformMatroid(2, 4) ++ matroid completeGraph 4|
|                                                          |
|o5 = true                                                 |
+----------------------------------------------------------+
|i6 : M1 = matroid completeGraph 4 ++ uniformMatroid(2, 4) |
|                                                          |
|o6 = a "matroid" of rank 5 on 10 elements                 |
|                                                          |
|o6 : Matroid                                              |
+----------------------------------------------------------+
|i7 : M0 == M1                                             |
|                                                          |
|o7 = false                                                |
+----------------------------------------------------------+
|i8 : areIsomorphic(M0, M1)                                |
|                                                          |
|o8 = true                                                 |
+----------------------------------------------------------+

Matroid union is an important operation in combinatorial optimization, and via
duality, is related to the problem of matroid intersection.

With the operation of union, one can work with transversal matroids and
gammoids. A matroid is transversal iff it is a union of rank 1 matroids; strict
gammoids are precisely the duals of transversal matroids, and gammoids are
restrictions of strict gammoids. In general the problem of determining if a
given matroid is a gammoid is difficult.

A union of two uniform matroids is again uniform, but a union of two graphic
matroids need not be binary:

+----------------------------------------------------------------------+
|i9 : M0 = matroid({a,b,c,d}, {{a},{b},{c}})                           |
|                                                                      |
|o9 = a "matroid" of rank 1 on 4 elements                              |
|                                                                      |
|o9 : Matroid                                                          |
+----------------------------------------------------------------------+
|i10 : M1 = matroid({a,b,c,d}, {{b},{c},{d}})                          |
|                                                                      |
|o10 = a "matroid" of rank 1 on 4 elements                             |
|                                                                      |
|o10 : Matroid                                                         |
+----------------------------------------------------------------------+
|i11 : M0 + M1 == uniformMatroid(2,4)                                  |
|                                                                      |
|o11 = true                                                            |
+----------------------------------------------------------------------+
|i12 : F7 = specificMatroid "fano"                                     |
|                                                                      |
|o12 = a "matroid" of rank 3 on 7 elements                             |
|                                                                      |
|o12 : Matroid                                                         |
+----------------------------------------------------------------------+
|i13 : NF = specificMatroid "nonfano"                                  |
|                                                                      |
|o13 = a "matroid" of rank 3 on 7 elements                             |
|                                                                      |
|o13 : Matroid                                                         |
+----------------------------------------------------------------------+
|i14 : all({F7 + NF, F7 + F7, NF + NF}, M -> M == uniformMatroid(6, 7))|
|                                                                      |
|o14 = true                                                            |
+----------------------------------------------------------------------+

One potential caveat: the ground set of M must not have repeated elements. If
this is not the case, the user MUST rename elements of M so that they become
distinct. Of course, this needs to be done for both M and N, and one should
also keep track of which elements of M and N are meant to be the same after the
renaming (otherwise the entire point of taking unions, as opposed to direct
sums, is lost).

In the example below, M contains the vector {1,1} twice. Macaulay2 has no way
of distinguishing the repeated vectors, so the second occurrence of {1,1} is
relabelled to the symbol d (of course, if the symbol d also happened to be an
element of N, then a different label would have to be chosen).

+---------------------------------------------------------------------+
|i15 : A = matrix{{0,1,1,1},{0,0,1,1}}                                |
|                                                                     |
|o15 = | 0 1 1 1 |                                                    |
|      | 0 0 1 1 |                                                    |
|                                                                     |
|               2       4                                             |
|o15 : Matrix ZZ  <-- ZZ                                              |
+---------------------------------------------------------------------+
|i16 : M = matroid A                                                  |
|                                                                     |
|o16 = a "matroid" of rank 2 on 4 elements                            |
|                                                                     |
|o16 : Matroid                                                        |
+---------------------------------------------------------------------+
|i17 : M_*                                                            |
|                                                                     |
|o17 = {0, | 1 |, | 1 |, | 1 |}                                       |
|          | 0 |  | 1 |  | 1 |                                        |
|                                                                     |
|o17 : List                                                           |
+---------------------------------------------------------------------+
|i18 : unique M_*                                                     |
|                                                                     |
|o18 = {0, | 1 |, | 1 |}                                              |
|          | 0 |  | 1 |                                               |
|                                                                     |
|o18 : List                                                           |
+---------------------------------------------------------------------+
|i19 : M0 = matroid(M_{0,1,2} | {d}, bases M)                         |
|                                                                     |
|o19 = a "matroid" of rank 2 on 4 elements                            |
|                                                                     |
|o19 : Matroid                                                        |
+---------------------------------------------------------------------+
|i20 : M == M0                                                        |
|                                                                     |
|o20 = true                                                           |
+---------------------------------------------------------------------+
|i21 : B = matrix{{0,1,2},{0,1,2}}                                    |
|                                                                     |
|o21 = | 0 1 2 |                                                      |
|      | 0 1 2 |                                                      |
|                                                                     |
|               2       3                                             |
|o21 : Matrix ZZ  <-- ZZ                                              |
+---------------------------------------------------------------------+
|i22 : N = matroid B                                                  |
|                                                                     |
|o22 = a "matroid" of rank 1 on 3 elements                            |
|                                                                     |
|o22 : Matroid                                                        |
+---------------------------------------------------------------------+
|i23 : U = M0 + N                                                     |
|                                                                     |
|o23 = a "matroid" of rank 3 on 5 elements                            |
|                                                                     |
|o23 : Matroid                                                        |
+---------------------------------------------------------------------+
|i24 : peek U                                                         |
|                                                                     |
|o24 = Matroid{bases => {set {4, 1, 2}, set {1, 2, 3}, set {4, 1, 3}}}|
|              cache => CacheTable{...1...}                           |
|              groundSet => set {0, 1, 2, 3, 4}                       |
|              rank => 3                                              |
+---------------------------------------------------------------------+
|i25 : U_*                                                            |
|                                                                     |
|o25 = {0, | 1 |, | 1 |, d, | 2 |}                                    |
|          | 0 |  | 1 |     | 2 |                                     |
|                                                                     |
|o25 : List                                                           |
+---------------------------------------------------------------------+

See also
========

  * Matroid ++ Matroid -- direct sum of matroids
  * relabel -- relabel a matroid

Ways to use this method:
========================

  * Matroid + Matroid -- union of matroids

Matroid ++ Matroid -- direct sum of matroids
********************************************

Synopsis
========

  * Operator: ++ (Macaulay2Doc),
  * Usage:
        M ++ N
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a matroid, the direct sum of M and N

Description
===========

The direct sum of M and N is a matroid with ground set equal to the disjoint
union of the ground sets of M and N, and bases equal to the union of bases of M
and N.

+-----------------------------------------------------------------------------+
|i1 : S = uniformMatroid(2,3) ++ uniformMatroid(1,3)                          |
|                                                                             |
|o1 = a "matroid" of rank 3 on 6 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : peek S                                                                  |
|                                                                             |
|o2 = Matroid{bases => {set {0, 1, 3}, set {4, 0, 1}, set {0, 5, 1}, set {0,  |
|             cache => CacheTable{...1...}                                    |
|             groundSet => set {0, 1, 2, 3, 4, 5}                             |
|             rank => 3                                                       |
|-----------------------------------------------------------------------------|
|2, 3}, set {4, 0, 2}, set {0, 5, 2}, set {1, 2, 3}, set {4, 1, 2}, set {5, 1,|
|-----------------------------------------------------------------------------|
|2}}}                                                                         |
+-----------------------------------------------------------------------------+
|i3 : S_*                                                                     |
|                                                                             |
|o3 = {(0, 0), (1, 0), (2, 0), (0, 1), (1, 1), (2, 1)}                        |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : (S ++ uniformMatroid(1, 3))_*                                           |
|                                                                             |
|o4 = {((0, 0), 0), ((1, 0), 0), ((2, 0), 0), ((0, 1), 0), ((1, 1), 0), ((2,  |
|     ------------------------------------------------------------------------|
|     1), 0), (0, 1), (1, 1), (2, 1)}                                         |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

The elements of the ground set of the direct sum will receive placeholders to
ensure disjointness (as evidenced by the elements of S being ordered pairs
above). As this method is binary, repeated applications of this function will
result in nested placeholders. Since the bases are stored as indices, the bases
of M will not change, but those of N will be shifted up by the size of the
ground set of M.

See also
========

  * Matroid + Matroid -- union of matroids
  * components(Matroid) -- connected components
    of matroid

Ways to use this method:
========================

  * Matroid ++ Matroid -- direct sum of matroids

Matroid == Matroid -- whether two matroids are equal
****************************************************

Synopsis
========

  * Operator: == (Macaulay2Doc),
  * Usage:
        M == N
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the two matroids
        are equal

Description
===========

Two matroids are considered equal if they have the same set of (indexed) bases
and same size grounds sets (in particular, the ground sets need not be
identical). This happens iff the identity permutation is an isomorphism.

The strong comparison operator === should not be used, as bases (and ground
sets) are internally stored as lists rather than sets, so the same matroid with
a different ordering on the list of bases (or ground set) will be treated as
different under ===. (One might try to sort the list of bases, but this is
potentially time-consuming, as the list of bases can grow rapidly with the size
of the ground set.)

+----------------------------------------------------------------------+
|i1 : M = matroid completeGraph 3                                      |
|                                                                      |
|o1 = a "matroid" of rank 2 on 3 elements                              |
|                                                                      |
|o1 : Matroid                                                          |
+----------------------------------------------------------------------+
|i2 : peek M                                                           |
|                                                                      |
|o2 = Matroid{bases => {set {1, 2}, set {0, 2}, set {0, 1}}}           |
|             cache => CacheTable{...6...}                             |
|             groundSet => set {0, 1, 2}                               |
|             rank => 2                                                |
+----------------------------------------------------------------------+
|i3 : N = uniformMatroid(2, 3)                                         |
|                                                                      |
|o3 = a "matroid" of rank 2 on 3 elements                              |
|                                                                      |
|o3 : Matroid                                                          |
+----------------------------------------------------------------------+
|i4 : peek N                                                           |
|                                                                      |
|o4 = Matroid{bases => {set {0, 1}, set {0, 2}, set {1, 2}}}           |
|             cache => CacheTable{...1...}                             |
|             groundSet => set {0, 1, 2}                               |
|             rank => 2                                                |
+----------------------------------------------------------------------+
|i5 : M == N                                                           |
|                                                                      |
|o5 = true                                                             |
+----------------------------------------------------------------------+
|i6 : M === N                                                          |
|                                                                      |
|o6 = false                                                            |
+----------------------------------------------------------------------+
|i7 : AG32 = specificMatroid "AG32" -- identically self-dual           |
|                                                                      |
|o7 = a "matroid" of rank 4 on 8 elements                              |
|                                                                      |
|o7 : Matroid                                                          |
+----------------------------------------------------------------------+
|i8 : AG32 == dual AG32                                                |
|                                                                      |
|o8 = true                                                             |
+----------------------------------------------------------------------+
|i9 : AG32 === dual AG32                                               |
|                                                                      |
|o9 = false                                                            |
+----------------------------------------------------------------------+
|i10 : V = specificMatroid "vamos" -- self-dual, but not identically so|
|                                                                      |
|o10 = a "matroid" of rank 4 on 8 elements                             |
|                                                                      |
|o10 : Matroid                                                         |
+----------------------------------------------------------------------+
|i11 : V == dual V                                                     |
|                                                                      |
|o11 = false                                                           |
+----------------------------------------------------------------------+
|i12 : areIsomorphic(V, dual V)                                        |
|                                                                      |
|o12 = true                                                            |
+----------------------------------------------------------------------+

See also
========

  * isomorphism(Matroid,Matroid), --
    computes an isomorphism between isomorphic matroids

Ways to use this method:
========================

  * Matroid == Matroid -- whether two matroids are
    equal

Matroid _ List -- elements of matroid
*************************************

Synopsis
========

  * Operator: _ (Macaulay2Doc),
  * Usage:
        M_S
        M_i
        M_*
  * Inputs:
      * M, a matroid,
      * S, a list (Macaulay2Doc), or set (Macaulay2Doc),
        of indices in M.groundSet
  * Outputs:
      * a list (Macaulay2Doc), of elements of M

Description
===========

Converts a list or set of indices to the list of elements of the matroid with
those indices. The inverse of this function is indicesOf.

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : M_2                                 |
|                                         |
|o2 = c                                   |
|                                         |
|o2 : Symbol                              |
+-----------------------------------------+
|i3 : M_{0,2,3}                           |
|                                         |
|o3 = {a, c, d}                           |
|                                         |
|o3 : List                                |
+-----------------------------------------+
|i4 : B = (bases M)#0                     |
|                                         |
|o4 = set {0, 1}                          |
|                                         |
|o4 : Set                                 |
+-----------------------------------------+
|i5 : M_B                                 |
|                                         |
|o5 = set {a, b}                          |
|                                         |
|o5 : Set                                 |
+-----------------------------------------+

If used with the operator _* (Macaulay2Doc), then the list of all
elements in M is returned. This is useful in conjunction with apply (Macaulay2Doc),
to iterate over all elements in a matroid.

+------------------------------------------------+
|i6 : F7 = specificMatroid "fano"                |
|                                                |
|o6 = a "matroid" of rank 3 on 7 elements        |
|                                                |
|o6 : Matroid                                    |
+------------------------------------------------+
|i7 : M4 = matroid completeGraph 4               |
|                                                |
|o7 = a "matroid" of rank 3 on 6 elements        |
|                                                |
|o7 : Matroid                                    |
+------------------------------------------------+
|i8 : all(F7_*, x -> areIsomorphic(F7 \ {x}, M4))|
|                                                |
|o8 = true                                       |
+------------------------------------------------+

Caveat
======

There are important differences between this method and groundSet,:
see that page for more details.

See also
========

  * groundSet -- (internal) ground set
  * indicesOf -- indices of a sublist

Ways to use this method:
========================

  * Matroid _ List -- elements of matroid
  * "Matroid _ Set"
  * "Matroid _ ZZ"

matroid(...,EntryMode=>...) -- select method of specifying matroid
******************************************************************

Synopsis
========

  * Usage:
        matroid(..., EntryMode => "bases")
        matroid(..., EntryMode => "nonbases")
        matroid(..., EntryMode => "circuits")

Description
===========

A matroid is determined by its set of bases, i.e. maximal (with respect to
inclusion) independent sets, which are all of the same size (namely, the rank
of the matroid). However, many interesting matroids have relatively few
dependencies, and thus it may be easier to specify the matroid by its
nonbases, i.e. dependent subsets of the ground set, with size equal
to the rank of the matroid.

Similarly, a matroid can be specified by its circuits, i.e.
minimal dependent sets. This is done e.g. when creating a graphical matroid.

If EntryMode is not specified, then the default value is assumed, which is
EntryMode => "bases".

+-----------------------------------------------------------------------------+
|i1 : M = matroid({{0,1,2}, {3,4,5}}, EntryMode => "circuits") -- bowtie graph|
|                                                                             |
|o1 = a "matroid" of rank 4 on 6 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
|-----------------------------------------------------------------------------|
|/ 2 disjoint K3's                                                            |
+-----------------------------------------------------------------------------+
|i2 : bases M                                                                 |
|                                                                             |
|o2 = {set {1, 2, 4, 5}, set {0, 2, 4, 5}, set {0, 1, 4, 5}, set {1, 2, 3, 5},|
|     ------------------------------------------------------------------------|
|     set {0, 2, 3, 5}, set {0, 1, 3, 5}, set {1, 2, 3, 4}, set {0, 2, 3, 4}, |
|     ------------------------------------------------------------------------|
|     set {0, 1, 3, 4}}                                                       |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : F7 = matroid({{0,1,6},{0,2,4},{0,3,5},{1,2,5},{1,3,4},{2,3,6},{4,5,6}}, |
|                                                                             |
|o3 = a "matroid" of rank 3 on 7 elements                                     |
|                                                                             |
|o3 : Matroid                                                                 |
|-----------------------------------------------------------------------------|
|EntryMode => "nonbases")                                                     |
+-----------------------------------------------------------------------------+
|i4 : F7 == specificMatroid "fano"                                            |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: bases
  * Function: matroid, -- constructs a matroid
  * Option key: EntryMode (Graphs), -- Constructs a simple graph

See also
========

  * matroid -- constructs a matroid
  * nonbases -- nonbases of matroid
  * circuits -- circuits of matroid

Functions with optional argument named EntryMode:
=================================================

  * digraph(...,EntryMode=>...) (missing documentation)
  * elementaryQuotient(...,EntryMode=>...)
    -- use a modular
    cut or linear subclass
  * extension(...,EntryMode=>...)
    -- use a modular cut or
    linear subclass
  * "graph(...,EntryMode=>...)" -- see graph (Graphs), --
    Constructs a simple graph
  * matroid(...,EntryMode=>...)
    -- select method of
    specifying matroid

maxWeightBasis -- maximum weight basis using greedy algorithm
*************************************************************

Synopsis
========

  * Usage:
        maxWeightBasis(M, w)
  * Inputs:
      * M, a matroid,
      * w, a list (Macaulay2Doc), a weight function
  * Outputs:
      * a set (Macaulay2Doc), a maximum-weight basis obtained by the
        greedy algorithm

Description
===========

For a matroid M on ground set E, a weight function on M is a function $w : E ->
\mathbb{R}$, extended to all subsets of E by setting $w(X) := \sum_{x\in X}
w(x)$. The greedy algorithm for finding a maximum-weight independent subset of
E starts with the empty set, and proceeds by successively adding elements of E
of maximum weight, which together with the elements already added, form an
independent set.

In this method, a weight function is specified by its list of values on E. Thus
if $E = \{e_1, ..., e_n\}$, then w is represented as the list $\{w(e_1), ...,
w(e_n)\}$.

Matroids can be characterized via the greedy algorithm as follows: a set
$\mathcal{I}$ of subsets of E is the set of independent sets of a matroid on E
iff $\mathcal{I}$ is nonempty, downward closed, and for every weight function
$w : E -> \mathbb{R}$, the greedy algorithm returns a maximal member of
$\mathcal{I}$ of maximum weight.

+-----------------------------------------------------------------------------+
|i1 : M = matroid completeGraph 4                                             |
|                                                                             |
|o1 = a "matroid" of rank 3 on 6 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : bases M                                                                 |
|                                                                             |
|o2 = {set {4, 5, 2}, set {4, 5, 1}, set {4, 0, 5}, set {5, 2, 3}, set {5, 1, |
|     ------------------------------------------------------------------------|
|     3}, set {0, 5, 3}, set {0, 5, 2}, set {0, 5, 1}, set {4, 2, 3}, set {4, |
|     ------------------------------------------------------------------------|
|     1, 3}, set {4, 0, 3}, set {4, 1, 2}, set {4, 0, 1}, set {1, 2, 3}, set  |
|     ------------------------------------------------------------------------|
|     {0, 2, 3}, set {0, 1, 2}}                                               |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : w1 = apply(M_*, e -> (toList e)#1)                                      |
|                                                                             |
|o3 = {1, 2, 3, 2, 3, 3}                                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : maxWeightBasis(M, w1)                                                   |
|                                                                             |
|o4 = set {4, 5, 2}                                                           |
|                                                                             |
|o4 : Set                                                                     |
+-----------------------------------------------------------------------------+
|i5 : w2 = rsort w1                                                           |
|                                                                             |
|o5 = {3, 3, 3, 2, 2, 1}                                                      |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : maxWeightBasis(M, w2)                                                   |
|                                                                             |
|o6 = set {0, 1, 2}                                                           |
|                                                                             |
|o6 : Set                                                                     |
+-----------------------------------------------------------------------------+

Ways to use maxWeightBasis:
===========================

  * "maxWeightBasis(Matroid,List)"

For the programmer
==================

The object maxWeightBasis, is a method function (Macaulay2Doc).

minor -- minor of matroid
*************************

Synopsis
========

  * Usage:
        minor(M, X, Y)
  * Inputs:
      * M, a matroid,
      * X, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M
      * Y, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M, disjoint from X
  * Outputs:
      * a matroid, the minor M / X \ Y

Description
===========

The minor M / X \ Y of M is given by contracting X and deleting Y from M. The
resulting matroid is independent of the order in which deletion and contraction
is done. If X (or Y) is a set (of indices in M.groundSet), then X is identified
with the sublist of elements of M with indices in X: cf. groundSet,
for more on this package-wide convention.

+-----------------------------------------------------------+
|i1 : M = matroid random(ZZ^3,ZZ^6)                         |
|                                                           |
|o1 = a "matroid" of rank 3 on 6 elements                   |
|                                                           |
|o1 : Matroid                                               |
+-----------------------------------------------------------+
|i2 : M_*                                                   |
|                                                           |
|o2 = {| 8 |, | 7 |, | 3 |, | 8 |, | 8 |, | 3 |}            |
|      | 1 |  | 8 |  | 7 |  | 5 |  | 5 |  | 6 |             |
|      | 3 |  | 3 |  | 8 |  | 7 |  | 2 |  | 3 |             |
|                                                           |
|o2 : List                                                  |
+-----------------------------------------------------------+
|i3 : M.groundSet                                           |
|                                                           |
|o3 = set {0, 1, 2, 3, 4, 5}                                |
|                                                           |
|o3 : Set                                                   |
+-----------------------------------------------------------+
|i4 : (X, Y) = (set{3}, set{0,1})                           |
|                                                           |
|o4 = (set {3}, set {0, 1})                                 |
|                                                           |
|o4 : Sequence                                              |
+-----------------------------------------------------------+
|i5 : (X1, Y1) = (M_X, M_Y)/toList                          |
|                                                           |
|o5 = ({| 8 |}, {| 7 |, | 8 |})                             |
|       | 5 |    | 8 |  | 1 |                               |
|       | 7 |    | 3 |  | 3 |                               |
|                                                           |
|o5 : Sequence                                              |
+-----------------------------------------------------------+
|i6 : N = minor(M, X, Y)                                    |
|                                                           |
|o6 = a "matroid" of rank 2 on 3 elements                   |
|                                                           |
|o6 : Matroid                                               |
+-----------------------------------------------------------+
|i7 : peek N                                                |
|                                                           |
|o7 = Matroid{bases => {set {0, 1}, set {0, 2}, set {1, 2}}}|
|             cache => CacheTable{...1...}                  |
|             groundSet => set {0, 1, 2}                    |
|             rank => 2                                     |
+-----------------------------------------------------------+
|i8 : N == minor(M, X1, Y1)                                 |
|                                                           |
|o8 = true                                                  |
+-----------------------------------------------------------+

Note that there is potential ambiguity for the second argument - namely,
whether or not Y is treated with respect to the ground set of M or M / X (which
are different). This method assumes that the indices of Y (and X) are taken
with respect to the ground set of M.

If one already has the indices Y0 of Y in M / X (or the indices X0 of X in M \
Y), one can simply use the notation M /, X \,
Y0 (or (M \ Y) / X0). Thus this method serves purely as a
convenience, to save the user the (trivial) task of computing Y0 from Y.

If X and Y are not disjoint, then an error is thrown (thus one should
subtract (Macaulay2Doc), X from Y beforehand).

+-----------------------------------------------------------------------------+
|i9 : M5 = matroid completeGraph 5                                            |
|                                                                             |
|o9 = a "matroid" of rank 4 on 10 elements                                    |
|                                                                             |
|o9 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i10 : M5.groundSet                                                           |
|                                                                             |
|o10 = set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}                                     |
|                                                                             |
|o10 : Set                                                                    |
+-----------------------------------------------------------------------------+
|i11 : N = minor(M5, set{8}, set{3,4,9})                                      |
|                                                                             |
|o11 = a "matroid" of rank 3 on 6 elements                                    |
|                                                                             |
|o11 : Matroid                                                                |
+-----------------------------------------------------------------------------+
|i12 : areIsomorphic(N, matroid completeGraph 4)                              |
|                                                                             |
|o12 = true                                                                   |
+-----------------------------------------------------------------------------+
|i13 : N == (M5 \ set{3,4,9}) / set{6} -- after deleting 3,4 (and 9), index 8 |
|                                                                             |
|o13 = true                                                                   |
|-----------------------------------------------------------------------------|
|-> 6                                                                         |
+-----------------------------------------------------------------------------+
|i14 : N == M5 / set{8} \ set{3,4,8} -- after contracting 8, index 9 -> 8     |
|                                                                             |
|o14 = true                                                                   |
+-----------------------------------------------------------------------------+
|i15 : (try minor(M5, set{8}, set{3,4,8,9})) === null                         |
|                                                                             |
|o15 = true                                                                   |
+-----------------------------------------------------------------------------+
|i16 : minor(M5, set{8}, set{3,4,8,9} - set{8})                               |
|                                                                             |
|o16 = a "matroid" of rank 3 on 6 elements                                    |
|                                                                             |
|o16 : Matroid                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * deletion -- deletion of subset of matroid
  * contraction -- contraction of subset of matroid
  * hasMinor -- whether a matroid has a given minor

Ways to use minor:
==================

  * "minor(Matroid,List,List)"
  * "minor(Matroid,Set,Set)"

For the programmer
==================

The object minor, is a method function (Macaulay2Doc).

modularCut -- associated to an elementary quotient or linear subclass
*********************************************************************

Synopsis
========

  * Usage:
        modularCut(M, N),
        modularCut(M, H)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
      * H, a list (Macaulay2Doc), a list of hyperplanes of the
        matroid forming a linear subclass
  * Optional inputs (Macaulay2Doc),:
      * CheckWellDefined,
        => ...,
        default value false, check whether the list is a linear subclass
  * Outputs:
      * a list (Macaulay2Doc), a list of flats of the matroid
        forming a modular cut

Description
===========

This function is provided by the package Matroids.

An elementary quotient M of a matroid N is completely determined by a modular
cut of flats of N.  Given such an elementary quotient, this function produces
the corresponding modular cut.  See isModularCut, for more
details about modular cuts.

+------------------------------------+
|i1 : N = matroid completeGraph 4;   |
+------------------------------------+
|i2 : F = set {0, 1, 3};             |
+------------------------------------+
|i3 : TFN = truncate(F, N);          |
+------------------------------------+
|i4 : isElementaryQuotient(TFN, N)   |
|                                    |
|o4 = true                           |
+------------------------------------+
|i5 : modularCut(TFN, N)             |
|                                    |
|o5 = {{0, 1, 3}, {0, 1, 2, 3, 4, 5}}|
|                                    |
|o5 : List                           |
+------------------------------------+

In turn, a modular cut K of the matroid M is completely determined by a
collection of hyperplanes of M called a linear subclass.  See
isLinearSubclass, for more details about linear subclasses.
Given a list H of hyperplanes of M forming a linear subclass, the corresponding
modular cut consists of all flats F of M such that every hyperplane containing
F belongs to H.

+-----------------------------------------------------------------------------+
|i6 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}         |
|                                                                             |
|o6 = | 1 0 0 1 1  |                                                          |
|     | 0 1 0 1 -1 |                                                          |
|     | 0 0 1 0 0  |                                                          |
|                                                                             |
|              3       5                                                      |
|o6 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i7 : M = matroid A                                                           |
|                                                                             |
|o7 = a "matroid" of rank 3 on 5 elements                                     |
|                                                                             |
|o7 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i8 : H = drop(hyperplanes M, 1)                                              |
|                                                                             |
|o8 = {set {4, 2}, set {2, 3}, set {1, 2}, set {0, 2}}                        |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : isLinearSubclass(M, H)                                                  |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+
|i10 : modularCut(M, H)                                                       |
|                                                                             |
|o10 = {set {2}, set {4, 2}, set {2, 3}, set {1, 2}, set {0, 2}, set {0, 1, 2,|
|      -----------------------------------------------------------------------|
|      3, 4}}                                                                 |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * elementaryQuotient -- associated to a modular
    cut or linear subclass
  * isElementaryQuotient -- whether a matroid is
    an elementary quotient of another matroid
  * isLinearSubclass -- whether a list of hyperplanes
    of a matroid is a linear subclass
  * isModularCut -- whether a list of flats of a matroid
    is a modular cut
  * linearSubclass -- associated to an elementary
    quotient or modular cut

Ways to use modularCut:
=======================

  * "modularCut(Matroid,List)"
  * "modularCut(Matroid,Matroid)"

For the programmer
==================

The object modularCut, is a method function with options (Macaulay2Doc).

modularCut(...,CheckWellDefined=>...) -- check whether the list is a linear subclass
************************************************************************************

Synopsis
========

  * Usage:
        modularCut(M, H, CheckWellDefined => true)
  * Inputs:
      * M, a matroid,
      * H, a list (Macaulay2Doc), a list of hyperplanes of the
        matroid forming a linear subclass
  * Outputs:
      * a list (Macaulay2Doc), a list of flats of the matroid
        forming a modular cut

Description
===========

This option is provided by the package Matroids.

When producing the modular cut of a matroid M corresponding to a list of
hyperplanes H, setting this option to true calls isLinearSubclass,
to check that the list H is in fact a linear subclass.

+-----------------------------------------------------------------------------+
|i1 : A = matrix {{1, 0, 0, 1, 1}, {0, 1, 0, 1, -1}, {0, 0, 1, 0, 0}}         |
|                                                                             |
|o1 = | 1 0 0 1 1  |                                                          |
|     | 0 1 0 1 -1 |                                                          |
|     | 0 0 1 0 0  |                                                          |
|                                                                             |
|              3       5                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i2 : M = matroid A                                                           |
|                                                                             |
|o2 = a "matroid" of rank 3 on 5 elements                                     |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : H = drop(hyperplanes M, 1)                                              |
|                                                                             |
|o3 = {set {4, 2}, set {2, 3}, set {1, 2}, set {0, 2}}                        |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : modularCut(M, H, CheckWellDefined => true)                              |
|                                                                             |
|o4 = {set {2}, set {4, 2}, set {2, 3}, set {1, 2}, set {0, 2}, set {0, 1, 2, |
|     ------------------------------------------------------------------------|
|     3, 4}}                                                                  |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: modularCut, -- associated to an elementary
    quotient or linear subclass
  * Option key: CheckWellDefined, -- an optional
    argument

See also
========

  * modularCut -- associated to an elementary quotient or
    linear subclass

Functions with optional argument named CheckWellDefined:
========================================================

  * "relaxation(...,CheckWellDefined=>...)" -- see CheckWellDefined,
    -- an optional argument
  * elementaryQuotient(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut or linear subclass
  * extension(...,CheckWellDefined=>...)
    -- check whether
    the list is a modular cut or linear subclass
  * linearSubclass(...,CheckWellDefined=>...)
    -- check
    whether the list is a modular cut
  * modularCut(...,CheckWellDefined=>...)
    -- check whether
    the list is a linear subclass

nonbases -- nonbases of matroid
*******************************

Synopsis
========

  * Usage:
        nonbases M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a list (Macaulay2Doc), of nonbases

Description
===========

In any matroid, all basis elements have the same cardinality r (which is the
rank of the matroid). The nonbases of a matroid are the subsets of the ground
set of cardinality r that are dependent.

Just as with bases, and circuits, nonbases are
stored via their indices (rather than the elements of the ground set
themselves).

+-----------------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})            |
|                                                     |
|o1 = a "matroid" of rank 2 on 4 elements             |
|                                                     |
|o1 : Matroid                                         |
+-----------------------------------------------------+
|i2 : nonbases M                                      |
|                                                     |
|o2 = {set {1, 2}, set {0, 3}, set {1, 3}, set {2, 3}}|
|                                                     |
|o2 : List                                            |
+-----------------------------------------------------+

See also
========

  * bases -- bases of matroid

Ways to use nonbases:
=====================

  * "nonbases(Matroid)"

For the programmer
==================

The object nonbases, is a method function (Macaulay2Doc).

parallelConnection -- parallel connection of two matroids
*********************************************************

Synopsis
========

  * Usage:
        parallelConnection(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a matroid, the parallel connection of M and N with
        basepoint 0

Description
===========

This function returns the parallel connection of two given matroids M and N
(cf. Oxley, Section 7.1). Parallel connection is dual to
seriesConnection,: namely, the parallel connection of M and N
is the dual of the series connection of M* and N*.

It is always assumed that the common basepoint of M and N is the first element
in the respective ground sets, i.e. the element with index 0. (To form a
parallel connection using a different basepoint, one can first relabel,
M and/or N.)

+-----------------------------------------------------------------------------+
|i1 : G = graph({{0,1},{1,2},{2,3},{3,4},{4,5},{5,6},{6,0},{0,2},{0,3},{0,4},{|
|                                                                             |
|o1 = Graph{0 => {1, 2, 3, 4, 6}   }                                          |
|           1 => {0, 2, 3}                                                    |
|           2 => {0, 1, 3}                                                    |
|           3 => {0, 1, 2, 4, 5, 6}                                           |
|           4 => {0, 3, 5}                                                    |
|           5 => {3, 4, 6}                                                    |
|           6 => {0, 3, 5}                                                    |
|                                                                             |
|o1 : Graph                                                                   |
|-----------------------------------------------------------------------------|
|1,3},{3,5},{3,6}})                                                           |
+-----------------------------------------------------------------------------+
|i2 : M = matroid G                                                           |
|                                                                             |
|o2 = a "matroid" of rank 6 on 13 elements                                    |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : parallelConnection(M, uniformMatroid(1,2))                              |
|                                                                             |
|o3 = a "matroid" of rank 6 on 14 elements                                    |
|                                                                             |
|o3 : Matroid                                                                 |
+-----------------------------------------------------------------------------+

See also
========

  * seriesConnection -- series connection of two
    matroids
  * sum2 -- 2-sum of matroids

Ways to use parallelConnection:
===============================

  * "parallelConnection(Matroid,Matroid)"

For the programmer
==================

The object parallelConnection, is a method function (Macaulay2Doc).

positiveOrientation -- a positive orientation of a matroid
**********************************************************

Synopsis
========

  * Usage:
        positiveOrientation M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a list (Macaulay2Doc), a positive orientation of M

Description
===========

This function computes a relabelling, of the ground set of a
matroid for which it is positively oriented, if one exists. In other words, the
output of this function is null (Macaulay2Doc), iff the output of
isPositivelyOrientable, is false.

+--------------------------------------------------------------+
|i1 : M = matroid({{0,1},{2,3},{4,5}}, EntryMode => "circuits")|
|                                                              |
|o1 = a "matroid" of rank 3 on 6 elements                      |
|                                                              |
|o1 : Matroid                                                  |
+--------------------------------------------------------------+
|i2 : isPositivelyOriented M                                   |
|                                                              |
|o2 = false                                                    |
+--------------------------------------------------------------+
|i3 : p = positiveOrientation M                                |
|                                                              |
|o3 = {0, 5, 1, 4, 2, 3}                                       |
|                                                              |
|o3 : List                                                     |
+--------------------------------------------------------------+
|i4 : N = relabel(M, p)                                        |
|                                                              |
|o4 = a "matroid" of rank 3 on 6 elements                      |
|                                                              |
|o4 : Matroid                                                  |
+--------------------------------------------------------------+
|i5 : isPositivelyOriented N                                   |
|                                                              |
|o5 = true                                                     |
+--------------------------------------------------------------+

See also
========

  * isPositivelyOriented -- whether a matroid is
    positively oriented
  * isPositivelyOrientable -- whether a matroid
    is positively orientable

Ways to use positiveOrientation:
================================

  * "positiveOrientation(Matroid)"

For the programmer
==================

The object positiveOrientation, is a method function (Macaulay2Doc).

projectiveGeometry -- projective geometry of dimension n over F_p
*****************************************************************

Synopsis
========

  * Usage:
        M = projectiveGeometry(n, p)
  * Inputs:
      * n, an integer (Macaulay2Doc), the dimension of the projective
        space
      * p, an integer (Macaulay2Doc), a prime
  * Outputs:
      * a matroid, the projective geometry of dimension n over
        F_p

Description
===========

The projective geometry of dimension n over F_p is the matroid whose ground set
consists of points in an n-dimensional projective space over F_p. The matroid
structure is precisely the simple matroid, associated to
the realizable matroid of (F_p)^(n+1) (i.e. all vectors in an (n+1)-dimensional
vector space over F_p) - the origin (being a loop) has been removed, and a
representative is chosen for all parallel classes (= lines).

Note that projective space has a stratification into affine spaces (one of each
smaller dimension). In particular, deleting any hyperplane from PG(n, p) gives
AG(n, p).

+-----------------------------------------------------------------------------+
|i1 : PG22 = projectiveGeometry(2, 2)                                         |
|                                                                             |
|o1 = a "matroid" of rank 3 on 7 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : PG22 == specificMatroid "fano"                                          |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
|i3 : A = transpose sub(matrix toList(((3:0)..(3:2-1))/toList), ZZ/2) -- all  |
|                                                                             |
|o3 = | 0 0 0 0 1 1 1 1 |                                                     |
|     | 0 0 1 1 0 0 1 1 |                                                     |
|     | 0 1 0 1 0 1 0 1 |                                                     |
|                                                                             |
|             ZZ 3      ZZ 8                                                  |
|o3 : Matrix (--)  <-- (--)                                                   |
|              2         2                                                    |
|-----------------------------------------------------------------------------|
|vectors in (ZZ/2)^3                                                          |
+-----------------------------------------------------------------------------+
|i4 : areIsomorphic(PG22, simpleMatroid matroid A)                            |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+
|i5 : PG32 = projectiveGeometry(3, 2)                                         |
|                                                                             |
|o5 = a "matroid" of rank 4 on 15 elements                                    |
|                                                                             |
|o5 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i6 : getRepresentation PG32                                                  |
|                                                                             |
|o6 = | 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 |                                       |
|     | 0 0 0 0 1 1 1 1 1 1 1 1 0 0 0 |                                       |
|     | 0 0 1 1 0 0 1 1 0 0 1 1 1 1 0 |                                       |
|     | 0 1 0 1 0 1 0 1 0 1 0 1 0 1 1 |                                       |
|                                                                             |
|             ZZ 4      ZZ 15                                                 |
|o6 : Matrix (--)  <-- (--)                                                   |
|              2         2                                                    |
+-----------------------------------------------------------------------------+
|i7 : H = first hyperplanes PG32                                              |
|                                                                             |
|o7 = set {8, 9, 10, 11, 12, 13, 14}                                          |
|                                                                             |
|o7 : Set                                                                     |
+-----------------------------------------------------------------------------+
|i8 : areIsomorphic(affineGeometry(3, 2), PG32 \ H)                           |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * affineGeometry -- affine geometry of rank n+1 over
    F_p
  * specificMatroid -- creates built-in matroid

Ways to use projectiveGeometry:
===============================

  * "projectiveGeometry(ZZ,ZZ)"

For the programmer
==================

The object projectiveGeometry, is a method function (Macaulay2Doc).

quickIsomorphismTest -- quick checks for isomorphism between matroids
*********************************************************************

Synopsis
========

  * Usage:
        quickIsomorphismTest(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a string (Macaulay2Doc), either "true" or "false" or
        "Could be isomorphic"

Description
===========

This method performs relatively quick tests to determine whether or not two
matroids are isomorphic. A result of "false" is definitive proof that the
matroids are not isomorphic, a result of "true" is definitive proof that the
matroids are isomorphic, and a result of "Could be isomorphic" is evidence that
the matroids may be isomorphic (although there are nonisomorphic matroids which
cannot be detected by this method).

If "true" or "false" is returned, use value (Macaulay2Doc), to
convert to a Boolean (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i1 : M0 = matroid(toList(a..z)/toString,{{"m","a","t","r","o","i","d"}})     |
|                                                                             |
|o1 = a "matroid" of rank 7 on 26 elements                                    |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : M1 = matroid(toList(0..25), {{random(ZZ),23,15,12,19,20,11}})           |
|                                                                             |
|o2 = a "matroid" of rank 7 on 26 elements                                    |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : quickIsomorphismTest(M0, M1)                                            |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+
|i4 : quickIsomorphismTest(matroid random(ZZ^5,ZZ^8), uniformMatroid(5, 8))   |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+
|i5 : quickIsomorphismTest(uniformMatroid(5, 9), uniformMatroid(4, 9))        |
|                                                                             |
|o5 = false                                                                   |
+-----------------------------------------------------------------------------+
|i6 : M0 = matroid graph({{a,b},{b,c},{c,d},{d,e},{e,f},{f,g},{f,h},{c,h},{c,f|
|                                                                             |
|o6 = a "matroid" of rank 7 on 11 elements                                    |
|                                                                             |
|o6 : Matroid                                                                 |
|-----------------------------------------------------------------------------|
|},{a,g},{d,g}})                                                              |
+-----------------------------------------------------------------------------+
|i7 : M1 = matroid graph({{a,b},{b,c},{c,d},{d,e},{e,f},{f,g},{f,h},{c,h},{c,f|
|                                                                             |
|o7 = a "matroid" of rank 7 on 11 elements                                    |
|                                                                             |
|o7 : Matroid                                                                 |
|-----------------------------------------------------------------------------|
|},{a,g},{a,h}})                                                              |
+-----------------------------------------------------------------------------+
|i8 : R = ZZ[x,y]; tuttePolynomial(M0, R) == tuttePolynomial(M1, R)           |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+
|i10 : time quickIsomorphismTest(M0, M1)                                      |
| -- used 0.000516017s (cpu); 0.00035256s (thread); 0s (gc)                   |
|                                                                             |
|o10 = false                                                                  |
+-----------------------------------------------------------------------------+
|i11 : value oo === false                                                     |
|                                                                             |
|o11 = true                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * isomorphism(Matroid,Matroid), --
    computes an isomorphism between isomorphic matroids
  * getIsos -- all isomorphisms between two matroids
  * areIsomorphic(Matroid,Matroid),
    -- whether two matroids are isomorphic

Ways to use quickIsomorphismTest:
=================================

  * "quickIsomorphismTest(Matroid,Matroid)"

For the programmer
==================

The object quickIsomorphismTest, is a method function (Macaulay2Doc).

rank(Matroid) -- rank of a matroid
**********************************

Synopsis
========

  * Function: rank (Macaulay2Doc),
  * Usage:
        rank M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * an integer (Macaulay2Doc),

Description
===========

The rank of a matroid is the common size of a(ny) basis of M. This is a basic
numerical invariant of a matroid.

+-----------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})|
|                                         |
|o1 = a "matroid" of rank 2 on 4 elements |
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : rank M                              |
|                                         |
|o2 = 2                                   |
+-----------------------------------------+

See also
========

  * rank(Matroid,Set) -- rank of a subset of a
    matroid

Ways to use this method:
========================

  * rank(Matroid) -- rank of a matroid

rank(Matroid,Set) -- rank of a subset of a matroid
**************************************************

Synopsis
========

  * Function: rank (Macaulay2Doc),
  * Usage:
        rank(M, S)
  * Inputs:
      * M, a matroid,
      * S, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M
  * Outputs:
      * an integer (Macaulay2Doc),

Description
===========

The rank of a subset S of a matroid is the size of a maximal independent subset
of S. The map 2^E $\to \mathbb{N}$, S $\mapsto$ rank(S), is called the rank
function, and completely determines the matroid.

Once the rank of a given subset is computed, it is cached in the matroid (under
M.cache#"ranks"), so future computations of the rank of the same set are
(essentially) instant.

The user may choose to install a custom rank function for a matroid (which
should take in a list of integers (corresponding to a subset of
M.groundSet), and output an integer), under M.cache#"rankFunction".
This is done automatically when a matroid is constructed from a matrix or
graph, or with setRepresentation.

+------------------------------------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}})                               |
|                                                                        |
|o1 = a "matroid" of rank 2 on 4 elements                                |
|                                                                        |
|o1 : Matroid                                                            |
+------------------------------------------------------------------------+
|i2 : for s in subsets M_* do print(toString s | " has rank " | rank_M s)|
|{} has rank 0                                                           |
|{a} has rank 1                                                          |
|{b} has rank 1                                                          |
|{a, b} has rank 2                                                       |
|{c} has rank 1                                                          |
|{a, c} has rank 2                                                       |
|{b, c} has rank 1                                                       |
|{a, b, c} has rank 2                                                    |
|{d} has rank 0                                                          |
|{a, d} has rank 1                                                       |
|{b, d} has rank 1                                                       |
|{a, b, d} has rank 2                                                    |
|{c, d} has rank 1                                                       |
|{a, c, d} has rank 2                                                    |
|{b, c, d} has rank 1                                                    |
|{a, b, c, d} has rank 2                                                 |
+------------------------------------------------------------------------+

See also
========

  * rank(Matroid) -- rank of a matroid

Ways to use this method:
========================

  * "rank(Matroid,List)"
  * rank(Matroid,Set) -- rank of a subset of a
    matroid

relabel -- relabel a matroid
****************************

Synopsis
========

  * Usage:
        relabel(M, H)
        relabel(M, L)
        relabel M
  * Inputs:
      * M, a matroid,
      * H, a hash table (Macaulay2Doc),
      * L, a list (Macaulay2Doc),
  * Outputs:
      * a matroid, a matroid isomorphic to M

Description
===========

This method yields another matroid isomorphic to the input matroid M with
labels specified by a hash table, or list of options. The keys of the hash
table should be (a subset of) $\{0, ..., n-1\}$ where n is the number of
elements in the groundSet, of M. Since any unused elements are
assumed to remain unchanged, the set of values should coincide with the set of
keys.

Alternatively, the images of $\{0, ..., n-1\}$ (in order) can be specified (as
a list, whose elements are not options). If neither a list nor hash table is
provided, then a random permutation is chosen.

+---------------------------------------------------------------------+
|i1 : Q6 = specificMatroid "Q6"                                       |
|                                                                     |
|o1 = a "matroid" of rank 3 on 6 elements                             |
|                                                                     |
|o1 : Matroid                                                         |
+---------------------------------------------------------------------+
|i2 : M = relabel_Q6 {3 => 0, 0 => 3}                                 |
|                                                                     |
|o2 = a "matroid" of rank 3 on 6 elements                             |
|                                                                     |
|o2 : Matroid                                                         |
+---------------------------------------------------------------------+
|i3 : (nonbases Q6, nonbases M)                                       |
|                                                                     |
|o3 = ({set {0, 1, 2}, set {4, 0, 3}}, {set {1, 2, 3}, set {4, 0, 3}})|
|                                                                     |
|o3 : Sequence                                                        |
+---------------------------------------------------------------------+
|i4 : (M == Q6, areIsomorphic(M, Q6))                                 |
|                                                                     |
|o4 = (false, true)                                                   |
|                                                                     |
|o4 : Sequence                                                        |
+---------------------------------------------------------------------+
|i5 : nonbases relabel Q6                                             |
|                                                                     |
|o5 = {set {0, 5, 3}, set {4, 5, 1}}                                  |
|                                                                     |
|o5 : List                                                            |
+---------------------------------------------------------------------+

See also
========

  * isomorphism(Matroid,Matroid), --
    computes an isomorphism between isomorphic matroids
  * areIsomorphic(Matroid,Matroid),
    -- whether two matroids are isomorphic

Ways to use relabel:
====================

  * "relabel(Matroid)"
  * "relabel(Matroid,HashTable)"
  * "relabel(Matroid,List)"

For the programmer
==================

The object relabel, is a method function (Macaulay2Doc).

relaxation -- relaxation of matroid
***********************************

Synopsis
========

  * Usage:
        relaxation(M, S)
        relaxation M
  * Inputs:
      * M, a matroid,
      * S, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M, which is a circuit-hyperplane of
        M
  * Optional inputs (Macaulay2Doc),:
      * CheckWellDefined, => ..., default value false,
        an optional argument
  * Outputs:
      * a matroid, the relaxation of M by S

Description
===========

Let M = (E, B) be a matroid with bases B. If there is a subset S of E that is
both a circuit, and a hyperplane, of M, then
the set $B \cup \{S\}$ is the set of bases of a matroid on E, called the
relaxation of M by S.

If no set S is provided, then this function will take S to be a random
circuit-hyperplane (the first in lexicographic order). If no
circuit-hyperplanes exist, then an error is produced.

Many interesting matroids arise as relaxations of other matroids: e.g. the
non-Fano matroid is a relaxation of the Fano matroid,
and the non-Pappus matroid is a relaxation of the Pappus matroid.

+----------------------------------------+
|i1 : P = specificMatroid "pappus"       |
|                                        |
|o1 = a "matroid" of rank 3 on 9 elements|
|                                        |
|o1 : Matroid                            |
+----------------------------------------+
|i2 : NP = specificMatroid "nonpappus"   |
|                                        |
|o2 = a "matroid" of rank 3 on 9 elements|
|                                        |
|o2 : Matroid                            |
+----------------------------------------+
|i3 : NP == relaxation(P, set{6,7,8})    |
|                                        |
|o3 = true                               |
+----------------------------------------+

Ways to use relaxation:
=======================

  * "relaxation(Matroid)"
  * "relaxation(Matroid,List)"
  * "relaxation(Matroid,Set)"

For the programmer
==================

The object relaxation, is a method function with options (Macaulay2Doc).

restriction -- restriction to subset of matroid
***********************************************

Synopsis
========

  * Usage:
        restriction(M, S)
        M | S
  * Inputs:
      * M, a matroid,
      * S, a set (Macaulay2Doc), of indices, or a list (Macaulay2Doc),
        of elements in M
  * Outputs:
      * a matroid, the restriction M | S

Description
===========

The restriction of M to S, M | S, has ground set S and independent sets equal
to the independent sets of M contained in S.

+------------------------------------------+
|i1 : M = matroid({a,b,c,d},{{a,b},{a,c}}) |
|                                          |
|o1 = a "matroid" of rank 2 on 4 elements  |
|                                          |
|o1 : Matroid                              |
+------------------------------------------+
|i2 : N = M | {a,b,d}                      |
|                                          |
|o2 = a "matroid" of rank 2 on 3 elements  |
|                                          |
|o2 : Matroid                              |
+------------------------------------------+
|i3 : peek N                               |
|                                          |
|o3 = Matroid{bases => {set {0, 1}}       }|
|             cache => CacheTable{...1...} |
|             groundSet => set {0, 1, 2}   |
|             rank => 2                    |
+------------------------------------------+
|i4 : N == M | set{0,1,3}                  |
|                                          |
|o4 = true                                 |
+------------------------------------------+

See also
========

  * deletion -- deletion of subset of matroid
  * minor -- minor of matroid

Ways to use restriction:
========================

  * "restriction(Matroid,List)"
  * "restriction(Matroid,Set)"

For the programmer
==================

The object restriction, is a method function (Macaulay2Doc).

saveMatroid -- save matroid to file
***********************************

Synopsis
========

  * Usage:
        saveMatroid M
        saveMatroid(M, s)
  * Inputs:
      * M, a matroid,
      * s, a string (Macaulay2Doc), the desired filename
  * Outputs:
      * a string (Macaulay2Doc), the output filename

Description
===========

This method stores a matroid in string format in an output file, including much
of the auxiliary data used in computations in this package (such as circuits,
flats, representations, etc.)

The name of the output file can be specified. If no output file is specified,
then a random filename is chosen (using temporaryFileName (Macaulay2Doc),
- note that in this case, such files are
automatically deleted when the M2 session ends, so make sure to copy the
temporary file before exiting M2).

The saved matroid can be read back into a later M2 session using the function
readFromFile, which is a synonym for the composite of value (Macaulay2Doc),
and get (Macaulay2Doc). This takes a filename
(as a String (Macaulay2Doc)) and returns the value of its
contents, as interpreted by M2.

+----------------------------------------+
|i2 : V = specificMatroid "vamos"        |
|                                        |
|o2 = a "matroid" of rank 4 on 8 elements|
|                                        |
|o2 : Matroid                            |
+----------------------------------------+
|i3 : betti ideal V                      |
|                                        |
|            0  1                        |
|o3 = total: 1 41                        |
|         0: 1  .                        |
|         1: .  .                        |
|         2: .  .                        |
|         3: .  5                        |
|         4: . 36                        |
|                                        |
|o3 : BettiTally                         |
+----------------------------------------+
|i4 : saveMatroid(V, "vamos.txt")        |
|                                        |
|o4 = vamos.txt                          |
+----------------------------------------+
|i5 : clearAll()                         |
+----------------------------------------+
|i6 : V = readFromFile "vamos.txt"       |
|                                        |
|o6 = a "matroid" of rank 4 on 8 elements|
|                                        |
|o6 : Matroid                            |
+----------------------------------------+
|i7 : keys V.cache                       |
|                                        |
|o7 = {groundSet, ideal}                 |
|                                        |
|o7 : List                               |
+----------------------------------------+

Ways to use saveMatroid:
========================

  * "saveMatroid(Matroid)"
  * "saveMatroid(Matroid,String)"

For the programmer
==================

The object saveMatroid, is a method function (Macaulay2Doc).

searchRepresentation -- search for a representation of a matroid over a finite field
************************************************************************************

Synopsis
========

  * Usage:
        searchRepresentation(M, k)
  * Inputs:
      * M, a matroid,
      * k, a Galois field (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Attempts => ..., default value 1000
  * Outputs:
      * a matrix (Macaulay2Doc), a purported representation of M

Description
===========

This function performs a brute-force search for a representation of a matroid,
over a given finite field (essentially repeatedly testing random candidates
until one is found).

The maximum number of attempts is specified by the optional argument Attempts
(default 1000).

Over GF(2), this function is guaranteed to (quickly) find a representation, if
one exists. (Over larger finite fields, there is no such guarantee.)

+--------------------------------------------------------------------------+
|i1 : searchRepresentation(uniformMatroid(2, 4), GF 2)                     |
+--------------------------------------------------------------------------+
|i2 : searchRepresentation(matroid completeGraph 5, GF 3, Attempts => 2000)|
|                                                                          |
|o2 = | 1 1 1 1 0  0  0 0  0 0 |                                           |
|     | 1 0 0 0 1  1  1 0  0 0 |                                           |
|     | 0 1 0 0 -1 0  0 1  1 0 |                                           |
|     | 0 0 1 0 0  -1 0 -1 0 1 |                                           |
|                                                                          |
|                  4           10                                          |
|o2 : Matrix (GF 3)  <-- (GF 3)                                            |
+--------------------------------------------------------------------------+

See also
========

  * setRepresentation -- stores user-defined
    representation
  * getRepresentation -- retrieves stored
    representation

Ways to use searchRepresentation:
=================================

  * "searchRepresentation(Matroid,GaloisField)"

For the programmer
==================

The object searchRepresentation, is a method function with options (Macaulay2Doc).

seriesConnection -- series connection of two matroids
*****************************************************

Synopsis
========

  * Usage:
        seriesConnection(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a matroid, the series connection of M and N with
        basepoint 0

Description
===========

This function returns the series connection of two given matroids M and N (cf.
Oxley, Section 7.1).

It is always assumed that the common basepoint of M and N is the first element
in the respective ground sets, i.e. the element with index 0. (To form a series
connection using a different basepoint, one can first relabel, M
and/or N.)

This method includes series extensions as a special case: a series extension of
M is a series connection of M with U(1,2).

+-----------------------------------------------------------------------------+
|i1 : G = graph({{0,1},{1,2},{2,3},{3,4},{4,5},{5,6},{6,0},{0,2},{0,3},{0,4},{|
|                                                                             |
|o1 = Graph{0 => {1, 2, 3, 4, 6}   }                                          |
|           1 => {0, 2, 3}                                                    |
|           2 => {0, 1, 3}                                                    |
|           3 => {0, 1, 2, 4, 5, 6}                                           |
|           4 => {0, 3, 5}                                                    |
|           5 => {3, 4, 6}                                                    |
|           6 => {0, 3, 5}                                                    |
|                                                                             |
|o1 : Graph                                                                   |
|-----------------------------------------------------------------------------|
|1,3},{3,5},{3,6}})                                                           |
+-----------------------------------------------------------------------------+
|i2 : M = matroid G                                                           |
|                                                                             |
|o2 = a "matroid" of rank 6 on 13 elements                                    |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : seriesConnection(M, uniformMatroid(1,2))                                |
|                                                                             |
|o3 = a "matroid" of rank 7 on 14 elements                                    |
|                                                                             |
|o3 : Matroid                                                                 |
+-----------------------------------------------------------------------------+

See also
========

  * parallelConnection -- parallel connection of two
    matroids
  * sum2 -- 2-sum of matroids

Ways to use seriesConnection:
=============================

  * "seriesConnection(Matroid,Matroid)"

For the programmer
==================

The object seriesConnection, is a method function (Macaulay2Doc).

setRepresentation -- stores user-defined representation
*******************************************************

Synopsis
========

  * Usage:
        setRepresentation(M, A)
  * Inputs:
      * M, a matroid,
      * A, a matrix (Macaulay2Doc),
  * Outputs:
      * a matroid, with a stored representation

Description
===========

This function provides a way for the user to specify a representation of a
matroid (given by a matrix). The matrix is cached in the matroid (under
M.cache.storedRepresentation), and can be retrieved using
getRepresentation.

This function will also create a custom rank function for the matroid, using
the given representation (this is also cached in the matroid, under
M.cache.rankFunction). This can lead to faster computations of rank.

+----------------------------------------------------+
|i1 : M = uniformMatroid(4, 6)                       |
|                                                    |
|o1 = a "matroid" of rank 4 on 6 elements            |
|                                                    |
|o1 : Matroid                                        |
+----------------------------------------------------+
|i2 : A = random(QQ^4,QQ^6)                          |
|                                                    |
|o2 = | 9/2 1   7/4  7/10 5/2 2   |                  |
|     | 1/2 3/4 7/9  7/3  6/7 6   |                  |
|     | 9/4 3/2 7/10 7    2/3 5/4 |                  |
|     | 1/2 3/4 1/2  3/7  1   2/9 |                  |
|                                                    |
|              4       6                             |
|o2 : Matrix QQ  <-- QQ                              |
+----------------------------------------------------+
|i3 : setRepresentation(M, A)                        |
|                                                    |
|o3 = a "matroid" of rank 4 on 6 elements            |
|                                                    |
|o3 : Matroid                                        |
+----------------------------------------------------+
|i4 : getRepresentation M                            |
|                                                    |
|o4 = | 9/2 1   7/4  7/10 5/2 2   |                  |
|     | 1/2 3/4 7/9  7/3  6/7 6   |                  |
|     | 9/4 3/2 7/10 7    2/3 5/4 |                  |
|     | 1/2 3/4 1/2  3/7  1   2/9 |                  |
|                                                    |
|              4       6                             |
|o4 : Matrix QQ  <-- QQ                              |
+----------------------------------------------------+
|i5 : keys M.cache                                   |
|                                                    |
|o5 = {groundSet, rankFunction, storedRepresentation}|
|                                                    |
|o5 : List                                           |
+----------------------------------------------------+
|i6 : elapsedTime fVector M                          |
| -- .00864738s elapsed                              |
|                                                    |
|o6 = HashTable{0 => 1 }                             |
|               1 => 6                               |
|               2 => 15                              |
|               3 => 20                              |
|               4 => 1                               |
|                                                    |
|o6 : HashTable                                      |
+----------------------------------------------------+

See also
========

  * getRepresentation -- retrieves stored
    representation
  * matroid -- constructs a matroid

Ways to use setRepresentation:
==============================

  * "setRepresentation(Matroid,Matrix)"

For the programmer
==================

The object setRepresentation, is a method function (Macaulay2Doc).

simpleMatroid -- simple matroid associated to a matroid
*******************************************************

Synopsis
========

  * Usage:
        S = simpleMatroid M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a matroid, the simple matroid associated to M

Description
===========

The simple matroid associated to a matroid M is obtained from M by deleting all
loops, and all but one element from each parallel class.

In a simple matroid, the lattice of flats, has the empty
set as minimal element, and all atoms are singletons.

+-----------------------------------------------------------------------------+
|i1 : M = uniformMatroid(0, 2) ++ uniformMatroid(1, 2) ++ uniformMatroid(2, 4)|
|                                                                             |
|o1 = a "matroid" of rank 3 on 8 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : isSimple M                                                              |
|                                                                             |
|o2 = false                                                                   |
+-----------------------------------------------------------------------------+
|i3 : S = simpleMatroid M                                                     |
|                                                                             |
|o3 = a "matroid" of rank 3 on 5 elements                                     |
|                                                                             |
|o3 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i4 : latticeOfFlats M == latticeOfFlats S                                    |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+
|i5 : select(flats S, f -> rank(S, f) <= 1)                                   |
|                                                                             |
|o5 = {set {}, set {4}, set {3}, set {2}, set {1}, set {0}}                   |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : AG32 = affineGeometry(3, 2)                                             |
|                                                                             |
|o6 = a "matroid" of rank 4 on 8 elements                                     |
|                                                                             |
|o6 : Matroid                                                                 |
+-----------------------------------------------------------------------------+

See also
========

  * isSimple(Matroid) -- whether a matroid is
    simple

Ways to use simpleMatroid:
==========================

  * "simpleMatroid(Matroid)"

For the programmer
==================

The object simpleMatroid, is a method function (Macaulay2Doc).

specificMatroid -- creates built-in matroid
*******************************************

Synopsis
========

  * Usage:
        specificMatroid(S)
  * Inputs:
      * S, a string (Macaulay2Doc), or symbol, the name of the
        matroid
  * Outputs:
      * a matroid,

Description
===========

Returns one of the named matroids below.

  * U24
  * C5
  * P6
  * Q6
  * fano
  * nonfano
  * V8+
  * vamos
  * pappus
  * nonpappus
  * nondesargues
  * betsyRoss
  * AG32
  * AG32'
  * F8
  * J
  * L8
  * O7
  * P6
  * P7
  * P8
  * P8=
  * Q3(GF(3)*)
  * Q6
  * Q8
  * R6
  * R8
  * R9
  * R9A
  * R9B
  * R10
  * R12
  * S8
  * S5612
  * T8
  * T12

The matroids provided in this function (together with the infinite families
given by the functions affineGeometry,
projectiveGeometry, binarySpike,
spike, swirl, wheel, whirl,
thetaMatroid, uniformMatroid)
includes all "interesting matroids" listed in Oxley, p. 639 - 664 (except for
the general Dowling geometry).

Many of these matroids are interesting for their (non-)representability or
duality properties:

  * U24 is the uniform matroid of rank 2 on 4 elements, i.e. the 4 point line,
    and is the unique forbidden minor for representability over the field of 2
    elements
  * The Fano matroid F7 is the matroid of the projective plane over F_2, and is
    representable only in characteristic 2. The non-Fano matroid is a
    relaxation of F7, and is representable only in characteristic not equal to
    2.
  * The Pappus matroid is an illustration of Pappus' theorem. By the same
    token, the non-Pappus matroid is a relaxation which is not representable
    over any field.
  * The Vamos matroid V, which is a relaxation of V8+, is the smallest (size)
    matroid which is not representable over any field - indeed, it is not even
    algebraic. V8+ is identically self-dual, while V is isomorphic to its dual.
  * AG32 is the affine geometry corresponding to a 3-dimensional vector space
    over F_2, and is identically self-dual, with circuits equal to its
    hyperplanes. A relaxation of AG32 is the smallest matroid not representable
    over any field, with fewer basis elements than V.
  * R9A and R9B (along with their duals) are the only matroids on <= 9 elements
    that are not representable over any field, although their foundations do
    not have $1$ as a fundamental element.
  * R10 is a rank 5 matroid on 10 elements, which is the unique splitter for
    the class of regular matroids.
  * The Betsy Ross matroid is a matroid which is representable over the Golden
    Mean partial field
+-------------------------------------------------------------------------+
|i1 : F7 = specificMatroid "fano"                                         |
|                                                                         |
|o1 = a "matroid" of rank 3 on 7 elements                                 |
|                                                                         |
|o1 : Matroid                                                             |
+-------------------------------------------------------------------------+
|i2 : all(F7_*, x -> areIsomorphic(matroid completeGraph 4, F7 \ {x}))    |
|                                                                         |
|o2 = true                                                                |
+-------------------------------------------------------------------------+
|i3 : AG32 = specificMatroid "AG32"                                       |
|                                                                         |
|o3 = a "matroid" of rank 4 on 8 elements                                 |
|                                                                         |
|o3 : Matroid                                                             |
+-------------------------------------------------------------------------+
|i4 : getRepresentation AG32                                              |
|                                                                         |
|o4 = | 1 1 1 1 1 1 1 1 |                                                 |
|     | 0 0 0 0 1 1 1 1 |                                                 |
|     | 0 0 1 1 0 0 1 1 |                                                 |
|     | 0 1 0 1 0 1 0 1 |                                                 |
|                                                                         |
|             ZZ 4      ZZ 8                                              |
|o4 : Matrix (--)  <-- (--)                                               |
|              2         2                                                |
+-------------------------------------------------------------------------+
|i5 : AG32 == dual AG32                                                   |
|                                                                         |
|o5 = true                                                                |
+-------------------------------------------------------------------------+
|i6 : R10 = specificMatroid "R10"                                         |
|                                                                         |
|o6 = a "matroid" of rank 5 on 10 elements                                |
|                                                                         |
|o6 : Matroid                                                             |
+-------------------------------------------------------------------------+
|i7 : getRepresentation R10                                               |
|                                                                         |
|o7 = | 1 0 0 0 0 1 1 0 0 1 |                                             |
|     | 0 1 0 0 0 1 1 1 0 0 |                                             |
|     | 0 0 1 0 0 0 1 1 1 0 |                                             |
|     | 0 0 0 1 0 0 0 1 1 1 |                                             |
|     | 0 0 0 0 1 1 0 0 1 1 |                                             |
|                                                                         |
|             ZZ 5      ZZ 10                                             |
|o7 : Matrix (--)  <-- (--)                                               |
|              2         2                                                |
+-------------------------------------------------------------------------+
|i8 : areIsomorphic(R10 \ set{0}, matroid completeMultipartiteGraph {3,3})|
|                                                                         |
|o8 = true                                                                |
+-------------------------------------------------------------------------+

Caveat
======

Notice that the ground set is a subset of $\{0, ..., n-1\}$ rather than $\{1,
..., n\}$.

See also
========

  * matroid -- constructs a matroid
  * allMatroids -- returns all n-element matroids of rank r

Ways to use specificMatroid:
============================

  * "specificMatroid(String)"
  * "specificMatroid(Symbol)"

For the programmer
==================

The object specificMatroid, is a method function (Macaulay2Doc).

spike -- spike matroid
**********************

Synopsis
========

  * Usage:
        M = spike r
        M = spike(r, L)
        M = binarySpike r
  * Inputs:
      * r, an integer (Macaulay2Doc),
      * L, a list (Macaulay2Doc), of circuits
  * Outputs:
      * a matroid, a (tipped) r-spike

Description
===========

The family of spikes appears in Oxley, p. 661-662. For a given r, every r-spike
has 2r+1 elements and rank r. The ground set consists of a tip 0, and r legs
{0, 1, 2}, {0, 3, 4}, ..., {0, 2*r-1, 2*r} (each of which is a circuit).

Deleting the tip 0 gives a matroid of rank r on 2r elements called a tipless
r-spike.

The optional input L should be a list of additional circuits, subject to
certain additional conditions to be a spike. If no additional circuits are
provided, then the spike is called free.

Out of all possible r-spikes, there is a a unique one which is binary (i.e.
representable over the field of 2 elements): this is returned by the function
binarySpike.

+-----------------------------------------+
|i1 : M = binarySpike 5                   |
|                                         |
|o1 = a "matroid" of rank 5 on 11 elements|
|                                         |
|o1 : Matroid                             |
+-----------------------------------------+
|i2 : getRepresentation M                 |
|                                         |
|o2 = | 1 0 0 0 0 0 1 1 1 1 1 |           |
|     | 0 1 0 0 0 1 0 1 1 1 1 |           |
|     | 0 0 1 0 0 1 1 0 1 1 1 |           |
|     | 0 0 0 1 0 1 1 1 0 1 1 |           |
|     | 0 0 0 0 1 1 1 1 1 0 1 |           |
|                                         |
|             ZZ 5      ZZ 11             |
|o2 : Matrix (--)  <-- (--)               |
|              2         2                |
+-----------------------------------------+
|i3 : N = M \ set{0}                      |
|                                         |
|o3 = a "matroid" of rank 5 on 10 elements|
|                                         |
|o3 : Matroid                             |
+-----------------------------------------+
|i4 : areIsomorphic(N, dual N)            |
|                                         |
|o4 = true                                |
+-----------------------------------------+
|i5 : N1 = (spike 5) \ set{0}             |
|                                         |
|o5 = a "matroid" of rank 5 on 10 elements|
|                                         |
|o5 : Matroid                             |
+-----------------------------------------+
|i6 : N1 == dual N1                       |
|                                         |
|o6 = true                                |
+-----------------------------------------+

See also
========

  * specificMatroid -- creates built-in matroid

Ways to use spike:
==================

  * "spike(ZZ)"
  * "spike(ZZ,List)"

For the programmer
==================

The object spike, is a method function (Macaulay2Doc).

sum2 -- 2-sum of matroids
*************************

Synopsis
========

  * Usage:
        sum2(M, N)
  * Inputs:
      * M, a matroid,
      * N, a matroid,
  * Outputs:
      * a matroid, the 2-sum of M and N with basepoint 0

Description
===========

This function returns the 2-sum of two given matroids M and N (cf. Oxley,
Section 7.1).

It is always assumed that the common basepoint of M and N is the first element
in the respective ground sets, i.e. the element with index 0. (To form a 2-sum
using a different basepoint, one can first relabel, M and/or N.)
Moreover, it is necessary that the basepoint 0 is not a loop, or
coloop, in either M or N. Under these assumptions, the 2-sum of
M and N is equal to the contraction, of the
seriesConnection, of M and N by 0 (or alternatively, the
deletion of the parallelConnection, of M and N by 0).

The operation of 2-sum is important in higher matroid connectivity: a
connected, matroid is 3-connected,
iff it cannot be expressed as a 2-sum of smaller matroids.

+----------------------------------------------------------+
|i1 : M = sum2(specificMatroid "fano", uniformMatroid(2,4))|
|                                                          |
|o1 = a "matroid" of rank 4 on 9 elements                  |
|                                                          |
|o1 : Matroid                                              |
+----------------------------------------------------------+
|i2 : isConnected M                                        |
|                                                          |
|o2 = true                                                 |
+----------------------------------------------------------+
|i3 : is3Connected M                                       |
|                                                          |
|o3 = false                                                |
+----------------------------------------------------------+

See also
========

  * seriesConnection -- series connection of two
    matroids
  * is3Connected -- whether a matroid is 3-connected
  * getSeparation -- finds a k-separation of a matroid
  * isConnected(Matroid) -- whether a matroid
    is connected

Ways to use sum2:
=================

  * "sum2(Matroid,Matroid)"

For the programmer
==================

The object sum2, is a method function (Macaulay2Doc).

swirl -- swirl matroid
**********************

Synopsis
========

  * Usage:
        M = swirl r
  * Inputs:
      * r, an integer (Macaulay2Doc),
  * Outputs:
      * a matroid, a free swirl

Description
===========

The family of swirls appears in Oxley, p. 664. The rank-r free swirl has 2r
elements and rank r.

+-----------------------------------------------+
|i1 : areIsomorphic(swirl 3, uniformMatroid_3 6)|
|                                               |
|o1 = true                                      |
+-----------------------------------------------+
|i2 : M = swirl 4                               |
|                                               |
|o2 = a "matroid" of rank 4 on 8 elements       |
|                                               |
|o2 : Matroid                                   |
+-----------------------------------------------+
|i3 : betti ideal M                             |
|                                               |
|            0  1                               |
|o3 = total: 1 44                               |
|         0: 1  .                               |
|         1: .  .                               |
|         2: .  .                               |
|         3: .  4                               |
|         4: . 40                               |
|                                               |
|o3 : BettiTally                                |
+-----------------------------------------------+
|i4 : M == dual M                               |
|                                               |
|o4 = true                                      |
+-----------------------------------------------+
|i5 : getSeparation(M, 3)                       |
|                                               |
|o5 = set {0, 1, 6, 7}                          |
|                                               |
|o5 : Set                                       |
+-----------------------------------------------+

See also
========

  * specificMatroid -- creates built-in matroid

Ways to use swirl:
==================

  * "swirl(ZZ)"

For the programmer
==================

The object swirl, is a method function (Macaulay2Doc).

thetaMatroid -- theta matroid
*****************************

Synopsis
========

  * Usage:
        M = thetaMatroid n
  * Inputs:
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * a matroid, the theta matroid

Description
===========

The family of theta matroids appears in Oxley, p. 663. For a given n,
thetaMatroid n has 2n elements and rank n.

A notable feature of this family is that thetaMatroid n is representable over a
field iff the field has at least n - 1 elements (a property also shared by
uniformMatroid(2, n)).

+----------------------------------------------+
|i1 : M = thetaMatroid 3                       |
|                                              |
|o1 = a "matroid" of rank 3 on 6 elements      |
|                                              |
|o1 : Matroid                                  |
+----------------------------------------------+
|i2 : areIsomorphic(M, matroid completeGraph 4)|
|                                              |
|o2 = true                                     |
+----------------------------------------------+

See also
========

  * specificMatroid -- creates built-in matroid

Ways to use thetaMatroid:
=========================

  * "thetaMatroid(ZZ)"

For the programmer
==================

The object thetaMatroid, is a method function (Macaulay2Doc).

toSageMatroid -- Sage format for matroid
****************************************

Synopsis
========

  * Usage:
        toSageMatroid M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a string (Macaulay2Doc),

Description
===========

This method returns a string which can be recognized as a matroid in the Sage
matroids package.

Currently this function is purely for demonstrative purposes, using lowercase
alphabet letters for the ground set (thus limited to matroids on <= 26
elements), and using a basis description.

The inverse functionality is provided by the function fromSageMatroid.

+----------------------------------------------------------------------------+
|i1 : V = specificMatroid "vamos"                                            |
|                                                                            |
|o1 = a "matroid" of rank 4 on 8 elements                                    |
|                                                                            |
|o1 : Matroid                                                                |
+----------------------------------------------------------------------------+
|i2 : s = toSageMatroid V                                                    |
|                                                                            |
|o2 = Matroid(groundset = 'abcdefgh', bases =                                |
|     ['dfgh','cfgh','bfgh','afgh','degh','cegh','begh','aegh','bdgh','adgh',|
|     'bcgh','acgh','defh','cefh','befh','aefh','cdfh','bdfh','adfh','bcfh', |
|     'acfh','abfh','cdeh','bdeh','adeh','bceh','aceh','abeh','bcdh','acdh', |
|     'abdh','abch','defg','cefg','befg','aefg','cdfg','bdfg','adfg','bcfg', |
|     'acfg','abfg','cdeg','bdeg','adeg','bceg','aceg','abeg','bcdg','acdg', |
|     'abdg','abcg','bdef','adef','bcef','acef','bcdf','acdf','abdf','abcf', |
|     'bcde','acde','abde','abce','efgh'])                                   |
+----------------------------------------------------------------------------+
|i3 : class s                                                                |
|                                                                            |
|o3 = String                                                                 |
|                                                                            |
|o3 : Type                                                                   |
+----------------------------------------------------------------------------+
|i4 : fromSageMatroid s === V                                                |
|                                                                            |
|o4 = true                                                                   |
+----------------------------------------------------------------------------+

Ways to use toSageMatroid:
==========================

  * "toSageMatroid(Matroid)"

For the programmer
==================

The object toSageMatroid, is a method function (Macaulay2Doc).

truncate(Set,Matroid) -- the truncation of a matroid with respect to a flat
***************************************************************************

Synopsis
========

  * Function: truncate (Macaulay2Doc),
  * Usage:
        truncate M,
        truncate(F, M)
  * Inputs:
      * F, a set (Macaulay2Doc), a flat of the matroid
      * M, a matroid,
  * Outputs:
      * a matroid, the truncation of the matroid

Description
===========

This function is provided by the package Matroids.

The truncation of a matroid M is the matroid T(M) on the same ground set as M
whose rank function is given by taking the maximum of the rank of a set in M
and the rank of M minus one.  The truncation T(M) is an example of an
elementary quotient of M. For a uniform matroid U_{r,n}, the truncation is just
U_{r-1,n}.

+---------------------------------------------------+
|i1 : M = uniformMatroid(4, 5);                     |
+---------------------------------------------------+
|i2 : TM = truncate M                               |
|                                                   |
|o2 = a "matroid" of rank 3 on 5 elements           |
|                                                   |
|o2 : Matroid                                       |
+---------------------------------------------------+
|i3 : quickIsomorphismTest(TM, uniformMatroid(3, 5))|
|                                                   |
|o3 = true                                          |
+---------------------------------------------------+

The flats of the truncation T(M) are just the flats of M with the hyperplanes
removed.

+---------------------------------------------------+
|i4 : M = matroid completeGraph 5;                  |
+---------------------------------------------------+
|i5 : TM = truncate M                               |
|                                                   |
|o5 = a "matroid" of rank 3 on 10 elements          |
|                                                   |
|o5 : Matroid                                       |
+---------------------------------------------------+
|i6 : set flats TM === (set flats M) - hyperplanes M|
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+

The i-fold truncation T^i(M) can be constructed as follows.

+-----------------------------------------------------------------------------+
|i7 : T2M = truncate(2, M)                                                    |
|                                                                             |
|o7 = a "matroid" of rank 2 on 10 elements                                    |
|                                                                             |
|o7 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i8 : partition(F -> rank(T2M, F), flats T2M)                                 |
|                                                                             |
|o8 = HashTable{0 => {set {}}                                                 |
|               1 => {set {9}, set {8}, set {7}, set {6}, set {5}, set {4},   |
|               2 => {set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}}                     |
|                                                                             |
|o8 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|                                   }                                         |
|set {3}, set {2}, set {1}, set {0}}                                          |
+-----------------------------------------------------------------------------+

We can also construct the principal truncation of M with respect to some flat
F.  The principal truncation of M with respect to F is the elementary quotient
of M corresponding to the principal modular cut associated to F.

+-----------------------------------------------------------------------------+
|i9 : F = set {0, 1, 4};                                                      |
+-----------------------------------------------------------------------------+
|i10 : TFM = truncate(F, M)                                                   |
|                                                                             |
|o10 = a "matroid" of rank 3 on 10 elements                                   |
|                                                                             |
|o10 : Matroid                                                                |
+-----------------------------------------------------------------------------+
|i11 : partition(G -> rank(TFM, G), flats TFM)                                |
|                                                                             |
|o11 = HashTable{0 => {set {}}                                                |
|                1 => {set {9}, set {8}, set {7}, set {6}, set {5}, set {3},  |
|                2 => {set {8, 9, 7}, set {9, 5, 6}, set {0, 9, 1, 4}, set {9 |
|                3 => {set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}}                    |
|                                                                             |
|o11 : HashTable                                                              |
|-----------------------------------------------------------------------------|
|                                                                             |
|set {2}, set {4, 0, 1}}                                                      |
|, 2, 3}, set {8, 0, 1, 3, 4, 6}, set {8, 5}, set {8, 2}, set {6, 7}, set {0, |
|-----------------------------------------------------------------------------|
|                                                   }                         |
|                                                                             |
|1, 2, 4, 5, 7}, set {7, 3}, set {6, 2}, set {5, 3}}                          |
+-----------------------------------------------------------------------------+

See also
========

  * elementaryQuotient -- associated to a modular
    cut or linear subclass
  * modularCut -- associated to an elementary quotient or
    linear subclass

Ways to use this method:
========================

  * "truncate(Matroid)"
  * truncate(Set,Matroid) -- the truncation
    of a matroid with respect to a flat

truncate(ZZ,Matroid) -- the truncation of a matroid with respect to a flat
**************************************************************************

Synopsis
========

  * Function: truncate (Macaulay2Doc),
  * Usage:
        truncate(i, M)
  * Inputs:
      * i, an integer (Macaulay2Doc), a non-negative integer
      * M, a matroid,
  * Outputs:
      * a matroid, the i-fold truncation of the matroid

Description
===========

This function is provided by the package Matroids.

Constructs the i-fold truncation T^i(M) of the matroid M.

+-----------------------------------------------------------------------------+
|i1 : M = matroid completeGraph 5                                             |
|                                                                             |
|o1 = a "matroid" of rank 4 on 10 elements                                    |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : T2M = truncate(2, M)                                                    |
|                                                                             |
|o2 = a "matroid" of rank 2 on 10 elements                                    |
|                                                                             |
|o2 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i3 : partition(F -> rank(T2M, F), flats T2M)                                 |
|                                                                             |
|o3 = HashTable{0 => {set {}}                                                 |
|               1 => {set {9}, set {8}, set {7}, set {6}, set {5}, set {4},   |
|               2 => {set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}}                     |
|                                                                             |
|o3 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|                                   }                                         |
|set {3}, set {2}, set {1}, set {0}}                                          |
+-----------------------------------------------------------------------------+

See also
========

  * elementaryQuotient -- associated to a modular
    cut or linear subclass
  * modularCut -- associated to an elementary quotient or
    linear subclass
  * truncate(Matroid) -- the truncation of
    a matroid with respect to a flat

Ways to use this method:
========================

  * truncate(ZZ,Matroid) -- the truncation
    of a matroid with respect to a flat

tutteEvaluate -- evaluate Tutte polynomial
******************************************

Synopsis
========

  * Usage:
        tutteEvaluate(M, a, b)
  * Inputs:
      * M, a matroid,
      * a, a thing (Macaulay2Doc),
      * b, a thing (Macaulay2Doc),
  * Outputs:
      * a thing (Macaulay2Doc), the evaluation of the Tutte
        polynomial of M at (a, b)

Description
===========

Provides a user-friendly method to evaluate the Tutte polynomial at given
values (i.e. calls substitute (Macaulay2Doc), with the correct
variables in the ring of the Tutte polynomial). For example, if M has Tutte
polynomial T, then T(1,1) is the number of bases of M.

+----------------------------------------+
|i1 : M = uniformMatroid(2, 4)           |
|                                        |
|o1 = a "matroid" of rank 2 on 4 elements|
|                                        |
|o1 : Matroid                            |
+----------------------------------------+
|i2 : tutteEvaluate(M, 1, 1)             |
|                                        |
|o2 = 6                                  |
+----------------------------------------+

If M = M(G) is the graphic matroid of a graph G, then T(2, 1) counts the number
of spanning forests of G, and T(2, 0) counts the number of acyclic orientations
of G.

+-----------------------------------------+
|i3 : M = matroid completeGraph 5         |
|                                         |
|o3 = a "matroid" of rank 4 on 10 elements|
|                                         |
|o3 : Matroid                             |
+-----------------------------------------+
|i4 : tutteEvaluate(M, 2, 1)              |
|                                         |
|o4 = 291                                 |
+-----------------------------------------+
|i5 : tutteEvaluate(M, 2, 0)              |
|                                         |
|o5 = 120                                 |
+-----------------------------------------+

See also
========

  * tuttePolynomial(Matroid) -- Tutte
    polynomial of a matroid

Ways to use tutteEvaluate:
==========================

  * "tutteEvaluate(Matroid,Thing,Thing)"

For the programmer
==================

The object tutteEvaluate, is a method function (Macaulay2Doc).

tuttePolynomial(Matroid) -- Tutte polynomial of a matroid
*********************************************************

Synopsis
========

  * Function: tuttePolynomial (Posets),
  * Usage:
        tuttePolynomial M
  * Inputs:
      * M, a matroid,
  * Outputs:
      * a ring element (Macaulay2Doc), the Tutte polynomial
        of M

Description
===========

The Tutte polynomial is an invariant of a matroid that is universal with
respect to satisfying a deletion-contraction recurrence. Indeed, one way to
define the Tutte polynomial of a matroid is: if $M$ is a matroid consisting of
$a$ loops and $b$ coloops, then $T_M(x, y) = x^ay^b$, and if $e \in M$ is
neither a loop nor a coloop, then $T_M(x, y) := T_{M \backslash e}(x, y) +
T_{M/e}(x, y)$, where M\e is the deletion, of M with respect to
$\{e\}$, and M/e is the contraction, of M with respect to
$\{e\}$. Many invariants of a matroid can be determined by substituting values
into its Tutte polynomial - cf. tutteEvaluate.

+---------------------------------------------------------------+
|i1 : tuttePolynomial matroid completeGraph 4                   |
|                                                               |
|      3    3     2            2                                |
|o1 = x  + y  + 3x  + 4x*y + 3y  + 2x + 2y                      |
|                                                               |
|o1 : ZZ[x..y]                                                  |
+---------------------------------------------------------------+
|i2 : tuttePolynomial specificMatroid "nonpappus"               |
|                                                               |
|      6     5     4    3      3     2             2            |
|o2 = y  + 3y  + 6y  + x  + 10y  + 6x  + 8x*y + 15y  + 13x + 13y|
|                                                               |
|o2 : ZZ[x..y]                                                  |
+---------------------------------------------------------------+

See also
========

  * tutteEvaluate -- evaluate Tutte polynomial
  * characteristicPolynomial(Matroid)
    -- computes characteristic
    polynomial of a matroid
  * chromaticPolynomial -- computes chromatic
    polynomial of a graph
  * deletion -- deletion of subset of matroid
  * contraction -- contraction of subset of matroid

Ways to use this method:
========================

  * tuttePolynomial(Matroid) -- Tutte
    polynomial of a matroid
  * "tuttePolynomial(Matroid,Ring)"

uniformMatroid -- uniform matroid
*********************************

Synopsis
========

  * Usage:
        U = uniformMatroid(k, n)
  * Inputs:
      * k, an integer (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * a matroid, the uniform matroid of rank k on n elements

Description
===========

The uniform matroid of rank k has as bases all size k subsets. The ground set
is $\{0, ..., n-1\}$.

+-----------------------------------------------------------------------------+
|i1 : U35 = uniformMatroid(3,5)                                               |
|                                                                             |
|o1 = a "matroid" of rank 3 on 5 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : peek U35                                                                |
|                                                                             |
|o2 = Matroid{bases => {set {0, 1, 2}, set {0, 1, 3}, set {0, 2, 3}, set {1,  |
|             cache => CacheTable{...1...}                                    |
|             groundSet => set {0, 1, 2, 3, 4}                                |
|             rank => 3                                                       |
|-----------------------------------------------------------------------------|
|2, 3}, set {4, 0, 1}, set {4, 0, 2}, set {4, 1, 2}, set {4, 0, 3}, set {4, 1,|
|-----------------------------------------------------------------------------|
|3}, set {4, 2, 3}}}                                                          |
+-----------------------------------------------------------------------------+

See also
========

  * specificMatroid -- creates built-in matroid

Ways to use uniformMatroid:
===========================

  * "uniformMatroid(ZZ,ZZ)"

For the programmer
==================

The object uniformMatroid, is a method function (Macaulay2Doc).

wheel -- wheels/whirls
**********************

Synopsis
========

  * Usage:
        M = wheel r
        M = whirl r
  * Inputs:
      * r, an integer (Macaulay2Doc),
  * Outputs:
      * a matroid, a rank r wheel or whirl

Description
===========

The families of wheels and whirls appears in Oxley, p. 659-660. The rank-r
wheel is the graphic matroid of the wheel graph (Graphs), with
r outer vertices, and has 2r elements. The rank-r whirl is the unique
relaxation of the rank-r wheel (and thus also has 2r elements).

+----------------------------------------+
|i1 : M = wheel 3                        |
|                                        |
|o1 = a "matroid" of rank 3 on 6 elements|
|                                        |
|o1 : Matroid                            |
+----------------------------------------+
|i2 : M == matroid wheelGraph 4          |
|                                        |
|o2 = true                               |
+----------------------------------------+
|i3 : N = whirl 3                        |
|                                        |
|o3 = a "matroid" of rank 3 on 6 elements|
|                                        |
|o3 : Matroid                            |
+----------------------------------------+
|i4 : areIsomorphic(N, relaxation M)     |
|                                        |
|o4 = true                               |
+----------------------------------------+

See also
========

  * wheelGraph (Graphs) -- Constructs a wheel graph
  * specificMatroid -- creates built-in matroid

Ways to use wheel:
==================

  * "wheel(ZZ)"

For the programmer
==================

The object wheel, is a method function (Macaulay2Doc).

Working with Chow rings of matroids
***********************************

This documentation page contains various tips for effectively working with Chow
rings of matroids within this package. We take the graphic matroid of the
complete graph on 4 vertices as the running example:

+-----------------------------------------------------------------------------+
|i1 : M = matroid completeGraph 4                                             |
|                                                                             |
|o1 = a "matroid" of rank 3 on 6 elements                                     |
|                                                                             |
|o1 : Matroid                                                                 |
+-----------------------------------------------------------------------------+
|i2 : I = idealChowRing M;                                                    |
|                                                                             |
|o2 : Ideal of QQ[x   , x   , x   , x   , x   , x   , x         , x         , |
|                  {5}   {4}   {3}   {2}   {1}   {0}   {3, 4, 5}   {1, 2, 5}  |
|-----------------------------------------------------------------------------|
|x      , x         , x      , x      , x         ]                           |
| {0, 5}   {0, 2, 4}   {1, 4}   {2, 3}   {0, 1, 3}                            |
+-----------------------------------------------------------------------------+

As seen from above, the output of idealChowRing, is an
Ideal (Macaulay2Doc), rather than a Ring (Macaulay2Doc).
One can get the ambient polynomial ring, as well as the
associated quotient ring:

+-------------------+
|i3 : R = ring I    |
|                   |
|o3 = R             |
|                   |
|o3 : PolynomialRing|
+-------------------+
|i4 : S = R/I       |
|                   |
|o4 = S             |
|                   |
|o4 : QuotientRing  |
+-------------------+

Next, one often wants to access and perform computations with elements in the
quotient ring. The variables in the ambient ring of the ideal of the Chow ring
are indexed by flats of the matroid, which retains useful information but makes
the variables themselves difficult to access. However, as with any ring in
Macaulay2, one can always access variables using subscripts:

+-------------------------------------------------------+
|i5 : R_0                                               |
|                                                       |
|o5 = x                                                 |
|      {5}                                              |
|                                                       |
|o5 : R                                                 |
+-------------------------------------------------------+
|i6 : S_1                                               |
|                                                       |
|o6 = x    - x          + x       - x       + x         |
|      {0}    {3, 4, 5}    {0, 5}    {1, 4}    {0, 1, 3}|
|                                                       |
|o6 : S                                                 |
+-------------------------------------------------------+
|i7 : S_5*S_6                                           |
|                                                       |
|o7 = 0                                                 |
|                                                       |
|o7 : S                                                 |
+-------------------------------------------------------+

Notice that elements of $S$ are already rewritten in the normal form modulo the
ideal of the Chow ring.

One can access the flat corresponding to a given variable as follows:

+----------------------+
|i8 : R_7              |
|                      |
|o8 = x                |
|      {1, 2, 5}       |
|                      |
|o8 : R                |
+----------------------+
|i9 : last baseName R_7|
|                      |
|o9 = {1, 2, 5}        |
|                      |
|o9 : List             |
+----------------------+

It is also possible to access variables via their flats by creating an
auxiliary HashTable (Macaulay2Doc),:

+-----------------------------------------------------------------------------+
|i10 : chowVars = hashTable apply(#gens R, i -> last baseName R_i => S_i)     |
|                                                                             |
|o10 = HashTable{{0, 1, 3} => x                                               |
|                              {0, 1, 3}                                      |
|                {0, 2, 4} => x                                               |
|                              {0, 2, 4}                                      |
|                {0, 5} => x                                                  |
|                           {0, 5}                                            |
|                {0} => x                                                     |
|                        {0}                                                  |
|                {1, 2, 5} => x                                               |
|                              {1, 2, 5}                                      |
|                {1, 4} => x                                                  |
|                           {1, 4}                                            |
|                {1} => x    - x          + x       + x          - x          |
|                        {0}    {1, 2, 5}    {0, 5}    {0, 2, 4}    {1, 4}    |
|                {2, 3} => x                                                  |
|                           {2, 3}                                            |
|                {2} => x    - x          + x       - x       + x             |
|                        {0}    {1, 2, 5}    {0, 5}    {2, 3}    {0, 1, 3}    |
|                {3, 4, 5} => x                                               |
|                              {3, 4, 5}                                      |
|                {3} => x    - x          + x       + x          - x          |
|                        {0}    {3, 4, 5}    {0, 5}    {0, 2, 4}    {2, 3}    |
|                {4} => x    - x          + x       - x       + x             |
|                        {0}    {3, 4, 5}    {0, 5}    {1, 4}    {0, 1, 3}    |
|                {5} => x    - x          - x          + x          + x       |
|                        {0}    {3, 4, 5}    {1, 2, 5}    {0, 2, 4}    {0, 1, |
|                                                                             |
|o10 : HashTable                                                              |
|-----------------------------------------------------------------------------|
|  }                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|3}                                                                           |
+-----------------------------------------------------------------------------+
|i11 : chowVars#{5} * chowVars#{0,5}                                          |
|                                                                             |
|        2                                                                    |
|o11 = -x                                                                     |
|        {0, 1, 3}                                                            |
|                                                                             |
|o11 : S                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * idealChowRing -- the defining ideal of the Chow ring