This is SimplicialComplexes.info, produced by Macaulay2, version 1.21

SimplicialComplexes -- exploring abstract simplicial complexes within commutative algebra
*****************************************************************************************

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

An abstract simplicial complex (see
https://en.wikipedia.org/wiki/Abstract_simplicial_complex ) is a family of
finite sets closed under the operation of taking subsets. In this package, the
finite set consists of variables in a polynomial ring (Macaulay2Doc),
and each subset is represented as a product of
the corresponding variables.  In other words, we exploit the natural bijection
between abstract simplicial complexes and Stanley-Reisner ideals (see
https://en.wikipedia.org/wiki/Stanley–Reisner_ring ).

This package is designed to explore applications of abstract simplicial
complexes within combinatorial commutative algebra. Introductions to this
theory can be found in the following textbooks:

  * Winfried Bruns (see https://www.home.uni-osnabrueck.de/wbruns/ ) and Jürgen
    Herzog (see https://en.wikipedia.org/wiki/Jürgen_Herzog ), Cohen-Macaulay
    rings (see https://www.cambridge.org/core/books/cohenmacaulay-rings/
    938BC2204D8A7C99E2CEBA1695A692A4 ), Cambridge Studies in Advanced
    Mathematics 39,Cambridge University Press, Cambridge, 1993. ISBN:
    0-521-41068-1
  * Ezra Miller (see https://services.math.duke.edu/~ezra/ ) and Bernd
    Sturmfels (see https://math.berkeley.edu/~bernd/ ), Combinatorial
    commutative algebra (see https://www.springer.com/gp/book/9780387223568 ),
    Graduate Texts in Mathematics 227, Springer-Verlag, New York, 2005. ISBN:
    0-387-22356-8
  * Irena Peeva (see http://pi.math.cornell.edu/~irena/ ), Graded Syzygies (see
    https://doi.org/10.1007/978-0-85729-177-6 ), Algebra and Applications 14,
    Springer-Verlag, London, 2011. ISBN: 978-0-85729-176-9
  * Richard Stanley (see http://www-math.mit.edu/~rstan/ ), Combinatorics and
    commutative algebra (see https://www.springer.com/gp/book/9780817643690 ),
    Progress in Mathematics 41, Birkhäuser Boston, Inc., Boston, MA, 1983.
    ISBN: 0-8176-3112-7

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

The following people have generously contributed code, improved existing code,
or enhanced the documentation: Janko Böhm (see
https://www.mathematik.uni-kl.de/~boehm/ ), Sorin Popescu (see
https://www.math.stonybrook.edu/~sorin/ ), Mike Stillman (see
http://www.math.cornell.edu/~mike/ ), and Lorenzo Venturello (see
https://www.mis.mpg.de/nlalg/nlalg-people/lorenzo-venturello.html ).

Caveat
======

This package is not intended to handle abstract simplicial complexes with a
very large number of vertices, because computations in the corresponding
polynomial ring are typically prohibitive.

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * Working with simplicial maps, --
    information about simplicial maps and the induced operations

Authors
=======

  * Gregory G. Smith (see http://www.mast.queensu.ca/~ggsmith )
    <ggsmith@mast.queensu.ca>
  * Ben Hersey <b.hersey@queensu.ca>
  * Alexandre Zotine <18az45@queensu.ca>

Version
=======

This documentation describes version 2.0 of SimplicialComplexes.

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

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

Exports
=======

  * Types
      * SimplicialComplex -- the class of all
        abstract simplicial complexes
      * SimplicialMap -- the class of all maps between
        simplicial complexes
  * Functions and commands
      * algebraicShifting -- the algebraic shifting
        of a simplicial complex
      * "bartnetteSphereComplex" -- see
        bartnetteSphereComplex(PolynomialRing),
        -- make a non-polytopal
        3-sphere with 8 vertices
      * "barycentricSubdivision" -- see
        barycentricSubdivision(SimplicialComplex,Ring),
        -- create the
        barycentric subdivision of a simplicial complex
      * "bjornerComplex" -- see bjornerComplex(PolynomialRing),
        -- make a shellable 2-polyhedron
        with 6 vertices
      * "boundaryMap" -- see boundaryMap(ZZ,SimplicialComplex),
        -- make a boundary map between
        the oriented faces of an abstract simplicial complex
      * buchbergerResolution -- make a Buchberger
        resolution of a monomial ideal
      * buchbergerSimplicialComplex -- make
        the Buchberger complex of a monomial ideal
      * "connectedComponents" -- see
        connectedComponents(SimplicialComplex),
        -- find the connected
        components of an abstract simplicial complex
      * "dunceHatComplex" -- see dunceHatComplex(PolynomialRing),
        -- make a realization of the dunce
        hat with 8 vertices
      * "elementaryCollapse" -- see
        elementaryCollapse(SimplicialComplex,RingElement),
        -- construct
        the elementary collapse of a free face in a simplicial complex
      * "flagfVector" -- see flagfVector(SimplicialComplex),
        -- compute the flag $f$-vector of
        an colored simplicial complex
      * "grunbaumBallComplex" -- see grunbaumBallComplex(PolynomialRing),
        -- make a nonshellable 3-ball
        with 14 vertices and 29 facets
      * "inducedSubcomplex" -- see
        inducedSubcomplex(SimplicialComplex,List),
        -- make the induced
        simplicial complex on a subset of vertices
      * "isProper" -- see isProper(SimplicialComplex),
        -- whether an abstract simplicial
        complex is properly colored
      * "kleinBottleComplex" -- see kleinBottleComplex(PolynomialRing),
        -- make a minimal triangulation
        of the Klein bottle
      * "link" -- see link(SimplicialComplex,RingElement),
        -- make the link of a face
        in an abstract simplicial complex
      * lyubeznikResolution -- create the Lyubeznik
        resolution of an ordered set of monomials.
      * lyubeznikSimplicialComplex -- create
        a simplicial complex supporting a Lyubeznik resolution of a monomial
        ideal
      * "nonPiecewiseLinearSphereComplex" -- see
        nonPiecewiseLinearSphereComplex(PolynomialRing),
        -- make a
        non-piecewise-linear 5-sphere with 18 vertices
      * "poincareSphereComplex" -- see
        poincareSphereComplex(PolynomialRing),
        -- make a homology 3-sphere
        with 16 vertices
      * "realProjectiveSpaceComplex" -- see
        realProjectiveSpaceComplex(ZZ,PolynomialRing),
        -- make a small
        triangulation of real projective space
      * "rudinBallComplex" -- see rudinBallComplex(PolynomialRing),
        -- make a nonshellable 3-ball
        with 14 vertices and 41 facets
      * scarfChainComplex -- create the Scarf chain
        complex for a list of monomials.
      * scarfSimplicialComplex -- create the
        Scarf simplicial complex for a list of monomials
      * "simplexComplex" -- see simplexComplex(ZZ,PolynomialRing),
        -- make the simplex as an
        abstract simplicial complex
      * "simplicialComplex" -- see simplicialComplex(List),
        -- make an abstract simplicial complex
        from a list of faces
      * "smallManifold" -- see smallManifold(ZZ,ZZ,ZZ,PolynomialRing),
        -- get a small
        manifold from the Frank Lutz database
      * "star" -- see star(SimplicialComplex,RingElement),
        -- make the star of a face
      * taylorResolution -- create the Taylor
        resolution of a monomial ideal
      * "wedge" -- see wedge(SimplicialComplex,SimplicialComplex, RingElement,RingElement),
        -- make the wedge sum of two abstract simplicial
        complexes
      * "zieglerBallComplex" -- see zieglerBallComplex(PolynomialRing),
        -- make a nonshellable 3-ball
        with 10 vertices and 21 facets
  * Methods
      * "algebraicShifting(SimplicialComplex)" -- see algebraicShifting,
        -- the algebraic shifting of a simplicial complex
      * bartnetteSphereComplex(PolynomialRing)
        -- make a non-polytopal
        3-sphere with 8 vertices
      * barycentricSubdivision(SimplicialComplex,Ring)
        -- create the
        barycentric subdivision of a simplicial complex
      * barycentricSubdivision(SimplicialMap,Ring,Ring)
        -- create the
        map between barycentric subdivisions corresponding to a simplicial map
      * bjornerComplex(PolynomialRing)
        -- make a shellable 2-polyhedron
        with 6 vertices
      * boundaryMap(ZZ,SimplicialComplex)
        -- make a boundary map between
        the oriented faces of an abstract simplicial complex
      * "buchbergerResolution(List)" -- see buchbergerResolution,
        -- make a Buchberger resolution of a monomial
        ideal
      * "buchbergerResolution(MonomialIdeal)" -- see
        buchbergerResolution, -- make a Buchberger
        resolution of a monomial ideal
      * "buchbergerSimplicialComplex(List,Ring)" -- see
        buchbergerSimplicialComplex, -- make the
        Buchberger complex of a monomial ideal
      * "buchbergerSimplicialComplex(MonomialIdeal,Ring)" -- see
        buchbergerSimplicialComplex, -- make the
        Buchberger complex of a monomial ideal
      * chainComplex(SimplicialComplex)
        -- create the chain complex
        associated to a simplicial complex.
      * chainComplex(SimplicialMap), --
        constructs the associated map between chain complexes
      * coefficientRing(SimplicialComplex)
        -- get the coefficient ring of
        the underlying polynomial ring
      * connectedComponents(SimplicialComplex)
        -- find the connected
        components of an abstract simplicial complex
      * dim(SimplicialComplex) -- find the
        dimension of an abstract simplicial complex
      * dual(SimplicialComplex) -- make the
        Alexander dual of an abstract simplicial complex
      * dunceHatComplex(PolynomialRing)
        -- make a realization of the dunce
        hat with 8 vertices
      * elementaryCollapse(SimplicialComplex,RingElement)
        -- construct
        the elementary collapse of a free face in a simplicial complex
      * faces(SimplicialComplex) -- get
        the list of faces for an abstract simplicial complex
      * faces(ZZ,SimplicialComplex),
        -- get the $i$-faces of an abstract simplicial complex
      * facets(SimplicialComplex) -- get
        the list of maximal faces
      * flagfVector(List,SimplicialComplex)
        -- compute a flag $f$-number
        of a colored simplicial complex
      * flagfVector(SimplicialComplex)
        -- compute the flag $f$-vector of
        an colored simplicial complex
      * fVector(SimplicialComplex), --
        compute the f-vector of an abstract simplicial complex
      * grunbaumBallComplex(PolynomialRing)
        -- make a nonshellable 3-ball
        with 14 vertices and 29 facets
      * HH SimplicialMap -- Compute the induced map on
        homology of a simplicial map.
      * "homology(Nothing,SimplicialMap)" -- see HH SimplicialMap,
        -- Compute the induced map on homology of a simplicial
        map.
      * HH^ZZ SimplicialMap -- Compute the induced
        map on cohomology of a simplicial map.
      * "HH^ZZ SimplicialComplex" -- see HH^ZZ(SimplicialComplex,Ring),
        -- compute the reduced cohomology
        of an abstract simplicial complex
      * HH^ZZ(SimplicialComplex,Ring)
        -- compute the reduced cohomology
        of an abstract simplicial complex
      * HH^ZZ(SimplicialComplex,SimplicialComplex)
        -- compute the
        relative homology of two simplicial complexes
      * HH_ZZ SimplicialMap -- Compute the
        induced map on homology of a simplicial map.
      * "HH_ZZ SimplicialComplex" -- see HH_ZZ(SimplicialComplex,Ring),
        -- compute the reduced homology
        of an abstract simplicial complex
      * HH_ZZ(SimplicialComplex,Ring)
        -- compute the reduced homology
        of an abstract simplicial complex
      * "HH SimplicialComplex" -- see homology(SimplicialComplex,Ring),
        -- compute the reduced homology
        of an abstract simplicial complex
      * "homology(Nothing,SimplicialComplex)" -- see
        homology(SimplicialComplex,Ring),
        -- compute the reduced homology
        of an abstract simplicial complex
      * "homology(Nothing,SimplicialComplex,Ring)" -- see
        homology(SimplicialComplex,Ring),
        -- compute the reduced homology
        of an abstract simplicial complex
      * homology(SimplicialComplex,Ring)
        -- compute the reduced homology
        of an abstract simplicial complex
      * "HH_ZZ(SimplicialComplex,SimplicialComplex)" -- see
        homology(SimplicialComplex,SimplicialComplex),
        -- compute the
        relative homology of two simplicial complexes
      * "homology(Nothing,SimplicialComplex,SimplicialComplex)" -- see
        homology(SimplicialComplex,SimplicialComplex),
        -- compute the
        relative homology of two simplicial complexes
      * homology(SimplicialComplex,SimplicialComplex)
        -- compute the
        relative homology of two simplicial complexes
      * ideal(SimplicialComplex) -- get
        the Stanley–Reisner ideal
      * image(SimplicialMap) -- construct the
        image of a simplicial map
      * inducedSubcomplex(SimplicialComplex,List)
        -- make the induced
        simplicial complex on a subset of vertices
      * isInjective(SimplicialMap), --
        checks if a simplicial map is injective
      * isProper(SimplicialComplex), --
        whether an abstract simplicial complex is properly colored
      * isPure(SimplicialComplex), --
        whether the facets are equidimensional
      * isSurjective(SimplicialMap), --
        checks if a simplicial map is surjective
      * isWellDefined(SimplicialComplex)
        -- whether underlying data is
        uncontradictory
      * isWellDefined(SimplicialMap),
        -- whether underlying data is uncontradictory
      * kleinBottleComplex(PolynomialRing)
        -- make a minimal triangulation
        of the Klein bottle
      * link(SimplicialComplex,RingElement)
        -- make the link of a face
        in an abstract simplicial complex
      * "lyubeznikResolution(List)" -- see lyubeznikResolution,
        -- create the Lyubeznik resolution of an ordered
        set of monomials.
      * "lyubeznikResolution(MonomialIdeal)" -- see lyubeznikResolution,
        -- create the Lyubeznik resolution of an ordered
        set of monomials.
      * "lyubeznikSimplicialComplex(List,Ring)" -- see
        lyubeznikSimplicialComplex, -- create a
        simplicial complex supporting a Lyubeznik resolution of a monomial
        ideal
      * "lyubeznikSimplicialComplex(MonomialIdeal,Ring)" -- see
        lyubeznikSimplicialComplex, -- create a
        simplicial complex supporting a Lyubeznik resolution of a monomial
        ideal
      * "map(SimplicialComplex,List)" -- see
        map(SimplicialComplex,SimplicialComplex,Matrix),
        -- create a
        simplicial map between simplicial complexes
      * "map(SimplicialComplex,Matrix)" -- see
        map(SimplicialComplex,SimplicialComplex,Matrix),
        -- create a
        simplicial map between simplicial complexes
      * "map(SimplicialComplex,RingMap)" -- see
        map(SimplicialComplex,SimplicialComplex,Matrix),
        -- create a
        simplicial map between simplicial complexes
      * "map(SimplicialComplex,SimplicialComplex,List)" -- see
        map(SimplicialComplex,SimplicialComplex,Matrix),
        -- create a
        simplicial map between simplicial complexes
      * map(SimplicialComplex,SimplicialComplex,Matrix)
        -- create a
        simplicial map between simplicial complexes
      * "map(SimplicialComplex,SimplicialComplex,RingMap)" -- see
        map(SimplicialComplex,SimplicialComplex,Matrix),
        -- create a
        simplicial map between simplicial complexes
      * map(SimplicialMap) -- the underlying
        ring map associated to a simplicial map
      * matrix(SimplicialMap) -- get the
        underlying map of rings
      * monomialIdeal(SimplicialComplex)
        -- get the Stanley–Reisner
        monomial ideal
      * net(SimplicialComplex) -- make a
        symbolic representation of an abstract simplicial complex
      * net(SimplicialMap) -- make a symbolic
        representation for a map of abstract simplicial complexes
      * nonPiecewiseLinearSphereComplex(PolynomialRing)
        -- make a
        non-piecewise-linear 5-sphere with 18 vertices
      * poincareSphereComplex(PolynomialRing)
        -- make a homology 3-sphere
        with 16 vertices
      * prune(SimplicialComplex) -- make a
        minimal presentation of an abstract simplicial complex
      * realProjectiveSpaceComplex(ZZ,PolynomialRing)
        -- make a small
        triangulation of real projective space
      * ring(SimplicialComplex) -- get the
        polynomial ring of its Stanley–Reisner ideal
      * rudinBallComplex(PolynomialRing)
        -- make a nonshellable 3-ball
        with 14 vertices and 41 facets
      * "scarfChainComplex(List)" -- see scarfChainComplex,
        -- create the Scarf chain complex for a list of
        monomials.
      * "scarfChainComplex(MonomialIdeal)" -- see scarfChainComplex,
        -- create the Scarf chain complex for a list of
        monomials.
      * "scarfSimplicialComplex(List,Ring)" -- see
        scarfSimplicialComplex, -- create the Scarf
        simplicial complex for a list of monomials
      * "scarfSimplicialComplex(MonomialIdeal,Ring)" -- see
        scarfSimplicialComplex, -- create the Scarf
        simplicial complex for a list of monomials
      * simplexComplex(ZZ,PolynomialRing)
        -- make the simplex as an
        abstract simplicial complex
      * SimplicialComplex * SimplicialComplex
        -- make the join for two abstract simplicial
        complexes
      * simplicialComplex(List) -- make an
        abstract simplicial complex from a list of faces
      * "simplicialComplex(Matrix)" -- see simplicialComplex(List),
        -- make an abstract simplicial complex
        from a list of faces
      * "simplicialComplex(Ideal)" -- see
        simplicialComplex(MonomialIdeal),
        -- make a simplicial complex from its Stanley–Reisner ideal
      * simplicialComplex(MonomialIdeal)
        -- make a simplicial complex from
        its Stanley–Reisner ideal
      * skeleton(ZZ,SimplicialComplex)
        -- make a new simplicial complex
        generated by all faces of a bounded dimension
      * smallManifold(ZZ,ZZ,ZZ,PolynomialRing)
        -- get a small
        manifold from the Frank Lutz database
      * source(SimplicialMap) -- get the
        source of the map
      * star(SimplicialComplex,RingElement)
        -- make the star of a face
      * substitute(SimplicialComplex,PolynomialRing)
        -- change the ring
        of a simplicial complex
      * target(SimplicialMap) -- get the
        target of the map
      * "taylorResolution(List)" -- see taylorResolution,
        -- create the Taylor resolution of a monomial ideal
      * "taylorResolution(MonomialIdeal)" -- see taylorResolution,
        -- create the Taylor resolution of a monomial ideal
      * vertices(SimplicialComplex), --
        get the list of the vertices for an abstract simplicial complex
      * wedge(SimplicialComplex,SimplicialComplex,RingElement,RingElement )
        -- make the wedge sum of two abstract simplicial
        complexes
      * zieglerBallComplex(PolynomialRing)
        -- make a nonshellable 3-ball
        with 10 vertices and 21 facets
  * Symbols
      * "Labels" -- see chainComplex(SimplicialComplex),
        -- create the chain complex
        associated to a simplicial complex.

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

The object SimplicialComplexes, is a package (Macaulay2Doc).

algebraicShifting -- the algebraic shifting of a simplicial complex
*******************************************************************

Synopsis
========

  * Usage:
        A = algebraicShifting D
  * Inputs:
      * D, an abstract simplicial complex,
  * Optional inputs (Macaulay2Doc),:
      * Multigrading => a Boolean value (Macaulay2Doc), default
        value false, which, if true, returns the colored algebraic shifting
        with respect to the multigrading of the underlying ring.
  * Outputs:
      * A, an abstract simplicial complex, which is
        the algebraic shifting of D. If Multigrading is true, then it returns
        the so-called colored shifted complex.

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

The boundary of the stacked 4-polytope on 6 vertices. Algebraic shifting
preserves the f-vector.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_6];                                                       |
+-----------------------------------------------------------------------------+
|i2 : I = monomialIdeal(x_2*x_3*x_4*x_5, x_1*x_6);                            |
|                                                                             |
|o2 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i3 : stacked = simplicialComplex I                                           |
|                                                                             |
|o3 = simplicialComplex | x_3x_4x_5x_6 x_2x_4x_5x_6 x_2x_3x_5x_6 x_2x_3x_4x_6 |
|                                                                             |
|o3 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_1x_3x_4x_5 x_1x_2x_4x_5 x_1x_2x_3x_5 x_1x_2x_3x_4 |                        |
+-----------------------------------------------------------------------------+
|i4 : shifted = algebraicShifting stacked                                     |
|                                                                             |
|o4 = simplicialComplex | x_3x_4x_5x_6 x_2x_4x_5x_6 x_1x_4x_5x_6 x_2x_3x_5x_6 |
|                                                                             |
|o4 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_1x_3x_5x_6 x_2x_3x_4x_6 x_1x_3x_4x_6 x_2x_3x_4x_5 |                        |
+-----------------------------------------------------------------------------+
|i5 : fVector stacked                                                         |
|                                                                             |
|o5 = {1, 6, 14, 16, 8}                                                       |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : fVector shifted                                                         |
|                                                                             |
|o6 = {1, 6, 14, 16, 8}                                                       |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

An empty triangle is a shifted complex.

+-------------------------------------------------+
|i7 : R' = QQ[a,b,c];                             |
+-------------------------------------------------+
|i8 : triangle = simplicialComplex {a*b, b*c, a*c}|
|                                                 |
|o8 = simplicialComplex | bc ac ab |              |
|                                                 |
|o8 : SimplicialComplex                           |
+-------------------------------------------------+
|i9 : algebraicShifting triangle === triangle     |
|                                                 |
|o9 = true                                        |
+-------------------------------------------------+

The multigraded algebraic shifting does not preserve the Betti numbers.

+-----------------------------------------------------------------------------+
|i10 : grading = {{1,0,0}, {1,0,0}, {1,0,0}, {0,1,0}, {0,0,1}};               |
+-----------------------------------------------------------------------------+
|i11 : R = QQ[x_{1,1}, x_{1,2}, x_{1,3}, x_{2,1}, x_{3,1}, Degrees =>         |
|-----------------------------------------------------------------------------|
|grading];                                                                    |
+-----------------------------------------------------------------------------+
|i12 : delta = simplicialComplex({x_{1,3}*x_{2,1}*x_{3,1}, x_{1,1}*x_{2,1}, x |
|                                                                             |
|o12 = simplicialComplex | x_{1, 2}x_{3, 1} x_{1, 1}x_{2, 1} x_{1, 3}x_{2, 1} |
|                                                                             |
|o12 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|_{1,2}*x_{3,1}})                                                             |
|                                                                             |
|x_{3, 1} |                                                                   |
+-----------------------------------------------------------------------------+
|i13 : shifted = algebraicShifting(delta, Multigrading => true)               |
|                                                                             |
|o13 = simplicialComplex | x_{1, 1} x_{1, 2}x_{3, 1} x_{1, 2}x_{2, 1} x_{1,   |
|                                                                             |
|o13 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|3}x_{2, 1}x_{3, 1} |                                                         |
+-----------------------------------------------------------------------------+
|i14 : prune (homology(delta))_1                                              |
|                                                                             |
|o14 = 0                                                                      |
|                                                                             |
|o14 : QQ-module                                                              |
+-----------------------------------------------------------------------------+
|i15 : prune (homology(shifted))_1                                            |
|                                                                             |
|        1                                                                    |
|o15 = QQ                                                                     |
|                                                                             |
|o15 : QQ-module, free                                                        |
+-----------------------------------------------------------------------------+

References:

G. Kalai, Algebraic Shifting, Computational Commutative Algebra and
Combinatorics, 2001;

S. Murai, Betti numbers of strongly color-stable ideals and squarefree strongly
color-stable ideals, Journal of Algebraic Combinatorics.

Ways to use algebraicShifting :
===============================

  * "algebraicShifting(SimplicialComplex)"

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

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

bartnetteSphereComplex(PolynomialRing) -- make a non-polytopal 3-sphere with 8 vertices
***************************************************************************************

Synopsis
========

  * Function: bartnetteSphereComplex,
  * Usage:
        bartnetteSphereComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that has at
        least 8 generators
  * Outputs:
      * an abstract simplicial complex,

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

First described by David Barnette's "Diagrams and Schlegel diagrams" appearing
in Combinatorial Structures and their Applications, (Proc. Calgary Internat.
Conf. 1969, pp 1-4), Gordon and Breach, New York, 1970, this method returns a
pure abstract simplicial complex of dimension 3 with 8 vertices and 19 facets.
It is smallest possible non-polytopal simplicial 3-sphere.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[a..h];                                                           |
+-----------------------------------------------------------------------------+
|i2 : Δ = bartnetteSphereComplex S;                                           |
+-----------------------------------------------------------------------------+
|i3 : matrix {facets Δ}                                                       |
|                                                                             |
|o3 = | defh befh cdfh bcfh adeh abeh acdh abch defg cefg adfg acfg bdeg bceg |
|     ------------------------------------------------------------------------|
|     abdg abcg bcef acdf abde |                                              |
|                                                                             |
|             1       19                                                      |
|o3 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i4 : dim Δ                                                                   |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : fVector Δ                                                               |
|                                                                             |
|o5 = {1, 8, 27, 38, 19}                                                      |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : assert(dim Δ === 3 and isPure Δ)                                        |
+-----------------------------------------------------------------------------+
|i7 : assert(ideal Δ === ideal(b*c*d, a*c*e, c*d*e, a*b*f, b*d*f, a*e*f,      |
|             c*d*g, a*e*g, b*f*g, b*d*h, c*e*h, a*f*h, g*h))                 |
+-----------------------------------------------------------------------------+
|i8 : assert(fVector Δ === {1,8,27,38,19})                                    |
+-----------------------------------------------------------------------------+

The vertices in the Bartnette sphere will correspond to the first 8 variables
of the input polynomial ring.

+-----------------------------------------------------------------------------+
|i9 : R = QQ[x_0..x_10];                                                      |
+-----------------------------------------------------------------------------+
|i10 : Γ = bartnetteSphereComplex R;                                          |
+-----------------------------------------------------------------------------+
|i11 : monomialIdeal Γ                                                        |
|                                                                             |
|o11 = monomialIdeal (x x x , x x x , x x x , x x x , x x x , x x x , x x x , |
|                      1 2 3   0 2 4   2 3 4   0 1 5   1 3 5   0 4 5   2 3 6  |
|      -----------------------------------------------------------------------|
|      x x x , x x x , x x x , x x x , x x x , x x , x , x , x  )             |
|       0 4 6   1 5 6   1 3 7   2 4 7   0 5 7   6 7   8   9   10              |
|                                                                             |
|o11 : MonomialIdeal of R                                                     |
+-----------------------------------------------------------------------------+
|i12 : assert(dim Γ === 3 and isPure Γ)                                       |
+-----------------------------------------------------------------------------+

Our enumeration of the vertices follows Example 9.5.23 in Jesús A De Loera,
Jörg Rambau, and Francisco Santos, Triangulations, structures for algorithms
and applications (see https://www.springer.com/gp/book/9783642129704 ),
Algorithms and Computation in Mathematics 25, Springer-Verlag, Berlin, 2010.

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional
  * poincareSphereComplex(PolynomialRing)
    -- make a homology 3-sphere with
    16 vertices

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

  * bartnetteSphereComplex(PolynomialRing)
    -- make a non-polytopal
    3-sphere with 8 vertices

barycentricSubdivision(SimplicialComplex,Ring) -- create the barycentric subdivision of a simplicial complex
************************************************************************************************************

Synopsis
========

  * Function: barycentricSubdivision,
  * Usage:
        barycentricSubdivision(D,R)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * R, a ring (Macaulay2Doc), the ambient ring for the
        barycentric subdivision of $D$
  * Outputs:
      * an abstract simplicial complex, the
        barycentric subdivision of $D$

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

If $\Delta$ is an abstract simplicial complex, the barycentric subdivision of
$\Delta$ is the abstract simplicial complex whose ground set (vertices) is the
set of faces of $D$ and whose faces correspond to sequences $\{(F_0, F_1,
\ldots, F_k)\}$ where $F_i$ is an $i$-dimensional face containing $F_{i-1}$. In
order to understand how the data of the barycentric subdivision is organized,
we work through a simple example.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_0..x_2];                                                       |
+-----------------------------------------------------------------------------+
|i2 : S = QQ[y_0..y_6];                                                       |
+-----------------------------------------------------------------------------+
|i3 : Δ = simplexComplex(2, R)                                                |
|                                                                             |
|o3 = simplicialComplex | x_0x_1x_2 |                                         |
|                                                                             |
|o3 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i4 : Γ = barycentricSubdivision(Δ, S)                                        |
|                                                                             |
|o4 = simplicialComplex | y_2y_5y_6 y_1y_5y_6 y_2y_4y_6 y_0y_4y_6 y_1y_3y_6   |
|                                                                             |
|o4 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|y_0y_3y_6 |                                                                  |
+-----------------------------------------------------------------------------+
|i5 : ΓFacets = facets Γ                                                      |
|                                                                             |
|o5 = {y y y , y y y , y y y , y y y , y y y , y y y }                        |
|       2 5 6   1 5 6   2 4 6   0 4 6   1 3 6   0 3 6                         |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

To make sense of the facets of the barycentric subdivision, we order the faces
of $\Delta$ as follows.

+---------------------------------------------------------+
|i6 : ΔFaces = flatten for i to 1 + dim Δ list faces(i, Δ)|
|                                                         |
|o6 = {x , x , x , x x , x x , x x , x x x }              |
|       0   1   2   0 1   0 2   1 2   0 1 2               |
|                                                         |
|o6 : List                                                |
+---------------------------------------------------------+

The indices of the variables appearing in each monomial (or facet) $F$ in the
facets of $\Gamma$ determines a sequence of monomials (faces) in $\Delta$.

+----------------------------------------------------------+
|i7 : netList for F in ΓFacets list F => ΔFaces_(indices F)|
|                                                          |
|     +----------------------------+                       |
|o7 = |y y y  => {x , x x , x x x }|                       |
|     | 2 5 6      2   1 2   0 1 2 |                       |
|     +----------------------------+                       |
|     |y y y  => {x , x x , x x x }|                       |
|     | 1 5 6      1   1 2   0 1 2 |                       |
|     +----------------------------+                       |
|     |y y y  => {x , x x , x x x }|                       |
|     | 2 4 6      2   0 2   0 1 2 |                       |
|     +----------------------------+                       |
|     |y y y  => {x , x x , x x x }|                       |
|     | 0 4 6      0   0 2   0 1 2 |                       |
|     +----------------------------+                       |
|     |y y y  => {x , x x , x x x }|                       |
|     | 1 3 6      1   0 1   0 1 2 |                       |
|     +----------------------------+                       |
|     |y y y  => {x , x x , x x x }|                       |
|     | 0 3 6      0   0 1   0 1 2 |                       |
|     +----------------------------+                       |
+----------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * barycentricSubdivision(SimplicialMap,Ring,Ring)
    -- create the map
    between barycentric subdivisions corresponding to a simplicial map

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

  * barycentricSubdivision(SimplicialComplex,Ring)
    -- create the
    barycentric subdivision of a simplicial complex

barycentricSubdivision(SimplicialMap,Ring,Ring) -- create the map between barycentric subdivisions corresponding to a simplicial map
************************************************************************************************************************************

Synopsis
========

  * Function: barycentricSubdivision,
  * Usage:
        barycentricSubdivision(f, R, S)
  * Inputs:
      * f, a map of abstract simplicial complexes, from
        the simplicial complex $D$ to the simplicial complex $E$
      * R, a ring (Macaulay2Doc), the ambient ring for the
        barycentric subdivision of $E$
      * S, a ring (Macaulay2Doc), the ambient ring for the
        barycentric subdivision of $D$
  * Outputs:
      * a map of abstract simplicial complexes, from the
        barycentric subdivision of $D$ to the barycentric subdivision of $E$.

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

The vertices of the barycentric subdivision of $D$ correspond to faces of $D$.
For every face $F$ in $D$, $\operatorname{barycentricSubdivision} (f,R,S)$ maps
the vertex corresponding to $F$ in the barycentric subdivision of $D$ to the
vertex corresponding to $f(F)$ in the barycentric subdivision of $E$. We work
out these correspondences, and the resulting simplicial map between barycentric
subdivisions in the example below.

+-----------------------------------------------------------------------------+
|i1 : T = ZZ/2[x_0,x_1,x_2];                                                  |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex{T_1*T_2}                                          |
|                                                                             |
|o2 = simplicialComplex | x_1x_2 |                                            |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : Γ = simplicialComplex{T_0*T_1}                                          |
|                                                                             |
|o3 = simplicialComplex | x_0x_1 |                                            |
|                                                                             |
|o3 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i4 : f = map(Γ, Δ, reverse gens T)                                           |
|                                                                             |
|o4 = | x_2 x_1 x_0 |                                                         |
|                                                                             |
|o4 : SimplicialMap simplicialComplex | x_0x_1 | <--- simplicialComplex |     |
|-----------------------------------------------------------------------------|
|x_1x_2 |                                                                     |
+-----------------------------------------------------------------------------+

The barycentric subdivisions of $D$, $E$, and $f$ are:

+-----------------------------------------------------------------------------+
|i5 : R = ZZ/2[y_0..y_2];                                                     |
+-----------------------------------------------------------------------------+
|i6 : S = ZZ/2[z_0..z_2];                                                     |
+-----------------------------------------------------------------------------+
|i7 : BΔ = barycentricSubdivision(Δ, R)                                       |
|                                                                             |
|o7 = simplicialComplex | y_1y_2 y_0y_2 |                                     |
|                                                                             |
|o7 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i8 : BΓ = barycentricSubdivision(Γ, S)                                       |
|                                                                             |
|o8 = simplicialComplex | z_1z_2 z_0z_2 |                                     |
|                                                                             |
|o8 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i9 : Bf = barycentricSubdivision(f, S, R)                                    |
|                                                                             |
|o9 = | z_1 z_0 z_2 |                                                         |
|                                                                             |
|o9 : SimplicialMap simplicialComplex | z_1z_2 z_0z_2 | <--- simplicialComplex|
|-----------------------------------------------------------------------------|
|| y_1y_2 y_0y_2 |                                                            |
+-----------------------------------------------------------------------------+

In order to understand the data for $Bf$, we first look at the correspondence
between the faces of $\Delta$, $\Gamma$, and the vertices of $B\Delta$,
$B\Gamma$, respectively.

+-------------------------------------------------------------------------+
|i10 : ΔFaces = flatten for i to dim Δ + 1 list faces(i, Δ)               |
|                                                                         |
|o10 = {x , x , x x }                                                     |
|        1   2   1 2                                                      |
|                                                                         |
|o10 : List                                                               |
+-------------------------------------------------------------------------+
|i11 : ΓFaces = flatten for i to dim Γ + 1 list faces(i, Γ)               |
|                                                                         |
|o11 = {x , x , x x }                                                     |
|        0   1   0 1                                                      |
|                                                                         |
|o11 : List                                                               |
+-------------------------------------------------------------------------+
|i12 : netList transpose {for y in vertices BΔ list y => ΔFaces_(index y),|
|          for z in vertices BΓ list z => ΓFaces_(index z)}               |
|                                                                         |
|      +----------+----------+                                            |
|o12 = |y  => x   |z  => x   |                                            |
|      | 0     1  | 0     0  |                                            |
|      +----------+----------+                                            |
|      |y  => x   |z  => x   |                                            |
|      | 1     2  | 1     1  |                                            |
|      +----------+----------+                                            |
|      |y  => x x |z  => x x |                                            |
|      | 2     1 2| 2     0 1|                                            |
|      +----------+----------+                                            |
+-------------------------------------------------------------------------+

These correspondences, together the images of each face of $D$ under $f$, will
completely determine the map $Bf$.

+-----------------------------------------------------------------------------+
|i13 : netList transpose {for F in ΔFaces list F => (map f)(F),               |
|          for v in vertices BΔ list v => (map Bf)(v) }                       |
|                                                                             |
|      +------------+--------+                                                |
|o13 = |x  => x     |y  => z |                                                |
|      | 1     1    | 0     1|                                                |
|      +------------+--------+                                                |
|      |x  => x     |y  => z |                                                |
|      | 2     0    | 1     0|                                                |
|      +------------+--------+                                                |
|      |x x  => x x |y  => z |                                                |
|      | 1 2     0 1| 2     2|                                                |
|      +------------+--------+                                                |
+-----------------------------------------------------------------------------+
|i14 : Bf                                                                     |
|                                                                             |
|o14 = | z_1 z_0 z_2 |                                                        |
|                                                                             |
|o14 : SimplicialMap simplicialComplex | z_1z_2 z_0z_2 | <---                 |
|-----------------------------------------------------------------------------|
|simplicialComplex | y_1y_2 y_0y_2 |                                          |
+-----------------------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * barycentricSubdivision(SimplicialComplex,Ring)
    -- create the
    barycentric subdivision of a simplicial complex
  * SimplicialComplex -- the class of all abstract
    simplicial complexes

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

  * barycentricSubdivision(SimplicialMap,Ring,Ring)
    -- create the map
    between barycentric subdivisions corresponding to a simplicial map

bjornerComplex(PolynomialRing) -- make a shellable 2-polyhedron with 6 vertices
*******************************************************************************

Synopsis
========

  * Function: bjornerComplex,
  * Usage:
        bjornerComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that has at
        least 6 generators
  * Outputs:
      * an abstract simplicial complex,

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

Attributed to Anders Björner (see https://en.wikipedia.org/wiki/Anders_Björner
), this method returns a shellable (see
https://en.wikipedia.org/wiki/Shelling_(topology) ) abstract simplicial complex
which has non-zero homology.

+----------------------------------------------------------------------+
|i1 : S = ZZ/101[a..f];                                                |
+----------------------------------------------------------------------+
|i2 : Δ = bjornerComplex S                                             |
|                                                                      |
|o2 = simplicialComplex | def cef bdf acf abf ade bce abe bcd acd abc ||
|                                                                      |
|o2 : SimplicialComplex                                                |
+----------------------------------------------------------------------+
|i3 : dim Δ                                                            |
|                                                                      |
|o3 = 2                                                                |
+----------------------------------------------------------------------+
|i4 : fVector Δ                                                        |
|                                                                      |
|o4 = {1, 6, 15, 11}                                                   |
|                                                                      |
|o4 : List                                                             |
+----------------------------------------------------------------------+
|i5 : assert(dim Δ === 2 and isPure Δ)                                 |
+----------------------------------------------------------------------+
|i6 : assert(fVector Δ === {1,6,15,11})                                |
+----------------------------------------------------------------------+
|i7 : prune HH chainComplex Δ                                          |
|                                                                      |
|o7 = -1 : 0                                                           |
|                                                                      |
|      0 : 0                                                           |
|                                                                      |
|      1 : 0                                                           |
|                                                                      |
|            ZZ 1                                                      |
|      2 : (---)                                                       |
|           101                                                        |
|                                                                      |
|o7 : GradedModule                                                     |
+----------------------------------------------------------------------+

This abstract simplicial complex is Cohen-Macaulay and shellable.

A shellable abstract simplicial complex $\Delta$ is extendably shellable if any
shelling of a subcomplex can be extended to a shelling of $\Delta$. The Björner
complex is not extendably shellable.

Our enumeration of the vertices follows the bjorner (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/bjorner_eng.html )
example in Masahiro Hachimori's simplicial complex library (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/index_eng.html ).

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * rudinBallComplex -- make a
    nonshellable 3-ball with 14 vertices and 41 facets
  * grunbaumBallComplex -- make
    a nonshellable 3-ball with 14 vertices and 29 facets
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional

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

  * bjornerComplex(PolynomialRing),
    -- make a shellable 2-polyhedron with 6 vertices

boundaryMap(ZZ,SimplicialComplex) -- make a boundary map between the oriented faces of an abstract simplicial complex
*********************************************************************************************************************

Synopsis
========

  * Function: boundaryMap,
  * Usage:
        boundaryMap(i, Delta)
  * Inputs:
      * i, an integer (Macaulay2Doc), specifying the dimension of
        faces in the source of the map
      * Delta, an abstract simplicial complex,
  * Optional inputs (Macaulay2Doc),:
      * Labels => a list (Macaulay2Doc), default value {}, of
        monomials in a polynomial ring, one for each vertex of $\Delta$
  * Outputs:
      * a matrix (Macaulay2Doc), that determines a map from
        $i$-faces to $i-1$-faces of $\Delta$

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

Up to sign, the boundary maps form the differential in the chain complex
associated to an abstract simplicial complex.  The columns of the output matrix
are indexed by the $i$-faces of the abstract simplicial complex $\Delta$ and
the rows are indexed by the $(i-1)$-faces.  The order of these indices is
obtained from the faces, method which
is implicitly determined by the monomial order on the underlying ring.
The matrix is defined over the coefficient ring,
of $\Delta$ and its entries in
this matrix are $-1$, $0$,or $1$ depending on whether the row index is an
oriented face of the column index.  The orientation of $\Delta$ is induced by
the ordering of the variables in its underlying ring.

Working over the integers, we have the boundary maps for the standard
$3$-simplex.

+------------------------------------------------------+
|i1 : R = ZZ[a..d];                                    |
+------------------------------------------------------+
|i2 : Δ = simplicialComplex {a*b*c*d}                  |
|                                                      |
|o2 = simplicialComplex | abcd |                       |
|                                                      |
|o2 : SimplicialComplex                                |
+------------------------------------------------------+
|i3 : boundaryMap(0, Δ)                                |
|                                                      |
|o3 = | 1 1 1 1 |                                      |
|                                                      |
|              1        4                              |
|o3 : Matrix ZZ  <--- ZZ                               |
+------------------------------------------------------+
|i4 : boundaryMap(1, Δ)                                |
|                                                      |
|o4 = | -1 -1 -1 0  0  0  |                            |
|     | 1  0  0  -1 -1 0  |                            |
|     | 0  1  0  1  0  -1 |                            |
|     | 0  0  1  0  1  1  |                            |
|                                                      |
|              4        6                              |
|o4 : Matrix ZZ  <--- ZZ                               |
+------------------------------------------------------+
|i5 : boundaryMap(2, Δ)                                |
|                                                      |
|o5 = | 1  1  0  0  |                                  |
|     | -1 0  1  0  |                                  |
|     | 0  -1 -1 0  |                                  |
|     | 1  0  0  1  |                                  |
|     | 0  1  0  -1 |                                  |
|     | 0  0  1  1  |                                  |
|                                                      |
|              6        4                              |
|o5 : Matrix ZZ  <--- ZZ                               |
+------------------------------------------------------+
|i6 : boundaryMap(3, Δ)                                |
|                                                      |
|o6 = | -1 |                                           |
|     | 1  |                                           |
|     | -1 |                                           |
|     | 1  |                                           |
|                                                      |
|              4        1                              |
|o6 : Matrix ZZ  <--- ZZ                               |
+------------------------------------------------------+
|i7 : fVector Δ                                        |
|                                                      |
|o7 = {1, 4, 6, 4, 1}                                  |
|                                                      |
|o7 : List                                             |
+------------------------------------------------------+
|i8 : C = chainComplex Δ                               |
|                                                      |
|       1       4       6       4       1              |
|o8 = ZZ  <-- ZZ  <-- ZZ  <-- ZZ  <-- ZZ               |
|                                                      |
|     -1      0       1       2       3                |
|                                                      |
|o8 : ChainComplex                                     |
+------------------------------------------------------+
|i9 : assert all(4, i -> C.dd_i == - boundaryMap(i, Δ))|
+------------------------------------------------------+

The boundary maps may depend on the coefficient ring.

+-----------------------------+
|i10 : R' = ZZ/2[a..d];       |
+-----------------------------+
|i11 : Δ' = sub(Δ, R');       |
+-----------------------------+
|i12 : boundaryMap(0, Δ')     |
|                             |
|o12 = | 1 1 1 1 |            |
|                             |
|              ZZ 1       ZZ 4|
|o12 : Matrix (--)  <--- (--) |
|               2          2  |
+-----------------------------+
|i13 : boundaryMap(1, Δ')     |
|                             |
|o13 = | 1 1 1 0 0 0 |        |
|      | 1 0 0 1 1 0 |        |
|      | 0 1 0 1 0 1 |        |
|      | 0 0 1 0 1 1 |        |
|                             |
|              ZZ 4       ZZ 6|
|o13 : Matrix (--)  <--- (--) |
|               2          2  |
+-----------------------------+
|i14 : boundaryMap(2, Δ')     |
|                             |
|o14 = | 1 1 0 0 |            |
|      | 1 0 1 0 |            |
|      | 0 1 1 0 |            |
|      | 1 0 0 1 |            |
|      | 0 1 0 1 |            |
|      | 0 0 1 1 |            |
|                             |
|              ZZ 6       ZZ 4|
|o14 : Matrix (--)  <--- (--) |
|               2          2  |
+-----------------------------+
|i15 : boundaryMap(3, Δ')     |
|                             |
|o15 = | 1 |                  |
|      | 1 |                  |
|      | 1 |                  |
|      | 1 |                  |
|                             |
|              ZZ 4       ZZ 1|
|o15 : Matrix (--)  <--- (--) |
|               2          2  |
+-----------------------------+

When the optional argument Labels is given a list of monomials, corresponding
to the vertices of $\Delta$, this method returns the differential in a chain
complex of free modules.  Each face, or basis vector, is labelled by the least
common multiple of the labels on its vertices.  In other words, the chain
complex associated to a labelled simplicial complex is the homogenization of
the canonical chain complex associated to $\Delta$; see Chapter 4 in
Miller-Sturmfels' Combinatorial Commutative Algebra or Section 55 in Irena
Peeva's Graded Syzygies.

Labelling the vertices in the standard $3$-simplex by its unique monomial
generators, we obtain the differential in the Taylor resolution of a monomial
ideal.

+-----------------------------------------------------------------------------+
|i16 : S = ZZ/101[x_0, x_1];                                                  |
+-----------------------------------------------------------------------------+
|i17 : M = monomialIdeal(x_1^3, x_0*x_1^2, x_0^2*x_1, x_0^3);                 |
|                                                                             |
|o17 : MonomialIdeal of S                                                     |
+-----------------------------------------------------------------------------+
|i18 : boundaryMap(0, Δ,  Labels => sort M_*)                                 |
|                                                                             |
|o18 = | x_1^3 x_0x_1^2 x_0^2x_1 x_0^3 |                                      |
|                                                                             |
|              1       4                                                      |
|o18 : Matrix S  <--- S                                                       |
+-----------------------------------------------------------------------------+
|i19 : boundaryMap(1, Δ,  Labels => sort M_*)                                 |
|                                                                             |
|o19 = {3} | -x_0 -x_0^2 -x_0^3 0    0      0    |                            |
|      {3} | x_1  0      0      -x_0 -x_0^2 0    |                            |
|      {3} | 0    x_1^2  0      x_1  0      -x_0 |                            |
|      {3} | 0    0      x_1^3  0    x_1^2  x_1  |                            |
|                                                                             |
|              4       6                                                      |
|o19 : Matrix S  <--- S                                                       |
+-----------------------------------------------------------------------------+
|i20 : boundaryMap(2, Δ,  Labels => sort M_*)                                 |
|                                                                             |
|o20 = {4} | x_0 x_0^2 0     0   |                                            |
|      {5} | -1  0     x_0   0   |                                            |
|      {6} | 0   -1    -1    0   |                                            |
|      {4} | x_1 0     0     x_0 |                                            |
|      {5} | 0   x_1   0     -1  |                                            |
|      {4} | 0   0     x_1^2 x_1 |                                            |
|                                                                             |
|              6       4                                                      |
|o20 : Matrix S  <--- S                                                       |
+-----------------------------------------------------------------------------+
|i21 : boundaryMap(3, Δ,  Labels => sort M_*)                                 |
|                                                                             |
|o21 = {5} | -x_0 |                                                           |
|      {6} | 1    |                                                           |
|      {6} | -1   |                                                           |
|      {5} | x_1  |                                                           |
|                                                                             |
|              4       1                                                      |
|o21 : Matrix S  <--- S                                                       |
+-----------------------------------------------------------------------------+
|i22 : T = taylorResolution M                                                 |
|                                                                             |
|       1      4      6      4      1                                         |
|o22 = S  <-- S  <-- S  <-- S  <-- S                                          |
|                                                                             |
|      0      1      2      3      4                                          |
|                                                                             |
|o22 : ChainComplex                                                           |
+-----------------------------------------------------------------------------+
|i23 : T.dd                                                                   |
|                                                                             |
|           1                                         4                       |
|o23 = 0 : S  <------------------------------------- S  : 1                   |
|                | x_1^3 x_0x_1^2 x_0^2x_1 x_0^3 |                            |
|                                                                             |
|           4                                                   6             |
|      1 : S  <----------------------------------------------- S  : 2         |
|                {3} | -x_0 -x_0^2 -x_0^3 0    0      0    |                  |
|                {3} | x_1  0      0      -x_0 -x_0^2 0    |                  |
|                {3} | 0    x_1^2  0      x_1  0      -x_0 |                  |
|                {3} | 0    0      x_1^3  0    x_1^2  x_1  |                  |
|                                                                             |
|           6                                   4                             |
|      2 : S  <------------------------------- S  : 3                         |
|                {4} | x_0 x_0^2 0     0   |                                  |
|                {5} | -1  0     x_0   0   |                                  |
|                {6} | 0   -1    -1    0   |                                  |
|                {4} | x_1 0     0     x_0 |                                  |
|                {5} | 0   x_1   0     -1  |                                  |
|                {4} | 0   0     x_1^2 x_1 |                                  |
|                                                                             |
|           4                    1                                            |
|      3 : S  <---------------- S  : 4                                        |
|                {5} | -x_0 |                                                 |
|                {6} | 1    |                                                 |
|                {6} | -1   |                                                 |
|                {5} | x_1  |                                                 |
|                                                                             |
|o23 : ChainComplexMap                                                        |
+-----------------------------------------------------------------------------+
|i24 : assert all(4, i -> T.dd_(i+1) == boundaryMap(i, Δ,  Labels => sort     |
|-----------------------------------------------------------------------------|
|M_*))                                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.
  * taylorResolution(MonomialIdeal) -- create the
    Taylor resolution of a monomial ideal

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

  * boundaryMap(ZZ,SimplicialComplex)
    -- make a boundary map between the
    oriented faces of an abstract simplicial complex

buchbergerResolution -- make a Buchberger resolution of a monomial ideal
************************************************************************

Synopsis
========

  * Usage:
        buchbergerResolution(L)
        buchbergerResolution(I)
  * Inputs:
      * I, a monomial ideal (Macaulay2Doc),
      * L, a list (Macaulay2Doc), a minimal set of generators for a
        monomial ideal $I$
  * Outputs:
      * a chain complex (Macaulay2Doc), the free resolution
        of the monomial ideal $I$ we get by homogenizing the Buchberger complex
        of $I$.

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

The Buchberger resolution of a monomial ideal is obtained by homogenizing the
Buchberger complex of the ideal.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[x_0..x_4];                                                   |
+-----------------------------------------------------------------------------+
|i2 : L = {x_1^2, x_2^2, x_3^2, x_1*x_3, x_2*x_4};                            |
+-----------------------------------------------------------------------------+
|i3 : BRes = (buchbergerResolution L);                                        |
+-----------------------------------------------------------------------------+
|i4 : BRes.dd                                                                 |
|                                                                             |
|          1                                           5                      |
|o4 = 0 : R  <--------------------------------------- R  : 1                  |
|               | x_1^2 x_2^2 x_3^2 x_1x_3 x_2x_4 |                           |
|                                                                             |
|          5                                                                  |
|     1 : R  <----------------------------------------------------------------|
|               {2} | -x_2^2 -x_3 -x_2x_4 0      0       0    0    0       0  |
|               {2} | x_1^2  0    0       -x_3^2 -x_1x_3 -x_4 0    0       0  |
|               {2} | 0      0    0       x_2^2  0       0    -x_1 -x_2x_4 0  |
|               {2} | 0      x_1  0       0      x_2^2   0    x_3  0       -x_|
|               {2} | 0      0    x_1^2   0      0       x_2  0    x_3^2   x_1|
|                                                                             |
|          9                                                               7  |
|     2 : R  <----------------------------------------------------------- R  :|
|               {4} | x_3    x_4   0      0     0      0       0      |       |
|               {3} | -x_2^2 0     x_2x_4 0     0      0       0      |       |
|               {4} | 0      -x_2  -x_3   0     0      0       0      |       |
|               {4} | 0      0     0      x_1   x_4    0       0      |       |
|               {4} | x_1    0     0      -x_3  0      x_4     0      |       |
|               {3} | 0      x_1^2 0      0     -x_3^2 -x_1x_3 0      |       |
|               {3} | 0      0     0      x_2^2 0      0       x_2x_4 |       |
|               {4} | 0      0     0      0     x_2    0       -x_1   |       |
|               {4} | 0      0     x_1    0     0      x_2     x_3    |       |
|                                                                             |
|          7                         2                                        |
|     3 : R  <--------------------- R  : 4                                    |
|               {5} | -x_4 0    |                                             |
|               {5} | x_3  0    |                                             |
|               {5} | -x_2 0    |                                             |
|               {5} | 0    -x_4 |                                             |
|               {5} | 0    x_1  |                                             |
|               {5} | x_1  -x_3 |                                             |
|               {5} | 0    x_2  |                                             |
|                                                                             |
|o4 : ChainComplexMap                                                         |
|-----------------------------------------------------------------------------|
|          9                                                                  |
|-------- R  : 2                                                              |
|     |                                                                       |
|     |                                                                       |
|     |                                                                       |
|2x_4 |                                                                       |
|x_3  |                                                                       |
|                                                                             |
|                                                                             |
| 3                                                                           |
+-----------------------------------------------------------------------------+
|i5 : BRes == chainComplex(buchbergerSimplicialComplex(L,R), Labels => L)     |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

When the Buchberger resolution is a minimal free resolution, it agrees with the
Scarf complex.

+-----------------------------------+
|i6 : Scarf = scarfChainComplex L   |
|                                   |
|      1      5      9      7      2|
|o6 = R  <-- R  <-- R  <-- R  <-- R |
|                                   |
|     0      1      2      3      4 |
|                                   |
|o6 : ChainComplex                  |
+-----------------------------------+
|i7 : BRes == Scarf                 |
|                                   |
|o7 = true                          |
+-----------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * buchbergerSimplicialComplex -- make the
    Buchberger complex of a monomial ideal
  * scarfSimplicialComplex -- create the Scarf
    simplicial complex for a list of monomials
  * scarfChainComplex -- create the Scarf chain
    complex for a list of monomials.
  * taylorResolution -- create the Taylor resolution
    of a monomial ideal

Ways to use buchbergerResolution :
==================================

  * "buchbergerResolution(List)"
  * "buchbergerResolution(MonomialIdeal)"

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

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

buchbergerSimplicialComplex -- make the Buchberger complex of a monomial ideal
******************************************************************************

Synopsis
========

  * Usage:
        buchbergerSimplicialComplex(L,R)
        buchbergerSimplicialComplex(I,R)
  * Inputs:
      * I, a monomial ideal (Macaulay2Doc),
      * L, a list (Macaulay2Doc), a minimal set of generators for a
        monomial ideal
      * R, a ring (Macaulay2Doc), the ambient ring for the
        Buchberger complex
  * Outputs:
      * an abstract simplicial complex,

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

If a monomial ideal is minimally generated by a list of monomials $L$, then the
Buchberger complex is the simplicial complex whose vertices correspond to the
monomials in $L$ and whose faces faces correspond subsets $F$ of $L$ for which
no monomial in $L$ properly divides $\text{lcm} (F)$. When we say a monomial
$m$ properly divides $\text{lcm} (F)$, we mean $m$ divides $\text{lcm} (F)$ and
$(\text{lcm} (F))/m$ has the same support as $\text{lcm} (F)$.

The Buchberger complex is a generalization of the Buchberger graph, first
introduced in Miller-Sturmfels Monomial Ideals and Planar Graphs (see
https://link.springer.com/chapter/10.1007/3-540-46796-3_3 ) as an important
object of study for Gröbner bases. Oltaneau and Welker introduce the Buchberger
complex in their paper The Buchberger Resolution (see
https://arxiv.org/pdf/1409.2041.pdf ).

+--------------------------------------------------------------+
|i1 : R = ZZ/101[x_0..x_4];                                    |
+--------------------------------------------------------------+
|i2 : S = ZZ/101[a,b,c,d,e];                                   |
+--------------------------------------------------------------+
|i3 : I = monomialIdeal(x_1^2, x_2^2, x_3^2, x_1*x_3, x_2*x_4);|
|                                                              |
|o3 : MonomialIdeal of R                                       |
+--------------------------------------------------------------+
|i4 : B1 = buchbergerSimplicialComplex(I,S)                    |
|                                                              |
|o4 = simplicialComplex | acde abcd |                          |
|                                                              |
|o4 : SimplicialComplex                                        |
+--------------------------------------------------------------+

The Buchberger complex supports a free resolution of $I$, called the
Buchberger resolution, of $I$.

+---------------------------------------------------------------+
|i5 : BRes = chainComplex(B1, Labels => first entries mingens I)|
|                                                               |
|      1      5      9      7      2                            |
|o5 = R  <-- R  <-- R  <-- R  <-- R                             |
|                                                               |
|     0      1      2      3      4                             |
|                                                               |
|o5 : ChainComplex                                              |
+---------------------------------------------------------------+
|i6 : HH_0(BRes)                                                |
|                                                               |
|o6 = cokernel | x_2x_4 x_3^2 x_1x_3 x_2^2 x_1^2 |              |
|                                                               |
|                            1                                  |
|o6 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i7 : all(1..dim B1+1, i -> prune HH_i(BRes) == 0)              |
|                                                               |
|o7 = true                                                      |
+---------------------------------------------------------------+
|i8 : BRes == buchbergerResolution(I)                           |
|                                                               |
|o8 = true                                                      |
+---------------------------------------------------------------+

If the monomial ideal is square free, then the Buchberger complex is the
simplex on $\#L$ vertices.

+---------------------------------------------+
|i9 : L = {x_1*x_2, x_1*x_3*x_4, x_0*x_2*x_4};|
+---------------------------------------------+
|i10 : B2 = buchbergerSimplicialComplex(L,S)  |
|                                             |
|o10 = simplicialComplex | abc |              |
|                                             |
|o10 : SimplicialComplex                      |
+---------------------------------------------+

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * buchbergerResolution -- make a Buchberger
    resolution of a monomial ideal
  * taylorResolution -- create the Taylor resolution
    of a monomial ideal
  * scarfSimplicialComplex -- create the Scarf
    simplicial complex for a list of monomials
  * scarfChainComplex -- create the Scarf chain
    complex for a list of monomials.

Ways to use buchbergerSimplicialComplex :
=========================================

  * "buchbergerSimplicialComplex(List,Ring)"
  * "buchbergerSimplicialComplex(MonomialIdeal,Ring)"

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

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

chainComplex(SimplicialComplex) -- create the chain complex associated to a simplicial complex.
***********************************************************************************************

Synopsis
========

  * Function: chainComplex (Macaulay2Doc),
  * Usage:
        chainComplex Delta
        chainComplex(Delta, Labels => L)
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Optional inputs (Macaulay2Doc),:
      * Labels => a list (Macaulay2Doc), default value {}, L of
        monomials in a polynomial ring, one for each vertex of $\Delta$
  * Outputs:
      * C, a chain complex (Macaulay2Doc), of free modules

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

Each abstract simplicial complex $\Delta$ determines a chain complex of free
modules over its coefficient ring.
For all integers $i$, the $i$-th
module in this chain complex has a basis corresponding to the $i$-dimensional
faces in the simplicial complex $\Delta$.

When the argument $\mathrm{Labels}$ has the default value, this method function
constructs $\widetilde C(D;k)$, where $k$ is the coefficient ring,
of $\Delta$. The reduced homology of an
abstract simplicial complex $\Delta$ is, by definition, the homology of this
chain complex.  We illustrate this method with a triangulation of the torus and
Klein bottle.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[a..g];                                                           |
+-----------------------------------------------------------------------------+
|i2 : torus = smallManifold(2, 7, 6, S)                                       |
|                                                                             |
|o2 = simplicialComplex | cfg afg beg aeg cdg bdg def bef adf bcf cde ace abd |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|abc |                                                                        |
+-----------------------------------------------------------------------------+
|i3 : C = chainComplex torus                                                  |
|                                                                             |
|       1       7       21       14                                           |
|o3 = QQ  <-- QQ  <-- QQ   <-- QQ                                             |
|                                                                             |
|     -1      0       1        2                                              |
|                                                                             |
|o3 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i4 : fVector torus                                                           |
|                                                                             |
|o4 = {1, 7, 21, 14}                                                          |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : prune HH C                                                              |
|                                                                             |
|o5 = -1 : 0                                                                  |
|                                                                             |
|      0 : 0                                                                  |
|                                                                             |
|            2                                                                |
|      1 : QQ                                                                 |
|                                                                             |
|            1                                                                |
|      2 : QQ                                                                 |
|                                                                             |
|o5 : GradedModule                                                            |
+-----------------------------------------------------------------------------+
|i6 : assert(prune HH_1 C == QQ^2)                                            |
+-----------------------------------------------------------------------------+
|i7 : assert(prune HH_2 C == QQ^1)                                            |
+-----------------------------------------------------------------------------+
|i8 : prune HH torus                                                          |
|                                                                             |
|o8 = -1 : 0                                                                  |
|                                                                             |
|      0 : 0                                                                  |
|                                                                             |
|            2                                                                |
|      1 : QQ                                                                 |
|                                                                             |
|            1                                                                |
|      2 : QQ                                                                 |
|                                                                             |
|o8 : GradedModule                                                            |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i9 : R = ZZ[a..h];                                                           |
+-----------------------------------------------------------------------------+
|i10 : Δ = kleinBottleComplex R                                               |
|                                                                             |
|o10 = simplicialComplex | cgh agh cfh afh efg dfg aeg cdg bef adf bcf cde bde|
|                                                                             |
|o10 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|ace abd abc |                                                                |
+-----------------------------------------------------------------------------+
|i11 : C' = chainComplex Δ                                                    |
|                                                                             |
|        1       8       24       16                                          |
|o11 = ZZ  <-- ZZ  <-- ZZ   <-- ZZ                                            |
|                                                                             |
|      -1      0       1        2                                             |
|                                                                             |
|o11 : ChainComplex                                                           |
+-----------------------------------------------------------------------------+
|i12 : C'.dd                                                                  |
|                                                                             |
|             1                                    8                          |
|o12 = -1 : ZZ  <------------------------------- ZZ  : 0                      |
|                  | -1 -1 -1 -1 -1 -1 -1 -1 |                                |
|                                                                             |
|            8                                                                |
|      0 : ZZ  <--------------------------------------------------------------|
|                 | 1  1  1  1  1  1  1  0  0  0  0  0  0  0  0  0  0  0  0  0|
|                 | -1 0  0  0  0  0  0  1  1  1  1  0  0  0  0  0  0  0  0  0|
|                 | 0  -1 0  0  0  0  0  -1 0  0  0  1  1  1  1  1  0  0  0  0|
|                 | 0  0  -1 0  0  0  0  0  -1 0  0  -1 0  0  0  0  1  1  1  0|
|                 | 0  0  0  -1 0  0  0  0  0  -1 0  0  -1 0  0  0  -1 0  0  1|
|                 | 0  0  0  0  -1 0  0  0  0  0  -1 0  0  -1 0  0  0  -1 0  -|
|                 | 0  0  0  0  0  -1 0  0  0  0  0  0  0  0  -1 0  0  0  -1 0|
|                 | 0  0  0  0  0  0  -1 0  0  0  0  0  0  0  0  -1 0  0  0  0|
|                                                                             |
|            24                                                            16 |
|      1 : ZZ   <------------------------------------------------------- ZZ   |
|                  | -1 -1 0  0  0  0  0  0  0  0  0  0  0  0  0  0  |        |
|                  | 1  0  -1 0  0  0  0  0  0  0  0  0  0  0  0  0  |        |
|                  | 0  1  0  -1 0  0  0  0  0  0  0  0  0  0  0  0  |        |
|                  | 0  0  1  0  -1 0  0  0  0  0  0  0  0  0  0  0  |        |
|                  | 0  0  0  1  0  -1 0  0  0  0  0  0  0  0  0  0  |        |
|                  | 0  0  0  0  1  0  -1 0  0  0  0  0  0  0  0  0  |        |
|                  | 0  0  0  0  0  1  1  0  0  0  0  0  0  0  0  0  |        |
|                  | -1 0  0  0  0  0  0  -1 0  0  0  0  0  0  0  0  |        |
|                  | 0  -1 0  0  0  0  0  0  -1 0  0  0  0  0  0  0  |        |
|                  | 0  0  0  0  0  0  0  0  1  -1 0  0  0  0  0  0  |        |
|                  | 0  0  0  0  0  0  0  1  0  1  0  0  0  0  0  0  |        |
|                  | 0  0  0  0  0  0  0  0  0  0  -1 -1 0  0  0  0  |        |
|                  | 0  0  -1 0  0  0  0  0  0  0  1  0  0  0  0  0  |        |
|                  | 0  0  0  0  0  0  0  -1 0  0  0  0  -1 0  0  0  |        |
|                  | 0  0  0  0  0  0  0  0  0  0  0  1  0  -1 0  0  |        |
|                  | 0  0  0  0  0  0  0  0  0  0  0  0  1  1  0  0  |        |
|                  | 0  0  0  0  0  0  0  0  -1 0  -1 0  0  0  0  0  |        |
|                  | 0  0  0  -1 0  0  0  0  0  0  0  0  0  0  -1 0  |        |
|                  | 0  0  0  0  0  0  0  0  0  0  0  -1 0  0  1  0  |        |
|                  | 0  0  0  0  0  0  0  0  0  -1 0  0  0  0  0  -1 |        |
|                  | 0  0  0  0  -1 0  0  0  0  0  0  0  0  0  0  1  |        |
|                  | 0  0  0  0  0  0  0  0  0  0  0  0  0  0  -1 -1 |        |
|                  | 0  0  0  0  0  -1 0  0  0  0  0  0  -1 0  0  0  |        |
|                  | 0  0  0  0  0  0  -1 0  0  0  0  0  0  -1 0  0  |        |
|                                                                             |
|o12 : ChainComplexMap                                                        |
|-----------------------------------------------------------------------------|
|                    24                                                       |
|----------------- ZZ   : 1                                                   |
|  0  0  0  0  |                                                              |
|  0  0  0  0  |                                                              |
|  0  0  0  0  |                                                              |
|  0  0  0  0  |                                                              |
|  1  0  0  0  |                                                              |
|1 0  1  1  0  |                                                              |
|  -1 -1 0  1  |                                                              |
|  0  0  -1 -1 |                                                              |
|                                                                             |
|                                                                             |
|: 2                                                                          |
+-----------------------------------------------------------------------------+
|i13 : fVector Δ                                                              |
|                                                                             |
|o13 = {1, 8, 24, 16}                                                         |
|                                                                             |
|o13 : List                                                                   |
+-----------------------------------------------------------------------------+
|i14 : prune HH C'                                                            |
|                                                                             |
|o14 = -1 : 0                                                                 |
|                                                                             |
|       0 : 0                                                                 |
|                                                                             |
|       1 : cokernel | 2 |                                                    |
|                    | 0 |                                                    |
|                                                                             |
|       2 : 0                                                                 |
|                                                                             |
|o14 : GradedModule                                                           |
+-----------------------------------------------------------------------------+
|i15 : prune HH Δ                                                             |
|                                                                             |
|o15 = -1 : 0                                                                 |
|                                                                             |
|       0 : 0                                                                 |
|                                                                             |
|       1 : cokernel | 2 |                                                    |
|                    | 0 |                                                    |
|                                                                             |
|       2 : 0                                                                 |
|                                                                             |
|o15 : GradedModule                                                           |
+-----------------------------------------------------------------------------+
|i16 : assert(prune HH_1 C' == ZZ^1/ideal(2) ++ ZZ^1)                         |
+-----------------------------------------------------------------------------+

When the optional argument $\mathrm{Labels}$ is a list of monomials,
corresponding to the vertices of $\Delta$, this method returns a chain complex
of free modules over the ring containing monomial labels.  Each face, or basis
vector, is labelled by the least common multiple of the labels on its vertices.
In other words, the chain complex associated to a labelled simplicial complex
is the homogenization of the canonical chain complex associated to $\Delta$;
see Chapter 4 in Miller-Sturmfels' Combinatorial Commutative Algebra or Section
55 in Irena Peeva's Graded Syzygies.

As the next example establishes, this approach can sometimes produce a minimal
free resolution of a monomial ideal.

+----------------------------------------------------------------------+
|i17 : S = QQ[a..d];                                                   |
+----------------------------------------------------------------------+
|i18 : Γ = simplicialComplex{a*b*c, b*c*d};                            |
+----------------------------------------------------------------------+
|i19 : C = chainComplex Γ                                              |
|                                                                      |
|        1       4       5       2                                     |
|o19 = QQ  <-- QQ  <-- QQ  <-- QQ                                      |
|                                                                      |
|      -1      0       1       2                                       |
|                                                                      |
|o19 : ChainComplex                                                    |
+----------------------------------------------------------------------+
|i20 : C.dd                                                            |
|                                                                      |
|             1                        4                               |
|o20 = -1 : QQ  <------------------- QQ  : 0                           |
|                  | -1 -1 -1 -1 |                                     |
|                                                                      |
|            4                           5                             |
|      0 : QQ  <---------------------- QQ  : 1                         |
|                 | 1  1  0  0  0  |                                   |
|                 | -1 0  1  1  0  |                                   |
|                 | 0  -1 -1 0  1  |                                   |
|                 | 0  0  0  -1 -1 |                                   |
|                                                                      |
|            5                  2                                      |
|      1 : QQ  <------------- QQ  : 2                                  |
|                 | -1 0  |                                            |
|                 | 1  0  |                                            |
|                 | -1 -1 |                                            |
|                 | 0  1  |                                            |
|                 | 0  -1 |                                            |
|                                                                      |
|o20 : ChainComplexMap                                                 |
+----------------------------------------------------------------------+
|i21 : R = QQ[x_0..x_3];                                               |
+----------------------------------------------------------------------+
|i22 : hC = chainComplex(Γ, Labels => {x_0*x_1, x_3, x_1*x_2, x_0*x_2})|
|                                                                      |
|       1      4      5      2                                         |
|o22 = R  <-- R  <-- R  <-- R                                          |
|                                                                      |
|      0      1      2      3                                          |
|                                                                      |
|o22 : ChainComplex                                                    |
+----------------------------------------------------------------------+
|i23 : hC.dd                                                           |
|                                                                      |
|           1                                    4                     |
|o23 = 0 : R  <-------------------------------- R  : 1                 |
|                | x_0x_1 x_3 x_1x_2 x_0x_2 |                          |
|                                                                      |
|           4                                                5         |
|      1 : R  <-------------------------------------------- R  : 2     |
|                {2} | -x_3   -x_2 0       0       0    |              |
|                {1} | x_0x_1 0    -x_1x_2 -x_0x_2 0    |              |
|                {2} | 0      x_0  x_3     0       -x_0 |              |
|                {2} | 0      0    0       x_3     x_1  |              |
|                                                                      |
|           5                         2                                |
|      2 : R  <--------------------- R  : 3                            |
|                {3} | x_2  0    |                                     |
|                {3} | -x_3 0    |                                     |
|                {3} | x_0  x_0  |                                     |
|                {3} | 0    -x_1 |                                     |
|                {3} | 0    x_3  |                                     |
|                                                                      |
|o23 : ChainComplexMap                                                 |
+----------------------------------------------------------------------+
|i24 : prune homology hC                                               |
|                                                                      |
|o24 = 0 : cokernel | x_3 x_1x_2 x_0x_2 x_0x_1 |                       |
|                                                                      |
|      1 : 0                                                           |
|                                                                      |
|      2 : 0                                                           |
|                                                                      |
|      3 : 0                                                           |
|                                                                      |
|o24 : GradedModule                                                    |
+----------------------------------------------------------------------+

By convention, the smallest nonzero term in the homogenized chain complex
appears in homological degree $0$, rather than homological degree $-1$.  This
shift in homological degree changes the signs in the differentials.

The homogenization of the chain complex associated to an abstract simplicial
complex does not always produce a free resolution. Reordering the labels in the
previous example demonstrates this.

+-----------------------------------------------------------------------+
|i25 : hC' = chainComplex(Γ, Labels => {x_3, x_0*x_1, x_1*x_2, x_0*x_2})|
|                                                                       |
|       1      4      5      2                                          |
|o25 = R  <-- R  <-- R  <-- R                                           |
|                                                                       |
|      0      1      2      3                                           |
|                                                                       |
|o25 : ChainComplex                                                     |
+-----------------------------------------------------------------------+
|i26 : hC'.dd                                                           |
|                                                                       |
|           1                                    4                      |
|o26 = 0 : R  <-------------------------------- R  : 1                  |
|                | x_3 x_0x_1 x_1x_2 x_0x_2 |                           |
|                                                                       |
|           4                                              5            |
|      1 : R  <------------------------------------------ R  : 2        |
|                {1} | -x_0x_1 -x_1x_2 0    0    0    |                 |
|                {2} | x_3     0       -x_2 -x_2 0    |                 |
|                {2} | 0       x_3     x_0  0    -x_0 |                 |
|                {2} | 0       0       0    x_1  x_1  |                 |
|                                                                       |
|           5                       2                                   |
|      2 : R  <------------------- R  : 3                               |
|                {3} | x_2  0  |                                        |
|                {3} | -x_0 0  |                                        |
|                {3} | x_3  1  |                                        |
|                {3} | 0    -1 |                                        |
|                {3} | 0    1  |                                        |
|                                                                       |
|o26 : ChainComplexMap                                                  |
+-----------------------------------------------------------------------+
|i27 : prune HH hC'                                                     |
|                                                                       |
|o27 = 0 : cokernel | x_3 x_1x_2 x_0x_2 x_0x_1 |                        |
|                                                                       |
|      1 : cokernel {3} | x_1 |                                         |
|                                                                       |
|      2 : 0                                                            |
|                                                                       |
|      3 : 0                                                            |
|                                                                       |
|o27 : GradedModule                                                     |
+-----------------------------------------------------------------------+

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * coefficientRing(SimplicialComplex)
    -- get the coefficient ring of the
    underlying polynomial ring
  * boundaryMap(ZZ,SimplicialComplex)
    -- make a boundary map between the
    oriented faces of an abstract simplicial complex
  * resolution(Ideal) (Macaulay2Doc) -- compute a
    projective resolution of (the quotient ring corresponding to) an ideal
  * HH ChainComplex (Macaulay2Doc) -- homology of a
    chain complex

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

  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.

chainComplex(SimplicialMap) -- constructs the associated map between chain complexes
************************************************************************************

Synopsis
========

  * Function: chainComplex (Macaulay2Doc),
  * Usage:
        chainComplex f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * a chain complex map (Macaulay2Doc),

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

Given a simplicial map, this constructs the map between the associated chain
complexes of the two simplicial complexes.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_5];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal(x_0*x_5, x_1*x_4, x_2*x_3)          |
|                                                                             |
|o2 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4   |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i3 : Γ = simplicialComplex monomialIdeal(x_1*x_2)                            |
|                                                                             |
|o3 = simplicialComplex | x_0x_2x_3x_4x_5 x_0x_1x_3x_4x_5 |                   |
|                                                                             |
|o3 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i4 : f = map(Γ, Δ, {x_0,x_0,x_1,x_2,x_3,x_3})                                |
|                                                                             |
|o4 = | x_0 x_0 x_1 x_2 x_3 x_3 |                                             |
|                                                                             |
|o4 : SimplicialMap simplicialComplex | x_0x_2x_3x_4x_5 x_0x_1x_3x_4x_5 | <---|
|-----------------------------------------------------------------------------|
|simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4        |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i5 : F = chainComplex f                                                      |
|                                                                             |
|            1              1                                                 |
|o5 = -1 : ZZ  <--------- ZZ  : -1                                            |
|                 | 1 |                                                       |
|                                                                             |
|           6                        6                                        |
|     0 : ZZ  <------------------- ZZ  : 0                                    |
|                | 1 1 0 0 0 0 |                                              |
|                | 0 0 1 0 0 0 |                                              |
|                | 0 0 0 1 0 0 |                                              |
|                | 0 0 0 0 1 1 |                                              |
|                | 0 0 0 0 0 0 |                                              |
|                | 0 0 0 0 0 0 |                                              |
|                                                                             |
|           14                                    12                          |
|     1 : ZZ   <------------------------------- ZZ   : 1                      |
|                 | 0 1 0 0 1 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 1 0 0 1 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 1 0 0 1 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 1 1 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 1 1 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                 | 0 0 0 0 0 0 0 0 0 0 0 0 |                                 |
|                                                                             |
|           16                            8                                   |
|     2 : ZZ   <----------------------- ZZ  : 2                               |
|                 | 0 0 1 0 1 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 1 0 1 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                 | 0 0 0 0 0 0 0 0 |                                         |
|                                                                             |
|o5 : ChainComplexMap                                                         |
+-----------------------------------------------------------------------------+

The inclusion of a face induces an inclusion of chain complexes.

+-----------------------------------------------------------------------------+
|i6 : S' = ZZ[y_0..y_5];                                                      |
+-----------------------------------------------------------------------------+
|i7 : fish = simplicialComplex {y_0*y_1*y_2, y_1*y_2*y_3, y_3*y_4*y_5}        |
|                                                                             |
|o7 = simplicialComplex | y_3y_4y_5 y_1y_2y_3 y_0y_1y_2 |                     |
|                                                                             |
|o7 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i8 : S'' = ZZ[z_0,z_1,z_2];                                                  |
+-----------------------------------------------------------------------------+
|i9 : fishface = simplicialComplex {z_0*z_1*z_2}                              |
|                                                                             |
|o9 = simplicialComplex | z_0z_1z_2 |                                         |
|                                                                             |
|o9 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i10 : f = map(fish,fishface,{y_0,y_1,y_2});                                  |
|                                                                             |
|o10 : SimplicialMap simplicialComplex | y_3y_4y_5 y_1y_2y_3 y_0y_1y_2 | <--- |
|-----------------------------------------------------------------------------|
|simplicialComplex | z_0z_1z_2 |                                              |
+-----------------------------------------------------------------------------+
|i11 : F = chainComplex f                                                     |
|                                                                             |
|             1              1                                                |
|o11 = -1 : ZZ  <--------- ZZ  : -1                                           |
|                  | 1 |                                                      |
|                                                                             |
|            6                  3                                             |
|      0 : ZZ  <------------- ZZ  : 0                                         |
|                 | 1 0 0 |                                                   |
|                 | 0 1 0 |                                                   |
|                 | 0 0 1 |                                                   |
|                 | 0 0 0 |                                                   |
|                 | 0 0 0 |                                                   |
|                 | 0 0 0 |                                                   |
|                                                                             |
|            8                  3                                             |
|      1 : ZZ  <------------- ZZ  : 1                                         |
|                 | 1 0 0 |                                                   |
|                 | 0 1 0 |                                                   |
|                 | 0 0 1 |                                                   |
|                 | 0 0 0 |                                                   |
|                 | 0 0 0 |                                                   |
|                 | 0 0 0 |                                                   |
|                 | 0 0 0 |                                                   |
|                 | 0 0 0 |                                                   |
|                                                                             |
|            3              1                                                 |
|      2 : ZZ  <--------- ZZ  : 2                                             |
|                 | 1 |                                                       |
|                 | 0 |                                                       |
|                 | 0 |                                                       |
|                                                                             |
|o11 : ChainComplexMap                                                        |
+-----------------------------------------------------------------------------+
|i12 : kernel F == 0                                                          |
|                                                                             |
|o12 = true                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.
  * ChainComplexMap (Macaulay2Doc) -- the class of all
    maps between chain complexes

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

  * chainComplex(SimplicialMap), --
    constructs the associated map between chain complexes

coefficientRing(SimplicialComplex) -- get the coefficient ring of the underlying polynomial ring
************************************************************************************************

Synopsis
========

  * Function: coefficientRing (Macaulay2Doc),
  * Usage:
        coefficientRing Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a ring (Macaulay2Doc), that is the coefficient ring of the
        polynomial ring that contains the defining Stanley–Reisner ideal

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

In this package, an abstract simplicial complex is represented as squarefree
monomial ideal in a polynomial ring.  This
method returns the coefficient ring (Macaulay2Doc), of
this polynomial ring.

We construct the boundary of the $4$-sphere using three different polynomial
rings.

+------------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                      |
+------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|                                                                        |
|o2 = simplicialComplex | bcde acde abde abce abcd |                     |
|                                                                        |
|o2 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i3 : ring Δ                                                             |
|                                                                        |
|o3 = S                                                                  |
|                                                                        |
|o3 : PolynomialRing                                                     |
+------------------------------------------------------------------------+
|i4 : monomialIdeal Δ                                                    |
|                                                                        |
|o4 = monomialIdeal(a*b*c*d*e)                                           |
|                                                                        |
|o4 : MonomialIdeal of S                                                 |
+------------------------------------------------------------------------+
|i5 : coefficientRing Δ                                                  |
|                                                                        |
|o5 = ZZ                                                                 |
|                                                                        |
|o5 : Ring                                                               |
+------------------------------------------------------------------------+
|i6 : assert (ring Δ === S and coefficientRing Δ === ZZ and              |
|         numgens ideal Δ === 1 )                                        |
+------------------------------------------------------------------------+
+------------------------------------------------------------------------+
|i7 : R = QQ[a..e];                                                      |
+------------------------------------------------------------------------+
|i8 : Γ = simplicialComplex {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|                                                                        |
|o8 = simplicialComplex | bcde acde abde abce abcd |                     |
|                                                                        |
|o8 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i9 : ring Γ                                                             |
|                                                                        |
|o9 = R                                                                  |
|                                                                        |
|o9 : PolynomialRing                                                     |
+------------------------------------------------------------------------+
|i10 : monomialIdeal Γ                                                   |
|                                                                        |
|o10 = monomialIdeal(a*b*c*d*e)                                          |
|                                                                        |
|o10 : MonomialIdeal of R                                                |
+------------------------------------------------------------------------+
|i11 : coefficientRing Γ                                                 |
|                                                                        |
|o11 = QQ                                                                |
|                                                                        |
|o11 : Ring                                                              |
+------------------------------------------------------------------------+
|i12 : assert (ring Γ === R and coefficientRing Γ === QQ and             |
|          numgens ideal Γ === 1)                                        |
+------------------------------------------------------------------------+
+--------------------------------------------------------------------------+
|i13 : S' = ZZ/101[a..f];                                                  |
+--------------------------------------------------------------------------+
|i14 : Δ' = simplicialComplex {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|                                                                          |
|o14 = simplicialComplex | bcde acde abde abce abcd |                      |
|                                                                          |
|o14 : SimplicialComplex                                                   |
+--------------------------------------------------------------------------+
|i15 : ring Δ'                                                             |
|                                                                          |
|o15 = S'                                                                  |
|                                                                          |
|o15 : PolynomialRing                                                      |
+--------------------------------------------------------------------------+
|i16 : monomialIdeal Δ'                                                    |
|                                                                          |
|o16 = monomialIdeal (a*b*c*d*e, f)                                        |
|                                                                          |
|o16 : MonomialIdeal of S'                                                 |
+--------------------------------------------------------------------------+
|i17 : coefficientRing Δ'                                                  |
|                                                                          |
|       ZZ                                                                 |
|o17 = ---                                                                 |
|      101                                                                 |
|                                                                          |
|o17 : QuotientRing                                                        |
+--------------------------------------------------------------------------+
|i18 : assert (ring Δ' === S' and coefficientRing Δ' === ZZ/101 and        |
|          numgens ideal Δ' === 2)                                         |
+--------------------------------------------------------------------------+

The Stanley–Reisner ideal is part of the defining data of an abstract
simplicial complex, so this method does no computation.

Although an abstract simplicial complex can be represented by a Stanley–Reisner
ideal in any polynomial ring with a sufficiently large number of variables,
some operations in this package do depend of the choice of the polynomial ring
(or its coefficient ring). For example, the chain complex,
of an abstract simplicial complex is, by
default, constructed over the coefficient ring of its polynomial ring, and the
dual of a simplicial complex (or monomial ideal) is dependent on the number of
variables in the polynomial ideal.

+----------------------------------------------------------+
|i19 : C = chainComplex Δ                                  |
|                                                          |
|        1       5       10       10       5               |
|o19 = ZZ  <-- ZZ  <-- ZZ   <-- ZZ   <-- ZZ                |
|                                                          |
|      -1      0       1        2        3                 |
|                                                          |
|o19 : ChainComplex                                        |
+----------------------------------------------------------+
|i20 : D = chainComplex Γ                                  |
|                                                          |
|        1       5       10       10       5               |
|o20 = QQ  <-- QQ  <-- QQ   <-- QQ   <-- QQ                |
|                                                          |
|      -1      0       1        2        3                 |
|                                                          |
|o20 : ChainComplex                                        |
+----------------------------------------------------------+
|i21 : C' = chainComplex Δ'                                |
|                                                          |
|        ZZ 1       ZZ 5       ZZ 10       ZZ 10       ZZ 5|
|o21 = (---)  <-- (---)  <-- (---)   <-- (---)   <-- (---) |
|       101        101        101         101         101  |
|                                                          |
|      -1         0          1           2           3     |
|                                                          |
|o21 : ChainComplex                                        |
+----------------------------------------------------------+
|i22 : assert (D == C ** QQ and C' == C ** (ZZ/101))       |
+----------------------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * ring(SimplicialComplex) -- get the
    polynomial ring of its Stanley–Reisner ideal
  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.

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

  * coefficientRing(SimplicialComplex)
    -- get the coefficient ring of the
    underlying polynomial ring

connectedComponents(SimplicialComplex) -- find the connected components of an abstract simplicial complex
*********************************************************************************************************

Synopsis
========

  * Function: connectedComponents,
  * Usage:
        connectedComponents Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a list (Macaulay2Doc), of induced subcomplexes of $\Delta$,
        each one a distinct connected component of $\Delta$.

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

Two vertices $v$ and $w$ in $\Delta$ are connected if there is a sequence of
facets $F_0, F_1, \ldots, F_k \in \Delta$ such that $v \in F_0$, $w \in F_k$
and $F_i \cap F_{i+1} \neq \varnothing$ for all $1 \leq i \leq k-1$. A
connected component of $\Delta$ is a maximal subcomplex of $\Delta$ in which
all pairs of vertices are connected.

Our first example is an abstract simplicial complex with two connected
components.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[x_0..x_6];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {x_0*x_1, x_1*x_2, x_3*x_4, x_4*x_5, x_5*x_6}     |
|                                                                             |
|o2 = simplicialComplex | x_5x_6 x_4x_5 x_3x_4 x_1x_2 x_0x_1 |                |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : C = connectedComponents Δ                                               |
|                                                                             |
|o3 = {simplicialComplex | x_1x_2 x_0x_1 |, simplicialComplex | x_5x_6 x_4x_5 |
|     ------------------------------------------------------------------------|
|     x_3x_4 |}                                                               |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : assert all(C, Γ -> connectedComponents Γ === {Γ})                       |
+-----------------------------------------------------------------------------+

The void and irrelevant complexes each have one connected component.

+-------------------------------------------------------------+
|i5 : void = simplicialComplex monomialIdeal(1_S)             |
|                                                             |
|o5 = simplicialComplex 0                                     |
|                                                             |
|o5 : SimplicialComplex                                       |
+-------------------------------------------------------------+
|i6 : connectedComponents void                                |
|                                                             |
|o6 = {simplicialComplex 0}                                   |
|                                                             |
|o6 : List                                                    |
+-------------------------------------------------------------+
|i7 : assert({void} === connectedComponents void)             |
+-------------------------------------------------------------+
|i8 : irrelevant = simplicialComplex {1_S}                    |
|                                                             |
|o8 = simplicialComplex | 1 |                                 |
|                                                             |
|o8 : SimplicialComplex                                       |
+-------------------------------------------------------------+
|i9 : connectedComponents irrelevant                          |
|                                                             |
|o9 = {simplicialComplex | 1 |}                               |
|                                                             |
|o9 : List                                                    |
+-------------------------------------------------------------+
|i10 : assert({irrelevant} === connectedComponents irrelevant)|
+-------------------------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * star(SimplicialComplex,RingElement)
    -- make the star of a face
  * link(SimplicialComplex,RingElement)
    -- make the link of a face in an
    abstract simplicial complex

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

  * connectedComponents(SimplicialComplex)
    -- find the connected
    components of an abstract simplicial complex

dim(SimplicialComplex) -- find the dimension of an abstract simplicial complex
******************************************************************************

Synopsis
========

  * Function: dim (Macaulay2Doc),
  * Usage:
        dim Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * an integer (Macaulay2Doc), one less than the maximum number
        of vertices in a face

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

A face $F$ in an abstract simplicial complex $\Delta$ of cardinality $|F| = i +
1$ has dimension $i$.  The dimension of $\Delta$ is the maximum of the
dimensions of its faces or it is $-\infty$ if $\Delta$ is the void complex
(which has no faces).

+------------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                      |
+------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|                                                                        |
|o2 = simplicialComplex | bcde acde abde abce abcd |                     |
|                                                                        |
|o2 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i3 : monomialIdeal Δ                                                    |
|                                                                        |
|o3 = monomialIdeal(a*b*c*d*e)                                           |
|                                                                        |
|o3 : MonomialIdeal of S                                                 |
+------------------------------------------------------------------------+
|i4 : dim Δ                                                              |
|                                                                        |
|o4 = 3                                                                  |
+------------------------------------------------------------------------+
|i5 : assert (dim Δ === 3 and numgens ideal Δ === 1 and isPure Δ)        |
+------------------------------------------------------------------------+
+------------------------------------------------------------------------+
|i6 : R = ZZ/101[a..f];                                                  |
+------------------------------------------------------------------------+
|i7 : Γ = simplicialComplex {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|                                                                        |
|o7 = simplicialComplex | bcde acde abde abce abcd |                     |
|                                                                        |
|o7 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i8 : monomialIdeal Γ                                                    |
|                                                                        |
|o8 = monomialIdeal (a*b*c*d*e, f)                                       |
|                                                                        |
|o8 : MonomialIdeal of R                                                 |
+------------------------------------------------------------------------+
|i9 : dim Γ                                                              |
|                                                                        |
|o9 = 3                                                                  |
+------------------------------------------------------------------------+
|i10 : assert (dim Γ === 3 and numgens ideal Γ === 2 and isPure Γ)       |
+------------------------------------------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.

+----------------------------------------------------+
|i11 : S' = QQ[a..e];                                |
+----------------------------------------------------+
|i12 : Δ' = simplicialComplex {e, c*d, b*d, a*b*c}   |
|                                                    |
|o12 = simplicialComplex | e cd bd abc |             |
|                                                    |
|o12 : SimplicialComplex                             |
+----------------------------------------------------+
|i13 : monomialIdeal Δ'                              |
|                                                    |
|o13 = monomialIdeal (a*d, b*c*d, a*e, b*e, c*e, d*e)|
|                                                    |
|o13 : MonomialIdeal of S'                           |
+----------------------------------------------------+
|i14 : dim Δ'                                        |
|                                                    |
|o14 = 2                                             |
+----------------------------------------------------+
|i15 : assert (dim Δ' === 2 and not isPure Δ')       |
+----------------------------------------------------+

The irrelevant complex has the empty set as a facet whereas the void complex
has no facets.  The irrelevant complex has dimension $-1$ while the void
complex has dimension $-\infty$.

+---------------------------------------------------------------+
|i16 : irrelevant = simplicialComplex {1_S'};                   |
+---------------------------------------------------------------+
|i17 : dim irrelevant                                           |
|                                                               |
|o17 = -1                                                       |
+---------------------------------------------------------------+
|i18 : void = simplicialComplex monomialIdeal 1_S               |
|                                                               |
|o18 = simplicialComplex 0                                      |
|                                                               |
|o18 : SimplicialComplex                                        |
+---------------------------------------------------------------+
|i19 : dim void                                                 |
|                                                               |
|o19 = -infinity                                                |
|                                                               |
|o19 : InfiniteNumber                                           |
+---------------------------------------------------------------+
|i20 : assert (dim irrelevant === -1 and dim void === -infinity)|
+---------------------------------------------------------------+

To avoid repeating a computation, the package caches the result in the
CacheTable (Macaulay2Doc), of the abstract simplicial complex.

+--------------------------+
|i21 : peek Δ.cache        |
|                          |
|o21 = CacheTable{dim => 3}|
+--------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional

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

  * dim(SimplicialComplex) -- find the
    dimension of an abstract simplicial complex

dual(SimplicialComplex) -- make the Alexander dual of an abstract simplicial complex
************************************************************************************

Synopsis
========

  * Function: dual (Macaulay2Doc),
  * Usage:
        dual Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * an abstract simplicial complex, that is the
        Alexander dual of $\Delta$

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

The Alexander dual of an abstract simplicial complex $\Delta$ is the abstract
simplicial complex whose faces are the complements of the nonfaces of $\Delta$.

The Alexander dual of a square is the disjoint union of two edges.

+-----------------------------------------------------+
|i1 : S = ZZ[a..d];                                   |
+-----------------------------------------------------+
|i2 : Δ = simplicialComplex {a*b, b*c, c*d, a*d}      |
|                                                     |
|o2 = simplicialComplex | cd ad bc ab |               |
|                                                     |
|o2 : SimplicialComplex                               |
+-----------------------------------------------------+
|i3 : dual Δ                                          |
|                                                     |
|o3 = simplicialComplex | bd ac |                     |
|                                                     |
|o3 : SimplicialComplex                               |
+-----------------------------------------------------+
|i4 : assert (dual Δ === simplicialComplex {a*c, b*d})|
+-----------------------------------------------------+
|i5 : assert (dual dual Δ === Δ)                      |
+-----------------------------------------------------+

The Alexander dual is homotopy equivalent to the complement of $\Delta$ in the
simplex generated by all of the variables in the polynomial ring,
of $\Delta$. This is known as Alexander Duality
(see https://en.wikipedia.org/wiki/Alexander_duality ). In particular, it
depends on the number of variables.

+-------------------------------------------------------------------+
|i6 : S' = ZZ[a..e];                                                |
+-------------------------------------------------------------------+
|i7 : Δ' = simplicialComplex {a*b, b*c, c*d, a*d}                   |
|                                                                   |
|o7 = simplicialComplex | cd ad bc ab |                             |
|                                                                   |
|o7 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i8 : dual Δ'                                                       |
|                                                                   |
|o8 = simplicialComplex | bde ace abcd |                            |
|                                                                   |
|o8 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i9 : assert (dual Δ' === simplicialComplex {b*d*e, a*c*e, a*b*c*d})|
+-------------------------------------------------------------------+
|i10 : assert (dual dual Δ' === Δ')                                 |
+-------------------------------------------------------------------+

The projective dimension of the Stanley–Reisner ring of $\Delta$ equals the
regularity of the Stanley–Reisner ideal of the Alexander dual of $\Delta$; see
Theorem 5.59 in Miller-Sturmfels' Combinatorial Commutative Algebra.

+-----------------------------------------------------------------------------+
|i11 : R = QQ[a..h];                                                          |
+-----------------------------------------------------------------------------+
|i12 : Γ =  bartnetteSphereComplex R                                          |
|                                                                             |
|o12 = simplicialComplex | defh befh cdfh bcfh adeh abeh acdh abch defg cefg  |
|                                                                             |
|o12 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|adfg acfg bdeg bceg abdg abcg bcef acdf abde |                               |
+-----------------------------------------------------------------------------+
|i13 : dual Γ                                                                 |
|                                                                             |
|o13 = simplicialComplex | aefgh bdfgh abfgh cdegh acegh bcdgh abefh bcdfh    |
|                                                                             |
|o13 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|acdeh acefg abdfg bcdeg abcdef |                                             |
+-----------------------------------------------------------------------------+
|i14 : pdim comodule ideal Γ                                                  |
|                                                                             |
|o14 = 4                                                                      |
+-----------------------------------------------------------------------------+
|i15 : regularity ideal dual Γ                                                |
|                                                                             |
|o15 = 4                                                                      |
+-----------------------------------------------------------------------------+
|i16 : assert (pdim comodule ideal Γ === regularity ideal dual Γ)             |
+-----------------------------------------------------------------------------+

Alexander duality interchanges extremal Betti numbers of the Stanley–Reisner
ideals.  Following Example 3.2 in Bayer–Charalambous–Popescu's Extremal betti
numbers and applications to monomial ideals (see
https://arxiv.org/abs/math/9804052 ) we have the following.

+-----------------------------------------------------------------------------+
|i17 : R' = QQ[x_0 .. x_6];                                                   |
+-----------------------------------------------------------------------------+
|i18 : Γ' = simplicialComplex {x_0*x_1*x_3, x_1*x_3*x_4, x_1*x_2*x_4,         |
|          x_2*x_4*x_5, x_2*x_3*x_5, x_3*x_5*x_6, x_3*x_4*x_6,                |
|          x_0*x_4*x_6, x_0*x_4*x_5, x_0*x_1*x_5, x_1*x_5*x_6,                |
|          x_1*x_2*x_6, x_0*x_2*x_6, x_0*x_2*x_3}                             |
|                                                                             |
|o18 = simplicialComplex | x_3x_5x_6 x_1x_5x_6 x_3x_4x_6 x_0x_4x_6 x_1x_2x_6  |
|                                                                             |
|o18 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|x_0x_2x_6 x_2x_4x_5 x_0x_4x_5 x_2x_3x_5 x_0x_1x_5 x_1x_3x_4 x_1x_2x_4        |
|-----------------------------------------------------------------------------|
|x_0x_2x_3 x_0x_1x_3 |                                                        |
+-----------------------------------------------------------------------------+
|i19 : I = ideal Γ'                                                           |
|                                                                             |
|o19 = ideal (x x x , x x x , x x x , x x x , x x x , x x x , x x x , x x x , |
|              0 1 2   1 2 3   0 1 4   0 2 4   0 3 4   2 3 4   0 2 5   1 2 5  |
|      -----------------------------------------------------------------------|
|      x x x , x x x , x x x , x x x , x x x , x x x , x x x , x x x , x x x ,|
|       0 3 5   1 3 5   1 4 5   3 4 5   0 1 6   0 3 6   1 3 6   2 3 6   1 4 6 |
|      -----------------------------------------------------------------------|
|      x x x , x x x , x x x , x x x )                                        |
|       2 4 6   0 5 6   2 5 6   4 5 6                                         |
|                                                                             |
|o19 : Ideal of R'                                                            |
+-----------------------------------------------------------------------------+
|i20 : J = ideal dual Γ'                                                      |
|                                                                             |
|o20 = ideal (x x x x , x x x x , x x x x , x x x x , x x x x , x x x x ,     |
|              0 1 2 4   0 2 3 4   0 1 2 5   1 2 3 5   0 3 4 5   1 3 4 5      |
|      -----------------------------------------------------------------------|
|      x x x x , x x x x , x x x x , x x x x , x x x x , x x x x , x x x x ,  |
|       0 1 3 6   1 2 3 6   0 1 4 6   2 3 4 6   0 2 5 6   0 3 5 6   1 4 5 6   |
|      -----------------------------------------------------------------------|
|      x x x x )                                                              |
|       2 4 5 6                                                               |
|                                                                             |
|o20 : Ideal of R'                                                            |
+-----------------------------------------------------------------------------+
|i21 : betti res I                                                            |
|                                                                             |
|             0  1  2  3  4 5                                                 |
|o21 = total: 1 21 49 42 15 2                                                 |
|          0: 1  .  .  .  . .                                                 |
|          1: .  .  .  .  . .                                                 |
|          2: . 21 49 42 14 2                                                 |
|          3: .  .  .  .  1 .                                                 |
|                                                                             |
|o21 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i22 : betti res J                                                            |
|                                                                             |
|             0  1  2 3 4                                                     |
|o22 = total: 1 14 21 9 1                                                     |
|          0: 1  .  . . .                                                     |
|          1: .  .  . . .                                                     |
|          2: .  .  . . .                                                     |
|          3: . 14 21 7 1                                                     |
|          4: .  .  . 2 .                                                     |
|                                                                             |
|o22 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * dual(MonomialIdeal) (Macaulay2Doc) -- the
    Alexander dual of a monomial ideal
  * pdim(Module) (Macaulay2Doc) -- calculate the
    projective dimension of a module
  * regularity(Module) (Macaulay2Doc) -- compute the
    Castelnuovo-Mumford regularity
  * betti(GradedModule) (Macaulay2Doc) -- display or modify a
    Betti diagram

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

  * dual(SimplicialComplex) -- make the
    Alexander dual of an abstract simplicial complex

dunceHatComplex(PolynomialRing) -- make a realization of the dunce hat with 8 vertices
**************************************************************************************

Synopsis
========

  * Function: dunceHatComplex,
  * Usage:
        dunceHatComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that has at
        least 8 generators
  * Outputs:
      * an abstract simplicial complex,

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

The dunce hat (see https://en.wikipedia.org/wiki/Dunce_hat_(topology) ) is a
compact topological space formed by taking a solid triangle and gluing all
three sides together, with the orientation of one side reversed. Simply gluing
two sides oriented in the same direction would yield a cone much like the dunce
cap, but the gluing of the third side results in identifying the base of the
cap with a line joining the base to the point.

Following Erik Christopher Zeeman's "On the dunce hat", Topology 2 (1964)
341–358, this method returns non-collapsible (see
https://en.wikipedia.org/wiki/Collapse_(topology) ) but contractible (see
https://en.wikipedia.org/wiki/Contractible_space ) example of an abstract
simplicial complex.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/101[a..h];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = dunceHatComplex S                                                   |
|                                                                             |
|o2 = simplicialComplex | fgh agh dfh cdh bch abh cfg bcg abg def aef acf bde |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|bce ace acd abd |                                                            |
+-----------------------------------------------------------------------------+
|i3 : dim Δ                                                                   |
|                                                                             |
|o3 = 2                                                                       |
+-----------------------------------------------------------------------------+
|i4 : fVector Δ                                                               |
|                                                                             |
|o4 = {1, 8, 24, 17}                                                          |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : assert(dim Δ === 2 and isPure Δ)                                        |
+-----------------------------------------------------------------------------+
|i6 : assert(fVector Δ === {1,8,24,17})                                       |
+-----------------------------------------------------------------------------+

Our enumeration of the vertices follows the dunce hat (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/dunce_hat_eng.html )
example in Masahiro Hachimori's simplicial complex library (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/index_eng.html ).

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * rudinBallComplex -- make a
    nonshellable 3-ball with 14 vertices and 41 facets
  * grunbaumBallComplex -- make
    a nonshellable 3-ball with 14 vertices and 29 facets
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional

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

  * dunceHatComplex(PolynomialRing),
    -- make a realization of the dunce hat with 8 vertices

elementaryCollapse(SimplicialComplex,RingElement) -- construct the elementary collapse of a free face in a simplicial complex
*****************************************************************************************************************************

Synopsis
========

  * Function: elementaryCollapse,
  * Usage:
        elementaryCollapse(Delta, F)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * F, a ring element (Macaulay2Doc), Corresponding to a
        free face of $\Delta$
  * Outputs:
      * an abstract simplicial complex, the
        simplicial complex where the face $F$ and the unique facet containing
        $F$ are removed

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

A free face of a simplicial complex $\Delta$ is a face that is a proper maximal
subface of exactly one facet. The elementary collapse is the simplicial complex
obtained by removing the free face, and the facet containing it, from $\Delta$.
A simplicial complex that can be collapsed to a single vertex is called
collapsible. Every collapsible simplicial complex is contractible, but the
converse is not true.

+---------------------------------------------------------------+
|i1 : R = ZZ/103[x_0..x_3];                                     |
+---------------------------------------------------------------+
|i2 : Δ = simplicialComplex{R_0*R_1*R_2,R_0*R_2*R_3,R_0*R_1*R_3}|
|                                                               |
|o2 = simplicialComplex | x_0x_2x_3 x_0x_1x_3 x_0x_1x_2 |       |
|                                                               |
|o2 : SimplicialComplex                                         |
+---------------------------------------------------------------+
|i3 : C1 = elementaryCollapse(Δ,R_1*R_2)                        |
|                                                               |
|o3 = simplicialComplex | x_0x_2x_3 x_0x_1x_3 |                 |
|                                                               |
|o3 : SimplicialComplex                                         |
+---------------------------------------------------------------+
|i4 : C2 = elementaryCollapse(C1,R_2*R_3)                       |
|                                                               |
|o4 = simplicialComplex | x_0x_2 x_0x_1x_3 |                    |
|                                                               |
|o4 : SimplicialComplex                                         |
+---------------------------------------------------------------+
|i5 : C3 = elementaryCollapse(C2,R_1*R_3)                       |
|                                                               |
|o5 = simplicialComplex | x_0x_3 x_0x_2 x_0x_1 |                |
|                                                               |
|o5 : SimplicialComplex                                         |
+---------------------------------------------------------------+
|i6 : C4 = elementaryCollapse(C3,R_1)                           |
|                                                               |
|o6 = simplicialComplex | x_0x_3 x_0x_2 |                       |
|                                                               |
|o6 : SimplicialComplex                                         |
+---------------------------------------------------------------+
|i7 : C5 = elementaryCollapse(C4,R_2)                           |
|                                                               |
|o7 = simplicialComplex | x_0x_3 |                              |
|                                                               |
|o7 : SimplicialComplex                                         |
+---------------------------------------------------------------+
|i8 : C6 = elementaryCollapse(C5,R_3)                           |
|                                                               |
|o8 = simplicialComplex | x_0 |                                 |
|                                                               |
|o8 : SimplicialComplex                                         |
+---------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * SimplicialComplex -- the class of all abstract
    simplicial complexes

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

  * elementaryCollapse(SimplicialComplex,RingElement)
    -- construct the
    elementary collapse of a free face in a simplicial complex

faces(SimplicialComplex) -- get the list of faces for an abstract simplicial complex
************************************************************************************

Synopsis
========

  * Function: faces (Polyhedra),
  * Usage:
        faces Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a hash table (Macaulay2Doc),

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

In this package, an abstract simplicial complex $\Delta$ is identified with a
squarefree monomial ideal in a polynomial ring.
The vertices of $\Delta$ correspond to a subset
of the variables in the polynomial ring, and each face is identified as the
product of the variables corresponding to the vertices of that face.  This
method function returns a HashTable (Macaulay2Doc), whose keys
are the integers from $-1$ to $\operatorname{dim} \Delta$ and the value of the
key $i$ is the list containing the monomials corresponding to the
$i$-dimensional faces of $\Delta$.

The faces of the simplex,
correspond to all subsets of the underlying vertex set.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[x_0..x_3];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplexComplex(3, S)                                                |
|                                                                             |
|o2 = simplicialComplex | x_0x_1x_2x_3 |                                      |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : faces Δ                                                                 |
|                                                                             |
|o3 = HashTable{-1 => {1}                                }                    |
|               0 => {x , x , x , x }                                         |
|                      0   1   2   3                                          |
|               1 => {x x , x x , x x , x x , x x , x x }                     |
|                      0 1   0 2   0 3   1 2   1 3   2 3                      |
|               2 => {x x x , x x x , x x x , x x x }                         |
|                      0 1 2   0 1 3   0 2 3   1 2 3                          |
|               3 => {x x x x }                                               |
|                      0 1 2 3                                                |
|                                                                             |
|o3 : HashTable                                                               |
+-----------------------------------------------------------------------------+
|i4 : dim Δ                                                                   |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : subsets vertices Δ                                                      |
|                                                                             |
|o5 = {{}, {x }, {x }, {x , x }, {x }, {x , x }, {x , x }, {x , x , x }, {x },|
|            0     1     0   1     2     0   2     1   2     0   1   2     3  |
|     ------------------------------------------------------------------------|
|     {x , x }, {x , x }, {x , x , x }, {x , x }, {x , x , x }, {x , x , x }, |
|       0   3     1   3     0   1   3     2   3     0   2   3     1   2   3   |
|     ------------------------------------------------------------------------|
|     {x , x , x , x }}                                                       |
|       0   1   2   3                                                         |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : assert(faces Δ === hashTable for i from -1 to 3 list                    |
|         i => first entries sub(matrix{rsort subsets(vertices Δ,             |
|-----------------------------------------------------------------------------|
|i+1)/product}, S))                                                           |
+-----------------------------------------------------------------------------+

The faces of the Bartnette sphere,
are a proper subset of the
$7$-simplex.

+-----------------------------------------------------------------------------+
|i7 : R = ZZ[a..h];                                                           |
+-----------------------------------------------------------------------------+
|i8 : Γ = bartnetteSphereComplex R;                                           |
+-----------------------------------------------------------------------------+
|i9 : matrix {facets Γ}                                                       |
|                                                                             |
|o9 = | defh befh cdfh bcfh adeh abeh acdh abch defg cefg adfg acfg bdeg bceg |
|     ------------------------------------------------------------------------|
|     abdg abcg bcef acdf abde |                                              |
|                                                                             |
|             1       19                                                      |
|o9 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i10 : faces Γ                                                                |
|                                                                             |
|o10 = HashTable{-1 => {1}                                                    |
|                0 => {a, b, c, d, e, f, g, h}                                |
|                1 => {a*b, a*c, a*d, a*e, a*f, a*g, a*h, b*c, b*d, b*e, b*f, |
|                2 => {a*b*c, a*b*d, a*b*e, a*b*g, a*b*h, a*c*d, a*c*f, a*c*g,|
|                3 => {a*b*c*g, a*b*c*h, a*b*d*e, a*b*d*g, a*b*e*h, a*c*d*f, a|
|                                                                             |
|o10 : HashTable                                                              |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|b*g, b*h, c*d, c*e, c*f, c*g, c*h, d*e, d*f, d*g, d*h, e*f, e*g, e*h, f*g, f*|
| a*c*h, a*d*e, a*d*f, a*d*g, a*d*h, a*e*h, a*f*g, b*c*e, b*c*f, b*c*g, b*c*h,|
|*c*d*h, a*c*f*g, a*d*e*h, a*d*f*g, b*c*e*f, b*c*e*g, b*c*f*h, b*d*e*g, b*e*f*|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|h}                                                                           |
| b*d*e, b*d*g, b*e*f, b*e*g, b*e*h, b*f*h, c*d*f, c*d*h, c*e*f, c*e*g, c*f*g,|
|h, c*d*f*h, c*e*f*g, d*e*f*g, d*e*f*h}                                       |
|-----------------------------------------------------------------------------|
|                                                       }                     |
|                                                                             |
|                                                                             |
|c*f*h, d*e*f, d*e*g, d*e*h, d*f*g, d*f*h, e*f*g, e*f*h}                      |
+-----------------------------------------------------------------------------+
|i11 : monomialIdeal Γ                                                        |
|                                                                             |
|o11 = monomialIdeal (b*c*d, a*c*e, c*d*e, a*b*f, b*d*f, a*e*f, c*d*g, a*e*g, |
|      -----------------------------------------------------------------------|
|      b*f*g, b*d*h, c*e*h, a*f*h, g*h)                                       |
|                                                                             |
|o11 : MonomialIdeal of R                                                     |
+-----------------------------------------------------------------------------+

There are two "trivial" simplicial complexes: the irrelevant complex has the
empty set as a facet whereas the void complex has no facets.

+---------------------------------------------------------+
|i12 : irrelevant = simplicialComplex monomialIdeal gens S|
|                                                         |
|o12 = simplicialComplex | 1 |                            |
|                                                         |
|o12 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i13 : faces irrelevant                                   |
|                                                         |
|o13 = HashTable{-1 => {1}}                               |
|                                                         |
|o13 : HashTable                                          |
+---------------------------------------------------------+
|i14 : assert(faces irrelevant === hashTable{-1 => {1_S}})|
+---------------------------------------------------------+
|i15 : void = simplicialComplex monomialIdeal 1_S         |
|                                                         |
|o15 = simplicialComplex 0                                |
|                                                         |
|o15 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i16 : faces void                                         |
|                                                         |
|o16 = HashTable{}                                        |
|                                                         |
|o16 : HashTable                                          |
+---------------------------------------------------------+
|i17 : assert(faces void === hashTable{})                 |
+---------------------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * vertices(SimplicialComplex) -- get
    the list of the vertices for an abstract simplicial complex
  * dim(SimplicialComplex) -- find the
    dimension of an abstract simplicial complex
  * faces(ZZ,SimplicialComplex), --
    get the $i$-faces of an abstract simplicial complex
  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex

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

  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex

faces(ZZ,SimplicialComplex) -- get the $i$-faces of an abstract simplicial complex
**********************************************************************************

Synopsis
========

  * Function: faces (Polyhedra),
  * Usage:
        faces(i, Delta)
  * Inputs:
      * i, an integer (Macaulay2Doc), the dimension of the faces
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a list (Macaulay2Doc), whose entries are squarefree
        monomials representing the faces of $\Delta$ of dimension $i$

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

In this package, an abstract simplicial complex $\Delta$ is identified with a
squarefree monomial ideal in a polynomial ring.
The vertices of $\Delta$ correspond to a subset
of the variables in the polynomial ring, and each face is identified as the
product of the variables corresponding to the vertices of that face. This
method function returns a List (Macaulay2Doc), whose entries are the
monomials corresponding to the $i$-faces of $\Delta$.

The faces of the simplex,
correspond to all subsets of the underlying vertex set.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[x_0..x_3];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplexComplex(3, S)                                                |
|                                                                             |
|o2 = simplicialComplex | x_0x_1x_2x_3 |                                      |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : netList for i from -1 to dim Δ list {i,faces(i, Δ)}                     |
|                                                                             |
|     +--+------------------------------------+                               |
|o3 = |-1|{1}                                 |                               |
|     +--+------------------------------------+                               |
|     |0 |{x , x , x , x }                    |                               |
|     |  |  0   1   2   3                     |                               |
|     +--+------------------------------------+                               |
|     |1 |{x x , x x , x x , x x , x x , x x }|                               |
|     |  |  0 1   0 2   0 3   1 2   1 3   2 3 |                               |
|     +--+------------------------------------+                               |
|     |2 |{x x x , x x x , x x x , x x x }    |                               |
|     |  |  0 1 2   0 1 3   0 2 3   1 2 3     |                               |
|     +--+------------------------------------+                               |
|     |3 |{x x x x }                          |                               |
|     |  |  0 1 2 3                           |                               |
|     +--+------------------------------------+                               |
+-----------------------------------------------------------------------------+
|i4 : assert all(-1..dim Δ, i ->  faces(i, Δ) === first entries               |
|-----------------------------------------------------------------------------|
|sub(matrix{rsort subsets(vertices Δ, i+1)/product}, S))                      |
+-----------------------------------------------------------------------------+

The faces of the dunce hat, are a
proper subset of the $7$-simplex.

+-----------------------------------------------------------------------------+
|i5 : R = ZZ[a..h];                                                           |
+-----------------------------------------------------------------------------+
|i6 : Γ = dunceHatComplex R;                                                  |
+-----------------------------------------------------------------------------+
|i7 : matrix {facets Γ}                                                       |
|                                                                             |
|o7 = | fgh agh dfh cdh bch abh cfg bcg abg def aef acf bde bce ace acd abd | |
|                                                                             |
|             1       17                                                      |
|o7 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i8 : netList for i from -1 to dim Γ list {i,faces(i, Γ)}                     |
|                                                                             |
|     +--+--------------------------------------------------------------------|
|o8 = |-1|{1}                                                                 |
|     +--+--------------------------------------------------------------------|
|     |0 |{a, b, c, d, e, f, g, h}                                            |
|     +--+--------------------------------------------------------------------|
|     |1 |{a*b, a*c, a*d, a*e, a*f, a*g, a*h, b*c, b*d, b*e, b*g, b*h, c*d, c*|
|     +--+--------------------------------------------------------------------|
|     |2 |{a*b*d, a*b*g, a*b*h, a*c*d, a*c*e, a*c*f, a*e*f, a*g*h, b*c*e, b*c*|
|     +--+--------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|----------------------------------------------------+                        |
|                                                    |                        |
|----------------------------------------------------+                        |
|                                                    |                        |
|----------------------------------------------------+                        |
|e, c*f, c*g, c*h, d*e, d*f, d*h, e*f, f*g, f*h, g*h}|                        |
|----------------------------------------------------+                        |
|g, b*c*h, b*d*e, c*d*h, c*f*g, d*e*f, d*f*h, f*g*h} |                        |
|----------------------------------------------------+                        |
+-----------------------------------------------------------------------------+
|i9 : monomialIdeal Γ                                                         |
|                                                                             |
|o9 = monomialIdeal (a*b*c, b*c*d, a*b*e, a*d*e, c*d*e, b*f, a*d*f, c*d*f,    |
|     ------------------------------------------------------------------------|
|     c*e*f, a*c*g, d*g, e*g, a*f*g, a*c*h, a*d*h, b*d*h, e*h, a*f*h, c*f*h,  |
|     ------------------------------------------------------------------------|
|     b*g*h, c*g*h)                                                           |
|                                                                             |
|o9 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+

There are two "trivial" simplicial complexes: the irrelevant complex has the
empty set as a facet whereas the void complex has no faces.

+---------------------------------------------------------+
|i10 : irrelevant = simplicialComplex monomialIdeal gens S|
|                                                         |
|o10 = simplicialComplex | 1 |                            |
|                                                         |
|o10 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i11 : dim irrelevant                                     |
|                                                         |
|o11 = -1                                                 |
+---------------------------------------------------------+
|i12 : faces (-1, irrelevant)                             |
|                                                         |
|o12 = {1}                                                |
|                                                         |
|o12 : List                                               |
+---------------------------------------------------------+
|i13 : assert(faces(-1, irrelevant) === {1_S})            |
+---------------------------------------------------------+
|i14 : void = simplicialComplex monomialIdeal 1_S         |
|                                                         |
|o14 = simplicialComplex 0                                |
|                                                         |
|o14 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i15 : faces(-1, void)                                    |
|                                                         |
|o15 = {}                                                 |
|                                                         |
|o15 : List                                               |
+---------------------------------------------------------+
|i16 : assert all(-2..7, i -> faces(i, void) == {})       |
+---------------------------------------------------------+

To avoid repeated computation, the values of this method are saved the
cache table (Macaulay2Doc), of the abstract simplicial complex
$\Delta$.

+-----------------------------------------------------------------+
|i17 : peek Δ.cache                                               |
|                                                                 |
|o17 = CacheTable{dim => 3                          }             |
|                 faces => MutableHashTable{...6...}              |
+-----------------------------------------------------------------+
|i18 : peek Δ.cache.faces                                         |
|                                                                 |
|o18 = MutableHashTable{-1 => {1}                                }|
|                       0 => {x , x , x , x }                     |
|                              0   1   2   3                      |
|                       1 => {x x , x x , x x , x x , x x , x x } |
|                              0 1   0 2   0 3   1 2   1 3   2 3  |
|                       2 => {x x x , x x x , x x x , x x x }     |
|                              0 1 2   0 1 3   0 2 3   1 2 3      |
|                       3 => {x x x x }                           |
|                              0 1 2 3                            |
|                       ring => QQ[x ..x ]                        |
|                                   0   3                         |
+-----------------------------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * vertices(SimplicialComplex) -- get
    the list of the vertices for an abstract simplicial complex
  * dim(SimplicialComplex) -- find the
    dimension of an abstract simplicial complex
  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex
  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex

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

  * faces(ZZ,SimplicialComplex), --
    get the $i$-faces of an abstract simplicial complex

facets(SimplicialComplex) -- get the list of maximal faces
**********************************************************

Synopsis
========

  * Function: facets (Polyhedra),
  * Usage:
        facets Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a list (Macaulay2Doc), whose entries are the squarefree
        monomials representing the facets in $\Delta$

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

In this package, an abstract simplicial complex $\Delta$ is identified with a
squarefree monomial ideal in a polynomial ring.
The vertices of $\Delta$ correspond to a subset
of the variables in the polynomial ring, and each face is identified as the
product of the variables corresponding to the vertices of that face. This
method function returns a list whose entries are the squarefree monomials
representing the maximal faces of $\Delta$.

The order of the facets is determined by the monomial order (Macaulay2Doc),
on the underlying polynomial ring.  The facets of
an abstract simplicial complex are used when outputting or printing; see
net(SimplicialComplex).

+----------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                    |
+----------------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal (a*b*c*d*e)                  |
|                                                                      |
|o2 = simplicialComplex | bcde acde abde abce abcd |                   |
|                                                                      |
|o2 : SimplicialComplex                                                |
+----------------------------------------------------------------------+
|i3 : facets Δ                                                         |
|                                                                      |
|o3 = {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}                    |
|                                                                      |
|o3 : List                                                             |
+----------------------------------------------------------------------+
|i4 : assert (facets Δ == {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|         and isPure Δ and dim Δ === 3)                                |
+----------------------------------------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.

+--------------------------------------------------------------+
|i5 : Γ = simplicialComplex {e, c*d, b*d, a*b*c}               |
|                                                              |
|o5 = simplicialComplex | e cd bd abc |                        |
|                                                              |
|o5 : SimplicialComplex                                        |
+--------------------------------------------------------------+
|i6 : facets Γ                                                 |
|                                                              |
|o6 = {e, c*d, b*d, a*b*c}                                     |
|                                                              |
|o6 : List                                                     |
+--------------------------------------------------------------+
|i7 : assert (facets Γ == {e, c*d, b*d, a*b*c} and             |
|         ideal Γ == ideal (a*d, b*c*d, a*e, b*e, c*e, d*e) and|
|         not isPure Γ and dim Γ === 2)                        |
+--------------------------------------------------------------+

The irrelevant complex has the empty set as a facet whereas the void complex
has no facets.

+---------------------------------------------------------------+
|i8 : irrelevant = simplicialComplex {1_S}                      |
|                                                               |
|o8 = simplicialComplex | 1 |                                   |
|                                                               |
|o8 : SimplicialComplex                                         |
+---------------------------------------------------------------+
|i9 : facets irrelevant                                         |
|                                                               |
|o9 = {1}                                                       |
|                                                               |
|o9 : List                                                      |
+---------------------------------------------------------------+
|i10 : void = simplicialComplex monomialIdeal 1_S               |
|                                                               |
|o10 = simplicialComplex 0                                      |
|                                                               |
|o10 : SimplicialComplex                                        |
+---------------------------------------------------------------+
|i11 : facets void                                              |
|                                                               |
|o11 = {}                                                       |
|                                                               |
|o11 : List                                                     |
+---------------------------------------------------------------+
|i12 : assert (facets irrelevant == {1_S} and facets void == {})|
+---------------------------------------------------------------+

The list of facets is part of the defining data of an abstract simplicial
complex. While this method function does no computation, it allows us access to
this data.

+-----------------------------------------------------------------------------+
|i13 : peek Δ                                                                 |
|                                                                             |
|o13 = SimplicialComplex{cache => CacheTable{...1...}                         |
|                        facets => {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e,       |
|                        monomialIdeal => monomialIdeal(a*b*c*d*e)            |
|                        ring => S                                            |
|-----------------------------------------------------------------------------|
|        }                                                                    |
|a*b*c*d}                                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * net(SimplicialComplex) -- make a
    symbolic representation of an abstract simplicial complex
  * ring(SimplicialComplex) -- get the
    polynomial ring of its Stanley–Reisner ideal
  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex

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

  * facets(SimplicialComplex) -- get the
    list of maximal faces

Finding attributes and properties -- information about accessing features of an abstract simplicial complex
***********************************************************************************************************

Having made a SimplicialComplex, one can access its
basic invariants or test for some elementary properties by using the following
methods:

Determining attributes and properties of simplicial complexes
=============================================================

  * ideal(SimplicialComplex) -- get the
    Stanley–Reisner ideal
  * monomialIdeal(SimplicialComplex)
    -- get the Stanley–Reisner monomial
    ideal
  * ring(SimplicialComplex) -- get the
    polynomial ring of its Stanley–Reisner ideal
  * coefficientRing(SimplicialComplex)
    -- get the coefficient ring of the
    underlying polynomial ring
  * dim(SimplicialComplex) -- find the
    dimension of an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional
  * vertices(SimplicialComplex) -- get
    the list of the vertices for an abstract simplicial complex
  * faces(ZZ,SimplicialComplex), --
    get the $i$-faces of an abstract simplicial complex
  * connectedComponents(SimplicialComplex)
    -- find the connected
    components of an abstract simplicial complex
  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex
  * flagfVector(List,SimplicialComplex)
    -- compute a flag $f$-number of
    a colored simplicial complex
  * isProper(SimplicialComplex), --
    whether an abstract simplicial complex is properly colored

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * Working with simplicial maps, --
    information about simplicial maps and the induced operations

flagfVector(List,SimplicialComplex) -- compute a flag $f$-number of a colored simplicial complex
************************************************************************************************

Synopsis
========

  * Function: flagfVector,
  * Usage:
        f = flagfVector(L, Delta)
  * Inputs:
      * L, a list (Macaulay2Doc),
      * Delta, an abstract simplicial complex,
  * Outputs:
      * an integer (Macaulay2Doc), the flag f-number corresponding to
        the color set determined by L

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

A coloring of an abstract simplicial complex $\Delta$ is a labelling of its
vertices with colors.  The color set of a face is the set of colors of its
vertices.  Given a set of colors $L$, the flag $f$-number $f_L(\Delta)$ is the
number of faces with color set $L$.  In this package, a coloring of an abstract
simplicial complex is determined by a multigrading of its ambient ring.

If we color the $2$-simplex with distinct colors, each color set corresponds to
a unique face.

+--------------------------------------+
|i1 : S = QQ[a,b,c, DegreeRank => 3];  |
+--------------------------------------+
|i2 : degrees S                        |
|                                      |
|o2 = {{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}|
|                                      |
|o2 : List                             |
+--------------------------------------+
|i3 : Δ = simplexComplex(2, S)         |
|                                      |
|o3 = simplicialComplex | abc |        |
|                                      |
|o3 : SimplicialComplex                |
+--------------------------------------+
|i4 : flagfVector({0,0,0}, Δ)          |
|                                      |
|o4 = 1                                |
+--------------------------------------+
|i5 : flagfVector({1,0,0}, Δ)          |
|                                      |
|o5 = 1                                |
+--------------------------------------+
|i6 : flagfVector({0,1,0}, Δ)          |
|                                      |
|o6 = 1                                |
+--------------------------------------+
|i7 : flagfVector({0,0,1}, Δ)          |
|                                      |
|o7 = 1                                |
+--------------------------------------+
|i8 : flagfVector({0,1,1}, Δ)          |
|                                      |
|o8 = 1                                |
+--------------------------------------+
|i9 : flagfVector({1,0,1}, Δ)          |
|                                      |
|o9 = 1                                |
+--------------------------------------+
|i10 : flagfVector({1,1,0}, Δ)         |
|                                      |
|o10 = 1                               |
+--------------------------------------+
|i11 : flagfVector({1,1,1}, Δ)         |
|                                      |
|o11 = 1                               |
+--------------------------------------+

A coloring is proper if no two vertices in the same face have the same color.
The bowtie complex has a proper $3$-coloring.

+-------------------------------------------------------------------------+
|i12 : R = ZZ[a..e, Degrees => {{1,0,0},{0,1,0},{0,0,1},{1,0,0},{0,1,0}}];|
+-------------------------------------------------------------------------+
|i13 : Γ = simplicialComplex {a*b*c, c*d*e}                               |
|                                                                         |
|o13 = simplicialComplex | cde abc |                                      |
|                                                                         |
|o13 : SimplicialComplex                                                  |
+-------------------------------------------------------------------------+
|i14 : assert isProper Γ                                                  |
+-------------------------------------------------------------------------+
|i15 : flagfVector({0,0,0}, Γ)                                            |
|                                                                         |
|o15 = 1                                                                  |
+-------------------------------------------------------------------------+
|i16 : flagfVector({1,0,0}, Γ)                                            |
|                                                                         |
|o16 = 2                                                                  |
+-------------------------------------------------------------------------+
|i17 : flagfVector({0,1,0}, Γ)                                            |
|                                                                         |
|o17 = 2                                                                  |
+-------------------------------------------------------------------------+
|i18 : flagfVector({0,0,1}, Γ)                                            |
|                                                                         |
|o18 = 1                                                                  |
+-------------------------------------------------------------------------+
|i19 : flagfVector({0,1,1}, Γ)                                            |
|                                                                         |
|o19 = 2                                                                  |
+-------------------------------------------------------------------------+
|i20 : flagfVector({1,0,1}, Γ)                                            |
|                                                                         |
|o20 = 2                                                                  |
+-------------------------------------------------------------------------+
|i21 : flagfVector({1,1,0}, Γ)                                            |
|                                                                         |
|o21 = 2                                                                  |
+-------------------------------------------------------------------------+
|i22 : flagfVector({1,1,1}, Γ)                                            |
|                                                                         |
|o22 = 2                                                                  |
+-------------------------------------------------------------------------+

The method function $\operatorname{flagfVector}$ does not check whether the
multigrading on ambient ring determines a proper coloring.

The flag $f$-vector is computed as the multigraded Hilbert function of the
quotient of an exterior algebra by the corresponding Stanley–Reisner ideal.

Caveat
======

Not every grading of the ambient polynomial ring corresponds to a coloring.

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * flagfVector(SimplicialComplex),
    -- compute the flag $f$-vector of an colored simplicial complex
  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex
  * isProper(SimplicialComplex), --
    whether an abstract simplicial complex is properly colored
  * algebraicShifting(SimplicialComplex) -- the
    algebraic shifting of a simplicial complex

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

  * flagfVector(List,SimplicialComplex)
    -- compute a flag $f$-number of
    a colored simplicial complex

flagfVector(SimplicialComplex) -- compute the flag $f$-vector of an colored simplicial complex
**********************************************************************************************

Synopsis
========

  * Function: flagfVector,
  * Usage:
        f = flagfVector Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * f, a hash table (Macaulay2Doc), where each key
        determines a color sets and the value is the flag f-number
        corresponding to that color set.

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

A coloring of an abstract simplicial complex $\Delta$ is a labelling of its
vertices with colors.  The color set of a face is the set of colors of its
vertices.  Given a set of colors $L$, the flag $f$-number $f_L(\Delta)$ is the
number of faces with color set $L$.  In this package, a coloring of an abstract
simplicial complex is determined by a multigrading of its ambient ring.
This method function returns a hashtable whose
keys are color sets (or more generally multidegrees) and whose values are the
corresponding flag $f$-number.

If we color the $2$-simplex with distinct colors, each color set corresponds to
a unique face.

+--------------------------------------+
|i1 : S = QQ[a,b,c, DegreeRank => 3];  |
+--------------------------------------+
|i2 : degrees S                        |
|                                      |
|o2 = {{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}|
|                                      |
|o2 : List                             |
+--------------------------------------+
|i3 : Δ = simplexComplex(2, S)         |
|                                      |
|o3 = simplicialComplex | abc |        |
|                                      |
|o3 : SimplicialComplex                |
+--------------------------------------+
|i4 : flagfVector Δ                    |
|                                      |
|o4 = HashTable{{0, 0, 0} => 1}        |
|               {0, 0, 1} => 1         |
|               {0, 1, 0} => 1         |
|               {0, 1, 1} => 1         |
|               {1, 0, 0} => 1         |
|               {1, 0, 1} => 1         |
|               {1, 1, 0} => 1         |
|               {1, 1, 1} => 1         |
|                                      |
|o4 : HashTable                        |
+--------------------------------------+

A coloring is proper if no two vertices in the same face have the same color.
The bowtie complex has a proper $3$-coloring.

+------------------------------------------------------------------------+
|i5 : R = ZZ[a..e, Degrees => {{1,0,0},{0,1,0},{0,0,1},{1,0,0},{0,1,0}}];|
+------------------------------------------------------------------------+
|i6 : Γ = simplicialComplex {a*b*c, c*d*e}                               |
|                                                                        |
|o6 = simplicialComplex | cde abc |                                      |
|                                                                        |
|o6 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i7 : assert isProper Γ                                                  |
+------------------------------------------------------------------------+
|i8 : flagfVector Γ                                                      |
|                                                                        |
|o8 = HashTable{{0, 0, 0} => 1}                                          |
|               {0, 0, 1} => 1                                           |
|               {0, 1, 0} => 2                                           |
|               {0, 1, 1} => 2                                           |
|               {1, 0, 0} => 2                                           |
|               {1, 0, 1} => 2                                           |
|               {1, 1, 0} => 2                                           |
|               {1, 1, 1} => 2                                           |
|                                                                        |
|o8 : HashTable                                                          |
+------------------------------------------------------------------------+

We can compute $i$-th entry of the $f$-vector of $\Delta$ by taking the taking
the sum of the flag $f$-numbers over color sets of size $i+1$.

+--------------------------------------------------------------------+
|i9 : fVector Γ                                                      |
|                                                                    |
|o9 = {1, 5, 6, 2}                                                   |
|                                                                    |
|o9 : List                                                           |
+--------------------------------------------------------------------+
|i10 : apply(toList(-1..dim Γ), i -> (                               |
|          F := flagfVector Γ;                                       |
|          sum for L in keys F list if sum L == i+1 then F#L else 0))|
|                                                                    |
|o10 = {1, 5, 6, 2}                                                  |
|                                                                    |
|o10 : List                                                          |
+--------------------------------------------------------------------+
|i11 : assert(oo === fVector Γ)                                      |
+--------------------------------------------------------------------+

The method function $\operatorname{flagfVector}$ does not check whether the
multigrading on ambient ring determines a proper coloring.

The flag $f$-vector is computed as the multigraded Hilbert function of the
quotient of an exterior algebra by the corresponding Stanley–Reisner ideal.

Caveat
======

Not every grading of the ambient polynomial ring corresponds to a coloring.

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * flagfVector(List,SimplicialComplex)
    -- compute a flag $f$-number of
    a colored simplicial complex
  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex
  * isProper(SimplicialComplex), --
    whether an abstract simplicial complex is properly colored
  * algebraicShifting(SimplicialComplex) -- the
    algebraic shifting of a simplicial complex

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

  * flagfVector(SimplicialComplex),
    -- compute the flag $f$-vector of an colored simplicial complex

fVector(SimplicialComplex) -- compute the f-vector of an abstract simplicial complex
************************************************************************************

Synopsis
========

  * Function: fVector (Polyhedra),
  * Usage:
        f = fVector Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * f, a list (Macaulay2Doc), where the $i$-th entry is the
        number of faces in $\Delta$ of dimension $i-1$ and $0 \leqslant i
        \leqslant \operatorname{dim} \Delta$

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

The f-vector of an abstract simplicial complex is the vector $(f_{-1}, f_0,
f_1, \dotsc, f_d)$ of nonnegative integers such that $f_i$ is the number of
$i$-dimensional faces in the simplicial complex.

Since the $i$-dimensional faces of the simplex,
correspond to all subsets of vertices
that have cardinality $i+1$, the entries in the f-vector of the simplex are all
binomial coefficients.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_6];                                                       |
+-----------------------------------------------------------------------------+
|i2 : netList for n from -1 to 6 list fVector simplexComplex(n, S)            |
|                                                                             |
|     +-+-+--+--+--+--+-+-+                                                   |
|o2 = |1| |  |  |  |  | | |                                                   |
|     +-+-+--+--+--+--+-+-+                                                   |
|     |1|1|  |  |  |  | | |                                                   |
|     +-+-+--+--+--+--+-+-+                                                   |
|     |1|2|1 |  |  |  | | |                                                   |
|     +-+-+--+--+--+--+-+-+                                                   |
|     |1|3|3 |1 |  |  | | |                                                   |
|     +-+-+--+--+--+--+-+-+                                                   |
|     |1|4|6 |4 |1 |  | | |                                                   |
|     +-+-+--+--+--+--+-+-+                                                   |
|     |1|5|10|10|5 |1 | | |                                                   |
|     +-+-+--+--+--+--+-+-+                                                   |
|     |1|6|15|20|15|6 |1| |                                                   |
|     +-+-+--+--+--+--+-+-+                                                   |
|     |1|7|21|35|35|21|7|1|                                                   |
|     +-+-+--+--+--+--+-+-+                                                   |
+-----------------------------------------------------------------------------+
|i3 : assert all(1..7, i -> (fVector simplexComplex(6,S))#i === binomial(7,i))|
+-----------------------------------------------------------------------------+

Our classic examples of abstract simplicial complexes illustrate more
possibilities.

+-------------------------------------+
|i4 : S = ZZ[x_1..x_16];              |
+-------------------------------------+
|i5 : fVector bartnetteSphereComplex S|
|                                     |
|o5 = {1, 8, 27, 38, 19}              |
|                                     |
|o5 : List                            |
+-------------------------------------+
|i6 : fVector bjornerComplex S        |
|                                     |
|o6 = {1, 6, 15, 11}                  |
|                                     |
|o6 : List                            |
+-------------------------------------+
|i7 : fVector dunceHatComplex S       |
|                                     |
|o7 = {1, 8, 24, 17}                  |
|                                     |
|o7 : List                            |
+-------------------------------------+
|i8 : fVector poincareSphereComplex S |
|                                     |
|o8 = {1, 16, 106, 180, 90}           |
|                                     |
|o8 : List                            |
+-------------------------------------+
|i9 : fVector rudinBallComplex S      |
|                                     |
|o9 = {1, 14, 66, 94, 41}             |
|                                     |
|o9 : List                            |
+-------------------------------------+

There are two "trivial" simplicial complexes: the irrelevant complex has the
empty set as a facet whereas the void complex has no faces.  Every abstract
simplicial complex other than the void complex has a unique face of dimension
$-1$.

+---------------------------------------------------------+
|i10 : irrelevant = simplicialComplex monomialIdeal gens S|
|                                                         |
|o10 = simplicialComplex | 1 |                            |
|                                                         |
|o10 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i11 : fVector irrelevant                                 |
|                                                         |
|o11 = {1}                                                |
|                                                         |
|o11 : List                                               |
+---------------------------------------------------------+
|i12 : assert(fVector irrelevant === {1})                 |
+---------------------------------------------------------+
|i13 : void = simplicialComplex monomialIdeal 1_S         |
|                                                         |
|o13 = simplicialComplex 0                                |
|                                                         |
|o13 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i14 : fVector void                                       |
|                                                         |
|o14 = {0}                                                |
|                                                         |
|o14 : List                                               |
+---------------------------------------------------------+
|i15 : assert(fVector void === {0})                       |
+---------------------------------------------------------+

The f-vector is computed as the Hilbert function of the quotient of an exterior
algebra by the corresponding Stanley–Reisner ideal.

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * dim(SimplicialComplex) -- find the
    dimension of an abstract simplicial complex
  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex

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

  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex

grunbaumBallComplex(PolynomialRing) -- make a nonshellable 3-ball with 14 vertices and 29 facets
************************************************************************************************

Synopsis
========

  * Function: grunbaumBallComplex,
  * Usage:
        grunbaumBallComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that has at
        least 14 generators
  * Outputs:
      * an abstract simplicial complex,

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

Attributed to F. Alberto Grünbaum, this method returns a triangulation of a
3-ball with 14 vertices and 29 facets that is not shellable (see
https://en.wikipedia.org/wiki/Shelling_(topology) ).

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/101[a..s];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = grunbaumBallComplex S;                                              |
+-----------------------------------------------------------------------------+
|i3 : matrix {facets Δ}                                                       |
|                                                                             |
|o3 = | hlmn elmn gkmn fkmn ghmn efmn bhln beln ghjn fhjn bfhn befn agkm afkm |
|     ------------------------------------------------------------------------|
|     ghim egim aegm aefm aghj dfhj adhj bghi cegi bcgi abgh bdfh abdh aceg   |
|     ------------------------------------------------------------------------|
|     abcg |                                                                  |
|                                                                             |
|             1       29                                                      |
|o3 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i4 : dim Δ                                                                   |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : fVector Δ                                                               |
|                                                                             |
|o5 = {1, 14, 54, 70, 29}                                                     |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : assert(dim Δ === 3 and isPure Δ)                                        |
+-----------------------------------------------------------------------------+
|i7 : assert(fVector Δ === {1,14,54,70,29})                                   |
+-----------------------------------------------------------------------------+

This abstract simplicial complex is Cohen-Macaulay but not shellable.

Our enumeration of the vertices follows the gruenbaum (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/gruenbaum_eng.html )
example in Masahiro Hachimori's simplicial complex library (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/index_eng.html ).

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * rudinBallComplex -- make a
    nonshellable 3-ball with 14 vertices and 41 facets
  * zieglerBallComplex -- make a
    nonshellable 3-ball with 10 vertices and 21 facets
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional

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

  * grunbaumBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with
    14 vertices and 29 facets

HH SimplicialMap -- Compute the induced map on homology of a simplicial map.
****************************************************************************

Synopsis
========

  * Function: homology (Macaulay2Doc),
  * Usage:
        homology f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * a graded module map (Macaulay2Doc), which is the
        map on homology induced by $f$

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

The graded module map from the homology of the source of $f$ to the homology of
the target of $f$. As an example, we map a circle into the torus in two ways,
and we get two distinct maps in homology.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_6];                                                       |
+-----------------------------------------------------------------------------+
|i2 : R = ZZ[y_0..y_2];                                                       |
+-----------------------------------------------------------------------------+
|i3 : Torus = smallManifold(2,7,6,S);                                         |
+-----------------------------------------------------------------------------+
|i4 : Circle = simplicialComplex{R_0*R_1, R_0*R_2, R_1*R_2};                  |
+-----------------------------------------------------------------------------+
|i5 : f1 = map(Torus,Circle,matrix{{S_3,S_6,S_5}});                           |
|                                                                             |
|o5 : SimplicialMap simplicialComplex | x_2x_5x_6 x_0x_5x_6 x_1x_4x_6         |
|-----------------------------------------------------------------------------|
|x_0x_4x_6 x_2x_3x_6 x_1x_3x_6 x_3x_4x_5 x_1x_4x_5 x_0x_3x_5 x_1x_2x_5        |
|-----------------------------------------------------------------------------|
|x_2x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | y_1y_2    |
|-----------------------------------------------------------------------------|
|y_0y_2 y_0y_1 |                                                              |
+-----------------------------------------------------------------------------+
|i6 : f2 = map(Torus,Circle,matrix{{S_0,S_2,S_3}});                           |
|                                                                             |
|o6 : SimplicialMap simplicialComplex | x_2x_5x_6 x_0x_5x_6 x_1x_4x_6         |
|-----------------------------------------------------------------------------|
|x_0x_4x_6 x_2x_3x_6 x_1x_3x_6 x_3x_4x_5 x_1x_4x_5 x_0x_3x_5 x_1x_2x_5        |
|-----------------------------------------------------------------------------|
|x_2x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | y_1y_2    |
|-----------------------------------------------------------------------------|
|y_0y_2 y_0y_1 |                                                              |
+-----------------------------------------------------------------------------+
|i7 : prune homology f1                                                       |
|                                                                             |
|o7 = -1: 0 <--0-- 0 :-1                                                      |
|                                                                             |
|     0: 0 <--0-- 0 :0                                                        |
|                                                                             |
|          2              1                                                   |
|     1: ZZ  <--| 1 |-- ZZ  :1                                                |
|               | 0 |                                                         |
|                                                                             |
|          1                                                                  |
|     2: ZZ  <--0-- 0 :2                                                      |
|                                                                             |
|o7 : GradedModuleMap                                                         |
+-----------------------------------------------------------------------------+
|i8 : prune homology f2                                                       |
|                                                                             |
|o8 = -1: 0 <--0-- 0 :-1                                                      |
|                                                                             |
|     0: 0 <--0-- 0 :0                                                        |
|                                                                             |
|          2              1                                                   |
|     1: ZZ  <--| 0 |-- ZZ  :1                                                |
|               | 1 |                                                         |
|                                                                             |
|          1                                                                  |
|     2: ZZ  <--0-- 0 :2                                                      |
|                                                                             |
|o8 : GradedModuleMap                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes
  * HH_ZZ SimplicialMap -- Compute the induced
    map on homology of a simplicial map.
  * homology(SimplicialComplex,Ring)
    -- compute the reduced homology of
    an abstract simplicial complex
  * HH_ZZ SimplicialComplex, --
    compute the reduced homology of an abstract simplicial complex
  * homology(SimplicialComplex,SimplicialComplex)
    -- compute the
    relative homology of two simplicial complexes

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

  * HH SimplicialMap -- Compute the induced map on
    homology of a simplicial map.
  * "homology(Nothing,SimplicialMap)"

HH^ZZ SimplicialMap -- Compute the induced map on cohomology of a simplicial map.
*********************************************************************************

Synopsis
========

  * Function: cohomology (Macaulay2Doc),
  * Usage:
        cohomology(i,f)
  * Inputs:
      * i, an integer (Macaulay2Doc),
      * f, a map of abstract simplicial complexes,
  * Optional inputs (Macaulay2Doc),:
      * Degree, => an
        integer (Macaulay2Doc), default value 0, which is ignored by
        this particular function
  * Outputs:
      * a matrix (Macaulay2Doc), which is the induced map on
        cohomology

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

The map from the $i$-th cohomology of the source of $f$ to the $i$-th
cohomology of the target of $f$. As an example, we map a circle into the torus
in two ways, and we get two distinct maps in cohomology.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_6];                                                       |
+-----------------------------------------------------------------------------+
|i2 : R = ZZ[y_0..y_2];                                                       |
+-----------------------------------------------------------------------------+
|i3 : Torus = smallManifold(2,7,6,S);                                         |
+-----------------------------------------------------------------------------+
|i4 : Circle = simplicialComplex{R_0*R_1, R_0*R_2, R_1*R_2};                  |
+-----------------------------------------------------------------------------+
|i5 : f1 = map(Torus,Circle,matrix{{S_3,S_6,S_5}});                           |
|                                                                             |
|o5 : SimplicialMap simplicialComplex | x_2x_5x_6 x_0x_5x_6 x_1x_4x_6         |
|-----------------------------------------------------------------------------|
|x_0x_4x_6 x_2x_3x_6 x_1x_3x_6 x_3x_4x_5 x_1x_4x_5 x_0x_3x_5 x_1x_2x_5        |
|-----------------------------------------------------------------------------|
|x_2x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | y_1y_2    |
|-----------------------------------------------------------------------------|
|y_0y_2 y_0y_1 |                                                              |
+-----------------------------------------------------------------------------+
|i6 : f2 = map(Torus,Circle,matrix{{S_0,S_2,S_3}});                           |
|                                                                             |
|o6 : SimplicialMap simplicialComplex | x_2x_5x_6 x_0x_5x_6 x_1x_4x_6         |
|-----------------------------------------------------------------------------|
|x_0x_4x_6 x_2x_3x_6 x_1x_3x_6 x_3x_4x_5 x_1x_4x_5 x_0x_3x_5 x_1x_2x_5        |
|-----------------------------------------------------------------------------|
|x_2x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | y_1y_2    |
|-----------------------------------------------------------------------------|
|y_0y_2 y_0y_1 |                                                              |
+-----------------------------------------------------------------------------+
|i7 : prune cohomology(1, f1)                                                 |
|                                                                             |
|o7 = | 1 -2 |                                                                |
|                                                                             |
|              1        2                                                     |
|o7 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i8 : prune cohomology(1, f2)                                                 |
|                                                                             |
|o8 = | 0 1 |                                                                 |
|                                                                             |
|              1        2                                                     |
|o8 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * HH^ZZ SimplicialComplex, --
    compute the reduced cohomology of an abstract simplicial complex
  * HH^ZZ(SimplicialComplex,SimplicialComplex)
    -- compute the relative
    homology of two simplicial complexes

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

  * HH^ZZ SimplicialMap -- Compute the induced map
    on cohomology of a simplicial map.

HH^ZZ(SimplicialComplex,Ring) -- compute the reduced cohomology of an abstract simplicial complex
*************************************************************************************************

Synopsis
========

  * Function: cohomology (Macaulay2Doc),
  * Usage:
        cohomology(k, Delta, R)
  * Inputs:
      * k, an integer (Macaulay2Doc),
      * Delta, an abstract simplicial complex,
      * R, a ring (Macaulay2Doc), that when omitted is equal to the
        underlying ring, of $\Delta$
  * Optional inputs (Macaulay2Doc),:
      * Degree, => an
        integer (Macaulay2Doc), default value 0, is ignored by this
        particular function
  * Outputs:
      * a module (Macaulay2Doc), that is reduced cohomology group
        of $\Delta$ with coefficients in $R$

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

Each abstract simplicial complex $\Delta$ determines a chain complex
$\widetilde C(\Delta, k)$ of free modules over its coefficient ring $k$. For
all integers $i$, the $i$-th term of $\widetilde C(\Delta, k)$ has a basis
corresponding to the $i$-dimensional faces of $\Delta$. The reduced cohomology
of $\Delta$ with coefficients in $R$ is, by definition, the cohomology of the
chain complex $\operatorname{Hom}( \widetilde C(\Delta, k) \otimes R, R)$.

The 2-sphere has vanishing first cohomology, but non-trivial second cohomology.

+------------------------------------------+
|i1 : S = ZZ[x_0..x_4];                    |
+------------------------------------------+
|i2 : Δ = skeleton(2, simplexComplex(3,S));|
+------------------------------------------+
|i3 : prune cohomology(1, Δ)               |
|                                          |
|o3 = 0                                    |
|                                          |
|o3 : ZZ-module                            |
+------------------------------------------+
|i4 : prune cohomology(2, Δ)               |
|                                          |
|       1                                  |
|o4 = ZZ                                   |
|                                          |
|o4 : ZZ-module, free                      |
+------------------------------------------+

A figure eight has rank two first cohomology.

+-----------------------------------------------------------------------------+
|i5 : figureEight = simplicialComplex {x_0*x_1, x_0*x_2, x_1*x_2, x_2*x_3,    |
|                                                                             |
|o5 = simplicialComplex | x_3x_4 x_2x_4 x_2x_3 x_1x_2 x_0x_2 x_0x_1 |         |
|                                                                             |
|o5 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_2*x_4, x_3*x_4}                                                            |
+-----------------------------------------------------------------------------+
|i6 : prune cohomology(1, figureEight)                                        |
|                                                                             |
|       2                                                                     |
|o6 = ZZ                                                                      |
|                                                                             |
|o6 : ZZ-module, free                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * HH^ZZ(SimplicialComplex,Ring),
    -- compute the reduced cohomology of an abstract simplicial complex
  * boundaryMap -- make a
    boundary map between the oriented faces of an abstract simplicial complex
  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.
  * HH^ZZ(SimplicialComplex,SimplicialComplex)
    -- compute the relative
    homology of two simplicial complexes

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

  * "HH^ZZ SimplicialComplex"
  * HH^ZZ(SimplicialComplex,Ring),
    -- compute the reduced cohomology of an abstract simplicial complex

HH^ZZ(SimplicialComplex,SimplicialComplex) -- compute the relative homology of two simplicial complexes
*******************************************************************************************************

Synopsis
========

  * Function: cohomology (Macaulay2Doc),
  * Usage:
        cohomology(k,D,E)
  * Inputs:
      * k, an integer (Macaulay2Doc),
      * D, an abstract simplicial complex,
      * E, an abstract simplicial complex,
  * Optional inputs (Macaulay2Doc),:
      * Degree => an integer (Macaulay2Doc), default value 0, this
        option is ignored by this particular function
  * Outputs:
      * a module (Macaulay2Doc),

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

This method computes the relative cohomology of a simplicial complex $D$
contracted along a subcomplex $E$.

Contracting an edge of a hexagon will not change the cohomology.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ[x_0..x_5];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Hexagon = simplicialComplex {x_0*x_1,x_1*x_2,x_2*x_3,x_3*x_4,x_4*x_5,x_5|
|                                                                             |
|o2 = simplicialComplex | x_4x_5 x_0x_5 x_3x_4 x_2x_3 x_1x_2 x_0x_1 |         |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|*x_0}                                                                        |
+-----------------------------------------------------------------------------+
|i3 : Edge = simplicialComplex {x_0*x_1}                                      |
|                                                                             |
|o3 = simplicialComplex | x_0x_1 |                                            |
|                                                                             |
|o3 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i4 : prune cohomology(1, Hexagon)                                            |
|                                                                             |
|       1                                                                     |
|o4 = ZZ                                                                      |
|                                                                             |
|o4 : ZZ-module, free                                                         |
+-----------------------------------------------------------------------------+
|i5 : prune cohomology(1, Hexagon, Edge) == prune cohomology(1,Hexagon)       |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

Gluing two antipodal points on a sphere introduces a non-trivial loop.

+-----------------------------------------------------------------------------+
|i6 : S = ZZ[y_0..y_4];                                                       |
+-----------------------------------------------------------------------------+
|i7 : Sphere = simplicialComplex {y_0*y_1*y_3, y_0*y_2*y_3, y_1*y_2*y_3,      |
|                                 y_0*y_1*y_4, y_0*y_2*y_4, y_1*y_2*y_4}      |
|                                                                             |
|o7 = simplicialComplex | y_1y_2y_4 y_0y_2y_4 y_0y_1y_4 y_1y_2y_3 y_0y_2y_3   |
|                                                                             |
|o7 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|y_0y_1y_3 |                                                                  |
+-----------------------------------------------------------------------------+
|i8 : prune cohomology(1, Sphere)                                             |
|                                                                             |
|o8 = 0                                                                       |
|                                                                             |
|o8 : ZZ-module                                                               |
+-----------------------------------------------------------------------------+
|i9 : Poles = simplicialComplex {y_3, y_4}                                    |
|                                                                             |
|o9 = simplicialComplex | y_4 y_3 |                                           |
|                                                                             |
|o9 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i10 : prune cohomology(1, Sphere, Poles)                                     |
|                                                                             |
|        1                                                                    |
|o10 = ZZ                                                                     |
|                                                                             |
|o10 : ZZ-module, free                                                        |
+-----------------------------------------------------------------------------+

This method assumes that $E$ is a subcomplex $D$, and may still run
nonsensically. Note also that the complexes need not be defined over the same
ring.

+-----------------------------------------------------------------------------+
|i11 : T = ZZ[z_0..z_5];                                                      |
+-----------------------------------------------------------------------------+
|i12 : Fish = simplicialComplex {z_0*z_1, z_1*z_2, z_2*z_3, z_3*z_0,          |
|                                z_0*z_4, z_0*z_5, z_4*z_5}                   |
|                                                                             |
|o12 = simplicialComplex | z_4z_5 z_0z_5 z_0z_4 z_2z_3 z_0z_3 z_1z_2 z_0z_1 | |
|                                                                             |
|o12 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i13 : prune cohomology(1, Fish, Hexagon)                                     |
|                                                                             |
|        2                                                                    |
|o13 = ZZ                                                                     |
|                                                                             |
|o13 : ZZ-module, free                                                        |
+-----------------------------------------------------------------------------+
|i14 : inclusion = map(Hexagon, Fish, gens ring Hexagon);                     |
|                                                                             |
|o14 : SimplicialMap simplicialComplex | x_4x_5 x_0x_5 x_3x_4 x_2x_3 x_1x_2   |
|-----------------------------------------------------------------------------|
|x_0x_1 | <--- simplicialComplex | z_4z_5 z_0z_5 z_0z_4 z_2z_3 z_0z_3 z_1z_2  |
|-----------------------------------------------------------------------------|
|z_0z_1 |                                                                     |
+-----------------------------------------------------------------------------+
|i15 : isWellDefined inclusion                                                |
|                                                                             |
|o15 = false                                                                  |
+-----------------------------------------------------------------------------+

Caveat
======

This method does not check if $E$ is contained in $D$.

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * HH^ZZ SimplicialComplex, --
    compute the reduced cohomology of an abstract simplicial complex
  * HH_ZZ(SimplicialComplex,SimplicialComplex)
    -- compute the
    relative homology of two simplicial complexes

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

  * HH^ZZ(SimplicialComplex,SimplicialComplex)
    -- compute the relative
    homology of two simplicial complexes

HH_ZZ SimplicialMap -- Compute the induced map on homology of a simplicial map.
*******************************************************************************

Synopsis
========

  * Function: homology (Macaulay2Doc),
  * Usage:
        homology(i,f)
  * Inputs:
      * i, an integer (Macaulay2Doc),
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * a matrix (Macaulay2Doc), which is the induced map on
        homology

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

The map from the $i$-th homology of the source of $f$ to the $i$-th homology of
the target of $f$. As an example, we map a circle into the torus in two ways,
and we get two distinct maps in homology.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_6];                                                       |
+-----------------------------------------------------------------------------+
|i2 : R = ZZ[y_0..y_2];                                                       |
+-----------------------------------------------------------------------------+
|i3 : Torus = smallManifold(2,7,6,S);                                         |
+-----------------------------------------------------------------------------+
|i4 : Circle = simplicialComplex{R_0*R_1, R_0*R_2, R_1*R_2};                  |
+-----------------------------------------------------------------------------+
|i5 : f1 = map(Torus,Circle,matrix{{S_3,S_6,S_5}});                           |
|                                                                             |
|o5 : SimplicialMap simplicialComplex | x_2x_5x_6 x_0x_5x_6 x_1x_4x_6         |
|-----------------------------------------------------------------------------|
|x_0x_4x_6 x_2x_3x_6 x_1x_3x_6 x_3x_4x_5 x_1x_4x_5 x_0x_3x_5 x_1x_2x_5        |
|-----------------------------------------------------------------------------|
|x_2x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | y_1y_2    |
|-----------------------------------------------------------------------------|
|y_0y_2 y_0y_1 |                                                              |
+-----------------------------------------------------------------------------+
|i6 : f2 = map(Torus,Circle,matrix{{S_0,S_2,S_3}});                           |
|                                                                             |
|o6 : SimplicialMap simplicialComplex | x_2x_5x_6 x_0x_5x_6 x_1x_4x_6         |
|-----------------------------------------------------------------------------|
|x_0x_4x_6 x_2x_3x_6 x_1x_3x_6 x_3x_4x_5 x_1x_4x_5 x_0x_3x_5 x_1x_2x_5        |
|-----------------------------------------------------------------------------|
|x_2x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | y_1y_2    |
|-----------------------------------------------------------------------------|
|y_0y_2 y_0y_1 |                                                              |
+-----------------------------------------------------------------------------+
|i7 : prune homology(1, f1)                                                   |
|                                                                             |
|o7 = | 1 |                                                                   |
|     | 0 |                                                                   |
|                                                                             |
|              2        1                                                     |
|o7 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i8 : prune homology(1, f2)                                                   |
|                                                                             |
|o8 = | 0 |                                                                   |
|     | 1 |                                                                   |
|                                                                             |
|              2        1                                                     |
|o8 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes
  * HH_ZZ SimplicialMap -- Compute the induced
    map on homology of a simplicial map.
  * homology(SimplicialComplex,Ring)
    -- compute the reduced homology of
    an abstract simplicial complex
  * HH_ZZ SimplicialComplex, --
    compute the reduced homology of an abstract simplicial complex
  * homology(SimplicialComplex,SimplicialComplex)
    -- compute the
    relative homology of two simplicial complexes

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

  * HH_ZZ SimplicialMap -- Compute the induced
    map on homology of a simplicial map.

HH_ZZ(SimplicialComplex,Ring) -- compute the reduced homology of an abstract simplicial complex
***********************************************************************************************

Synopsis
========

  * Function: homology (Macaulay2Doc),
  * Usage:
        homology(i, Delta, R)
  * Inputs:
      * i, an integer (Macaulay2Doc),
      * Delta, an abstract simplicial complex,
      * R, a ring (Macaulay2Doc),
  * Outputs:
      * a module (Macaulay2Doc), that is the $i$-th reduced
        homology group of $\Delta$ with coefficients in $R$

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

Each abstract simplicial complex $\Delta$ determines a chain complex
$\widetilde C(\Delta, k)$ of free modules over its coefficient ring $k$. For
all integers $i$, the $i$-th term of $\widetilde C(\Delta, k)$ has a basis
corresponding to the $i$-dimensional faces of $\Delta$. When the optional
argument $R$ is included, the chain complex is tensored with $R$.  The reduced
homology of $\Delta$ with coefficients in $R$ is, by definition, the homology
of $\widetilde C(\Delta, k) \otimes R$.

The $2$-sphere has vanishing first homology, but non-trivial second homology.
We obtain a triangulation of the $2$-sphere by taking the $2$-skeleton of the
$3$-simplex.  Since homology groups are typically expressed as a
subquotient (Macaulay2Doc), we prune (Macaulay2Doc),
the output to obtain a minimal
presentation.

+-------------------------------------------+
|i1 : S = ZZ[a..h];                         |
+-------------------------------------------+
|i2 : Δ = skeleton(2, simplexComplex(3, S)) |
|                                           |
|o2 = simplicialComplex | bcd acd abd abc | |
|                                           |
|o2 : SimplicialComplex                     |
+-------------------------------------------+
|i3 : prune homology(0, Δ)                  |
|                                           |
|o3 = 0                                     |
|                                           |
|o3 : ZZ-module                             |
+-------------------------------------------+
|i4 : prune homology(1, Δ)                  |
|                                           |
|o4 = 0                                     |
|                                           |
|o4 : ZZ-module                             |
+-------------------------------------------+
|i5 : prune homology(2, Δ)                  |
|                                           |
|       1                                   |
|o5 = ZZ                                    |
|                                           |
|o5 : ZZ-module, free                       |
+-------------------------------------------+
|i6 : assert(homology(2, Δ) === HH_2 Δ)     |
+-------------------------------------------+
|i7 : prune homology(2, Δ, QQ)              |
|                                           |
|       1                                   |
|o7 = QQ                                    |
|                                           |
|o7 : QQ-module, free                       |
+-------------------------------------------+
|i8 : prune homology(2, Δ, ZZ/2)            |
|                                           |
|      ZZ 1                                 |
|o8 = (--)                                  |
|       2                                   |
|                                           |
|     ZZ                                    |
|o8 : ---module, free                       |
|      2                                    |
+-------------------------------------------+
|i9 : assert(prune homology(0, Δ) === ZZ^0) |
+-------------------------------------------+
|i10 : assert(prune homology(1, Δ) === ZZ^0)|
+-------------------------------------------+
|i11 : assert(prune homology(2, Δ) === ZZ^1)|
+-------------------------------------------+

The reduced homology of the Klein bottle,
has torsion.

+-----------------------------------------------------------------------------+
|i12 : Γ = kleinBottleComplex S                                               |
|                                                                             |
|o12 = simplicialComplex | cgh agh cfh afh efg dfg aeg cdg bef adf bcf cde bde|
|                                                                             |
|o12 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|ace abd abc |                                                                |
+-----------------------------------------------------------------------------+
|i13 : prune homology(0, Γ)                                                   |
|                                                                             |
|o13 = 0                                                                      |
|                                                                             |
|o13 : ZZ-module                                                              |
+-----------------------------------------------------------------------------+
|i14 : prune homology(1, Γ)                                                   |
|                                                                             |
|o14 = cokernel | 2 |                                                         |
|               | 0 |                                                         |
|                                                                             |
|                               2                                             |
|o14 : ZZ-module, quotient of ZZ                                              |
+-----------------------------------------------------------------------------+
|i15 : prune homology(1, Γ, QQ)                                               |
|                                                                             |
|        1                                                                    |
|o15 = QQ                                                                     |
|                                                                             |
|o15 : QQ-module, free                                                        |
+-----------------------------------------------------------------------------+
|i16 : prune homology(1, Γ, ZZ/2)                                             |
|                                                                             |
|       ZZ 2                                                                  |
|o16 = (--)                                                                   |
|        2                                                                    |
|                                                                             |
|      ZZ                                                                     |
|o16 : ---module, free                                                        |
|       2                                                                     |
+-----------------------------------------------------------------------------+
|i17 : assert(homology(1, Γ, ZZ/2) === HH_1(Γ, ZZ/2))                         |
+-----------------------------------------------------------------------------+
|i18 : prune homology(2, Γ)                                                   |
|                                                                             |
|o18 = 0                                                                      |
|                                                                             |
|o18 : ZZ-module                                                              |
+-----------------------------------------------------------------------------+
|i19 : assert(prune homology(0, Γ) === ZZ^0)                                  |
+-----------------------------------------------------------------------------+
|i20 : assert(prune homology(1, Γ, QQ) === QQ^1)                              |
+-----------------------------------------------------------------------------+
|i21 : assert(prune homology(1, Γ, ZZ/2) === (ZZ/2)^2)                        |
+-----------------------------------------------------------------------------+
|i22 : assert(prune homology(2, Γ) === ZZ^0)                                  |
+-----------------------------------------------------------------------------+

There are two "trivial" simplicial complexes: the irrelevant complex has the
empty set as a facet whereas the void complex has no faces.  Every abstract
simplicial complex other than the void complex has a unique face of dimension
$-1$.

+---------------------------------------------------------+
|i23 : irrelevant = simplicialComplex monomialIdeal gens S|
|                                                         |
|o23 = simplicialComplex | 1 |                            |
|                                                         |
|o23 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i24 : homology(-1, irrelevant)                           |
|                                                         |
|        1                                                |
|o24 = ZZ                                                 |
|                                                         |
|o24 : ZZ-module, free                                    |
+---------------------------------------------------------+
|i25 : assert(homology(-1, irrelevant) === ZZ^1)          |
+---------------------------------------------------------+
|i26 : void = simplicialComplex monomialIdeal 1_S         |
|                                                         |
|o26 = simplicialComplex 0                                |
|                                                         |
|o26 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i27 : homology(-1, void)                                 |
|                                                         |
|o27 = 0                                                  |
|                                                         |
|o27 : ZZ-module                                          |
+---------------------------------------------------------+
|i28 : assert(homology(-1, void) === ZZ^0)                |
+---------------------------------------------------------+

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * homology(SimplicialComplex,Ring)
    -- compute the reduced homology of
    an abstract simplicial complex
  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.
  * homology(SimplicialComplex,SimplicialComplex)
    -- compute the
    relative homology of two simplicial complexes

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

  * "HH_ZZ SimplicialComplex"
  * HH_ZZ(SimplicialComplex,Ring),
    -- compute the reduced homology of an abstract simplicial complex

homology(SimplicialComplex,Ring) -- compute the reduced homology of an abstract simplicial complex
**************************************************************************************************

Synopsis
========

  * Function: homology (Macaulay2Doc),
  * Usage:
        homology(Delta, R)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * R, a ring (Macaulay2Doc),
  * Outputs:
      * a graded module (Macaulay2Doc), that is reduced
        homology group of $\Delta$ with coefficients in $R$

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

Each abstract simplicial complex $\Delta$ determines a chain complex of free
modules over its coefficient ring.  For all integers $i$, the $i$-th term in
this chain complex has a basis corresponding to the $i$-th faces in the
simplicial complex $\Delta$.  When the optional argument $R$ is include, the
chain complex is tensored with the given ring.  The reduced homology of
$\Delta$ with coefficients in $R$ is, by definition, the homology of this chain
complex.

The $2$-sphere has vanishing first homology, but non-trivial second homology.
We obtain a triangulation of the $2$-sphere by taking the $2$-skeleton of the
$3$-simplex.  Since homology groups are typically expressed as a
subquotient (Macaulay2Doc), we prune (Macaulay2Doc),
the output to obtain a minimal
presentation.

+------------------------------------------------------+
|i1 : S = ZZ[a..h];                                    |
+------------------------------------------------------+
|i2 : Δ = skeleton(2, simplexComplex(3, S))            |
|                                                      |
|o2 = simplicialComplex | bcd acd abd abc |            |
|                                                      |
|o2 : SimplicialComplex                                |
+------------------------------------------------------+
|i3 : prune homology Δ                                 |
|                                                      |
|o3 = -1 : 0                                           |
|                                                      |
|      0 : 0                                           |
|                                                      |
|      1 : 0                                           |
|                                                      |
|            1                                         |
|      2 : ZZ                                          |
|                                                      |
|o3 : GradedModule                                     |
+------------------------------------------------------+
|i4 : prune homology(Δ, QQ)                            |
|                                                      |
|o4 = -1 : 0                                           |
|                                                      |
|      0 : 0                                           |
|                                                      |
|      1 : 0                                           |
|                                                      |
|            1                                         |
|      2 : QQ                                          |
|                                                      |
|o4 : GradedModule                                     |
+------------------------------------------------------+
|i5 : prune homology(Δ, ZZ/2)                          |
|                                                      |
|o5 = -1 : 0                                           |
|                                                      |
|      0 : 0                                           |
|                                                      |
|      1 : 0                                           |
|                                                      |
|           ZZ 1                                       |
|      2 : (--)                                        |
|            2                                         |
|                                                      |
|o5 : GradedModule                                     |
+------------------------------------------------------+
|i6 : assert(homology Δ == HH Δ)                       |
+------------------------------------------------------+
|i7 : assert(prune homology Δ == gradedModule ZZ^1[-2])|
+------------------------------------------------------+

The reduced homology of the Klein bottle,
has torsion.

+-----------------------------------------------------------------------------+
|i8 : Γ = kleinBottleComplex S                                                |
|                                                                             |
|o8 = simplicialComplex | cgh agh cfh afh efg dfg aeg cdg bef adf bcf cde bde |
|                                                                             |
|o8 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|ace abd abc |                                                                |
+-----------------------------------------------------------------------------+
|i9 : prune homology Γ                                                        |
|                                                                             |
|o9 = -1 : 0                                                                  |
|                                                                             |
|      0 : 0                                                                  |
|                                                                             |
|      1 : cokernel | 2 |                                                     |
|                   | 0 |                                                     |
|                                                                             |
|      2 : 0                                                                  |
|                                                                             |
|o9 : GradedModule                                                            |
+-----------------------------------------------------------------------------+
|i10 : prune homology(Γ, QQ)                                                  |
|                                                                             |
|o10 = -1 : 0                                                                 |
|                                                                             |
|       0 : 0                                                                 |
|                                                                             |
|             1                                                               |
|       1 : QQ                                                                |
|                                                                             |
|       2 : 0                                                                 |
|                                                                             |
|o10 : GradedModule                                                           |
+-----------------------------------------------------------------------------+
|i11 : prune homology(Γ, ZZ/2)                                                |
|                                                                             |
|o11 = -1 : 0                                                                 |
|                                                                             |
|       0 : 0                                                                 |
|                                                                             |
|            ZZ 2                                                             |
|       1 : (--)                                                              |
|             2                                                               |
|                                                                             |
|            ZZ 1                                                             |
|       2 : (--)                                                              |
|             2                                                               |
|                                                                             |
|o11 : GradedModule                                                           |
+-----------------------------------------------------------------------------+
|i12 : assert(prune homology(Γ, ZZ/2) == gradedModule((ZZ/2)^2[-1] ++         |
|-----------------------------------------------------------------------------|
|(ZZ/2)^1[-2]))                                                               |
+-----------------------------------------------------------------------------+

There are two "trivial" simplicial complexes: the irrelevant complex has the
empty set as a facet whereas the void complex has no faces.  Every abstract
simplicial complex other than the void complex has a unique face of dimension
$-1$.

+---------------------------------------------------------+
|i13 : irrelevant = simplicialComplex monomialIdeal gens S|
|                                                         |
|o13 = simplicialComplex | 1 |                            |
|                                                         |
|o13 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i14 : homology irrelevant                                |
|                                                         |
|             1                                           |
|o14 = -1 : ZZ                                            |
|                                                         |
|o14 : GradedModule                                       |
+---------------------------------------------------------+
|i15 : assert(homology irrelevant == gradedModule ZZ^1[1])|
+---------------------------------------------------------+
|i16 : void = simplicialComplex monomialIdeal 1_S         |
|                                                         |
|o16 = simplicialComplex 0                                |
|                                                         |
|o16 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i17 : homology void                                      |
|                                                         |
|o17 = 0 : 0                                              |
|                                                         |
|o17 : GradedModule                                       |
+---------------------------------------------------------+
|i18 : assert(homology void == gradedModule ZZ^0[0])      |
+---------------------------------------------------------+

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * HH_ZZ(SimplicialComplex,Ring),
    -- compute the reduced homology of an abstract simplicial complex
  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.
  * homology(SimplicialComplex,SimplicialComplex)
    -- compute the
    relative homology of two simplicial complexes

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

  * "HH SimplicialComplex"
  * "homology(Nothing,SimplicialComplex)"
  * "homology(Nothing,SimplicialComplex,Ring)"
  * homology(SimplicialComplex,Ring)
    -- compute the reduced homology of
    an abstract simplicial complex

homology(SimplicialComplex,SimplicialComplex) -- compute the relative homology of two simplicial complexes
**********************************************************************************************************

Synopsis
========

  * Function: homology (Macaulay2Doc),
  * Usage:
        homology(Delta, Gamma)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * Gamma, an abstract simplicial complex,
  * Outputs:
      * a chain complex (Macaulay2Doc),

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

This method computes the relative homology of a simplicial complex $\Delta$
contracted along a subcomplex $\Gamma$.

Contracting an edge of a hexagon will not change the homology.

+----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_5];                                                      |
+----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {x_0*x_1,x_1*x_2,x_2*x_3,x_3*x_4,x_4*x_5,x_5*x_0}|
|                                                                            |
|o2 = simplicialComplex | x_4x_5 x_0x_5 x_3x_4 x_2x_3 x_1x_2 x_0x_1 |        |
|                                                                            |
|o2 : SimplicialComplex                                                      |
+----------------------------------------------------------------------------+
|i3 : Γ = simplicialComplex {x_0*x_1}                                        |
|                                                                            |
|o3 = simplicialComplex | x_0x_1 |                                           |
|                                                                            |
|o3 : SimplicialComplex                                                      |
+----------------------------------------------------------------------------+
|i4 : prune homology Δ                                                       |
|                                                                            |
|o4 = -1 : 0                                                                 |
|                                                                            |
|      0 : 0                                                                 |
|                                                                            |
|            1                                                               |
|      1 : ZZ                                                                |
|                                                                            |
|o4 : GradedModule                                                           |
+----------------------------------------------------------------------------+
|i5 : prune homology(Δ, Γ)                                                   |
|                                                                            |
|o5 = -1 : 0                                                                 |
|                                                                            |
|      0 : 0                                                                 |
|                                                                            |
|            1                                                               |
|      1 : ZZ                                                                |
|                                                                            |
|o5 : GradedModule                                                           |
+----------------------------------------------------------------------------+
|i6 : assert(prune homology(Δ, Γ) == prune homology Δ)                       |
+----------------------------------------------------------------------------+

Gluing two antipodal points on a sphere introduces a non-trivial loop.

+-----------------------------------------------------------------------------+
|i7 : S = ZZ[y_0..y_4];                                                       |
+-----------------------------------------------------------------------------+
|i8 : Δ = simplicialComplex {y_0*y_1*y_3, y_0*y_2*y_3, y_1*y_2*y_3,           |
|                            y_0*y_1*y_4, y_0*y_2*y_4, y_1*y_2*y_4}           |
|                                                                             |
|o8 = simplicialComplex | y_1y_2y_4 y_0y_2y_4 y_0y_1y_4 y_1y_2y_3 y_0y_2y_3   |
|                                                                             |
|o8 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|y_0y_1y_3 |                                                                  |
+-----------------------------------------------------------------------------+
|i9 : prune homology Δ                                                        |
|                                                                             |
|o9 = -1 : 0                                                                  |
|                                                                             |
|      0 : 0                                                                  |
|                                                                             |
|      1 : 0                                                                  |
|                                                                             |
|            1                                                                |
|      2 : ZZ                                                                 |
|                                                                             |
|o9 : GradedModule                                                            |
+-----------------------------------------------------------------------------+
|i10 : Γ = simplicialComplex {y_3, y_4}                                       |
|                                                                             |
|o10 = simplicialComplex | y_4 y_3 |                                          |
|                                                                             |
|o10 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i11 : prune homology(Δ, Γ)                                                   |
|                                                                             |
|o11 = -1 : 0                                                                 |
|                                                                             |
|       0 : 0                                                                 |
|                                                                             |
|             1                                                               |
|       1 : ZZ                                                                |
|                                                                             |
|             1                                                               |
|       2 : ZZ                                                                |
|                                                                             |
|o11 : GradedModule                                                           |
+-----------------------------------------------------------------------------+

This method assumes that $\Gamma$ is a subcomplex of $\Delta$ and does not even
check that the two abstract simplicial complexes are defined over the same
ring.

Caveat
======

This method does not check if $\Gamma$ is contained in $\Delta$.

See also
========

  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * HH SimplicialComplex, --
    compute the reduced homology of an abstract simplicial complex
  * HH_ZZ SimplicialComplex, --
    compute the reduced homology of an abstract simplicial complex

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

  * "HH_ZZ(SimplicialComplex,SimplicialComplex)"
  * "homology(Nothing,SimplicialComplex,SimplicialComplex)"
  * homology(SimplicialComplex,SimplicialComplex)
    -- compute the
    relative homology of two simplicial complexes

id _ SimplicialComplex -- make the identity map from a SimplicialComplex to itself
**********************************************************************************

Synopsis
========

  * Scripted functor: id (Macaulay2Doc),
  * Usage:
        id_Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a map of abstract simplicial complexes,

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

The identity map on the underlying vertex set of an abstract simplicial complex
induces the identity map on the entire complex.

The first example is the identity map on a $4$-simplex.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                           |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplexComplex(4, S)                                                |
|                                                                             |
|o2 = simplicialComplex | abcde |                                             |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : f = id_Δ                                                                |
|                                                                             |
|o3 = | a b c d e |                                                           |
|                                                                             |
|o3 : SimplicialMap simplicialComplex | abcde | <--- simplicialComplex | abcde|
|-----------------------------------------------------------------------------|
||                                                                            |
+-----------------------------------------------------------------------------+
|i4 : assert (isWellDefined f and source f === Δ and                          |
|         target f === Δ and matrix f === vars S)                             |
+-----------------------------------------------------------------------------+

The second example is the identity map on the octahedron.

+-----------------------------------------------------------------------------+
|i5 : R = ZZ[x_0..x_5];                                                       |
+-----------------------------------------------------------------------------+
|i6 : Γ = simplicialComplex monomialIdeal(x_0*x_5, x_1*x_4, x_2*x_3)          |
|                                                                             |
|o6 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4   |
|                                                                             |
|o6 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i7 : g = id_Γ                                                                |
|                                                                             |
|o7 = | x_0 x_1 x_2 x_3 x_4 x_5 |                                             |
|                                                                             |
|o7 : SimplicialMap simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5         |
|-----------------------------------------------------------------------------|
|x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | |
|-----------------------------------------------------------------------------|
|x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3        |
|-----------------------------------------------------------------------------|
|x_0x_1x_2 |                                                                  |
+-----------------------------------------------------------------------------+
|i8 : assert (isWellDefined g and source g === Γ and                          |
|         target g === Γ and matrix g === vars R)                             |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes
  * id (Macaulay2Doc) -- identity map

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

  * id _ SimplicialComplex -- make the
    identity map from a SimplicialComplex to itself

ideal(SimplicialComplex) -- get the Stanley–Reisner ideal
*********************************************************

Synopsis
========

  * Function: ideal (Macaulay2Doc),
  * Usage:
        ideal Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * an ideal (Macaulay2Doc), that is generated by the
        monomials representing the minimal nonfaces in $\Delta$

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

In this package, an abstract simplicial complex is represented as squarefree
monomial ideal in a polynomial ring.  This
method function returns the defining ideal.

The boundary of the 4-simplex is a simplicial sphere with 5 vertices, 5
tetrahedral facets, and a minimal nonface that corresponds to the interior of
the sphere.

+------------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                      |
+------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|                                                                        |
|o2 = simplicialComplex | bcde acde abde abce abcd |                     |
|                                                                        |
|o2 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i3 : I = ideal Δ                                                        |
|                                                                        |
|o3 = ideal(a*b*c*d*e)                                                   |
|                                                                        |
|o3 : Ideal of S                                                         |
+------------------------------------------------------------------------+
|i4 : dim Δ                                                              |
|                                                                        |
|o4 = 3                                                                  |
+------------------------------------------------------------------------+
|i5 : assert (I == ideal a*b*c*d*e and instance(I, Ideal) and            |
|         numgens I === 1 and dim Δ === 3)                               |
+------------------------------------------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.

+------------------------------------------------------------+
|i6 : Γ = simplicialComplex {e, c*d, b*d, a*b*c}             |
|                                                            |
|o6 = simplicialComplex | e cd bd abc |                      |
|                                                            |
|o6 : SimplicialComplex                                      |
+------------------------------------------------------------+
|i7 : J = ideal Γ                                            |
|                                                            |
|o7 = ideal (a*d, b*c*d, a*e, b*e, c*e, d*e)                 |
|                                                            |
|o7 : Ideal of S                                             |
+------------------------------------------------------------+
|i8 : assert (J == ideal (a*d, b*c*d, a*e, b*e, c*e, d*e) and|
|         dim Γ === 2 and instance(J, Ideal))                |
+------------------------------------------------------------+

The irrelevant complex has the empty set as a facet whereas the void complex
has no facets.

+-------------------------------------------------------+
|i9 : irrelevant = simplicialComplex {1_S};             |
+-------------------------------------------------------+
|i10 : M = ideal irrelevant                             |
|                                                       |
|o10 = ideal (a, b, c, d, e)                            |
|                                                       |
|o10 : Ideal of S                                       |
+-------------------------------------------------------+
|i11 : assert (M == ideal gens S and instance(M, Ideal))|
+-------------------------------------------------------+
|i12 : void = simplicialComplex monomialIdeal 1_S       |
|                                                       |
|o12 = simplicialComplex 0                              |
|                                                       |
|o12 : SimplicialComplex                                |
+-------------------------------------------------------+
|i13 : U = ideal void                                   |
|                                                       |
|o13 = ideal 1                                          |
|                                                       |
|o13 : Ideal of S                                       |
+-------------------------------------------------------+
|i14 : assert (U == ideal 1_S and instance (U, Ideal))  |
+-------------------------------------------------------+

This routine is identical to monomialIdeal(SimplicialComplex),
except for the type (Macaulay2Doc),
of the output.

+-----------------------------------------------------------------------------+
|i15 : printWidth = 250;                                                      |
+-----------------------------------------------------------------------------+
|i16 : code (ideal, SimplicialComplex)                                        |
|                                                                             |
|o16 = -- code for method: ideal(SimplicialComplex)                           |
|      /usr/share/Macaulay2/SimplicialComplexes/Code.m2:19:39-19:50: --source |
|      ideal SimplicialComplex := Ideal => D -> ideal D.monomialIdeal         |
|-----------------------------------------------------------------------------|
|code:                                                                        |
+-----------------------------------------------------------------------------+
|i17 : code (monomialIdeal, SimplicialComplex)                                |
|                                                                             |
|o17 = -- code for method: monomialIdeal(SimplicialComplex)                   |
|      /usr/share/Macaulay2/SimplicialComplexes/Code.m2:20:55-20:             |
|      monomialIdeal SimplicialComplex := MonomialIdeal => D -> D             |
|-----------------------------------------------------------------------------|
|60: --source code:                                                           |
|.monomialIdeal                                                               |
+-----------------------------------------------------------------------------+

As the Stanley–Reisner ideal is part the defining data of an abstract
simplicial complex, so this method does no computation.

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * simplicialComplex(MonomialIdeal)
    -- make a simplicial complex from its
    Stanley–Reisner ideal
  * monomialIdeal(SimplicialComplex)
    -- get the Stanley–Reisner monomial
    ideal
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * ring(SimplicialComplex) -- get the
    polynomial ring of its Stanley–Reisner ideal

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

  * ideal(SimplicialComplex) -- get the
    Stanley–Reisner ideal

image(SimplicialMap) -- construct the image of a simplicial map
***************************************************************

Synopsis
========

  * Function: image (Macaulay2Doc),
  * Usage:
        image f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * an abstract simplicial complex, the image of
        the source of $f$ in the target of $f$

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

The image of $f$ is the subcomplex of the target of $f$ whose faces are of the
form $f(F)$ for some face $F$ in the source of $f$.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/229[a,b,c];                                                      |
+-----------------------------------------------------------------------------+
|i2 : D = simplicialComplex{a*b*c}                                            |
|                                                                             |
|o2 = simplicialComplex | abc |                                               |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : E = simplicialComplex{a*b,b*c}                                          |
|                                                                             |
|o3 = simplicialComplex | bc ab |                                             |
|                                                                             |
|o3 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i4 : f = map(E,D,{a,b,a})                                                    |
|                                                                             |
|o4 = | a b a |                                                               |
|                                                                             |
|o4 : SimplicialMap simplicialComplex | bc ab | <--- simplicialComplex | abc ||
+-----------------------------------------------------------------------------+
|i5 : isWellDefined f                                                         |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : image f                                                                 |
|                                                                             |
|o6 = simplicialComplex | ab |                                                |
|                                                                             |
|o6 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * source(SimplicialMap) -- get the source
    of the map
  * target(SimplicialMap) -- get the target
    of the map
  * isInjective(SimplicialMap) -- checks
    if a simplicial map is injective
  * isSurjective(SimplicialMap), --
    checks if a simplicial map is surjective

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

  * image(SimplicialMap) -- construct the
    image of a simplicial map

inducedSubcomplex(SimplicialComplex,List) -- make the induced simplicial complex on a subset of vertices
********************************************************************************************************

Synopsis
========

  * Function: inducedSubcomplex,
  * Usage:
        inducedSubcomplex(Delta, V)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * V, a list (Macaulay2Doc), of variables in the ring of
        $\Delta$ representing vertices
  * Outputs:
      * an abstract simplicial complex, the induced
        subcomplex of $\Delta$ on the given vertices

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

Given a simplicial complex $\Delta$ and a subset $V$ of its vertices, the
induced subcomplex is the abstract simplicial complexes consisting of all faces
in $\Delta$ whose vertices are contained in $V$.

+------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_3];                                                  |
+------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex{x_0*x_1*x_2, x_2*x_3, x_1*x_3}               |
|                                                                        |
|o2 = simplicialComplex | x_2x_3 x_1x_3 x_0x_1x_2 |                      |
|                                                                        |
|o2 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i3 : Γ = inducedSubcomplex(Δ, {x_1, x_2, x_3})                          |
|                                                                        |
|o3 = simplicialComplex | x_2x_3 x_1x_3 x_1x_2 |                         |
|                                                                        |
|o3 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i4 : vertices Γ                                                         |
|                                                                        |
|o4 = {x , x , x }                                                       |
|       1   2   3                                                        |
|                                                                        |
|o4 : List                                                               |
+------------------------------------------------------------------------+
|i5 : assert (isWellDefined Γ and set vertices Γ === set {x_1, x_2, x_3})|
+------------------------------------------------------------------------+
|i6 : assert all (facets Γ, F -> member(F, faces(#support F - 1, Δ)))    |
+------------------------------------------------------------------------+

As a special case, we can consider induced subcomplexes of the void and
irrelevant complexes.

+--------------------------------------------------------------+
|i7 : void = simplicialComplex monomialIdeal(1_S);             |
+--------------------------------------------------------------+
|i8 : inducedSubcomplex(void, {})                              |
|                                                              |
|o8 = simplicialComplex 0                                      |
|                                                              |
|o8 : SimplicialComplex                                        |
+--------------------------------------------------------------+
|i9 : assert(void === inducedSubcomplex(void, {}))             |
+--------------------------------------------------------------+
|i10 : irrelevant = simplicialComplex {1_S};                   |
+--------------------------------------------------------------+
|i11 : inducedSubcomplex(irrelevant, {})                       |
|                                                              |
|o11 = simplicialComplex | 1 |                                 |
|                                                              |
|o11 : SimplicialComplex                                       |
+--------------------------------------------------------------+
|i12 : assert(irrelevant === inducedSubcomplex(irrelevant, {}))|
+--------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * ring(SimplicialComplex) -- get the
    polynomial ring of its Stanley–Reisner ideal
  * vertices(SimplicialComplex) -- get
    the list of the vertices for an abstract simplicial complex

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

  * inducedSubcomplex(SimplicialComplex,List)
    -- make the induced
    simplicial complex on a subset of vertices

isInjective(SimplicialMap) -- checks if a simplicial map is injective
*********************************************************************

Synopsis
========

  * Function: isInjective (Macaulay2Doc),
  * Usage:
        isInjective f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Checks if vertices map to unique vertices.

The inclusion of a face is injective.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ[a..f];                                                           |
+-----------------------------------------------------------------------------+
|i2 : fish = simplicialComplex {a*b*c, b*c*d, d*e*f}                          |
|                                                                             |
|o2 = simplicialComplex | def bcd abc |                                       |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : R' = ZZ[x_0,x_1,x_2];                                                   |
+-----------------------------------------------------------------------------+
|i4 : fishface = simplicialComplex {x_0*x_1*x_2}                              |
|                                                                             |
|o4 = simplicialComplex | x_0x_1x_2 |                                         |
|                                                                             |
|o4 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i5 : f = map(fish,fishface,{a,b,c})                                          |
|                                                                             |
|o5 = | a b c |                                                               |
|                                                                             |
|o5 : SimplicialMap simplicialComplex | def bcd abc | <--- simplicialComplex ||
|-----------------------------------------------------------------------------|
|x_0x_1x_2 |                                                                  |
+-----------------------------------------------------------------------------+
|i6 : isInjective f                                                           |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

The identity map should always be injective.

+-------------------------------+
|i7 : isInjective id_fish       |
|                               |
|o7 = true                      |
+-------------------------------+
|i8 : assert isInjective id_fish|
+-------------------------------+

Collapsing a triangle to an edge should not be injective.

+-----------------------------------------------------------------------------+
|i9 : f' = map(fish, fishface, {b,c,c})                                       |
|                                                                             |
|o9 = | b c c |                                                               |
|                                                                             |
|o9 : SimplicialMap simplicialComplex | def bcd abc | <--- simplicialComplex ||
|-----------------------------------------------------------------------------|
|x_0x_1x_2 |                                                                  |
+-----------------------------------------------------------------------------+
|i10 : isInjective f'                                                         |
|                                                                             |
|o10 = false                                                                  |
+-----------------------------------------------------------------------------+
|i11 : assert not isInjective f'                                              |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * isSurjective(SimplicialMap), --
    checks if a simplicial map is surjective
  * id _ SimplicialComplex -- make the
    identity map from a SimplicialComplex to itself

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

  * isInjective(SimplicialMap) -- checks
    if a simplicial map is injective

isProper(SimplicialComplex) -- whether an abstract simplicial complex is properly colored
*****************************************************************************************

Synopsis
========

  * Function: isProper,
  * Usage:
        isProper Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a Boolean value (Macaulay2Doc), that is true if the
        multigrading on its ambient ring determines a proper coloring

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

A coloring of an abstract simplicial complex $\Delta$ is a labelling of its
vertices with colors.  A proper coloring of a simplicial complex $\Delta$ is a
labelling of the vertices with colors such that no two vertices in the same
face are the same color.  In this package, a coloring of an abstract simplicial
complex is determined by a multigrading of its ambient ring.
This method determines whether a multigrading on
the ambient ring defines a proper coloring of the abstract simplicial complex.

Giving the three vertices is the $2$-simplex distinct colors, each color set
corresponds to a unique face.

+--------------------------------------+
|i1 : S = QQ[a, b, c, DegreeRank => 3];|
+--------------------------------------+
|i2 : Δ = simplexComplex(2, S)         |
|                                      |
|o2 = simplicialComplex | abc |        |
|                                      |
|o2 : SimplicialComplex                |
+--------------------------------------+
|i3 : isProper Δ                       |
|                                      |
|o3 = true                             |
+--------------------------------------+
|i4 : assert isProper Δ                |
+--------------------------------------+

Two vertices of $\Delta$ have the same color when the corresponding variables
have the same multidegree.

+------------------------------------------------------------------------+
|i5 : Δ1 = sub(Δ, newRing(ring Δ, Degrees => {{1,0,0},{1,0,0},{0,0,1}}));|
+------------------------------------------------------------------------+
|i6 : isProper Δ1                                                        |
|                                                                        |
|o6 = false                                                              |
+------------------------------------------------------------------------+
|i7 : assert not isProper Δ1                                             |
+------------------------------------------------------------------------+
|i8 : flagfVector({1,0,0}, Δ1)                                           |
|                                                                        |
|o8 = 2                                                                  |
+------------------------------------------------------------------------+

Two vertices have distinct colors when the multidegrees of the corresponding
variables are linearly independent.

+-------------------------------------------------------------------------+
|i9 : Δ2 = sub(Δ, newRing(ring Δ, Degrees => {{1,0,0},{0,1,0},{0,2,1}})); |
+-------------------------------------------------------------------------+
|i10 : isProper Δ2                                                        |
|                                                                         |
|o10 = true                                                               |
+-------------------------------------------------------------------------+
|i11 : assert isProper Δ2                                                 |
+-------------------------------------------------------------------------+
|i12 : Δ3 = sub(Δ, newRing(ring Δ, Degrees => {{1,0,0},{0,1,0},{1,1,0}}));|
+-------------------------------------------------------------------------+
|i13 : isProper Δ3                                                        |
|                                                                         |
|o13 = false                                                              |
+-------------------------------------------------------------------------+
|i14 : assert not isProper Δ3                                             |
+-------------------------------------------------------------------------+

Caveat
======

Not every grading of the ambient polynomial ring corresponds to a coloring.

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * flagfVector(SimplicialComplex),
    -- compute the flag $f$-vector of an colored simplicial complex
  * flagfVector(List,SimplicialComplex)
    -- compute a flag $f$-number of
    a colored simplicial complex

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

  * isProper(SimplicialComplex), --
    whether an abstract simplicial complex is properly colored

isPure(SimplicialComplex) -- whether the facets are equidimensional
*******************************************************************

Synopsis
========

  * Function: isPure (Polyhedra),
  * Usage:
        isPure Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a Boolean value (Macaulay2Doc), which is true if the
        facets of $\Delta$ are of the same dimension, and false otherwise.

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

An abstract simplicial complex is pure of dimension $d$ if every facet has the
same dimension.

Many classic examples of abstract simplicial complexes are pure.

+------------------------------------+
|i1 : S = ZZ[x_1..x_18];             |
+------------------------------------+
|i2 : isPure simplexComplex(5, S)    |
|                                    |
|o2 = true                           |
+------------------------------------+
|i3 : isPure bartnetteSphereComplex S|
|                                    |
|o3 = true                           |
+------------------------------------+
|i4 : isPure bjornerComplex S        |
|                                    |
|o4 = true                           |
+------------------------------------+
|i5 : isPure dunceHatComplex S       |
|                                    |
|o5 = true                           |
+------------------------------------+
|i6 : isPure poincareSphereComplex S |
|                                    |
|o6 = true                           |
+------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.  Moreover, its 1-skeleton and
2-skeleton are not pure.

+-----------------------------------------------+
|i7 : R = ZZ/101[a..f];                         |
+-----------------------------------------------+
|i8 : Γ = simplicialComplex {e, c*d, b*d, a*b*c}|
|                                               |
|o8 = simplicialComplex | e cd bd abc |         |
|                                               |
|o8 : SimplicialComplex                         |
+-----------------------------------------------+
|i9 : isPure Γ                                  |
|                                               |
|o9 = false                                     |
+-----------------------------------------------+
|i10 : isPure skeleton (1, Γ)                   |
|                                               |
|o10 = false                                    |
+-----------------------------------------------+
|i11 : isPure skeleton (2, Γ)                   |
|                                               |
|o11 = false                                    |
+-----------------------------------------------+

There are two "trivial" simplicial complexes: the irrelevant complex has the
empty set as a facet whereas the void complex has no faces.  Both are pure.

+---------------------------------------------------------+
|i12 : irrelevant = simplicialComplex monomialIdeal gens S|
|                                                         |
|o12 = simplicialComplex | 1 |                            |
|                                                         |
|o12 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i13 : isPure irrelevant                                  |
|                                                         |
|o13 = true                                               |
+---------------------------------------------------------+
|i14 : void = simplicialComplex monomialIdeal 1_S         |
|                                                         |
|o14 = simplicialComplex 0                                |
|                                                         |
|o14 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i15 : isPure void                                        |
|                                                         |
|o15 = true                                               |
+---------------------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * dim(SimplicialComplex) -- find the
    dimension of an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * skeleton(ZZ,SimplicialComplex),
    -- make a new simplicial complex generated by all faces of a bounded
    dimension

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

  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional

isSurjective(SimplicialMap) -- checks if a simplicial map is surjective
***********************************************************************

Synopsis
========

  * Function: isSurjective (Macaulay2Doc),
  * Usage:
        isSurjective f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Checks if every vertex in the target has a preimage.

Collapsing a triangle to an edge is surjective.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ[a,b,c];                                                          |
+-----------------------------------------------------------------------------+
|i2 : triangle = simplicialComplex {a*b*c}                                    |
|                                                                             |
|o2 = simplicialComplex | abc |                                               |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : R' = ZZ[x_0,x_1];                                                       |
+-----------------------------------------------------------------------------+
|i4 : edge = simplicialComplex {x_0*x_1}                                      |
|                                                                             |
|o4 = simplicialComplex | x_0x_1 |                                            |
|                                                                             |
|o4 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i5 : f = map(edge,triangle,{x_0,x_0,x_1})                                    |
|                                                                             |
|o5 = | x_0 x_0 x_1 |                                                         |
|                                                                             |
|o5 : SimplicialMap simplicialComplex | x_0x_1 | <--- simplicialComplex | abc |
|-----------------------------------------------------------------------------|
||                                                                            |
+-----------------------------------------------------------------------------+
|i6 : isSurjective f                                                          |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

The identity map should always be surjective.

+------------------------------------+
|i7 : isSurjective id_triangle       |
|                                    |
|o7 = true                           |
+------------------------------------+
|i8 : assert isSurjective id_triangle|
+------------------------------------+

The inclusion of an edge in a triangle is not surjective.

+-----------------------------------------------------------------------------+
|i9 : f' = map(triangle,edge,{a,b});                                          |
|                                                                             |
|o9 : SimplicialMap simplicialComplex | abc | <--- simplicialComplex | x_0x_1 |
|-----------------------------------------------------------------------------|
||                                                                            |
+-----------------------------------------------------------------------------+
|i10 : isSurjective f'                                                        |
|                                                                             |
|o10 = false                                                                  |
+-----------------------------------------------------------------------------+
|i11 : assert not isSurjective f'                                             |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * isInjective(SimplicialMap) -- checks
    if a simplicial map is injective
  * id _ SimplicialComplex -- make the
    identity map from a SimplicialComplex to itself

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

  * isSurjective(SimplicialMap), --
    checks if a simplicial map is surjective

isWellDefined(SimplicialComplex) -- whether underlying data is uncontradictory
******************************************************************************

Synopsis
========

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        isWellDefined Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a Boolean value (Macaulay2Doc), that is true (Macaulay2Doc),
        if underlying data unambiguously defines an
        abstract simplicial complex

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

In this package, a simplicial complex is represented by its Stanley–Reisner
ideal (see https://en.wikipedia.org/wiki/Stanley–Reisner_ring ). The vertices
are identified with a subset of the variables in a polynomial ring and each
face is identified with the product of the corresponding variables. A nonface
is any subset of the variables that does not belong to the simplicial complex
and each nonface is again identified with a product of variables. The
Stanley-Reisner ideal of a simplicial complex is generated by monomials
corresponding to its nonfaces.

This method determines whether the underlying data correctly defines an
abstract simplicial complex.  In particular, it verifies that the monomial
ideal is squarefee (Macaulay2Doc), and that the matrix of
facets are the maximal faces in the abstract simplicial complex.

The boundary of the 4-simplex is a simplicial sphere with 5 vertices, 5 facets,
and a minimal nonface that corresponds to the interior of the sphere.

+----------------------------------------------------+
|i1 : S = ZZ[a..e];                                  |
+----------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal (a*b*c*d*e)|
|                                                    |
|o2 = simplicialComplex | bcde acde abde abce abcd | |
|                                                    |
|o2 : SimplicialComplex                              |
+----------------------------------------------------+
|i3 : assert isWellDefined Δ                         |
+----------------------------------------------------+

This method also checks the following aspects of the data structure:

  * the underlying HashTable (Macaulay2Doc), has the expected
    keys, namely ring, monomialIdeal, facets, and cache,
  * the value of the ring key is a PolynomialRing (Macaulay2Doc),
  * the value of the monomialIdeal key is a MonomialIdeal (Macaulay2Doc),
  * the ring of the monomialIdeal value equals the value of the ring key,
  * the value of the facets key is a List (Macaulay2Doc),
  * the ring of each entry in facets equals the value of the ring key,
  * the value of the cache key is a CacheTable (Macaulay2Doc).

Abstract simplicial complexes created using the constructors in this package
will automatically be well-defined.  The primary purpose of this method is to
document the underlying data structure for developers.

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * simplicialComplex(List) -- make an
    abstract simplicial complex from a list of faces
  * simplicialComplex(MonomialIdeal)
    -- make a simplicial complex from its
    Stanley–Reisner ideal

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

  * isWellDefined(SimplicialComplex)
    -- whether underlying data is
    uncontradictory

isWellDefined(SimplicialMap) -- whether underlying data is uncontradictory
**************************************************************************

Synopsis
========

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        isWellDefined f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * a Boolean value (Macaulay2Doc), that is true (Macaulay2Doc),
        if underlying data unambiguously defines a
        simplicial map

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

Maps between simplicial complexes are well-defined if the image of every face
is contained in a face. In this package, vertices of abstract simplicial
complexes are identified with a subset of the variables in a fixed polynomial
ring and each face is identified with monomials in those variables.
Consequently, a map between simplicial complexes is given by a map between the
respective polynomial rings.

This method determines whether the underlying ring map correctly defines a
simplicial map. In particular, it checks if variables are sent to variables,
and that the image of each monomial corresponding to a face in the source
divides some monomial corresponding to a face in the target (i.e. the image of
a face is contained in a face).

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/229[a,b,c,d];                                                    |
+-----------------------------------------------------------------------------+
|i2 : D = simplicialComplex{a*b*c, b*c*d}                                     |
|                                                                             |
|o2 = simplicialComplex | bcd abc |                                           |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : E = simplicialComplex{a*b, b*c}                                         |
|                                                                             |
|o3 = simplicialComplex | bc ab |                                             |
|                                                                             |
|o3 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i4 : f = map(E,D,{a,b,b,c})                                                  |
|                                                                             |
|o4 = | a b b c |                                                             |
|                                                                             |
|o4 : SimplicialMap simplicialComplex | bc ab | <--- simplicialComplex | bcd  |
|-----------------------------------------------------------------------------|
|abc |                                                                        |
+-----------------------------------------------------------------------------+
|i5 : isWellDefined f                                                         |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

The constructors in this package have no guarantee to be well defined; the data
defining a simplicial map is a ring map between the corresponding polynomial
rings, which could have no relation to the two complexes. By making the current
debugging level greater than one, one gets some additional information about
the nature of the failure.

+-----------------------------------------------------------------------------+
|i6 : g = map(E,D,{b*c,c,c+a,1})                                              |
|                                                                             |
|o6 = | bc c a+c 1 |                                                          |
|                                                                             |
|o6 : SimplicialMap simplicialComplex | bc ab | <--- simplicialComplex | bcd  |
|-----------------------------------------------------------------------------|
|abc |                                                                        |
+-----------------------------------------------------------------------------+
|i7 : isWellDefined g                                                         |
|                                                                             |
|o7 = false                                                                   |
+-----------------------------------------------------------------------------+
|i8 : debugLevel = 1;                                                         |
+-----------------------------------------------------------------------------+
|i9 : isWellDefined g                                                         |
|-- expected image of a vertex to be a vertex                                 |
|o9 = false                                                                   |
+-----------------------------------------------------------------------------+
|i10 : h = map(E,D,{a,b,c,c})                                                 |
|                                                                             |
|o10 = | a b c c |                                                            |
|                                                                             |
|o10 : SimplicialMap simplicialComplex | bc ab | <--- simplicialComplex | bcd |
|-----------------------------------------------------------------------------|
|abc |                                                                        |
+-----------------------------------------------------------------------------+
|i11 : isWellDefined h                                                        |
|-- expected image of a face to be a face                                     |
|o11 = false                                                                  |
+-----------------------------------------------------------------------------+

This method also checks the following aspects of the data structure:

  * the underlying HashTable (Macaulay2Doc), has the expected
    keys, namely source, target, map, and cache,
  * the value of the source key is a SimplicialComplex,
  * the value of the target key is a SimplicialComplex,
  * the value of the RingMap key is a RingMap (Macaulay2Doc).
  * the value of the cache key is a CacheTable (Macaulay2Doc).
  * the underlying ring map source value equals the ring of the source value,
  * the underlying ring map target value equals the ring of the target value,
  * the coefficient ring of the source value equals the coefficient ring of the
    target value,

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes
  * map(SimplicialComplex,SimplicialComplex,List)
    -- create a
    simplicial map between simplicial complexes

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

  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory

kleinBottleComplex(PolynomialRing) -- make a minimal triangulation of the Klein bottle
**************************************************************************************

Synopsis
========

  * Function: kleinBottleComplex,
  * Usage:
        kleinBottleComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that
        specifies the polynomial ring containing the Stanley–Reisner ideal
  * Outputs:
      * an abstract simplicial complex, corresponding
        to a minimal triangulation of the Klein bottle

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

This function accesses Frank Lutz's database of all small triangulated
2-manifolds via the method smallManifold,
to obtain the minimal
triangulation of the Klein bottle.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_7];                                                       |
+-----------------------------------------------------------------------------+
|i2 : KleinBottle = kleinBottleComplex S                                      |
|                                                                             |
|o2 = simplicialComplex | x_2x_6x_7 x_0x_6x_7 x_2x_5x_7 x_0x_5x_7 x_4x_5x_6   |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_3x_5x_6 x_0x_4x_6 x_2x_3x_6 x_1x_4x_5 x_0x_3x_5 x_1x_2x_5 x_2x_3x_4        |
|-----------------------------------------------------------------------------|
|x_1x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                    |
+-----------------------------------------------------------------------------+

From Theorem 6.3 in Chapter one of Munkres' Algebraic Topology (see
https://www.pearson.com/us/higher-education/product/Munkres-Topology-2nd-
Edition/9780131816299.html ) states that the first homology of the Klein bottle
should have rank one free part, and $\mathbb{Z}/2\mathbb{Z}$ torsion. The
second homology should be zero.

+-------------------------+
|i3 : prune HH KleinBottle|
|                         |
|o3 = -1 : 0              |
|                         |
|      0 : 0              |
|                         |
|      1 : cokernel | 2 | |
|                   | 0 | |
|                         |
|      2 : 0              |
|                         |
|o3 : GradedModule        |
+-------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * smallManifold(ZZ,ZZ,ZZ,PolynomialRing)
    -- get a small manifold
    from the Frank Lutz database

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

  * kleinBottleComplex(PolynomialRing)
    -- make a minimal triangulation of
    the Klein bottle

link(SimplicialComplex,RingElement) -- make the link of a face in an abstract simplicial complex
************************************************************************************************

Synopsis
========

  * Function: link,
  * Usage:
        link(Delta, F)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * F, a ring element (Macaulay2Doc), that is a monomial
        representing a face of $\Delta$
  * Outputs:
      * an abstract simplicial complex, the link of
        face $f$ in $\Delta$

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

The link of a face $F$ in the abstract simplicial complex $\Delta$ is the set
of faces that are disjoint from $F$ but whose unions with $F$ lie in $\Delta$.

Following Example 1.39 in Miller-Sturmfels' Combinatorial Commutative Algebra,
we consider a simplicial complex with 6 facets.  The link of the vertex $a$
consists of the vertex $e$ along with the proper faces of the triangle $b*c*d$.
The link of the vertex $c$ is pure of dimension $1$; its four facets being the
three edges of the triangle $a*b*d$ plus the extra edge $b*e$. The link of $e$
consists of the vertex $a$ along with the edge $b*c$.  The link of the edge
$b*c$ consists of the three remaining vertices.  Finally, the link of the edge
$a*e$ is the irrelevant complex.

+---------------------------------------------------------------------+
|i1 : S = QQ[a..e];                                                   |
+---------------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal (d*e, a*b*e, a*c*e, a*b*c*d)|
|                                                                     |
|o2 = simplicialComplex | ae bce bcd acd abd abc |                    |
|                                                                     |
|o2 : SimplicialComplex                                               |
+---------------------------------------------------------------------+
|i3 : link (Δ, a)                                                     |
|                                                                     |
|o3 = simplicialComplex | e cd bd bc |                                |
|                                                                     |
|o3 : SimplicialComplex                                               |
+---------------------------------------------------------------------+
|i4 : link (Δ, c)                                                     |
|                                                                     |
|o4 = simplicialComplex | be bd ad ab |                               |
|                                                                     |
|o4 : SimplicialComplex                                               |
+---------------------------------------------------------------------+
|i5 : link (Δ, e)                                                     |
|                                                                     |
|o5 = simplicialComplex | a bc |                                      |
|                                                                     |
|o5 : SimplicialComplex                                               |
+---------------------------------------------------------------------+
|i6 : link (Δ, b*c)                                                   |
|                                                                     |
|o6 = simplicialComplex | e d a |                                     |
|                                                                     |
|o6 : SimplicialComplex                                               |
+---------------------------------------------------------------------+
|i7 : link (Δ, a*e)                                                   |
|                                                                     |
|o7 = simplicialComplex | 1 |                                         |
|                                                                     |
|o7 : SimplicialComplex                                               |
+---------------------------------------------------------------------+
|i8 : assert (facets link (Δ, a) ===  {e, c*d, b*d, b*c})             |
+---------------------------------------------------------------------+
|i9 : assert (facets link (Δ, c) ===  {b*e, b*d, a*d, a*b})           |
+---------------------------------------------------------------------+
|i10 : assert (facets link (Δ, e) === {a, b*c})                       |
+---------------------------------------------------------------------+
|i11 : assert (facets link (Δ, b*c) === {e,d,a})                      |
+---------------------------------------------------------------------+
|i12 : assert (facets link (Δ, a*e) === {1_S})                        |
+---------------------------------------------------------------------+
|i13 : assert (isPure link (Δ, c) and dim link (Δ, a*e) === -1)       |
+---------------------------------------------------------------------+

The link of the empty face equals the original simplicial complex.

+---------------------------------------------------------------+
|i14 : link(Δ, 1_S)                                             |
|                                                               |
|o14 = simplicialComplex | ae bce bcd acd abd abc |             |
|                                                               |
|o14 : SimplicialComplex                                        |
+---------------------------------------------------------------+
|i15 : void = simplicialComplex monomialIdeal 1_S               |
|                                                               |
|o15 = simplicialComplex 0                                      |
|                                                               |
|o15 : SimplicialComplex                                        |
+---------------------------------------------------------------+
|i16 : link (void, 1_S)                                         |
|                                                               |
|o16 = simplicialComplex 0                                      |
|                                                               |
|o16 : SimplicialComplex                                        |
+---------------------------------------------------------------+
|i17 : assert (link (Δ, 1_S) === Δ and link(void, 1_S) === void)|
+---------------------------------------------------------------+

If $G$ is a face in the link of some face $F$, then $F$ is a face in the link
of $G$.

+----------------------------------------------------------------------+
|i18 : S = ZZ/101[a..g];                                               |
+----------------------------------------------------------------------+
|i19 : Δ = simplicialComplex {a*b*c, a*c*d, a*d*e, a*e*f, a*f*g, a*b*g}|
|                                                                      |
|o19 = simplicialComplex | afg abg aef ade acd abc |                   |
|                                                                      |
|o19 : SimplicialComplex                                               |
+----------------------------------------------------------------------+
|i20 : link (Δ, a*b)                                                   |
|                                                                      |
|o20 = simplicialComplex | g c |                                       |
|                                                                      |
|o20 : SimplicialComplex                                               |
+----------------------------------------------------------------------+
|i21 : link (Δ, g)                                                     |
|                                                                      |
|o21 = simplicialComplex | af ab |                                     |
|                                                                      |
|o21 : SimplicialComplex                                               |
+----------------------------------------------------------------------+
|i22 : link (Δ, c)                                                     |
|                                                                      |
|o22 = simplicialComplex | ad ab |                                     |
|                                                                      |
|o22 : SimplicialComplex                                               |
+----------------------------------------------------------------------+

The dual version of Hochster's formula (see Corollary 1.40 in Miller-Sturmfels)
relates the Betti numbers of a Stanley–Reisner ideal with the reduced homology
of a link in the Alexander dual simplicial complex.

+-----------------------------------------------------------------------------+
|i23 : betti res ideal Δ                                                      |
|                                                                             |
|             0 1  2 3 4                                                      |
|o23 = total: 1 9 16 9 1                                                      |
|          0: 1 .  . . .                                                      |
|          1: . 9 16 9 .                                                      |
|          2: . .  . . 1                                                      |
|                                                                             |
|o23 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i24 : R = QQ[a..e, DegreeRank => 5];                                         |
+-----------------------------------------------------------------------------+
|i25 : Γ = simplicialComplex monomialIdeal (d*e, a*b*e, a*c*e, a*b*c*d)       |
|                                                                             |
|o25 = simplicialComplex | ae bce bcd acd abd abc |                           |
|                                                                             |
|o25 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i26 : prune Tor_0(R^1/gens R,ideal Γ)                                        |
|                                                                             |
|o26 = cokernel {1, 1, 1, 1, 0} | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 e d c b a |   |
|               {1, 1, 0, 0, 1} | 0 0 0 0 0 e d c b a 0 0 0 0 0 0 0 0 0 0 |   |
|               {1, 0, 1, 0, 1} | 0 0 0 0 0 0 0 0 0 0 e d c b a 0 0 0 0 0 |   |
|               {0, 0, 0, 1, 1} | e d c b a 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |   |
|                                                                             |
|                             4                                               |
|o26 : R-module, quotient of R                                                |
+-----------------------------------------------------------------------------+
|i27 : assert (hilbertFunction({1,1,1,1,0}, Tor_0(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_(-1) (link (dual Γ, e)))                                             |
+-----------------------------------------------------------------------------+
|i28 : assert (hilbertFunction({1,1,0,0,1}, Tor_0(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_(-1) (link (dual Γ, c*d)))                                           |
+-----------------------------------------------------------------------------+
|i29 : assert (hilbertFunction({1,0,1,0,1}, Tor_0(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_(-1) (link (dual Γ, b*d)))                                           |
+-----------------------------------------------------------------------------+
|i30 : assert (hilbertFunction({0,0,0,1,1}, Tor_0(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_(-1) (link (dual Γ, a*b*c)))                                         |
+-----------------------------------------------------------------------------+
|i31 : prune Tor_1(R^1/gens R, ideal Γ)                                       |
|                                                                             |
|o31 = cokernel {1, 1, 1, 0, 1} | e d c b a 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |   |
|               {1, 1, 0, 1, 1} | 0 0 0 0 0 e d c b a 0 0 0 0 0 0 0 0 0 0 |   |
|               {1, 0, 1, 1, 1} | 0 0 0 0 0 0 0 0 0 0 e d c b a 0 0 0 0 0 |   |
|               {1, 1, 1, 1, 1} | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 e d c b a |   |
|                                                                             |
|                             4                                               |
|o31 : R-module, quotient of R                                                |
+-----------------------------------------------------------------------------+
|i32 : assert (hilbertFunction({1,1,1,0,1}, Tor_1(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_0 (link (dual Γ, d)))                                                |
+-----------------------------------------------------------------------------+
|i33 : assert (hilbertFunction({1,1,0,1,1}, Tor_1(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_0 (link (dual Γ, c)))                                                |
+-----------------------------------------------------------------------------+
|i34 : assert (hilbertFunction({1,0,1,1,1}, Tor_1(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_0 (link (dual Γ, b)))                                                |
+-----------------------------------------------------------------------------+
|i35 : assert (hilbertFunction({1,1,1,1,1}, Tor_1(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_0 (link (dual Γ, 1_R)))                                              |
+-----------------------------------------------------------------------------+
|i36 : prune Tor_2(R^1/gens R, ideal Γ)                                       |
|                                                                             |
|o36 = cokernel {1, 1, 1, 1, 1} | e d c b a |                                 |
|                                                                             |
|                             1                                               |
|o36 : R-module, quotient of R                                                |
+-----------------------------------------------------------------------------+
|i37 : assert (hilbertFunction({1,1,1,1,1}, Tor_2(R^1/gens R, ideal Γ)) ===   |
|-----------------------------------------------------------------------------|
|rank HH_1 (link (dual Γ, 1_R)))                                              |
+-----------------------------------------------------------------------------+

The Reisner criterion for the Cohen-Macaulay property of the Stanley–Reisner
ring involves links, see Theorem 5.53 in Miller-Sturmfels.  Specifically, an
abstract simplicial complex $\Delta$ is Cohen-Macaulay if and only if, for all
faces $F$ in $\Delta$ and all $i$ such that $i < \operatorname{dim}
\operatorname{link}(\Delta, F)$, the $i$-th reduced homology of
$\operatorname{link}(\Delta, F)$ vanishes.

+-----------------------------------------------------------------------------+
|i38 : R' = QQ[a..h];                                                         |
+-----------------------------------------------------------------------------+
|i39 : B = bartnetteSphereComplex R'                                          |
|                                                                             |
|o39 = simplicialComplex | defh befh cdfh bcfh adeh abeh acdh abch defg cefg  |
|                                                                             |
|o39 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|adfg acfg bdeg bceg abdg abcg bcef acdf abde |                               |
+-----------------------------------------------------------------------------+
|i40 : pdim comodule ideal B === codim ideal B  -- B is Cohen-Macaulay        |
|                                                                             |
|o40 = true                                                                   |
+-----------------------------------------------------------------------------+
|i41 : assert all (flatten apply(-1..2, i -> (faces B)#i), f -> (             |
|               L := link (B, f);                                             |
|               all (-1..dim L - 1, j -> HH_j(L) == 0)))                      |
+-----------------------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * dual(SimplicialComplex) -- make the
    Alexander dual of an abstract simplicial complex
  * star(SimplicialComplex,RingElement)
    -- make the star of a face
  * bartnetteSphereComplex,
    -- make a non-polytopal 3-sphere with 8 vertices
  * pdim(Module) (Macaulay2Doc) -- calculate the
    projective dimension of a module
  * codim(Ideal) (Macaulay2Doc) -- compute the
    codimension

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

  * link(SimplicialComplex,RingElement)
    -- make the link of a face in an
    abstract simplicial complex

lyubeznikResolution -- create the Lyubeznik resolution of an ordered set of monomials.
**************************************************************************************

Synopsis
========

  * Usage:
        lyubeznikResolution L
        lyubeznikResolution M
  * Inputs:
      * L, a list (Macaulay2Doc), of monomials in a polynomial
        ring, that minimally generate a monomial ideal.
      * M, a monomial ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * MonomialOrder => a list (Macaulay2Doc), default value {}
  * Outputs:
      * a chain complex (Macaulay2Doc), the Lyubeznik
        resolution of $S/M$.

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

For a monomial ideal $M$ in a polynomial ring $S$, minimally generated by $L$,
the Lyubeznik resolution is a resolution of $S/M$ determined by a total
ordering of the minimal generators of $M$. It is the subcomplex of the Taylor
resolution of $M$ induced on the rooted faces. If $L$ is used as input, the
ordering is the order in which the monomials appear in $L$. If $M$ is used as
the input, the ordering is obtained from $\operatorname{first}
\operatorname{mingens} \operatorname{entries} M$. For more details on Lyubeznik
resolutions and their construction, see Jeff Mermin Three Simplicial
Resolutions (see https://www.degruyter.com/view/book/9783110250404/10.1515/
9783110250404.127.xml ), (English summary) Progress in commutative algebra 1,
127–141, de Gruyter, Berlin, 2012.

+--------------------------------------+
|i1 : S = QQ[x,y];                     |
+--------------------------------------+
|i2 : M = monomialIdeal{x*y,x^2,y^3};  |
|                                      |
|o2 : MonomialIdeal of S               |
+--------------------------------------+
|i3 : F = lyubeznikResolution M;       |
+--------------------------------------+
|i4 : F.dd                             |
|                                      |
|          1                    3      |
|o4 = 0 : S  <---------------- S  : 1  |
|               | xy x2 y3 |           |
|                                      |
|          3                      2    |
|     1 : S  <------------------ S  : 2|
|               {2} | -x -y2 |         |
|               {2} | y  0   |         |
|               {3} | 0  x   |         |
|                                      |
|o4 : ChainComplexMap                  |
+--------------------------------------+

Changing the order of the generators may change the output. We can do this by
manually entering the permuted list of generators, or by using the optional
$\mathrm{MonomialOrder}$ argument.

+--------------------------------------------------------+
|i5 : first entries mingens M                            |
|                                                        |
|            2   3                                       |
|o5 = {x*y, x , y }                                      |
|                                                        |
|o5 : List                                               |
+--------------------------------------------------------+
|i6 : F' = lyubeznikResolution({x^2,y^3,x*y});           |
+--------------------------------------------------------+
|i7 : F'.dd                                              |
|                                                        |
|          1                    3                        |
|o7 = 0 : S  <---------------- S  : 1                    |
|               | x2 y3 xy |                             |
|                                                        |
|          3                         3                   |
|     1 : S  <--------------------- S  : 2               |
|               {2} | -y3 -y 0  |                        |
|               {3} | x2  0  -x |                        |
|               {2} | 0   x  y2 |                        |
|                                                        |
|          3                   1                         |
|     2 : S  <--------------- S  : 3                     |
|               {5} | 1   |                              |
|               {3} | -y2 |                              |
|               {4} | x   |                              |
|                                                        |
|o7 : ChainComplexMap                                    |
+--------------------------------------------------------+
|i8 : F' = lyubeznikResolution(M,MonomialOrder=>{1,2,0});|
+--------------------------------------------------------+
|i9 : F'.dd                                              |
|                                                        |
|          1                    3                        |
|o9 = 0 : S  <---------------- S  : 1                    |
|               | x2 y3 xy |                             |
|                                                        |
|          3                         3                   |
|     1 : S  <--------------------- S  : 2               |
|               {2} | -y3 -y 0  |                        |
|               {3} | x2  0  -x |                        |
|               {2} | 0   x  y2 |                        |
|                                                        |
|          3                   1                         |
|     2 : S  <--------------- S  : 3                     |
|               {5} | 1   |                              |
|               {3} | -y2 |                              |
|               {4} | x   |                              |
|                                                        |
|o9 : ChainComplexMap                                    |
+--------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * SimplicialComplexes -- exploring abstract simplicial complexes
    within commutative algebra
  * lyubeznikSimplicialComplex -- create a
    simplicial complex supporting a Lyubeznik resolution of a monomial ideal
  * taylorResolution -- create the Taylor resolution
    of a monomial ideal

Ways to use lyubeznikResolution :
=================================

  * "lyubeznikResolution(List)"
  * "lyubeznikResolution(MonomialIdeal)"

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

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

lyubeznikSimplicialComplex -- create a simplicial complex supporting a Lyubeznik resolution of a monomial ideal
***************************************************************************************************************

Synopsis
========

  * Usage:
        lyubeznikSimplicialComplex(L,R)
        lyubeznikSimplicialComplex(M,R)
  * Inputs:
      * L, a list (Macaulay2Doc), of monomials in a polynomial
        ring, that minimally generate a monomial ideal.
      * M, a monomial ideal (Macaulay2Doc),
      * R, a polynomial ring (Macaulay2Doc), the ambient
        ring used in constructing the Lyubeznik simplicial complex.
  * Optional inputs (Macaulay2Doc),:
      * MonomialOrder => a list (Macaulay2Doc), default value {}
  * Outputs:
      * D, an abstract simplicial complex,

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

The Lyubeznik simplicial complex is the simplicial complex that supports the
Lyubeznik resolution, of an ordered set of
monomials. This function is sensitive to the order in which the monomials in
$L$ appear. If you are using a monomial ideal $M$ as your input, then the order
of the monomials is given by $\operatorname{first} \operatorname{entries}
\operatorname{mingens} M$.

+----------------------------------------+
|i1 : S = QQ[x,y];                       |
+----------------------------------------+
|i2 : R = QQ[a,b,c];                     |
+----------------------------------------+
|i3 : M = monomialIdeal{x*y,x^2,y^3};    |
|                                        |
|o3 : MonomialIdeal of S                 |
+----------------------------------------+
|i4 : D = lyubeznikSimplicialComplex(M,R)|
|                                        |
|o4 = simplicialComplex | ac ab |        |
|                                        |
|o4 : SimplicialComplex                  |
+----------------------------------------+

The lyubeznik resolution of $M$ is the homogenization of $D$ by $M$ (See
chainComplex(SimplicialComplex,Labels=>...)).

+------------------------------------------------------------+
|i5 : L = lyubeznikResolution(M);                            |
+------------------------------------------------------------+
|i6 : L.dd                                                   |
|                                                            |
|          1                    3                            |
|o6 = 0 : S  <---------------- S  : 1                        |
|               | xy x2 y3 |                                 |
|                                                            |
|          3                      2                          |
|     1 : S  <------------------ S  : 2                      |
|               {2} | -x -y2 |                               |
|               {2} | y  0   |                               |
|               {3} | 0  x   |                               |
|                                                            |
|o6 : ChainComplexMap                                        |
+------------------------------------------------------------+
|i7 : L' = chainComplex(D,Labels=>(first entries mingens M));|
+------------------------------------------------------------+
|i8 : L'.dd                                                  |
|                                                            |
|          1                    3                            |
|o8 = 0 : S  <---------------- S  : 1                        |
|               | xy x2 y3 |                                 |
|                                                            |
|          3                      2                          |
|     1 : S  <------------------ S  : 2                      |
|               {2} | -x -y2 |                               |
|               {2} | y  0   |                               |
|               {3} | 0  x   |                               |
|                                                            |
|o8 : ChainComplexMap                                        |
+------------------------------------------------------------+

Changing the order of the generators may change the output. We can do this by
manually entering the permuted list of generators, or by using the optional
$\operatorname{MonomialOrder}$ argument.

+-----------------------------------------------------------------+
|i9 : first entries mingens M                                     |
|                                                                 |
|            2   3                                                |
|o9 = {x*y, x , y }                                               |
|                                                                 |
|o9 : List                                                        |
+-----------------------------------------------------------------+
|i10 : D' = lyubeznikSimplicialComplex(M,R,MonomialOrder=>{1,2,0})|
|                                                                 |
|o10 = simplicialComplex | abc |                                  |
|                                                                 |
|o10 : SimplicialComplex                                          |
+-----------------------------------------------------------------+
|i11 : D' = lyubeznikSimplicialComplex({x^2,y^3,x*y},R)           |
|                                                                 |
|o11 = simplicialComplex | abc |                                  |
|                                                                 |
|o11 : SimplicialComplex                                          |
+-----------------------------------------------------------------+
|i12 : (lyubeznikResolution(M,MonomialOrder=>{1,2,0})).dd         |
|                                                                 |
|           1                    3                                |
|o12 = 0 : S  <---------------- S  : 1                            |
|                | x2 y3 xy |                                     |
|                                                                 |
|           3                         3                           |
|      1 : S  <--------------------- S  : 2                       |
|                {2} | -y3 -y 0  |                                |
|                {3} | x2  0  -x |                                |
|                {2} | 0   x  y2 |                                |
|                                                                 |
|           3                   1                                 |
|      2 : S  <--------------- S  : 3                             |
|                {5} | 1   |                                      |
|                {3} | -y2 |                                      |
|                {4} | x   |                                      |
|                                                                 |
|o12 : ChainComplexMap                                            |
+-----------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * SimplicialComplexes -- exploring abstract simplicial complexes
    within commutative algebra
  * lyubeznikResolution -- create the Lyubeznik
    resolution of an ordered set of monomials.
  * scarfSimplicialComplex -- create the Scarf
    simplicial complex for a list of monomials

Ways to use lyubeznikSimplicialComplex :
========================================

  * "lyubeznikSimplicialComplex(List,Ring)"
  * "lyubeznikSimplicialComplex(MonomialIdeal,Ring)"

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

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

Making an abstract simplicial complex -- information about the basic constructors
*********************************************************************************

An abstract simplicial complex on a finite set is a family of subsets that is
closed under taking subsets.  The elements in the abstract simplicial complex
are called its faces.  The faces having cardinality 1 are its vertices and the
maximal faces (order by inclusion) are its facets.  Following the combinatorial
conventions, every nonempty abstract simplicial complex has the empty set as a
face.

In this package, a simplicial complex is represented by its Stanley–Reisner
ideal (see https://en.wikipedia.org/wiki/Stanley–Reisner_ring ). The vertices
are identified with a subset of the variables in a polynomial ring and each
face is identified with the product of the corresponding variables. A nonface
is any subset of the variables that does not belong to the simplicial complex
and each nonface is again identified with product of variables. The
Stanley-Reisner ideal of a simplicial complex is generated by monomials
corresponding to its nonfaces.

Basic constructors for abstract simplicial complexes
====================================================

  * simplicialComplex(List) -- make an
    abstract simplicial complex from a list of faces
  * simplicialComplex(MonomialIdeal)
    -- make a simplicial complex from its
    Stanley–Reisner ideal
  * SimplicialComplex -- the class of all abstract
    simplicial complexes
  * isWellDefined(SimplicialComplex)
    -- whether underlying data is
    uncontradictory

Classic examples of abstract simplicial complexes
=================================================

  * simplexComplex(ZZ,PolynomialRing)
    -- make the simplex as an abstract
    simplicial complex
  * bartnetteSphereComplex(PolynomialRing)
    -- make a non-polytopal
    3-sphere with 8 vertices
  * bjornerComplex(PolynomialRing),
    -- make a shellable 2-polyhedron with 6 vertices
  * dunceHatComplex(PolynomialRing),
    -- make a realization of the dunce hat with 8 vertices
  * poincareSphereComplex(PolynomialRing)
    -- make a homology 3-sphere with
    16 vertices
  * nonPiecewiseLinearSphereComplex(PolynomialRing)
    -- make a
    non-piecewise-linear 5-sphere with 18 vertices
  * rudinBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with 14
    vertices and 41 facets
  * grunbaumBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with
    14 vertices and 29 facets
  * zieglerBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with
    10 vertices and 21 facets
  * smallManifold, --
    get a small manifold from the Frank Lutz database

Other operations producing abstract simplicial complexes
========================================================

  * prune(SimplicialComplex) -- make a
    minimal presentation of an abstract simplicial complex
  * inducedSubcomplex(SimplicialComplex,List)
    -- make the induced
    simplicial complex on a subset of vertices
  * dual(SimplicialComplex) -- make the
    Alexander dual of an abstract simplicial complex
  * link(SimplicialComplex,RingElement)
    -- make the link of a face in an
    abstract simplicial complex
  * skeleton(ZZ,SimplicialComplex),
    -- make a new simplicial complex generated by all faces of a bounded
    dimension
  * star(SimplicialComplex,RingElement)
    -- make the star of a face
  * SimplicialComplex * SimplicialComplex
    -- make the join for two abstract simplicial complexes
  * wedge(SimplicialComplex,SimplicialComplex,RingElement,RingElement)
    -- make the wedge sum of two abstract simplicial complexes

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * Working with simplicial maps, --
    information about simplicial maps and the induced operations

map(SimplicialComplex,SimplicialComplex,Matrix) -- create a simplicial map between simplicial complexes
*******************************************************************************************************

Synopsis
========

  * Function: map (Macaulay2Doc),
  * Usage:
        f = map(E,D,M)
        f = map(D,M)
  * Inputs:
      * Delta, an abstract simplicial complex, the
        source, of the simplicial complex
      * Gamma, an abstract simplicial complex, the
        target, of the simplicial map.
      * M, a matrix (Macaulay2Doc), list (Macaulay2Doc),
        or ring map (Macaulay2Doc).
  * Optional inputs (Macaulay2Doc),:
      * Degree (Macaulay2Doc), => ..., default value null, ignored
      * DegreeLift (Macaulay2Doc), => ...,
        default value null, ignored
      * DegreeMap (Macaulay2Doc), => ...,
        default value null, ignored
  * Outputs:
      * f, a map of abstract simplicial complexes,

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

A simplicial map $f: \Delta \to \Gamma$ is a function that sends the vertices
of $\Delta$ to vertices of $\Gamma$, with the added condition that if $\{ v_1,
v_2,..,v_k \} \in \Delta$, then $\{ f(v_1), f(v_2), ..., f(v_n) \} \in \Gamma$.
If no target is specified, it is assumed that the target is the simplicial
complex whose faces are $f(F)$ for all faces $F \in \Delta$. As a first
example, let's look at the identity map on a 3-simplex.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[a,b,c,d];                                                        |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplexComplex(3,S);                                                |
+-----------------------------------------------------------------------------+
|i3 : f = map(Δ,Δ, id_S)                                                      |
|                                                                             |
|o3 = | a b c d |                                                             |
|                                                                             |
|o3 : SimplicialMap simplicialComplex | abcd | <--- simplicialComplex | abcd ||
+-----------------------------------------------------------------------------+
|i4 : matrix f                                                                |
|                                                                             |
|o4 = | a b c d |                                                             |
|                                                                             |
|             1       4                                                       |
|o4 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i5 : map f                                                                   |
|                                                                             |
|o5 = map (S, S, {a, b, c, d})                                                |
|                                                                             |
|o5 : RingMap S <--- S                                                        |
+-----------------------------------------------------------------------------+

Here is a slightly more interesting example.

+-----------------------------------------------------------------------------+
|i6 : R = QQ[s,t,u,v,w];                                                      |
+-----------------------------------------------------------------------------+
|i7 : Γ = simplicialComplex{s*t*u,u*v*w};                                     |
+-----------------------------------------------------------------------------+
|i8 : g = map(Δ,Γ, {a,b,c,d,d})                                               |
|                                                                             |
|o8 = | a b c d d |                                                           |
|                                                                             |
|o8 : SimplicialMap simplicialComplex | abcd | <--- simplicialComplex | uvw   |
|-----------------------------------------------------------------------------|
|stu |                                                                        |
+-----------------------------------------------------------------------------+
|i9 : source g                                                                |
|                                                                             |
|o9 = simplicialComplex | uvw stu |                                           |
|                                                                             |
|o9 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i10 : target g                                                               |
|                                                                             |
|o10 = simplicialComplex | abcd |                                             |
|                                                                             |
|o10 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i11 : image g                                                                |
|                                                                             |
|o11 = simplicialComplex | cd abc |                                           |
|                                                                             |
|o11 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * source(SimplicialMap) -- get the source
    of the map
  * target(SimplicialMap) -- get the target
    of the map
  * image(SimplicialMap) -- construct the
    image of a simplicial map
  * matrix(SimplicialMap) -- get the
    underlying map of rings
  * map(SimplicialMap) -- the underlying ring
    map associated to a simplicial map
  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory

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

  * "map(SimplicialComplex,List)"
  * "map(SimplicialComplex,Matrix)"
  * "map(SimplicialComplex,RingMap)"
  * "map(SimplicialComplex,SimplicialComplex,List)"
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,SimplicialComplex,RingMap)"

map(SimplicialMap) -- the underlying ring map associated to a simplicial map
****************************************************************************

Synopsis
========

  * Function: map (Macaulay2Doc),
  * Usage:
        phi = map f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Optional inputs (Macaulay2Doc),:
      * Degree (Macaulay2Doc), => ..., default value null, ignored
      * DegreeLift (Macaulay2Doc), => ...,
        default value null, ignored
      * DegreeMap (Macaulay2Doc), => ...,
        default value null, ignored
  * Outputs:
      * phi, a ring map (Macaulay2Doc), a map from the ring of
        the source of $f$ to the ring of the target of $f$.

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

Every simplicial map sends the vertices of the source of $f$ to the vertices of
the target of $f$. Consequently, this determines a ring map between the ring of
the source of $f$ and the ring of the target of $f$.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/101[a,b,c,d];                                                    |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplexComplex(3,S)                                                 |
|                                                                             |
|o2 = simplicialComplex | abcd |                                              |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : f = map(Δ,Δ,matrix{{a,b,c,d}})                                          |
|                                                                             |
|o3 = | a b c d |                                                             |
|                                                                             |
|o3 : SimplicialMap simplicialComplex | abcd | <--- simplicialComplex | abcd ||
+-----------------------------------------------------------------------------+
|i4 : map f                                                                   |
|                                                                             |
|o4 = map (S, S, {a, b, c, d})                                                |
|                                                                             |
|o4 : RingMap S <--- S                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * map(SimplicialComplex,SimplicialComplex,RingMap)
    -- create a
    simplicial map between simplicial complexes
  * source(SimplicialMap) -- get the source
    of the map
  * target(SimplicialMap) -- get the target
    of the map
  * matrix(SimplicialMap) -- get the
    underlying map of rings
  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory

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

  * map(SimplicialMap) -- the underlying ring
    map associated to a simplicial map

matrix(SimplicialMap) -- get the underlying map of rings
********************************************************

Synopsis
========

  * Function: matrix (Macaulay2Doc),
  * Usage:
        g = matrix f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Optional inputs (Macaulay2Doc),:
      * Degree (Macaulay2Doc), => ..., default value
        null, unused
  * Outputs:
      * g, a matrix (Macaulay2Doc), having one row

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

A simplicial map is a map $f \colon \Delta \to \Gamma$ such that for any face
$F \subset \Delta$, the image $f(F)$ is contained in a face of $\Gamma$.  Since
an abstract simplicial complex is, in this package, represented by its
Stanley–Reisner ideal in a polynomial ring, the simplicial map $f$ corresponds
to a ring map from the ring of $\Delta$ to the ring of $\Gamma$.  The ring map
is described by a matrix having one row; the entry in the $i$-th column is the
image in the ring of $\Gamma$ of the $i$-th variable in the ring $\Delta$.
This method returns this matrix.

For the identity map, the matrix of variables in the ambient polynomial ring.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_5];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal(x_0*x_5, x_1*x_4, x_2*x_3)          |
|                                                                             |
|o2 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4   |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i3 : id_Δ                                                                    |
|                                                                             |
|o3 = | x_0 x_1 x_2 x_3 x_4 x_5 |                                             |
|                                                                             |
|o3 : SimplicialMap simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5         |
|-----------------------------------------------------------------------------|
|x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | |
|-----------------------------------------------------------------------------|
|x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3        |
|-----------------------------------------------------------------------------|
|x_0x_1x_2 |                                                                  |
+-----------------------------------------------------------------------------+
|i4 : matrix id_Δ                                                             |
|                                                                             |
|o4 = | x_0 x_1 x_2 x_3 x_4 x_5 |                                             |
|                                                                             |
|             1       6                                                       |
|o4 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i5 : assert(matrix id_Δ === vars S)                                          |
+-----------------------------------------------------------------------------+

The next map projects an octahedron onto a square.

+-----------------------------------------------------------------------------+
|i6 : R = ZZ[y_0..y_3];                                                       |
+-----------------------------------------------------------------------------+
|i7 : Γ = simplicialComplex monomialIdeal(y_1*y_2)                            |
|                                                                             |
|o7 = simplicialComplex | y_0y_2y_3 y_0y_1y_3 |                               |
|                                                                             |
|o7 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i8 : f = map(Γ, Δ, {y_0,y_0,y_1,y_2,y_3,y_3})                                |
|                                                                             |
|o8 = | y_0 y_0 y_1 y_2 y_3 y_3 |                                             |
|                                                                             |
|o8 : SimplicialMap simplicialComplex | y_0y_2y_3 y_0y_1y_3 | <---            |
|-----------------------------------------------------------------------------|
|simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4        |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i9 : matrix f                                                                |
|                                                                             |
|o9 = | y_0 y_0 y_1 y_2 y_3 y_3 |                                             |
|                                                                             |
|             1       6                                                       |
|o9 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+

This matrix is simply extracted from the underlying map of rings.

+-----------------------------------------------------------------------------+
|i10 : code(matrix, SimplicialMap)                                            |
|                                                                             |
|o10 = -- code for method: matrix(SimplicialMap)                              |
|      /usr/share/Macaulay2/SimplicialComplexes/Code.m2:                      |
|      matrix SimplicialMap := Matrix => opts -> f -> matrix map f            |
|      -----------------------------------------------------------------------|
|      904:40-904:59: --source code:                                          |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * source(SimplicialMap) -- get the source
    of the map
  * target(SimplicialMap) -- get the target
    of the map
  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes

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

  * matrix(SimplicialMap) -- get the
    underlying map of rings

monomialIdeal(SimplicialComplex) -- get the Stanley–Reisner monomial ideal
**************************************************************************

Synopsis
========

  * Function: monomialIdeal (Macaulay2Doc),
  * Usage:
        monomialIdeal Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a monomial ideal (Macaulay2Doc), that is generated
        by the monomials representing the minimal nonfaces in $\Delta$

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

In this package, an abstract simplicial complex is represented as squarefree
monomial ideal in a polynomial ring.  This
method returns the defining monomial ideal.

The boundary of the 4-simplex is a simplicial sphere with 5 vertices, 5
tetrahedral facets, and a minimal nonface that corresponds to the interior of
the sphere.

+------------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                      |
+------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|                                                                        |
|o2 = simplicialComplex | bcde acde abde abce abcd |                     |
|                                                                        |
|o2 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i3 : I = monomialIdeal Δ                                                |
|                                                                        |
|o3 = monomialIdeal(a*b*c*d*e)                                           |
|                                                                        |
|o3 : MonomialIdeal of S                                                 |
+------------------------------------------------------------------------+
|i4 : dim Δ                                                              |
|                                                                        |
|o4 = 3                                                                  |
+------------------------------------------------------------------------+
|i5 : assert (I == monomialIdeal a*b*c*d*e and numgens I === 1 and       |
|         instance(I, MonomialIdeal) and dim Δ === 3)                    |
+------------------------------------------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.

+--------------------------------------------------------------------+
|i6 : Γ = simplicialComplex {e, c*d, b*d, a*b*c}                     |
|                                                                    |
|o6 = simplicialComplex | e cd bd abc |                              |
|                                                                    |
|o6 : SimplicialComplex                                              |
+--------------------------------------------------------------------+
|i7 : J = monomialIdeal Γ                                            |
|                                                                    |
|o7 = monomialIdeal (a*d, b*c*d, a*e, b*e, c*e, d*e)                 |
|                                                                    |
|o7 : MonomialIdeal of S                                             |
+--------------------------------------------------------------------+
|i8 : assert (J == monomialIdeal (a*d, b*c*d, a*e, b*e, c*e, d*e) and|
|         dim Γ === 2 and instance(J, MonomialIdeal))                |
+--------------------------------------------------------------------+

The irrelevant complex has the empty set as a facet whereas the void complex
has no facets.

+-----------------------------------------------------------------------+
|i9 : irrelevant = simplicialComplex {1_S};                             |
+-----------------------------------------------------------------------+
|i10 : M = monomialIdeal irrelevant                                     |
|                                                                       |
|o10 = monomialIdeal (a, b, c, d, e)                                    |
|                                                                       |
|o10 : MonomialIdeal of S                                               |
+-----------------------------------------------------------------------+
|i11 : void = simplicialComplex monomialIdeal 1_S                       |
|                                                                       |
|o11 = simplicialComplex 0                                              |
|                                                                       |
|o11 : SimplicialComplex                                                |
+-----------------------------------------------------------------------+
|i12 : assert (M == monomialIdeal gens S and instance(M, MonomialIdeal))|
+-----------------------------------------------------------------------+
|i13 : U = monomialIdeal void                                           |
|                                                                       |
|o13 = monomialIdeal 1                                                  |
|                                                                       |
|o13 : MonomialIdeal of S                                               |
+-----------------------------------------------------------------------+
|i14 : assert (U == monomialIdeal 1_S and instance (U, MonomialIdeal))  |
+-----------------------------------------------------------------------+

This routine is identical to ideal(SimplicialComplex),
except for the type (Macaulay2Doc), of
the output.

+-----------------------------------------------------------------------------+
|i15 : printWidth = 250;                                                      |
+-----------------------------------------------------------------------------+
|i16 : code (ideal, SimplicialComplex)                                        |
|                                                                             |
|o16 = -- code for method: ideal(SimplicialComplex)                           |
|      /usr/share/Macaulay2/SimplicialComplexes/Code.m2:19:39-19:50: --source |
|      ideal SimplicialComplex := Ideal => D -> ideal D.monomialIdeal         |
|-----------------------------------------------------------------------------|
|code:                                                                        |
+-----------------------------------------------------------------------------+
|i17 : code (monomialIdeal, SimplicialComplex)                                |
|                                                                             |
|o17 = -- code for method: monomialIdeal(SimplicialComplex)                   |
|      /usr/share/Macaulay2/SimplicialComplexes/Code.m2:20:55-20:             |
|      monomialIdeal SimplicialComplex := MonomialIdeal => D -> D             |
|-----------------------------------------------------------------------------|
|60: --source code:                                                           |
|.monomialIdeal                                                               |
+-----------------------------------------------------------------------------+

As the Stanley–Reisner ideal is part the defining data of an abstract
simplicial complex, so this method does no computation.

+-----------------------------------------------------------------------------+
|i18 : peek Δ                                                                 |
|                                                                             |
|o18 = SimplicialComplex{cache => CacheTable{...1...}                         |
|                        facets => {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e,       |
|                        monomialIdeal => monomialIdeal(a*b*c*d*e)            |
|                        ring => S                                            |
|-----------------------------------------------------------------------------|
|        }                                                                    |
|a*b*c*d}                                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * simplicialComplex(MonomialIdeal)
    -- make a simplicial complex from its
    Stanley–Reisner ideal
  * ideal(SimplicialComplex) -- get the
    Stanley–Reisner ideal
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * ring(SimplicialComplex) -- get the
    polynomial ring of its Stanley–Reisner ideal

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

  * monomialIdeal(SimplicialComplex)
    -- get the Stanley–Reisner monomial
    ideal

net(SimplicialComplex) -- make a symbolic representation of an abstract simplicial complex
******************************************************************************************

Synopsis
========

  * Function: net (Macaulay2Doc),
  * Usage:
        net Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a net (Macaulay2Doc), a symbolic representation used for
        printing

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

The net of an abstract simplicial complex is an expression that lists the
monomials representing the facets (also known as the maximal faces).  This
function is the primary function called upon by << Thing (Macaulay2Doc),
to format for printing.

+----------------------------------------------------------+
|i1 : S = ZZ[a..f];                                        |
+----------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal(a*f, b*d, c*e)   |
|                                                          |
|o2 = simplicialComplex | def bef cdf bcf ade abe acd abc ||
|                                                          |
|o2 : SimplicialComplex                                    |
+----------------------------------------------------------+
|i3 : net Δ                                                |
|                                                          |
|o3 = simplicialComplex | def bef cdf bcf ade abe acd abc ||
+----------------------------------------------------------+
|i4 : assert instance(net Δ, Net)                          |
+----------------------------------------------------------+

The void complex has no facets whereas the irrelevant complex has the empty set
as a facet.

+-----------------------------------------------+
|i5 : void = simplicialComplex monomialIdeal 1_S|
|                                               |
|o5 = simplicialComplex 0                       |
|                                               |
|o5 : SimplicialComplex                         |
+-----------------------------------------------+
|i6 : net void                                  |
|                                               |
|o6 = simplicialComplex 0                       |
+-----------------------------------------------+
|i7 : irrelevant = simplicialComplex {1_S};     |
+-----------------------------------------------+
|i8 : net irrelevant                            |
|                                               |
|o8 = simplicialComplex | 1 |                   |
+-----------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces

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

  * net(SimplicialComplex) -- make a
    symbolic representation of an abstract simplicial complex

net(SimplicialMap) -- make a symbolic representation for a map of abstract simplicial complexes
***********************************************************************************************

Synopsis
========

  * Function: net (Macaulay2Doc),
  * Usage:
        net f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * a net (Macaulay2Doc), a symbolic representation used for
        printing

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

The net of map $f \colon \Delta \to \Gamma$ between abstract simplicial
complexes is a list of variables in the ring of $\Gamma$.  This list determines
a ring map from the ring of $\Delta$ to the ring of $\Gamma$ by sending the
$i$-th variable in the ring of $\Delta$ to the $i$-th monomial on the list.

The identity map $\operatorname{id} \colon \Delta \to \Delta$ corresponds to
list of variables in the ring of $\Delta$.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_5];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal(x_0*x_5, x_1*x_4, x_2*x_3)          |
|                                                                             |
|o2 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4   |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i3 : id_Δ                                                                    |
|                                                                             |
|o3 = | x_0 x_1 x_2 x_3 x_4 x_5 |                                             |
|                                                                             |
|o3 : SimplicialMap simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5         |
|-----------------------------------------------------------------------------|
|x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | |
|-----------------------------------------------------------------------------|
|x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3        |
|-----------------------------------------------------------------------------|
|x_0x_1x_2 |                                                                  |
+-----------------------------------------------------------------------------+
|i4 : net id_Δ                                                                |
|                                                                             |
|o4 = | x_0 x_1 x_2 x_3 x_4 x_5 |                                             |
+-----------------------------------------------------------------------------+
|i5 : matrix id_Δ                                                             |
|                                                                             |
|o5 = | x_0 x_1 x_2 x_3 x_4 x_5 |                                             |
|                                                                             |
|             1       6                                                       |
|o5 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+

The next example does not come from the identity map.

+-----------------------------------------------------------------------------+
|i6 : S' = ZZ[y_0..y_3];                                                      |
+-----------------------------------------------------------------------------+
|i7 : Γ = simplicialComplex monomialIdeal(y_1*y_2)                            |
|                                                                             |
|o7 = simplicialComplex | y_0y_2y_3 y_0y_1y_3 |                               |
|                                                                             |
|o7 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i8 : f = map(Γ, Δ, {y_0,y_0,y_1,y_2,y_3,y_3})                                |
|                                                                             |
|o8 = | y_0 y_0 y_1 y_2 y_3 y_3 |                                             |
|                                                                             |
|o8 : SimplicialMap simplicialComplex | y_0y_2y_3 y_0y_1y_3 | <---            |
|-----------------------------------------------------------------------------|
|simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4        |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i9 : assert isWellDefined f                                                  |
+-----------------------------------------------------------------------------+
|i10 : net f                                                                  |
|                                                                             |
|o10 = | y_0 y_0 y_1 y_2 y_3 y_3 |                                            |
+-----------------------------------------------------------------------------+
|i11 : matrix f                                                               |
|                                                                             |
|o11 = | y_0 y_0 y_1 y_2 y_3 y_3 |                                            |
|                                                                             |
|               1        6                                                    |
|o11 : Matrix S'  <--- S'                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * matrix(SimplicialMap) -- get the
    underlying map of rings
  * net(SimplicialComplex) -- make a
    symbolic representation of an abstract simplicial complex

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

  * net(SimplicialMap) -- make a symbolic
    representation for a map of abstract simplicial complexes

nonPiecewiseLinearSphereComplex(PolynomialRing) -- make a non-piecewise-linear 5-sphere with 18 vertices
********************************************************************************************************

Synopsis
========

  * Function: nonPiecewiseLinearSphereComplex,
  * Usage:
        nonPiecewiseLinearSphereComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that has at
        least 18 generators
  * Outputs:
      * an abstract simplicial complex,

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

A piecewise linear (PL) (see
https://en.wikipedia.org/wiki/Piecewise_linear_manifold ) sphere is a manifold
which is PL homeomorphic to the boundary of a simplex. All the spheres in
dimensions less than or equal to 3 are PL, but there are non-PL spheres in
dimensions larger than or equal to 5.

As described in Theorem 7 in Anders Björner and Frank H. Lutz's "Simplicial
manifolds, bistellar flips and a 16-vertex triangulation of the Poincaré
homology 3-sphere", Experimental Mathematics 9 (2000) 275–289, this method
returns a non-PL 5-sphere constructed from the Björner–Lutz homology sphere,
by taking a double
suspension.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/101[a..s];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = nonPiecewiseLinearSphereComplex S;                                  |
+-----------------------------------------------------------------------------+
|i3 : matrix {facets Δ}                                                       |
|                                                                             |
|o3 = | dmopqr bmopqr glopqr dlopqr bgopqr fjmpqr djmpqr fimpqr bimpqr ehlpqr |
|     ------------------------------------------------------------------------|
|     dhlpqr eglpqr bikpqr aikpqr egkpqr bgkpqr aekpqr dhjpqr chjpqr cfjpqr   |
|     ------------------------------------------------------------------------|
|     cfipqr acipqr aehpqr achpqr fjmoqr djmoqr fimoqr bimoqr ehloqr dhloqr   |
|     ------------------------------------------------------------------------|
|     egloqr bikoqr aikoqr egkoqr bgkoqr aekoqr dhjoqr chjoqr cfjoqr cfioqr   |
|     ------------------------------------------------------------------------|
|     acioqr aehoqr achoqr hkmopr dkmopr ahmopr abmopr gilopr cilopr cdlopr   |
|     ------------------------------------------------------------------------|
|     fhkopr cfkopr cdkopr gijopr eijopr bgjopr aejopr abjopr efiopr cfiopr   |
|     ------------------------------------------------------------------------|
|     efhopr aehopr klmnpr glmnpr hkmnpr ghmnpr iklnpr gilnpr hiknpr ghinpr   |
|     ------------------------------------------------------------------------|
|     jklmpr fjlmpr eglmpr eflmpr djkmpr efimpr beimpr cghmpr achmpr cegmpr   |
|     ------------------------------------------------------------------------|
|     bcempr abcmpr ajklpr aiklpr bfjlpr abjlpr acilpr efhlpr bfhlpr bdhlpr   |
|     ------------------------------------------------------------------------|
|     bcdlpr abclpr dejkpr aejkpr bhikpr bfhkpr cfgkpr bfgkpr cegkpr cdekpr   |
|     ------------------------------------------------------------------------|
|     ghijpr dhijpr deijpr cghjpr cfgjpr bfgjpr bdhipr bdeipr bcdepr klmnor   |
|     ------------------------------------------------------------------------|
|     glmnor hkmnor ghmnor iklnor gilnor hiknor ghinor jklmor fjlmor eglmor   |
|     ------------------------------------------------------------------------|
|     eflmor djkmor efimor beimor cghmor achmor cegmor bcemor abcmor ajklor   |
|     ------------------------------------------------------------------------|
|     aiklor bfjlor abjlor acilor efhlor bfhlor bdhlor bcdlor abclor dejkor   |
|     ------------------------------------------------------------------------|
|     aejkor bhikor bfhkor cfgkor bfgkor cegkor cdekor ghijor dhijor deijor   |
|     ------------------------------------------------------------------------|
|     cghjor cfgjor bfgjor bdhior bdeior bcdeor hkmopq dkmopq ahmopq abmopq   |
|     ------------------------------------------------------------------------|
|     gilopq cilopq cdlopq fhkopq cfkopq cdkopq gijopq eijopq bgjopq aejopq   |
|     ------------------------------------------------------------------------|
|     abjopq efiopq cfiopq efhopq aehopq klmnpq glmnpq hkmnpq ghmnpq iklnpq   |
|     ------------------------------------------------------------------------|
|     gilnpq hiknpq ghinpq jklmpq fjlmpq eglmpq eflmpq djkmpq efimpq beimpq   |
|     ------------------------------------------------------------------------|
|     cghmpq achmpq cegmpq bcempq abcmpq ajklpq aiklpq bfjlpq abjlpq acilpq   |
|     ------------------------------------------------------------------------|
|     efhlpq bfhlpq bdhlpq bcdlpq abclpq dejkpq aejkpq bhikpq bfhkpq cfgkpq   |
|     ------------------------------------------------------------------------|
|     bfgkpq cegkpq cdekpq ghijpq dhijpq deijpq cghjpq cfgjpq bfgjpq bdhipq   |
|     ------------------------------------------------------------------------|
|     bdeipq bcdepq klmnoq glmnoq hkmnoq ghmnoq iklnoq gilnoq hiknoq ghinoq   |
|     ------------------------------------------------------------------------|
|     jklmoq fjlmoq eglmoq eflmoq djkmoq efimoq beimoq cghmoq achmoq cegmoq   |
|     ------------------------------------------------------------------------|
|     bcemoq abcmoq ajkloq aikloq bfjloq abjloq aciloq efhloq bfhloq bdhloq   |
|     ------------------------------------------------------------------------|
|     bcdloq abcloq dejkoq aejkoq bhikoq bfhkoq cfgkoq bfgkoq cegkoq cdekoq   |
|     ------------------------------------------------------------------------|
|     ghijoq dhijoq deijoq cghjoq cfgjoq bfgjoq bdhioq bdeioq bcdeoq |        |
|                                                                             |
|             1       269                                                     |
|o3 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i4 : dim Δ                                                                   |
|                                                                             |
|o4 = 5                                                                       |
+-----------------------------------------------------------------------------+
|i5 : fVector Δ                                                               |
|                                                                             |
|o5 = {1, 18, 141, 515, 930, 807, 269}                                        |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : assert(dim Δ === 5 and isPure Δ)                                        |
+-----------------------------------------------------------------------------+
|i7 : assert(fVector Δ === {1,18,141,515,930,807,269})                        |
+-----------------------------------------------------------------------------+

This abstract simplicial complex is Cohen-Macaulay.

Our enumeration of the vertices follows the nonplsphere (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/nonpl_sphere_eng.html )
example in Masahiro Hachimori's simplicial complex library (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/index_eng.html ).

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * poincareSphereComplex, --
    make a homology 3-sphere with 16 vertices
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional

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

  * nonPiecewiseLinearSphereComplex(PolynomialRing)
    -- make a
    non-piecewise-linear 5-sphere with 18 vertices

poincareSphereComplex(PolynomialRing) -- make a homology 3-sphere with 16 vertices
**********************************************************************************

Synopsis
========

  * Function: poincareSphereComplex,
  * Usage:
        poincareSphereComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that has at
        least 16 generators
  * Outputs:
      * an abstract simplicial complex,

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

The Poincaré homology sphere (see https://en.wikipedia.org/wiki/Homology_sphere
) is a homology 3-sphere; it has the same homology groups as a 3-sphere.
Following Theorem 5 in Anders Björner and Frank H. Lutz's "Simplicial
manifolds, bistellar flips and a 16-vertex triangulation of the Poincaré
homology 3-sphere", Experimental Mathematics 9 (2000) 275–289, this method
returns a Poincaré homology sphere with 16 vertices.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/101[a..q];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = poincareSphereComplex S;                                            |
+-----------------------------------------------------------------------------+
|i3 : matrix {facets Δ}                                                       |
|                                                                             |
|o3 = | mnop inop jmop ijop kmnp iknp jkmp ijkp lmno hlno gino ghno flmo ajmo |
|     ------------------------------------------------------------------------|
|     afmo bhlo bflo ghko bhko dgko bdko eijo cejo acjo egio dego abfo cdeo   |
|     ------------------------------------------------------------------------|
|     acdo abdo clmn ckmn dhln cdln aikn cekn aekn ghjn dhjn bgjn dfjn bfjn   |
|     ------------------------------------------------------------------------|
|     bgin abin defn aefn abfn cden fglm cglm djkm bdkm bckm dhjm ahjm ehim   |
|     ------------------------------------------------------------------------|
|     dhim egim bgim bdim aehm efgm bcgm aefm ijkl fjkl aikl fgkl agkl eijl   |
|     ------------------------------------------------------------------------|
|     bfjl bejl ehil dhil adil behl acgl acdl dfjk aghk behk aehk dfgk bcek   |
|     ------------------------------------------------------------------------|
|     aghj bcgj acgj bcej abdi defg |                                         |
|                                                                             |
|             1       90                                                      |
|o3 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i4 : dim Δ                                                                   |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : fVector Δ                                                               |
|                                                                             |
|o5 = {1, 16, 106, 180, 90}                                                   |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : prune HH chainComplex Δ                                                 |
|                                                                             |
|o6 = -1 : 0                                                                  |
|                                                                             |
|      0 : 0                                                                  |
|                                                                             |
|      1 : 0                                                                  |
|                                                                             |
|      2 : 0                                                                  |
|                                                                             |
|            ZZ 1                                                             |
|      3 : (---)                                                              |
|           101                                                               |
|                                                                             |
|o6 : GradedModule                                                            |
+-----------------------------------------------------------------------------+
|i7 : assert(dim Δ === 3 and isPure Δ)                                        |
+-----------------------------------------------------------------------------+
|i8 : assert(fVector Δ === {1,16,106,180,90})                                 |
+-----------------------------------------------------------------------------+

This abstract simplicial complex is Cohen-Macaulay.

Our enumeration of the vertices also follows the poincare (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/poincare_eng.html )
example in Masahiro Hachimori's simplicial complex library (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/index_eng.html ).

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional
  * nonPiecewiseLinearSphereComplex
    -- make a
    non-piecewise-linear 5-sphere with 18 vertices

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

  * poincareSphereComplex(PolynomialRing)
    -- make a homology 3-sphere with
    16 vertices

prune(SimplicialComplex) -- make a minimal presentation of an abstract simplicial complex
*****************************************************************************************

Synopsis
========

  * Function: prune (Macaulay2Doc),
  * Usage:
        prune Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Optional inputs (Macaulay2Doc),:
      * Exclude (Macaulay2Doc), => a
        list (Macaulay2Doc), default value {}, that is ignored by this
        particular function
  * Outputs:
      * an abstract simplicial complex, where
        vertices are precisely the generators in its polynomial ring

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

In this package, an abstract simplicial complex is represented by its
Stanley–Reisner ideal in a polynomial ring.
When the vertex set of $\Delta$ is a proper subset of the variables in its
polynomial ring, this method creates an isomorphic abstract simplicial complex
such that the generators of its polynomial ring are the vertices of $\Delta$.

When the monomial ideal of the abstract simplicial complex contains no linear
forms, this method just returns the input.

+--------------------------------+
|i1 : S = QQ[a..e];              |
+--------------------------------+
|i2 : Δ4 = simplexComplex(4, S)  |
|                                |
|o2 = simplicialComplex | abcde ||
|                                |
|o2 : SimplicialComplex          |
+--------------------------------+
|i3 : monomialIdeal Δ4           |
|                                |
|o3 = monomialIdeal ()           |
|                                |
|o3 : MonomialIdeal of S         |
+--------------------------------+
|i4 : prune Δ4                   |
|                                |
|o4 = simplicialComplex | abcde ||
|                                |
|o4 : SimplicialComplex          |
+--------------------------------+
|i5 : assert(Δ4 === prune Δ4)    |
+--------------------------------+

When the monomial ideal contains one or more variables, this method returns an
isomorphic abstract simplicial complex represented by a monomial ideal in a
smaller polynomial ring.

+-----------------------------------------------------------+
|i6 : Γ = simplicialComplex monomialIdeal(a, a*b, b*c, c*d) |
|                                                           |
|o6 = simplicialComplex | ce bde |                          |
|                                                           |
|o6 : SimplicialComplex                                     |
+-----------------------------------------------------------+
|i7 : monomialIdeal Γ                                       |
|                                                           |
|o7 = monomialIdeal (a, b*c, c*d)                           |
|                                                           |
|o7 : MonomialIdeal of S                                    |
+-----------------------------------------------------------+
|i8 : prune Γ                                               |
|                                                           |
|o8 = simplicialComplex | ce bde |                          |
|                                                           |
|o8 : SimplicialComplex                                     |
+-----------------------------------------------------------+
|i9 : monomialIdeal prune Γ                                 |
|                                                           |
|o9 = monomialIdeal (b*c, c*d)                              |
|                                                           |
|o9 : MonomialIdeal of QQ[b..e]                             |
+-----------------------------------------------------------+
|i10 : R = ring prune Γ;                                    |
+-----------------------------------------------------------+
|i11 : (gens R, vertices  Γ)                                |
|                                                           |
|o11 = ({b, c, d, e}, {b, c, d, e})                         |
|                                                           |
|o11 : Sequence                                             |
+-----------------------------------------------------------+
|i12 : assert(ring Γ =!= ring prune Γ)                      |
+-----------------------------------------------------------+
|i13 : assert(gens R  === apply(vertices Γ, x -> sub(x, R)))|
+-----------------------------------------------------------+
+------------------------------------------------------------+
|i14 : Δ2 = simplexComplex(2, S)                             |
|                                                            |
|o14 = simplicialComplex | abc |                             |
|                                                            |
|o14 : SimplicialComplex                                     |
+------------------------------------------------------------+
|i15 : prune Δ2                                              |
|                                                            |
|o15 = simplicialComplex | abc |                             |
|                                                            |
|o15 : SimplicialComplex                                     |
+------------------------------------------------------------+
|i16 : R = ring prune Δ2;                                    |
+------------------------------------------------------------+
|i17 : (gens R, vertices  Δ2)                                |
|                                                            |
|o17 = ({a, b, c}, {a, b, c})                                |
|                                                            |
|o17 : Sequence                                              |
+------------------------------------------------------------+
|i18 : assert(ring Δ2 =!= ring prune Δ2)                     |
+------------------------------------------------------------+
|i19 : assert(gens R  === apply(vertices Δ2, x -> sub(x, R)))|
+------------------------------------------------------------+

There are two distinct abstract simplicial complexes that have no vertices.

+-------------------------------------------------+
|i20 : void = simplicialComplex monomialIdeal(1_S)|
|                                                 |
|o20 = simplicialComplex 0                        |
|                                                 |
|o20 : SimplicialComplex                          |
+-------------------------------------------------+
|i21 : facets void                                |
|                                                 |
|o21 = {}                                         |
|                                                 |
|o21 : List                                       |
+-------------------------------------------------+
|i22 : monomialIdeal prune void                   |
|                                                 |
|o22 = monomialIdeal 1                            |
|                                                 |
|o22 : MonomialIdeal of QQ[]                      |
+-------------------------------------------------+
|i23 : assert(gens ring prune void === {})        |
+-------------------------------------------------+
|i24 : assert(monomialIdeal prune void == 1)      |
+-------------------------------------------------+
+-------------------------------------------------+
|i25 : irrelevant = simplicialComplex{1_S}        |
|                                                 |
|o25 = simplicialComplex | 1 |                    |
|                                                 |
|o25 : SimplicialComplex                          |
+-------------------------------------------------+
|i26 : facets irrelevant                          |
|                                                 |
|o26 = {1}                                        |
|                                                 |
|o26 : List                                       |
+-------------------------------------------------+
|i27 : prune irrelevant                           |
|                                                 |
|o27 = simplicialComplex | 1 |                    |
|                                                 |
|o27 : SimplicialComplex                          |
+-------------------------------------------------+
|i28 : monomialIdeal prune irrelevant             |
|                                                 |
|o28 = monomialIdeal ()                           |
|                                                 |
|o28 : MonomialIdeal of QQ[]                      |
+-------------------------------------------------+
|i29 : assert(gens ring prune irrelevant === {})  |
+-------------------------------------------------+
|i30 : assert(monomialIdeal prune irrelevant == 0)|
+-------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * vertices(SimplicialComplex) -- get
    the list of the vertices for an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces

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

  * prune(SimplicialComplex) -- make a
    minimal presentation of an abstract simplicial complex

realProjectiveSpaceComplex(ZZ,PolynomialRing) -- make a small triangulation of real projective space
****************************************************************************************************

Synopsis
========

  * Function: realProjectiveSpaceComplex,
  * Usage:
        realProjectiveSpaceComplex(n, S)
  * Inputs:
      * n, an integer (Macaulay2Doc), that specifies the dimension of
        real projective space
      * S, a polynomial ring (Macaulay2Doc), that
        specifies the polynomial ring containing the Stanley–Reisner ideal
  * Outputs:
      * an abstract simplicial complex, corresponding
        to a triangulation of real projective space

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

This method implements some of the minimal triangulations of real projective
space found in the literature. For $n = 0, 1$, these are just the obvious point
and 1-sphere. For $n = 2$, the minimal triangulation is provided by Frank H.
Lutz's (see http://page.math.tu-berlin.de/~lutz/ ) small manifold database (see
http://page.math.tu-berlin.de/~lutz/stellar/ ). Frank Lutz has also provided
minimal triangulations for $n = 3$ and $4$, in "Triangulated Manifolds with Few
Vertices: Combinatorial Manifolds", arXiv:math/0506372v1 (see
https://arxiv.org/abs/math/0506372 ).

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_10]                                                       |
|                                                                             |
|o1 = S                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : Δ = realProjectiveSpaceComplex(3, S)                                    |
|                                                                             |
|o2 = simplicialComplex | x_3x_4x_5x_10 x_0x_4x_5x_10 x_1x_3x_5x_10           |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_1x_5x_10 x_2x_3x_4x_10 x_0x_2x_4x_10 x_1x_2x_3x_10 x_0x_1x_2x_10        |
|-----------------------------------------------------------------------------|
|x_2x_5x_8x_9 x_1x_5x_8x_9 x_2x_4x_8x_9 x_1x_4x_8x_9 x_1x_4x_7x_9 x_0x_4x_7x_9|
|-----------------------------------------------------------------------------|
|x_1x_3x_7x_9 x_0x_3x_7x_9 x_3x_5x_6x_9 x_2x_5x_6x_9 x_0x_3x_6x_9 x_0x_2x_6x_9|
|-----------------------------------------------------------------------------|
|x_1x_3x_5x_9 x_0x_2x_4x_9 x_2x_5x_7x_8 x_0x_5x_7x_8 x_2x_3x_7x_8 x_0x_3x_7x_8|
|-----------------------------------------------------------------------------|
|x_3x_4x_6x_8 x_1x_4x_6x_8 x_0x_3x_6x_8 x_0x_1x_6x_8 x_0x_1x_5x_8 x_2x_3x_4x_8|
|-----------------------------------------------------------------------------|
|x_4x_5x_6x_7 x_2x_5x_6x_7 x_1x_4x_6x_7 x_1x_2x_6x_7 x_0x_4x_5x_7 x_1x_2x_3x_7|
|-----------------------------------------------------------------------------|
|x_3x_4x_5x_6 x_0x_1x_2x_6 |                                                  |
+-----------------------------------------------------------------------------+

Caveat
======

Since no minimal or small triangulations of real projective space have been
constructed for $n > 4$, we haven't implemented the triangulations for higher
projective space yet. Due to the exponential growth of the number of vertices,
computations quickly become intractable.

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * smallManifold(ZZ,ZZ,ZZ,PolynomialRing)
    -- get a small manifold
    from the Frank Lutz database
  * smallManifold, --
    get a small manifold from the Frank Lutz database

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

  * realProjectiveSpaceComplex(ZZ,PolynomialRing)
    -- make a small
    triangulation of real projective space

ring(SimplicialComplex) -- get the polynomial ring of its Stanley–Reisner ideal
*******************************************************************************

Synopsis
========

  * Function: ring (Macaulay2Doc),
  * Usage:
        ring Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a polynomial ring (Macaulay2Doc), containing the
        defining Stanley–Reisner ideal

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

In this package, an abstract simplicial complex is represented as squarefree
monomial ideal in a polynomial ring.  In
particular, the vertices of an abstract simplicial complex are a subset of the
variables in that polynomial ring. This method returns the polynomial ring
containing the vertices of the simplicial complex.

The boundary of the 4-simplex is a simplicial sphere with 5 vertices, 5
tetrahedral facets, and a minimal nonface that corresponds to the interior of
the sphere.

+------------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                      |
+------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}|
|                                                                        |
|o2 = simplicialComplex | bcde acde abde abce abcd |                     |
|                                                                        |
|o2 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i3 : ring Δ                                                             |
|                                                                        |
|o3 = S                                                                  |
|                                                                        |
|o3 : PolynomialRing                                                     |
+------------------------------------------------------------------------+
|i4 : coefficientRing Δ                                                  |
|                                                                        |
|o4 = ZZ                                                                 |
|                                                                        |
|o4 : Ring                                                               |
+------------------------------------------------------------------------+
|i5 : dim Δ                                                              |
|                                                                        |
|o5 = 3                                                                  |
+------------------------------------------------------------------------+
|i6 : assert (ring Δ === S and coefficientRing Δ === ZZ)                 |
+------------------------------------------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.

+------------------------------------------------------------+
|i7 : R = ZZ/101[a..e];                                      |
+------------------------------------------------------------+
|i8 : Γ = simplicialComplex {e, c*d, b*d, a*b*c}             |
|                                                            |
|o8 = simplicialComplex | e cd bd abc |                      |
|                                                            |
|o8 : SimplicialComplex                                      |
+------------------------------------------------------------+
|i9 : ring Γ                                                 |
|                                                            |
|o9 = R                                                      |
|                                                            |
|o9 : PolynomialRing                                         |
+------------------------------------------------------------+
|i10 : ideal Γ                                               |
|                                                            |
|o10 = ideal (a*d, b*c*d, a*e, b*e, c*e, d*e)                |
|                                                            |
|o10 : Ideal of R                                            |
+------------------------------------------------------------+
|i11 : assert (ring Γ === R and coefficientRing Γ === ZZ/101)|
+------------------------------------------------------------+

The irrelevant complex has the empty set as a facet whereas the void complex
has no facets.

+--------------------------------------------------------+
|i12 : irrelevant = simplicialComplex {1_R};             |
+--------------------------------------------------------+
|i13 : ring irrelevant                                   |
|                                                        |
|o13 = R                                                 |
|                                                        |
|o13 : PolynomialRing                                    |
+--------------------------------------------------------+
|i14 : void = simplicialComplex monomialIdeal 1_S        |
|                                                        |
|o14 = simplicialComplex 0                               |
|                                                        |
|o14 : SimplicialComplex                                 |
+--------------------------------------------------------+
|i15 : ring void                                         |
|                                                        |
|o15 = S                                                 |
|                                                        |
|o15 : PolynomialRing                                    |
+--------------------------------------------------------+
|i16 : assert (ring irrelevant === R and ring void === S)|
+--------------------------------------------------------+

As the Stanley–Reisner ideal is part the defining data of an abstract
simplicial complex, so this method does no computation.

+-----------------------------------------------------------------------------+
|i17 : peek Δ                                                                 |
|                                                                             |
|o17 = SimplicialComplex{cache => CacheTable{...1...}                         |
|                        facets => {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e,       |
|                        monomialIdeal => monomialIdeal(a*b*c*d*e)            |
|                        ring => S                                            |
|-----------------------------------------------------------------------------|
|        }                                                                    |
|a*b*c*d}                                                                     |
+-----------------------------------------------------------------------------+

Caveat
======

Although an abstract simplicial complex can be represented by a Stanley–Reisner
ideal in any polynomial ring with a sufficiently large number of variables,
some operations in this package do depend of the choice of the polynomial ring
(or its coefficient ring).  For example, the chain complex,
of an abstract simplicial complex is
typically constructed over the coefficient ring of this polynomial ring, and
the dual of a simplicial complex (or monomial ideal) is dependent on the number
of variables in the polynomial ideal.

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * simplicialComplex(MonomialIdeal)
    -- make a simplicial complex from its
    Stanley–Reisner ideal
  * monomialIdeal(SimplicialComplex)
    -- get the Stanley–Reisner monomial
    ideal
  * coefficientRing(SimplicialComplex)
    -- get the coefficient ring of the
    underlying polynomial ring

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

  * ring(SimplicialComplex) -- get the
    polynomial ring of its Stanley–Reisner ideal

rudinBallComplex(PolynomialRing) -- make a nonshellable 3-ball with 14 vertices and 41 facets
*********************************************************************************************

Synopsis
========

  * Function: rudinBallComplex,
  * Usage:
        rudinBallComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that has at
        least 14 generators
  * Outputs:
      * an abstract simplicial complex,

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

As described in Mary Ellen Rudin's "An unshellable triangulation of a
tetrahedron" (see https://www.ams.org/journals/bull/1958-64-03/S0002-9904-1958-
10168-8/S0002-9904-1958-10168-8.pdf ), Bulletin of the American Mathematical
Society 64 (1958) 90–91, this method returns triangulation of a 3-ball with 14
vertices and 41 facets that is not shellable (see
https://en.wikipedia.org/wiki/Shelling_(topology) ).  This abstract simplicial
complex has a convex realization.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/101[a..s];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = rudinBallComplex S;                                                 |
+-----------------------------------------------------------------------------+
|i3 : matrix {facets Δ}                                                       |
|                                                                             |
|o3 = | klmn hlmn ikmn fjmn djmn fimn dhmn jkln bjln bhln cjkn eikn egkn cgkn |
|     ------------------------------------------------------------------------|
|     cfjn bdjn efin bdhn gklm eilm cilm ehlm cglm aikm agkm efim acim dehm   |
|     ------------------------------------------------------------------------|
|     acgm fjkl fhkl dhkl dgkl bfjl bfhl dehl cdgl cfjk aeik aegk cdgk |      |
|                                                                             |
|             1       41                                                      |
|o3 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i4 : dim Δ                                                                   |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : fVector Δ                                                               |
|                                                                             |
|o5 = {1, 14, 66, 94, 41}                                                     |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : assert(dim Δ === 3 and isPure Δ)                                        |
+-----------------------------------------------------------------------------+
|i7 : assert(fVector Δ === {1,14,66,94,41})                                   |
+-----------------------------------------------------------------------------+

This abstract simplicial complex is Cohen-Macaulay but not shellable.

Our enumeration of the vertices follows the rudin (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/rudin_eng.html ) example
in Masahiro Hachimori's simplicial complex library (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/index_eng.html ).

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * grunbaumBallComplex -- make
    a nonshellable 3-ball with 14 vertices and 29 facets
  * zieglerBallComplex -- make a
    nonshellable 3-ball with 10 vertices and 21 facets
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional

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

  * rudinBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with 14
    vertices and 41 facets

scarfChainComplex -- create the Scarf chain complex for a list of monomials.
****************************************************************************

Synopsis
========

  * Usage:
        scarfChainComplex L
        scarfChainComplex M
  * Inputs:
      * L, a list (Macaulay2Doc), of monomials in a polynomial
        ring, that minimally generate a monomial ideal.
      * M, a monomial ideal (Macaulay2Doc),
  * Outputs:
      * C, a chain complex (Macaulay2Doc),

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

For a monomial ideal $M$, minimally generated by a list of monomials $L$ in a
polynomial ring $S$, the Scarf complex is the subcomplex of the Taylor
resolution of $S/M$ that is induced on the multihomogeneous basis elements with
unique multidegrees. If the Scarf Complex is a resolution, then it is the
minimal free resolution of $S/M$. For more information on the Scarf complex and
its construction, see Bayer, Dave; Peeva, Irena; Sturmfels, Bernd Monomial
Resolutions (see https://www.intlpress.com/site/pub/files/_fulltext/journals/
mrl/1998/0005/0001/MRL-1998-0005-0001-a003.pdf ). Math. Res. Lett. 5 (1998),
no. 1-2, 31–46, or Jeff Mermin Three Simplicial Resolutions (see
https://www.degruyter.com/view/book/9783110250404/10.1515/9783110250404.127.xml
), (English summary) Progress in commutative algebra 1, 127–141, de Gruyter,
Berlin, 2012.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[x_0..x_3, Degrees => {{1,0,0,0},{0,1,0,0},{0,0,1,0},{0,0,0,1}}]; |
+-----------------------------------------------------------------------------+
|i2 : M = monomialIdeal(x_0*x_1,x_0*x_3,x_1*x_2,x_2*x_3);                     |
|                                                                             |
|o2 : MonomialIdeal of S                                                      |
+-----------------------------------------------------------------------------+
|i3 : T = taylorResolution M;                                                 |
+-----------------------------------------------------------------------------+
|i4 : C = scarfChainComplex M;                                                |
+-----------------------------------------------------------------------------+
|i5 : T.dd                                                                    |
|                                                                             |
|          1                                       4                          |
|o5 = 0 : S  <----------------------------------- S  : 1                      |
|               | x_2x_3 x_0x_3 x_1x_2 x_0x_1 |                               |
|                                                                             |
|          4                                                            6     |
|     1 : S  <-------------------------------------------------------- S  : 2 |
|               {0, 0, 1, 1} | -x_0 -x_1 -x_0x_1 0       0    0    |          |
|               {1, 0, 0, 1} | x_2  0    0       -x_1x_2 -x_1 0    |          |
|               {0, 1, 1, 0} | 0    x_3  0       x_0x_3  0    -x_0 |          |
|               {1, 1, 0, 0} | 0    0    x_2x_3  0       x_3  x_2  |          |
|                                                                             |
|          6                                          4                       |
|     2 : S  <-------------------------------------- S  : 3                   |
|               {1, 0, 1, 1} | x_1  x_1 0   0    |                            |
|               {0, 1, 1, 1} | -x_0 0   x_0 0    |                            |
|               {1, 1, 1, 1} | 0    -1  -1  0    |                            |
|               {1, 1, 1, 1} | 1    0   0   1    |                            |
|               {1, 1, 0, 1} | 0    x_2 0   -x_2 |                            |
|               {1, 1, 1, 0} | 0    0   x_3 x_3  |                            |
|                                                                             |
|          4                           1                                      |
|     3 : S  <----------------------- S  : 4                                  |
|               {1, 1, 1, 1} | -1 |                                           |
|               {1, 1, 1, 1} | 1  |                                           |
|               {1, 1, 1, 1} | -1 |                                           |
|               {1, 1, 1, 1} | 1  |                                           |
|                                                                             |
|o5 : ChainComplexMap                                                         |
+-----------------------------------------------------------------------------+
|i6 : C.dd                                                                    |
|                                                                             |
|          1                                       4                          |
|o6 = 0 : S  <----------------------------------- S  : 1                      |
|               | x_2x_3 x_0x_3 x_1x_2 x_0x_1 |                               |
|                                                                             |
|          4                                            4                     |
|     1 : S  <---------------------------------------- S  : 2                 |
|               {0, 0, 1, 1} | -x_0 -x_1 0    0    |                          |
|               {1, 0, 0, 1} | x_2  0    -x_1 0    |                          |
|               {0, 1, 1, 0} | 0    x_3  0    -x_0 |                          |
|               {1, 1, 0, 0} | 0    0    x_3  x_2  |                          |
|                                                                             |
|o6 : ChainComplexMap                                                         |
+-----------------------------------------------------------------------------+
|i7 : flatten for i to length C list degrees C_i                              |
|                                                                             |
|o7 = {{0, 0, 0, 0}, {0, 0, 1, 1}, {1, 0, 0, 1}, {0, 1, 1, 0}, {1, 1, 0, 0},  |
|     ------------------------------------------------------------------------|
|     {1, 0, 1, 1}, {0, 1, 1, 1}, {1, 1, 0, 1}, {1, 1, 1, 0}}                 |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : prune homology C                                                        |
|                                                                             |
|o8 = 0 : cokernel | x_2x_3 x_0x_3 x_1x_2 x_0x_1 |                            |
|                                                                             |
|     1 : 0                                                                   |
|                                                                             |
|          1                                                                  |
|     2 : S                                                                   |
|                                                                             |
|o8 : GradedModule                                                            |
+-----------------------------------------------------------------------------+
|i9 : T' = taylorResolution{x_0*x_1,x_0*x_2,x_0*x_3};                         |
+-----------------------------------------------------------------------------+
|i10 : C' = scarfChainComplex{x_0*x_1,x_0*x_2,x_0*x_3};                       |
+-----------------------------------------------------------------------------+
|i11 : T'.dd                                                                  |
|                                                                             |
|           1                                3                                |
|o11 = 0 : S  <---------------------------- S  : 1                            |
|                | x_0x_1 x_0x_2 x_0x_3 |                                     |
|                                                                             |
|           3                                       3                         |
|      1 : S  <----------------------------------- S  : 2                     |
|                {1, 1, 0, 0} | -x_2 -x_3 0    |                              |
|                {1, 0, 1, 0} | x_1  0    -x_3 |                              |
|                {1, 0, 0, 1} | 0    x_1  x_2  |                              |
|                                                                             |
|           3                             1                                   |
|      2 : S  <------------------------- S  : 3                               |
|                {1, 1, 1, 0} | x_3  |                                        |
|                {1, 1, 0, 1} | -x_2 |                                        |
|                {1, 0, 1, 1} | x_1  |                                        |
|                                                                             |
|o11 : ChainComplexMap                                                        |
+-----------------------------------------------------------------------------+
|i12 : C'.dd                                                                  |
|                                                                             |
|           1                                3                                |
|o12 = 0 : S  <---------------------------- S  : 1                            |
|                | x_0x_1 x_0x_2 x_0x_3 |                                     |
|                                                                             |
|           3                                       3                         |
|      1 : S  <----------------------------------- S  : 2                     |
|                {1, 1, 0, 0} | -x_2 -x_3 0    |                              |
|                {1, 0, 1, 0} | x_1  0    -x_3 |                              |
|                {1, 0, 0, 1} | 0    x_1  x_2  |                              |
|                                                                             |
|           3                             1                                   |
|      2 : S  <------------------------- S  : 3                               |
|                {1, 1, 1, 0} | x_3  |                                        |
|                {1, 1, 0, 1} | -x_2 |                                        |
|                {1, 0, 1, 1} | x_1  |                                        |
|                                                                             |
|o12 : ChainComplexMap                                                        |
+-----------------------------------------------------------------------------+
|i13 : prune homology C'                                                      |
|                                                                             |
|o13 = 0 : cokernel | x_0x_3 x_0x_2 x_0x_1 |                                  |
|                                                                             |
|      1 : 0                                                                  |
|                                                                             |
|      2 : 0                                                                  |
|                                                                             |
|      3 : 0                                                                  |
|                                                                             |
|o13 : GradedModule                                                           |
+-----------------------------------------------------------------------------+
|i14 : flatten for i to length C list degrees C'_i                            |
|                                                                             |
|o14 = {{0, 0, 0, 0}, {1, 1, 0, 0}, {1, 0, 1, 0}, {1, 0, 0, 1}, {1, 1, 1, 0}, |
|      -----------------------------------------------------------------------|
|      {1, 1, 0, 1}, {1, 0, 1, 1}}                                            |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * scarfSimplicialComplex -- create the Scarf
    simplicial complex for a list of monomials
  * taylorResolution -- create the Taylor resolution
    of a monomial ideal
  * lyubeznikSimplicialComplex -- create a
    simplicial complex supporting a Lyubeznik resolution of a monomial ideal

Ways to use scarfChainComplex :
===============================

  * "scarfChainComplex(List)"
  * "scarfChainComplex(MonomialIdeal)"

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

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

scarfSimplicialComplex -- create the Scarf simplicial complex for a list of monomials
*************************************************************************************

Synopsis
========

  * Usage:
        scarfSimplicialComplex(L, R)
        scarfSimplicialComplex(M, R)
  * Inputs:
      * L, a list (Macaulay2Doc), of monomials in a polynomial
        ring, that minimally generate a monomial ideal
      * M, a monomial ideal (Macaulay2Doc),
      * R, a ring (Macaulay2Doc), the ambient ring used to
        construct the Scarf simplicial complex.
  * Outputs:
      * D, an abstract simplicial complex,

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

The Scarf simplicial complex is the simplicial complex that supports the Scarf
complex of a monomial ideal. The Scarf complex does not need to be an acyclic
simplicial complex. In fact, every simplicial complex that is not the boundary
of a simplex is the Scarf complex for some monomial ideal, see Theorem 5.3 in
Peeva, Irena; Velasco, Mauricio Frames and Degenerations of Monomial
Resolutions (see http://citeseerx.ist.psu.edu/viewdoc/download?doi=
10.1.1.145.2645&rep=rep1&type=pdf ). For more information on the Scarf
simplicial complex and its construction, see Bayer, Dave; Peeva, Irena;
Sturmfels, Bernd Monomial Resolutions (see
https://www.intlpress.com/site/pub/files/_fulltext/journals/mrl/1998/0005/0001/
MRL-1998-0005-0001-a003.pdf ). Math. Res. Lett. 5 (1998), no. 1-2, 31–46, or
Jeff Mermin Three Simplicial Resolutions (see
https://www.degruyter.com/view/book/9783110250404/10.1515/9783110250404.127.xml
), (English summary) Progress in commutative algebra 1, 127–141, de Gruyter,
Berlin, 2012.

+--------------------------------------------------------+
|i1 : R = ZZ[a,b,c,d];                                   |
+--------------------------------------------------------+
|i2 : S = ZZ/17[x_0..x_3];                               |
+--------------------------------------------------------+
|i3 : M  = monomialIdeal(x_0*x_1,x_1*x_2,x_2*x_3)        |
|                                                        |
|o3 = monomialIdeal (x x , x x , x x )                   |
|                     0 1   1 2   2 3                    |
|                                                        |
|o3 : MonomialIdeal of S                                 |
+--------------------------------------------------------+
|i4 : D = scarfSimplicialComplex(M,R)                    |
|                                                        |
|o4 = simplicialComplex | bc ab |                        |
|                                                        |
|o4 : SimplicialComplex                                  |
+--------------------------------------------------------+
|i5 : prune homology D                                   |
|                                                        |
|o5 = -1 : 0                                             |
|                                                        |
|      0 : 0                                             |
|                                                        |
|      1 : 0                                             |
|                                                        |
|o5 : GradedModule                                       |
+--------------------------------------------------------+
|i6 : M' = monomialIdeal(x_0*x_1,x_0*x_3,x_1*x_2,x_2*x_3)|
|                                                        |
|o6 = monomialIdeal (x x , x x , x x , x x )             |
|                     0 1   1 2   0 3   2 3              |
|                                                        |
|o6 : MonomialIdeal of S                                 |
+--------------------------------------------------------+
|i7 : D' = scarfSimplicialComplex(M',R)                  |
|                                                        |
|o7 = simplicialComplex | cd bd ac ab |                  |
|                                                        |
|o7 : SimplicialComplex                                  |
+--------------------------------------------------------+
|i8 : prune homology D'                                  |
|                                                        |
|o8 = -1 : 0                                             |
|                                                        |
|      0 : 0                                             |
|                                                        |
|            1                                           |
|      1 : ZZ                                            |
|                                                        |
|o8 : GradedModule                                       |
+--------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * SimplicialComplexes -- exploring abstract simplicial complexes
    within commutative algebra
  * scarfChainComplex -- create the Scarf chain
    complex for a list of monomials.
  * lyubeznikSimplicialComplex -- create a
    simplicial complex supporting a Lyubeznik resolution of a monomial ideal

Ways to use scarfSimplicialComplex :
====================================

  * "scarfSimplicialComplex(List,Ring)"
  * "scarfSimplicialComplex(MonomialIdeal,Ring)"

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

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

simplexComplex(ZZ,PolynomialRing) -- make the simplex as an abstract simplicial complex
***************************************************************************************

Synopsis
========

  * Function: simplexComplex,
  * Usage:
        simplexComplex (d, S)
  * Inputs:
      * d, an integer (Macaulay2Doc), that is the dimension of the
        simplex
      * S, a polynomial ring (Macaulay2Doc), that has at
        least $d+1$ generators
  * Outputs:
      * an abstract simplicial complex, that has a
        unique facet of dimension $d$

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

A simplex is a generalization of the notion of a triangle or tetrahedron to
arbitrary dimensions.  For example, a 0-simplex is a point, a 1-simplex is a
line segment, a 2-simplex is a triangle, and a 3-simplex is a tetrahedron.  The
$d$-simplex is the unique $d$-dimensional abstract simplicial complex having
one facet.  Furthermore, in the $d$-simplex, there are $\binom{d+1}{k+1}$ faces
having dimension $k$.

+-----------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                               |
+-----------------------------------------------------------------+
|i2 : irrelevant = simplexComplex (-1, S)                         |
|                                                                 |
|o2 = simplicialComplex | 1 |                                     |
|                                                                 |
|o2 : SimplicialComplex                                           |
+-----------------------------------------------------------------+
|i3 : monomialIdeal irrelevant                                    |
|                                                                 |
|o3 = monomialIdeal (a, b, c, d, e)                               |
|                                                                 |
|o3 : MonomialIdeal of S                                          |
+-----------------------------------------------------------------+
|i4 : dim irrelevant                                              |
|                                                                 |
|o4 = -1                                                          |
+-----------------------------------------------------------------+
|i5 : fVector irrelevant                                          |
|                                                                 |
|o5 = {1}                                                         |
|                                                                 |
|o5 : List                                                        |
+-----------------------------------------------------------------+
|i6 : assert(facets irrelevant === {1_S})                         |
+-----------------------------------------------------------------+
|i7 : assert(dim irrelevant === -1 and fVector irrelevant === {1})|
+-----------------------------------------------------------------+
+------------------------------------------------+
|i8 : Δ0 = simplexComplex (0, S)                 |
|                                                |
|o8 = simplicialComplex | a |                    |
|                                                |
|o8 : SimplicialComplex                          |
+------------------------------------------------+
|i9 : monomialIdeal Δ0                           |
|                                                |
|o9 = monomialIdeal (b, c, d, e)                 |
|                                                |
|o9 : MonomialIdeal of S                         |
+------------------------------------------------+
|i10 : dim Δ0                                    |
|                                                |
|o10 = 0                                         |
+------------------------------------------------+
|i11 : fVector Δ0                                |
|                                                |
|o11 = {1, 1}                                    |
|                                                |
|o11 : List                                      |
+------------------------------------------------+
|i12 : assert(facets Δ0 === {a} and dim Δ0 === 0)|
+------------------------------------------------+
|i13 : assert(fVector Δ0 == {1,1})               |
+------------------------------------------------+
+--------------------------------------------------+
|i14 : Δ1 = simplexComplex (1, S)                  |
|                                                  |
|o14 = simplicialComplex | ab |                    |
|                                                  |
|o14 : SimplicialComplex                           |
+--------------------------------------------------+
|i15 : monomialIdeal Δ1                            |
|                                                  |
|o15 = monomialIdeal (c, d, e)                     |
|                                                  |
|o15 : MonomialIdeal of S                          |
+--------------------------------------------------+
|i16 : dim Δ1                                      |
|                                                  |
|o16 = 1                                           |
+--------------------------------------------------+
|i17 : fVector Δ1                                  |
|                                                  |
|o17 = {1, 2, 1}                                   |
|                                                  |
|o17 : List                                        |
+--------------------------------------------------+
|i18 : assert(facets Δ1 === {a*b} and dim Δ1 === 1)|
+--------------------------------------------------+
|i19 : assert(fVector Δ1 === {1,2,1})              |
+--------------------------------------------------+
+----------------------------------------------------+
|i20 : Δ2 = simplexComplex (2, S)                    |
|                                                    |
|o20 = simplicialComplex | abc |                     |
|                                                    |
|o20 : SimplicialComplex                             |
+----------------------------------------------------+
|i21 : monomialIdeal Δ2                              |
|                                                    |
|o21 = monomialIdeal (d, e)                          |
|                                                    |
|o21 : MonomialIdeal of S                            |
+----------------------------------------------------+
|i22 : dim Δ2                                        |
|                                                    |
|o22 = 2                                             |
+----------------------------------------------------+
|i23 : fVector Δ2                                    |
|                                                    |
|o23 = {1, 3, 3, 1}                                  |
|                                                    |
|o23 : List                                          |
+----------------------------------------------------+
|i24 : assert(facets Δ2 === {a*b*c} and dim Δ2 === 2)|
+----------------------------------------------------+
|i25 : assert(fVector Δ2 === {1,3,3,1})              |
+----------------------------------------------------+
+------------------------------------------------------------------------+
|i26 : Δ3 = simplexComplex (3, S)                                        |
|                                                                        |
|o26 = simplicialComplex | abcd |                                        |
|                                                                        |
|o26 : SimplicialComplex                                                 |
+------------------------------------------------------------------------+
|i27 : monomialIdeal Δ3                                                  |
|                                                                        |
|o27 = monomialIdeal e                                                   |
|                                                                        |
|o27 : MonomialIdeal of S                                                |
+------------------------------------------------------------------------+
|i28 : dim Δ3                                                            |
|                                                                        |
|o28 = 3                                                                 |
+------------------------------------------------------------------------+
|i29 : fVector Δ3                                                        |
|                                                                        |
|o29 = {1, 4, 6, 4, 1}                                                   |
|                                                                        |
|o29 : List                                                              |
+------------------------------------------------------------------------+
|i30 : assert(facets Δ3 === {a*b*c*d} and dim Δ3 === 3)                  |
+------------------------------------------------------------------------+
|i31 : assert(fVector Δ3 === toList apply(-1..3, i -> binomial(3+1,i+1)))|
+------------------------------------------------------------------------+
+------------------------------------------------------------------------+
|i32 : Δ4 = simplexComplex (4, S)                                        |
|                                                                        |
|o32 = simplicialComplex | abcde |                                       |
|                                                                        |
|o32 : SimplicialComplex                                                 |
+------------------------------------------------------------------------+
|i33 : monomialIdeal Δ4                                                  |
|                                                                        |
|o33 = monomialIdeal ()                                                  |
|                                                                        |
|o33 : MonomialIdeal of S                                                |
+------------------------------------------------------------------------+
|i34 : dim Δ4                                                            |
|                                                                        |
|o34 = 4                                                                 |
+------------------------------------------------------------------------+
|i35 : fVector Δ4                                                        |
|                                                                        |
|o35 = {1, 5, 10, 10, 5, 1}                                              |
|                                                                        |
|o35 : List                                                              |
+------------------------------------------------------------------------+
|i36 : assert(facets Δ4 === {a*b*c*d*e} and dim Δ4 === 4)                |
+------------------------------------------------------------------------+
|i37 : assert(fVector Δ4 === toList apply(-1..4, i -> binomial(4+1,i+1)))|
+------------------------------------------------------------------------+

The vertices in the $d$-simplex are the first $d+1$ variables in the given
polynomial ring.

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex

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

  * simplexComplex(ZZ,PolynomialRing)
    -- make the simplex as an abstract
    simplicial complex

SimplicialComplex -- the class of all abstract simplicial complexes
*******************************************************************

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

An abstract simplicial complex on a finite set is a family of subsets that is
closed under taking subsets.  The elements in the abstract simplicial complex
are called its faces.  The faces having cardinality 1 are its vertices and the
maximal faces (order by inclusion) are its facets.  Following the combinatorial
conventions, every nonempty abstract simplicial complex has the empty set as a
face.

In this package, a simplicial complex is represented by its Stanley–Reisner
ideal (see https://en.wikipedia.org/wiki/Stanley–Reisner_ring ). The vertices
are identified with a subset of the variables in a polynomial ring and each
face is identified with the product of the corresponding variables. A nonface
is any subset of the variables that does not belong to the simplicial complex
and each nonface is again identified with a product of variables. The
Stanley-Reisner ideal of a simplicial complex is generated by monomials
corresponding to its nonfaces.

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations
  * Working with simplicial maps, --
    information about simplicial maps and the induced operations

Functions and methods returning an abstract simplicial complex :
================================================================

  * bartnetteSphereComplex(PolynomialRing)
    -- make a non-polytopal
    3-sphere with 8 vertices
  * barycentricSubdivision(SimplicialComplex,Ring)
    -- create the
    barycentric subdivision of a simplicial complex
  * bjornerComplex(PolynomialRing),
    -- make a shellable 2-polyhedron with 6 vertices
  * dual(SimplicialComplex) -- make the
    Alexander dual of an abstract simplicial complex
  * dunceHatComplex(PolynomialRing),
    -- make a realization of the dunce hat with 8 vertices
  * elementaryCollapse(SimplicialComplex,RingElement)
    -- construct the
    elementary collapse of a free face in a simplicial complex
  * grunbaumBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with
    14 vertices and 29 facets
  * image(SimplicialMap) -- construct the
    image of a simplicial map
  * inducedSubcomplex(SimplicialComplex,List)
    -- make the induced
    simplicial complex on a subset of vertices
  * kleinBottleComplex(PolynomialRing)
    -- make a minimal triangulation of
    the Klein bottle
  * link(SimplicialComplex,RingElement)
    -- make the link of a face in an
    abstract simplicial complex
  * nonPiecewiseLinearSphereComplex(PolynomialRing)
    -- make a
    non-piecewise-linear 5-sphere with 18 vertices
  * poincareSphereComplex(PolynomialRing)
    -- make a homology 3-sphere with
    16 vertices
  * prune(SimplicialComplex) -- make a
    minimal presentation of an abstract simplicial complex
  * realProjectiveSpaceComplex(ZZ,PolynomialRing)
    -- make a small
    triangulation of real projective space
  * rudinBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with 14
    vertices and 41 facets
  * simplexComplex(ZZ,PolynomialRing)
    -- make the simplex as an abstract
    simplicial complex
  * simplicialComplex(List) -- make an
    abstract simplicial complex from a list of faces
  * "simplicialComplex(Matrix)" -- see simplicialComplex(List),
    -- make an abstract simplicial complex from a
    list of faces
  * "simplicialComplex(Ideal)" -- see simplicialComplex(MonomialIdeal),
    -- make a simplicial complex from its
    Stanley–Reisner ideal
  * simplicialComplex(MonomialIdeal)
    -- make a simplicial complex from its
    Stanley–Reisner ideal
  * skeleton(ZZ,SimplicialComplex),
    -- make a new simplicial complex generated by all faces of a bounded
    dimension
  * smallManifold(ZZ,ZZ,ZZ,PolynomialRing)
    -- get a small manifold
    from the Frank Lutz database
  * source(SimplicialMap) -- get the source
    of the map
  * substitute(SimplicialComplex,PolynomialRing)
    -- change the ring of a
    simplicial complex
  * target(SimplicialMap) -- get the target
    of the map
  * wedge(SimplicialComplex,SimplicialComplex,RingElement,RingElement)
    -- make the wedge sum of two abstract simplicial complexes
  * zieglerBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with
    10 vertices and 21 facets

Methods that use an abstract simplicial complex :
=================================================

  * "algebraicShifting(SimplicialComplex)" -- see algebraicShifting,
    -- the algebraic shifting of a simplicial complex
  * boundaryMap(ZZ,SimplicialComplex)
    -- make a boundary map between the
    oriented faces of an abstract simplicial complex
  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.
  * coefficientRing(SimplicialComplex)
    -- get the coefficient ring of the
    underlying polynomial ring
  * connectedComponents(SimplicialComplex)
    -- find the connected
    components of an abstract simplicial complex
  * dim(SimplicialComplex) -- find the
    dimension of an abstract simplicial complex
  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex
  * faces(ZZ,SimplicialComplex), --
    get the $i$-faces of an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * flagfVector(List,SimplicialComplex)
    -- compute a flag $f$-number of
    a colored simplicial complex
  * flagfVector(SimplicialComplex),
    -- compute the flag $f$-vector of an colored simplicial complex
  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex
  * "HH^ZZ SimplicialComplex" -- see HH^ZZ(SimplicialComplex,Ring),
    -- compute the reduced cohomology of
    an abstract simplicial complex
  * HH^ZZ(SimplicialComplex,Ring),
    -- compute the reduced cohomology of an abstract simplicial complex
  * HH^ZZ(SimplicialComplex,SimplicialComplex)
    -- compute the relative
    homology of two simplicial complexes
  * "HH_ZZ SimplicialComplex" -- see HH_ZZ(SimplicialComplex,Ring),
    -- compute the reduced homology of
    an abstract simplicial complex
  * HH_ZZ(SimplicialComplex,Ring),
    -- compute the reduced homology of an abstract simplicial complex
  * "HH SimplicialComplex" -- see homology(SimplicialComplex,Ring),
    -- compute the reduced homology of
    an abstract simplicial complex
  * "homology(Nothing,SimplicialComplex)" -- see
    homology(SimplicialComplex,Ring),
    -- compute the reduced homology of an abstract simplicial complex
  * "homology(Nothing,SimplicialComplex,Ring)" -- see
    homology(SimplicialComplex,Ring),
    -- compute the reduced homology of an abstract simplicial complex
  * homology(SimplicialComplex,Ring)
    -- compute the reduced homology of
    an abstract simplicial complex
  * "HH_ZZ(SimplicialComplex,SimplicialComplex)" -- see
    homology(SimplicialComplex,SimplicialComplex),
    -- compute the
    relative homology of two simplicial complexes
  * "homology(Nothing,SimplicialComplex,SimplicialComplex)" -- see
    homology(SimplicialComplex,SimplicialComplex),
    -- compute the
    relative homology of two simplicial complexes
  * homology(SimplicialComplex,SimplicialComplex)
    -- compute the
    relative homology of two simplicial complexes
  * ideal(SimplicialComplex) -- get the
    Stanley–Reisner ideal
  * isProper(SimplicialComplex), --
    whether an abstract simplicial complex is properly colored
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional
  * isWellDefined(SimplicialComplex)
    -- whether underlying data is
    uncontradictory
  * "map(SimplicialComplex,List)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,Matrix)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,RingMap)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,SimplicialComplex,List)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,SimplicialComplex,RingMap)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * monomialIdeal(SimplicialComplex)
    -- get the Stanley–Reisner monomial
    ideal
  * net(SimplicialComplex) -- make a
    symbolic representation of an abstract simplicial complex
  * ring(SimplicialComplex) -- get the
    polynomial ring of its Stanley–Reisner ideal
  * SimplicialComplex * SimplicialComplex
    -- make the join for two abstract simplicial complexes
  * star(SimplicialComplex,RingElement)
    -- make the star of a face
  * vertices(SimplicialComplex) -- get
    the list of the vertices for an abstract simplicial complex

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

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

SimplicialComplex * SimplicialComplex -- make the join for two abstract simplicial complexes
********************************************************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        Delta * Gamma
  * Inputs:
      * Delta, an abstract simplicial complex,
      * Gamma, an abstract simplicial complex,
  * Outputs:
      * an abstract simplicial complex, that is the
        join of $\Delta$ and $\Gamma$

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

The join of two simplicial complexes $\Delta$ and $\Gamma$ is a new simplicial
complex whose faces are disjoint unions of a face in $\Delta$ and a face in
$\Gamma$.

If $\Gamma$ is the simplicial complex consisting of a single vertex, then the
join $\Delta \mathrel{*} \Gamma$ is the cone (see
https://en.wikipedia.org/wiki/Cone_(topology) ) over $\Delta$.  For example,
the cone over a bow-tie complex.

+-----------------------------------------+
|i1 : S = QQ[a..e];                       |
+-----------------------------------------+
|i2 : Δ = simplicialComplex {a*b*c, c*d*e}|
|                                         |
|o2 = simplicialComplex | cde abc |       |
|                                         |
|o2 : SimplicialComplex                   |
+-----------------------------------------+
|i3 : R = QQ[f];                          |
+-----------------------------------------+
|i4 : Γ = simplicialComplex {f};          |
+-----------------------------------------+
|i5 : Δ' = Δ * Γ                          |
|                                         |
|o5 = simplicialComplex | cdef abcf |     |
|                                         |
|o5 : SimplicialComplex                   |
+-----------------------------------------+
|i6 : assert (dim Δ' === dim Δ + 1)       |
+-----------------------------------------+

If $\Gamma$ is a $1$-sphere (consisting of two isolated vertices), then the
join $\Delta \mathrel{*} \Gamma$ is the suspension (see
https://en.wikipedia.org/wiki/Suspension_(topology) ) of $\Delta$.  For
example, the octahedron is the suspension of a square.

+-----------------------------------------------------------------+
|i7 : S = QQ[a..d];                                               |
+-----------------------------------------------------------------+
|i8 : Δ = simplicialComplex {a*b, b*c, c*d, a*d}                  |
|                                                                 |
|o8 = simplicialComplex | cd ad bc ab |                           |
|                                                                 |
|o8 : SimplicialComplex                                           |
+-----------------------------------------------------------------+
|i9 : R = QQ[e,f];                                                |
+-----------------------------------------------------------------+
|i10 : Γ = simplicialComplex {e, f}                               |
|                                                                 |
|o10 = simplicialComplex | f e |                                  |
|                                                                 |
|o10 : SimplicialComplex                                          |
+-----------------------------------------------------------------+
|i11 : Δ' = Δ * Γ                                                 |
|                                                                 |
|o11 = simplicialComplex | cdf cde adf ade bcf bce abf abe |      |
|                                                                 |
|o11 : SimplicialComplex                                          |
+-----------------------------------------------------------------+
|i12 : assert (dim Δ' === dim Δ + 1)                              |
+-----------------------------------------------------------------+
|i13 : assert (apply(2+dim Δ', i -> #faces(i-1,Δ')) == {1,6,12,8})|
+-----------------------------------------------------------------+

The join of a hexagon and a pentagon is a 3-sphere.

+-----------------------------------------------------------------------------+
|i14 : S = ZZ[a..f];                                                          |
+-----------------------------------------------------------------------------+
|i15 : Δ = simplicialComplex {a*b, b*c, c*d, d*e, e*f, a*f}                   |
|                                                                             |
|o15 = simplicialComplex | ef af de cd bc ab |                                |
|                                                                             |
|o15 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i16 : R = ZZ[g..k];                                                          |
+-----------------------------------------------------------------------------+
|i17 : Γ = simplicialComplex {g*h, h*i, i*j, j*k, g*k}                        |
|                                                                             |
|o17 = simplicialComplex | jk gk ij hi gh |                                   |
|                                                                             |
|o17 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i18 : Δ' = Δ * Γ                                                             |
|                                                                             |
|o18 = simplicialComplex | efjk efgk efij efhi efgh afjk afgk afij afhi afgh  |
|                                                                             |
|o18 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|dejk degk deij dehi degh cdjk cdgk cdij cdhi cdgh bcjk bcgk bcij bchi bcgh   |
|-----------------------------------------------------------------------------|
|abjk abgk abij abhi abgh |                                                   |
+-----------------------------------------------------------------------------+
|i19 : prune HH Δ'                                                            |
|                                                                             |
|o19 = -1 : 0                                                                 |
|                                                                             |
|       0 : 0                                                                 |
|                                                                             |
|       1 : 0                                                                 |
|                                                                             |
|       2 : 0                                                                 |
|                                                                             |
|             1                                                               |
|       3 : ZZ                                                                |
|                                                                             |
|o19 : GradedModule                                                           |
+-----------------------------------------------------------------------------+
|i20 : assert (dim Δ' === 3)                                                  |
+-----------------------------------------------------------------------------+

Caveat
======

When the variables in the ring of $\Delta$ and the ring of $\Gamma$ are not
disjoint, names of vertices in the join may not be intelligible; the same name
will be used for two distinct variables.

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex
  * substitute(SimplicialComplex,PolynomialRing)
    -- change the ring of a
    simplicial complex
  * wedge
    -- make the wedge sum of two abstract simplicial
    complexes

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

  * SimplicialComplex * SimplicialComplex
    -- make the join for two abstract simplicial complexes

simplicialComplex(List) -- make an abstract simplicial complex from a list of faces
***********************************************************************************

Synopsis
========

  * Function: simplicialComplex,
  * Usage:
        simplicialComplex L
  * Inputs:
      * L, a list (Macaulay2Doc), whose entries are monomials in a
        polynomial ring corresponding to faces or a Matrix (Macaulay2Doc),
        with one row and monomial entries
  * Outputs:
      * an abstract simplicial complex, that is
        generated by the given faces

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

An abstract simplicial complex on a finite set is a family of subsets that is
closed under taking subsets. The elements in the abstract simplicial complex
are called faces. The faces having cardinality 1 are called vertices and the
maximal faces (order by inclusion) are called facets.  Following the
combinatorial conventions, every nonempty abstract simplicial complex has the
empty set as a face.

In this package, a simplicial complex is represented by its Stanley–Reisner
ideal (see https://en.wikipedia.org/wiki/Stanley–Reisner_ring ). The vertices
are identified with a subset of the variables in a polynomial ring and each
face is identified with the product of the corresponding variables. A nonface
is any subset of the variables that does not belong to the simplicial complex
and each nonface is again identified with a product of variables. The
Stanley-Reisner ideal of a simplicial complex is generated by monomials
corresponding to its nonfaces.

The boundary of the 4-simplex is a simplicial sphere with 5 vertices, 5
tetrahedral facets, and a minimal nonface that corresponds to the interior of
the sphere.

+------------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                      |
+------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {a*b*d*e, b*c*d*e, a*b*c*e, a*b*c*d, a*c*d*e}|
|                                                                        |
|o2 = simplicialComplex | bcde acde abde abce abcd |                     |
|                                                                        |
|o2 : SimplicialComplex                                                  |
+------------------------------------------------------------------------+
|i3 : facets Δ                                                           |
|                                                                        |
|o3 = {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}                      |
|                                                                        |
|o3 : List                                                               |
+------------------------------------------------------------------------+
|i4 : monomialIdeal Δ                                                    |
|                                                                        |
|o4 = monomialIdeal(a*b*c*d*e)                                           |
|                                                                        |
|o4 : MonomialIdeal of S                                                 |
+------------------------------------------------------------------------+
|i5 : dim Δ                                                              |
|                                                                        |
|o5 = 3                                                                  |
+------------------------------------------------------------------------+
|i6 : assert (dim Δ === 3 and numgens ideal Δ === 1 and isPure Δ)        |
+------------------------------------------------------------------------+
|i7 : assert (Δ === simplicialComplex facets Δ)                          |
+------------------------------------------------------------------------+

Although the list of faces may include non-facets, an abstract simplicial
complex is displayed by listing its facets.  The order of faces in the input
list is unimportant.

+-----------------------------------------------------------------------------+
|i8 : Γ = simplicialComplex {a*b*d*e, b*c, a*b*c*d,  a*c*d*e, a*c*d,  b*c*d*e,|
|                                                                             |
|o8 = simplicialComplex | bcde acde abde abce abcd |                          |
|                                                                             |
|o8 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|d, a*b*c*e}                                                                  |
+-----------------------------------------------------------------------------+
|i9 : monomialIdeal Γ                                                         |
|                                                                             |
|o9 = monomialIdeal(a*b*c*d*e)                                                |
|                                                                             |
|o9 : MonomialIdeal of S                                                      |
+-----------------------------------------------------------------------------+
|i10 : assert (Γ === Δ)                                                       |
+-----------------------------------------------------------------------------+
|i11 : assert (Γ === simplicialComplex facets Γ)                              |
+-----------------------------------------------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.

+----------------------------------------------------+
|i12 : S' = ZZ/101[a..e];                            |
+----------------------------------------------------+
|i13 : Δ' = simplicialComplex {e, c*d, b*d, a*b*c}   |
|                                                    |
|o13 = simplicialComplex | e cd bd abc |             |
|                                                    |
|o13 : SimplicialComplex                             |
+----------------------------------------------------+
|i14 : monomialIdeal Δ'                              |
|                                                    |
|o14 = monomialIdeal (a*d, b*c*d, a*e, b*e, c*e, d*e)|
|                                                    |
|o14 : MonomialIdeal of S'                           |
+----------------------------------------------------+
|i15 : facets Δ'                                     |
|                                                    |
|o15 = {e, c*d, b*d, a*b*c}                          |
|                                                    |
|o15 : List                                          |
+----------------------------------------------------+
|i16 : dim Δ'                                        |
|                                                    |
|o16 = 2                                             |
+----------------------------------------------------+
|i17 : assert (dim Δ' === 2 and not isPure Δ')       |
+----------------------------------------------------+
|i18 : assert (Δ' === simplicialComplex facets Δ')   |
+----------------------------------------------------+

There are two "trivial" simplicial complexes: The irrelevant complex has the
empty set as a facet whereas the void complex has no facets.  Since every
abstract simplicial complex in this package is equipped with a chosen
polynomial ring, the void complex cannot be constructed by just listing its
facets.

+-----------------------------------------------------------------+
|i19 : irrelevant = simplicialComplex {1_S'};                     |
+-----------------------------------------------------------------+
|i20 : dim irrelevant                                             |
|                                                                 |
|o20 = -1                                                         |
+-----------------------------------------------------------------+
|i21 : void = simplicialComplex monomialIdeal 1_S                 |
|                                                                 |
|o21 = simplicialComplex 0                                        |
|                                                                 |
|o21 : SimplicialComplex                                          |
+-----------------------------------------------------------------+
|i22 : dim void                                                   |
|                                                                 |
|o22 = -infinity                                                  |
|                                                                 |
|o22 : InfiniteNumber                                             |
+-----------------------------------------------------------------+
|i23 : assert (dim irrelevant === -1 and dim void === -infinity)  |
+-----------------------------------------------------------------+
|i24 : assert (irrelevant === simplicialComplex facets irrelevant)|
+-----------------------------------------------------------------+

Although an abstract simplicial complex can be represented by a Stanley–Reisner
ideal in any polynomial ring with a sufficiently large number of variables,
some operations in this package do depend of the choice of the polynomial ring
(or its coefficient ring). For example, the chain complex,
of an abstract simplicial complex is
typically constructed over the coefficient ring of this polynomial ring, and
the dual of a simplicial complex (or monomial ideal) is dependent on the number
of variables in the polynomial ideal.

+---------------------------------------------+
|i25 : chainComplex Δ                         |
|                                             |
|        1       5       10       10       5  |
|o25 = ZZ  <-- ZZ  <-- ZZ   <-- ZZ   <-- ZZ   |
|                                             |
|      -1      0       1        2        3    |
|                                             |
|o25 : ChainComplex                           |
+---------------------------------------------+
|i26 : chainComplex Γ                         |
|                                             |
|        1       5       10       10       5  |
|o26 = ZZ  <-- ZZ  <-- ZZ   <-- ZZ   <-- ZZ   |
|                                             |
|      -1      0       1        2        3    |
|                                             |
|o26 : ChainComplex                           |
+---------------------------------------------+
|i27 : chainComplex Δ'                        |
|                                             |
|        ZZ 1       ZZ 5       ZZ 5       ZZ 1|
|o27 = (---)  <-- (---)  <-- (---)  <-- (---) |
|       101        101        101        101  |
|                                             |
|      -1         0          1          2     |
|                                             |
|o27 : ChainComplex                           |
+---------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * simplicialComplex(MonomialIdeal)
    -- make a simplicial complex from its
    Stanley–Reisner ideal
  * facets(SimplicialComplex) -- get the
    list of maximal faces

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

  * simplicialComplex(List) -- make an
    abstract simplicial complex from a list of faces
  * "simplicialComplex(Matrix)"

simplicialComplex(MonomialIdeal) -- make a simplicial complex from its Stanley–Reisner ideal
********************************************************************************************

Synopsis
========

  * Function: simplicialComplex,
  * Usage:
        simplicialComplex I
  * Inputs:
      * I, a monomial ideal (Macaulay2Doc), or an
        Ideal (Macaulay2Doc), with monomial entries
  * Outputs:
      * an abstract simplicial complex, whose minimal
        nonfaces correspond to the generators of $I$

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

An abstract simplicial complex on a finite set is a family of subsets that is
closed under taking subsets.  The elements in the abstract simplicial complex
are called its faces.  The faces having cardinality 1 are its vertices and the
maximal faces (order by inclusion) are its facets.  Following the combinatorial
conventions, every nonempty abstract simplicial complex has the empty set as a
face.

In this package, a simplicial complex is represented by its Stanley–Reisner
ideal (see https://en.wikipedia.org/wiki/Stanley–Reisner_ring ). The vertices
are identified with a subset of the variables in a polynomial ring and each
face is identified with the product of the corresponding variables. A nonface
is any subset of the variables that does not belong to the simplicial complex
and each nonface is again identified with a product of variables. The
Stanley-Reisner ideal of a simplicial complex is generated by monomials
corresponding to its nonfaces.

The boundary of the 4-simplex is a simplicial sphere with 5 vertices, 5
tetrahedral facets, and a minimal nonface that corresponds to the interior of
the sphere.

+----------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                              |
+----------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal (a*b*c*d*e)            |
|                                                                |
|o2 = simplicialComplex | bcde acde abde abce abcd |             |
|                                                                |
|o2 : SimplicialComplex                                          |
+----------------------------------------------------------------+
|i3 : monomialIdeal Δ                                            |
|                                                                |
|o3 = monomialIdeal(a*b*c*d*e)                                   |
|                                                                |
|o3 : MonomialIdeal of S                                         |
+----------------------------------------------------------------+
|i4 : facets Δ                                                   |
|                                                                |
|o4 = {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}              |
|                                                                |
|o4 : List                                                       |
+----------------------------------------------------------------+
|i5 : dim Δ                                                      |
|                                                                |
|o5 = 3                                                          |
+----------------------------------------------------------------+
|i6 : assert (dim Δ === 3 and numgens ideal Δ === 1 and isPure Δ)|
+----------------------------------------------------------------+

An isomorphic abstract simplicial complex may be constructed in a larger
polynomial ring.

+------------------------------------------------------------+
|i7 : R = QQ[a..f];                                          |
+------------------------------------------------------------+
|i8 : Γ = simplicialComplex monomialIdeal (a*b*c*d*e, f)     |
|                                                            |
|o8 = simplicialComplex | bcde acde abde abce abcd |         |
|                                                            |
|o8 : SimplicialComplex                                      |
+------------------------------------------------------------+
|i9 : monomialIdeal Γ                                        |
|                                                            |
|o9 = monomialIdeal (a*b*c*d*e, f)                           |
|                                                            |
|o9 : MonomialIdeal of R                                     |
+------------------------------------------------------------+
|i10 : facets Γ                                              |
|                                                            |
|o10 = {b*c*d*e, a*c*d*e, a*b*d*e, a*b*c*e, a*b*c*d}         |
|                                                            |
|o10 : List                                                  |
+------------------------------------------------------------+
|i11 : assert((for F in facets Γ list sub(F,S)) === facets Δ)|
+------------------------------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.

+---------------------------------------------------------------------------+
|i12 : S' = ZZ/101[a..e];                                                   |
+---------------------------------------------------------------------------+
|i13 : Δ' = simplicialComplex monomialIdeal (a*d, b*c*d, a*e, b*e, c*e, d*e)|
|                                                                           |
|o13 = simplicialComplex | e cd bd abc |                                    |
|                                                                           |
|o13 : SimplicialComplex                                                    |
+---------------------------------------------------------------------------+
|i14 : monomialIdeal Δ'                                                     |
|                                                                           |
|o14 = monomialIdeal (a*d, b*c*d, a*e, b*e, c*e, d*e)                       |
|                                                                           |
|o14 : MonomialIdeal of S'                                                  |
+---------------------------------------------------------------------------+
|i15 : facets Δ'                                                            |
|                                                                           |
|o15 = {e, c*d, b*d, a*b*c}                                                 |
|                                                                           |
|o15 : List                                                                 |
+---------------------------------------------------------------------------+
|i16 : dim Δ'                                                               |
|                                                                           |
|o16 = 2                                                                    |
+---------------------------------------------------------------------------+
|i17 : assert (dim Δ' === 2 and not isPure Δ')                              |
+---------------------------------------------------------------------------+

There are two "trivial" simplicial complexes: The irrelevant complex has the
empty set as a facet whereas the void complex has no facets.  Since every
abstract simplicial complex in this package is equipped with a chosen
polynomial ring, the void complex cannot be constructed by just listing its
facets.

+-----------------------------------------------------------------+
|i18 : irrelevant = simplicialComplex monomialIdeal gens S        |
|                                                                 |
|o18 = simplicialComplex | 1 |                                    |
|                                                                 |
|o18 : SimplicialComplex                                          |
+-----------------------------------------------------------------+
|i19 : monomialIdeal irrelevant                                   |
|                                                                 |
|o19 = monomialIdeal (a, b, c, d, e)                              |
|                                                                 |
|o19 : MonomialIdeal of S                                         |
+-----------------------------------------------------------------+
|i20 : facets irrelevant                                          |
|                                                                 |
|o20 = {1}                                                        |
|                                                                 |
|o20 : List                                                       |
+-----------------------------------------------------------------+
|i21 : void = simplicialComplex monomialIdeal 1_R                 |
|                                                                 |
|o21 = simplicialComplex 0                                        |
|                                                                 |
|o21 : SimplicialComplex                                          |
+-----------------------------------------------------------------+
|i22 : monomialIdeal void                                         |
|                                                                 |
|o22 = monomialIdeal 1                                            |
|                                                                 |
|o22 : MonomialIdeal of R                                         |
+-----------------------------------------------------------------+
|i23 : facets void                                                |
|                                                                 |
|o23 = {}                                                         |
|                                                                 |
|o23 : List                                                       |
+-----------------------------------------------------------------+
|i24 : assert (facets irrelevant === {1_S} and facets void === {})|
+-----------------------------------------------------------------+

Although an abstract simplicial complex can be represented by a Stanley–Reisner
ideal in any polynomial ring with a sufficiently large number of variables,
some operations in this package do depend of the choice of the polynomial ring
(or its coefficient ring). For example, the chain complex,
of an abstract simplicial complex is
typically constructed over the coefficient ring of this polynomial ring, and
the dual of a simplicial complex (or monomial ideal) is dependent on the number
of variables in the polynomial ideal.

+---------------------------------------------+
|i25 : chainComplex Δ                         |
|                                             |
|        1       5       10       10       5  |
|o25 = ZZ  <-- ZZ  <-- ZZ   <-- ZZ   <-- ZZ   |
|                                             |
|      -1      0       1        2        3    |
|                                             |
|o25 : ChainComplex                           |
+---------------------------------------------+
|i26 : chainComplex Γ                         |
|                                             |
|        1       5       10       10       5  |
|o26 = QQ  <-- QQ  <-- QQ   <-- QQ   <-- QQ   |
|                                             |
|      -1      0       1        2        3    |
|                                             |
|o26 : ChainComplex                           |
+---------------------------------------------+
|i27 : chainComplex Δ'                        |
|                                             |
|        ZZ 1       ZZ 5       ZZ 5       ZZ 1|
|o27 = (---)  <-- (---)  <-- (---)  <-- (---) |
|       101        101        101        101  |
|                                             |
|      -1         0          1          2     |
|                                             |
|o27 : ChainComplex                           |
+---------------------------------------------+

The input can be an Ideal (Macaulay2Doc), in which case the
constructor verifies that it is a squarefree monomial ideal.

+-----------------------------------------------------------+
|i28 : Bowtie = simplicialComplex ideal {a*d, b*d, a*e, b*e}|
|                                                           |
|o28 = simplicialComplex | cde abc |                        |
|                                                           |
|o28 : SimplicialComplex                                    |
+-----------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * simplicialComplex(List) -- make an
    abstract simplicial complex from a list of faces
  * facets(SimplicialComplex) -- get the
    list of maximal faces

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

  * "simplicialComplex(Ideal)"
  * simplicialComplex(MonomialIdeal)
    -- make a simplicial complex from its
    Stanley–Reisner ideal

SimplicialMap -- the class of all maps between simplicial complexes
*******************************************************************

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

Let $C$ and $D$ be simplicial complexes. A simplicial map is a map $f : C \to
D$ such that for any face $F \subset C$, we have that $f(F)$ is contained in a
face of $D$.

To specify a map of simplicial complexes, the target and source complexes need
to be specified as well as a matrix which determines a map between the
complexes' corresponding rings.

The primary constructor of a simplicial map is
map(SimplicialComplex,SimplicialComplex,Matrix).

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * SimplicialComplex -- the class of all abstract
    simplicial complexes
  * id _ SimplicialComplex -- make the
    identity map from a SimplicialComplex to itself
  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory

Functions and methods returning a map of abstract simplicial complexes :
========================================================================

  * barycentricSubdivision(SimplicialMap,Ring,Ring)
    -- create the map
    between barycentric subdivisions corresponding to a simplicial map
  * "map(SimplicialComplex,List)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,Matrix)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,RingMap)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,SimplicialComplex,List)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes
  * "map(SimplicialComplex,SimplicialComplex,RingMap)" -- see
    map(SimplicialComplex,SimplicialComplex,Matrix),
    -- create a
    simplicial map between simplicial complexes

Methods that use a map of abstract simplicial complexes :
=========================================================

  * chainComplex(SimplicialMap), --
    constructs the associated map between chain complexes
  * HH SimplicialMap -- Compute the induced map on
    homology of a simplicial map.
  * "homology(Nothing,SimplicialMap)" -- see HH SimplicialMap,
    -- Compute the induced map on homology of a simplicial map.
  * HH^ZZ SimplicialMap -- Compute the induced map
    on cohomology of a simplicial map.
  * HH_ZZ SimplicialMap -- Compute the induced
    map on homology of a simplicial map.
  * image(SimplicialMap) -- construct the
    image of a simplicial map
  * isInjective(SimplicialMap) -- checks
    if a simplicial map is injective
  * isSurjective(SimplicialMap), --
    checks if a simplicial map is surjective
  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory
  * map(SimplicialMap) -- the underlying ring
    map associated to a simplicial map
  * matrix(SimplicialMap) -- get the
    underlying map of rings
  * net(SimplicialMap) -- make a symbolic
    representation for a map of abstract simplicial complexes
  * source(SimplicialMap) -- get the source
    of the map
  * target(SimplicialMap) -- get the target
    of the map

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

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

skeleton(ZZ,SimplicialComplex) -- make a new simplicial complex generated by all faces of a bounded dimension
*************************************************************************************************************

Synopsis
========

  * Function: skeleton (Polyhedra),
  * Usage:
        skeleton(n, Delta)
  * Inputs:
      * k, an integer (Macaulay2Doc), that bounds the dimension of
        the faces
      * Delta, an abstract simplicial complex,
  * Outputs:
      * an abstract simplicial complex, that is
        generated by all the faces in $\Delta$ of dimension less than or equal
        to $k$

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

The $k$-skeleton of an abstract simplicial complex is the subcomplex consisting
of all of the faces of dimension at most $k$.  When the abstract simplicial
complex is pure, its $k$-skeleton is
simply generated by its $k$-dimensional faces.

The boundary of the 4-simplex is a simplicial 3-sphere with 5 vertices, 5
facets, and a minimal nonface that corresponds to the interior of the sphere.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                           |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal (a*b*c*d*e)                         |
|                                                                             |
|o2 = simplicialComplex | bcde acde abde abce abcd |                          |
|                                                                             |
|o2 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i3 : skeleton (-2, Δ)                                                        |
|                                                                             |
|o3 = simplicialComplex 0                                                     |
|                                                                             |
|o3 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i4 : assert (skeleton (-2, Δ) === simplicialComplex monomialIdeal 1_S)       |
+-----------------------------------------------------------------------------+
|i5 : skeleton (-1, Δ)                                                        |
|                                                                             |
|o5 = simplicialComplex | 1 |                                                 |
|                                                                             |
|o5 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i6 : assert (skeleton (-1, Δ) === simplicialComplex {1_S})                   |
+-----------------------------------------------------------------------------+
|i7 : skeleton (0, Δ)                                                         |
|                                                                             |
|o7 = simplicialComplex | e d c b a |                                         |
|                                                                             |
|o7 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i8 : assert (skeleton (0, Δ) === simplicialComplex gens S)                   |
+-----------------------------------------------------------------------------+
|i9 : skeleton (1, Δ)                                                         |
|                                                                             |
|o9 = simplicialComplex | de ce be ae cd bd ad bc ac ab |                     |
|                                                                             |
|o9 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i10 : assert (skeleton (1, Δ) === simplicialComplex apply (subsets (gens S,  |
|-----------------------------------------------------------------------------|
|2), product))                                                                |
+-----------------------------------------------------------------------------+
|i11 : skeleton (2, Δ)                                                        |
|                                                                             |
|o11 = simplicialComplex | cde bde ade bce ace abe bcd acd abd abc |          |
|                                                                             |
|o11 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i12 : assert (skeleton (2, Δ) === simplicialComplex apply (subsets (gens S,  |
|-----------------------------------------------------------------------------|
|3), product))                                                                |
+-----------------------------------------------------------------------------+
|i13 : skeleton (3, Δ)                                                        |
|                                                                             |
|o13 = simplicialComplex | bcde acde abde abce abcd |                         |
|                                                                             |
|o13 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i14 : assert (skeleton (3, Δ) === Δ)                                         |
+-----------------------------------------------------------------------------+
|i15 : fVector Δ                                                              |
|                                                                             |
|o15 = {1, 5, 10, 10, 5}                                                      |
|                                                                             |
|o15 : List                                                                   |
+-----------------------------------------------------------------------------+

The abstract simplicial complex from Example 1.8 of Miller-Sturmfels'
Combinatorial Commutative Algebra consists of a triangle (on vertices $a$, $b$,
$c$), two edges (connecting $c$ to $d$ and $b$ to $d$), and an isolated vertex
(namely $e$). It has six minimal nonfaces.  Moreover, its 1-skeleton and
2-skeleton are not pure.

+-----------------------------------------------------------------------------+
|i16 : R = ZZ/101[a..f];                                                      |
+-----------------------------------------------------------------------------+
|i17 : Γ = simplicialComplex {e, c*d, b*d, a*b*c}                             |
|                                                                             |
|o17 = simplicialComplex | e cd bd abc |                                      |
|                                                                             |
|o17 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i18 : skeleton (-7, Γ)                                                       |
|                                                                             |
|o18 = simplicialComplex 0                                                    |
|                                                                             |
|o18 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i19 : assert (skeleton (-7, Γ) === simplicialComplex monomialIdeal 1_R)      |
+-----------------------------------------------------------------------------+
|i20 : skeleton (-1, Γ)                                                       |
|                                                                             |
|o20 = simplicialComplex | 1 |                                                |
|                                                                             |
|o20 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i21 : assert (skeleton (-1, Γ) === simplicialComplex {1_R})                  |
+-----------------------------------------------------------------------------+
|i22 : skeleton (0, Γ)                                                        |
|                                                                             |
|o22 = simplicialComplex | e d c b a |                                        |
|                                                                             |
|o22 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i23 : assert (skeleton (0, Γ) === simplicialComplex {a, b, c, d, e})         |
+-----------------------------------------------------------------------------+
|i24 : skeleton (1, Γ)                                                        |
|                                                                             |
|o24 = simplicialComplex | e cd bd bc ac ab |                                 |
|                                                                             |
|o24 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i25 : assert (skeleton (1, Γ) === simplicialComplex {e, c*d, b*d, b*c, a*c,  |
|-----------------------------------------------------------------------------|
|a*b})                                                                        |
+-----------------------------------------------------------------------------+
|i26 : skeleton (2, Γ)                                                        |
|                                                                             |
|o26 = simplicialComplex | e cd bd abc |                                      |
|                                                                             |
|o26 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i27 : assert (skeleton (2, Γ) === Γ)                                         |
+-----------------------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex
  * fVector(SimplicialComplex), --
    compute the f-vector of an abstract simplicial complex

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

  * skeleton(ZZ,SimplicialComplex),
    -- make a new simplicial complex generated by all faces of a bounded
    dimension

smallManifold(ZZ,ZZ,ZZ,PolynomialRing) -- get a small manifold from the Frank Lutz database
*******************************************************************************************

Synopsis
========

  * Function: smallManifold,
  * Usage:
        smoothManifold(d, v, i, S)
  * Inputs:
      * d, an integer (Macaulay2Doc), equal to dimension of the
        manifold
      * v, an integer (Macaulay2Doc), equal to the number of vertices
      * i, an integer (Macaulay2Doc), indexing a small $d$-manifold
        in the database
      * S, a polynomial ring (Macaulay2Doc), that
        specifies the polynomial ring containing the Stanley–Reisner ideal
  * Outputs:
      * an abstract simplicial complex, corresponding
        to a triangulation of a $d$-manifold

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

This function accesses a database of all small triangulated 2- or 3-manifolds
with at most ten vertices.  The enumeration of these abstract simplicial
complex follows Frank H. Lutz's (see http://page.math.tu-berlin.de/~lutz/ )
classification in "Triangulated Manifolds with Few Vertices: Combinatorial
Manifolds", arXiv:math/0506372v1 (see https://arxiv.org/abs/math/0506372 ).
Alternative formats, further references, and more details may be found at the
manifold page (see http://page.math.tu-berlin.de/~lutz/stellar/ ).

There is a $1$ surface with four vertices, $1$ with five vertices, $3$ with six
vertices, $9$ with seven vertices, $43$ with eight vertices, $655$ with nine
vertices, and $42,426$ with ten vertices.  There is $1$ threefold with five
vertices, $2$ with six vertices, $5$ with seven vertices, $39$ with eight
vertices, and $1,297$ with nine vertices.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[a..j];                                                           |
+-----------------------------------------------------------------------------+
|i2 : Γ = smallManifold(3, 8, 21, S);                                         |
+-----------------------------------------------------------------------------+
|i3 : matrix {facets Γ}                                                       |
|                                                                             |
|o3 = | dfgh afgh cdgh bcgh abgh bdfh abfh bcdh defg aefg cdeg bceg abeg adef |
|     ------------------------------------------------------------------------|
|     abdf acde abce abcd |                                                   |
|                                                                             |
|             1       18                                                      |
|o3 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i4 : prune HH Γ                                                              |
|                                                                             |
|o4 = -1 : 0                                                                  |
|                                                                             |
|      0 : 0                                                                  |
|                                                                             |
|      1 : 0                                                                  |
|                                                                             |
|      2 : 0                                                                  |
|                                                                             |
|            1                                                                |
|      3 : ZZ                                                                 |
|                                                                             |
|o4 : GradedModule                                                            |
+-----------------------------------------------------------------------------+
|i5 : assert(isWellDefined Γ and dim Γ === 3 and # vertices Γ === 8)          |
+-----------------------------------------------------------------------------+
|i6 : assert (simplicialComplex faces(3, simplexComplex(4, S)) ===            |
|-----------------------------------------------------------------------------|
|smallManifold(3,5,0,S))                                                      |
+-----------------------------------------------------------------------------+

Frank Lutz also includes some information of the topological type of the
manifolds on his webpage (see http://page.math.tu-berlin.de/~lutz/ ). The
2-sphere, 2-torus, real projective plane and Klein Bottle can all be accessed
from the database. Here are the smallest instances which appear in the database
for real projective plane and the Klein Bottle (note that our index begins
counting at zero instead of one):

+-----------------------------------------------------------------------------+
|i7 : RP2 = smallManifold(2, 6, 1, S)                                         |
|                                                                             |
|o7 = simplicialComplex | bef aef cdf adf bcf cde bde ace abd abc |           |
|                                                                             |
|o7 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i8 : KleinBottle = smallManifold(2, 8, 12, S)                                |
|                                                                             |
|o8 = simplicialComplex | cgh agh cfh afh efg dfg aeg cdg bef adf bcf cde bde |
|                                                                             |
|o8 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|ace abd abc |                                                                |
+-----------------------------------------------------------------------------+

From Theorems 6.3 and 6.4 in Chapter one of Munkres' Algebraic Topology (see
https://www.pearson.com/us/higher-education/product/Munkres-Topology-2nd-
Edition/9780131816299.html ), both real projective plane and the Klein Bottle
should have zero homology except in the first position.

+--------------------------------+
|i9 : RP2H = prune HH RP2        |
|                                |
|o9 = -1 : 0                     |
|                                |
|      0 : 0                     |
|                                |
|      1 : cokernel | 2 |        |
|                                |
|      2 : 0                     |
|                                |
|o9 : GradedModule               |
+--------------------------------+
|i10 : KBH = prune HH KleinBottle|
|                                |
|o10 = -1 : 0                    |
|                                |
|       0 : 0                    |
|                                |
|       1 : cokernel | 2 |       |
|                    | 0 |       |
|                                |
|       2 : 0                    |
|                                |
|o10 : GradedModule              |
+--------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * dim(SimplicialComplex) -- find the
    dimension of an abstract simplicial complex

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

  * smallManifold(ZZ,ZZ,ZZ,PolynomialRing)
    -- get a small manifold
    from the Frank Lutz database

source(SimplicialMap) -- get the source of the map
**************************************************

Synopsis
========

  * Function: source (Macaulay2Doc),
  * Usage:
        X = source f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * X, an abstract simplicial complex, that is
        the source of the map f

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

Given a map $f \colon \Delta \to \Gamma$, this method returns the abstract
simplicial complex $\Delta$.  The source is one of the defining attributes of a
simplicial map

For the identity map, the source and target are equal.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_5];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal(x_0*x_5, x_1*x_4, x_2*x_3)          |
|                                                                             |
|o2 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4   |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i3 : id_Δ                                                                    |
|                                                                             |
|o3 = | x_0 x_1 x_2 x_3 x_4 x_5 |                                             |
|                                                                             |
|o3 : SimplicialMap simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5         |
|-----------------------------------------------------------------------------|
|x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | |
|-----------------------------------------------------------------------------|
|x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3        |
|-----------------------------------------------------------------------------|
|x_0x_1x_2 |                                                                  |
+-----------------------------------------------------------------------------+
|i4 : source id_Δ                                                             |
|                                                                             |
|o4 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4   |
|                                                                             |
|o4 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i5 : assert(source id_Δ === Δ)                                               |
+-----------------------------------------------------------------------------+
|i6 : assert(source id_Δ === target id_Δ)                                     |
+-----------------------------------------------------------------------------+

The next map projects an octahedron onto a square.

+-----------------------------------------------------------------------------+
|i7 : R = ZZ[y_0..y_3];                                                       |
+-----------------------------------------------------------------------------+
|i8 : Γ = simplicialComplex monomialIdeal(y_1*y_2)                            |
|                                                                             |
|o8 = simplicialComplex | y_0y_2y_3 y_0y_1y_3 |                               |
|                                                                             |
|o8 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i9 : f = map(Γ, Δ, {y_0,y_0,y_1,y_2,y_3,y_3})                                |
|                                                                             |
|o9 = | y_0 y_0 y_1 y_2 y_3 y_3 |                                             |
|                                                                             |
|o9 : SimplicialMap simplicialComplex | y_0y_2y_3 y_0y_1y_3 | <---            |
|-----------------------------------------------------------------------------|
|simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4        |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i10 : assert isWellDefined f                                                 |
+-----------------------------------------------------------------------------+
|i11 : source f                                                               |
|                                                                             |
|o11 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4  |
|                                                                             |
|o11 : SimplicialComplex                                                      |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i12 : assert(source f === Δ)                                                 |
+-----------------------------------------------------------------------------+
|i13 : peek f                                                                 |
|                                                                             |
|o13 = SimplicialMap{cache => CacheTable{}                                    |
|                    map => map (R, S, {y , y , y , y , y , y })              |
|                                        0   0   1   2   3   3                |
|                    source => simplicialComplex | x_3x_4x_5 x_2x_4x_5        |
|                    target => simplicialComplex | y_0y_2y_3 y_0y_1y_3        |
|-----------------------------------------------------------------------------|
|                                                             }               |
|                                                                             |
|                                                                             |
|x_1x_3x_5 x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                |
||                                                                            |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * target(SimplicialMap) -- get the target
    of the map
  * matrix(SimplicialMap) -- get the
    underlying map of rings
  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes

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

  * source(SimplicialMap) -- get the source
    of the map

star(SimplicialComplex,RingElement) -- make the star of a face
**************************************************************

Synopsis
========

  * Function: star,
  * Usage:
        star(Delta, F)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * F, a ring element (Macaulay2Doc), a monomial
        representing a subset of the vertices in $\Delta$
  * Outputs:
      * an abstract simplicial complex, that consists
        of all faces in $\Delta$ whose union with $F$ is also a face in
        $\Delta$

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

Given a subset $F$ of the vertices in an abstract simplicial complex $\Delta$,
the star of $F$ is the set of faces $G$ in $\Delta$ such that the union of $G$
and $F$ is also a face in $\Delta$.  This set forms a subcomplex of $\Delta$.
When the subset $F$ is not face in $\Delta$, the star of $F$ is a void complex
(having no facets).

The star of a subset $F$ may be the entire complex, a proper subcomplex, or the
void complex.

+-------------------------------------------------------------------+
|i1 : S = ZZ[a..e];                                                 |
+-------------------------------------------------------------------+
|i2 : Δ = simplicialComplex {a*b*c, c*d*e}                          |
|                                                                   |
|o2 = simplicialComplex | cde abc |                                 |
|                                                                   |
|o2 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i3 : star (Δ, c)                                                   |
|                                                                   |
|o3 = simplicialComplex | cde abc |                                 |
|                                                                   |
|o3 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i4 : assert (star (Δ, c) === Δ)                                    |
+-------------------------------------------------------------------+
|i5 : star (Δ, a*b)                                                 |
|                                                                   |
|o5 = simplicialComplex | abc |                                     |
|                                                                   |
|o5 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i6 : assert (star (Δ, a*b) === simplicialComplex {a*b*c})          |
+-------------------------------------------------------------------+
|i7 : star (Δ, a*d)                                                 |
|                                                                   |
|o7 = simplicialComplex 0                                           |
|                                                                   |
|o7 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i8 : assert (star (Δ, a*d) === simplicialComplex monomialIdeal 1_S)|
+-------------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex
  * link(SimplicialComplex,RingElement)
    -- make the link of a face in an
    abstract simplicial complex

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

  * star(SimplicialComplex,RingElement)
    -- make the star of a face

substitute(SimplicialComplex,PolynomialRing) -- change the ring of a simplicial complex
***************************************************************************************

Synopsis
========

  * Function: substitute (Macaulay2Doc),
  * Usage:
        substitute(Delta, R)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * R, a polynomial ring (Macaulay2Doc),
  * Outputs:
      * an abstract simplicial complex,

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

Given a polynomial ring $R$, with enough variables, we can create a simplicial
complex identical to $\Delta$, defined over the ring $R$.

+-------------------------------+
|i1 : S = ZZ/23[x,y,z,w];       |
+-------------------------------+
|i2 : Δ = simplexComplex(3,S)   |
|                               |
|o2 = simplicialComplex | xyzw ||
|                               |
|o2 : SimplicialComplex         |
+-------------------------------+
|i3 : R = ZZ/101[a,b,c,d,e];    |
+-------------------------------+
|i4 : Γ = substitute(Δ, R)      |
|                               |
|o4 = simplicialComplex | abcd ||
|                               |
|o4 : SimplicialComplex         |
+-------------------------------+

This method is a works by applying substitute(RingElement,Ring) (Macaulay2Doc),
to the facets of $\Delta$.

+-----------------------------------------------------------------------------+
|i5 : code(substitute, SimplicialComplex, PolynomialRing)                     |
|                                                                             |
|o5 = -- code for method: substitute(SimplicialComplex,PolynomialRing)        |
|     /usr/share/Macaulay2/SimplicialComplexes/Code.m2:671:78-681:72: --source|
|     substitute(SimplicialComplex, PolynomialRing) := SimplicialComplex => (D|
|         if ideal D === ideal(1_(ring D))                                    |
|         then (                                                              |
|             I := sub(ideal D, R);                                           |
|             simplicialComplex monomialIdeal I                               |
|             )                                                               |
|         else (                                                              |
|             n := numgens ring D;                                            |
|             simplicialComplex for F in facets D list sub(F, (vars R)_{0..n-1|
|             )                                                               |
|         )                                                                   |
|-----------------------------------------------------------------------------|
| code:                                                                       |
|, R) -> (                                                                    |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|})                                                                           |
+-----------------------------------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors

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

  * substitute(SimplicialComplex,PolynomialRing)
    -- change the ring of a
    simplicial complex

target(SimplicialMap) -- get the target of the map
**************************************************

Synopsis
========

  * Function: target (Macaulay2Doc),
  * Usage:
        Y = target f
  * Inputs:
      * f, a map of abstract simplicial complexes,
  * Outputs:
      * Y, an abstract simplicial complex, that is
        the target of the map f

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

Given a map $f \colon \Delta \to \Gamma$, this method returns the abstract
simplicial complex $\Gamma$.  The target is one of the defining attributes of a
simplicial map

For the identity map, the source and target are equal.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ[x_0..x_5];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = simplicialComplex monomialIdeal(x_0*x_5, x_1*x_4, x_2*x_3)          |
|                                                                             |
|o2 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4   |
|                                                                             |
|o2 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i3 : id_Δ                                                                    |
|                                                                             |
|o3 = | x_0 x_1 x_2 x_3 x_4 x_5 |                                             |
|                                                                             |
|o3 : SimplicialMap simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5         |
|-----------------------------------------------------------------------------|
|x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 | <--- simplicialComplex | |
|-----------------------------------------------------------------------------|
|x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3        |
|-----------------------------------------------------------------------------|
|x_0x_1x_2 |                                                                  |
+-----------------------------------------------------------------------------+
|i4 : source id_Δ                                                             |
|                                                                             |
|o4 = simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4   |
|                                                                             |
|o4 : SimplicialComplex                                                       |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i5 : assert(target id_Δ === Δ)                                               |
+-----------------------------------------------------------------------------+
|i6 : assert(target id_Δ === source id_Δ)                                     |
+-----------------------------------------------------------------------------+

The next map projects an octahedron onto a square.

+-----------------------------------------------------------------------------+
|i7 : R = ZZ[y_0..y_3];                                                       |
+-----------------------------------------------------------------------------+
|i8 : Γ = simplicialComplex monomialIdeal(y_1*y_2)                            |
|                                                                             |
|o8 = simplicialComplex | y_0y_2y_3 y_0y_1y_3 |                               |
|                                                                             |
|o8 : SimplicialComplex                                                       |
+-----------------------------------------------------------------------------+
|i9 : f = map(Γ, Δ, {y_0,y_0,y_1,y_2,y_3,y_3})                                |
|                                                                             |
|o9 = | y_0 y_0 y_1 y_2 y_3 y_3 |                                             |
|                                                                             |
|o9 : SimplicialMap simplicialComplex | y_0y_2y_3 y_0y_1y_3 | <---            |
|-----------------------------------------------------------------------------|
|simplicialComplex | x_3x_4x_5 x_2x_4x_5 x_1x_3x_5 x_1x_2x_5 x_0x_3x_4        |
|-----------------------------------------------------------------------------|
|x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                                              |
+-----------------------------------------------------------------------------+
|i10 : assert isWellDefined f                                                 |
+-----------------------------------------------------------------------------+
|i11 : target f                                                               |
|                                                                             |
|o11 = simplicialComplex | y_0y_2y_3 y_0y_1y_3 |                              |
|                                                                             |
|o11 : SimplicialComplex                                                      |
+-----------------------------------------------------------------------------+
|i12 : assert(target f === Γ)                                                 |
+-----------------------------------------------------------------------------+
|i13 : peek f                                                                 |
|                                                                             |
|o13 = SimplicialMap{cache => CacheTable{}                                    |
|                    map => map (R, S, {y , y , y , y , y , y })              |
|                                        0   0   1   2   3   3                |
|                    source => simplicialComplex | x_3x_4x_5 x_2x_4x_5        |
|                    target => simplicialComplex | y_0y_2y_3 y_0y_1y_3        |
|-----------------------------------------------------------------------------|
|                                                             }               |
|                                                                             |
|                                                                             |
|x_1x_3x_5 x_1x_2x_5 x_0x_3x_4 x_0x_2x_4 x_0x_1x_3 x_0x_1x_2 |                |
||                                                                            |
+-----------------------------------------------------------------------------+

See also
========

  * Working with simplicial maps, --
    information about simplicial maps and the induced operations
  * source(SimplicialMap) -- get the source
    of the map
  * matrix(SimplicialMap) -- get the
    underlying map of rings
  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory
  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes

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

  * target(SimplicialMap) -- get the target
    of the map

taylorResolution -- create the Taylor resolution of a monomial ideal
********************************************************************

Synopsis
========

  * Usage:
        taylorResolution L
        taylorResolution M
  * Inputs:
      * L, a list (Macaulay2Doc), of monomials in a polynomial
        ring, that minimally generate a monomial ideal.
      * M, a monomial ideal (Macaulay2Doc),
  * Outputs:
      * a chain complex (Macaulay2Doc),

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

If $M$ is a monomial ideal, minimally generated by $L$, then the Taylor
resolution of $M$ is the resolution of $M$ obtained by homogenizing the $(\#L -
1)$-simplex.

+-------------------------------------------------------+
|i1 : S = QQ[vars(0..3)]                                |
|                                                       |
|o1 = S                                                 |
|                                                       |
|o1 : PolynomialRing                                    |
+-------------------------------------------------------+
|i2 : M = monomialIdeal(a*b,c^3,c*d,b^2*c)              |
|                                                       |
|                          2    3                       |
|o2 = monomialIdeal (a*b, b c, c , c*d)                 |
|                                                       |
|o2 : MonomialIdeal of S                                |
+-------------------------------------------------------+
|i3 : T = taylorResolution M                            |
|                                                       |
|      1      4      6      4      1                    |
|o3 = S  <-- S  <-- S  <-- S  <-- S                     |
|                                                       |
|     0      1      2      3      4                     |
|                                                       |
|o3 : ChainComplex                                      |
+-------------------------------------------------------+
|i4 : T.dd                                              |
|                                                       |
|          1                        4                   |
|o4 = 0 : S  <-------------------- S  : 1               |
|               | cd ab c3 b2c |                        |
|                                                       |
|          4                                       6    |
|     1 : S  <----------------------------------- S  : 2|
|               {2} | -ab -c2 -b2 0   0   0   |         |
|               {2} | cd  0   0   -c3 -bc 0   |         |
|               {3} | 0   d   0   ab  0   -b2 |         |
|               {3} | 0   0   d   0   a   c2  |         |
|                                                       |
|          6                              4             |
|     2 : S  <-------------------------- S  : 3         |
|               {4} | c2  b  0   0   |                  |
|               {4} | -ab 0  b2  0   |                  |
|               {4} | 0   -a -c2 0   |                  |
|               {5} | d   0  0   b   |                  |
|               {4} | 0   d  0   -c2 |                  |
|               {5} | 0   0  d   a   |                  |
|                                                       |
|          4                  1                         |
|     3 : S  <-------------- S  : 4                     |
|               {6} | -b |                              |
|               {5} | c2 |                              |
|               {6} | -a |                              |
|               {6} | d  |                              |
|                                                       |
|o4 : ChainComplexMap                                   |
+-------------------------------------------------------+

If $M$ is generated by a regular sequence $L$, then the Taylor resolution is
the Koszul complex on $L$.

+-------------------------------------------------+
|i5 : L = gens S                                  |
|                                                 |
|o5 = {a, b, c, d}                                |
|                                                 |
|o5 : List                                        |
+-------------------------------------------------+
|i6 : T = taylorResolution L;                     |
+-------------------------------------------------+
|i7 : K = koszul matrix{L};                       |
+-------------------------------------------------+
|i8 : T.dd                                        |
|                                                 |
|          1                   4                  |
|o8 = 0 : S  <--------------- S  : 1              |
|               | a b c d |                       |
|                                                 |
|          4                                 6    |
|     1 : S  <----------------------------- S  : 2|
|               {1} | -b -c -d 0  0  0  |         |
|               {1} | a  0  0  -c -d 0  |         |
|               {1} | 0  a  0  b  0  -d |         |
|               {1} | 0  0  a  0  b  c  |         |
|                                                 |
|          6                           4          |
|     2 : S  <----------------------- S  : 3      |
|               {2} | c  d  0  0  |               |
|               {2} | -b 0  d  0  |               |
|               {2} | 0  -b -c 0  |               |
|               {2} | a  0  0  d  |               |
|               {2} | 0  a  0  -c |               |
|               {2} | 0  0  a  b  |               |
|                                                 |
|          4                  1                   |
|     3 : S  <-------------- S  : 4               |
|               {3} | -d |                        |
|               {3} | c  |                        |
|               {3} | -b |                        |
|               {3} | a  |                        |
|                                                 |
|o8 : ChainComplexMap                             |
+-------------------------------------------------+
|i9 : K.dd                                        |
|                                                 |
|          1                   4                  |
|o9 = 0 : S  <--------------- S  : 1              |
|               | a b c d |                       |
|                                                 |
|          4                                 6    |
|     1 : S  <----------------------------- S  : 2|
|               {1} | -b -c 0  -d 0  0  |         |
|               {1} | a  0  -c 0  -d 0  |         |
|               {1} | 0  a  b  0  0  -d |         |
|               {1} | 0  0  0  a  b  c  |         |
|                                                 |
|          6                           4          |
|     2 : S  <----------------------- S  : 3      |
|               {2} | c  d  0  0  |               |
|               {2} | -b 0  d  0  |               |
|               {2} | a  0  0  d  |               |
|               {2} | 0  -b -c 0  |               |
|               {2} | 0  a  0  -c |               |
|               {2} | 0  0  a  b  |               |
|                                                 |
|          4                  1                   |
|     3 : S  <-------------- S  : 4               |
|               {3} | -d |                        |
|               {3} | c  |                        |
|               {3} | -b |                        |
|               {3} | a  |                        |
|                                                 |
|o9 : ChainComplexMap                             |
+-------------------------------------------------+

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * lyubeznikResolution -- create the Lyubeznik
    resolution of an ordered set of monomials.
  * scarfChainComplex -- create the Scarf chain
    complex for a list of monomials.
  * koszul (Macaulay2Doc) -- Koszul complex or specific matrix in
    the Koszul complex

Ways to use taylorResolution :
==============================

  * "taylorResolution(List)"
  * "taylorResolution(MonomialIdeal)"

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

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

vertices(SimplicialComplex) -- get the list of the vertices for an abstract simplicial complex
**********************************************************************************************

Synopsis
========

  * Function: vertices (Polyhedra),
  * Usage:
        vertices Delta
  * Inputs:
      * Delta, an abstract simplicial complex,
  * Outputs:
      * a list (Macaulay2Doc), of variables in a polynomial ring
        corresponding to the vertices of $\Delta$

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

In this package, an abstract simplicial complex is represented by its
Stanley–Reisner ideal in a polynomial ring,
so the vertices are identified with a subset of the variables. This method
returns the list of variables in this polynomial ring that corresponds to the
vertices.

+------------------------------------------------------------+
|i1 : S = QQ[a..e];                                          |
+------------------------------------------------------------+
|i2 : vertices simplexComplex(4, S)                          |
|                                                            |
|o2 = {a, b, c, d, e}                                        |
|                                                            |
|o2 : List                                                   |
+------------------------------------------------------------+
|i3 : Δ = simplicialComplex monomialIdeal(a*b, b*c, c*d, d*e)|
|                                                            |
|o3 = simplicialComplex | be bd ad ace |                     |
|                                                            |
|o3 : SimplicialComplex                                      |
+------------------------------------------------------------+
|i4 : vertices Δ                                             |
|                                                            |
|o4 = {a, b, c, d, e}                                        |
|                                                            |
|o4 : List                                                   |
+------------------------------------------------------------+
|i5 : faces(0, Δ)                                            |
|                                                            |
|o5 = {a, b, c, d, e}                                        |
|                                                            |
|o5 : List                                                   |
+------------------------------------------------------------+
|i6 : assert(vertices Δ === gens S)                          |
+------------------------------------------------------------+

The vertices may correspond to a proper subset of the variables in the ambient
polynomial ring.

+----------------------------------------------------------+
|i7 : vertices simplexComplex(2, S)                        |
|                                                          |
|o7 = {a, b, c}                                            |
|                                                          |
|o7 : List                                                 |
+----------------------------------------------------------+
|i8 : Γ = simplicialComplex monomialIdeal(a, a*b, b*c, c*d)|
|                                                          |
|o8 = simplicialComplex | ce bde |                         |
|                                                          |
|o8 : SimplicialComplex                                    |
+----------------------------------------------------------+
|i9 : vertices Γ                                           |
|                                                          |
|o9 = {b, c, d, e}                                         |
|                                                          |
|o9 : List                                                 |
+----------------------------------------------------------+
|i10 : faces(0, Γ)                                         |
|                                                          |
|o10 = {b, c, d, e}                                        |
|                                                          |
|o10 : List                                                |
+----------------------------------------------------------+
|i11 : assert(vertices Γ === {b, c, d, e})                 |
+----------------------------------------------------------+

There are two "trivial" simplicial complexes having no vertices: the irrelevant
complex has the empty set as a facet whereas the void complex has no facets.

+---------------------------------------------------------+
|i12 : irrelevant = simplicialComplex monomialIdeal gens S|
|                                                         |
|o12 = simplicialComplex | 1 |                            |
|                                                         |
|o12 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i13 : vertices irrelevant                                |
|                                                         |
|o13 = {}                                                 |
|                                                         |
|o13 : List                                               |
+---------------------------------------------------------+
|i14 : assert(vertices irrelevant === {})                 |
+---------------------------------------------------------+
|i15 : void = simplicialComplex monomialIdeal 1_S         |
|                                                         |
|o15 = simplicialComplex 0                                |
|                                                         |
|o15 : SimplicialComplex                                  |
+---------------------------------------------------------+
|i16 : vertices void                                      |
|                                                         |
|o16 = {}                                                 |
|                                                         |
|o16 : List                                               |
+---------------------------------------------------------+
|i17 : assert(vertices void === {})                       |
+---------------------------------------------------------+

See also
========

  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * facets(SimplicialComplex) -- get the
    list of maximal faces
  * faces(SimplicialComplex) -- get the
    list of faces for an abstract simplicial complex

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

  * vertices(SimplicialComplex) -- get
    the list of the vertices for an abstract simplicial complex

wedge(SimplicialComplex,SimplicialComplex,RingElement,RingElement) -- make the wedge sum of two abstract simplicial complexes
*****************************************************************************************************************************

Synopsis
========

  * Function: wedge,
  * Usage:
        wedge (Delta, Gamma, u, v)
  * Inputs:
      * Delta, an abstract simplicial complex,
      * Gamma, an abstract simplicial complex,
      * u, a ring element (Macaulay2Doc), a vertex of
        $\Delta$
      * v, a ring element (Macaulay2Doc), a vertex of
        $\Gamma$
  * Optional inputs (Macaulay2Doc),:
      * Variables => a list (Macaulay2Doc), default value {}, that
        provides variables for the polynomial ring in which the wedge sum is
        represented by its Stanley–Reisner ideal
  * Outputs:
      * an abstract simplicial complex, the wedge sum
        of $\Delta$ and $\Gamma$ obtained by identifying the vertices $u$ and
        $v$

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

For any two abstract simplicial complexes $\Delta$ and $\Gamma$ with
distinguished vertices $u$ and $v$, the wedge sum is the simplicial complex
formed by taking the disjoint union of $\Delta$ and $\Gamma$ and then
identifying $u$ and $v$.

The bowtie complex is the wedge sum of two 2-simplicies

+-------------------------------------------------------------------+
|i1 : S = QQ[a,b,c];                                                |
+-------------------------------------------------------------------+
|i2 : Δ = simplexComplex(2, S)                                      |
|                                                                   |
|o2 = simplicialComplex | abc |                                     |
|                                                                   |
|o2 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i3 : R = QQ[d,e,f];                                                |
+-------------------------------------------------------------------+
|i4 : Γ = simplexComplex(2, R)                                      |
|                                                                   |
|o4 = simplicialComplex | def |                                     |
|                                                                   |
|o4 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i5 : ΔvΓ = wedge (Δ, Γ, a, f)                                      |
|                                                                   |
|o5 = simplicialComplex | ade abc |                                 |
|                                                                   |
|o5 : SimplicialComplex                                             |
+-------------------------------------------------------------------+
|i6 : vertices ΔvΓ                                                  |
|                                                                   |
|o6 = {a, b, c, d, e}                                               |
|                                                                   |
|o6 : List                                                          |
+-------------------------------------------------------------------+
|i7 : assert (# gens ring ΔvΓ === # gens ring Δ + # gens ring Γ - 1)|
+-------------------------------------------------------------------+

When the optional argument $\mathrm{Variables}$ is used, the wedge sum is
represented by its Stanley–Reisner ideal in a new polynomial ring having this
list as variables.  The variables in the ring of $\Delta$ corresponds to the
first few variables in this new polynomial ring and the variables in the ring
of $\Gamma$ correspond to the next few variables in $R$ (omitting the variable
corresponding to $v$).  This option is particularly convenient when taking the
wedge sum of two abstract simplical complexes already defined in the same ring.

+-------------------------------------------------------------+
|i8 : ΔvΓ' = wedge (Δ, Γ, a, d, Variables => toList(x_0..x_4))|
|                                                             |
|o8 = simplicialComplex | x_0x_3x_4 x_0x_1x_2 |               |
|                                                             |
|o8 : SimplicialComplex                                       |
+-------------------------------------------------------------+
|i9 : vertices ΔvΓ'                                           |
|                                                             |
|o9 = {x , x , x , x , x }                                    |
|       0   1   2   3   4                                     |
|                                                             |
|o9 : List                                                    |
+-------------------------------------------------------------+
|i10 : ΔvΓ'' = wedge (Δ, Δ, a, a, Variables => {a,b,c,d,e})   |
|                                                             |
|o10 = simplicialComplex | ade abc |                          |
|                                                             |
|o10 : SimplicialComplex                                      |
+-------------------------------------------------------------+
|i11 : vertices ΔvΓ''                                         |
|                                                             |
|o11 = {a, b, c, d, e}                                        |
|                                                             |
|o11 : List                                                   |
+-------------------------------------------------------------+
|i12 : ring ΔvΓ''                                             |
|                                                             |
|o12 = QQ[a..e]                                               |
|                                                             |
|o12 : PolynomialRing                                         |
+-------------------------------------------------------------+

Caveat
======

When the variables in the ring of $\Delta$ and the ring of $\Gamma$ are not
disjoint, names of vertices in the wedge sum may not be intelligible; the same
name will apparently be used for two distinct variables.

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * vertices(SimplicialComplex) -- get
    the list of the vertices for an abstract simplicial complex
  * SimplicialComplex * SimplicialComplex
    -- make the join for two abstract simplicial complexes
  * substitute(SimplicialComplex,PolynomialRing)
    -- change the ring of a
    simplicial complex
  * elementaryCollapse
    -- construct the
    elementary collapse of a free face in a simplicial complex

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

  * wedge(SimplicialComplex,SimplicialComplex,RingElement,RingElement)
    -- make the wedge sum of two abstract simplicial complexes

Working with associated chain complexes -- information about the chain complexes and their homogenizations
**********************************************************************************************************

Each abstract simplicial complex $\Delta$ determines a chain complex of free
modules over its coefficient ring.
For all integers $i$, the $i$-th term
in this chain complex has a basis corresponding to the $i$-dimensional faces in
the simplicial complex $\Delta$.  The reduced homology of $\Delta$ is, by
definition, the homology of this chain complex.  Similarly, the reduced
cohomology of $\Delta$ is obtained by first using the $\operatorname{Hom}$
functor and then taking homology.

Basic operations arising of
============================

  * chainComplex(SimplicialComplex),
    -- create the chain complex associated to a simplicial complex.
  * boundaryMap(ZZ,SimplicialComplex)
    -- make a boundary map between the
    oriented faces of an abstract simplicial complex
  * HH_ZZ SimplicialComplex, --
    compute the reduced homology of an abstract simplicial complex
  * HH^ZZ SimplicialComplex, --
    compute the reduced cohomology of an abstract simplicial complex

Constructing abstract simplicial complexes from monomial ideals
===============================================================

Monomial ideals produce a few different abstract simplicial complexes, where
the vertices are in bijection with the unique minimal set of monomial
generators.

  * buchbergerSimplicialComplex(MonomialIdeal,Ring)
    -- make the Buchberger complex of a monomial
    ideal
  * lyubeznikSimplicialComplex(MonomialIdeal,Ring)
    -- create a simplicial complex supporting a
    Lyubeznik resolution of a monomial ideal
  * scarfSimplicialComplex(MonomialIdeal,Ring),
    -- create the Scarf simplicial complex for a list of monomials

Free chain complexes arising from abstract simplicial complexes
===============================================================

By labelling or identifying the vertices in an abstract simplicial complex with
distinct monomials (and each face with the least common multiple of its
vertices), one transforms a chain complex of vector spaces into chain complex
of free modules over a polynomial ring.  This approach allows one to understand
the minimal resolutions of some monomial ideals.

  * chainComplex(SimplicialComplex,Labels=>...)
    -- create the chain complex associated
    to a simplicial complex.
  * buchbergerResolution(MonomialIdeal) -- make a
    Buchberger resolution of a monomial ideal
  * lyubeznikResolution(MonomialIdeal) -- create
    the Lyubeznik resolution of an ordered set of monomials.
  * scarfChainComplex(MonomialIdeal) -- create the
    Scarf chain complex for a list of monomials.
  * taylorResolution(MonomialIdeal) -- create the
    Taylor resolution of a monomial ideal

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * Working with simplicial maps, --
    information about simplicial maps and the induced operations

Working with simplicial maps -- information about simplicial maps and the induced operations
********************************************************************************************

Let $C$ and $D$ be simplicial complexes. A simplicial map is a map $f : C \to
D$ such that for any face $F \subset C$, we have that $f(F)$ is contained in a
face of $D$.

Although the primary method for creating a simplicial map is
map(SimplicialComplex,SimplicialComplex,Matrix),
there are a few other
constructors.

Making simplicial maps
======================

  * map(SimplicialComplex,SimplicialComplex,Matrix)
    -- create a
    simplicial map between simplicial complexes
  * id _ SimplicialComplex -- make the
    identity map from a SimplicialComplex to itself
  * SimplicialMap -- the class of all maps between
    simplicial complexes
  * isWellDefined(SimplicialMap), --
    whether underlying data is uncontradictory

Having made a simplicial map, one can access its basic
invariants or test for some elementary properties by using the following
methods. Having made a map of abstract simplicial complexes,
one can access its basic invariants or test for some elementary
properties by using the following methods.

Determining attributes and properties of simplicial maps
========================================================

  * source(SimplicialMap) -- get the source
    of the map
  * target(SimplicialMap) -- get the target
    of the map
  * matrix(SimplicialMap) -- get the
    underlying map of rings

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * Finding attributes and properties,
    -- information about accessing features of an abstract simplicial complex
  * Working with associated chain complexes
    -- information about the chain complexes and their
    homogenizations

zieglerBallComplex(PolynomialRing) -- make a nonshellable 3-ball with 10 vertices and 21 facets
***********************************************************************************************

Synopsis
========

  * Function: zieglerBallComplex,
  * Usage:
        zieglerBallComplex S
  * Inputs:
      * S, a polynomial ring (Macaulay2Doc), that has at
        least 10 generators
  * Outputs:
      * an abstract simplicial complex,

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

As appears on page 167 of Günter M. Ziegler's "Shelling polyhedral 3-balls and
4-polytopes", Discrete & Computational Geometry 19 (1998) 159–174, this method
returns a non-shellable  (see https://en.wikipedia.org/wiki/Shelling_(topology)
) 3-ball with 10 vertices and 21 facets.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/101[a..n];                                                       |
+-----------------------------------------------------------------------------+
|i2 : Δ = zieglerBallComplex S;                                               |
+-----------------------------------------------------------------------------+
|i3 : matrix {facets Δ}                                                       |
|                                                                             |
|o3 = | bfgj bcgj befj abej abcj aehi adhi aefi abfi abdi cfgh degh cdgh bcfh |
|     ------------------------------------------------------------------------|
|     adeh bcdh bcfg adeg acdg abef abcd |                                    |
|                                                                             |
|             1       21                                                      |
|o3 : Matrix S  <--- S                                                        |
+-----------------------------------------------------------------------------+
|i4 : dim Δ                                                                   |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : fVector Δ                                                               |
|                                                                             |
|o5 = {1, 10, 38, 50, 21}                                                     |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : assert(dim Δ === 3 and isPure Δ)                                        |
+-----------------------------------------------------------------------------+
|i7 : assert(fVector Δ === {1,10,38,50,21})                                   |
+-----------------------------------------------------------------------------+

This abstract simplicial complex is Cohen-Macaulay but not shellable.

Our enumeration of the vertices follows the ziegler (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/ziegler_eng.html )
example in Masahiro Hachimori's simplicial complex library (see
http://infoshako.sk.tsukuba.ac.jp/~hachi/math/library/index_eng.html ).

See also
========

  * Making an abstract simplicial complex
    -- information about the basic constructors
  * rudinBallComplex -- make a
    nonshellable 3-ball with 14 vertices and 41 facets
  * grunbaumBallComplex -- make
    a nonshellable 3-ball with 14 vertices and 29 facets
  * isPure(SimplicialComplex) -- whether
    the facets are equidimensional

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

  * zieglerBallComplex(PolynomialRing)
    -- make a nonshellable 3-ball with
    10 vertices and 21 facets